2016-02-16 09:53:44 +00:00
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[synchronization]]
= Synchronization and Cache Control
Synchronization of access to resources is primarily the responsibility of
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
the application in Vulkan.
The order of execution of commands with respect to the host and other
commands on the device has few implicit guarantees, and needs to be
explicitly specified.
Memory caches and other optimizations are also explicitly managed, requiring
that the flow of data through the system is largely under application
control.
Whilst some implicit guarantees exist between commands, four explicit
synchronization primitives are exposed by Vulkan:
<<synchronization-fences,Fences>>::
Fences can: be used to communicate to the host that execution of some
task on the device has completed.
<<synchronization-semaphores,Semaphores>>::
Semaphores can: be used to control resource access across multiple
queues.
<<synchronization-events,Events>>::
Events provide a fine-grained synchronization primitive which can: be
signaled either within a command buffer or by the host, and can: be
waited upon within a command buffer or queried on the host.
<<synchronization-pipeline-barriers,Pipeline Barriers>>::
Pipeline barriers also provide synchronization control within a command
buffer, but at a single point, rather than with separate signal and wait
operations.
In addition to the base primitives provided here, <<renderpass, Render
Passes>> provide a useful synchronization framework for most rendering
tasks, built upon the concepts in this chapter.
Many cases that would otherwise need an application to use synchronization
primitives in this chapter can: be expressed more efficiently as part of a
render pass.
[[synchronization-dependencies]]
== Execution and Memory Dependencies
An _operation_ is an arbitrary amount of work to be executed on the host, a
device, or an external entity such as a presentation engine.
Synchronization commands introduce explicit _execution dependencies_, and
_memory dependencies_ between two sets of operations defined by the
command's two _synchronization scopes_.
[[synchronization-dependencies-scopes]]
The synchronization scopes define which other operations a synchronization
command is able to create execution dependencies with.
Any type of operation that is not in a synchronization command's
synchronization scopes will not be included in the resulting dependency.
For example, for many synchronization commands, the synchronization scopes
can: be limited to just operations executing in specific
<<synchronization-pipeline-stages,pipeline stages>>, which allows other
pipeline stages to be excluded from a dependency.
Other scoping options are possible, depending on the particular command.
[[synchronization-dependencies-execution]]
An _execution dependency_ is a guarantee that for two sets of operations,
the first set must: _happen-before_ the second set.
If an operation happens-before another operation, then the first operation
must: complete before the second operation is initiated.
More precisely:
* Let *A* and *B* be separate sets of operations.
* Let *S* be a synchronization command.
* Let *A~S~* and *B~S~* be the synchronization scopes of *S*.
* Let *A'* be the intersection of sets *A* and *A~S~*.
* Let *B'* be the intersection of sets *B* and *B~S~*.
* Submitting *A*, *S* and *B* for execution, in that order, will result in
execution dependency *E* between *A'* and *B'*.
* Execution dependency *E* guarantees that *A'* happens-before *B'*.
[[synchronization-dependencies-chains]]
An _execution dependency chain_ is a sequence of execution dependencies that
form a happens-before relation between the first dependency's *A'* and the
final dependency's *B'*.
For each consecutive pair of execution dependencies, a chain exists if the
intersection of *B~S~* in the first dependency and *A~S~* in the second
dependency is not an empty set.
The formation of a single execution dependency from an execution dependency
chain can be described by substituting the following in the description of
execution dependencies:
* Let *S* be a set of synchronization commands that generate an execution
dependency chain.
* Let *A~S~* be the first synchronization scope of the first command in
*S*.
* Let *B~S~* be the second synchronization scope of the last command in
*S*.
.Note
[NOTE]
====
An execution dependency is inherently also multiple execution dependencies -
a dependency exists between each subset of *A'* and each subset of *B'*, and
the same is true for execution dependency chains.
For example, a synchronization command with multiple
<<synchronization-pipeline-stages,pipeline stages>> in its stage masks
effectively generates one dependency between each source stage and each
destination stage.
This can be useful to think about when considering how execution chains are
formed if they don't involve all parts of a synchronization command's
dependency.
Similarly, any set of adjacent dependencies in an execution dependency chain
can: be considered an execution dependency chain in its own right.
====
Execution dependencies alone are not sufficient to guarantee that values
resulting from writes in one set of operations can: be read from another set
of operations.
[[synchronization-dependencies-available-and-visible]]
Two additional types of operation are used to control memory access.
_Availability operations_ cause the values generated by specified memory
write accesses to become _available_ for future access.
Any available value remains available until a subsequent write to the same
memory location occurs (whether it is made available or not) or the memory
is freed.
_Visibility operations_ cause any available values to become _visible_ to
specified memory accesses.
[[synchronization-dependencies-memory]]
A _memory dependency_ is an execution dependency which includes availability
and visibility operations such that:
* The first set of operations happens-before the availability operation.
* The availability operation happens-before the visibility operation.
* The visibility operation happens-before the second set of operations.
Once written values are made visible to a particular type of memory access,
they can: be read or written by that type of memory access.
Most synchronization commands in Vulkan define a memory dependency.
[[synchronization-dependencies-access-scopes]]
The specific memory accesses that are made available and visible are defined
by the _access scopes_ of a memory dependency.
Any type of access that is in a memory dependency's first access scope and
occurs in *A'* is made available.
Any type of access that is in a memory dependency's second access scope and
occurs in *B'* has any available writes made visible to it.
Any type of operation that is not in a synchronization command's access
scopes will not be included in the resulting dependency.
A memory dependency enforces availability and visibility of memory accesses
and execution order two sets of operations.
Adding to the description of <<synchronization-dependencies-chains,
execution dependency chains>>:
* Let *a* be the set of memory accesses performed by *A'*.
* Let *b* be the set of memory accesses performed by *B'*.
* Let *a~S~* be the first access scope of the first command in *S*.
* Let *b~S~* be the second access scope of the last command in *S*.
* Let *a'* be the intersection of sets *a* and *a~S~*.
* Let *b'* be the intersection of sets *b* and *b~S~*.
* Submitting *A*, *S* and *B* for execution, in that order, will result in
a memory dependency *m* between *A'* and *B'*.
* Memory dependency *m* guarantees that:
** Memory writes in *a'* are made available.
** Available memory writes, including those from *a'*, are made visible to
*b'*.
[NOTE]
.Note
====
Execution and memory dependencies are used to solve data hazards, i.e. to
ensure that read and write operations occur in a well-defined order.
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.
====
[[synchronization-image-layout-transitions]]
=== Image Layout Transitions
Image subresources can: be transitioned from one <<resources-image-layouts,
layout>> to another as part of a <<synchronization-dependencies-memory,
memory dependency>> (e.g. by using an
<<synchronization-image-memory-barriers,image memory barrier>>).
When a layout transition is specified in a memory dependency, it
happens-after the availability operations in the memory dependency, and
happens-before the visibility operations.
Image layout transitions may: perform read and write accesses on all memory
bound to the image subresource range, so applications must: ensure that all
memory writes have been made
<<synchronization-dependencies-available-and-visible, available>> before a
layout transition is executed.
Available memory is automatically made visible to a layout transition, and
writes performed by a layout transition are automatically made available.
Layout transitions always apply to a particular image subresource range, and
specify both an old layout and new layout.
If the old layout does not match the new layout, a transition occurs.
The old layout must: match the current layout of the image subresource
range, with one exception.
The old layout can: always be specified as ename:VK_IMAGE_LAYOUT_UNDEFINED,
though doing so invalidates the contents of the image subresource range.
.Note
[NOTE]
====
Setting the old layout to ename:VK_IMAGE_LAYOUT_UNDEFINED implies that the
contents of the image subresource need not be preserved.
Implementations may: use this information to avoid performing expensive data
transition operations.
====
.Note
[NOTE]
====
Applications must: ensure that layout transitions happen-after all
operations accessing the image with the old layout, and happen-before any
operations that will access the image with the new layout.
Layout transitions are potentially read/write operations, so not defining
appropriate memory dependencies to guarantee this will result in a data
race.
====
The contents of any portion of another resource which aliases memory that is
bound to the transitioned image subresource range are undefined after an
image layout transition.
[[synchronization-pipeline-stages]]
=== Pipeline Stages
The work performed by an <<fundamentals-queueoperation-commandorder, action
command>> consists of multiple operations, which are performed by a sequence
of logically independent execution units known as _pipeline stages_.
The exact pipeline stages executed depend on the particular action command
that is used, and current command buffer state when the action command was
recorded.
<<drawing,Drawing commands>>, <<dispatch,dispatching commands>>,
<<copies,copy commands>>, and <<clears,clear commands>> all execute
<<synchronization-pipeline-stages-types,different sets of pipeline stages>>.
Execution of operations across pipeline stages must: adhere to
<<fundamentals-queueoperation-apiorder, API order>>,
<<fundamentals-queueoperation-commandorder, command order>>, and
<<synchronization-pipeline-stages-order, pipeline stage order>>.
Otherwise, execution across pipeline stages may: overlap or execute out of
order with regards to other stages, unless otherwise enforced by an
execution dependency.
// refBegin VkPipelineStageFlagBits - Bitmask specifying pipeline stages
Several of the <<fundamentals-queueoperation-commandorder, synchronization
commands>> include pipeline stage parameters, restricting the
<<synchronization-dependencies-scopes, synchronization scopes>> for that
command to those stages.
This allows fine grained control over the exact execution dependencies and
accesses performed by action commands.
Implementations should: use these pipeline stages to avoid unnecessary
stalls or cache flushing.
These pipeline stages are specified using a bitmask:
include::../api/enums/VkPipelineStageFlagBits.txt[]
The meaning of each bit is:
* ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT: Stage of the pipeline where any
commands are initially received by the queue.
ifdef::VK_NVX_device_generated_commands[]
* ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX: Stage of the pipeline
where device-side generation of commands via
flink:vkCmdProcessCommandsNVX is handled.
endif::VK_NVX_device_generated_commands[]
* ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT: Stage of the pipeline where
Draw/DispatchIndirect data structures are consumed.
2016-12-11 04:59:58 +00:00
ifdef::VK_NVX_device_generated_commands[]
This stage also includes reading commands written by
flink:vkCmdProcessCommandsNVX.
endif::VK_NVX_device_generated_commands[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT: Stage of the pipeline where
vertex and index buffers are consumed.
* ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT: Vertex shader stage.
* ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT: Tessellation
control shader stage.
* ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT: Tessellation
evaluation shader stage.
* ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT: Geometry shader stage.
* ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT: Fragment shader stage.
* ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT: Stage of the pipeline
where early fragment tests (depth and stencil tests before fragment
shading) are performed.
This stage also includes <<renderpass-load-store-ops, subpass load
operations>> for framebuffer attachments with a depth/stencil format.
* ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT: Stage of the pipeline
where late fragment tests (depth and stencil tests after fragment
shading) are performed.
This stage also includes <<renderpass-load-store-ops, subpass store
operations>> for framebuffer attachments with a depth/stencil format.
* ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT: Stage of the
pipeline after blending where the final color values are output from the
pipeline.
This stage also includes <<renderpass-load-store-ops, subpass load and
store operations>> and multisample resolve operations for framebuffer
attachments with a color format.
* [[synchronization-pipeline-stages-transfer]]
ename:VK_PIPELINE_STAGE_TRANSFER_BIT: Execution of copy commands.
This includes the operations resulting from all <<copies,copy
commands>>, <<clears,clear commands>> (with the exception of
flink:vkCmdClearAttachments), and flink:vkCmdCopyQueryPoolResults.
* ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT: Execution of a compute
shader.
* ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT: Final stage in the pipeline
where operations generated by all commands complete execution.
* ename:VK_PIPELINE_STAGE_HOST_BIT: A pseudo-stage indicating execution on
the host of reads/writes of device memory.
This stage is not invoked by any action commands.
* ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT: Execution of all graphics
pipeline stages.
Equivalent to the logical or of:
** ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
** ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
** ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT
** ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT
** ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
** ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
** ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
** ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT
** ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
** ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT
** ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
** ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
* ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT: Equivalent to the logical or
of every other pipeline stage flag that is supported on the queue it is
used with.
[NOTE]
.Note
====
An execution dependency with only ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
in the destination stage mask will only prevent that stage from executing in
subsequently submitted commands.
As this stage doesn't perform any actual execution, this is not observable -
in effect, it does not delay processing of subsequent commands.
Similarly an execution dependency with only
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT in the source stage mask will
effectively not wait for any prior commands to complete.
When defining a memory dependency, using only
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT or
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT would never make any accesses
available and/or visible because these stages do not access memory.
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT and
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT are useful for accomplishing layout
transitions and queue ownership operations when the required execution
dependency is satisfied by other means - for example, semaphore operations
between queues.
====
// refEnd VkPipelineStageFlagBits
[[synchronization-pipeline-stages-masks]]
If a synchronization command includes a source stage mask, its first
<<synchronization-dependencies-scopes, synchronization scope>> only includes
execution of the pipeline stages specified in that mask, as well as any
<<synchronization-pipeline-stages-order, logically earlier>> stages.
If a synchronization command includes a destination stage mask, its second
<<synchronization-dependencies-scopes, synchronization scope>> only includes
execution of the pipeline stages specified in that mask, as well as any
<<synchronization-pipeline-stages-order, logically later>> stages.
<<synchronization-dependencies-access-scopes, Access scopes>> are affected
in a similar way.
If a synchronization command includes a source stage mask, its first
<<synchronization-dependencies-access-scopes, access scope>> only includes
memory access performed by pipeline stages specified in that mask.
If a synchronization command includes a destination stage mask, its second
<<synchronization-dependencies-access-scopes, access scope>> only includes
memory access performed by pipeline stages specified in that mask.
[NOTE]
.Note
====
Implementations may: not support synchronization at every pipeline stage for
every synchronization operation.
If a pipeline stage that an implementation does not support synchronization
for appears in a source stage mask, then it may: substitute that stage for
any logically later stage.
If a pipeline stage that an implementation does not support synchronization
for appears in a destination stage mask, then it may: substitute that stage
for any logically earlier stage.
For example, if an implementation is unable to signal an event immediately
after vertex shader execution is complete, it may: instead signal the event
after color attachment output has completed.
If an implementation makes such a substitution, it must: not affect the
semantics of execution or memory dependencies or image and buffer memory
barriers.
====
Certain pipeline stages are only available on queues that support a
particular set of operations.
The following table lists, for each pipeline stage flag, which queue
capability flag must: be supported by the queue.
When multiple flags are enumerated in the second column of the table, it
means that the pipeline stage is supported on the queue if it supports any
of the listed capability flags.
For further details on queue capabilities see
<<devsandqueues-physical-device-enumeration,Physical Device Enumeration>>
and <<devsandqueues-queues,Queues>>.
2016-12-02 11:32:05 +00:00
[[synchronization-pipeline-stages-supported]]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
.Supported pipeline stage flags
[width="100%",cols="69%,31%",options="header",align="center"]
|====
|Pipeline stage flag | Required queue capability flag
2016-12-02 11:32:05 +00:00
|ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT | None required
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
|ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT | ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT
|ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT | ename:VK_QUEUE_GRAPHICS_BIT
|ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT | ename:VK_QUEUE_COMPUTE_BIT
|ename:VK_PIPELINE_STAGE_TRANSFER_BIT | ename:VK_QUEUE_GRAPHICS_BIT, ename:VK_QUEUE_COMPUTE_BIT or ename:VK_QUEUE_TRANSFER_BIT
2016-12-02 11:32:05 +00:00
|ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT | None required
|ename:VK_PIPELINE_STAGE_HOST_BIT | None required
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
|ename:VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT | ename:VK_QUEUE_GRAPHICS_BIT
2016-12-02 11:32:05 +00:00
|ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT | None required
2016-12-11 04:59:58 +00:00
ifdef::VK_NVX_device_generated_commands[]
|ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX | ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT
endif::VK_NVX_device_generated_commands[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
|====
[[synchronization-pipeline-stages-order]]
Pipeline stages that execute as a result of a command logically complete
execution in a specific order, such that completion of a logically later
pipeline stage must: not happen-before completion of a logically earlier
stage.
This means that including any given stage in the source stage mask for a
particular synchronization command also implies that any logically earlier
stages are included in *A~S~* for that command.
Similarly, initiation of a logically earlier pipeline stage must: not
happen-after initiation of a logically later pipeline stage.
Including any given stage in the destination stage mask for a particular
synchronization command also implies that any logically later stages are
included in *B~S~* for that command.
.Note
[NOTE]
====
Logically earlier/later stages are not included when defining the
<<synchronization-dependencies-access-scopes, access scopes>> of a
<<synchronization-memory-barriers,memory barrier>>.
====
[[synchronization-pipeline-stages-types]]
The order of pipeline stages depends on the particular pipeline; graphics,
compute, transfer or host.
For the graphics pipeline, the following stages occur in this order:
* ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
* ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
* ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT
* ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT
* ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT
* ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
* ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
* ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT
* ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT
* ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
* ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
For the compute pipeline, the following stages occur in this order:
* ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
* ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
* ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT
* ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
For the transfer pipeline, the following stages occur in this order:
* ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
* ename:VK_PIPELINE_STAGE_TRANSFER_BIT
* ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
For host operations, only one pipeline stage occurs, so no order is
guaranteed:
* ename:VK_PIPELINE_STAGE_HOST_BIT
2016-12-11 04:59:58 +00:00
ifdef::VK_NVX_device_generated_commands[]
For the command processing pipeline, the following stages occur in this
order:
* ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT
* ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
* ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
endif::VK_NVX_device_generated_commands[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-access-types]]
=== Access Types
Memory in Vulkan can: be accessed from within shader invocations and via
some fixed-function stages of the pipeline.
The _access type_ is a function of the <<descriptorsets, descriptor type>>
used, or how a fixed-function stage accesses memory.
Each access type corresponds to a bit flag in slink:VkAccessFlagBits.
[[synchronization-access-masks]]
Some synchronization commands take sets of access types as parameters to
define the <<synchronization-dependencies-access-scopes, access scopes>> of
a memory dependency.
If a synchronization command includes a source access mask, its first
<<synchronization-dependencies-access-scopes, access scope>> only includes
accesses via the access types specified in that mask.
Similarly, if a synchronization command includes a destination access mask,
its second <<synchronization-dependencies-access-scopes, access scope>> only
includes accesses via the access types specified in that mask.
// refBegin VkAccessFlagBits Bitmask specifying memory access types that will participate in a memory dependency
Access types that can be set in an access mask include:
[[synchronization-access-flags]]
include::../api/enums/VkAccessFlagBits.txt[]
* ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT: Read access to an indirect
command structure read as part of an indirect drawing or dispatch
command.
* ename:VK_ACCESS_INDEX_READ_BIT: Read access to an index buffer as part
of an indexed drawing command, bound by flink:vkCmdBindIndexBuffer.
* ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT: Read access to a vertex
buffer as part of a drawing command, bound by
flink:vkCmdBindVertexBuffers.
* ename:VK_ACCESS_UNIFORM_READ_BIT: Read access to a
<<descriptorsets-uniformbuffer, uniform buffer>>.
* ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT: Read access to an
<<renderpass, input attachment>> within a renderpass during fragment
shading.
* ename:VK_ACCESS_SHADER_READ_BIT: Read access to a
<<descriptorsets-storagebuffer, storage buffer>>,
<<descriptorsets-uniformtexelbuffer, uniform texel buffer>>,
<<descriptorsets-storagetexelbuffer, storage texel buffer>>,
<<descriptorsets-sampledimage, sampled image>>, or
<<descriptorsets-storageimage, storage image>>.
* ename:VK_ACCESS_SHADER_WRITE_BIT: Write access to a
<<descriptorsets-storagebuffer, storage buffer>>,
<<descriptorsets-storagetexelbuffer, storage texel buffer>>, or
<<descriptorsets-storageimage, storage image>>.
* ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT: Read access to a
<<renderpass, color attachment>>, such as via <<framebuffer-blending,
blending>>, <<framebuffer-logicop, logic operations>>, or via certain
<<renderpass-load-store-ops, subpass load operations>>.
* ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT: Write access to a
<<renderpass, color or resolve attachment>> during a <<renderpass,
render pass>> or via certain <<renderpass-load-store-ops, subpass load
and store operations>>.
* ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT: Read access to a
<<renderpass, depth/stencil attachment>>, via <<fragops-ds-state, depth
or stencil operations>> or via certain <<renderpass-load-store-ops,
subpass load operations>>.
* ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT: Write access to a
<<renderpass, depth/stencil attachment>>, via <<fragops-ds-state, depth
or stencil operations>> or via certain <<renderpass-load-store-ops,
subpass load and store operations>>.
* ename:VK_ACCESS_TRANSFER_READ_BIT: Read access to an image or buffer in
a <<copies, copy>> operation.
* ename:VK_ACCESS_TRANSFER_WRITE_BIT: Write access to an image or buffer
in a <<clears, clear>> or <<copies, copy>> operation.
* ename:VK_ACCESS_HOST_READ_BIT: Read access by a host operation.
* ename:VK_ACCESS_HOST_WRITE_BIT: Write access by a host operation.
* ename:VK_ACCESS_MEMORY_READ_BIT: Read access via non-specific entities.
These entities include the Vulkan device and host, but may: also include
entities external to the Vulkan device or otherwise not part of the core
Vulkan pipeline.
When included in a destination access mask, makes all available writes
visible to all future read accesses on entities known to the Vulkan
device.
* ename:VK_ACCESS_MEMORY_WRITE_BIT: Write access via non-specific
entities.
These entities include the Vulkan device and host, but may: also include
entities external to the Vulkan device or otherwise not part of the core
Vulkan pipeline.
When included in a source access mask, all writes that are performed by
entities known to the Vulkan device are made available.
When included in a destination access mask, makes all available writes
visible to all future write accesses on entities known to the Vulkan
device.
2016-12-11 04:59:58 +00:00
ifdef::VK_NVX_device_generated_commands[]
* ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX: Reads from sname:VkBuffer
inputs to flink:vkCmdProcessCommandsNVX.
* ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX: Writes to the target
command buffer in flink:vkCmdProcessCommandsNVX.
endif::VK_NVX_device_generated_commands[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Certain access types are only performed by a subset of pipeline stages.
Any synchronization command that takes both stage masks and access masks
uses both to define the <<synchronization-dependencies-access-scopes, access
scopes>> - only the specified access types performed by the specified stages
are included in the access scope.
An application must: not specify an access flag in a synchronization command
if it does not include a pipeline stage in the corresponding stage mask that
is able to perform accesses of that type.
The following table lists, for each access flag, which pipeline stages can:
perform that type of access.
2016-12-02 11:32:05 +00:00
[[synchronization-access-types-supported]]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
.Supported access types
[width="100%",cols="67%,33%",options="header",align="center"]
|====
|Access flag | Supported pipeline stages
|ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT | ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT
|ename:VK_ACCESS_INDEX_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT
|ename:VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_INPUT_BIT
|ename:VK_ACCESS_UNIFORM_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT
|ename:VK_ACCESS_INPUT_ATTACHMENT_READ_BIT | ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT
|ename:VK_ACCESS_SHADER_READ_BIT | ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT
|ename:VK_ACCESS_SHADER_WRITE_BIT | ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT, ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT, ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT, ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, or ename:VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT
|ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT | ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
|ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
|ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT | ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT, or ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT
|ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT | ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT, or ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT
|ename:VK_ACCESS_TRANSFER_READ_BIT | ename:VK_PIPELINE_STAGE_TRANSFER_BIT
|ename:VK_ACCESS_TRANSFER_WRITE_BIT | ename:VK_PIPELINE_STAGE_TRANSFER_BIT
|ename:VK_ACCESS_HOST_READ_BIT | ename:VK_PIPELINE_STAGE_HOST_BIT
|ename:VK_ACCESS_HOST_WRITE_BIT | ename:VK_PIPELINE_STAGE_HOST_BIT
|ename:VK_ACCESS_MEMORY_READ_BIT | N/A
|ename:VK_ACCESS_MEMORY_WRITE_BIT | N/A
2016-12-11 04:59:58 +00:00
ifdef::VK_NVX_device_generated_commands[]
|ename:VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX | ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
|ename:VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX | ename:VK_PIPELINE_STAGE_COMMAND_PROCESS_BIT_NVX
endif::VK_NVX_device_generated_commands[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
|====
[[synchronization-framebuffer-regions]]
=== Framebuffer Region Dependencies
<<synchronization-pipeline-stages, Pipeline stages>> that operate on, or
with respect to, the framebuffer are collectively the _framebuffer-space_
pipeline stages.
These stages are:
* ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT
* ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT
* ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT
* ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
For these pipeline stages, an execution or memory dependency from the first
set of operations to the second set can: either be a single
_framebuffer-global_ dependency, or split into multiple _framebuffer-local_
dependencies.
A dependency with non-framebuffer-space pipeline stages is neither
framebuffer-global nor framebuffer-local.
A _framebuffer region_ is a set of sample (x, y, layer, sample) coordinates
that is a subset of the entire framebuffer.
A single framebuffer-local dependency guarantees that only for a single
framebuffer region, the first set of operations and availability operations
happen-before visibility operations and the second set of operations.
No ordering guarantees are made between framebuffer regions for a
framebuffer-local dependency.
A framebuffer-global dependency guarantees that the first set of operations
for all framebuffer regions happens-before the second set of operations for
any framebuffer region.
.Note
[NOTE]
====
Since fragment invocations are not specified to run in any particular
groupings, the size of a framebuffer region is implementation-dependent, not
known to the application, and must: be assumed to be no larger than a single
sample.
====
If a synchronization command includes a pname:dependencyFlags parameter, and
specifies the ename:VK_DEPENDENCY_BY_REGION_BIT flag, then it defines
framebuffer-local dependencies for the framebuffer-space pipeline stages in
that synchronization command, for all framebuffer regions.
If no pname:dependencyFlags parameter is included, or the
ename:VK_DEPENDENCY_BY_REGION_BIT flag is not specified, then a
framebuffer-global dependency is specified for those stages.
The ename:VK_DEPENDENCY_BY_REGION_BIT flag does not affect the dependencies
between non-framebuffer-space pipeline stages, nor does it affect the
dependencies between framebuffer-space and non-framebuffer-space pipeline
stages.
.Note
[NOTE]
====
Framebuffer-local dependencies are more optimal for most architectures;
particularly tile-based architectures - which can keep framebuffer-regions
entirely in on-chip registers and thus avoid external bandwidth across such
a dependency.
Including a framebuffer-global dependency in your rendering will usually
force all implementations to flush data to memory, or to a higher level
cache, breaking any potential locality optimizations.
====
2016-02-16 09:53:44 +00:00
[[synchronization-fences]]
== Fences
2016-09-17 04:22:17 +00:00
// refBegin VkFence Opaque handle to a fence object
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Fences are a synchronization primitive that can: be used to insert a
dependency from a queue to the host.
Fences have two states - signaled and unsignaled.
A fence can: be signaled as part of the execution of a
<<devsandqueues-submission, queue submission>> command.
Fences can: be unsignaled on the host with flink:vkResetFences.
Fences can: be waited on by the host with the flink:vkWaitForFences command,
and the current state can: be queried with flink:vkGetFenceStatus.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
Fences are represented by sname:VkFence handles:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/handles/VkFence.txt[]
2016-07-11 01:13:41 +00:00
// refEnd VkFence
2016-09-17 04:22:17 +00:00
// refBegin vkCreateFence Create a new fence object
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
To create a fence, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCreateFence.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that creates the fence.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:pCreateInfo is a pointer to an instance of the
sname:VkFenceCreateInfo structure which contains information about how
the fence is to be created.
2016-02-16 09:53:44 +00:00
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pFence points to a handle in which the resulting fence object is
returned.
include::../validity/protos/vkCreateFence.txt[]
2016-09-17 04:22:17 +00:00
// refBegin VkFenceCreateInfo Structure specifying parameters of a newly created fence
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkFenceCreateInfo structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkFenceCreateInfo.txt[]
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
* pname:flags defines the initial state and behavior of the fence.
Bits which can: be set include:
2016-07-11 01:13:41 +00:00
+
--
2016-09-17 04:22:17 +00:00
// refBegin VkFenceCreateFlagBits Bitmask specifying initial state and behavior of a fence
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/enums/VkFenceCreateFlagBits.txt[]
2016-07-11 01:13:41 +00:00
--
+
2016-02-16 09:53:44 +00:00
If pname:flags contains ename:VK_FENCE_CREATE_SIGNALED_BIT then the fence
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
object is created in the signaled state; otherwise it is created in the
unsignaled state.
2016-02-16 09:53:44 +00:00
include::../validity/structs/VkFenceCreateInfo.txt[]
2016-07-11 01:13:41 +00:00
// refBegin vkDestroyFence Destroy a fence object
2016-02-16 09:53:44 +00:00
To destroy a fence, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkDestroyFence.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that destroys the fence.
* pname:fence is the handle of the fence to destroy.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* All <<devsandqueues-submission, queue submission>> commands that refer
to pname:fence must: have completed execution
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
* If sname:VkAllocationCallbacks were provided when pname:fence was
created, a compatible set of callbacks must: be provided here
* If no sname:VkAllocationCallbacks were provided when pname:fence was
created, pname:pAllocator must: be `NULL`
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkDestroyFence.txt[]
2016-09-17 04:22:17 +00:00
// refBegin vkGetFenceStatus Return the status of a fence
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
To query the status of a fence from the host, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkGetFenceStatus.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the fence.
* pname:fence is the handle of the fence to query.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Upon success, fname:vkGetFenceStatus returns the status of the fence object,
with the following return codes:
.Fence Object Status Codes
[width="80%",options="header"]
|====
| Status | Meaning
| ename:VK_SUCCESS | The fence specified by pname:fence is signaled.
| ename:VK_NOT_READY | The fence specified by pname:fence is unsignaled.
|====
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
If a <<devsandqueues-submission, queue submission>> command is pending
execution, then the value returned by this command may: immediately be out
of date.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkGetFenceStatus.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-fences-unsignaling]]
2016-09-17 04:22:17 +00:00
// refBegin vkResetFences Resets one or more fence objects
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
To set the state of fences to unsignaled from the host, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkResetFences.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the fences.
* pname:fenceCount is the number of fences to reset.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:pFences is a pointer to an array of fence handles to reset.
When flink:vkResetFences is executed on the host, it defines a _fence
unsignal operation_ for each fence, which resets the fence to the unsignaled
state.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
If any member of pname:pFences is already in the unsignaled state when
flink:vkResetFences is executed, then flink:vkResetFences has no effect on
that fence.
Change log for March 4, 2016 Vulkan 1.0.5 spec update:
* Bump API patch number to 5 for this update.
Github Issues:
* Correctly describe slink:VkPhysicalDeviceProperties pname:deviceName
member as a string, not a pointer to a string. Also one typo fix for
"hetereogeneous" (public issue 4).
* Replace maynot: macro with may: not, and "may: or maynot:" with
"may:" (public issue 4).
* Clarify that redundantly setting the state of a fence or event has
no effect (public issue 4).
* Minor fixes to ref pages to track descriptions of memory bits that
changed in the core spec. Fix name of a member in the description of
sname:sname:VkPipelineMultisampleStateCreateInfo (public issues 8,
13).
* Remove redundant validity statement for
sname:VkGraphicsPipelineCreateInfo::pname:stageCount (public issue
14).
* Fix typos in chapters 7-9 (public issue 14).
* Clarify the example demonstrating the behavior of
code:OpMemoryBarrier in the
<<shaders-execution-memory-ordering,shader memory acces
ordering>> section (public issue 16).
* Specify that freeing mapped memory implicitly unmaps the memory in
the description of flink:vkFreeMemory (public issue 17).
* Forbid allocation callbacks from calling into the API in the
<<memory-allocation,memory allocation>> section (public issue
20).
* Add missing validity rules about size being greater than 0 and
offset being less than size of object. Fix
flink:VkMappedMemoryRange's misinterpretation of offset (public
issues 27, 31).
* Add validity rule disallowing overlapping source/destination
descriptors in flink:VkCopyDescriptorSet (public issue 32).
* Clarify that array and matrix stride has to be a multiple of the
base alignment of the array or matrix in the
<<interfaces-resources-layout,Offset and Stride Assignment>>
section (public issue 38).
* Correct parenthesis floor nesting error in equation for
<<textures-RGB-sexp,RGB to shared exponent conversion>>.
Clarify case of when exp' is forced to 0, avoiding log2(0) undefined
problem (public issue 40).
* Remove redundant statement from the code:FragDepth description in
the <<interfaces-builtin-variables,Built-In Variables>>
section (public issue 47).
* Define the clamping of the
<<textures-level-of-detail-operation,bias added to the scale
factor>> by linking to the slink:VkPhysicalDevice feature
pname:maxSamplerLodBias (public issue 64).
* Fix typo "optimal linear resources" and clarify the set of resources
<<features-limits-bufferImageGranularity,the
pname:bufferImageGranularity resource>> applies to (public issue
67).
* Replace 'descriptor accessed by a pipeline' language for
sname:VkDescriptorSetAllocateInfo with more precise phrasing about
binding a descriptor set before a command that invokes work using
that set (public issue 69).
* tstripadj.svg contained an Inkscape tag which caused Firefox and IE
11 to fail to render it, and was illegal SVG. Generating Plain SVG
from the Inkscape SVG source fixes this (public issue 70).
* Fix validity for sname:VkVertexInputBindingDescription and
sname:VkVertexInputAttributeDescription numbers (public issue 72).
Internal Issues:
* Clarify the meaning of
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT in
elink:VkFormatFeatureFlagBits with respect to depth compare
(internal issue 107).
* Added a note explaining that ename:VK_QUEUE_TRANSFER_BIT may or may
not be reported for a queue family that already supports
ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT as the
former is a strict subset of the latter ones (internal issue 116).
* Add validity language for sname:VkDescriptorSetAllocateInfo about
exceeding the descriptor pool capacity (internal issue 140).
* Add ename:VK_INCOMPLETE success code for
flink:vkEnumeratePhysicalDevices query (internal issue 163).
Other Commits:
* Add the VK_NV_glsl_shader extension definitions to the API.
* Update GL_KHR_vulkan_glsl with 1) origin_upper_left as default 2)
specialization array constant semantics.
* Corrected/updated Data Format Specification date.
2016-03-03 13:06:18 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* Any given element of pname:pFences must: not currently be associated
with any queue command that has not yet completed execution on that
queue
****
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkResetFences.txt[]
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
[[synchronization-fences-signaling]]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When a fence is submitted to a queue as part of a
<<devsandqueues-submission, queue submission>> command, it defines a memory
dependency on the batches that were submitted as part of that command, and
defines a _fence signal operation_ which sets the fence to the signaled
state.
The first <<synchronization-dependencies-scopes, synchronization scope>>
includes every batch submitted in the same <<devsandqueues-submission, queue
submission>> command.
Fence signal operations that are defined by flink:vkQueueSubmit additionally
include all previous queue submissions to the same queue via
flink:vkQueueSubmit in the first synchronization scope.
The second <<synchronization-dependencies-scopes, synchronization scope>>
only includes the fence signal operation.
The first <<synchronization-dependencies-access-scopes, access scope>>
includes all memory access performed by the device.
The second <<synchronization-dependencies-access-scopes, access scope>> is
empty.
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
2016-09-17 04:22:17 +00:00
// refBegin vkWaitForFences Wait for one or more fences to become signaled
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
To wait for one or more fences to enter the signaled state on the host,
call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkWaitForFences.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the fences.
* pname:fenceCount is the number of fences to wait on.
* pname:pFences is a pointer to an array of pname:fenceCount fence
handles.
* pname:waitAll is the condition that must: be satisfied to successfully
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
unblock the wait.
If pname:waitAll is ename:VK_TRUE, then the condition is that all fences
in pname:pFences are signaled.
Otherwise, the condition is that at least one fence in pname:pFences is
signaled.
Change log for March 10, 2016 Vulkan 1.0.6 spec update:
* Bump API patch number and header version number to 6 for this
update.
Github Issues:
* Define 'invocation group' for compute and graphics shaders. Cleanup
definition and use of 'workgroup', and add glossary entries (public
issue 1).
* Various minor editorial fixes (public issue 33).
* Clarify locations for block members in the
<<interfaces-iointerfaces-locations,Location Assignment>>
section (public issue 45).
* Editorial fixes for <<commandbuffer-allocation,Command Buffer
Allocation>> section (public issues 54, 59).
* Clarify behavior of depth test in the <<fragops-depth,Depth
Test>> section (public issues 80, 81).
* Remove discussion of return codes from
flink:vkGetPhysicalDeviceSparseImageFormatProperties and
flink:vkGetImageSparseMemoryRequirements, which don't return values
(public issue 82).
* Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
pname:drawCount of 0, as well as 1, when the multiDrawIndirect
feature is not supported (public issue 88).
* Remove confusing wording in the <<features-limits,Limits>>
section describing the slink:VkPhysicalDeviceLimits
pname:minTexelBufferOffsetAlignment,
pname:minUniformBufferOffsetAlignment, and
pname:minStorageBufferOffsetAlignment members as both minimums and
maximums (public issue 91).
* Clarified that only the RGB components should be affected in places
where sRGB is referred to in the spec, such as ASTC formats. Minor
re-wording to avoid "color space" when actively incorrect, now that
we refer to the Data Format Spec which actually makes a distinction
between color space and transfer function (public issue 94).
* Treat pname:pPropertyCount == 0 consistently in
flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties (public issue 99)
* Cleanup minor editorial issues in chapters 14-17 (public issue 100).
* Clarify definition of flink:vkEnumerateInstanceExtensionProperties
and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
* Define the flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
parameter to be a pointer to a null-terminated UTF-8 string (public
issue 101).
* Rearrange "Missing information" references in mandatory format
tables (public issue 101).
* Clarify that the enumerated extensions returned by
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties will only include
extensions provided by the platform or extensions implemented in
implicitly enabled layers (public issue 101).
* Miscellaneous editorial fixes. Include the Vulkan spec patch number
in the PDF title. Fix label on <<fig-non-strict-lines,Non
strict lines>> diagram. Use more easily distinguished symbols in
tables in the <<features-required-format-support,Required
Format Support>> section. Don't require FQDNs used as layer names be
encoded in lower case if not possible, in the
<<extensions-naming-conventions, Extension and Layer Naming
Conventions>> section (public issues 101, 119, 121).
Internal Issues:
* Fixed excessive spacing in tables in XHTML (internal issue 18).
* Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
applies to secondary command buffers. Previously spec only referred
to the members of pname:pCommandBuffers being affected by this bit.
Added a separate slink:VkSubmitInfo Valid Usage restriction
specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
also applies to any secondary command buffers that are recorded into
the primary command buffers in pname:pCommandBuffers (internal issue
106).
* Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
NULL (internal issue 117).
* Remove "the value of" where it is redundant (e.g. speaking of an API
parameter, struct member, or SPIR-V variable, but not when speaking
of color components) (internal issue 175).
* Forced patch version to always be 0 in the header. Add a
"VK_API_VERSION_<major>_<minor>" macro for people to use to do the
right thing. Add a VK_HEADER_VERSION which captures the header
release number independent of the spec patch number (internal issue
176).
* Correct description of
slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
a null-terminated UTF-8 string" (internal issue #197).
Other Commits:
* Updated DataFormat spec reference to the new date for revision 5 of
that spec.
* Fixed KEEP option (to retain LaTeX intermediate files) in the
Makefile to be included when edited there, as well as set on the
command line.
* Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
script functionality to add and remove validity from existing
functions. Includes schema and readme changes.
* Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
sets.
2016-03-11 01:33:02 +00:00
* pname:timeout is the timeout period in units of nanoseconds.
pname:timeout is adjusted to the closest value allowed by the
2016-02-16 09:53:44 +00:00
implementation-dependent timeout accuracy, which may: be substantially
longer than one nanosecond, and may: be longer than the requested
period.
If the condition is satisfied when fname:vkWaitForFences is called, then
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
fname:vkWaitForFences returns immediately.
If the condition is not satisfied at the time fname:vkWaitForFences is
called, then fname:vkWaitForFences will block and wait up to pname:timeout
nanoseconds for the condition to become satisfied.
2016-02-16 09:53:44 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
If pname:timeout is zero, then fname:vkWaitForFences does not wait, but
simply returns the current state of the fences.
ename:VK_TIMEOUT will be returned in this case if the condition is not
satisfied, even though no actual wait was performed.
2016-02-16 09:53:44 +00:00
If the specified timeout period expires before the condition is satisfied,
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
fname:vkWaitForFences returns ename:VK_TIMEOUT.
If the condition is satisfied before pname:timeout nanoseconds has expired,
2016-02-16 09:53:44 +00:00
fname:vkWaitForFences returns ename:VK_SUCCESS.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
include::../validity/protos/vkWaitForFences.txt[]
[[synchronization-fences-waiting]]
An execution dependency is defined by waiting for a fence to become
signaled, either via flink:vkWaitForFences or by polling on
flink:vkGetFenceStatus.
The first <<synchronization-dependencies-scopes, synchronization scope>>
includes only the fence signal operation.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes the host operations of flink:vkWaitForFences or
flink:vkGetFenceStatus indicating that the fence has become signaled.
.Note
[NOTE]
====
Signaling a fence and waiting on the host does not guarantee that the
results of memory accesses will be visible to the host.
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
To provide that guarantee, the application must: insert a memory barrier
between the device writes and the end of the submission that will signal the
fence, with pname:dstAccessMask having the ename:VK_ACCESS_HOST_READ_BIT bit
set, with pname:dstStageMask having the ename:VK_PIPELINE_STAGE_HOST_BIT bit
set, and with the appropriate pname:srcStageMask and pname:srcAccessMask
members set to guarantee completion of the writes.
If the memory was allocated without the
2016-02-16 09:53:44 +00:00
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, then
fname:vkInvalidateMappedMemoryRanges must: be called after the fence is
signaled in order to ensure the writes are visible to the host, as described
in <<memory-device-hostaccess,Host Access to Device Memory Objects>>.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
====
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
[[synchronization-semaphores]]
== Semaphores
2016-09-17 04:22:17 +00:00
// refBegin VkSemaphore Opaque handle to a semaphore object
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Semaphores are a synchronization primitive that can: be used to insert a
dependency between batches submitted to queues.
Semaphores have two states - signaled and unsignaled.
The state of a semaphore can: be signaled after execution of a batch of
commands is completed.
A batch can: wait for a semaphore to become signaled before it begins
execution, and the semaphore is also unsignaled before the batch begins
execution.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
Semaphores are represented by sname:VkSemaphore handles:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/handles/VkSemaphore.txt[]
2016-07-11 01:13:41 +00:00
// refEnd VkSemaphore
2016-09-17 04:22:17 +00:00
// refBegin vkCreateSemaphore Create a new queue semaphore object
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
To create a semaphore, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCreateSemaphore.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that creates the semaphore.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:pCreateInfo is a pointer to an instance of the
sname:VkSemaphoreCreateInfo structure which contains information about
how the semaphore is to be created.
2016-02-16 09:53:44 +00:00
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
* pname:pSemaphore points to a handle in which the resulting semaphore
object is returned.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When created, the semaphore is in the unsignaled state.
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCreateSemaphore.txt[]
2016-09-17 04:22:17 +00:00
// refBegin VkSemaphoreCreateInfo Structure specifying parameters of a newly created semaphore
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkSemaphoreCreateInfo structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkSemaphoreCreateInfo.txt[]
2016-02-16 09:53:44 +00:00
* 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.
include::../validity/structs/VkSemaphoreCreateInfo.txt[]
2016-07-11 01:13:41 +00:00
// refBegin vkDestroySemaphore Destroy a semaphore object
2016-02-16 09:53:44 +00:00
To destroy a semaphore, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkDestroySemaphore.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that destroys the semaphore.
* pname:semaphore is the handle of the semaphore to destroy.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* All submitted batches that refer to pname:semaphore must: have completed
execution
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
* If sname:VkAllocationCallbacks were provided when pname:semaphore was
created, a compatible set of callbacks must: be provided here
* If no sname:VkAllocationCallbacks were provided when pname:semaphore was
created, pname:pAllocator must: be `NULL`
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkDestroySemaphore.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
[[synchronization-semaphores-signaling]]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
=== Semaphore Signaling
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When a batch is submitted to a queue via a <<devsandqueues-submission, queue
submission>>, and it includes semaphores to be signaled, it defines a memory
dependency on the batch, and defines _semaphore signal operations_ which set
the semaphores to the signaled state.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The first <<synchronization-dependencies-scopes, synchronization scope>>
includes every command submitted in the same batch.
Semaphore signal operations that are defined by flink:vkQueueSubmit
additionally include all batches previously submitted to the same queue via
flink:vkQueueSubmit, including batches that are submitted in the same
<<devsandqueues-submission, queue submission>> command, but at a lower index
within the array of batches.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes only the semaphore signal operation.
The first <<synchronization-dependencies-access-scopes, access scope>>
includes all memory access performed by the device.
The second <<synchronization-dependencies-access-scopes, access scope>> is
empty.
[[synchronization-semaphores-waiting]]
=== Semaphore Waiting & Unsignaling
When a batch is submitted to a queue via a <<devsandqueues-submission, queue
submission>>, and it includes semaphores to be waited on, it defines a
memory dependency between prior semaphore signal operations and the batch,
and defines _semaphore unsignal operations_ which set the semaphores to the
unsignaled state.
The first synchronization scope includes all semaphore signal operations
that operate on semaphores waited on in the same batch, and that
happen-before the wait completes.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes every command submitted in the same batch.
In the case of flink:vkQueueSubmit, the second synchronization scope is
limited to operations on the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
by the corresponding element of pname:pWaitDstStageMask.
Also, in the case of flink:vkQueueSubmit, the second synchronization scope
additionally includes all batches subsequently submitted to the same queue
via flink:vkQueueSubmit, including batches that are submitted in the same
<<devsandqueues-submission, queue submission>> command, but at a higher
index within the array of batches.
The first <<synchronization-dependencies-access-scopes, access scope>> is
empty.
The second <<synchronization-dependencies-access-scopes, access scope>>
includes all memory access performed by the device.
The semaphore unsignal operation happens-after the first set of operations
in the execution dependency, and happens-before the second set of operations
in the execution dependency.
ifdef::VK_KHR_swapchain[]
2016-02-16 09:53:44 +00:00
.Note
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[NOTE]
2016-02-16 09:53:44 +00:00
====
A common scenario for using pname:pWaitDstStageMask with values other than
ename:VK_PIPELINE_STAGE_ALL_COMMANDS_BIT is when synchronizing a window
system presentation operation against subsequent command buffers which
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
render the next frame.
In this case, a presentation image must: not be overwritten until the
presentation operation completes, but other pipeline stages can: execute
without waiting.
A mask of ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT prevents
subsequent color attachment writes from executing until the semaphore
signals.
2016-02-16 09:53:44 +00:00
Some implementations may: be able to execute transfer operations and/or
vertex processing work before the semaphore is signaled.
If an image layout transition needs to be performed on a swapchain image
2016-04-21 08:08:38 +00:00
before it is used in a framebuffer, that can: be performed as the first
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
operation submitted to the queue after acquiring the image, and should: not
prevent other work from overlapping with the presentation operation.
For example, a sname:VkImageMemoryBarrier could use:
2016-02-16 09:53:44 +00:00
* pname:srcStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
2016-10-25 05:22:26 +00:00
* pname:srcAccessMask = 0
2016-02-16 09:53:44 +00:00
* pname:dstStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
* pname:dstAccessMask = ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
Change log for April 1, 2016 Vulkan 1.0.8 spec update:
* Bump API patch number and header version number to 8 for this
update.
Github Issues:
* Specify in the validity language for flink:vkBeginCommandBuffer that
pname:commandBuffer mustnot: currently be pending execution (public
issue 96).
* Describe depth comparison using the correct temporary variable names
in the <<textures-depth-compare-operation,Depth Compare Operation>>
section (public issue 100).
* Clarify the order of descriptor update operations in the
flink:vkUpdateDescriptorSets command (public issue 115).
* Specify in the VK_KHR_swapchain extension that
flink:vkAcquireNextImageKHR's pname:semaphore and pname:fence
parameters cannot both be sname:VK_NULL_HANDLE (partly addresses,
but does not fully close, public issue 117 / internal issue 246).
* Change reference to the "lifetime" of a Vulkan command to
"duration", and define the "duration" term (public issue 135).
* Added valid usage language for slink:VkImageLayout to require both
pname:height and pname:depth to be 1 for 1D images and pname:depth
to be 1 for 2D images (public issue 137).
* Fix SPIR-V example code in the
<<descriptorsets-inputattachment,Input Attachment>> section to
properly decorate the code:InputAttachmentIndex (public issue 139).
* Fix reference to nonexistent pname:imageInfo in the description of
flink:VkWriteDescriptorSet to refer to pname:pImageInfo (public
issue 140).
Internal Issues:
* Link to the fixed-function vertex chapter from the drawing chapter
(internal issue #110)
* Fix typo in slink:VkImageCreateInfo validity language:
ptext:maxExtent.sampleCounts -> pname:sampleCounts (internal issue
249).
* Explain why the non-core token etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
is used in the example in the
<<synchronization-semaphores,Semaphores>> section (internal issue
251).
* Attempt to clarify in the VK_KHR_android_surface extension's
<<platformQuerySupport_android,Android Platform Support>> section
that there is no Android-specific WSI query, and why (internal issue
252).
Other Commits:
* Add missing language about ename:VK_INCOMPLETE being returned from
array queries when the passed array is too short, in the
VK_KHR_display, VK_KHR_swapchain, and VK_KHR_surface extensions.
2016-04-01 10:04:38 +00:00
* pname:oldLayout = etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
2016-02-16 09:53:44 +00:00
* pname:newLayout = ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
Change log for August 5, 2016 Vulkan 1.0.23 spec update:
* Bump API patch number and header version number to 23 for this update.
Github Issues:
* Add explicit valid value attributes to pname:sType members in vk.xml
(public issue 34).
* Clarify usage of flink:vkGetInstanceProcAddr and
flink:vkGetDeviceProcAddr (public issue 225).
* Fix a copy-and-paste error in the description of
pname:pSwapchainImageCount saying that it was the count of ``format
pairs'' instead of ``swapchain images'' (public issue 292).
* flink:vkCmdExecuteCommandBuffers requires all command buffers to be
allocated from command pools created for the same queue family (public
issue 296).
* Remove bogus +optional+ attribute for
flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml
(public issue 301).
* Clean up the <<resources-image-views-compatibility,image and image view
compatibility table>> reference and contents. Use full enumerant names.
Refer to pname:layerCount in the ``view parameters'' column instead of
pname:arrayLayers. Require N >= 1 for the cube array subview row, not
just arrayLayers >= 6 N (public issue 304).
* Modify description of <<resources-memory-aliasing,memory aliasing>> to
be consistent with the description of
<<resources-bufferimagegranularity,buffer image granularity>> (public
issue 307).
Internal Issues:
* Describe remaining +vk_platform.h+ macros in the <<boilerplate,API
Boilerplate>> appendix (internal issue 6).
* Clarify
<<features-features-robustBufferAccess,pname:robustBufferAccess>>
feature behavior; what memory can be accessed, how bounds checking is
performed, and allowing for vectorization (internal issue 332).
* Document markup for automatic extraction of reference pages from the
spec sources in the style guide (internal issue 395).
* Allow flink:vkCreateDisplayModeKHR to return
ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode
parameters that the specified display does not support (internal issue
411).
* Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and
more clearly remove the subroutine keyword alongside it (internal issue
421).
* Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets
not contained in the layout (internal issue 427).
Other Commits:
* Change the order in which members of sname:VkAttachmentDescription and
sname:VkPipelineInputAssemblyStateCreateInfo are described to match
their order in the structures.
2016-08-05 12:11:02 +00:00
Alternatively, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
the image's contents need not be preserved.
2016-02-16 09:53:44 +00:00
This barrier accomplishes a dependency chain between previous presentation
operations and subsequent color attachment output operations, with the
layout transition performed in between, and does not introduce a dependency
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
between previous work and any vertex processing stages.
More precisely, the semaphore signals after the presentation operation
completes, then the semaphore wait stalls the
2016-02-16 09:53:44 +00:00
ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage, then there is a
dependency from that same stage to itself with the layout transition
performed in between.
====
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
endif::VK_KHR_swapchain[]
2016-02-16 09:53:44 +00:00
[[synchronization-events]]
== Events
2016-09-17 04:22:17 +00:00
// refBegin VkEvent Opaque handle to a event object
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Events are a synchronization primitive that can: be used to insert a
fine-grained dependency between commands submitted to the same queue, or
between the host and a queue.
Events have two states - signaled and unsignaled.
An application can: signal an event, or unsignal it, on either the host or
the device.
A device can: wait for an event to become signaled before executing further
operations.
No command exists to wait for an event to become signaled on the host, but
the current state of an event can: be queried.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
Events are represented by sname:VkEvent handles:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/handles/VkEvent.txt[]
2016-07-11 01:13:41 +00:00
// refEnd VkEvent
2016-09-17 04:22:17 +00:00
// refBegin vkCreateEvent Create a new event object
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
To create an event, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCreateEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that creates the event.
* pname:pCreateInfo is a pointer to an instance of the
sname:VkEventCreateInfo structure which contains information about how
the event is to be created.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pEvent points to a handle in which the resulting event object is
returned.
2016-07-11 01:13:41 +00:00
When created, the event object is in the unsignaled state.
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCreateEvent.txt[]
2016-09-17 04:22:17 +00:00
// refBegin VkEventCreateInfo Structure specifying parameters of a newly created event
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkEventCreateInfo structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkEventCreateInfo.txt[]
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
2016-07-11 01:13:41 +00:00
* pname:flags is reserved for future use.
2016-02-16 09:53:44 +00:00
include::../validity/structs/VkEventCreateInfo.txt[]
2016-07-11 01:13:41 +00:00
// refBegin vkDestroyEvent Destroy an event object
2016-02-16 09:53:44 +00:00
To destroy an event, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkDestroyEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that destroys the event.
* pname:event is the handle of the event to destroy.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* All submitted commands that refer to pname:event must: have completed
execution
* If sname:VkAllocationCallbacks were provided when pname:event was
created, a compatible set of callbacks must: be provided here
* If no sname:VkAllocationCallbacks were provided when pname:event was
created, pname:pAllocator must: be `NULL`
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkDestroyEvent.txt[]
2016-09-17 04:22:17 +00:00
// refBegin vkGetEventStatus Retrieve the status of an event object
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
To query the state of an event from the host, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkGetEventStatus.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the event.
* pname:event is the handle of the event to query.
Upon success, fname:vkGetEventStatus returns the state of the event object
with the following return codes:
2016-08-28 10:47:19 +00:00
.Event Object Status Codes
2016-02-16 09:53:44 +00:00
[width="80%",options="header"]
2016-09-17 04:22:17 +00:00
|====
2016-02-16 09:53:44 +00:00
| Status | Meaning
| ename:VK_EVENT_SET | The event specified by pname:event is signaled.
| ename:VK_EVENT_RESET | The event specified by pname:event is unsignaled.
2016-09-17 04:22:17 +00:00
|====
2016-02-16 09:53:44 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
If a fname:vkCmdSetEvent or fname:vkCmdResetEvent command is pending
execution, then the value returned by this command may: immediately be out
of date.
Change log for September 6, 2016 Vulkan 1.0.26 spec update:
* Bump API patch number and header version number to 26 for this update.
Github Issues:
* Bring sample code in the +VK_KHR_surface+ and +VK_KHR_swapchain+
extension summary appendices up to date, and note they will be replaced
with pointers to the LunarG SDK examples in the future (public issue
279).
* Add a new <<fundamentals-commandsyntax-results-lifetime,Lifetime of
Retrieved Results>> section specifying that ftext:vkGet* and
ftext:VkEnumerate* results are invariant unless otherwise specified, and
specify behavior for individual commands which are not invariant (public
issue 280).
* Remove conflicting definition of
slink:VkDisplayPlaneCapabilitiesKHR::pname:maxSrcPosition and clean up
language of the remaining definition (public issue 351).
* Fix many minor spelling errors and add rules to the style guide to
prevent recurrences (public issue 352).
Internal Issues:
* Remove redundant descriptions of the etext:VK_USE_PLATFORM_* macros from
the <<wsi,Window System Integration>> chapter in favor of the
description in the <<boilerplate-wsi-header,Window System-Specific
Header Control>> appendix (internal issue 6).
* Replace misleading 'can: be destroyed when not X' with more correct
'must: not be destroyed while X' in the
<<fundamentals-objectmodel-lifetime,Object Lifetime>> section. Disallow
destroying a pipeline layout while a command buffer using it is
recording (internal issue 241).
* Clarify that ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT is valid for
all images used as attachments in elink:VkImageUsageFlagBits and the
slink:VkImageLayout validity language (internal issue 320).
* Note that <<extended-functionality-layers,Layers>> may wrap object
handles, but that this is a generally discouraged. A link to additional
information in the documentation for layer authors is provided (issue
398)
* Replace the mustnot: and shouldnot: macros with equivalent must: not and
should: not to get rid of non-English words while still highlighting
normative language (internal issue 407).
* Disallow creating multisampled images with
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT in the slink:VkImageLayout
validity language and the <<features-supported-sample-counts,Supported
Sample Counts>> section (internal issue 445).
* Fix typo so that flink:vkCmdDrawIndexedIndirect is defined in terms of
flink:vkCmdDrawIndexed rather than flink:vkCmdDrawIndirect (internal
issue 446).
* Reorganize the per-extension information sections to all be in the
<<extensions,Layers & Extensions>> appendix. Also fix a typo in
+VK_IMG_filter_cubic+ which incorrectly identified it as a +KHR+
extension (internal issue 461).
Other Issues:
* Use asciidoc markup instead of latexmath to simplify diagrams in the
<<features-formats-non-packed,byte mapping tables>> for color formats.
* Fix a markup problem with the wildcarded enumerant names in a NOTE in
the <<textures-texel-replacement,Texel Replacement>> section.
* Fix missing attributes in the XML interface for
elink:VkExternalMemoryHandleTypeFlagBitsNV and
elink:VkExternalMemoryFeatureFlagBitsNV (KhronosGroup/Vulkan-Hpp issue
#25)
* Cleanup reference page builds so only core pages are built for releases.
2016-09-06 13:17:27 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
The state of an event can: be updated by the host.
The state of the event is immediately changed, and subsequent calls to
fname:vkGetEventStatus will return the new state.
If an event is already in the requested state, then updating it to the same
state has no effect.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkGetEventStatus.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-events-signaling-host]]
2016-09-17 04:22:17 +00:00
// refBegin vkSetEvent Set an event to signaled state
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
To set the state of an event to signaled from the host, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkSetEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the event.
* pname:event is the event to set.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When flink:vkSetEvent is executed on the host, it defines an _event signal
operation_ which sets the event to the signaled state.
If pname:event is already in the signaled state when flink:vkSetEvent is
executed, then flink:vkSetEvent has no effect, and no event signal operation
occurs.
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkSetEvent.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-events-unsignaling-host]]
2016-09-17 04:22:17 +00:00
// refBegin vkResetEvent Reset an event to non-signaled state
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
To set the state of an event to unsignaled from the host, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkResetEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:device is the logical device that owns the event.
* pname:event is the event to reset.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When flink:vkResetEvent is executed on the host, it defines an _event
unsignal operation_ which resets the event to the unsignaled state.
If pname:event is already in the unsignaled state when flink:vkResetEvent is
executed, then flink:vkResetEvent has no effect, and no event unsignal
operation occurs.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* pname:event must: not be waited on by a fname:vkCmdWaitEvents command
that is currently executing
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkResetEvent.txt[]
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
The state of an event can: also be updated on the device by commands
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
inserted in command buffers.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-events-signaling-device]]
// refBegin vkCmdSetEvent Set an event object to signaled state
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
To set the state of an event to signaled from a device, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdSetEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:commandBuffer is the command buffer into which the command is
recorded.
* pname:event is the event that will be signaled.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:stageMask specifies the <<synchronization-pipeline-stages,source
stage mask>> used to determine when the pname:event is signaled.
When flink:vkCmdSetEvent is submitted to a queue, it defines an execution
dependency on commands that were submitted before it, and defines an event
signal operation which sets the event to the signaled state.
The first <<synchronization-dependencies-scopes, synchronization scope>>
includes every command previously submitted to the same queue, including
those in the same command buffer and batch.
The synchronization scope is limited to operations on the pipeline stages
determined by the <<synchronization-pipeline-stages-masks, source stage
mask>> specified by pname:stageMask.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes only the event signal operation.
If pname:event is already in the signaled state when flink:vkCmdSetEvent is
executed on the device, then flink:vkCmdSetEvent has no effect, no event
signal operation occurs, and no execution dependency is generated.
2016-02-16 09:53:44 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:stageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
feature is not enabled, pname:stageMask must: not contain
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCmdSetEvent.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-events-unsignaling-device]]
2016-09-17 04:22:17 +00:00
// refBegin vkCmdResetEvent Reset an event object to non-signaled state
2016-07-11 01:13:41 +00:00
2016-02-16 09:53:44 +00:00
To set the state of an event to unsignaled from a device, call:
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdResetEvent.txt[]
2016-02-16 09:53:44 +00:00
* pname:commandBuffer is the command buffer into which the command is
recorded.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:event is the event that will be unsignaled.
* pname:stageMask specifies the <<synchronization-pipeline-stages,source
stage mask>> used to determine when the pname:event is unsignaled.
When flink:vkCmdResetEvent is submitted to a queue, it defines an execution
dependency on commands that were submitted before it, and defines an event
unsignal operation which resets the event to the unsignaled state.
The first <<synchronization-dependencies-scopes, synchronization scope>>
includes every command previously submitted to the same queue, including
those in the same command buffer and batch.
The synchronization scope is limited to operations on the pipeline stages
determined by the <<synchronization-pipeline-stages-masks, source stage
mask>> specified by pname:stageMask.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes only the event unsignal operation.
If pname:event is already in the unsignaled state when flink:vkCmdResetEvent
is executed on the device, then flink:vkCmdResetEvent has no effect, no
event unsignal operation occurs, and no execution dependency is generated.
2016-02-16 09:53:44 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:stageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
feature is not enabled, pname:stageMask must: not contain
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
* When this command executes, pname:event must: not be waited on by a
fname:vkCmdWaitEvents command that is currently executing
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCmdResetEvent.txt[]
2016-07-11 01:13:41 +00:00
// refBegin vkCmdWaitEvents Wait for one or more events and insert a set of memory
2016-02-16 09:53:44 +00:00
To wait for one or more events to enter the signaled state on a device,
call:
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-events-waiting-device]]
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdWaitEvents.txt[]
2016-02-16 09:53:44 +00:00
* pname:commandBuffer is the command buffer into which the command is
recorded.
* pname:eventCount is the length of the pname:pEvents array.
* pname:pEvents is an array of event object handles to wait on.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:srcStageMask is the <<synchronization-pipeline-stages, source
stage mask>>
* pname:dstStageMask is the <<synchronization-pipeline-stages, destination
stage mask>>.
* pname:memoryBarrierCount is the length of the pname:pMemoryBarriers
array.
* pname:pMemoryBarriers is a pointer to an array of slink:VkMemoryBarrier
structures.
* pname:bufferMemoryBarrierCount is the length of the
pname:pBufferMemoryBarriers array.
2016-02-16 09:53:44 +00:00
* pname:pBufferMemoryBarriers is a pointer to an array of
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
slink:VkBufferMemoryBarrier structures.
* pname:imageMemoryBarrierCount is the length of the
pname:pImageMemoryBarriers array.
2016-02-16 09:53:44 +00:00
* pname:pImageMemoryBarriers is a pointer to an array of
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
slink:VkImageMemoryBarrier structures.
When fname:vkCmdWaitEvents is submitted to a queue, it defines a memory
dependency between prior event signal operations, and subsequent commands.
The first synchronization scope only includes event signal operations that
operate on members of pname:pEvents, and the operations that happened-before
the event signal operations.
Event signal operations performed by flink:vkCmdSetEvent that were
previously submitted to the same queue are included in the first
synchronization scope, if the <<synchronization-pipeline-stages-order,
logically latest>> pipeline stage in their pname:stageMask parameter is
<<synchronization-pipeline-stages-order, logically earlier>> than or equal
to the <<synchronization-pipeline-stages-order, logically latest>> pipeline
stage in pname:srcStageMask.
Event signal operations performed by flink:vkSetEvent are only included in
the first synchronization scope if ename:VK_PIPELINE_STAGE_HOST_BIT is
included in pname:srcStageMask.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes commands subsequently submitted to the same queue, including those
in the same command buffer and batch.
The second synchronization scope is limited to operations on the pipeline
stages determined by the <<synchronization-pipeline-stages-masks,
destination stage mask>> specified by pname:dstStageMask.
The first <<synchronization-dependencies-access-scopes, access scope>> is
limited to access in the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, source stage mask>> specified by
pname:srcStageMask.
Within that, the first access scope only includes the first access scopes
defined by elements of the pname:pMemoryBarriers,
pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which
each define a set of <<synchronization-memory-barriers, memory barriers>>.
If no memory barriers are specified, then the first access scope includes no
accesses.
The second <<synchronization-dependencies-access-scopes, access scope>> is
limited to access in the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
by pname:dstStageMask.
Within that, the second access scope only includes the second access scopes
defined by elements of the pname:pMemoryBarriers,
pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which
each define a set of <<synchronization-memory-barriers, memory barriers>>.
If no memory barriers are specified, then the second access scope includes
no accesses.
[NOTE]
.Note
====
flink:vkCmdWaitEvents is used with flink:vkCmdSetEvent to define a memory
dependency between two sets of action commands, roughly in the same way as
pipeline barriers, but split into two commands such that work between the
two may: execute unhindered.
====
2016-02-16 09:53:44 +00:00
[NOTE]
.Note
====
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
Applications should: be careful to avoid race conditions when using events.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
There is no direct ordering guarantee between a flink:vkCmdResetEvent
command and a flink:vkCmdWaitEvents command submitted after it, so some
other execution dependency must: be included between these commands (e.g. a
semaphore).
2016-02-16 09:53:44 +00:00
====
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* pname:srcStageMask must: be the bitwise OR of the pname:stageMask
parameter used in previous calls to fname:vkCmdSetEvent with any of the
members of pname:pEvents and ename:VK_PIPELINE_STAGE_HOST_BIT if any of
the members of pname:pEvents was set using fname:vkSetEvent
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:srcStageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:dstStageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
feature is not enabled, pname:srcStageMask must: not contain
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
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 pname:pEvents includes one or more events that will be signaled by
fname:vkSetEvent after pname:commandBuffer has been submitted to a
queue, then fname:vkCmdWaitEvents must: not be called inside a render
pass instance
2016-12-02 11:32:05 +00:00
* Any pipeline stage included in pname:srcStageMask or pname:dstStageMask
must: be supported by the capabilities of the queue family specified by
the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo
structure that was used to create the sname:VkCommandPool that
pname:commandBuffer was allocated from, as specified in the
<<synchronization-pipeline-stages-supported, table of supported pipeline
stages>>.
* Any given element of pname:pMemoryBarriers, pname:pBufferMemoryBarriers
or pname:pImageMemoryBarriers must: not have any access flag included in
its pname:srcAccessMask member if that bit is not supported by any of
the pipeline stages in pname:srcStageMask, as specified in the
<<synchronization-access-types-supported, table of supported access
types>>.
* Any given element of pname:pMemoryBarriers, pname:pBufferMemoryBarriers
or pname:pImageMemoryBarriers must: not have any access flag included in
its pname:dstAccessMask member if that bit is not supported by any of
the pipeline stages in pname:dstStageMask, as specified in the
<<synchronization-access-types-supported, table of supported access
types>>.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
****
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkCmdWaitEvents.txt[]
2016-02-16 09:53:44 +00:00
[[synchronization-pipeline-barriers]]
== Pipeline Barriers
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
flink:vkCmdPipelineBarrier is a synchronization command that inserts a
dependency between commands submitted to the same queue, or between commands
in the same subpass.
2016-07-11 01:13:41 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
// refBegin vkCmdPipelineBarrier Insert a memory dependency
2016-07-11 01:13:41 +00:00
To record a pipeline barrier, call:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkCmdPipelineBarrier.txt[]
2016-02-16 09:53:44 +00:00
* pname:commandBuffer is the command buffer into which the command is
recorded.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:srcStageMask defines a <<synchronization-pipeline-stages-masks,
source stage mask>>.
* pname:dstStageMask defines a <<synchronization-pipeline-stages-masks,
destination stage mask>>.
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
* pname:dependencyFlags is a bitmask of elink:VkDependencyFlagBits.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The bits that can: be included in pname:dependencyFlags are:
+
--
// refBegin VkDependencyFlagBits Bitmask specifying how execution and memory dependencies are formed
include::../api/enums/VkDependencyFlagBits.txt[]
--
** ename:VK_DEPENDENCY_BY_REGION_BIT signifies that dependencies will be
<<synchronization-framebuffer-regions, framebuffer-local>>.
2016-02-16 09:53:44 +00:00
* pname:memoryBarrierCount is the length of the pname:pMemoryBarriers
array.
* pname:pMemoryBarriers is a pointer to an array of slink:VkMemoryBarrier
structures.
* pname:bufferMemoryBarrierCount is the length of the
pname:pBufferMemoryBarriers array.
* pname:pBufferMemoryBarriers is a pointer to an array of
slink:VkBufferMemoryBarrier structures.
* pname:imageMemoryBarrierCount is the length of the
pname:pImageMemoryBarriers array.
* pname:pImageMemoryBarriers is a pointer to an array of
slink:VkImageMemoryBarrier structures.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When flink:vkCmdPipelineBarrier is submitted to a queue, it defines a memory
dependency between commands that were submitted before it, and those
submitted after it.
If flink:vkCmdPipelineBarrier was recorded outside a render pass instance,
the first <<synchronization-dependencies-scopes, synchronization scope>>
includes every command submitted to the same queue before it, including
those in the same command buffer and batch.
If flink:vkCmdPipelineBarrier was recorded inside a render pass instance,
the first synchronization scope includes only commands submitted before it
within the same subpass.
In either case, the first synchronization scope is limited to operations on
the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, source stage mask>> specified by
pname:srcStageMask.
If flink:vkCmdPipelineBarrier was recorded outside a render pass instance,
the second <<synchronization-dependencies-scopes, synchronization scope>>
includes every command submitted to the same queue after it, including those
in the same command buffer and batch.
If flink:vkCmdPipelineBarrier was recorded inside a render pass instance,
the second synchronization scope includes only commands submitted after it
within the same subpass.
In either case, the second synchronization scope is limited to operations on
the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
by pname:dstStageMask.
The first <<synchronization-dependencies-access-scopes, access scope>> is
limited to access in the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, source stage mask>> specified by
pname:srcStageMask.
Within that, the first access scope only includes the first access scopes
defined by elements of the pname:pMemoryBarriers,
pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which
each define a set of <<synchronization-memory-barriers, memory barriers>>.
If no memory barriers are specified, then the first access scope includes no
accesses.
The second <<synchronization-dependencies-access-scopes, access scope>> is
limited to access in the pipeline stages determined by the
<<synchronization-pipeline-stages-masks, destination stage mask>> specified
by pname:dstStageMask.
Within that, the second access scope only includes the second access scopes
defined by elements of the pname:pMemoryBarriers,
pname:pBufferMemoryBarriers and pname:pImageMemoryBarriers arrays, which
each define a set of <<synchronization-memory-barriers, memory barriers>>.
If no memory barriers are specified, then the second access scope includes
no accesses.
If pname:dependencyFlags includes ename:VK_DEPENDENCY_BY_REGION_BIT, then
any dependency between <<synchronization-framebuffer-regions,
framebuffer-space>> pipeline stages is
<<synchronization-framebuffer-regions, framebuffer-local>> - otherwise it is
<<synchronization-framebuffer-regions, framebuffer-global>>.
2016-02-16 09:53:44 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:srcStageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-geometryShader,geometry shaders>> feature is
not enabled, pname:dstStageMask must: not contain
ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
feature is not enabled, pname:srcStageMask must: not contain
ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or
ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
* If the <<features-features-tessellationShader,tessellation shaders>>
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,
the render pass must: have been created with a sname:VkSubpassDependency
instance in pname:pDependencies that expresses a dependency from the
current subpass to itself.
Additionally:
** pname:srcStageMask must: contain a subset of the bit values in the
pname:srcStageMask member of that instance of sname:VkSubpassDependency
** pname:dstStageMask must: contain a subset of the bit values in the
pname:dstStageMask member of that instance of sname:VkSubpassDependency
** The pname:srcAccessMask of any element of pname:pMemoryBarriers or
pname:pImageMemoryBarriers must: contain a subset of the bit values the
pname:srcAccessMask member of that instance of
sname:VkSubpassDependency
** The pname:dstAccessMask of any element of pname:pMemoryBarriers or
pname:pImageMemoryBarriers must: contain a subset of the bit values the
pname:dstAccessMask member of that instance of
sname:VkSubpassDependency
** pname:dependencyFlags must: be equal to the pname:dependencyFlags
member of that instance of sname:VkSubpassDependency
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
pname:bufferMemoryBarrierCount must: be `0`
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
the pname:image member of any element of pname:pImageMemoryBarriers
must: be equal to one of the elements of pname:pAttachments that the
current pname:framebuffer was created with, that is also referred to by
one of the elements of the pname:pColorAttachments,
pname:pResolveAttachments or pname:pDepthStencilAttachment members of
the sname:VkSubpassDescription instance that the current subpass was
created with
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
the pname:oldLayout and pname:newLayout members of any element of
pname:pImageMemoryBarriers must: be equal to the pname:layout member of
an element of the pname:pColorAttachments, pname:pResolveAttachments or
pname:pDepthStencilAttachment members of the sname:VkSubpassDescription
instance that the current subpass was created with, that refers to the
same pname:image
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
the pname:oldLayout and pname:newLayout members of an element of
pname:pImageMemoryBarriers must: be equal
* If fname:vkCmdPipelineBarrier is called within a render pass instance,
the pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex members of
any element of pname:pImageMemoryBarriers must: be
ename:VK_QUEUE_FAMILY_IGNORED
2016-12-02 11:32:05 +00:00
* Any pipeline stage included in pname:srcStageMask or pname:dstStageMask
must: be supported by the capabilities of the queue family specified by
the pname:queueFamilyIndex member of the slink:VkCommandPoolCreateInfo
structure that was used to create the sname:VkCommandPool that
pname:commandBuffer was allocated from, as specified in the
<<synchronization-pipeline-stages-supported, table of supported pipeline
stages>>.
* Any given element of pname:pMemoryBarriers, pname:pBufferMemoryBarriers
or pname:pImageMemoryBarriers must: not have any access flag included in
its pname:srcAccessMask member if that bit is not supported by any of
the pipeline stages in pname:srcStageMask, as specified in the
<<synchronization-access-types-supported, table of supported access
types>>.
* Any given element of pname:pMemoryBarriers, pname:pBufferMemoryBarriers
or pname:pImageMemoryBarriers must: not have any access flag included in
its pname:dstAccessMask member if that bit is not supported by any of
the pipeline stages in pname:dstStageMask, as specified in the
<<synchronization-access-types-supported, table of supported access
types>>.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
****
2016-02-16 09:53:44 +00:00
include::../validity/protos/vkCmdPipelineBarrier.txt[]
[[synchronization-pipeline-barriers-subpass-self-dependencies]]
=== Subpass Self-dependency
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
If fname:vkCmdPipelineBarrier is called inside a render pass instance, the
following restrictions apply.
For a given subpass to allow a pipeline barrier, the render pass must:
declare a _self-dependency_ from that subpass to itself.
That is, there must: exist a sname:VkSubpassDependency in the subpass
dependency list for the render pass with pname:srcSubpass and
pname:dstSubpass equal to that subpass index.
More than one self-dependency can: be declared for each subpass.
Self-dependencies must: only include pipeline stage bits that are graphics
stages.
Self-dependencies must: not have any earlier pipeline stages depend on any
later pipeline stages.
More precisely, this means that whatever is the last pipeline stage in
2016-02-16 09:53:44 +00:00
pname:srcStageMask must: be no later than whatever is the first pipeline
stage in pname:dstStageMask (the latest source stage can: be equal to the
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
earliest destination stage).
If the source and destination stage masks both include framebuffer-space
stages, then pname:dependencyFlags must: include
2016-02-16 09:53:44 +00:00
ename:VK_DEPENDENCY_BY_REGION_BIT.
A fname:vkCmdPipelineBarrier command inside a render pass instance must: be
a _subset_ of one of the self-dependencies of the subpass it is used in,
meaning that the stage masks and access masks must: each include only a
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
subset of the bits of the corresponding mask in that self-dependency.
If the self-dependency has ename:VK_DEPENDENCY_BY_REGION_BIT set, then so
must: the pipeline barrier.
Pipeline barriers within a render pass instance can: only be types
sname:VkMemoryBarrier or sname:VkImageMemoryBarrier.
If a sname:VkImageMemoryBarrier is used, the image and image subresource
range specified in the barrier must: be a subset of one of the image views
used by the framebuffer in the current subpass.
Additionally, pname:oldLayout must: be equal to pname:newLayout, and both
the pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex must: be
ename:VK_QUEUE_FAMILY_IGNORED.
2016-02-16 09:53:44 +00:00
[[synchronization-memory-barriers]]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
== Memory Barriers
_Memory barriers_ are used to explicitly control access to buffer and image
subresource ranges.
Memory barriers are used to <<synchronization-queue-transfers, transfer
ownership between queue families>>,
<<synchronization-image-layout-transitions, change image layouts>>, and
define <<synchronization-dependencies-available-and-visible, availability
and visibility operations>>.
They explicitly define the <<synchronization-access-types, access types>>
and buffer and image subresource ranges that are included in the
<<synchronization-dependencies-access-scopes, access scopes>> of a memory
dependency that is created by a synchronization command that includes them.
[[synchronization-global-memory-barriers]]
2016-02-16 09:53:44 +00:00
=== Global Memory Barriers
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Global memory barriers apply to memory accesses involving all memory objects
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
that exist at the time of its execution.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
// refBegin VkMemoryBarrier Structure specifying a global memory barrier
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkMemoryBarrier structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkMemoryBarrier.txt[]
2016-02-16 09:53:44 +00:00
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:srcAccessMask defines a <<synchronization-access-masks, source
access mask>>.
* pname:dstAccessMask defines a <<synchronization-access-masks,
destination access mask>>.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The first <<synchronization-dependencies-access-scopes, access scope>> is
limited to access types in the <<synchronization-access-masks, source access
mask>> specified by pname:srcAccessMask.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The second <<synchronization-dependencies-access-scopes, access scope>> is
limited to access types in the <<synchronization-access-masks, destination
access mask>> specified by pname:dstAccessMask.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
include::../validity/structs/VkMemoryBarrier.txt[]
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-buffer-memory-barriers]]
2016-02-16 09:53:44 +00:00
=== Buffer Memory Barriers
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Buffer memory barriers only apply to memory accesses involving a specific
buffer range.
That is, a memory dependency formed from an buffer memory barrier is
<<synchronization-dependencies-access-scopes, scoped>> to access via the
specified buffer range.
Buffer memory barriers can: also be used to define a
<<synchronization-queue-transfers, queue family ownership transfer>> for the
specified buffer range.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
// refBegin VkBufferMemoryBarrier Structure specifying a buffer memory barrier
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkBufferMemoryBarrier structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkBufferMemoryBarrier.txt[]
2016-02-16 09:53:44 +00:00
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:srcAccessMask defines a <<synchronization-access-masks, source
access mask>>.
* pname:dstAccessMask defines a <<synchronization-access-masks,
destination access mask>>.
* pname:srcQueueFamilyIndex is the source queue family for a
<<synchronization-queue-transfers, queue family ownership transfer>>
* pname:dstQueueFamilyIndex is the destination queue family for a
<<synchronization-queue-transfers, queue family ownership transfer>>
2016-02-16 09:53:44 +00:00
* pname:buffer is a handle to the buffer whose backing memory is affected
by the barrier.
* pname:offset is an offset in bytes into the backing memory for
pname:buffer; this is relative to the base offset as bound to the buffer
(see flink:vkBindBufferMemory).
* pname:size is a size in bytes of the affected area of backing memory for
pname:buffer, or ename:VK_WHOLE_SIZE to use the range from pname:offset
to the end of the buffer.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The first <<synchronization-dependencies-access-scopes, access scope>> is
limited to access to the memory backing the specified buffer range, via
access types in the <<synchronization-access-masks, source access mask>>
specified by pname:srcAccessMask.
The second <<synchronization-dependencies-access-scopes, access scope>> is
limited to access to the memory backing the specified buffer range, via
access types in the <<synchronization-access-masks, destination access
mask>> specified by pname:dstAccessMask.
If pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, and
pname:srcQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a <<synchronization-queue-transfers-release, queue
family release operation>> for the specified buffer range, and the second
access scope includes no access, as if pname:dstAccessMask was `0`.
If pname:dstQueueFamilyIndex is not equal to pname:srcQueueFamilyIndex, and
pname:dstQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a <<synchronization-queue-transfers-acquire, queue
family acquire operation>> for the specified buffer range, and the first
access scope includes no access, as if pname:srcAccessMask was `0`.
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* pname:offset must: be less than the size of pname:buffer
* If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
greater than `0`
* If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
less than or equal to than the size of pname:buffer minus pname:offset
* If pname:buffer was created with a sharing mode of
ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED
* If pname:buffer was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: either both be
ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see
<<devsandqueues-queueprops>>)
* If pname:buffer was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, and pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex are valid queue families, at least one of them
must: be the same as the family of the queue that will execute this
barrier
****
2016-02-16 09:53:44 +00:00
include::../validity/structs/VkBufferMemoryBarrier.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-image-memory-barriers]]
2016-02-16 09:53:44 +00:00
=== Image Memory Barriers
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
Image memory barriers only apply to memory accesses involving a specific
image subresource range.
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
That is, a memory dependency formed from an image memory barrier is
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
<<synchronization-dependencies-access-scopes, scoped>> to access via the
specified image subresource range.
Image memory barriers can: also be used to define
<<synchronization-image-layout-transitions, image layout transitions>> or a
<<synchronization-queue-transfers, queue family ownership transfer>> for the
specified image subresource range.
2016-02-16 09:53:44 +00:00
2016-09-17 04:22:17 +00:00
// refBegin VkImageMemoryBarrier Structure specifying the parameters of an image memory barrier
2016-07-11 01:13:41 +00:00
2016-04-21 08:08:38 +00:00
The sname:VkImageMemoryBarrier structure is defined as:
2016-02-16 09:53:44 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/structs/VkImageMemoryBarrier.txt[]
2016-02-16 09:53:44 +00:00
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
* pname:srcAccessMask defines a <<synchronization-access-masks, source
access mask>>.
* pname:dstAccessMask defines a <<synchronization-access-masks,
destination access mask>>.
* pname:oldLayout is the old layout in an
<<synchronization-image-layout-transitions, image layout transition>>.
* pname:newLayout is the new layout in an
<<synchronization-image-layout-transitions, image layout transition>>.
* pname:srcQueueFamilyIndex is the source queue family for a
<<synchronization-queue-transfers, queue family ownership transfer>>
* pname:dstQueueFamilyIndex is the destination queue family for a
<<synchronization-queue-transfers, queue family ownership transfer>>
2016-02-16 09:53:44 +00:00
* pname:image is a handle to the image whose backing memory is affected by
the barrier.
* pname:subresourceRange describes an area of the backing memory for
pname:image (see <<resources-image-views>> for the description of
Change log for April 15, 2016 Vulkan 1.0.10 spec update:
* Bump API patch number and header version number to 10 for this
update.
Github Issues:
* Slightly tweak the <<memory-allocation,Host Memory>> allocator language
so that an application wrapping the standard C alloc/free/realloc
functions is still correct - the previous language was too strong with
regards to freeing memory. Also made certain scenarios clearer - an
implementation may now continue without error if an allocation failed
and it is able to continue correctly (public issue 21).
* Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the
corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the
<<sparsememory-miptail,Mip Tail Regions>> section and related commands
flink:vkCreateBuffer and flink:vkCreateImage (public issue 84).
* Update the <<features,Features, Limits, and Formats>> chapter to clarify
interactions between optional features and dynamic state for the
pname:depthBiasClamp and pname:wideLines features (public issue 89).
* Describe the code:WorkgroupSize builtin in the
<<interfaces-builtin-variables,Built-In Variables>> section, and update
the <<compute-shaders,Compute Shaders>> section to further clarify how
to set the number of workgroups to execute in a compute shader (public
issue 145).
* Use the term *image subresource* everywhere instead of *subresource*,
except for the special case of *host-accessible subresource*, which may
be either an image subresource or buffer range (public issue 120)
* Add a note to the <<features,Features, Limits, and Formats>> section
about extensibility of structures (Public issue 165).
* Fix return code flink:vkAcquireNextImageKHR when the timeout parameter
is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue
170).
* Fix typo in slink:VkLayerProperties::pname:apiVersion field (public
issue 172).
Internal Issues:
* Fix a few minor internally-detected typos.
* Minor formatting tweaks to pseudocode in the <<resources,Resource
Creation>> chapter (internal issue 179).
* Fix typo in the definition of point sampling for
elink:VkCullModeFlagBits (internal issue 268).
2016-04-14 08:58:49 +00:00
sname:VkImageSubresourceRange), as well as the set of image subresources
whose image layouts are modified.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The first <<synchronization-dependencies-access-scopes, access scope>> is
limited to access to the memory backing the specified image subresource
range, via access types in the <<synchronization-access-masks, source access
mask>> specified by pname:srcAccessMask.
The second <<synchronization-dependencies-access-scopes, access scope>> is
limited to access to the memory backing the specified image subresource
range, via access types in the <<synchronization-access-masks, destination
access mask>> specified by pname:dstAccessMask.
If pname:srcQueueFamilyIndex is not equal to pname:dstQueueFamilyIndex, and
pname:srcQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a <<synchronization-queue-transfers-release, queue
family release operation>> for the specified image subresource range, and
the second access scope includes no access, as if pname:dstAccessMask was
`0`.
If pname:dstQueueFamilyIndex is not equal to pname:srcQueueFamilyIndex, and
pname:dstQueueFamilyIndex is equal to the current queue family, then the
memory barrier defines a <<synchronization-queue-transfers-acquire, queue
family acquire operation>> for the specified image subresource range, and
the first access scope includes no access, as if pname:srcAccessMask was
`0`.
If pname:oldLayout is not equal to pname:newLayout, then the memory barrier
defines an <<synchronization-image-layout-transitions, image layout
transition>> for the specified image subresource range.
Layout transitions that are performed via image memory barriers
automatically happen-after layout transitions previously submitted to the
same queue, and automatically happen-before layout transitions subsequently
submitted to the same queue; this includes layout transitions that occur as
part of a render pass instance, in both cases.
2016-02-16 09:53:44 +00:00
Change log for September 30, 2016 Vulkan 1.0.29 spec update:
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
2016-10-01 04:13:37 +00:00
.Valid Usage
****
* pname:oldLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or the current
layout of the image subresources affected by the barrier
* pname:newLayout must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED
* If pname:image was created with a sharing mode of
ename:VK_SHARING_MODE_CONCURRENT, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: both be ename:VK_QUEUE_FAMILY_IGNORED
* If pname:image was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: either both be
ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see
<<devsandqueues-queueprops>>)
* If pname:image was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, and pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex are valid queue families, at least one of them
must: be the same as the family of the queue that will execute this
barrier
* pname:subresourceRange must: be a valid image subresource range for the
image (see <<resources-image-views>>)
* If pname:image has a depth/stencil format with both depth and stencil
components, then pname:aspectMask member of pname:subresourceRange must:
include both ename:VK_IMAGE_ASPECT_DEPTH_BIT and
ename:VK_IMAGE_ASPECT_STENCIL_BIT
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then pname:image must:
have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT set
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then pname:image
must: have been created with
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then pname:image
must: have been created with
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then pname:image must:
have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then pname:image must: have
been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
* If either pname:oldLayout or pname:newLayout is
ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then pname:image must: have
been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set
****
2016-07-11 01:13:41 +00:00
include::../validity/structs/VkImageMemoryBarrier.txt[]
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-queue-transfers]]
=== Queue Family Ownership Transfer
Resources created with a elink:VkSharingMode of
ename:VK_SHARING_MODE_EXCLUSIVE must: have their ownership explicitly
transferred from one queue family to another in order to access their
content in a well-defined manner on a queue in a different queue family.
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
accesses performed by the second queue family.
.Note
[NOTE]
====
If an application does not need the contents of a resource to remain valid
when transferring from one queue family to another, then the ownership
transfer should: be skipped.
====
A queue family ownership transfer consists of two distinct parts:
2016-12-02 11:32:05 +00:00
. Release exclusive ownership from the source queue family
. Acquire exclusive ownership for the destination queue family
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
An application must: ensure that these operations occur in the correct order
by defining an execution dependency between them, e.g. using a semaphore.
[[synchronization-queue-transfers-release]] A _release operation_ is used to
release exclusive ownership of a range of a buffer or image subresource
range.
A release operation is defined by executing a
<<synchronization-buffer-memory-barriers, buffer memory barrier>> (for a
buffer range) or an <<synchronization-image-memory-barriers, image memory
barrier>> (for an image subresource range), on a queue from the source queue
family.
The pname:srcQueueFamilyIndex parameter of the barrier must: be set to the
source queue family index, and the pname:dstQueueFamilyIndex parameter to
the destination queue family index.
pname:dstStageMask is ignored for such a barrier, such that no visibility
operation is executed - the value of this mask does not affect the validity
of the barrier.
The release operation happens-after the availability operation.
[[synchronization-queue-transfers-acquire]] An _acquire operation_ is used
to acquire exclusive ownership of a range of a buffer or image subresource
range.
An acquire operation is defined by executing a
<<synchronization-buffer-memory-barriers, buffer memory barrier>> (for a
buffer range) or an <<synchronization-image-memory-barriers, image memory
barrier>> (for an image subresource range), on a queue from the destination
queue family.
The pname:srcQueueFamilyIndex parameter of the barrier must: be set to the
source queue family index, and the pname:dstQueueFamilyIndex parameter to
the destination queue family index.
pname:srcStageMask is ignored for such a barrier, such that no availability
operation is executed - the value of this mask does not affect the validity
of the barrier.
The acquire operation happens-before the visibility operation.
.Note
[NOTE]
====
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
for those accesses has no practical effect.
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
both sides - but this was subsequently relaxed.
It is now recommended that these masks are simply set to 0.
====
If the transfer is via an image memory barrier, and an
<<synchronization-image-layout-transitions, image layout transition>> is
desired, then the values of pname:oldLayout and pname:newLayout in the
release memory barrier must: be equal to values of pname:oldLayout and
pname:newLayout in the acquire memory barrier.
Although the image layout transition is submitted twice, it will only be
executed once.
A layout transition specified in this way happens-after the release
operation and happens-before the acquire operation.
If the values of pname:srcQueueFamilyIndex and pname:dstQueueFamilyIndex are
equal, no ownership transfer is performed, and the barrier operates as if
they were both set to ename:VK_QUEUE_FAMILY_IGNORED.
Queue family ownership transfers may: perform read and write accesses on all
memory bound to the image subresource or buffer range, so applications must:
ensure that all memory writes have been made
<<synchronization-dependencies-available-and-visible, available>> before a
queue family ownership transfer is executed.
Available memory is automatically made visible to queue family release and
acquire operations, and writes performed by those operations are
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
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
after a release or acquire operation.
[[synchronization-wait-idle]]
== Wait Idle Operations
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
2016-09-17 04:22:17 +00:00
// refBegin vkQueueWaitIdle Wait for a queue to become idle
2016-07-11 01:13:41 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
To wait on the host for the completion of outstanding queue operations for a
given queue, call:
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkQueueWaitIdle.txt[]
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
* pname:queue is the queue on which to wait.
fname:vkQueueWaitIdle is equivalent to submitting a fence to a queue and
waiting with an infinite timeout for that fence to signal.
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkQueueWaitIdle.txt[]
2016-09-17 04:22:17 +00:00
// refBegin vkDeviceWaitIdle Wait for a device to become idle
2016-07-11 01:13:41 +00:00
Change log for September 23, 2016 Vulkan 1.0.28 spec update:
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
2016-09-24 07:58:11 +00:00
To wait on the host for the completion of outstanding queue operations for
all queues on a given logical device, call:
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
Change log for July 22, 2016 Vulkan 1.0.22 spec update:
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
2016-07-23 10:15:48 +00:00
include::../api/protos/vkDeviceWaitIdle.txt[]
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
* pname:device is the logical device to idle.
fname:vkDeviceWaitIdle is equivalent to calling fname:vkQueueWaitIdle for
all queues owned by pname:device.
2016-02-16 09:53:44 +00:00
2016-07-11 01:13:41 +00:00
include::../validity/protos/vkDeviceWaitIdle.txt[]
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
[[synchronization-submission-host-writes]]
Change log for June 24, 2016 Vulkan 1.0.18 spec update:
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
2016-06-23 10:18:00 +00:00
== Host Write Ordering Guarantees
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
When batches of command buffers are submitted to a queue via
flink:vkQueueSubmit, it defines a memory dependency with prior host
operations, and execution of command buffers submitted to the queue.
The first <<synchronization-dependencies-scopes, synchronization scope>> is
defined by the host execution model, but includes execution of
flink:vkQueueSubmit on the host and anything that happened-before it.
The second <<synchronization-dependencies-scopes, synchronization scope>>
includes every command submitted in the same <<devsandqueues-submission,
queue submission>> command, and all future submissions to the same queue.
The first <<synchronization-dependencies-access-scopes, access scope>>
includes all host writes to mappable device memory that are either coherent,
or have been flushed with flink:vkFlushMappedMemoryRanges.
2016-02-16 09:53:44 +00:00
Change log for November 25, 2016 Vulkan 1.0.35 spec update:
* Bump API patch number and header version number to 35 for this update.
Github Issues:
* Document in the <<memory-device-hostaccess,Host Access>> section that
mapping and unmapping does not invalidate or flush the mapped memory
(public issues 27, 126).
* Redefine the entire <<synchronization>> chapter in terms of consistent
and well defined terminology, that's called out at the start of the
chapter. This terminology is applied equally to all synchronization
types, including subpass dependencies, submissions, and much of the
implicit ordering stuff dotted around the spec. Key terms are laid out
in the <<synchronization-dependencies,Execution and Memory
Dependencies>> section at the top of the rewritten chapter (public
issues 128, 131, 132, 217, 299, 300, 302, 306, 322, 346, 347, 371, 407).
* Specify order of submission for batches in the
<<vkQueueSubmit,vkQueueSubmit>> and
<<vkQueueBindSparse,vkQueueBindSparse>> commands (public issue 371).
* Add valid usage statements to each of the WSI extension sections
indicating that the WSI-specific structure parameters must be valid, and
remove automatically generated valid usage statements now covered by the
manual sections (public issue 383).
* Clarify render pass compatibility for flink:vkCmdExecuteCommands (public
issue 390).
Internal Issues:
* Update +vk.xml+ to make previously explicit valid usage statements for
<<vkDebugReportMessageEXT,vkDebugReportMessageEXT>> implicit instead
(internal issue 553).
* Add valid usage statement for slink:VkCreateImageInfo preventing
creation of 1D sparse images (internal issue 573).
* Fix Python scripts to always read/write files in utf-8 encoding, and a
logic error in reflib.py which could cause a fatal error for
malstructured asciidoc (internal issues 578, 586).
2016-11-26 10:33:44 +00:00
The second <<synchronization-dependencies-access-scopes, access scope>>
includes all memory access performed by the device.
