Function Prototype

vkCmdPushConstants

Update the values of push constants
primary / secondary
both
graphics / compute
state

To update push constants, call:

void vkCmdPushConstants(
    VkCommandBuffer commandBuffer,
    VkPipelineLayout layout,
    VkShaderStageFlags stageFlags,
    uint32_t offset,
    uint32_t size,
    const void* pValues);
  • commandBuffer is the command buffer in which the push constant update will be recorded.
  • layout is the pipeline layout used to program the push constant updates.
  • stageFlags is a bitmask of VkShaderStageFlagBits specifying the shader stages that will use the push constants in the updated range.
  • offset is the start offset of the push constant range to update, in units of bytes.
  • size is the size of the push constant range to update, in units of bytes.
  • pValues is a pointer to an array of size bytes containing the new push constant values.

When a command buffer begins recording, all push constant values are undefined:. Reads of undefined: push constant values by the executing shader return undefined: values.

Push constant values can be updated incrementally, causing shader stages in stageFlags to read the new data from pValues for push constants modified by this command, while still reading the previous data for push constants not modified by this command. When a bound pipeline command is issued, the bound pipeline’s layout must be compatible with the layouts used to set the values of all push constants in the pipeline layout’s push constant ranges, as described in Pipeline Layout Compatibility. Binding a pipeline with a layout that is not compatible with the push constant layout does not disturb the push constant values.

As stageFlags needs to include all flags the relevant push constant ranges were created with, any flags that are not supported by the queue family that the VkCommandPool used to allocate commandBuffer was created on are ignored.

Valid Usage

VUID-vkCmdPushConstants-offset-01795

For each byte in the range specified by offset and size and for each shader stage in stageFlags, there must be a push constant range in layout that includes that byte and that stage

VUID-vkCmdPushConstants-offset-01796

For each byte in the range specified by offset and size and for each push constant range that overlaps that byte, stageFlagsmust include all stages in that push constant range’s VkPushConstantRange::stageFlags

VUID-vkCmdPushConstants-offset-00368

offset must be a multiple of 4

VUID-vkCmdPushConstants-size-00369

size must be a multiple of 4

VUID-vkCmdPushConstants-offset-00370

offset must be less than VkPhysicalDeviceLimits::maxPushConstantsSize

VUID-vkCmdPushConstants-size-00371

size must be less than or equal to VkPhysicalDeviceLimits::maxPushConstantsSize minus offset

Valid Usage (Implicit)

VUID-vkCmdPushConstants-stageFlags-parameter

stageFlags must be a valid combination of VkShaderStageFlagBits values

VUID-vkCmdPushConstants-pValues-parameter

pValues must be a valid pointer to an array of size bytes

VUID-vkCmdPushConstants-commandBuffer-cmdpool

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

VUID-vkCmdPushConstants-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdPushConstants-size-arraylength

size must be greater than 0

VUID-vkCmdPushConstants-commonparent

Both of commandBuffer, and layout 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 ::