Function Prototype

vkCmdSetScissor

Set scissor rectangles dynamically for a command buffer

primary / secondary
both
graphics
state

To dynamically set the scissor rectangles, call:

void vkCmdSetScissor(
    VkCommandBuffer commandBuffer,
    uint32_t firstScissor,
    uint32_t scissorCount,
    const VkRect2D* pScissors);
  • commandBuffer is the command buffer into which the command will be recorded.
  • firstScissor is the index of the first scissor whose state is updated by the command.
  • scissorCount is the number of scissors whose rectangles are updated by the command.
  • pScissors is a pointer to an array of VkRect2D structures defining scissor rectangles.

The scissor rectangles taken from element i of pScissors replace the current state for the scissor index firstScissor + i, for i in [0, scissorCount).

This command sets the scissor rectangles for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with VK_DYNAMIC_STATE_SCISSOR set in VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineViewportStateCreateInfo::pScissors values used to create the currently active pipeline.

Valid Usage

VUID-vkCmdSetScissor-firstScissor-00592

The sum of firstScissor and scissorCount must be between 1 and VkPhysicalDeviceLimits::maxViewports, inclusive

VUID-vkCmdSetScissor-firstScissor-00593

If the multiViewport feature is not enabled, firstScissor must be 0

VUID-vkCmdSetScissor-scissorCount-00594

If the multiViewport feature is not enabled, scissorCount must be 1

VUID-vkCmdSetScissor-x-00595

The x and y members of offset member of any element of pScissors must be greater than or equal to 0

VUID-vkCmdSetScissor-offset-00596

Evaluation of (offset.x + extent.width) must not cause a signed integer addition overflow for any element of pScissors

VUID-vkCmdSetScissor-offset-00597

Evaluation of (offset.y + extent.height) must not cause a signed integer addition overflow for any element of pScissors

VUID-vkCmdSetScissor-viewportScissor2D-04789

If this command is recorded in a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled, then this function must not be called

Valid Usage (Implicit)

VUID-vkCmdSetScissor-pScissors-parameter

pScissors must be a valid pointer to an array of scissorCount VkRect2D structures

VUID-vkCmdSetScissor-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdSetScissor-videocoding

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

VUID-vkCmdSetScissor-scissorCount-arraylength

scissorCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized
  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized ::