Change log for October 7, 2018 Vulkan 1.1.87 spec update:

* Update release number to 87.

Public Issues:

  * Merge flink:vkCmdPipelineBarrier self-dependency barrier VUs referring
    to the same subpass dependency (public pull request 756).
  * Describe default value of `"optional"` attribute in the registry schema
    document (public issue 769)
  * Fix links in <<VK_NVX_raytracing>> extension (public pull request 805).
  * Mark the <<VK_KHR_mir_surface>> extension obsolete (see public issue 814
    - does not close this, however).
  * Fix missing endif in Image Creation block (public issue 817).

Internal Issues:

  * Clarify that the compressed texture formats corresponding to
    <<features-features-textureCompressionETC2>>,
    <<features-features-textureCompressionASTC_LDR>>, and
    <<features-features-textureCompressionBC>> is not contingent on the
    feature bits, and may be supported even if the features are not enabled
    (internal issue 663).
  * Clarify that code:FragStencilRefEXT is output only in the
    <<interfaces-builtin-variables, Built-In Variables>> section (internal
    issue 1173).
  * Identify and correct many overly-aggressive uses of "`undefined`", and
    narrow them down, where straightforward to do so. Mark such resolved
    uses of "`undefined`" with the custom undefined: macro. Add a new
    <<writing-undefined, Describing Undefined Behavior>> section (internal
    issue 1267).
  * Don't require code:inline_uniform_block descriptors to be populated
    before use in the flink:vkAllocateDescriptorSets section (internal issue
    1380).
  * Allow suppressing inline SVG images by controlling this with an
    attribute set in the Makefile, rather than the explicit [%inline]
    directive (internal issue 1391).
  * Mark 'Khronos' as a registered trademark in several places, now that it
    is one.
  * Fix typo in the <<VK_KHR_shader_atomic_int64>> appendix using the GLSL
    naming of the compare exchange op when referring to the SPIR-V op.
  * Specify in the flink:vkGetPhysicalDeviceQueueFamilyProperties section
    that all implementations must support at least one queue family, and
    that every queue family must contain at least one queue.
  * Make slink:VkPipelineDynamicStateCreateInfo::pname:dynamicStateCount,
    slink:VkSampleLocationsInfoEXT::pname:sampleLocationsPerPixel, and
    slink:VkSampleLocationsInfoEXT::pname:sampleLocationsCount optional, to
    fix bogus implicit valid usage checks that were causing failures in the
    conformance tests.
  * Fix vendor tag in reserved extension 237 constants. Does not affect
    anything since it's just a placeholder, but this should avoid further
    comments.
  * Minor markup fixes in some extension appendices.

New Extensions:

  * `<<VK_FUCHSIA_imagepipe_surface>>`
This commit is contained in:
Jon Leech 2018-10-07 06:10:21 -07:00
parent c75ae4fb18
commit 911a764694
67 changed files with 959 additions and 610 deletions

View File

@ -8,6 +8,66 @@ public pull requests that have been accepted.
-----------------------------------------------------
Change log for October 7, 2018 Vulkan 1.1.87 spec update:
* Update release number to 87.
Public Issues:
* Merge flink:vkCmdPipelineBarrier self-dependency barrier VUs referring
to the same subpass dependency (public pull request 756).
* Describe default value of `"optional"` attribute in the registry schema
document (public issue 769)
* Fix links in <<VK_NVX_raytracing>> extension (public pull request 805).
* Mark the <<VK_KHR_mir_surface>> extension obsolete (see public issue 814
- does not close this, however).
* Fix missing endif in Image Creation block (public issue 817).
Internal Issues:
* Clarify that the compressed texture formats corresponding to
<<features-features-textureCompressionETC2>>,
<<features-features-textureCompressionASTC_LDR>>, and
<<features-features-textureCompressionBC>> is not contingent on the
feature bits, and may be supported even if the features are not enabled
(internal issue 663).
* Clarify that code:FragStencilRefEXT is output only in the
<<interfaces-builtin-variables, Built-In Variables>> section (internal
issue 1173).
* Identify and correct many overly-aggressive uses of "`undefined`", and
narrow them down, where straightforward to do so. Mark such resolved
uses of "`undefined`" with the custom undefined: macro. Add a new
<<writing-undefined, Describing Undefined Behavior>> section (internal
issue 1267).
* Don't require code:inline_uniform_block descriptors to be populated
before use in the flink:vkAllocateDescriptorSets section (internal issue
1380).
* Allow suppressing inline SVG images by controlling this with an
attribute set in the Makefile, rather than the explicit [%inline]
directive (internal issue 1391).
* Mark 'Khronos' as a registered trademark in several places, now that it
is one.
* Fix typo in the <<VK_KHR_shader_atomic_int64>> appendix using the GLSL
naming of the compare exchange op when referring to the SPIR-V op.
* Specify in the flink:vkGetPhysicalDeviceQueueFamilyProperties section
that all implementations must support at least one queue family, and
that every queue family must contain at least one queue.
* Make slink:VkPipelineDynamicStateCreateInfo::pname:dynamicStateCount,
slink:VkSampleLocationsInfoEXT::pname:sampleLocationsPerPixel, and
slink:VkSampleLocationsInfoEXT::pname:sampleLocationsCount optional, to
fix bogus implicit valid usage checks that were causing failures in the
conformance tests.
* Fix vendor tag in reserved extension 237 constants. Does not affect
anything since it's just a placeholder, but this should avoid further
comments.
* Minor markup fixes in some extension appendices.
New Extensions:
* `<<VK_FUCHSIA_imagepipe_surface>>`
-----------------------------------------------------
Change log for September 29, 2018 Vulkan 1.1.86 spec update:
* Update release number to 86.
@ -2536,7 +2596,7 @@ Internal Issues:
Other Issues:
* Vulkan(R) is now a registered trademark symbol, and this is reflected in
* Vulkan is now a registered trademark symbol, and this is reflected in
documents and copyright statements.
-----------------------------------------------------

View File

@ -46,6 +46,11 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
# normally used when building with extensions included.
APITITLE =
# IMAGEOPTS is normally set to generate inline SVG images, but can be
# overridden to an empty string, since the inline option doesn't work
# well with our HTML diffs.
IMAGEOPTS = inline
# The default 'all' target builds the following sub-targets:
# html - HTML single-page API specification
# pdf - PDF single-page API specification
@ -107,7 +112,7 @@ VERBOSE =
# EXTRAATTRIBS sets additional attributes, if passed to make
# ADOCOPTS options for asciidoc->HTML5 output
NOTEOPTS = -a editing-notes -a implementation-guide
PATCHVERSION = 86
PATCHVERSION = 87
ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS)))
SPECREVISION = 1.1.$(PATCHVERSION)
else
@ -132,6 +137,7 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \
-a revremark="$(SPECREMARK)" \
-a apititle="$(APITITLE)" \
-a stem=latexmath \
-a imageopts="$(IMAGEOPTS)" \
$(VERSIONATTRIBS) \
$(EXTATTRIBS) \
$(EXTRAATTRIBS)

View File

@ -325,7 +325,7 @@ submitted.
1) Should we just name this extension `VK_EXT_debug_report2`
**RESOLVED**: No.
*RESOLVED*: No.
There is enough additional changes to the structures to break backwards
compatibility.
So, a new name was decided that would not indicate any interaction with the
@ -333,7 +333,7 @@ previous extension.
2) Will validation layers immediately support all the new features.
**RESOLVED**: Not immediately.
*RESOLVED*: Not immediately.
As one can imagine, there is a lot of work involved with converting the
validation layer logging over to the new functionality.
Basic logging, as seen in the origin
@ -347,7 +347,7 @@ exposed.
3) If the validation layers won't expose the new functionality immediately,
then what's the point of this extension?
**RESOLVED**: We needed a replacement for
*RESOLVED*: We needed a replacement for
<<VK_EXT_debug_report,VK_EXT_debug_report>> because the
elink:VkDebugReportObjectTypeEXT enumeration will no longer be updated and
any new objects will need to be debugged using the new functionality
@ -358,8 +358,7 @@ is an instance extension providing the callback functionality, and another
device extension providing the general debug marker and annotation
functionality)?
**RESOLVED**: No, the functionality for this extension is too closely
related.
*RESOLVED*: No, the functionality for this extension is too closely related.
If we did split up the extension, where would the structures and enums live,
and how would you define that the device behavior in the instance extension
is really only valid if the device extension is enabled, and the

View File

@ -16,26 +16,32 @@ Finally it removes the restriction on the pname:depth value in
slink:VkClearDepthStencilValue.
=== New Object Types
None.
=== New Enum Constants
None.
=== New Enums
None.
=== New Structures
None.
=== New Functions
None.
=== Issues
1) How do slink:VkViewport pname:minDepth and pname:maxDepth values outside
of the `0.0` to `1.0` range interact with
<<vertexpostproc-clipping,Primitive Clipping>>?
**RESOLVED**: The behavior described in <<vertexpostproc-clipping,Primitive
*RESOLVED*: The behavior described in <<vertexpostproc-clipping,Primitive
Clipping>> still applies.
If depth clamping is disabled the depth values are still clipped to [eq]#0
{leq} z~c~ {leq} w~c~# before the viewport transform.
@ -47,9 +53,10 @@ the `0.0` to `1.0` range.
2) What happens if a resulting depth fragment is outside of the `0.0` to
`1.0` range and the depth buffer is fixed-point rather than floating-point?
**RESOLVED**: The supported range of a fixed-point depth buffer is `0.0` to
*RESOLVED*: The supported range of a fixed-point depth buffer is `0.0` to
`1.0` and depth fragments are clamped to this range.
=== Version History
* Revision 1, 2017-06-22 (Piers Daniell)
- Internal revisions

View File

@ -65,7 +65,7 @@ However, usual synchronization requirements apply.
RESOLVED: No, it violates valid usage conditions.
Using the memory object imported from a host allocation that's already freed
thus results in undefined behavior.
thus results in undefined: behavior.
4) Is flink:vkMapMemory expected to return the same host address which was
specified when importing it to the memory object?
@ -89,7 +89,7 @@ physical device?
RESOLVED: No, at least not guaranteed by this extension.
Some platforms do not allow locking the same physical pages for device
access multiple times, so attempting to do it may result in undefined
access multiple times, so attempting to do it may result in undefined:
behavior.
7) Does this extension support exporting the new handle type?

View File

@ -21,115 +21,115 @@ include::meta/VK_EXT_image_drm_format_modifier.txt[]
==== Summary
This extension provides the ability to use _DRM format modifiers_ with images,
enabling Vulkan to better integrate with the Linux ecosystem of graphics,
video, and display APIs.
This extension provides the ability to use _DRM format modifiers_ with
images, enabling Vulkan to better integrate with the Linux ecosystem of
graphics, video, and display APIs.
Its functionality closely overlaps with
`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^
and
`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^.
Unlike the EGL extensions, this extension does not require the use of
a specific handle type (such as a dma_buf) for external memory
and provides more explicit control of image creation.
Unlike the EGL extensions, this extension does not require the use of a
specific handle type (such as a dma_buf) for external memory and provides
more explicit control of image creation.
==== Introduction to DRM Format Modifiers
A _DRM format modifier_ is a 64-bit, vendor-prefixed, semi-opaque unsigned integer.
Most _modifiers_ represent a concrete, vendor-specific tiling format for images.
Some exceptions are etext:DRM_FORMAT_MOD_LINEAR (which is not vendor-specific);
etext:DRM_FORMAT_MOD_NONE (which is an alias of etext:DRM_FORMAT_MOD_LINEAR due
to historical accident);
and etext:DRM_FORMAT_MOD_INVALID (which does not represent a tiling format).
A _DRM format modifier_ is a 64-bit, vendor-prefixed, semi-opaque unsigned
integer.
Most _modifiers_ represent a concrete, vendor-specific tiling format for
images.
Some exceptions are etext:DRM_FORMAT_MOD_LINEAR (which is not
vendor-specific); etext:DRM_FORMAT_MOD_NONE (which is an alias of
etext:DRM_FORMAT_MOD_LINEAR due to historical accident); and
etext:DRM_FORMAT_MOD_INVALID (which does not represent a tiling format).
The _modifier's_ vendor prefix consists of the 8 most signficant bits.
The canonical list of _modifiers_ and vendor prefixes is found in
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`drm_fourcc.h`]
in the Linux kernel source.
The other dominant source of _modifiers_ are vendor kernel trees.
One goal of _modifiers_ in the Linux ecosystem
is to enumerate for each vendor a reasonably sized set of tiling formats that
are appropriate for images shared
across processes, APIs, and/or devices,
where each participating component may possibly be from different vendors.
A non-goal is to enumerate all tiling formats supported
by all vendors. Some tiling formats used internally by vendors are
inappropriate for sharing; no _modifiers_ should be assigned to such tiling
formats.
One goal of _modifiers_ in the Linux ecosystem is to enumerate for each
vendor a reasonably sized set of tiling formats that are appropriate for
images shared across processes, APIs, and/or devices, where each
participating component may possibly be from different vendors.
A non-goal is to enumerate all tiling formats supported by all vendors.
Some tiling formats used internally by vendors are inappropriate for
sharing; no _modifiers_ should be assigned to such tiling formats.
Modifier values typically do not _describe_ memory layouts.
More precisely, a _modifier_'s lower 56 bits usually have no structure.
Instead, modifiers _name_ memory layouts;
they name a small set of vendor-preferred layouts for image sharing.
Instead, modifiers _name_ memory layouts; they name a small set of
vendor-preferred layouts for image sharing.
As a consequence, in each vendor namespace the modifier values are often
sequentially allocated starting at 1.
Each _modifier_ is usually supported by a single vendor
and its name matches the pattern `{VENDOR}_FORMAT_MOD_*`
or `DRM_FORMAT_MOD_{VENDOR}_*`.
Examples are
etext:I915_FORMAT_MOD_X_TILED and
Each _modifier_ is usually supported by a single vendor and its name matches
the pattern `{VENDOR}_FORMAT_MOD_*` or `DRM_FORMAT_MOD_{VENDOR}_*`.
Examples are etext:I915_FORMAT_MOD_X_TILED and
etext:DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED.
An exception is etext:DRM_FORMAT_MOD_LINEAR,
which is supported by most vendors.
An exception is etext:DRM_FORMAT_MOD_LINEAR, which is supported by most
vendors.
Many APIs in Linux use _modifiers_ to negotiate and specify the
memory layout of shared images. For example, a Wayland compositor and Wayland
client may, by relaying _modifiers_ over the Wayland protocol
`zwp_linux_dmabuf_v1`, negotiate a vendor-specific tiling format for a shared
stext:wl_buffer. The client may allocate the underlying memory for the
stext:wl_buffer with GBM, providing the chosen _modifier_ to
fname:gbm_bo_create_with_modifiers. The client may then import the stext:wl_buffer
into Vulkan for producing image content, providing the resource's
dma_buf to slink:VkImportMemoryFdInfo and
its _modifier_ to slink:VkImageDrmFormatModifierExplicitCreateInfoEXT.
Many APIs in Linux use _modifiers_ to negotiate and specify the memory
layout of shared images.
For example, a Wayland compositor and Wayland client may, by relaying
_modifiers_ over the Wayland protocol `zwp_linux_dmabuf_v1`, negotiate a
vendor-specific tiling format for a shared stext:wl_buffer.
The client may allocate the underlying memory for the stext:wl_buffer with
GBM, providing the chosen _modifier_ to fname:gbm_bo_create_with_modifiers.
The client may then import the stext:wl_buffer into Vulkan for producing
image content, providing the resource's dma_buf to
slink:VkImportMemoryFdInfo and its _modifier_ to
slink:VkImageDrmFormatModifierExplicitCreateInfoEXT.
The compositor may then import the stext:wl_buffer into OpenGL for sampling,
providing the resource's dma_buf and _modifier_ to
fname:eglCreateImage.
The compositor may also bypass OpenGL and submit the stext:wl_buffer directly
to the kernel's display API, providing the dma_buf and _modifier_ through
stext:drm_mode_fb_cmd2.
providing the resource's dma_buf and _modifier_ to fname:eglCreateImage.
The compositor may also bypass OpenGL and submit the stext:wl_buffer
directly to the kernel's display API, providing the dma_buf and _modifier_
through stext:drm_mode_fb_cmd2.
==== Format Translation
_Modifier_-capable APIs often pair _modifiers_ with DRM formats,
which are defined in
_Modifier_-capable APIs often pair _modifiers_ with DRM formats, which are
defined in
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`drm_fourcc.h`].
However, `VK_EXT_image_drm_format_modifier` uses elink:VkFormat instead of DRM formats.
The application must convert between elink:VkFormat and DRM format
when it sends or receives a DRM format to or from an external API.
However, `VK_EXT_image_drm_format_modifier` uses elink:VkFormat instead of
DRM formats.
The application must convert between elink:VkFormat and DRM format when it
sends or receives a DRM format to or from an external API.
The mapping from elink:VkFormat to DRM format is lossy.
Therefore, when receiving a DRM format from an external API,
often the application must use information from the external API
to accurately map the DRM format to a elink:VkFormat.
For example, DRM formats do not distinguish between RGB and sRGB
(as of 2018-03-28);
external information is required to identify the image's colorspace.
Therefore, when receiving a DRM format from an external API, often the
application must use information from the external API to accurately map the
DRM format to a elink:VkFormat.
For example, DRM formats do not distinguish between RGB and sRGB (as of
2018-03-28); external information is required to identify the image's
colorspace.
The mapping between elink:VkFormat and DRM format is also incomplete.
For some DRM formats there exist no corresponding Vulkan format,
and for some Vulkan formats there exist no corresponding DRM format.
For some DRM formats there exist no corresponding Vulkan format, and for
some Vulkan formats there exist no corresponding DRM format.
==== Usage Patterns
Three primary usage patterns are intended for this extension:
* *Negotiation.*
The application negotiates with _modifier_-aware, external components to
determine sets of image creation parameters supported among all components.
* *Negotiation.* The application negotiates with _modifier_-aware,
external components to determine sets of image creation parameters
supported among all components.
+
--
In the Linux ecosystem, the negotiation usually assumes the image is a 2D,
single-sampled, non-mipmapped, non-array image; this extension permits that
assumption but does not require it. The result of the negotiation usually
resembles a set of tuples such as _(drmFormat, drmFormatModifier)_,
where each participating component supports all tuples in the set.
assumption but does not require it.
The result of the negotiation usually resembles a set of tuples such as
_(drmFormat, drmFormatModifier)_, where each participating component
supports all tuples in the set.
Many details of this negotiation—such as the protocol used during negotiation,
the set of image creation parameters expressable in the protocol, and how the
protocol chooses which process and which API will create the image—are outside
the scope of this specification.
Many details of this negotiation—such as the protocol used during
negotiation, the set of image creation parameters expressable in the
protocol, and how the protocol chooses which process and which API will
create the image—are outside the scope of this specification.
In this extension, flink:vkGetPhysicalDeviceFormatProperties2 with
slink:VkDrmFormatModifierPropertiesListEXT serves a primary role during the
@ -137,87 +137,91 @@ negotiation, and flink:vkGetPhysicalDeviceImageFormatProperties2 with
slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role.
--
* *Import.*
The application imports an image with a _modifier_.
* *Import.* The application imports an image with a _modifier_.
+
--
In this pattern, the application receives from an external source the
image's memory and its creation parameters, which are often the result of
the negotiation described above. Some image creation parameters are
implicitly defined by the external source; for example,
ename:VK_IMAGE_TYPE_2D is often assumed. Some image creation parameters are
usually explicit, such as the image's pname:format,
pname:drmFormatModifier, and pname:extent; and each plane's pname:offset
and pname:rowPitch.
the negotiation described above.
Some image creation parameters are implicitly defined by the external
source; for example, ename:VK_IMAGE_TYPE_2D is often assumed.
Some image creation parameters are usually explicit, such as the image's
pname:format, pname:drmFormatModifier, and pname:extent; and each plane's
pname:offset and pname:rowPitch.
Before creating the image, the application first verifies that the physical device
supports the received creation parameters by querying
Before creating the image, the application first verifies that the physical
device supports the received creation parameters by querying
flink:vkGetPhysicalDeviceFormatProperties2 with
slink:VkDrmFormatModifierPropertiesListEXT and
flink:vkGetPhysicalDeviceImageFormatProperties2 with
slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates
the image by chaining slink:VkImageDrmFormatModifierExplicitCreateInfoEXT
and slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo.
slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT.
Then the application creates the image by chaining
slink:VkImageDrmFormatModifierExplicitCreateInfoEXT and
slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo.
--
* *Export.* The application creates an image and allocates its memory.
Then the application exports to _modifier_-aware consumers the image's
memory handles; its creation parameters; its _modifier_; and the
<<VkSubresourceLayout,pname:offset>>, <<VkSubresourceLayout,pname:size>>,
and <<VkSubresourceLayout,pname:rowPitch>> of each _memory plane_.
<<VkSubresourceLayout,pname:offset>>,
<<VkSubresourceLayout,pname:size>>, and
<<VkSubresourceLayout,pname:rowPitch>> of each _memory plane_.
+
--
In this pattern, the Vulkan device is the authority for the image; it is
the allocator of the image's memory and the decider of the image's creation
parameters. When choosing the image's creation parameters, the application
usually chooses a tuple _(format, drmFormatModifier)_
from the result of the negotiation described above.
The negotiation's result often contains multiple tuples
that share the same format but differ in their _modifier_. In this case, the
application should defer the choice of the image's _modifier_ to the Vulkan
implementation by providing all such _modifiers_ to
In this pattern, the Vulkan device is the authority for the image; it is the
allocator of the image's memory and the decider of the image's creation
parameters.
When choosing the image's creation parameters, the application usually
chooses a tuple _(format, drmFormatModifier)_ from the result of the
negotiation described above.
The negotiation's result often contains multiple tuples that share the same
format but differ in their _modifier_.
In this case, the application should defer the choice of the image's
_modifier_ to the Vulkan implementation by providing all such _modifiers_ to
slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers;
and the implementation should choose from pname:pDrmFormatModifiers the
optimal _modifier_ in consideration with the other image parameters.
The application creates the image by chaining
slink:VkImageDrmFormatModifierListCreateInfoEXT and
slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. The
protocol and APIs by which the application will share the image with external
consumers will likely determine the value of
slink:VkExternalMemoryImageCreateInfo::pname:handleTypes. The
implementation chooses for the image an optimal _modifier_ from
slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo.
The protocol and APIs by which the application will share the image with
external consumers will likely determine the value of
slink:VkExternalMemoryImageCreateInfo::pname:handleTypes.
The implementation chooses for the image an optimal _modifier_ from
slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers.
The application then queries the implementation-chosen _modifier_ with
flink:vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory
layout of each plane with flink:vkGetImageSubresourceLayout.
The application then allocates the image's memory with slink:VkMemoryAllocateInfo,
adding chained extension structures for external memory; binds it to the
image; and exports the memory, for example, with flink:vkGetMemoryFd.
The application then allocates the image's memory with
slink:VkMemoryAllocateInfo, adding chained extension structures for external
memory; binds it to the image; and exports the memory, for example, with
flink:vkGetMemoryFd.
Finally, the application sends the image's creation parameters, its _modifier_,
its per-plane memory layout, and the exported memory handle to the
external consumers. The details of how the application transmits this
information to external consumers is outside the scope of this specification.
Finally, the application sends the image's creation parameters, its
_modifier_, its per-plane memory layout, and the exported memory handle to
the external consumers.
The details of how the application transmits this information to external
consumers is outside the scope of this specification.
--
==== Prior Art
Extension
`EGL_EXT_image_dma_buf_import`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^
introduced the ability to create an stext:EGLImage by importing for each plane
a dma_buf, offset, and row pitch.
introduced the ability to create an stext:EGLImage by importing for each
plane a dma_buf, offset, and row pitch.
Later, extension
`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^
introduced the ability to query which combination of formats and _modifiers_
the implementation supports and to specify _modifiers_ during creation of the
stext:EGLImage.
the implementation supports and to specify _modifiers_ during creation of
the stext:EGLImage.
Extension
`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^ is
the inverse of `EGL_EXT_image_dma_buf_import_modifiers`.
`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,3>>^
is the inverse of `EGL_EXT_image_dma_buf_import_modifiers`.
The Linux kernel modesetting API (KMS), when configuring the display's
framebuffer with `struct
@ -225,11 +229,11 @@ drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, allows one to
specify the frambuffer's _modifier_ as well as a per-plane memory handle,
offset, and row pitch.
GBM, a graphics buffer manager for Linux, allows creation of a `gbm_bo` (that
is, a graphics _buffer object_) by importing data similar to that in
GBM, a graphics buffer manager for Linux, allows creation of a `gbm_bo`
(that is, a graphics _buffer object_) by importing data similar to that in
`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^;
and symmetrically allows exporting the same data from the `gbm_bo`. See the
references to _modifier_ and _plane_ in
and symmetrically allows exporting the same data from the `gbm_bo`.
See the references to _modifier_ and _plane_ in
`gbm.h`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^.
@ -287,147 +291,167 @@ None.
=== Issues
1. Should this extension define a single DRM format modifier per
1) Should this extension define a single DRM format modifier per
sname:VkImage? Or define one per plane?
+
--
*RESOLVED.*
There exists a single DRM format modifier per sname:VkImage.
*RESOLVED*: There exists a single DRM format modifier per sname:VkImage.
*DISCUSSION.*
Prior art, such as
*DISCUSSION*: Prior art, such as
`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^,
`struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and
`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^,
`struct
gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^,
allows defining one _modifier_ per plane.
However, developers of the GBM and kernel APIs concede it was a mistake. Beginning in
Linux 4.10, the kernel requires that the application provide the same DRM format
_modifier_ for each plane.
(See Linux commit https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bae781b259269590109e8a4a8227331362b88212[bae781b259269590109e8a4a8227331362b88212]).
However, developers of the GBM and kernel APIs concede it was a mistake.
Beginning in Linux 4.10, the kernel requires that the application provide
the same DRM format _modifier_ for each plane.
(See Linux commit
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bae781b259269590109e8a4a8227331362b88212[bae781b259269590109e8a4a8227331362b88212]).
And GBM provides an entrypoint, ftext:gbm_bo_get_modifier, for querying the
_modifier_ of the image but does not provide one to query the modifier of
individual planes.
--
2. When creating an image with slink:VkImageDrmFormatModifierExplicitCreateInfoEXT,
which is typically used when _importing_ an image,
should the application explicitly provide the size of each plane?
2) When creating an image with
slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, which is typically
used when _importing_ an image, should the application explicitly provide
the size of each plane?
+
--
*RESOLVED.* No. The application must: not provide the size. To enforce this,
the API requires that
*RESOLVED*: No.
The application must: not provide the size.
To enforce this, the API requires that
slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:pPlaneLayouts::<<VkSubresourceLayout,pname:size>>
must: be 0.
*DISCUSSION.*
Prior art, such as
*DISCUSSION*: Prior art, such as
`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^,
`struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and
`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, omits
from the API the size of each plane. Instead, the APIs infer each plane's size
from the import parameters, which include the image's pixel format and
a dma_buf, offset, and row pitch for each plane.
`struct
gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^,
omits from the API the size of each plane.
Instead, the APIs infer each plane's size from the import parameters, which
include the image's pixel format and a dma_buf, offset, and row pitch for
each plane.
However, Vulkan differs from EGL and GBM with regards to image
creation in the following ways:
However, Vulkan differs from EGL and GBM with regards to image creation in
the following ways:
.Differences in Image Creation
- *Undedicated allocation by default.*
When importing or exporting a set of dma_bufs as an stext:EGLImage or
stext:gbm_bo, common practice mandates that each dma_buf's memory be
dedicated (in the sense of `VK_KHR_dedicated_allocation`) to the image
(though not necessarily dedicated to a single plane). In particular,
neither the GBM documentation nor the EGL extension specifications explicitly
state this requirement, but in light of common practice this is likely due to
under-specification rather than intentional omission. In contrast,
`VK_EXT_image_drm_format_modifier` permits, but does not require, the
implementation to require dedicated allocations for images created with
ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.
- *Undedicated allocation by default.* When importing or exporting a set
of dma_bufs as an stext:EGLImage or stext:gbm_bo, common practice
mandates that each dma_buf's memory be dedicated (in the sense of
`VK_KHR_dedicated_allocation`) to the image (though not necessarily
dedicated to a single plane).
In particular, neither the GBM documentation nor the EGL extension
specifications explicitly state this requirement, but in light of common
practice this is likely due to under-specification rather than
intentional omission.
In contrast, `VK_EXT_image_drm_format_modifier` permits, but does not
require, the implementation to require dedicated allocations for images
created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.
- *Separation of image creation and memory allocation.*
When importing a set of dma_bufs as an stext:EGLImage or stext:gbm_bo, EGL
and GBM create the image resource and bind it to memory (the dma_bufs)
simultaneously. This allows EGL and GBM to query each dma_buf's size during
image creation. In Vulkan, image creation and memory allocation are
independent unless a dedicated allocation is used (as in
`VK_KHR_dedicated_allocation`). Therefore, without requiring dedicated
allocation, Vulkan cannot query the size of each dma_buf (or other external
handle) when calculating the image's memory layout. Even if dedication
allocation were required, Vulkan cannot calculate the image's memory layout
until after the image is bound to its dma_ufs.
- *Separation of image creation and memory allocation.* When importing a
set of dma_bufs as an stext:EGLImage or stext:gbm_bo, EGL and GBM create
the image resource and bind it to memory (the dma_bufs) simultaneously.
This allows EGL and GBM to query each dma_buf's size during image
creation.
In Vulkan, image creation and memory allocation are independent unless a
dedicated allocation is used (as in `VK_KHR_dedicated_allocation`).
Therefore, without requiring dedicated allocation, Vulkan cannot query
the size of each dma_buf (or other external handle) when calculating the
image's memory layout.
Even if dedication allocation were required, Vulkan cannot calculate the
image's memory layout until after the image is bound to its dma_ufs.
The above differences complicate the potential inference of plane size in
Vulkan. Consider the following problematic cases:
Vulkan.
Consider the following problematic cases:
.Problematic Plane Size Calculations
- *Padding.* Some plane of the image may require implementation-dependent padding.
- *Padding.* Some plane of the image may require implementation-dependent
padding.
- *Metadata.* For some _modifiers_, the image may have a metadata plane which
requires a non-trivial calculation to determine its size.
- *Metadata.* For some _modifiers_, the image may have a metadata plane
which requires a non-trivial calculation to determine its size.
- *Mipmapped, array, and 3D images.* The implementation may support
ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT for images whose
pname:mipLevels, pname:arrayLayers, or pname:depth is greater than 1. For
such images with certain _modifiers_, the calculation of each plane's size
may be non-trivial.
pname:mipLevels, pname:arrayLayers, or pname:depth is greater than 1.
For such images with certain _modifiers_, the calculation of each
plane's size may be non-trivial.
However, an application-provided plane size solves none of the above problems.
However, an application-provided plane size solves none of the above
problems.
For simplicity, consider an external image with a single memory plane. The
implementation is obviously capable calculating the image's size when its
tiling is ename:VK_IMAGE_TILING_OPTIMAL. Likewise, any reasonable
implementation is capable of calculating the image's size when its tiling uses
a supported _modifier_.
For simplicity, consider an external image with a single memory plane.
The implementation is obviously capable calculating the image's size when
its tiling is ename:VK_IMAGE_TILING_OPTIMAL.
Likewise, any reasonable implementation is capable of calculating the
image's size when its tiling uses a supported _modifier_.
Suppose that the external image's size is smaller than the
implementation-calculated size. If the application provided the external
image's size to slink:vkCreateImage, the implementation would observe the
mismatched size and recognize its inability to comprehend the external image's
layout (unless the implementation used the application-provided size to select
a refinement of the tiling layout indicated by the _modifier_, which is
strongly discouraged). The implementation would observe the conflict, and
reject image creation with
ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On the other
hand, if the application did not provide the external image's size to
slink:vkCreateImage, then the application would observe after
implementation-calculated size.
If the application provided the external image's size to
slink:vkCreateImage, the implementation would observe the mismatched size
and recognize its inability to comprehend the external image's layout
(unless the implementation used the application-provided size to select a
refinement of the tiling layout indicated by the _modifier_, which is
strongly discouraged).
The implementation would observe the conflict, and reject image creation
with ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
On the other hand, if the application did not provide the external image's
size to slink:vkCreateImage, then the application would observe after
calling flink:vkGetImageMemoryRequirements that the external image's size is
less than the size required by the implementation. The application would
observe the conflict and refuse to bind the sname:VkImage to the external
memory. In both cases, the result is explicit failure.
less than the size required by the implementation.
The application would observe the conflict and refuse to bind the
sname:VkImage to the external memory.
In both cases, the result is explicit failure.
Suppose that the external image's size is larger than the
implementation-calculated size. If the application provided the external
image's size to slink:vkCreateImage, for reasons similar to above the
implementation would observe the mismatched size and recognize its inability to
comprehend the image data residing in the extra size. The implementation,
however, must assume that image data resides in the entire size provided by the
application. The implementation would observe the conflict and reject image
creation with ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On
the other hand, if the application did not provide the external image's size to
flink:vkCreateImage, then the application would observe after calling
flink:vkGetImageMemoryRequirements that the external image's size is larger
than the implementation-usable size. The application would observe the
conflict and refuse to bind the sname:VkImage to the external memory. In both
cases, the result is explicit failure.
implementation-calculated size.
If the application provided the external image's size to
slink:vkCreateImage, for reasons similar to above the implementation would
observe the mismatched size and recognize its inability to comprehend the
image data residing in the extra size.
The implementation, however, must assume that image data resides in the
entire size provided by the application.
The implementation would observe the conflict and reject image creation with
ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.
On the other hand, if the application did not provide the external image's
size to flink:vkCreateImage, then the application would observe after
calling flink:vkGetImageMemoryRequirements that the external image's size is
larger than the implementation-usable size.
The application would observe the conflict and refuse to bind the
sname:VkImage to the external memory.
In both cases, the result is explicit failure.
Therefore, an application-provided size provides no benefit, and this extension
should not require it. This decision renders
slink:VkSubresourceLayout::pname:size an unused field during image creation,
and thus introduces a risk that implementations may require applications to
submit sideband creation parameters in the unused field. To prevent
implementations from relying on sideband data, this extension _requires_ the
application to set pname:size to 0.
Therefore, an application-provided size provides no benefit, and this
extension should not require it.
This decision renders slink:VkSubresourceLayout::pname:size an unused field
during image creation, and thus introduces a risk that implementations may
require applications to submit sideband creation parameters in the unused
field.
To prevent implementations from relying on sideband data, this extension
_requires_ the application to set pname:size to 0.
--
==== References
1. [[VK_EXT_image_drm_format_modifier-fn1]] https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import]
2. [[VK_EXT_image_drm_format_modifier-fn2]] https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers]
3. [[VK_EXT_image_drm_format_modifier-fn3]] https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_image_dma_buf_export.txt[EGL_MESA_image_dma_buf_export]
4. [[VK_EXT_image_drm_format_modifier-fn4]] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_mode.h?id=refs/tags/v4.10#n392[struct drm_mode_fb_cmd2]
5. [[VK_EXT_image_drm_format_modifier-fn5]] https://cgit.freedesktop.org/mesa/mesa/tree/src/gbm/main/gbm.h?id=refs/tags/mesa-18.0.0-rc1[gbm.h]
. [[VK_EXT_image_drm_format_modifier-fn1]]
https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import]
. [[VK_EXT_image_drm_format_modifier-fn2]]
https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers]
. [[VK_EXT_image_drm_format_modifier-fn3]]
https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_image_dma_buf_export.txt[EGL_MESA_image_dma_buf_export]
. [[VK_EXT_image_drm_format_modifier-fn4]]
https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_mode.h?id=refs/tags/v4.10#n392[struct
drm_mode_fb_cmd2]
. [[VK_EXT_image_drm_format_modifier-fn5]]
https://cgit.freedesktop.org/mesa/mesa/tree/src/gbm/main/gbm.h?id=refs/tags/mesa-18.0.0-rc1[gbm.h]
==== Version History

View File

@ -0,0 +1,49 @@
// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
include::meta/VK_FUCHSIA_imagepipe_surface.txt[]
*Last Modified Date*::
2018-07-27
*IP Status*::
No known IP claims.
*Contributors*::
- Craig Stout, Google
- Ian Elliott, Google
- Jesse Hall, Google
The `VK_FUCHSIA_imagepipe_surface` extension is an instance extension.
It provides a mechanism to create a slink:VkSurfaceKHR object (defined by
the `<<VK_KHR_surface>>` extension) that refers to a Fuchsia
code:imagePipeHandle.
=== New Object Types
None
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA
=== New Enums
None
=== New Structures
* slink:VkImagePipeSurfaceCreateInfoFUCHSIA
=== New Functions
* flink:vkCreateImagePipeSurfaceFUCHSIA
=== Issues
None
=== Version History
* Revision 1, 2018-07-27 (Craig Stout)
- Initial draft.

View File

@ -61,7 +61,7 @@ on imported semaphores that are in an invalid state?
*RESOLVED*: Yes.
Normally, validating such state would be the responsibility of the
application, and the implementation would be free to enter an undefined
application, and the implementation would be free to enter an undefined:
state if valid usage rules were violated.
However, this could cause security concerns when using imported semaphores,
as it would require the importing application to trust the exporting

View File

@ -4,7 +4,7 @@
include::meta/VK_KHR_shader_atomic_int64.txt[]
*Last Modified Data*::
*Last Modified Date*::
2018-07-05
*Interactions and External Dependencies*::
- This extension requires the
@ -23,7 +23,7 @@ which allows a shader to contain 64-bit atomic operations on signed and
unsigned integers.
The supported operations include OpAtomicMin, OpAtomicMax, OpAtomicAnd,
OpAtomicOr, OpAtomicXor, OpAtomicAdd, OpAtomicExchange, and
OpAtomicCompSwap.
OpAtomicCompareExchange.
=== New Enum Constants

View File

@ -273,7 +273,7 @@ limits out via trial/failure iterations.
15) Should there be a special value for
slink:VkSurfaceCapabilitiesKHR::pname:currentExtent to indicate the size of
the platform surface is undefined?
the platform surface is undefined:?
*RESOLVED*: Yes.
On some platforms (Wayland, for example), the surface size is defined by the
@ -321,7 +321,7 @@ necessary to express lack of support for no mirroring.
To allow this, the etext:MIRROR_NONE enum must occupy a bit in the flags.
Since etext:MIRROR_NONE must be a bit in the bitmask rather than a bitmask
with no values set, allowing more than one bit to be set in the bitmask
would make it possible to describe undefined transforms such as
would make it possible to describe undefined: transforms such as
etext:VK_MIRROR_NONE_BIT | etext:VK_MIRROR_HORIZONTAL_BIT, or a transform
that includes both "`no mirroring`" and "`horizontal mirroring`"
simultaneously.

View File

@ -72,7 +72,7 @@ these uses interfere with each other?
*RESOLVED*: Yes.
Uses of a window object by multiple graphics APIs results in undefined
Uses of a window object by multiple graphics APIs results in undefined:
behavior.
Such behavior may succeed when using one Vulkan implementation but fail when
using a different Vulkan implementation.

View File

@ -67,7 +67,7 @@ None.
(1) Is the representative fragment test guaranteed to have any effect?
**RESOLVED**: No.
*RESOLVED*: No.
As specified, we only guarantee that each primitive with at least one
fragment that passes prior tests will have one fragment passing the
representative fragment tests.
@ -83,7 +83,7 @@ images, with no writes to color or depth buffers.
(2) Will the set of fragments that pass the representative fragment test be
repeatable if you draw the same scene over and over again?
**RESOLVED**: No.
*RESOLVED*: No.
The set of fragments that pass the representative fragment test is
implementation-dependent and may vary due to the timing of operations
performed by the GPU.
@ -91,8 +91,8 @@ performed by the GPU.
(3) What happens if you enable the representative fragment test with writes
to color and/or depth render targets enabled?
**RESOLVED**: If writes to the color or depth buffer are enabled, they will
be performed for any fragments that survive the relevant tests.
*RESOLVED*: If writes to the color or depth buffer are enabled, they will be
performed for any fragments that survive the relevant tests.
Any fragments that fail the representative fragment test will not update
color buffers.
For the use cases intended for this feature, we don't expect color or depth
@ -101,7 +101,7 @@ writes to be enabled.
(4) How do derivatives and automatic texture level of detail computations
work with the representative fragment test enabled?
**RESOLVED**: If a fragment shader uses derivative functions or texture
*RESOLVED*: If a fragment shader uses derivative functions or texture
lookups using automatic level of detail computation, derivatives will be
computed identically whether or not the representative fragment test is
enabled.
@ -112,6 +112,5 @@ derivatives in the fragment shader.
* Revision 2, 2018-09-13 (pbrown)
- Add issues.
* Revision 1, 2018-08-22 (Kedarnath Thangudu)
- Internal Revisions

View File

@ -172,9 +172,8 @@ corresponding footprint texel.
(2) What should an application do to ensure maximum performance when
accumulating footprints into an aggregate footprint image?
**RESOLVED**: We expect that the most common usage of this feature will be
to accumulate aggregate footprint coverage, as described in the previous
issue.
*RESOLVED*: We expect that the most common usage of this feature will be to
accumulate aggregate footprint coverage, as described in the previous issue.
Even if you ignore the anisotropic filtering case where the implementation
may return a granularity larger than that requested by the caller, each
shader invocation will need to use atomic functions to update up to four

View File

@ -33,7 +33,6 @@ None.
=== New Enum Constants
* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_SWIZZLE_STATE_CREATE_INFO_NV
=== New Enums
@ -54,7 +53,7 @@ None.
1) Where does viewport swizzling occur in the pipeline?
**RESOLVED**: Despite being associated with the viewport, viewport swizzling
*RESOLVED*: Despite being associated with the viewport, viewport swizzling
must happen prior to the viewport transform.
In particular, it needs to be performed before clipping and perspective
division.
@ -70,7 +69,7 @@ feedback, and makes primitive queries only count each primitive once.
`<<VK_NV_viewport_array2>>`, and `<<VK_NV_geometry_shader_passthrough>>` can
be used together in practice?
**RESOLVED**: One interesting use case for this extension is for single-pass
*RESOLVED*: One interesting use case for this extension is for single-pass
rendering to a cubemap.
In this example, the application would attach a cubemap texture to a layered
FBO where the six cube faces are treated as layers.
@ -188,39 +187,38 @@ viewport swizzle does not support arbitrary math.
To get proper projection, [eq]#1/W# buffering should be used.
To do this:
1.
Program the viewport swizzles to move the pre-projection [eq]#W# eye
coordinate (typically 1.0) into the [eq]#Z# coordinate of the swizzle output
and the eye coordinate component used for depth into the [eq]#W# coordinate.
For example, the viewport corresponding to the [eq]#+Z# face might use a
swizzle of [eq]#(+X, -Y, +W, +Z)#.
The [eq]#Z# normalized device coordinate computed after swizzling would then
be [eq]#z'/w' = 1/Z~eye~#.
2.
On NVIDIA implementations supporting floating-point depth buffers with
values outside [eq]#[0,1]#, prevent unwanted near plane clipping by enabling
pname:depthClampEnable.
Ensure that the depth clamp doesn't mess up depth testing by programming the
depth range to very large values, such as [eq]#pname:minDepthBounds=-z#,
[eq]#pname:maxDepthBounds=+z#, where [eq]#z = 2^127^#.
It should be possible to use IEEE infinity encodings also (`0xFF800000` for
`-INF`, `0x7F800000` for `+INF`).
Even when near/far clipping is disabled, primitives extending behind the eye
will still be clipped because one or more vertices will have a negative
[eq]#W# coordinate and fail [eq]#X#/[eq]#Y# clipping tests.
. Program the viewport swizzles to move the pre-projection [eq]#W# eye
coordinate (typically 1.0) into the [eq]#Z# coordinate of the swizzle
output and the eye coordinate component used for depth into the [eq]#W#
coordinate.
For example, the viewport corresponding to the [eq]#+Z# face might use a
swizzle of [eq]#(+X, -Y, +W, +Z)#.
The [eq]#Z# normalized device coordinate computed after swizzling would
then be [eq]#z'/w' = 1/Z~eye~#.
. On NVIDIA implementations supporting floating-point depth buffers with
values outside [eq]#[0,1]#, prevent unwanted near plane clipping by
enabling pname:depthClampEnable.
Ensure that the depth clamp doesn't mess up depth testing by programming
the depth range to very large values, such as
[eq]#pname:minDepthBounds=-z#, [eq]#pname:maxDepthBounds=+z#, where
[eq]#z = 2^127^#.
It should be possible to use IEEE infinity encodings also (`0xFF800000`
for `-INF`, `0x7F800000` for `+INF`).
Even when near/far clipping is disabled, primitives extending behind the
eye will still be clipped because one or more vertices will have a
negative [eq]#W# coordinate and fail [eq]#X#/[eq]#Y# clipping tests.
+
--
On other implementations, scale [eq]#X#, [eq]#Y#, and [eq]#Z# eye
coordinates so that vertices on the near plane have a post-swizzle [eq]#W#
coordinate of 1.0.
For example, if the near plane is at [eq]#Z~eye~ = 1/256#, scale [eq]#X#,
[eq]#Y#, and [eq]#Z# by 256.
3.
Adjust depth testing to reflect the fact that [eq]#1/W# values are large
near the eye and small away from the eye.
Clear the depth buffer to zero (infinitely far away) and use a depth test of
ename:VK_COMPARE_OP_GREATER instead of ename:VK_COMPARE_OP_LESS.
--
. Adjust depth testing to reflect the fact that [eq]#1/W# values are large
near the eye and small away from the eye.
Clear the depth buffer to zero (infinitely far away) and use a depth
test of ename:VK_COMPARE_OP_GREATER instead of ename:VK_COMPARE_OP_LESS.
=== Version History

View File

@ -275,7 +275,7 @@ If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
This allows the application to define a binary-compatible custom handle
which may: provide more type-safety or other features needed by the
application.
Behavior is undefined if the application defines a non-binary-compatible
Behavior is undefined: if the application defines a non-binary-compatible
handle and may: result in memory corruption or application termination.
Binary compatibility is platform dependent so the application must: be
careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE

View File

@ -779,26 +779,28 @@ Linear Resource::
* a slink:VkBuffer
* a slink:VkImage created with ename:VK_IMAGE_TILING_LINEAR
ifdef::VK_EXT_image_drm_format_modifier[]
* a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
and whose <<glossary-drm-format-modifier,Linux DRM format modifier>>
is ename:DRM_FORMAT_MOD_LINEAR
* a slink:VkImage created with
ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and whose
<<glossary-drm-format-modifier,Linux DRM format modifier>> is
ename:DRM_FORMAT_MOD_LINEAR
endif::VK_EXT_image_drm_format_modifier[]
+
A resource is _non-linear_ if it is one of the following:
* a slink:VkImage created with ename:VK_IMAGE_TILING_OPTIMAL
ifdef::VK_EXT_image_drm_format_modifier[]
* a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
and whose <<glossary-drm-format-modifier,Linux DRM format modifier>>
is not ename:DRM_FORMAT_MOD_LINEAR
* a slink:VkImage created with
ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and whose
<<glossary-drm-format-modifier,Linux DRM format modifier>> is not
ename:DRM_FORMAT_MOD_LINEAR
endif::VK_EXT_image_drm_format_modifier[]
ifdef::VK_EXT_image_drm_format_modifier[]
[[glossary-drm-format-modifier,Linux DRM format modifier]]
Linux DRM Format Modifier::
A 64-bit, vendor-prefixed, semi-opaque unsigned integer that describes
vendor-specific details of an image's memory layout. In Linux graphics APIs,
_modifiers_ are
commonly used to specify the memory layout of externally shared images.
vendor-specific details of an image's memory layout.
In Linux graphics APIs, _modifiers_ are commonly used to specify the
memory layout of externally shared images.
An image has a _modifier_ if and only if it is created with pname:tiling
equal to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.
For more details, refer to the appendix for extension

View File

@ -640,7 +640,8 @@ instructions:
<<ieee-754,IEEE 754>> infinity.
* Any denormalized value input into a shader or potentially generated by
any instruction in a shader may: be flushed to 0.
* The rounding mode cannot: be set and is undefined.
* The rounding mode cannot: be set, and results will be <<Correctly
Rounded>>, as described below.
* [eq]##NaN##s may: not be generated.
Instructions that operate on a [eq]#NaN# may: not result in a [eq]#NaN#.
* Support for signaling [eq]##NaN##s is optional: and exceptions are never
@ -678,7 +679,7 @@ Where the range of allowed return values includes any value of magnitude
larger than that of the largest representable finite floating-point number,
operations may return an infinity of the appropriate sign.
If the infinitely precise result of the operation is not mathematically
defined then the value returned is undefined.
defined then the value returned is undefined:.
.Inherited From ...
Where an operation's precision is described as being inherited from a
@ -731,11 +732,11 @@ at least as follows, unless decorated with RelaxedPrecision:
GLSL.std.450 extended instructions specifically defined in terms of the
above instructions inherit the above errors.
GLSL.std.450 extended instructions not listed above and not defined in terms
of the above have undefined precision.
of the above have undefined: precision.
These include, for example, the trigonometric functions and determinant.
For the code:OpSRem and code:OpSMod instructions, if either operand is
negative the result is undefined.
negative the result is undefined:.
[NOTE]
.Note

View File

@ -141,7 +141,7 @@ as the product of non-premultiplied R, G, and B component values and the A
component of the color.
If any R, G, or B component of a premultiplied input color is non-zero and
the A component is zero, the color is considered ill-formed, and the
corresponding component of the blend result is undefined.
corresponding component of the blend result is undefined:.
The weighting functions [eq]#p~0~#, [eq]#p~1~#, and [eq]#p~2~# are defined
in table <<framebuffer-blend-advanced-overlap-modes,Advanced Blend Overlap

View File

@ -88,7 +88,7 @@ which cause a debug report, are:
include::../api/enums/VkDebugReportFlagBitsEXT.txt[]
* ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that an error that may
cause undefined results, including an application crash.
cause undefined: results, including an application crash.
* ename:VK_DEBUG_REPORT_WARNING_BIT_EXT specifies use of Vulkan that may:
expose an app bug.
Such cases may not be immediately harmful, such as a fragment shader
@ -134,7 +134,7 @@ include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
triggered.
* pname:object is the object where the issue was detected.
If pname:objectType is ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT,
pname:object is undefined.
pname:object is undefined:.
* pname:location is a component (layer, driver, loader) defined value that
specifies the _location_ of the trigger.
This is an optional: value.

View File

@ -466,7 +466,7 @@ include::../api/enums/VkDebugUtilsMessageSeverityFlagBitsEXT.txt[]
In general if you see a warning but you know that the behavior is
intended/desired, then simply ignore the warning.
* ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT specifies that an
error that may cause undefined results, including an application crash.
error that may cause undefined: results, including an application crash.
--

View File

@ -0,0 +1,53 @@
// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[[platformCreateSurface_imagepipe,platformCreateSurface_imagepipe]]
=== Fuchsia Platform
[open,refpage='vkCreateImagePipeSurfaceFUCHSIA',desc='Create a slink:VkSurfaceKHR object for a Fuchsia ImagePipe',type='protos']
--
To create a sname:VkSurfaceKHR object for a Fuchsia ImagePipe, call:
include::../../api/protos/vkCreateImagePipeSurfaceFUCHSIA.txt[]
* pname:instance is the instance to associate with the surface.
* pname:pCreateInfo is a pointer to an instance of the
slink:VkImagePipeSurfaceCreateInfoFUCHSIA structure containing
parameters affecting the creation of the surface object.
* pname:pAllocator is the allocator used for host memory allocated for the
surface object when there is no more specific allocator available (see
<<memory-allocation,Memory Allocation>>).
* pname:pSurface points to a slink:VkSurfaceKHR handle in which the
created surface object is returned.
include::../../validity/protos/vkCreateImagePipeSurfaceFUCHSIA.txt[]
--
[open,refpage='VkImagePipeSurfaceCreateInfoFUCHSIA',desc='Structure specifying parameters of a newly created ImagePipe surface object',type='structs']
--
The sname:VkImagePipeSurfaceCreateInfoFUCHSIA structure is defined as:
include::../../api/structs/VkImagePipeSurfaceCreateInfoFUCHSIA.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use.
* pname:imagePipeHandle is a code:zx_handle_t referring to the ImagePipe
to associate with the surface.
.Valid Usage
****
* [[VUID-VkImagePipeSurfaceCreateInfoFUCHSIA-imagePipeHandle-00000]]
pname:imagePipeHandle must: be a valid code:zx_handle_t
****
include::../../validity/structs/VkImagePipeSurfaceCreateInfoFUCHSIA.txt[]
--
On Fuchsia, the surface pname:currentExtent is the special value
[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#, indicating that the surface size will be
determined by the extent of a swapchain targeting the surface.

View File

@ -0,0 +1,12 @@
// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[[platformQuerySupport_fuchsia,platformQuerySupport_fuchsia]]
=== Fuchsia Platform
On Fuchsia, all physical devices and queue families must: be capable of
presentation with any ImagePipe.
As a result there is no Fuchsia-specific query for these capabilities.

View File

@ -114,6 +114,10 @@ ifdef::VK_KHR_xlib_surface[]
include::../VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[]
endif::VK_KHR_xlib_surface[]
ifdef::VK_FUCHSIA_imagepipe_surface[]
include::../VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt[]
endif::VK_FUCHSIA_imagepipe_surface[]
ifdef::VK_MVK_ios_surface[]
include::../VK_MVK_ios_surface/platformCreateSurface_ios.txt[]
endif::VK_MVK_ios_surface[]
@ -243,6 +247,10 @@ ifdef::VK_KHR_xlib_surface[]
include::../VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[]
endif::VK_KHR_xlib_surface[]
ifdef::VK_FUCHSIA_imagepipe_surface[]
include::../VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt[]
endif::VK_FUCHSIA_imagepipe_surface[]
ifdef::VK_MVK_ios_surface[]
include::../VK_MVK_ios_surface/platformQuerySupport_ios.txt[]
endif::VK_MVK_ios_surface[]

View File

@ -169,7 +169,7 @@ Usage requirements.
swapchain may: not own all of their pixels.
Pixels in the presentable images that correspond to regions of the
target surface obscured by another window on the desktop, or subject to
some other clipping mechanism will have undefined content when read
some other clipping mechanism will have undefined: content when read
back.
Pixel shaders may: not execute for these pixels, and thus any side
effects they would have had will not occur.
@ -585,14 +585,14 @@ the sname:VkImages returned by fname:vkGetSwapchainImagesKHR.
The memory for each image will not alias with the memory for other images or
with any sname:VkDeviceMemory object.
As such, performing any operation affecting the binding of memory to a
presentable image results in undefined behavior.
presentable image results in undefined: behavior.
All presentable images are initially in the ename:VK_IMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must:
transition them to a valid layout for the intended use.
Further, the lifetime of presentable images is controlled by the
implementation so destroying a presentable image with flink:vkDestroyImage
results in undefined behavior.
results in undefined: behavior.
See flink:vkDestroySwapchainKHR for further details on the lifetime of
presentable images.
@ -809,15 +809,26 @@ re-create the swapchain to better match the platform surface properties.
If the native surface and presented image sizes no longer match,
presentation may: fail.
If presentation does succeed, parts of the native surface may: be undefined,
parts of the presented image may: have been clipped before presentation,
and/or the image may: have been scaled (uniformly or not uniformly) before
presentation.
If presentation does succeed, the mapping from the presented image to the
native surface is implementation-defined.
It is the application's responsibility to detect surface size changes and
react appropriately.
If presentation fails because of a mismatch in the surface and presented
image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be returned.
[NOTE]
.Note
====
For example, consider a 4x3 window/surface that gets resized to be 3x4
(taller than wider).
On some window systems, the portion of the window/surface that was
previously and still is visible (the 3x3 part) will contain the same
contents as before, while the remaining parts of the window will have
undefined: contents.
Other window systems may: squash/stretch the image to fill the new window
size without any undefined: contents, or apply some other mapping.
====
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkAcquireNextImage2KHR',desc='Retrieve the index of the next available presentable image',type='protos']
@ -1122,7 +1133,7 @@ If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each
element of pname:pDeviceMasks selects which instances of the swapchain image
are component-wise summed and the sum of those images is presented.
If the sum in any component is outside the representable range, the value of
that component is undefined.
that component is undefined:.
Each element of pname:pDeviceMasks must: have a value for which all set bits
are set in one of the elements of
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.
@ -1232,7 +1243,7 @@ as they were prior to transitioning the image to the present source layout
and presenting it.
However, if a mechanism other than Vulkan is used to modify the platform
window associated with the swapchain, the content of all presentable images
in the swapchain becomes undefined.
in the swapchain becomes undefined:.
[NOTE]
.Note

View File

@ -50,7 +50,9 @@ include::../../api/structs/VkWaylandSurfaceCreateInfoKHR.txt[]
include::../../validity/structs/VkWaylandSurfaceCreateInfoKHR.txt[]
--
On Wayland, pname:currentExtent is undefined [eq]#(0xFFFFFFFF, 0xFFFFFFFF)#.
On Wayland, pname:currentExtent is the special value [eq]#(0xFFFFFFFF,
0xFFFFFFFF)#, indicating that the surface size will be determined by the
extent of a swapchain targeting the surface.
Whatever the application sets a swapchain's pname:imageExtent to will be the
size of the window, after the first image is presented.
pname:minImageExtent is [eq]#(1,1)#, and pname:maxImageExtent is the maximum

View File

@ -25,9 +25,9 @@ During the lifetime of a surface created using a particular
code:nn::code:vi::code:NativeWindowHandle any attempts to create another
surface for the same code:nn::code:vi::code:Layer and any attempts to
connect to the same code:nn::code:vi::code:Layer through other platform
mechanisms will have undefined results.
mechanisms will have undefined: results.
The pname:currentExtent of a VI surface is always undefined.
The pname:currentExtent of a VI surface is always undefined:.
Applications are expected to choose an appropriate size for the swapchain's
pname:imageExtent (e.g., by matching the result of a call to
code:nn::code:vi::code:GetDisplayResolution).

View File

@ -54,7 +54,7 @@ defined in the command buffer prior this call.
However, given the stateless nature of the generated sequences, they will
not affect commands after the reserved space.
Treat the state that can: be affected by the provided
sname:VkIndirectCommandsLayoutNVX as undefined.
sname:VkIndirectCommandsLayoutNVX as undefined:.
[open,refpage='vkCmdProcessCommandsNVX',desc='Performs the generation of commands on the device',type='protos']
--
@ -187,7 +187,7 @@ cmdProcessAllSequences(cmd, objectTable,
.Note
====
It is important to note that the state that may be affected through
generated commands must: be considered undefined for the commands following
generated commands must: be considered undefined: for the commands following
them.
It is not possible to setup generated state and provoking work that uses
this state outside of the generated sequence.

View File

@ -370,7 +370,7 @@ include::../api/structs/VkClearColorValue.txt[]
negative values in the smaller type).
If the integer clear value is not representable in the target type (e.g.
would overflow in conversion to that type), the clear value is
undefined.
undefined:.
* pname:uint32 are the color clear values when the format of the image or
attachment is unsigned integer (etext:UINT).
Unsigned integer values are converted to the format of the image by

View File

@ -32,18 +32,18 @@ Each command buffer manages state independently of other command buffers.
There is no inheritance of state across primary and secondary command
buffers, or between secondary command buffers.
When a command buffer begins recording, all state in that command buffer is
undefined.
undefined:.
When secondary command buffer(s) are recorded to execute on a primary
command buffer, the secondary command buffer inherits no state from the
primary command buffer, and all state of the primary command buffer is
undefined after an execute secondary command buffer command is recorded.
undefined: after an execute secondary command buffer command is recorded.
There is one exception to this rule - if the primary command buffer is
inside a render pass instance, then the render pass and subpass state is not
disturbed by executing secondary command buffers.
Whenever the state of a command buffer is undefined, the application must:
Whenever the state of a command buffer is undefined:, the application must:
set all relevant state on the command buffer before any state dependent
commands such as draws and dispatches are recorded, otherwise the behavior
of executing that command buffer is undefined.
of executing that command buffer is undefined:.
Unless otherwise specified, and without explicit synchronization, the
various commands submitted to a queue via command buffers may: execute in
@ -101,8 +101,7 @@ Invalid::
Command buffers in the invalid state can: only be reset or freed.
[[commandbuffer-lifecycle-diagram]]
[%inline]
image::images/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center"]
image::images/commandbuffer_lifecycle.svg[title="Lifecycle of a command buffer",align="center",opts="{imageopts}"]
Any given command that operates on a command buffer has its own requirements
on what state a command buffer must: be in, which are detailed in the valid
@ -1351,7 +1350,7 @@ the fname:vkCmdWaitEvents commands that wait upon them must: not be inside a
render pass instance.
Implementations may: have limits on how long the command buffer will wait,
in order to avoid interfering with progress of other clients of the device.
If the event is not signaled within these limits, results are undefined and
If the event is not signaled within these limits, results are undefined: and
may: include device loss.

View File

@ -84,8 +84,8 @@ include::../api/protos/vkCmdCopyBuffer.txt[]
Each region in pname:pRegions is copied from the source buffer to the same
region of the destination buffer.
pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the
same memory, but the result is undefined if the copy regions overlap in
memory.
same memory, but the resulting values are undefined: if the copy regions
overlap in memory.
.Valid Usage
****
@ -1102,7 +1102,7 @@ Specifically:
* data copied to or from the depth aspect of a
ename:VK_FORMAT_X8_D24_UNORM_PACK32 or ename:VK_FORMAT_D24_UNORM_S8_UINT
format is packed with one 32-bit word per texel with the D24 value in
the LSBs of the word, and undefined values in the eight MSBs.
the LSBs of the word, and undefined: values in the eight MSBs.
[NOTE]
.Note
@ -1115,8 +1115,11 @@ in pname:imageSubresource, and the other specifies the stencil aspect.
Because depth or stencil aspect buffer to image copies may: require format
conversions on some implementations, they are not supported on queues that
do not support graphics.
ifndef::VK_EXT_depth_range_unrestricted[]
When copying to a depth aspect, the data in buffer memory must: be in the
the range [eq]#[0,1]# or undefined results occur.
the range [eq]#[0,1]#, or the resulting values are undefined:.
endif::VK_EXT_depth_range_unrestricted[]
Copies are done layer by layer starting with image layer
pname:baseArrayLayer member of pname:imageSubresource.
@ -1301,9 +1304,11 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If the calling command's sname:VkImage parameter is of elink:VkImageType
ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount
members of pname:imageSubresource must: be `0` and `1`, respectively
ifndef::VK_EXT_depth_range_unrestricted[]
* [[VUID-VkBufferImageCopy-None-00214]]
When copying to the depth aspect of an image subresource, the data in
the source buffer must: be in the range [eq]#[0,1]#
endif::VK_EXT_depth_range_unrestricted[]
****
include::../validity/structs/VkBufferImageCopy.txt[]
@ -1479,9 +1484,9 @@ between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname:z.
If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value
sampled from the source image is taken by doing linear filtering using the
interpolated *z* coordinate.
If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from
the source image is taken from the single nearest slice (with undefined
rounding mode).
If pname:filter parameter is ename:VK_FILTER_NEAREST then the value sampled
from the source image is taken from the single nearest slice, with an
implementation-dependent arithmetic rounding mode.
The following filtering and conversion rules apply:

View File

@ -537,8 +537,8 @@ The above layout definition allows the descriptor bindings to be specified
sparsely such that not all binding numbers between 0 and the maximum binding
number need to be specified in the pname:pBindings array.
Bindings that are not specified have a pname:descriptorCount and
pname:stageFlags of zero, and the pname:descriptorType is treated as
undefined.
pname:stageFlags of zero, and the value of pname:descriptorType is
undefined:.
However, all binding numbers between 0 and the maximum binding number in the
slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings array may: consume
memory in the descriptor set layout even if not all descriptor bindings are
@ -908,7 +908,7 @@ pname:descriptorCount of zero is treated as if the pname:descriptorCount is
one, and thus the binding is not ignored and the maximum descriptor count
will be returned.
If the layout is not supported, then the value written to
pname:maxVariableDescriptorCount is undefined.
pname:maxVariableDescriptorCount is undefined:.
include::../validity/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.txt[]
--
@ -1572,7 +1572,7 @@ include::../api/structs/VkPushConstantRange.txt[]
that will access a range of push constants.
If a particular stage is not included in the range, then accessing
members of that range of push constants from the corresponding shader
stage will result in undefined data being read.
stage will return undefined: values.
* pname:offset and pname:size are the start offset and size, respectively,
consumed by the range.
Both pname:offset and pname:size are in units of bytes and must: be a
@ -2090,7 +2090,7 @@ include::../api/protos/vkAllocateDescriptorSets.txt[]
The allocated descriptor sets are returned in pname:pDescriptorSets.
When a descriptor set is allocated, the initial state is largely
uninitialized and all descriptors are undefined.
uninitialized and all descriptors are undefined:.
However, the descriptor set can: be bound in a command buffer without
causing errors or exceptions.
ifdef::VK_EXT_descriptor_indexing[]
@ -2107,9 +2107,14 @@ ifndef::VK_EXT_descriptor_indexing[]
All descriptors that are statically used must: have been populated before
the descriptor set is consumed.
endif::VK_EXT_descriptor_indexing[]
ifdef::VK_EXT_inline_uniform_block[]
Descriptor bindings with descriptor type of
ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT need not be populated
before the descriptor set is consumed.
endif::VK_EXT_inline_uniform_block[]
Entries that are not used by a pipeline can: have uninitialized descriptors
or descriptors of resources that have been destroyed, and executing a draw
or dispatch with such a descriptor set bound does not cause undefined
or dispatch with such a descriptor set bound does not cause undefined:
behavior.
This means applications need not populate unused entries with dummy
descriptors.
@ -3669,7 +3674,7 @@ descriptor set and later bound to a command buffer.
Push descriptors allow for incremental updates of descriptors without
managing the lifetime of descriptor sets.
When a command buffer begins recording, all push descriptors have undefined
When a command buffer begins recording, all push descriptors have undefined:
contents.
Push descriptors can: be updated incrementally and cause shaders to use the
updated descriptors for subsequent rendering commands (either compute or
@ -3848,7 +3853,8 @@ Push constants represent a high speed path to modify constant data in
pipelines that is expected to outperform memory-backed resource updates.
====
The values of push constants are undefined at the start of a command buffer.
The values of push constants are undefined: at the start of a command
buffer.
[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos']
--

View File

@ -344,8 +344,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
compatibility>>
endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
If pname:deviceLUIDValid is ename:VK_FALSE, the contents of pname:deviceLUID
and pname:deviceNodeMask are undefined.
If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID
and pname:deviceNodeMask are undefined:.
If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the
Windows operating system, the contents of pname:deviceLUID can: be cast to
an sname:LUID object and must: be equal to the locally unique identifier of
@ -482,6 +482,7 @@ include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
If pname:pQueueFamilyProperties is `NULL`, then the number of queue families
available is returned in pname:pQueueFamilyPropertyCount.
Implementations must: support at least one queue family.
Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by
the user to the number of elements in the pname:pQueueFamilyProperties
array, and on return the variable is overwritten with the number of
@ -504,6 +505,7 @@ include::../api/structs/VkQueueFamilyProperties.txt[]
capabilities of the queues in this queue family.
* pname:queueCount is the unsigned integer count of queues in this queue
family.
Each queue family must: support at least one queue.
* pname:timestampValidBits is the unsigned integer count of meaningful
bits in the timestamps written via fname:vkCmdWriteTimestamp.
The valid range for the count is 36..64 bits, or a value of 0,
@ -1089,10 +1091,10 @@ via the Vulkan API.
====
Undefined behavior caused by an application error may: cause a device to
become lost.
However, such undefined behavior may: also cause unrecoverable damage to the
process, and it is then not guaranteed that the API objects, including the
sname:VkPhysicalDevice or the sname:VkInstance are still valid or that the
error is recoverable.
However, such undefined: behavior may: also cause unrecoverable damage to
the process, and it is then not guaranteed that the API objects, including
the sname:VkPhysicalDevice or the sname:VkInstance are still valid or that
the error is recoverable.
====
When a device is lost, its child objects are not implicitly destroyed and
@ -1102,7 +1104,7 @@ can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object
Lifetime>> section).
The host address space corresponding to device memory mapped using
flink:vkMapMemory is still valid, and host memory accesses to these mapped
regions are still valid, but the contents are undefined.
regions are still valid, but the contents are undefined:.
It is still legal to call any API command on the device and child objects.
Once a device is lost, command execution may: fail, and commands that return
@ -1128,10 +1130,10 @@ ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS.
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
The content of any external memory objects that have been exported from or
imported to a lost device become undefined.
imported to a lost device become undefined:.
Objects on other logical devices or in other APIs which are associated with
the same underlying memory resource as the external memory objects on the
lost device are unaffected other than their content becoming undefined.
lost device are unaffected other than their content becoming undefined:.
The layout of subresources of images on other logical devices that are bound
to sname:VkDeviceMemory objects associated with the same underlying memory
resources as external memory objects on the lost device becomes
@ -1143,10 +1145,10 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[]
The state of sname:VkSemaphore objects on other logical devices created by
<<synchronization-semaphores-importing,importing a semaphore payload>> with
temporary permanence which was exported from the lost device is undefined.
temporary permanence which was exported from the lost device is undefined:.
The state of sname:VkSemaphore objects on other logical devices that
permanently share a semaphore payload with a sname:VkSemaphore object on the
lost device is undefined, and remains undefined following any subsequent
lost device is undefined:, and remains undefined: following any subsequent
signal operations.
Implementations must: ensure pending and subsequently submitted wait
operations on such semaphores behave as defined in

View File

@ -156,8 +156,7 @@ ename:VK_PRIMITIVE_TOPOLOGY_POINT_LIST.
Each vertex defines a separate point.
.Point Lists
[%inline]
image::images/primitive_topology_point_list.svg[align="center"]
image::images/primitive_topology_point_list.svg[align="center",opts="{imageopts}"]
=== Line Lists
@ -169,8 +168,7 @@ vertices each defining one more segment.
If the number of vertices is odd, then the last vertex is ignored.
.Line Lists
[%inline]
image::images/primitive_topology_line_list.svg[align="center"]
image::images/primitive_topology_line_list.svg[align="center",opts="{imageopts}"]
=== Line Strips
@ -186,8 +184,7 @@ The last vertex specifies the end of the last segment.
If only one vertex is specified, then no primitive is generated.
.Line Strips
[%inline]
image::images/primitive_topology_line_strip.svg[align="center"]
image::images/primitive_topology_line_strip.svg[align="center",opts="{imageopts}"]
=== Triangle Lists
@ -201,8 +198,7 @@ where there are [eq]#3 n {plus} k# vertices drawn.
vertices are ignored.
.Triangle Lists
[%inline]
image::images/primitive_topology_triangle_list.svg[align="center"]
image::images/primitive_topology_triangle_list.svg[align="center",opts="{imageopts}"]
=== Triangle Strips
@ -218,8 +214,7 @@ The order of vertices in successive triangles changes as shown in the figure
below, so that all triangle faces have the same orientation.
.Triangle Strips
[%inline]
image::images/primitive_topology_triangle_strip.svg[align="center"]
image::images/primitive_topology_triangle_strip.svg[align="center",opts="{imageopts}"]
=== Triangle Fans
@ -230,8 +225,7 @@ It is similar to a triangle strip, but changes the vertex replaced from the
previous triangle so that all triangles in the fan share a common vertex.
.Triangle Fans
[%inline]
image::images/primitive_topology_triangle_fan.svg[align="center"]
image::images/primitive_topology_triangle_fan.svg[align="center",opts="{imageopts}"]
=== Line Lists With Adjacency
@ -252,8 +246,7 @@ are considered adjacent to vertices [eq]#4 i {plus} 1# and [eq]#4 i {plus}
2#, respectively.
.Line Lists With Adjacency
[%inline]
image::images/primitive_topology_line_list_with_adjacency.svg[align="center"]
image::images/primitive_topology_line_list_with_adjacency.svg[align="center",opts="{imageopts}"]
=== Line Strips With Adjacency
@ -273,8 +266,7 @@ considered adjacent to vertices [eq]#i {plus} 1# and [eq]#i {plus} 2#,
respectively.
.Line Strips With Adjacency
[%inline]
image::images/primitive_topology_line_strip_with_adjacency.svg[align="center"]
image::images/primitive_topology_line_strip_with_adjacency.svg[align="center",opts="{imageopts}"]
=== Triangle Lists With Adjacency
@ -296,8 +288,7 @@ For triangle [eq]#i#, vertices [eq]#6 i {plus} 1#, [eq]#6 i {plus} 3#, and
4#, and from [eq]#6 i {plus} 4# to [eq]#6 i# vertices, respectively.
.Triangle Lists With Adjacency
[%inline]
image::images/primitive_topology_triangle_list_with_adjacency.svg[align="center"]
image::images/primitive_topology_triangle_list_with_adjacency.svg[align="center",opts="{imageopts}"]
=== Triangle Strips With Adjacency
@ -314,8 +305,7 @@ are [eq]#2 (n {plus} 2) {plus} k# vertices.
If there are fewer than 6 vertices, the entire primitive is ignored.
.Triangle Strips With Adjacency
[%inline]
image::images/primitive_topology_triangle_strip_with_adjacency.svg[align="center"]
image::images/primitive_topology_triangle_strip_with_adjacency.svg[align="center",opts="{imageopts}"]
The table below illustrates the vertices and order used to draw each
triangle, and which vertices are considered adjacent to each edge of those
@ -428,10 +418,10 @@ the pipeline.
If the draw includes multiple instances, then the set of primitives is sent
to the vertex shading stage multiple times, once for each instance.
It is undefined whether vertex shading occurs on vertices that are discarded
as part of incomplete primitives, but if it does occur then it operates as
if they were vertices in complete primitives and such invocations can: have
side effects.
It is implementation-dependent whether vertex shading occurs on vertices
that are discarded as part of incomplete primitives, but if it does occur
then it operates as if they were vertices in complete primitives and such
invocations can: have side effects.
Vertex shading receives two per-vertex inputs from the primitive assembly
stage - the code:vertexIndex and the code:instanceIndex.

View File

@ -64,7 +64,7 @@ sname:VkDevice creation time.
If a feature is enabled that the physical device does not support,
sname:VkDevice creation will fail.
If an application uses a feature without enabling it at sname:VkDevice
creation time, the device behavior is undefined.
creation time, the device behavior is undefined:.
The validation layer will warn if features are used without being enabled.
The fine-grained features are enabled by passing a pointer to the
@ -223,7 +223,7 @@ used.
bound to the buffer, but must: not modify any other memory.
** Out-of-bounds atomics may: modify values within the memory range(s)
bound to the buffer, but must: not modify any other memory, and return
an undefined value.
an undefined: value.
** Vertex input attributes are considered out of bounds if the offset of
the attribute in the bound vertex buffer range plus the size of the
attribute is greater than either:
@ -246,7 +246,7 @@ binding for that vertex shader invocation are considered out of bounds.
attribute.
**** Zero values, or [eq]#(0,0,0,x)# vectors, as described above.
** If pname:robustBufferAccess is not enabled, out of bounds accesses may:
corrupt any memory within the process and cause undefined behavior up
corrupt any memory within the process and cause undefined: behavior up
to and including application termination.
* [[features-features-fullDrawIndexUint32]] pname:fullDrawIndexUint32
specifies the full 32-bit range of indices is supported for indexed draw
@ -421,9 +421,10 @@ endif::VK_NV_scissor_exclusive[]
** ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK
** ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK
+
To query for additional properties, or if the feature is not enabled,
flink:vkGetPhysicalDeviceFormatProperties and
flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for
additional supported properties of individual formats.
supported properties of individual formats as normal.
* [[features-features-textureCompressionASTC_LDR]]
pname:textureCompressionASTC_LDR specifies whether all of the ASTC LDR
@ -463,9 +464,10 @@ additional supported properties of individual formats.
** ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK
** ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK
+
To query for additional properties, or if the feature is not enabled,
flink:vkGetPhysicalDeviceFormatProperties and
flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for
additional supported properties of individual formats.
supported properties of individual formats as normal.
* [[features-features-textureCompressionBC]] pname:textureCompressionBC
specifies whether all of the BC compressed texture formats are
@ -493,9 +495,10 @@ additional supported properties of individual formats.
** ename:VK_FORMAT_BC7_UNORM_BLOCK
** ename:VK_FORMAT_BC7_SRGB_BLOCK
+
To query for additional properties, or if the feature is not enabled,
flink:vkGetPhysicalDeviceFormatProperties and
flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for
additional supported properties of individual formats.
supported properties of individual formats as normal.
* [[features-features-occlusionQueryPrecise]] pname:occlusionQueryPrecise
specifies whether occlusion queries returning actual sample counts are
@ -3071,7 +3074,7 @@ mapping of the image view used with min/max filtering must: have been
created with the pname:r component set to
ename:VK_COMPONENT_SWIZZLE_IDENTITY.
Only the pname:r component of the sampled image value is defined and the
other component values are undefined.
other component values are undefined:.
If pname:filterMinmaxImageComponentMapping is ename:VK_TRUE this restriction
does not apply and image component mapping works as normal.
@ -3090,11 +3093,11 @@ include::../api/structs/VkPhysicalDeviceProtectedMemoryProperties.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:protectedNoFault specifies whether the undefined behavior will not
* pname:protectedNoFault specifies whether the undefined: behavior may:
include process termination or device loss.
If pname:protectedNoFault is ename:VK_FALSE, undefined behavior may:
If pname:protectedNoFault is ename:VK_FALSE, undefined: behavior may:
include process termination or device loss.
If pname:protectedNoFault is ename:VK_TRUE, undefined behavior will not
If pname:protectedNoFault is ename:VK_TRUE, undefined: behavior will not
include process termination or device loss.
If the sname:VkPhysicalDeviceProtectedMemoryProperties structure is included
@ -7154,7 +7157,7 @@ sname:VkImageFormatProperties will be filled with zero.
.Note
====
Filling sname:VkImageFormatProperties with zero for unsupported formats is
an exception to the usual rule that output structures have undefined
an exception to the usual rule that output structures have undefined:
contents on error.
This exception was unintentional, but is preserved for backwards
compatibility.
@ -7292,7 +7295,7 @@ pname:imageFormatProperties will be filled with zero.
.Note
====
Filling pname:imageFormatProperties with zero for unsupported formats is an
exception to the usual rule that output structures have undefined contents
exception to the usual rule that output structures have undefined: contents
on error.
This exception was unintentional, but is preserved for backwards
compatibility.

View File

@ -633,7 +633,7 @@ coverage value.
endif::VK_NV_sample_mask_override_coverage[]
If such a fragment shader did not assign a value to code:SampleMask due to
flow of control, the value code:ANDed with the fragment coverage is
undefined.
undefined:.
If no fragment shader is active, or if the active fragment shader does not
include code:SampleMask in its interface, the fragment coverage is not
modified.
@ -967,7 +967,7 @@ stencil comparison.
The reference value used by stencil comparison must be within the range
[eq]#[0,2^s^-1]# , where [eq]#s# is the number of bits in the stencil
framebuffer attachment, otherwise the reference value is considered
undefined.
undefined:.
The [eq]#s# least significant bits of pname:compareMask are bitwise
code:ANDed with both the reference and the stored stencil value, and the
resulting masked values are those that participate in the comparison

View File

@ -684,7 +684,7 @@ although more rigorous validation can: be enabled through the use of layers.
The core layer assumes applications are using the API correctly.
Except as documented elsewhere in the Specification, the behavior of the
core layer to an application using the API incorrectly is undefined, and
core layer to an application using the API incorrectly is undefined:, and
may: include program termination.
However, implementations must: ensure that incorrect usage by an application
does not affect the integrity of the operating system, the Vulkan
@ -885,7 +885,7 @@ A bit flag is valid if:
Any etext:Vk*Flags member or parameter returned from a query command or
otherwise output from Vulkan to the application may: contain bit flags
undefined in its corresponding etext:Vk*FlagBits type.
undefined: in its corresponding etext:Vk*FlagBits type.
An application cannot: rely on the state of these unspecified bits.
@ -1127,10 +1127,10 @@ ifdef::VK_EXT_descriptor_indexing[]
endif::VK_EXT_descriptor_indexing[]
If a command returns a run time error, unless otherwise specified any output
parameters will have undefined contents, except that if the output parameter
is a structure with pname:sType and pname:pNext fields, those fields will be
unmodified.
Any structures chained from pname:pNext will also have undefined contents,
parameters will have undefined: contents, except that if the output
parameter is a structure with pname:sType and pname:pNext fields, those
fields will be unmodified.
Any structures chained from pname:pNext will also have undefined: contents,
except that pname:sType and pname:pNext will be unmodified.
Out of memory errors do not damage any currently existing Vulkan objects.
@ -1212,7 +1212,7 @@ Most single-precision floating-point formats meet these requirements.
The special values [eq]#Inf# and [eq]#-Inf# encode values with magnitudes
too large to be represented; the special value [eq]#NaN# encodes {ldquo}Not
A Number{rdquo} values resulting from undefined arithmetic operations such
A Number{rdquo} values resulting from undefined: arithmetic operations such
as [eq]#0 / 0#.
Implementations may: support [eq]#Inf# and [eq]#NaN# in their floating-point
computations.

View File

@ -41,8 +41,8 @@ be cast to the type of the command being queried.
[width="80%",options="header"]
|====
| pname:instance | pname:pName | return value
| * | `NULL` | undefined
| invalid instance | * | undefined
| * | `NULL` | undefined:
| invalid instance | * | undefined:
ifdef::VK_VERSION_1_1[]
| `NULL` | flink:vkEnumerateInstanceVersion | fp
endif::VK_VERSION_1_1[]
@ -95,9 +95,9 @@ first parameter) that is pname:device or a child of pname:device.
[width="80%",options="header"]
|====
| pname:device | pname:pName | return value
| `NULL` | * | undefined
| invalid device | * | undefined
| device | `NULL` | undefined
| `NULL` | * | undefined:
| invalid device | * | undefined:
| device | `NULL` | undefined:
| device | core device-level Vulkan command | fp
| device | enabled device extension commands | fp
| device | * (any pname:pName not covered above) | `NULL`
@ -148,12 +148,12 @@ To obtain a function pointer for a physical-device-level command from a
device extension, an application can: use flink:vkGetInstanceProcAddr.
This function pointer may: point to dispatch code, which calls a different
real implementation for different sname:VkPhysicalDevice objects.
Behavior is undefined if an extension physical-device command is called on a
physical device that does not support the extension.
Behavior is undefined: if an extension physical-device command is called on
a physical device that does not support the extension.
Device extensions may: define structures that can: be added to the
ptext:pNext chain of physical-device-level commands.
Behavior is undefined if such an extension structure is passed to a
Behavior is undefined: if such an extension structure is passed to a
physical-device-level command for a physical device that does not support
the extension.

View File

@ -53,7 +53,7 @@ operands to the code:OpEntryPoint instruction and are declared with the
code:Input or code:Output storage classes, respectively, in the SPIR-V
module.
code:Output variables of a shader stage have undefined values until the
code:Output variables of a shader stage have undefined: values until the
shader writes to them or uses the code:Initializer operand when declaring
the variable.
@ -371,8 +371,8 @@ B, and A inputs to the blending unit, respectively, or to the output
attachment if blending is disabled.
If two variables are placed within the same location, they must: have the
same underlying type (floating-point or integer).
The input to blending or color attachment writes is undefined for components
which do not correspond to a fragment shader output.
The input values to blending or color attachment writes are undefined: for
components which do not correspond to a fragment shader output.
Fragment outputs identified with an code:Index of zero are directed to the
first input of the blending unit associated with the corresponding
@ -398,11 +398,11 @@ fixed-point as described in <<fundamentals-fpfixedconv>>; If the color
attachment has an integer format, color values are assumed to be integers
and converted to the bit-depth of the target.
Any value that cannot be represented in the attachment's format is
undefined.
undefined:.
For any other attachment format no conversion is performed.
If the type of the values written by the fragment shader do not match the
format of the corresponding color attachment, the result is undefined for
those components.
format of the corresponding color attachment, the resulting values are
undefined: for those components.
[[interfaces-inputattachment]]
@ -440,7 +440,7 @@ by a fragment stage.
The basic data type (floating-point, integer, unsigned integer) of the
subpass input must: match the basic format of the corresponding input
attachment, or the values of subpass loads from these variables are
undefined.
undefined:.
See <<descriptorsets-inputattachment>> for more details.
@ -514,7 +514,7 @@ code:OpTypeSampledImage, or an array of one of these types.
The code:Sampled code:Type of an code:OpTypeImage declaration must: match
the same basic data type as the corresponding resource, or the values
obtained by reading or sampling from this image are undefined.
obtained by reading or sampling from this image are undefined:.
The code:Image code:Format of an code:OpTypeImage declaration must: not be
*Unknown*, for variables which are used for code:OpImageRead,
@ -1399,8 +1399,8 @@ ifdef::VK_EXT_shader_stencil_export[]
code:FragStencilRefEXT::
Decorating a variable with the code:FragStencilRefEXT built-in decoration
will make that variable contain the stencil reference value for all samples
covered by the fragment.
will make that variable contain the new stencil reference value for all
samples covered by the fragment.
This value will be used as the stencil reference value used in stencil
testing.
+
@ -1409,7 +1409,7 @@ code:StencilRefReplacingEXT execution mode.
If a shader declares the code:StencilRefReplacingEXT execution mode and
there is an execution path through the shader that does not set
code:FragStencilRefEXT, then the fragment's stencil reference value is
undefined for executions of the shader that take that path.
undefined: for executions of the shader that take that path.
+
The code:FragStencilRefEXT decoration must: be used only within fragment
shaders.
@ -1737,7 +1737,7 @@ code:Layer for all output vertices of a given primitive.
If the code:Layer value is less than 0 or greater than or equal to the
number of layers in the framebuffer, then primitives may: still be
rasterized, fragment shaders may: be executed, and the framebuffer values
for all layers are undefined.
for all layers are undefined:.
+
The code:Layer decoration must: be used only within
ifdef::VK_NV_viewport_array2,VK_EXT_shader_viewport_index_layer[]
@ -2007,7 +2007,7 @@ point being rasterized, normalized to the size of the point with origin in
the upper left corner of the point, as described in
<<primsrast-points-basic,Basic Point Rasterization>>.
If the primitive the fragment shader invocation belongs to is not a point,
then the variable decorated with code:PointCoord contains an undefined
then the variable decorated with code:PointCoord contains an undefined:
value.
+
The code:PointCoord decoration must: be used only within fragment shaders.
@ -2416,7 +2416,7 @@ explicitly, to be no larger than the implementation-dependent maximum
sample-mask (as an array of 32-bit elements), determined by the maximum
number of samples.
If a fragment shader entry point's interface includes an output variable
decorated with code:SampleMask, the sample mask will be undefined for any
decorated with code:SampleMask, the sample mask will be undefined: for any
array elements of any fragment shader invocations that fail to assign a
value.
If a fragment shader entry point's interface does not include an output
@ -2450,7 +2450,7 @@ code:Input storage class.
ifdef::VK_EXT_sample_locations[]
If the current pipeline uses <<primrast-samplelocations, custom sample
locations>> the value of any variable decorated with the code:SamplePosition
built-in decoration is undefined.
built-in decoration is undefined:.
endif::VK_EXT_sample_locations[]
+
The variable decorated with code:SamplePosition must: be declared as a
@ -2902,7 +2902,7 @@ viewport transform, scissor rectangle, and exclusive
endif::VK_NV_scissor_exclusive[]
scissor rectangle, for each view.
The same values must: be written to all vertices in a given primitive, or
else the set of viewports used for that primitive is undefined.
else the set of viewports used for that primitive is undefined:.
+
Any variable decorated with code:ViewportMaskPerViewNV must: be declared as
an array of scalar 32-bit integers with at least as many elements as the

View File

@ -85,8 +85,8 @@ in this Specification.
*Cannot* means something the application literally is unable to express or
accomplish through the API, while *must not* means something that the
application is capable of expressing through the API, but that the
consequences of doing so are undefined and potentially unrecoverable for the
implementation.
consequences of doing so are undefined: and potentially unrecoverable for
the implementation.
==================
Unless otherwise noted in the section heading, all sections and appendices

View File

@ -159,7 +159,7 @@ pname:size bytes, and the contents of the original allocation from bytes
zero to [eq]#min(original size, new size) - 1# must: be preserved in the
returned allocation.
If pname:size is larger than the old size, the contents of the additional
space are undefined.
space are undefined:.
If satisfying these requirements involves creating a new allocation, then
the old allocation should: be freed.
@ -837,10 +837,10 @@ different types (with potentially different alignment requirements) in the
same memory object.
ifndef::VK_VERSION_1_1[]
When memory is allocated, its contents are undefined.
When memory is allocated, its contents are undefined:.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
When memory is allocated, its contents are undefined with the following
When memory is allocated, its contents are undefined: with the following
constraint:
* The contents of unprotected memory must: not be a function of data
@ -2261,7 +2261,7 @@ object is no longer in use by the device--for example by command buffers in
the _pending state_.
The memory can: remain bound to images or buffers at the time the memory
object is freed, but any further use of them (on host or device) for
anything other than destroying those objects will result in undefined
anything other than destroying those objects will result in undefined:
behavior.
If there are still any bound images or buffers, the memory may: not be
immediately released by the implementation, but must: be released by the
@ -2488,7 +2488,7 @@ available to the host memory domain using the ename:VK_ACCESS_HOST_WRITE_BIT
and ename:VK_ACCESS_HOST_READ_BIT <<synchronization-access-types, access
types>>, are made visible to the host.
If a range of non-coherent memory is written by the host and then
invalidated without first being flushed, its contents are undefined.
invalidated without first being flushed, its contents are undefined:.
Within each range described by pname:pMemoryRanges, each set of
pname:nonCoherentAtomSize bytes in that range is invalidated if any byte in
@ -2665,20 +2665,21 @@ Protected memory adds the following concepts:
** Unprotected queue operations
*** Any read from or write to protected memory during unprotected queue
operations results in undefined behavior but is subject to the
operations results in undefined: behavior but is subject to the
inviolable rules below.
** Protected queue operations
*** Any write to unprotected memory during protected queue operations
results in undefined behavior but is subject to the inviolable rules
results in undefined: behavior but is subject to the inviolable rules
below.
*** Except for framebuffer-space pipeline stages, compute shader stage,
and transfer stage, any read from or write to protected memory during
protected queue operations results in undefined behavior but is
protected queue operations results in undefined: behavior but is
subject to the inviolable rules below.
*** Any queries during protected queue operations results in undefined
behavior but is subject to the inviolable rules below.
*** Any query during protected queue operations results in undefined:
behavior, but is subject to the inviolable rules below.
[[memory-protected-memory-undefined]]
==== Protected memory inviolable rules
@ -2693,7 +2694,7 @@ The implementation must: guarantee that:
data from protected memory.
Incorrect usage by an application of the memory protection system results in
undefined behavior which may: include process termination or device loss.
undefined: behavior which may: include process termination or device loss.
endif::VK_VERSION_1_1[]
ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[]

View File

@ -84,12 +84,11 @@ Actual ordering guarantees between pipeline stages are explained in detail
in the <<synchronization-pipeline-stages-order, synchronization chapter>>.
[[pipelines-block-diagram]]
[%inline]
ifndef::VK_NV_mesh_shader[]
image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center"]
image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"]
endif::VK_NV_mesh_shader[]
ifdef::VK_NV_mesh_shader[]
image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center"]
image::images/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center",opts="{imageopts}"]
endif::VK_NV_mesh_shader[]
Each pipeline is controlled by a monolithic object created from a
@ -1155,10 +1154,8 @@ fixed-function stages of the pipeline are skipped.
If a geometry shader is omitted, the geometry shading stage is skipped.
If a fragment shader is omitted, the results of fragment processing are
undefined.
Specifically, any fragment color outputs are considered to have undefined
values, and the fragment depth is considered to be unmodified.
If a fragment shader is omitted, fragment color outputs have undefined:
values, and the fragment depth value is unmodified.
This can: be useful for depth-only rendering.
Presence of a shader stage in a pipeline is indicated by including a valid
@ -1881,17 +1878,17 @@ parameter:
pipeline object, then that command buffer state is not disturbed.
* If the state is specified as dynamic in the new pipeline object but is
not specified as dynamic in the previous pipeline object, then that
command buffer state becomes undefined.
If the state is an array, then the entire array becomes undefined.
command buffer state becomes undefined:.
If the state is an array, then the entire array becomes undefined:.
* If the state is an array specified as dynamic in both the new and the
previous pipeline object, and the array size is not the same in both
pipeline objects, then that command buffer state becomes undefined.
pipeline objects, then that command buffer state becomes undefined:.
Dynamic state setting commands must: not be issued for state that is not
specified as dynamic in the bound pipeline object.
Dynamic state that does not affect the result of operations can: be left
undefined.
undefined:.
[NOTE]
.Note

View File

@ -428,8 +428,7 @@ instructions enabling the application to get direct access to the fragment
mask and the individual color fragment values.
[[vk-amd-shader-fragment-mask-diagram]]
[%inline]
image::images/fragment_mask.svg[align="center",title="Fragment Mask",align="center"]
image::images/fragment_mask.svg[align="center",title="Fragment Mask",align="center",opts="{imageopts}"]
endif::VK_AMD_shader_fragment_mask[]
@ -1306,8 +1305,7 @@ code:PointSize written by:
and clamped to the implementation-dependent point size range
[eq]#[pname:pointSizeRange[0],pname:pointSizeRange[1]]#.
If the value written to code:PointSize is less than or equal to zero, or if
no value was written to code:PointSize, results are undefined.
The value written to code:PointSize must: be greater than zero.
Not all point sizes need be supported, but the size 1.0 must: be supported.
The range of supported sizes and the size of evenly-spaced gradations within
@ -1518,8 +1516,7 @@ triangles where each pair of vertices at each end of the line has identical
attributes.
[[fig-non-strict-lines]]
[%inline]
image::images/non_strict_lines.svg[align="center",title="Non strict lines"]
image::images/non_strict_lines.svg[align="center",title="Non strict lines",opts="{imageopts}"]
[[primsrast-polygons]]
@ -1870,7 +1867,7 @@ triangle, where the depth is extrapolated.
endif::VK_NV_fill_rectangle[]
If no depth buffer is present, [eq]#r# is undefined.
If no depth buffer is present, [eq]#r# is undefined:.
The bias value [eq]#o# for a polygon is

View File

@ -160,7 +160,7 @@ Each query in a query pool has a status that is either _unavailable_ or
_available_, and also has state to store the numerical results of a query
operation of the type requested when the query pool was created.
Resetting a query via flink:vkCmdResetQueryPool sets the status to
unavailable and makes the numerical results undefined.
unavailable and makes the numerical results undefined:.
Performing a query operation with flink:vkCmdBeginQuery and
flink:vkCmdEndQuery changes the status to available when the query
<<queries-operation-finished,finishes>>, and updates the numerical results.
@ -178,10 +178,10 @@ flink:vkCmdCopyQueryPoolResults does not include
ename:VK_QUERY_RESULT_WAIT_BIT, execution of flink:vkCmdCopyQueryPoolResults
may: happen-before the results of flink:vkCmdEndQuery are available.
After query pool creation, each query is in an undefined state and must: be
After query pool creation, each query is in an undefined: state and must: be
reset prior to use.
Queries must: also be reset between uses.
Using a query that has not been reset will result in undefined behavior.
Using a query that has not been reset will result in undefined: behavior.
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
@ -436,7 +436,7 @@ In either case, the layout in memory is defined as follows:
Timestamps write one integer value.
* If more than one query is retrieved and pname:stride is not at least as
large as the size of the array of integers corresponding to a single
query, the values written to memory are undefined.
query, the values written to memory are undefined:.
[open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos']
--
@ -787,8 +787,8 @@ While the query is active, the pipeline type determines which set of
statistics are available, but these must: be configured on the query pool
when it is created.
If a statistic counter is issued on a command buffer that does not support
the corresponding operation, that counter is undefined after the query has
finished.
the corresponding operation, the value of that counter is undefined: after
the query has finished.
At least one statistic counter relevant to the operations supported on the
recording command buffer must: be enabled.

View File

@ -350,7 +350,7 @@ Correlation masks must: not have a functional effect on the results of the
multiview rendering.
When multiview is enabled, at the beginning of each subpass all non-render
pass state is undefined.
pass state is undefined:.
In particular, each time flink:vkCmdBeginRenderPass or
flink:vkCmdNextSubpass is called the graphics pipeline must: be bound, any
relevant descriptor sets or vertex/index buffers must: be bound, and any
@ -657,7 +657,7 @@ include::../api/enums/VkAttachmentLoadOp.txt[]
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
* ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE specifies that the previous
contents within the area need not be preserved; the contents of the
attachment will be undefined inside the render area.
attachment will be undefined: inside the render area.
For attachments with a depth/stencil format, this uses the access type
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
For attachments with a color format, this uses the access type
@ -682,7 +682,7 @@ include::../api/enums/VkAttachmentStoreOp.txt[]
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
* ename:VK_ATTACHMENT_STORE_OP_DONT_CARE specifies the contents within the
render area are not needed after rendering, and may: be discarded; the
contents of the attachment will be undefined inside the render area.
contents of the attachment will be undefined: inside the render area.
For attachments with a depth/stencil format, this uses the access type
ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
For attachments with a color format, this uses the access type
@ -740,7 +740,7 @@ The precise set of valid scenarios is described in more detail
If a set of attachments alias each other, then all except the first to be
used in the render pass must: use an pname:initialLayout of
ename:VK_IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases
make their contents undefined.
make their contents undefined:.
Once an alias has been used and a different alias has been used after it,
the first alias must: not be used in any later subpasses.
However, an application can: assign the same image view to multiple aliasing
@ -820,8 +820,8 @@ include::../api/structs/VkSubpassDescription.txt[]
used by a subpass, but whose contents must: be preserved throughout the
subpass.
The contents of an attachment within the render area become undefined at the
start of a subpass *S* if all of the following conditions are true:
The contents of an attachment within the render area become undefined: at
the start of a subpass *S* if all of the following conditions are true:
* The attachment is used as a color, depth/stencil, or resolve attachment
in any subpass in the render pass.
@ -829,8 +829,8 @@ start of a subpass *S* if all of the following conditions are true:
subpass dependency from *S~1~* to *S*.
* The attachment is not used or preserved in subpass *S*.
Once the contents of an attachment become undefined in subpass *S*, they
remain undefined for subpasses in subpass dependency chains starting with
Once the contents of an attachment become undefined: in subpass *S*, they
remain undefined: for subpasses in subpass dependency chains starting with
subpass *S* until they are written again.
However, they remain valid for subpasses in other subpass dependency chains
starting with subpass *S~1~* if those subpasses use or preserve the
@ -1338,7 +1338,7 @@ If no sample locations state has been specified for an automatic layout
transition performed on an attachment referring to a depth/stencil image
created with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
the contents of the depth aspect of the depth/stencil attachment become
undefined as if the layout of the attachment was transitioned from the
undefined: as if the layout of the attachment was transitioned from the
ename:VK_IMAGE_LAYOUT_UNDEFINED layout.
endif::VK_EXT_sample_locations[]
@ -2430,9 +2430,7 @@ restricted to the pixels whose x and y coordinates fall within the render
area on all attachments.
The render area extends to all layers of pname:framebuffer.
The application must: ensure (using scissor if necessary) that all rendering
is contained within the render area, otherwise the pixels outside of the
render area become undefined and shader side effects may: occur for
fragments outside the render area.
is contained within the render area.
The render area must: be contained within the framebuffer dimensions.
ifdef::VK_VERSION_1_1,VK_KHR_multiview[]

View File

@ -1786,7 +1786,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
However, the subresource layout of images in Android hardware buffer
external memory is not known until the image has been bound to memory, so
calling fname:vkGetImageSubresourceLayout for such an image before it has
been bound will result in undefined behavior.
been bound will result in undefined: behavior.
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
.Valid Usage
@ -1923,7 +1923,8 @@ adjacent slices of a 3D image.
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;
---------------------------------------------------
pname:arrayPitch is undefined for images that were not created as arrays.
The value of pname:arrayPitch is undefined: for images that were not created
as arrays.
pname:depthPitch is defined only for 3D images.
If the image has a
@ -2257,7 +2258,7 @@ If it is ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can: be
preinitialized by the host while using this layout, and the transition away
from this layout will preserve that data.
If it is ename:VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are
considered to be undefined, and the transition away from this layout is not
considered to be undefined:, and the transition away from this layout is not
guaranteed to preserve that data.
For either of these initial layouts, any image subresources must: be
transitioned to another layout before they are accessed by the device.
@ -2437,21 +2438,21 @@ subresource as a depth/stencil attachment, thus applications must: provide
the same sample locations that were last used to render to the given image
subresource whenever a layout transition of the image subresource happens,
otherwise the contents of the depth aspect of the image subresource become
undefined.
undefined:.
In addition, depth reads from a depth/stencil attachment referring to an
image subresource range of a depth/stencil image created with
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
different sample locations than what have been last used to perform depth
writes to the image subresources of the same image subresource range produce
undefined results.
writes to the image subresources of the same image subresource range return
undefined: values.
Similarly, depth writes to a depth/stencil attachment referring to an image
subresource range of a depth/stencil image created with
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
different sample locations than what have been last used to perform depth
writes to the image subresources of the same image subresource range make
the contents of the depth aspect of those image subresources undefined.
the contents of the depth aspect of those image subresources undefined:.
endif::VK_EXT_sample_locations[]
@ -3134,7 +3135,7 @@ image array layer [eq]#(pname:baseArrayLayer {plus} i)# is face index
[eq]#(i mod 6)# of cube _i / 6_.
If the number of layers in the view, whether set explicitly in
pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a
multiple of 6, behavior when indexing the last cube is undefined.
multiple of 6, behavior when indexing the last cube is undefined:.
pname:aspectMask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT,
ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if
@ -3582,7 +3583,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
The precise size of images that will be bound to external Android hardware
buffer memory is unknown until the memory has been imported or allocated, so
calling flink:vkGetImageMemoryRequirements with such an image before it has
been bound to memory will result in undefined behavior.
been bound to memory will result in undefined: behavior.
When importing Android hardware buffer memory, the pname:allocationSize can:
be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID.
When allocating new memory for an image that can: be exported to an Android
@ -4963,7 +4964,7 @@ A queue family can: take ownership of an image subresource or buffer range
of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an
ownership transfer, in the same way as for a resource that was just created;
however, taking ownership in this way has the effect that the contents of
the image subresource or buffer range are undefined.
the image subresource or buffer range are undefined:.
Ranges of buffers and image subresources of image objects created using
ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the
@ -5020,12 +5021,13 @@ identical images that alias the same range of an underlying memory object
affect the layout of all the subresources in the set.
As a corollary, writes to any image subresources in such a set must: not
make the contents of memory used by other subresources in the set undefined.
make the contents of memory used by other subresources in the set
undefined:.
An application can: define the content of a subresource of one image by
performing device writes to an identical subresource of another image
provided both images are bound to the same region of external memory.
Applications may: also add resources to such a set after the content of the
existing set members has been defined without making the content undefined
existing set members has been defined without making the content undefined:
by creating a new image with the initial layout
ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of
external memory as the existing images.
@ -5036,13 +5038,13 @@ external memory as the existing images.
Because layout transitions apply to all identical images aliasing the same
region of external memory, the actual layout of the memory backing a new
image as well as an existing image with defined content will not be
undefined.
undefined:.
Such an image is not usable until it acquires ownership of its memory from
the existing owner.
Therefore, the layout specified as part of this transition will be the true
initial layout of the image.
The undefined layout specified when creating it is a placeholder to simplify
valid usage requirements.
The undefined: layout specified when creating it is a placeholder to
simplify valid usage requirements.
====
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
@ -5164,25 +5166,25 @@ endif::VK_VERSION_1_1,VK_KHR_external_memory[]
Otherwise, the aliases interpret the contents of the memory differently, and
writes via one alias make the contents of memory partially or completely
undefined to the other alias.
undefined: to the other alias.
If the first alias is a host-accessible subresource, then the bytes affected
are those written by the memory operations according to its addressing
scheme.
If the first alias is not host-accessible, then the bytes affected are those
overlapped by the image subresources that were written.
If the second alias is a host-accessible subresource, the affected bytes
become undefined.
become undefined:.
If the second alias is a not host-accessible, all sparse image blocks (for
sparse partially-resident images) or all image subresources (for non-sparse
image and fully resident sparse images) that overlap the affected bytes
become undefined.
become undefined:.
If any image subresources are made undefined due to writes to an alias, then
each of those image subresources must: have its layout transitioned from
ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or from
ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by the
host.
If any sparse blocks of a sparse image have been made undefined, then only
If any image subresources are made undefined: due to writes to an alias,
then each of those image subresources must: have its layout transitioned
from ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or
from ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by
the host.
If any sparse blocks of a sparse image have been made undefined:, then only
the image subresources containing them must: be transitioned.
Use of an overlapping range by two aliases must: be separated by a memory

View File

@ -199,14 +199,14 @@ simultaneously.
Further, invocations of a single shader produced as the result of different
commands may: execute simultaneously.
The relative execution order of invocations of the same shader type is
undefined.
undefined:.
Shader invocations may: complete in a different order than that in which the
primitives they originated from were drawn or dispatched by the application.
However, fragment shader outputs are written to attachments in
<<primrast-order,rasterization order>>.
The relative order of invocations of different shader types is largely
undefined.
The relative execution order of invocations of different shader types is
largely undefined:.
However, when invoking a shader whose inputs are generated from a previous
pipeline stage, the shader invocations from the previous stage are
guaranteed to have executed far enough to generate input values for all
@ -217,10 +217,10 @@ required inputs.
== Shader Memory Access Ordering
The order in which image or buffer memory is read or written by shaders is
largely undefined.
largely undefined:.
For some shader types (vertex, tessellation evaluation, and in some cases,
fragment), even the number of shader invocations that may: perform loads and
stores is undefined.
stores is undefined:.
In particular, the following rules apply:
@ -230,15 +230,16 @@ In particular, the following rules apply:
in those sections.
* <<shaders-fragment-execution,Fragment>> shaders will be invoked zero or
more times, as defined in that section.
* The relative order of invocations of the same shader type are undefined.
* The relative execution order of invocations of the same shader type is
undefined:.
A store issued by a shader when working on primitive B might complete
prior to a store for primitive A, even if primitive A is specified prior
to primitive B. This applies even to fragment shaders; while fragment
shader outputs are always written to the framebuffer in
<<primrast-order, rasterization order>>, stores executed by fragment
shader invocations are not.
* The relative order of invocations of different shader types is largely
undefined.
* The relative execution order of invocations of different shader types is
largely undefined:.
[NOTE]
.Note
@ -295,7 +296,7 @@ Reads that are the result of shader loads through a variable decorated with
code:Coherent automatically have available writes to the same buffer, buffer
view, or image view made visible to them.
The order that coherent writes to different locations become available is
undefined, unless enforced by a memory barrier instruction or other memory
undefined:, unless enforced by a memory barrier instruction or other memory
dependency.
[NOTE]
@ -308,7 +309,7 @@ and visibility for access via other buffers, buffer views, or image views.
The built-in atomic memory transaction instructions can: be used to read and
write a given memory address atomically.
While built-in atomic functions issued by multiple shader invocations are
executed in undefined order relative to each other, these functions perform
executed in undefined: order relative to each other, these functions perform
both a read and a write of a memory address and guarantee that no other
memory transaction will write to the underlying memory between the read and
write.
@ -506,12 +507,12 @@ shader.
Each invocation of the tessellation control shader can: read the attributes
of any incoming vertices and their associated data.
The invocations corresponding to a given patch execute logically in
parallel, with undefined relative execution order.
parallel, with undefined: relative execution order.
However, the code:OpControlBarrier instruction can: be used to provide
limited control of the execution order by synchronizing invocations within a
patch, effectively dividing tessellation control shader execution into a set
of phases.
Tessellation control shaders will read undefined values if one invocation
Tessellation control shaders will read undefined: values if one invocation
reads a per-vertex or per-patch attribute written by another invocation at
any point during the same phase, or if two invocations attempt to write
different values to the same per-patch output in a single phase.
@ -620,7 +621,7 @@ for the purposes of evaluating derivatives for use in non-helper fragment
shader invocations.
Stores and atomics performed by helper invocations must: not have any effect
on memory, and values returned by atomic instructions in helper invocations
are undefined.
are undefined:.
[[shaders-fragment-earlytest]]
@ -810,8 +811,9 @@ including any helper invocations generated by that primitive.
ifdef::VK_NV_compute_shader_derivatives[]
A derivative group for a compute shader is a single local workgroup.
endif::VK_NV_compute_shader_derivatives[]
Derivatives are undefined for a sampled image instruction if the instruction
is in flow control that is not uniform across the derivative group.
Derivatives are undefined: for a sampled image instruction if the
instruction is in flow control that is not uniform across the derivative
group.
ifdef::VK_VERSION_1_1[]
[[shaders-subgroup]]

View File

@ -68,7 +68,7 @@ slink:VkPhysicalDeviceFeatures.
resource are well defined and behave as if the data bound is populated
with all zeros; writes are discarded.
When this property is absent, accesses are considered safe, but reads
will return undefined values.
will return undefined: values.
** Requested via the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT and
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bits.
** [[features-features-sparseResidency]] Sparse residency support is
@ -199,7 +199,7 @@ implementation:
* pname:residencyNonResidentStrict
If this property is not present, reads of unbound regions of the image will
return undefined values.
return undefined: values.
Both reads and writes are still considered _safe_ and will not affect other
resources or populated regions of the image.
@ -228,9 +228,9 @@ unbound regions.
Reads and writes to unbound regions will access the implementation-managed
memory instead.
Given that reads of unbound regions are undefined in this scenario,
implementations may: use the same physical memory for all unbound regions of
multiple resources within the same process.
Given that the values resulting from reads of unbound regions are undefined:
in this scenario, implementations may: use the same physical memory for all
unbound regions of multiple resources within the same process.
****
endif::implementation-guide[]
@ -278,8 +278,7 @@ ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and
ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT alter memory usage and
requirements.
[%inline]
image::images/sparseimage.svg[align="center", title="Sparse Image"]
image::images/sparseimage.svg[align="center",title="Sparse Image",opts="{imageopts}"]
In the absence of ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and
ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, each array layer contains a
@ -293,14 +292,12 @@ used sparse blocks.
Any bound partially-used-sparse-blocks must: still have their full sparse
block size in bytes allocated in memory.
[%inline]
image::images/sparseimage_singlemiptail.svg[align="center", title="Sparse Image with Single Mip Tail"]
image::images/sparseimage_singlemiptail.svg[align="center",title="Sparse Image with Single Mip Tail",opts="{imageopts}"]
When ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is present all array
layers will share a single mip tail region.
[%inline]
image::images/sparseimage_alignedmipsize.svg[align="center", title="Sparse Image with Aligned Mip Size"]
image::images/sparseimage_alignedmipsize.svg[align="center",title="Sparse Image with Aligned Mip Size",opts="{imageopts}"]
[NOTE]
.Note
@ -320,8 +317,7 @@ Only the first [eq]#N# mip levels whose dimensions are an exact multiple of
the sparse image block dimensions can: be bound and unbound on a sparse
block basis.
[%inline]
image::images/sparseimage_alignedmipsize_singlemiptail.svg[align="center", title="Sparse Image with Aligned Mip Size and Single Mip Tail"]
image::images/sparseimage_alignedmipsize_singlemiptail.svg[align="center",title="Sparse Image with Aligned Mip Size and Single Mip Tail",opts="{imageopts}"]
[NOTE]
.Note
@ -436,8 +432,7 @@ memory allocation for implementation-private _metadata_ associated with the
image.
See the figure below:
[%inline]
image::images/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect Sparse Image"]
image::images/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect Sparse Image",opts="{imageopts}"]
[NOTE]
.Note
@ -488,7 +483,7 @@ memory.
Memory dependencies must: be used to separate writes to one alias from reads
or writes to another alias.
Writes to aliased memory that are not properly guarded against accesses to
different aliases will have undefined results for all accesses to the
different aliases will have undefined: results for all accesses to the
aliased memory.
Applications that wish to make use of data consistent sparse memory aliasing
@ -566,7 +561,7 @@ Any pages that the application does not bind to memory may: be bound to one
Given the following properties:
* A process must: not access memory from another process
* Reads return undefined values
* Reads return undefined: values
It is sufficient for each host process to allocate these dummy pages and use
them for all resources in that process.
@ -1107,7 +1102,7 @@ include::../api/structs/VkSparseImageMemoryRequirements.txt[]
* pname:imageMipTailStride is the offset stride between each array-layer's
mip tail, if pname:formatProperties.flags does not contain
ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT (otherwise the value is
undefined).
undefined:).
include::../validity/structs/VkSparseImageMemoryRequirements.txt[]
--
@ -1246,7 +1241,7 @@ It is important to note that freeing a sname:VkDeviceMemory object with
fname:vkFreeMemory will not cause resources (or resource regions) bound to
the memory object to become unbound.
Access to resources that are bound to memory objects that have been freed
will result in undefined behavior, potentially including application
will result in undefined: behavior, potentially including application
termination.
Implementations must: ensure that no access to physical memory owned by the
@ -1261,7 +1256,7 @@ ename:VK_QUEUE_SPARSE_BINDING_BIT bit.
Applications must: use <<synchronization,synchronization primitives>> to
guarantee that other queues do not access ranges of memory concurrently with
a binding change.
Accessing memory in a range while it is being rebound results in undefined
Accessing memory in a range while it is being rebound results in undefined:
behavior.
It is valid to access other ranges of the same resource while a bind
operation is executing.

View File

@ -190,7 +190,7 @@ Write-after-read hazards can be solved with just an execution dependency,
but read-after-write and write-after-write hazards need appropriate memory
dependencies to be included between them.
If an application does not include dependencies to solve these hazards, the
results and execution orders of memory accesses are undefined.
results and execution orders of memory accesses are undefined:.
====
@ -1747,7 +1747,7 @@ Other than these non-deterministic results, behavior is well defined.
In particular:
* The implementation must: not crash or enter an internally inconsistent
state where future valid Vulkan commands might cause undefined results,
state where future valid Vulkan commands might cause undefined: results,
* Timeouts on future wait commands on fences sharing the payload must: be
effective.
@ -2477,7 +2477,7 @@ Unlike fences or events, the act of waiting for a semaphore also unsignals
that semaphore.
If two operations are separately specified to wait for the same semaphore,
and there are no other execution dependencies between those operations,
behaviour is undefined.
behaviour is undefined:.
An execution dependency must: be present that guarantees that the semaphore
unsignal operation for the first of those waits, happens-before the
semaphore is signalled again, and before the second unsignal operation.
@ -2645,7 +2645,7 @@ to one or more of the following:
* Continuing execution of the violating command or operation as if the
semaphore wait completed successfully after an implementation-dependent
timeout.
In this case, the state of the payload becomes undefined, and future
In this case, the state of the payload becomes undefined:, and future
operations on semaphores sharing the payload will be subject to these
same rules.
The semaphore must: be destroyed or have its payload replaced by an
@ -3541,7 +3541,8 @@ framebuffer-space>> pipeline stages is
feature is not enabled, pname:dstStageMask must: not contain
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
* [[VUID-vkCmdPipelineBarrier-pDependencies-02285]]
If fname:vkCmdPipelineBarrier is called within a render pass instance,
the render pass must: have been created with at least one
sname:VkSubpassDependency instance in
sname:VkRenderPassCreateInfo::pname:pDependencies that expresses a
@ -3553,8 +3554,8 @@ framebuffer-space>> pipeline stages is
equal to sname:VkSubpassDependency::pname:dependencyFlags,
pname:srcAccessMask member of each each element of pname:pMemoryBarriers
and pname:pImageMemoryBarriers contains a subset of the bit values in
sname:VkSubpassDependency::pname:srcAccessMask, and
pname:dstAccessMask member of each element of pname:pMemoryBarriers and
sname:VkSubpassDependency::pname:srcAccessMask, and pname:dstAccessMask
member of each element of pname:pMemoryBarriers and
pname:pImageMemoryBarriers contains a subset of the bit values in
sname:VkSubpassDependency::pname:dstAccessMask
* [[VUID-vkCmdPipelineBarrier-bufferMemoryBarrierCount-01178]]
@ -3998,7 +3999,7 @@ sname:VkImageMemoryBarrier does not match the sample location state last
used to render to the image subresource range specified by
pname:subresourceRange or if no sname:VkSampleLocationsInfoEXT structure is
in the pname:pNext chain of sname:VkImageMemoryBarrier then the contents of
the given image subresource range becomes undefined as if pname:oldLayout
the given image subresource range becomes undefined: as if pname:oldLayout
would equal ename:VK_IMAGE_LAYOUT_UNDEFINED.
endif::VK_EXT_sample_locations[]
@ -4208,7 +4209,7 @@ endif::VK_EXT_queue_family_foreign[]
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
If memory dependencies are correctly expressed between uses of such a
resource between two queues in different families, but no ownership transfer
is defined, the contents of that resource are undefined for any read
is defined, the contents of that resource are undefined: for any read
accesses performed by the second queue family.
[NOTE]
@ -4277,9 +4278,9 @@ The acquire operation happens-before the visibility operation.
Whilst it is not invalid to provide destination or source access masks for
memory barriers used for release or acquire operations, respectively, they
have no practical effect.
Access after a release operation has undefined results, and so visibility
Access after a release operation has undefined: results, and so visibility
for those accesses has no practical effect.
Similarly, write access before an acquire operation will produce undefined
Similarly, write access before an acquire operation will produce undefined:
results for future access, so availability of those writes has no practical
use.
In an earlier version of the specification, these were required to match on
@ -4312,10 +4313,10 @@ automatically made available.
Once a queue family has acquired ownership of a buffer range or image
subresource range of an ename:VK_SHARING_MODE_EXCLUSIVE resource, its
contents are undefined to other queue families unless ownership is
contents are undefined: to other queue families unless ownership is
transferred.
The contents of any portion of another resource which aliases memory that is
bound to the transferred buffer or image subresource range are undefined
bound to the transferred buffer or image subresource range are undefined:
after a release or acquire operation.

View File

@ -89,13 +89,11 @@ The domain space has an upper-left origin.
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
[[img-tessellation-topology-ul]]
[%inline]
image::images/tessparamUL.svg[align="center",title="Domain parameterization for tessellation primitive modes (upper-left origin)"]
image::images/tessparamUL.svg[align="center",title="Domain parameterization for tessellation primitive modes (upper-left origin)",opts="{imageopts}"]
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
[[img-tessellation-topology-ll]]
[%inline]
image::images/tessparam.svg[align="center",title="Domain parameterization for tessellation primitive modes (lower-left origin)"]
image::images/tessparam.svg[align="center",title="Domain parameterization for tessellation primitive modes (lower-left origin)",opts="{imageopts}"]
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
.Caption
@ -298,8 +296,7 @@ This subdivision process is illustrated in <<img-innertri,Inner Triangle
Tessellation>>.
[[img-innertri]]
[%inline]
image::images/innertri.svg[align="center",title="Inner Triangle Tessellation"]
image::images/innertri.svg[align="center",title="Inner Triangle Tessellation",opts="{imageopts}"]
.Caption
****
@ -409,8 +406,7 @@ This subdivision is illustrated in Figure <<img-innerquad,Inner Quad
Tessellation>>.
[[img-innerquad]]
[%inline]
image::images/innerquad.svg[align="center",title="Inner Quad Tessellation"]
image::images/innerquad.svg[align="center",title="Inner Quad Tessellation",opts="{imageopts}"]
.Caption
****

View File

@ -130,8 +130,7 @@ n is the sample index and is taken from the code:Sample image operand.
For all coordinate types, unused coordinates are assigned a value of zero.
[[textures-texel-coordinate-systems-diagrams]]
[%inline]
image::images/vulkantexture0.svg[align="center",title="Texel Coordinate Systems"]
image::images/vulkantexture0.svg[align="center",title="Texel Coordinate Systems",opts="{imageopts}"]
The Texel Coordinate Systems - For the example shown of an 8{times}4 texel
two dimensional image.
@ -172,8 +171,7 @@ the unnormalized coordinate space of the lower-resolution channels.
====
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[%inline]
image::images/vulkantexture1.svg[align="center",title="Texel Coordinate Systems"]
image::images/vulkantexture1.svg[align="center",title="Texel Coordinate Systems",opts="{imageopts}"]
The Texel Coordinate Systems - For the example shown of an 8{times}4 texel
two dimensional image.
@ -372,7 +370,7 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
_Texel input validation operations_ inspect instruction/image/sampler state
or coordinates, and in certain circumstances cause the texel value to be
replaced or become undefined.
replaced or become undefined:.
There are a series of validations that the texel undergoes.
@ -383,7 +381,7 @@ There are a number of cases where a SPIR-V instruction can: mismatch with
the sampler, the image view, or both.
There are a number of cases where the sampler can: mismatch with the image
view.
In such cases the value of the texel returned is undefined.
In such cases the value of the texel returned is undefined:.
These cases include:
@ -582,8 +580,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If all planes of a _disjoint_ _multi-planar_ image are not in the same
<<resources-image-layouts,image layout>> when the image is sampled with
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, the result of
texel reads is undefined.
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, the values
returned by texel reads are undefined:.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
@ -675,7 +673,7 @@ components in the image format
| Four component color format | [eq]#C~rgba~ = (B~r~,B~g~,B~b~,B~a~)#
|====
The value returned by a read of an invalid texel is undefined, unless that
The value returned by a read of an invalid texel is undefined:, unless that
read operation is from a buffer resource and the pname:robustBufferAccess
feature is enabled.
In that case, an invalid texel is replaced as described by the
@ -688,7 +686,7 @@ values for integer and floating-point components of the image format,
respectively.
If pname:residencyNonResidentStrict is ename:VK_FALSE, the value of the
sparse unbound texel is undefined.
sparse unbound texel is undefined:.
[[textures-depth-compare-operation]]
@ -815,7 +813,7 @@ If the border color is one of the etext:VK_BORDER_COLOR_*_OPAQUE_BLACK enums
and the elink:VkComponentSwizzle is not ename:VK_COMPONENT_SWIZZLE_IDENTITY
for all components (or the
<<resources-image-views-identity-mappings,equivalent identity mapping>>),
the value of the texel after swizzle is undefined.
the value of the texel after swizzle is undefined:.
[[textures-sparse-residency]]
@ -874,23 +872,17 @@ positions where required for interpolation.
The limits of a sample for etext:NEAREST sampling is shown as a grid.
====
[%inline]
image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN"]
image::images/chromasamples_422_cosited.svg[align="center",title="422 downsampling, xChromaOffset=COSITED_EVEN",opts="{imageopts}"]
[%inline]
image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT"]
image::images/chromasamples_422_midpoint.svg[align="center",title="422 downsampling, xChromaOffset=MIDPOINT",opts="{imageopts}"]
[%inline]
image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN"]
image::images/chromasamples_420_xcosited_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=COSITED_EVEN",opts="{imageopts}"]
[%inline]
image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN"]
image::images/chromasamples_420_xmidpoint_ycosited.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=COSITED_EVEN",opts="{imageopts}"]
[%inline]
image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT"]
image::images/chromasamples_420_xcosited_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=COSITED_EVEN, yChromaOffset=MIDPOINT",opts="{imageopts}"]
[%inline]
image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT"]
image::images/chromasamples_420_xmidpoint_ymidpoint.svg[align="center",title="420 downsampling, xChromaOffset=MIDPOINT, yChromaOffset=MIDPOINT",opts="{imageopts}"]
Reconstruction is implemented in one of two ways:
@ -1326,7 +1318,7 @@ Floating-point outputs are converted as described in
<<fundamentals-fixedconv,Fixed-Point Data Conversion>>.
Integer outputs are converted such that their value is preserved.
The converted value of any integer that cannot be represented in the target
format is undefined.
format is undefined:.
== Derivative Operations
@ -1339,8 +1331,7 @@ compute and
endif::VK_NV_compute_shader_derivatives[]
fragment shaders.
[%inline]
image::images/vulkantexture2.svg[align="center",title="Implicit Derivatives"]
image::images/vulkantexture2.svg[align="center",title="Implicit Derivatives",opts="{imageopts}"]
Derivatives are computed as if there is a 2{times}2 neighborhood of
fragments for each fragment shader invocation.
@ -1499,13 +1490,13 @@ For implicit derivative image instructions, the partial derivative values
may: be computed by linear approximation using a 2{times}2 neighborhood of
shader invocations (known as a _quad_), as described above.
If the instruction is in control flow that is not uniform across the quad,
then the derivative values and hence the implicit LOD values are undefined.
then the derivative values and hence the implicit LOD values are undefined:.
ifdef::VK_EXT_descriptor_indexing[]
If the image or sampler object used by an implicit derivative image
instruction is not uniform across the quad and
<<features-limits-quadDivergentImplicitLod,pname:quadDivergentImplicitLod>>
is not supported, then the derivative and LOD values are undefined.
is not supported, then the derivative and LOD values are undefined:.
Implicit derivatives are well-defined when the image and sampler and control
flow are uniform across the quad, even if they diverge between different
quads.
@ -2143,9 +2134,9 @@ d & = level_{base} +
If [eq]#d# does not lie in the range [eq]#[pname:baseMipLevel,
pname:baseMipLevel {plus} pname:levelCount)# then any values fetched are
ifndef::VK_AMD_shader_image_load_store_lod[undefined.]
ifndef::VK_AMD_shader_image_load_store_lod[undefined:.]
ifdef::VK_AMD_shader_image_load_store_lod[]
undefined, and any writes are discarded.
undefined:, and any writes are discarded.
endif::VK_AMD_shader_image_load_store_lod[]

View File

@ -203,7 +203,7 @@ If a geometry shader is active, the output primitive topology is either
points, line strips, or triangle strips, and the selection of the provoking
vertex behaves according to the corresponding row of the table.
If a tessellation evaluation shader is active and a geometry shader is not
active, the provoking vertex is undefined but must: be one of the vertices
active, the provoking vertex is undefined: but must: be one of the vertices
of the primitive.
@ -540,8 +540,8 @@ implementation-dependent vertex of each primitive.
If code:ViewportIndex is outside the range zero to pname:viewportCount minus
one for a primitive, or if the geometry shader did not assign a value to
code:ViewportIndex for all vertices of a primitive due to flow control, the
results of the viewport transformation of the vertices of such primitives
are undefined.
values resulting from the viewport transformation of the vertices of such
primitives are undefined:.
If no geometry shader is active, or if the geometry shader does not have an
output decorated with code:ViewportIndex, the viewport numbered zero is used
by the viewport transformation.
@ -563,8 +563,8 @@ If code:ViewportIndex or any of the bits in code:ViewportMaskNV are outside
the range zero to pname:viewportCount minus one for a primitive, or if the
last active vertex processing stage did not assign a value to either
code:ViewportIndex or code:ViewportMaskNV for all vertices of a primitive
due to flow control, the results of the viewport transformation of the
vertices of such primitives are undefined.
due to flow control, the values resulting from the viewport transformation
of the vertices of such primitives are undefined:.
If the last vertex processing stage does not have an output decorated with
code:ViewportIndex or code:ViewportMaskNV, the viewport numbered zero is
used by the viewport transformation.
@ -582,8 +582,8 @@ primitive.
If code:ViewportIndex is outside the range zero to pname:viewportCount minus
one for a primitive, or if the last active vertex processing stage did not
assign a value to code:ViewportIndex for all vertices of a primitive due to
flow control, the results of the viewport transformation of the vertices of
such primitives are undefined.
flow control, the values resulting from the viewport transformation of the
vertices of such primitives are undefined:.
If the last vertex processing stage does not have an output decorated with
code:ViewportIndex, the viewport numbered zero is used by the viewport
transformation.

View File

@ -42,6 +42,7 @@ def enQuote(str):
def makeTarget(outDir, extensionList, submitName, title, target):
print('make clean_generated')
print('make OUTDIR=' + outDir,
'IMAGEOPTS=',
'EXTENSIONS="' + ' '.join(extensionList) + '"',
'APITITLE="' + title + '"', target)
# Rename into submission directory

View File

@ -43,4 +43,5 @@ Asciidoctor::Extensions.register do
inline_macro CodeInlineMacro
inline_macro AttrInlineMacro
inline_macro TagInlineMacro
inline_macro UndefinedInlineMacro
end

View File

@ -219,3 +219,13 @@ class AttrInlineMacro < StrongInlineMacroBase
match /attr:(\w+)/
end
# Does nothing - just markup that we've considered the use case
class UndefinedInlineMacro < VulkanInlineMacroBase
named :undefined
match /undefined:/
def process parent, target, attributes
'undefined'
end
end

View File

@ -25,17 +25,17 @@ This Specification has been created under the Khronos Intellectual Property
Rights Policy, which is Attachment A of the Khronos Group Membership
Agreement available at www.khronos.org/files/member_agreement.pdf, and which
defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.
Parties desiring to implement the Specification and make use of Khronos trademarks
in relation to that implementation, and receive reciprocal patent license protection
under the Khronos Intellectual Property Rights Policy must become Adopters and
confirm the implementation as conformant under the process defined by Khronos for
Parties desiring to implement the Specification and make use of Khronos trademarks
in relation to that implementation, and receive reciprocal patent license protection
under the Khronos Intellectual Property Rights Policy must become Adopters and
confirm the implementation as conformant under the process defined by Khronos for
this Specification; see https://www.khronos.org/adopters.
This Specification contains substantially unmodified functionality from, and is a
successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.
Some parts of this Specification are purely informative and so are EXCLUDED from
the Scope of this Specification. The <<introduction-conventions>> section of the
the Scope of this Specification. The <<introduction-conventions>> section of the
<<introduction>> defines how these parts of the Specification are identified.
Where this Specification uses <<introduction-technical-terminology,technical
@ -60,8 +60,8 @@ implemented, are considered to be included as Compliant Portions.
Where this Specification includes <<introduction-normative-references,
normative references to external documents>>, only the specifically
identified sections of those external documents are INCLUDED in the Scope of
this Specification. If not created by Khronos, those external documents may
contain contributions from non-members of Khronos not covered by the Khronos
this Specification. If not created by Khronos, those external documents may
contain contributions from non-members of Khronos not covered by the Khronos
Intellectual Property Rights Policy.
ifndef::ratified_core_spec[]
@ -75,8 +75,9 @@ https://www.khronos.org/registry/vulkan/specs/1.1-khr_extensions/html/vkspec.htm
(core with KHR extensions).
endif::ratified_core_spec[]
Vulkan is a registered trademark, and Khronos is a trademark of The Khronos
Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of
Apple Inc.; and OpenGL is a registered trademark of Silicon Graphics International,
all used under license by Khronos. All other product names, trademarks, and/or
company names are used solely for identification and belong to their respective owners.
Vulkan and Khronos are registered trademarks of The Khronos Group Inc.
ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple
Inc.; and OpenGL is a registered trademark of Silicon Graphics
International, all used under license by Khronos. All other product names,
trademarks, and/or company names are used solely for identification and
belong to their respective owners.

View File

@ -24,6 +24,10 @@
#include "vulkan_android.h"
#endif
#ifdef VK_USE_PLATFORM_FUCHSIA
#include <zircon/types.h>
#include "vulkan_fuchsia.h"
#endif
#ifdef VK_USE_PLATFORM_IOS_MVK
#include "vulkan_ios.h"

View File

@ -43,7 +43,7 @@ extern "C" {
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff)
#define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff)
// Version of this file
#define VK_HEADER_VERSION 86
#define VK_HEADER_VERSION 87
#define VK_NULL_HANDLE 0
@ -443,6 +443,7 @@ typedef enum VkStructureType {
VK_STRUCTURE_TYPE_CHECKPOINT_DATA_NV = 1000206000,
VK_STRUCTURE_TYPE_QUEUE_FAMILY_CHECKPOINT_PROPERTIES_NV = 1000206001,
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_MEMORY_MODEL_FEATURES_KHR = 1000211000,
VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA = 1000214000,
VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,
VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO_KHR = VK_STRUCTURE_TYPE_RENDER_PASS_MULTIVIEW_CREATE_INFO,
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES,

View File

@ -0,0 +1,58 @@
#ifndef VULKAN_FUCHSIA_H_
#define VULKAN_FUCHSIA_H_ 1
#ifdef __cplusplus
extern "C" {
#endif
/*
** Copyright (c) 2015-2018 The Khronos Group Inc.
**
** Licensed under the Apache License, Version 2.0 (the "License");
** you may not use this file except in compliance with the License.
** You may obtain a copy of the License at
**
** http://www.apache.org/licenses/LICENSE-2.0
**
** Unless required by applicable law or agreed to in writing, software
** distributed under the License is distributed on an "AS IS" BASIS,
** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
** See the License for the specific language governing permissions and
** limitations under the License.
*/
/*
** This header is generated from the Khronos Vulkan XML API Registry.
**
*/
#define VK_FUCHSIA_imagepipe_surface 1
#define VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION 1
#define VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME "VK_FUCHSIA_imagepipe_surface"
typedef VkFlags VkImagePipeSurfaceCreateFlagsFUCHSIA;
typedef struct VkImagePipeSurfaceCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkImagePipeSurfaceCreateFlagsFUCHSIA flags;
zx_handle_t imagePipeHandle;
} VkImagePipeSurfaceCreateInfoFUCHSIA;
typedef VkResult (VKAPI_PTR *PFN_vkCreateImagePipeSurfaceFUCHSIA)(VkInstance instance, const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSurfaceKHR* pSurface);
#ifndef VK_NO_PROTOTYPES
VKAPI_ATTR VkResult VKAPI_CALL vkCreateImagePipeSurfaceFUCHSIA(
VkInstance instance,
const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
#endif
#ifdef __cplusplus
}
#endif
#endif

View File

@ -1,2 +1,2 @@
# The value to start tagging VU statements at, unless overridden by -nextvu
startVUID = 2285
startVUID = 2286

View File

@ -2,7 +2,7 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
= The Khronos Vulkan^(R)^ API Registry
= The Khronos^®^ Vulkan^®^ API Registry
Jon Leech
:data-uri:
:icons: font
@ -492,12 +492,15 @@ member.
generate validation code from the allowed length.
* attr:externsync - denotes that the member should be externally
synchronized when accessed by Vulkan
* attr:optional - a value of `"true"` or `"false"` determines whether this
* attr:optional - optional.
A value of `"true"` or `"false"` determines whether this
member can be omitted by providing `NULL` (for pointers),
`VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
that are the size of an array in the same structure. If the member
is a pointer to one of those types, multiple values may be provided,
separated by commas - one for each pointer indirection.
If not present, the value is assumed to be `"false"` (the member must
not be omitted).
* attr:noautovalidity - prevents automatic validity language being
generated for the tagged item. Only suppresses item-specific
validity - parenting issues etc. are still captured.
@ -890,12 +893,14 @@ members.
item count in attr:len list.
This attribute is intended to support consumers of the XML who need to
generate validation code from the allowed length.
* attr:optional - a value of `"true"` or `"false"` determines whether this
member can be omitted by providing `NULL` (for pointers),
* attr:optional - optional. A value of `"true"` or `"false"` determines whether this
parameter can be omitted by providing `NULL` (for pointers),
`VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
that are the size of an array in the same command. If the member is
that are the size of an array in the same command. If the parameter is
a pointer to one of those types, multiple values may be provided,
separated by commas - one for each pointer indirection.
separated by commas - one for each pointer indirection. If not present,
the value is assumed to be `"false"` (the parameter must not be
omitted).
* attr:noautovalidity - prevents automatic validity language being
generated for the tagged item. Only suppresses item-specific
validity - parenting issues etc. are still captured.
@ -2006,6 +2011,8 @@ files and Python scripts are logged in Github history.
[[changelog]]
= Change Log
* 2018-10-01 - Add description of the default value of attr:optional
member and parameter attributes, if not specified.
* 2018-08-28 - Add optional attr:provisional attribute to tag:extension
tags.
* 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and

View File

@ -348,17 +348,20 @@ and is added to the list of figures:
.Example Markup
----
[[fig-anchorname]]
[%inline]
image::images/imagename.svg[align="center",title="Figure caption",{fullimagewidth}]
image::images/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"]
----
There must be SVG versions of each figure checked into the `images/`
directory, to support generating both HTML and PDF outputs.
The PDF generation pipeline is now able to use SVG images, so PDF versions
of each image are no longer required.
The `[%inline]` directive decreases output image size in the generated HTML.
The `opts=` attribute defaults to `inline`, which decreases output image
size in the generated HTML.
However, the `inline` option interferes with generating HTML diffs between
two specifications with the script we currently use.
By using an asciidoctor attribute, this behavior can be controlled.
Asciidoc restricts captions in figures to be a single line in the source
Asciidoctor restricts captions in figures to be a single line in the source
document.
If a longer caption is required, follow the figure directive with a sidebar
block including the full caption preceded by a link to the figure:

View File

@ -192,6 +192,28 @@ the prefix from the word with a hyphen.
This list is not intended to be complete.
[[writing-undefined]]
== Describing Undefined Behavior
When describing undefined behavior, be clear about what is and is not
defined.
Do not write "`undefined results`" unless the effect of an operation is
truly completely undefined (up to and including termination of the
application, for example).
More often, what should be done is to say that the *values* of specified
variables, or the *contents* of specified memory, become undefined or
implementation-defined as a result of such operations.
Use the undefined{cl} macro to indicate that each use of the term
"`undefined`" has been carefully considered and accurately represents the
degree of undefined behavior allowed.
Any use of the word "`undefined`" without the trailing {cl} is suspect.
Note that this does not translate into visible markup in the output
document; it is simply markup to help track uses of the word.
[[writing-describing]]
== Describing Commands and Parameters

View File

@ -2,7 +2,7 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
= Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions
= Vulkan^®^ Documentation and Extensions: Procedures and Conventions
Jon Leech, Tobias Hector
:data-uri:
:icons: font
@ -31,8 +31,8 @@ include::copyright-ccby.txt[]
This document contains required procedures and conventions when writing
specifications for new Vulkan APIs, extensions and layers, or related
Khronos documentation such as white papers and tutorials; or contributing to
existing Vulkan specifications.
Khronos^{reg}^ documentation such as white papers and tutorials; or
contributing to existing Vulkan specifications.
These are collectively referred to as _Vulkan Documentation_ or just
_documentation_ below.
The primary focus is the API Specification and API extensions, although all
@ -152,6 +152,9 @@ include::style/vuid.txt[]
* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images,
Figures>> section (public pull request 734).
* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined
Behavior>> (as part of the fixes for public issue 379), and describing why
the undefined{cl} macro should always be used.
* 2018-07-08 - Remove requirement to explicitly include extension appendices
in the <<extensions-documenting-extensions, Changes for New Extensions>>
section.

View File

@ -2,8 +2,8 @@
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
= Vulkan^(R)^ {revnumber} - A Specification {apititle}
The Khronos Vulkan Working Group
= Vulkan^®^ {revnumber} - A Specification {apititle}
The Khronos^®^ Vulkan Working Group
:data-uri:
:icons: font
:toc2:

View File

@ -43,6 +43,7 @@ SRC = ../src
# Vulkan platform-specific headers
PLATFORM_HEADERS = \
$(VULKAN)/vulkan_android.h \
$(VULKAN)/vulkan_fuchsia.h \
$(VULKAN)/vulkan_ios.h \
$(VULKAN)/vulkan_macos.h \
$(VULKAN)/vulkan_mir.h \

View File

@ -254,6 +254,7 @@ def makeGenOpts(args):
[ 'vulkan_android.h', [ 'VK_KHR_android_surface',
'VK_ANDROID_external_memory_android_hardware_buffer'
], commonSuppressExtensions ],
[ 'vulkan_fuchsia.h', [ 'VK_FUCHSIA_imagepipe_surface'], commonSuppressExtensions ],
[ 'vulkan_ios.h', [ 'VK_MVK_ios_surface' ], commonSuppressExtensions ],
[ 'vulkan_macos.h', [ 'VK_MVK_macos_surface' ], commonSuppressExtensions ],
[ 'vulkan_mir.h', [ 'VK_KHR_mir_surface' ], commonSuppressExtensions ],

View File

@ -55,6 +55,7 @@ server.
<platform name="vi" protect="VK_USE_PLATFORM_VI_NN" comment="Nintendo Vi"/>
<platform name="ios" protect="VK_USE_PLATFORM_IOS_MVK" comment="Apple IOS"/>
<platform name="macos" protect="VK_USE_PLATFORM_MACOS_MVK" comment="Apple MacOS"/>
<platform name="fuchsia" protect="VK_USE_PLATFORM_FUCHSIA" comment="Fuchsia"/>
</platforms>
<tags comment="Vulkan vendor/author tags for extensions and layers">
@ -99,13 +100,14 @@ server.
<type category="include" name="wayland-client.h"/>
<type category="include" name="windows.h"/>
<type category="include" name="xcb/xcb.h"/>
<type category="include" name="zircon/types.h"/>
<comment>
In the current header structure, each platform's interfaces
are confined to a platform-specific header (vulkan_xlib.h,
vulkan_win32.h, etc.). These headers are not self-contained,
and should not include native headers (X11/Xlib.h,
windows.h, etc.). Code should either include vulkan.h after
defining the appropriate VK_USE_PLATFORM_platform_KHR
defining the appropriate VK_USE_PLATFORM_platform
macros, or include the required native headers prior to
explicitly including the corresponding platform header.
@ -133,6 +135,7 @@ server.
<type requires="xcb/xcb.h" name="xcb_connection_t"/>
<type requires="xcb/xcb.h" name="xcb_visualid_t"/>
<type requires="xcb/xcb.h" name="xcb_window_t"/>
<type requires="zircon/types.h" name="zx_handle_t"/>
<type category="define">#define <name>VK_MAKE_VERSION</name>(major, minor, patch) \
(((major) &lt;&lt; 22) | ((minor) &lt;&lt; 12) | (patch))</type>
@ -147,7 +150,7 @@ server.
<type category="define">// Vulkan 1.1 version number
#define <name>VK_API_VERSION_1_1</name> <type>VK_MAKE_VERSION</type>(1, 1, 0)// Patch version should always be set to 0</type>
<type category="define">// Version of this file
#define <name>VK_HEADER_VERSION</name> 86</type>
#define <name>VK_HEADER_VERSION</name> 87</type>
<type category="define">
#define <name>VK_DEFINE_HANDLE</name>(object) typedef struct object##_T* object;</type>
@ -270,6 +273,7 @@ server.
<type category="bitmask">typedef <type>VkFlags</type> <name>VkXcbSurfaceCreateFlagsKHR</name>;</type>
<type category="bitmask">typedef <type>VkFlags</type> <name>VkIOSSurfaceCreateFlagsMVK</name>;</type>
<type category="bitmask">typedef <type>VkFlags</type> <name>VkMacOSSurfaceCreateFlagsMVK</name>;</type>
<type category="bitmask">typedef <type>VkFlags</type> <name>VkImagePipeSurfaceCreateFlagsFUCHSIA</name>;</type>
<type requires="VkPeerMemoryFeatureFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkPeerMemoryFeatureFlags</name>;</type>
<type category="bitmask" name="VkPeerMemoryFeatureFlagsKHR" alias="VkPeerMemoryFeatureFlags"/>
<type requires="VkMemoryAllocateFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkMemoryAllocateFlags</name>;</type>
@ -1125,7 +1129,7 @@ server.
<member values="VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO"><type>VkStructureType</type> <name>sType</name></member>
<member>const <type>void</type>* <name>pNext</name></member>
<member optional="true"><type>VkPipelineDynamicStateCreateFlags</type> <name>flags</name></member>
<member><type>uint32_t</type> <name>dynamicStateCount</name></member>
<member optional="true"><type>uint32_t</type> <name>dynamicStateCount</name></member>
<member len="dynamicStateCount">const <type>VkDynamicState</type>* <name>pDynamicStates</name></member>
</type>
<type category="struct" name="VkStencilOpState">
@ -1677,6 +1681,12 @@ server.
<member noautovalidity="true"><type>xcb_connection_t</type>* <name>connection</name></member>
<member><type>xcb_window_t</type> <name>window</name></member>
</type>
<type category="struct" name="VkImagePipeSurfaceCreateInfoFUCHSIA">
<member values="VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA"><type>VkStructureType</type> <name>sType</name></member>
<member>const <type>void</type>* <name>pNext</name></member>
<member optional="true"><type>VkImagePipeSurfaceCreateFlagsFUCHSIA</type> <name>flags</name></member>
<member><type>zx_handle_t</type> <name>imagePipeHandle</name></member>
</type>
<type category="struct" name="VkSurfaceFormatKHR" returnedonly="true">
<member><type>VkFormat</type> <name>format</name><comment>Supported pair of rendering format</comment></member>
<member><type>VkColorSpaceKHR</type> <name>colorSpace</name><comment>and color space for the surface</comment></member>
@ -2776,10 +2786,10 @@ server.
</type>
<type category="struct" name="VkSampleLocationsInfoEXT" structextends="VkImageMemoryBarrier">
<member values="VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT"><type>VkStructureType</type> <name>sType</name></member>
<member>const <type>void</type>* <name>pNext</name></member>
<member><type>VkSampleCountFlagBits</type> <name>sampleLocationsPerPixel</name></member>
<member><type>VkExtent2D</type> <name>sampleLocationGridSize</name></member>
<member><type>uint32_t</type> <name>sampleLocationsCount</name></member>
<member>const <type>void</type>* <name>pNext</name></member>
<member optional="true"><type>VkSampleCountFlagBits</type> <name>sampleLocationsPerPixel</name></member>
<member><type>VkExtent2D</type> <name>sampleLocationGridSize</name></member>
<member optional="true"><type>uint32_t</type> <name>sampleLocationsCount</name></member>
<member len="sampleLocationsCount">const <type>VkSampleLocationEXT</type>* <name>pSampleLocations</name></member>
</type>
<type category="struct" name="VkAttachmentSampleLocationsEXT">
@ -5837,6 +5847,13 @@ server.
<param><type>xcb_connection_t</type>* <name>connection</name></param>
<param><type>xcb_visualid_t</type> <name>visual_id</name></param>
</command>
<command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY,VK_ERROR_OUT_OF_DEVICE_MEMORY">
<proto><type>VkResult</type> <name>vkCreateImagePipeSurfaceFUCHSIA</name></proto>
<param><type>VkInstance</type> <name>instance</name></param>
<param>const <type>VkImagePipeSurfaceCreateInfoFUCHSIA</type>* <name>pCreateInfo</name></param>
<param optional="true">const <type>VkAllocationCallbacks</type>* <name>pAllocator</name></param>
<param><type>VkSurfaceKHR</type>* <name>pSurface</name></param>
</command>
<command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY">
<proto><type>VkResult</type> <name>vkCreateDebugReportCallbackEXT</name></proto>
<param><type>VkInstance</type> <name>instance</name></param>
@ -7486,7 +7503,7 @@ server.
<command name="vkGetPhysicalDeviceWaylandPresentationSupportKHR"/>
</require>
</extension>
<extension name="VK_KHR_mir_surface" number="8" type="instance" requires="VK_KHR_surface" platform="mir" author="KHR" contact="Jesse Hall @critsec,Ian Elliott @ianelliottus" supported="vulkan">
<extension name="VK_KHR_mir_surface" number="8" type="instance" requires="VK_KHR_surface" platform="mir" author="KHR" contact="Jesse Hall @critsec,Ian Elliott @ianelliottus" obsoletedby="" supported="vulkan">
<require>
<enum value="4" name="VK_KHR_MIR_SURFACE_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_mir_surface&quot;" name="VK_KHR_MIR_SURFACE_EXTENSION_NAME"/>
@ -9743,10 +9760,14 @@ server.
<enum value="&quot;VK_KHR_extension_214&quot;" name="VK_KHR_EXTENSION_214_EXTENSION_NAME"/>
</require>
</extension>
<extension name="VK_GOOGLE_extension_215" number="215" author="GOOGLE" contact="Jesse Hall @critsec" supported="disabled">
<extension name="VK_FUCHSIA_imagepipe_surface" number="215" type="instance" author="FUCHSIA" requires="VK_KHR_surface" platform="fuchsia" contact="Craig Stout @cdotstout" supported="vulkan">
<require>
<enum value="0" name="VK_KHR_EXTENSION_215_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_extension_215&quot;" name="VK_KHR_EXTENSION_215_EXTENSION_NAME"/>
<enum value="1" name="VK_FUCHSIA_IMAGEPIPE_SURFACE_SPEC_VERSION"/>
<enum value="&quot;VK_FUCHSIA_imagepipe_surface&quot;" name="VK_FUCHSIA_IMAGEPIPE_SURFACE_EXTENSION_NAME"/>
<enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA"/>
<type name="VkImagePipeSurfaceCreateFlagsFUCHSIA"/>
<type name="VkImagePipeSurfaceCreateInfoFUCHSIA"/>
<command name="vkCreateImagePipeSurfaceFUCHSIA"/>
</require>
</extension>
<extension name="VK_GOOGLE_extension_216" number="216" author="GOOGLE" contact="Jesse Hall @critsec" supported="disabled">
@ -9883,8 +9904,8 @@ server.
</extension>
<extension name="VK_KHR_extension_237" number="237" author="KHR" contact="Jesse Hall @critsec" supported="disabled">
<require>
<enum value="0" name="VK_AMD_EXTENSION_237_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_extension_237&quot;" name="VK_AMD_EXTENSION_237_EXTENSION_NAME"/>
<enum value="0" name="VK_KHR_EXTENSION_237_SPEC_VERSION"/>
<enum value="&quot;VK_KHR_extension_237&quot;" name="VK_KHR_EXTENSION_237_EXTENSION_NAME"/>
</require>
</extension>
</extensions>