# vkCmdWriteBufferMarkerAMD(3) Manual Page

## Name

vkCmdWriteBufferMarkerAMD - Execute a pipelined write of a marker value into a buffer

## C Specification

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

    void vkCmdWriteBufferMarkerAMD(
        VkCommandBuffer                             commandBuffer,
        VkPipelineStageFlagBits                     pipelineStage,
        VkBuffer                                    dstBuffer,
        VkDeviceSize                                dstOffset,
        uint32_t                                    marker);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

- `pipelineStage` is one of the VkPipelineStageFlagBits values, specifying the pipeline stage whose completion triggers the marker write.

- `dstBuffer` is the buffer where the marker will be written to.

- `dstOffset` is the byte offset into the buffer where the marker will be written to.

- `marker` is the 32-bit value of the marker.

## Description

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 `vkCmdWriteBufferMarkerAMD` commands so long as their specified pipeline stages occur either at the same time or earlier than this command’s specified `pipelineStage`.

While consecutive buffer marker writes with the same `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 `VK_ACCESS_TRANSFER_WRITE_BIT`, and the pipeline stages for identifying the synchronization scope must include both `pipelineStage` and `VK_PIPELINE_STAGE_TRANSFER_BIT`.

| Note Similar to `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 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

- `dstOffset` must be less than or equal to the size of `dstBuffer` minus `4`.

- `dstBuffer` must have been created with `VK_BUFFER_USAGE_TRANSFER_DST_BIT` usage flag

- If `dstBuffer` is non-sparse then it must be bound completely and contiguously to a single `VkDeviceMemory` object

- `dstOffset` must be a multiple of `4`

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

- `pipelineStage` must be a valid VkPipelineStageFlagBits value

- `dstBuffer` must be a valid VkBuffer handle

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support transfer, graphics, or compute operations

- Both of `commandBuffer`, and `dstBuffer` must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Both | Transfer Graphics Compute | Transfer

## See Also

VkBuffer, VkCommandBuffer, `VkDeviceSize`, VkPipelineStageFlagBits

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.