25.2. Scissor Test

The scissor test determines if a fragment’s framebuffer coordinates $(x_f,y_f)$ 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);

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 $\mathit{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.

Valid Usage

commandBuffer must be a valid VkCommandBuffer handle
pScissors must be a 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
The currently bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_SCISSOR dynamic state enabled
firstScissor must be less than VkPhysicalDeviceLimits::maxViewports
The sum of firstScissor and scissorCount must be between 1 and VkPhysicalDeviceLimits::maxViewports, inclusive
The x and y members of offset must be greater than or equal to 0
Evaluation of (offset.x + extent.width) must not cause a signed integer addition overflow
Evaluation of (offset.y + extent.height) must not cause a signed integer addition overflow

Command Buffer Levels	Render Pass Scope	Supported Queue Types
Primary Secondary	Both	GRAPHICS

If $\mathit{offset.x} \le x_f \lt \mathit{offset.x} + \mathit{extent.width}$ and $\mathit{offset.y} \le y_f \lt \mathit{offset.y} + \mathit{extent.height}$ for the selected scissor rectangle, then the scissor test passes. Otherwise, the test fails and the fragment is discarded. For points, lines, and polygons, the scissor rectangle for a primitive is selected in the same manner as the viewport (see Controlling the Viewport). The scissor rectangles only apply to drawing commands, not to other commands like clears or copies.

It is legal for $\mathit{offset.x} + \mathit{extent.width}$ or $\mathit{offset.y} + \mathit{extent.height}$ to exceed the dimensions of the framebuffer - the scissor test still applies as defined above. Rasterization does not produce fragments outside of the framebuffer, so such fragments never have the scissor test performed on them.

The scissor test is always performed. Applications can effectively disable the scissor test by specifying a scissor rectangle that encompasses the entire framebuffer.