1// Copyright (c) 2018-2020 Advanced Micro Devices, Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[copies-buffer-markers]]
6== Buffer Markers
7
8ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[]
9[open,refpage='vkCmdWriteBufferMarker2AMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
10--
11:refpage: vkCmdWriteBufferMarker2AMD
12
13To write a 32-bit marker value into a buffer as a pipelined operation, call:
14
15include::{generated}/api/protos/vkCmdWriteBufferMarker2AMD.adoc[]
16
17  * pname:commandBuffer is the command buffer into which the command will be
18    recorded.
19  * pname:stage specifies the pipeline stage whose completion triggers the
20    marker write.
21  * pname:dstBuffer is the buffer where the marker will be written.
22  * pname:dstOffset is the byte offset into the buffer where the marker will
23    be written.
24  * pname:marker is the 32-bit value of the marker.
25
26The command will write the 32-bit marker value into the buffer only after
27all preceding commands have finished executing up to at least the specified
28pipeline stage.
29This includes the completion of other preceding
30fname:vkCmdWriteBufferMarker2AMD commands so long as their specified
31pipeline stages occur either at the same time or earlier than this command's
32specified pname:stage.
33
34While consecutive buffer marker writes with the same pname:stage parameter
35implicitly complete in submission order, memory and execution dependencies
36between buffer marker writes and other operations must: still be explicitly
37ordered using synchronization commands.
38The access scope for buffer marker writes falls under the
39ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
40the synchronization scope must: include both pname:stage and
41ename:VK_PIPELINE_STAGE_TRANSFER_BIT.
42
43[NOTE]
44.Note
45====
46Similar to fname:vkCmdWriteTimestamp2, if an implementation is unable to
47write a marker at any specific pipeline stage, it may: instead do so at any
48logically later stage.
49====
50
51[NOTE]
52.Note
53====
54Implementations may: only support a limited number of pipelined marker write
55operations in flight at a given time.
56Thus an excessive number of marker write operations may: degrade command
57execution performance.
58====
59
60.Valid Usage
61****
62:stageMaskName: stage
63include::{chapters}/commonvalidity/stage_mask_2_common.adoc[]
64  * [[VUID-vkCmdWriteBufferMarker2AMD-synchronization2-03893]]
65    The <<features-synchronization2, pname:synchronization2>> feature must:
66    be enabled
67  * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03894]]
68    pname:stage must: include only a single pipeline stage
69  * [[VUID-vkCmdWriteBufferMarker2AMD-stage-03895]]
70    pname:stage must: include only stages that are valid for the queue
71    family that was used to create the command pool that pname:commandBuffer
72    was allocated from
73  * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03896]]
74    pname:dstOffset must: be less than or equal to the size of
75    pname:dstBuffer minus `4`
76  * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03897]]
77    pname:dstBuffer must: have been created with the
78    ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
79  * [[VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03898]]
80    If pname:dstBuffer is non-sparse then it must: be bound completely and
81    contiguously to a single sname:VkDeviceMemory object
82  * [[VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03899]]
83    pname:dstOffset must: be a multiple of `4`
84****
85
86include::{generated}/validity/protos/vkCmdWriteBufferMarker2AMD.adoc[]
87--
88endif::VK_VERSION_1_3,VK_KHR_synchronization2[]
89
90[open,refpage='vkCmdWriteBufferMarkerAMD',desc='Execute a pipelined write of a marker value into a buffer',type='protos']
91--
92:refpage: vkCmdWriteBufferMarkerAMD
93
94To write a 32-bit marker value into a buffer as a pipelined operation, call:
95
96include::{generated}/api/protos/vkCmdWriteBufferMarkerAMD.adoc[]
97
98  * pname:commandBuffer is the command buffer into which the command will be
99    recorded.
100  * pname:pipelineStage is a elink:VkPipelineStageFlagBits value specifying
101    the pipeline stage whose completion triggers the marker write.
102  * pname:dstBuffer is the buffer where the marker will be written to.
103  * pname:dstOffset is the byte offset into the buffer where the marker will
104    be written to.
105  * pname:marker is the 32-bit value of the marker.
106
107The command will write the 32-bit marker value into the buffer only after
108all preceding commands have finished executing up to at least the specified
109pipeline stage.
110This includes the completion of other preceding
111fname:vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline
112stages occur either at the same time or earlier than this command's
113specified pname:pipelineStage.
114
115While consecutive buffer marker writes with the same pname:pipelineStage
116parameter are implicitly complete in submission order, memory and execution
117dependencies between buffer marker writes and other operations must still be
118explicitly ordered using synchronization commands.
119The access scope for buffer marker writes falls under the
120ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
121the synchronization scope must: include both pname:pipelineStage and
122ename:VK_PIPELINE_STAGE_TRANSFER_BIT.
123
124[NOTE]
125.Note
126====
127Similar to fname:vkCmdWriteTimestamp, if an implementation is unable to
128write a marker at any specific pipeline stage, it may: instead do so at any
129logically later stage.
130====
131
132[NOTE]
133.Note
134====
135Implementations may: only support a limited number of pipelined marker write
136operations in flight at a given time, thus excessive number of marker write
137operations may: degrade command execution performance.
138====
139
140.Valid Usage
141****
142include::{chapters}/commonvalidity/pipeline_stage_common.adoc[]
143  * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798]]
144    pname:dstOffset must: be less than or equal to the size of
145    pname:dstBuffer minus `4`
146  * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799]]
147    pname:dstBuffer must: have been created with
148    ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
149  * [[VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01800]]
150    If pname:dstBuffer is non-sparse then it must: be bound completely and
151    contiguously to a single sname:VkDeviceMemory object
152  * [[VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801]]
153    pname:dstOffset must: be a multiple of `4`
154****
155
156include::{generated}/validity/protos/vkCmdWriteBufferMarkerAMD.adoc[]
157--
158