status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-27 06:34:53 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/appendices/VK_KHR_surface.txt
Jon Leech 82e0f83d43 Change log for February 10, 2017 Vulkan 1.0.40 spec update: 
* Bump API patch number and header version number to 40 for this update.
  * There is a major build change in this release. We are now using the
    Ruby-based ``asciidoctor'' implementation, rather than the Python-based
    ``asciidoc'' implementation, to process the specification. While the
    actual specification markup changes were minimal, this requires a new
    set of build tools and a very different installation process, especially
    because we now use an experimental direct-to-PDF backend for Asciidoctor
    instead of Docbook->dblatex->PDF. It is no longer possible to build the
    Specification using asciidoc. See doc/specs/vulkan/README.adoc
    for some guidance on installing the new toolchain components.
  * There are some minor rendering issues in the PDF output due to teething
    problems with the asciidoctor toolchain, especially with mathematical
    equations. We are aware of these and working on them.

Github Issues:

  * Updated sample code for the <<sparsememory-examples-basic,sparse
    resource binding example>> (public issue 97).
  * Modify line and point clipping behavior in the
    <<vertexpostproc-clipping, Primitive Clipping>> section to allow for
    pop-free behavior. The ability to check for which behavior is
    implemented may be added a future feature or extension (public issue
    113).
  * Unify the discussions of implicit ordering throughout the spec, in
    particular in the new sections <<drawing-primitive-order, Primitive
    Order>>, <<primrast-order, Rasterization Order>>, and
    <<synchronization-implicit, Implicit Synchronization Guarantees>>; the
    discussion of <<synchronization-submission-order, submission order>>;
    and references elsewhere to these sections (public issue 133).
  * Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
    language and introduce the term ``identically defined'' (public issue
    164).
  * Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
    reuse the object type enum from +VK_EXT_debug_report+, and moves the
    definition of that enum into +VK_EXT_debug_report+ where it should be
    (public issue 409).
  * Remove redundant valid usage statement from slink:VkImageBlit (public
    issue 421).
  * Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
    specialization constant (public issue 424).
  * Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
    426).
  * Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
    issue 447).

Internal Issues:

  * Moved to asciidoctor for spec builds (internal issue 121).
  * Update style guide to describe where to put new extensions-specific
    asciidoc files, and what to name them (internal issue 626).
  * Add src/spec/indexExt.py to autogenerate registry index entries linking
    into the 1.0-extensions specification, instead of maintaining the index
    manually. (internal issue 642).
  * Autogenerate extension dependencies and lists of all extensions and all
    KHR extensions from the "supported" attributes in +vk.xml+. Execute
    +make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
    extension is added to vk.xml, to regenerate the dependency script. The
    consequence is that specifying a single extension to the +makeExt+
    script will automatically enable all extensions it depends on as well,
    and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
    updated when a new extension is supported (internal issue 648).
  * Put extension appendices all at the same asciidoc section level, so KHR
    WSI extensions show up in the HTML index (internal issue 648).

Other Issues:

  * Imbed images in the generated HTML specs instead of loading them from
    the images/ directory.
  * Fix missing EXT in extension name
    (ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
  * Add new +VK_EXT_SMPTE_2086_metadata+ extension.
  * In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
    +VK_KHR_xlib_surface+ specification, add language warning users that
    they always need to call code:XinitThreads.
  * Use the term "presentable image" (rather than "swapchain image")
    consistently in +VK_KHR_swapchain+ and related extensions, and add a
    glossary term defining it.
  * Relocate the valid usage for samples of
    flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
    to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
    structure.
2017-02-10 20:37:39 -08:00

262 lines
9.2 KiB
Plaintext
Raw Blame History

// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[VK_KHR_surface]]
== VK_KHR_surface
*Name String*::
+VK_KHR_surface+
*Extension Type*::
Instance extension
*Registered Extension Number*::
1
*Last Modified Date*::
2016-08-25
*Revision*::
25
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Patrick Doane, Blizzard
- Ian Elliott, LunarG
- Jesse Hall, Google
- James Jones, NVIDIA
- David Mao, AMD
- Norbert Nopper, Freescale
- Alon Or-bach, Samsung
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Jeff Vigil, Qualcomm
- Chia-I Wu, LunarG
- Jason Ekstrand, Intel
*Contacts*::
- James Jones, NVIDIA
- Ian Elliott, LunarG
The +VK_KHR_surface+ extension is an instance extension.
It introduces slink:VkSurfaceKHR objects, which abstract native platform
surface or window objects for use with Vulkan.
It also provides a way to determine whether a queue family in a physical
device supports presenting to particular surface.
Separate extensions for each each platform provide the mechanisms for
creating slink:VkSurfaceKHR objects, but once created they may be used in
this and other platform-independent extensions, in particular the
+VK_KHR_swapchain+ extension.
=== New Object Types
* slink:VkSurfaceKHR
=== New Enum Constants
* Extending ename:VkResult:
** ename:VK_ERROR_SURFACE_LOST_KHR
** ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
=== New Enums
* ename:VkSurfaceTransformFlagBitsKHR
* ename:VkPresentModeKHR
* ename:VkColorSpaceKHR
* ename:VkCompositeAlphaFlagBitsKHR
=== New Structures
* slink:VkSurfaceCapabilitiesKHR
* slink:VkSurfaceFormatKHR
=== New Functions
* flink:vkDestroySurfaceKHR
* flink:vkGetPhysicalDeviceSurfaceSupportKHR
* flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
* flink:vkGetPhysicalDeviceSurfaceFormatsKHR
* flink:vkGetPhysicalDeviceSurfacePresentModesKHR
=== Examples
[NOTE]
.Note
====
The example code for the +VK_KHR_surface+ and +VK_KHR_swapchain+ extensions
was removed from the appendix after revision 1.0.29.
This WSI example code was ported to the cube demo that is shipped with the
official Khronos SDK, and is being kept up-to-date in that location (see:
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c).
====
=== Issues
1) Should this extension include a method to query whether a physical device
supports presenting to a specific window or native surface on a given
platform?
*RESOLVED*: Yes.
Without this, applications would need to create a device instance to
determine whether a particular window can be presented to.
Knowing that a device supports presentation to a platform in general is not
sufficient, as a single machine might support multiple seats, or instances
of the platform that each use different underlying physical devices.
Additionally, on some platforms, such as the X Window System, different
drivers and devices might be used for different windows depending on which
section of the desktop they exist on.
2) Should the flink:vkGetSurfacePropertiesKHR, flink:vkGetSurfaceFormatsKHR,
and flink:vkGetSurfacePresentModesKHR functions from +VK_KHR_swapchain+ be
modified to operate on physical devices and moved to this extension to
implement the resolution of issue 1?
*RESOLVED*: No, separate query functions are needed, as the purposes served
are similar but incompatible.
The flink:vkGetSurface*KHR functions return information that could
potentially depend on an initialized device.
For example, the formats supported for presentation to the surface might
vary depending on which device extensions are enabled.
The query introduced to resolve issue 1 should be used only to query generic
driver or platform properties.
The physical device parameter is intended to serve only as an identifier
rather than a stateful object.
3) Should Vulkan include support Xlib or XCB as the API for accessing the X
Window System platform?
*RESOLVED*: Both.
XCB is a more modern and efficient API, but Xlib usage is deeply ingrained
in many applications and likely will remain in use for the foreseeable
future.
Not all drivers necessarily need to support both, but including both as
options in the core specification will probably encourage support, which
should in turn eases adoption of the Vulkan API in older codebases.
Additionally, the performance improvements possible with XCB likely will not
have a measurable impact on the performance of Vulkan presentation and other
minimal window system interactions defined here.
4) Should the GBM platform be included in the list of platform enums?
*RESOLVED*: Deferred, and will be addressed with a platform-specific
extension to be written in the future.
=== Version History
* Revision 1, 2015-05-20 (James Jones)
- Initial draft, based on LunarG KHR spec, other KHR specs, patches
attached to bugs.
* Revision 2, 2015-05-22 (Ian Elliott)
- Created initial Description section.
- Removed query for whether a platform requires the use of a queue for
presentation, since it was decided that presentation will always be
modeled as being part of the queue.
- Fixed typos and other minor mistakes.
* Revision 3, 2015-05-26 (Ian Elliott)
- Improved the Description section.
* Revision 4, 2015-05-27 (James Jones)
- Fixed compilation errors in example code.
* Revision 5, 2015-06-01 (James Jones)
- Added issues 1 and 2 and made related spec updates.
* Revision 6, 2015-06-01 (James Jones)
- Merged the platform type mappings table previously removed from
VK_KHR_swapchain with the platform description table in this spec.
- Added issues 3 and 4 documenting choices made when building the initial
list of native platforms supported.
* Revision 7, 2015-06-11 (Ian Elliott)
- Updated table 1 per input from the KHR TSG.
- Updated issue 4 (GBM) per discussion with Daniel Stone.
He will create a platform-specific extension sometime in the future.
* Revision 8, 2015-06-17 (James Jones)
- Updated enum-extending values using new convention.
- Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.
* Revision 9, 2015-06-17 (James Jones)
- Rebased on Vulkan API version 126.
* Revision 10, 2015-06-18 (James Jones)
- Marked issues 2 and 3 resolved.
* Revision 11, 2015-06-23 (Ian Elliott)
- Examples now show use of function pointers for extension functions.
- Eliminated extraneous whitespace.
* Revision 12, 2015-07-07 (Daniel Rakos)
- Added error section describing when each error is expected to be
reported.
- Replaced the term "queue node index" with "queue family index" in the
spec as that is the agreed term to be used in the latest version of the
core header and spec.
- Replaced bool32_t with VkBool32.
* Revision 13, 2015-08-06 (Daniel Rakos)
- Updated spec against latest core API header version.
* Revision 14, 2015-08-20 (Ian Elliott)
- Renamed this extension and all of its enumerations, types, functions,
etc.
This makes it compliant with the proposed standard for Vulkan
extensions.
- Switched from "revision" to "version", including use of the
VK_MAKE_VERSION macro in the header file.
- Did miscellaneous cleanup, etc.
* Revision 15, 2015-08-20 (Ian Elliott--porting a 2015-07-29 change from
James Jones)
- Moved the surface transform enums here from VK_WSI_swapchain so they
could be re-used by VK_WSI_display.
* Revision 16, 2015-09-01 (James Jones)
- Restore single-field revision number.
* Revision 17, 2015-09-01 (James Jones)
- Fix example code compilation errors.
* Revision 18, 2015-09-26 (Jesse Hall)
- Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is
created via layered extensions.
Added VkDestroySurfaceKHR.
* Revision 19, 2015-09-28 (Jesse Hall)
- Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.
* Revision 20, 2015-09-30 (Jeff Vigil)
- Add error result VK_ERROR_SURFACE_LOST_KHR.
* Revision 21, 2015-10-15 (Daniel Rakos)
- Updated the resolution of issue #2 and include the surface capability
queries in this extension.
- Renamed SurfaceProperties to SurfaceCapabilities as it better reflects
that the values returned are the capabilities of the surface on a
particular device.
- Other minor cleanup and consistency changes.
* Revision 22, 2015-10-26 (Ian Elliott)
- Renamed from VK_EXT_KHR_surface to VK_KHR_surface.
* Revision 23, 2015-11-03 (Daniel Rakos)
- Added allocation callbacks to vkDestroySurfaceKHR.
* Revision 24, 2015-11-10 (Jesse Hall)
- Removed VkSurfaceTransformKHR.
Use VkSurfaceTransformFlagBitsKHR instead.
- Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to
maxImageArrayLayers.
* Revision 25, 2016-01-14 (James Jones)
- Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface
to the VK_KHR_surface extension.
* 2016-08-23 (Ian Elliott)
- Update the example code, to not have so many characters per line, and
to split out a new example to show how to obtain function pointers.
* 2016-08-25 (Ian Elliott)
- A note was added at the beginning of the example code, stating that it
will be removed from future versions of the appendix.
Reference in New Issue View Git Blame Copy Permalink