registry/vulkan/chapters/VK_AMD_buffer_marker/copies.txt - third_party/platform/external/gfxstream-protocols - Git at Google

 // Copyright (c) 2018-2020 Advanced Micro Devices, Inc.
 //
 // SPDX-License-Identifier: CC-BY-4.0

 [[copies-buffer-markers]]
 == Buffer Markers

 ifdef::VK_KHR_synchronization2[]

 [open,refpage='vkCmdWriteBufferMarker2AMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
 --
 :refpage: vkCmdWriteBufferMarker2AMD

 To write a 32-bit marker value into a buffer as a pipelined operation, call:

 include::{generated}/api/protos/vkCmdWriteBufferMarker2AMD.txt[]

   * pname:commandBuffer is the command buffer into which the command will be
     recorded.
   * pname:stage specifies the pipeline stage whose completion triggers the
     marker write.
   * pname:dstBuffer is the buffer where the marker will be written.
   * pname:dstOffset is the byte offset into the buffer where the marker will
     be written.
   * pname:marker is the 32-bit value of the marker.

 The command will write the 32-bit marker value into the buffer only after
 all preceding commands have finished executing up to at least the specified
 pipeline stage.
 This includes the completion of other preceding
 fname:vkCmdWriteBufferMarker2AMD commands so long as their specified
 pipeline stages occur either at the same time or earlier than this command's
 specified pname:stage.

 While consecutive buffer marker writes with the same pname:stage parameter
 implicitly complete in submission order, memory and execution dependencies
 between buffer marker writes and other operations must: still be explicitly
 ordered using synchronization commands.
 The access scope for buffer marker writes falls under the
 ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
 the synchronization scope must: include both pname:stage and
 ename:VK_PIPELINE_STAGE_TRANSFER_BIT.

 [NOTE]
 .Note
 ====
 Similar to fname:vkCmdWriteTimestamp2KHR, if an implementation is unable to
 write a marker at any specific pipeline stage, it may: instead do so at any
 logically later stage.
 ====

 [NOTE]
 .Note
 ====
 Implementations may: only support a limited number of pipelined marker write
 operations in flight at a given time.
 Thus an excessive number of marker write operations may: degrade command
 execution performance.
 ====

 .Valid Usage
 ****
 :stageMaskName: stage
 include::{chapters}/commonvalidity/stage_mask_2_common.txt[]
   * [[VUID-vkCmdWriteBufferMarker2AMD-synchronization2-03893]]
     The <<features-synchronization2, pname:synchronization2>> feature must:
     be enabled
   * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03894]]
     pname:stage must: include only a single pipeline stage
   * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03895]]
     pname:stage must: include only stages that are valid for the queue
     family that was used to create the command pool that pname:commandBuffer
     was allocated from
   * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03896]]
     pname:dstOffset must: be less than or equal to the size of
     pname:dstBuffer minus `4`
   * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03897]]
     pname:dstBuffer must: have been created with the
     ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
   * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03898]]
     If pname:dstBuffer is non-sparse then it must: be bound completely and
     contiguously to a single sname:VkDeviceMemory object
   * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03899]]
     pname:dstOffset must: be a multiple of `4`
 ****

 include::{generated}/validity/protos/vkCmdWriteBufferMarker2AMD.txt[]
 --
 endif::VK_KHR_synchronization2[]

 [open,refpage='vkCmdWriteBufferMarkerAMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
 --
 :refpage: vkCmdWriteBufferMarkerAMD

 To write a 32-bit marker value into a buffer as a pipelined operation, call:

 include::{generated}/api/protos/vkCmdWriteBufferMarkerAMD.txt[]

   * pname:commandBuffer is the command buffer into which the command will be
     recorded.
   * pname:pipelineStage is a elink:VkPipelineStageFlagBits value specifying
     the pipeline stage whose completion triggers the marker write.
   * pname:dstBuffer is the buffer where the marker will be written to.
   * pname:dstOffset is the byte offset into the buffer where the marker will
     be written to.
   * pname:marker is the 32-bit value of the marker.

 The command will write the 32-bit marker value into the buffer only after
 all preceding commands have finished executing up to at least the specified
 pipeline stage.
 This includes the completion of other preceding
 fname:vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline
 stages occur either at the same time or earlier than this command's
 specified pname:pipelineStage.

 While consecutive buffer marker writes with the same pname:pipelineStage
 parameter are implicitly complete in submission order, memory and execution
 dependencies between buffer marker writes and other operations must still be
 explicitly ordered using synchronization commands.
 The access scope for buffer marker writes falls under the
 ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
 the synchronization scope must: include both pname:pipelineStage and
 ename:VK_PIPELINE_STAGE_TRANSFER_BIT.

 [NOTE]
 .Note
 ====
 Similar to fname:vkCmdWriteTimestamp, if an implementation is unable to
 write a marker at any specific pipeline stage, it may: instead do so at any
 logically later stage.
 ====

 [NOTE]
 .Note
 ====
 Implementations may: only support a limited number of pipelined marker write
 operations in flight at a given time, thus excessive number of marker write
 operations may: degrade command execution performance.
 ====

 .Valid Usage
 ****
 include::{chapters}/commonvalidity/pipeline_stage_common.txt[]
   * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798]]
     pname:dstOffset must: be less than or equal to the size of
     pname:dstBuffer minus `4`
   * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799]]
     pname:dstBuffer must: have been created with
     ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
   * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01800]]
     If pname:dstBuffer is non-sparse then it must: be bound completely and
     contiguously to a single sname:VkDeviceMemory object
   * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801]]
     pname:dstOffset must: be a multiple of `4`
 ****

 include::{generated}/validity/protos/vkCmdWriteBufferMarkerAMD.txt[]
 --
	// Copyright (c) 2018-2020 Advanced Micro Devices, Inc.
	//
	// SPDX-License-Identifier: CC-BY-4.0

	[[copies-buffer-markers]]
	== Buffer Markers

	ifdef::VK_KHR_synchronization2[]

	[open,refpage='vkCmdWriteBufferMarker2AMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
	--
	:refpage: vkCmdWriteBufferMarker2AMD

	To write a 32-bit marker value into a buffer as a pipelined operation, call:

	include::{generated}/api/protos/vkCmdWriteBufferMarker2AMD.txt[]

	* pname:commandBuffer is the command buffer into which the command will be
	recorded.
	* pname:stage specifies the pipeline stage whose completion triggers the
	marker write.
	* pname:dstBuffer is the buffer where the marker will be written.
	* pname:dstOffset is the byte offset into the buffer where the marker will
	be written.
	* pname:marker is the 32-bit value of the marker.

	The command will write the 32-bit marker value into the buffer only after
	all preceding commands have finished executing up to at least the specified
	pipeline stage.
	This includes the completion of other preceding
	fname:vkCmdWriteBufferMarker2AMD commands so long as their specified
	pipeline stages occur either at the same time or earlier than this command's
	specified pname:stage.

	While consecutive buffer marker writes with the same pname:stage parameter
	implicitly complete in submission order, memory and execution dependencies
	between buffer marker writes and other operations must: still be explicitly
	ordered using synchronization commands.
	The access scope for buffer marker writes falls under the
	ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
	the synchronization scope must: include both pname:stage and
	ename:VK_PIPELINE_STAGE_TRANSFER_BIT.

	[NOTE]
	.Note
	====
	Similar to fname:vkCmdWriteTimestamp2KHR, if an implementation is unable to
	write a marker at any specific pipeline stage, it may: instead do so at any
	logically later stage.
	====

	[NOTE]
	.Note
	====
	Implementations may: only support a limited number of pipelined marker write
	operations in flight at a given time.
	Thus an excessive number of marker write operations may: degrade command
	execution performance.
	====

	.Valid Usage
	****
	:stageMaskName: stage
	include::{chapters}/commonvalidity/stage_mask_2_common.txt[]
	* [[VUID-vkCmdWriteBufferMarker2AMD-synchronization2-03893]]
	The <<features-synchronization2, pname:synchronization2>> feature must:
	be enabled
	* [[VUID-vkCmdWriteBufferMarker2AMD-stage-03894]]
	pname:stage must: include only a single pipeline stage
	* [[VUID-vkCmdWriteBufferMarker2AMD-stage-03895]]
	pname:stage must: include only stages that are valid for the queue
	family that was used to create the command pool that pname:commandBuffer
	was allocated from
	* [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03896]]
	pname:dstOffset must: be less than or equal to the size of
	pname:dstBuffer minus `4`
	* [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03897]]
	pname:dstBuffer must: have been created with the
	ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
	* [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03898]]
	If pname:dstBuffer is non-sparse then it must: be bound completely and
	contiguously to a single sname:VkDeviceMemory object
	* [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03899]]
	pname:dstOffset must: be a multiple of `4`
	****

	include::{generated}/validity/protos/vkCmdWriteBufferMarker2AMD.txt[]
	--
	endif::VK_KHR_synchronization2[]

	[open,refpage='vkCmdWriteBufferMarkerAMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
	--
	:refpage: vkCmdWriteBufferMarkerAMD

	To write a 32-bit marker value into a buffer as a pipelined operation, call:

	include::{generated}/api/protos/vkCmdWriteBufferMarkerAMD.txt[]

	* pname:commandBuffer is the command buffer into which the command will be
	recorded.
	* pname:pipelineStage is a elink:VkPipelineStageFlagBits value specifying
	the pipeline stage whose completion triggers the marker write.
	* pname:dstBuffer is the buffer where the marker will be written to.
	* pname:dstOffset is the byte offset into the buffer where the marker will
	be written to.
	* pname:marker is the 32-bit value of the marker.

	The command will write the 32-bit marker value into the buffer only after
	all preceding commands have finished executing up to at least the specified
	pipeline stage.
	This includes the completion of other preceding
	fname:vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline
	stages occur either at the same time or earlier than this command's
	specified pname:pipelineStage.

	While consecutive buffer marker writes with the same pname:pipelineStage
	parameter are implicitly complete in submission order, memory and execution
	dependencies between buffer marker writes and other operations must still be
	explicitly ordered using synchronization commands.
	The access scope for buffer marker writes falls under the
	ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
	the synchronization scope must: include both pname:pipelineStage and
	ename:VK_PIPELINE_STAGE_TRANSFER_BIT.

	[NOTE]
	.Note
	====
	Similar to fname:vkCmdWriteTimestamp, if an implementation is unable to
	write a marker at any specific pipeline stage, it may: instead do so at any
	logically later stage.
	====

	[NOTE]
	.Note
	====
	Implementations may: only support a limited number of pipelined marker write
	operations in flight at a given time, thus excessive number of marker write
	operations may: degrade command execution performance.
	====

	.Valid Usage
	****
	include::{chapters}/commonvalidity/pipeline_stage_common.txt[]
	* [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798]]
	pname:dstOffset must: be less than or equal to the size of
	pname:dstBuffer minus `4`
	* [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799]]
	pname:dstBuffer must: have been created with
	ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
	* [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01800]]
	If pname:dstBuffer is non-sparse then it must: be bound completely and
	contiguously to a single sname:VkDeviceMemory object
	* [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801]]
	pname:dstOffset must: be a multiple of `4`
	****

	include::{generated}/validity/protos/vkCmdWriteBufferMarkerAMD.txt[]
	--