// 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[]
--