vkCmdSetScissor(3)

# vkCmdSetScissor(3) Manual Page

## Name

vkCmdSetScissor - Set the dynamic scissor rectangles on a command buffer

## C Specification

The scissor test determines if a fragment’s framebuffer coordinates (xf,yf) lie within the scissor rectangle corresponding to the viewport index (see Controlling the Viewport) used by the primitive that generated the fragment. If the pipeline state object is created without `VK_DYNAMIC_STATE_SCISSOR` enabled then the scissor rectangles are set by the VkPipelineViewportStateCreateInfo state of the pipeline state object. Otherwise, to dynamically set the scissor rectangles call:

    void vkCmdSetScissor(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    firstScissor,
        uint32_t                                    scissorCount,
        const VkRect2D*                             pScissors);

## Parameters

- `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.

## Description

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

Each scissor rectangle is described by a VkRect2D structure, with the `offset.x` and `offset.y` values determining the upper left corner of the scissor rectangle, and the `extent.width` and `extent.height` values determining the size in pixels.

If a render pass transform is enabled, the (`offset.x` and `offset.y`) and (`extent.width` and `extent.height`) values are transformed as described in render pass transform before participating in the scissor test.

Valid Usage

- `firstScissor` must be less than `VkPhysicalDeviceLimits`::`maxViewports`

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

- If the multiple viewports feature is not enabled, `firstScissor` must be `0`

- If the multiple viewports feature is not enabled, `scissorCount` must be `1`

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

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

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

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

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

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support graphics operations

- `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

Command Properties

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

## See Also

VkCommandBuffer, VkRect2D

## 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.