vkCmdWriteBufferMarkerAMD(3)

# vkCmdWriteBufferMarkerAMD(3) Manual Page

## Name

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

Loading… please wait.

## C Specification

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

    // Provided by VK_AMD_buffer_marker
    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

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04074
  `pipelineStage` must be a valid stage for the queue family that was used to create the command pool that `commandBuffer` was allocated from

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04075
  If the geometry shaders feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04076
  If the tessellation shaders feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT` or `VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04077
  If the conditional rendering feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04078
  If the fragment density map feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04079
  If the transform feedback feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04080
  If the mesh shaders feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV` or `VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV`

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04081
  If the shading rate image feature is not enabled, `pipelineStage` must not be `VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV`

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

- VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799
  `dstBuffer` must have been created with `VK_BUFFER_USAGE_TRANSFER_DST_BIT` usage flag

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

- VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801
  `dstOffset` must be a multiple of `4`

Valid Usage (Implicit)

- VUID-vkCmdWriteBufferMarkerAMD-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-parameter
  `pipelineStage` must be a valid VkPipelineStageFlagBits value

- VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-parameter
  `dstBuffer` must be a valid VkBuffer handle

- VUID-vkCmdWriteBufferMarkerAMD-commandBuffer-recording
  `commandBuffer` must be in the recording state

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

- VUID-vkCmdWriteBufferMarkerAMD-commonparent
  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 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0