mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-01 00:55:16 +00:00
6db51e9241
* Bump API patch number and header version number to 11 for this
update.
Github Issues:
* Clarify the WSI extension language by switching from the fuzzier
"ownership" language to more-consistent "acquire" language (public
issue 117).
* Clarify that memory barriers apply to all commands in the dependency
chains in the flink:vkGetRenderAreaGranularity command and the
<<synchronization-execution-and-memory-dependencies,Execution And
Memory Dependencies>> section (public issue 132).
* Clarify that a queue family is a set of queues in the
<<fundamentals-execmodel,Execution Model>> section (public issue
166).
* Removed requirement from valid usage language that
VkPresentInfoKHR::waitSemaphoreCount must be greater than 0 (public
issue 171).
* Fix broken internal links, describe structures consistently, use
consistent style for SPIR-V codewords, and tag normative terms that
were missing asciidoc tags (public issue 183 and ancillary
markup/normative language fixes).
* Fix typos for slink:VkPhysicalDeviceLimits member names in
slink:VkImageCreateInfo validity language (public issue 184).
Internal Issues:
* Document that the requested patch version number specified as part
of slink:VkApplicationInfo::pname:apiVersion is ignored when
creating an instance (internal issue 176).
* Clarify handling of extension structs in the
<<fundamentals-validusageValid Usage>> section (internal issue 254).
* Update required slink:VkImageFormatProperties::pname:maxMipLevels to
be limited to the maximum allowed mipmap pyramid size corresponding
to the actual maximum supported size for the format (internal issue
256).
* Modify the <<features-extentperimagetype,Allowed Extent Values Based
On Image Type>> section so the allowed maximum extent is the maximum
image dimension supported for each dimension of the type of texture
being queried (internal issue 257).
* Clarify in the <<spirvenv-module-validation,Validation Rules within
a Module>> section that at least one of the code:LocalSize execution
mode or code:WorkgroupSize decoration is required for each compute
shader entry point in a shader module (internal issue 279).
* Add validity rules for formats in flink:vkCmdClearColorImage and
flink:vkCmdClearDepthStencilImage (internal issue 283).
* Clarify that slink:VkImageFormatProperties::pname:maxResourceSize is
an upper bound, and that it may not be possible to create an image
anywhere near that size (internal issue 284).
Other Commits:
* Fix various minor markup errors reported by validation scripts.
* Change copyright from Khronos Free Use License to Apache 2.0 license
on relevant script/XML/header files. This does not affect the
specification source copyright.
95 lines
4.2 KiB
Plaintext
95 lines
4.2 KiB
Plaintext
vkBeginCommandBuffer(3)
|
|
=======================
|
|
|
|
Name
|
|
----
|
|
vkBeginCommandBuffer - Start recording a command buffer
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
include::../protos/vkBeginCommandBuffer.txt[]
|
|
|
|
Parameters
|
|
----------
|
|
|
|
pname:commandBuffer::
|
|
A handle to the command buffer that is to be recorded.
|
|
|
|
pname:pBeginInfo::
|
|
A pointer to an instance of slink:VkCommandBufferBeginInfo containing information about the command buffer.
|
|
|
|
Description
|
|
-----------
|
|
|
|
fname:vkBeginCommandBuffer begins recording the command buffer whose handle is
|
|
specified in pname:commandBuffer. pname:pBeginInfo is a pointer to an instance of the slink:VkCommandBufferBeginInfo
|
|
structure whose definition is:
|
|
|
|
include::../structs/VkCommandBufferBeginInfo.txt[]
|
|
|
|
The ptext:sType member of slink:VkCommandBufferBeginInfo should be set to
|
|
ename:VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO and the ptext:pNext member of the structure
|
|
is reserved for extensions and should be set to code:NULL if none are in use.
|
|
|
|
The pname:flags member of pname:pBeginInfo may be used to indicate the type of workload
|
|
expected to be placed in the command buffer, which may allow implementations
|
|
to optimize command buffer contents more appropriately. The available flags for use
|
|
in this member are:
|
|
|
|
include::../enums/VkCommandBufferUsageFlagBits.txt[]
|
|
|
|
If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
|
|
then the command buffer may only be submitted to a queue for execution once,
|
|
after which time it must be reset or destroyed. If this flag is not included,
|
|
then it is legal to submit the command buffer many times.
|
|
|
|
If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
|
|
then the command buffer must be a secondary command buffer (see flink:vkAllocateCommandBuffers
|
|
for more information) and is considered to be entirely contained inside a renderpass
|
|
that is begun in the calling primary command buffer. In such a case, the pname:renderPass,
|
|
pname:subpass and pname:framebuffer members refer to the renderpass, subpass and framebuffer
|
|
that will be active when the command buffer is referenced with a call to flink:vkCmdExecuteCommands.
|
|
|
|
If ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT is not set, then the pname:renderPass,
|
|
pname:subpass and pname:framebuffer members are ignored. If the command buffer is a primary
|
|
command buffer, then new renderpasses may be initiated by calls to flink:vkCmdBeginRenderPass.
|
|
If the command buffer is a secondary command buffer, then it may not contain commands that
|
|
are legal only inside a renderpass, and may not be called from a primary command buffer
|
|
while a renderpass is active.
|
|
|
|
If the pname:flags member contains ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT,
|
|
then multiple submissions of the command buffer may be in flight simultaneously.
|
|
|
|
* A primary command buffer is considered to be in flight from the time it is submitted
|
|
to a queue by a call to flink:vkQueueSubmit until the time it is retired (signaling
|
|
the fence passed to the call to flink:vkQueueSubmit).
|
|
|
|
* A secondary command buffer is considered to be in flight from a reference to it
|
|
it is made from a primary command buffer using a call to flink:vkCmdExecuteCommands
|
|
until that primary command buffer is retired.
|
|
|
|
If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set,
|
|
then only one invocation of the command buffer may be in flight at any time.
|
|
|
|
It should be noted that for primary command buffers,
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT implies possible multiple submission
|
|
of the command buffer, suggesting that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
|
|
should be clear. Secondary command buffers may be referenced at most once from
|
|
a primary command buffer (even the same primary command buffer) unless
|
|
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is set.
|
|
|
|
The pname:renderPass and pname:framebuffer members must be code:VK_NULL_HANDLE
|
|
for primary command buffers. For secondary command buffers, they must refer to
|
|
the render pass and framebuffer that will be active when the secondary command
|
|
buffer is called.
|
|
|
|
include::../validity/protos/vkBeginCommandBuffer.txt[]
|
|
|
|
See Also
|
|
--------
|
|
|
|
flink:vkAllocateCommandBuffers, flink:vkFreeCommandBuffers, flink:vkEndCommandBuffer, flink:vkResetCommandBuffer
|
|
|
|
include::footer.txt[]
|