// Copyright 2016-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_discard_rectangles.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2023-01-18
*Interactions and External Dependencies*::
  - Interacts with `apiext:VK_KHR_device_group`
  - Interacts with Vulkan 1.1
*Contributors*::
  - Daniel Koch, NVIDIA
  - Jeff Bolz, NVIDIA

=== Description

This extension provides additional orthogonally aligned "`discard
rectangles`" specified in framebuffer-space coordinates that restrict
rasterization of all points, lines and triangles.

From zero to an implementation-dependent limit (specified by
pname:maxDiscardRectangles) number of discard rectangles can be operational
at once.
When one or more discard rectangles are active, rasterized fragments can
either survive if the fragment is within any of the operational discard
rectangles (ename:VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT mode) or be
rejected if the fragment is within any of the operational discard rectangles
(ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT mode).

These discard rectangles operate orthogonally to the existing scissor test
functionality.
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
The discard rectangles can be different for each physical device in a device
group by specifying the device mask and setting discard rectangle dynamic
state.
endif::VK_VERSION_1_1,VK_KHR_device_group[]

Version 2 of this extension introduces new dynamic states
ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT and
ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT, and the corresponding
functions flink:vkCmdSetDiscardRectangleEnableEXT and
flink:vkCmdSetDiscardRectangleModeEXT.
Applications that use these dynamic states must ensure the implementation
advertises at least pname:specVersion `2` of this extension.

include::{generated}/interfaces/VK_EXT_discard_rectangles.adoc[]

=== Version History

  * Revision 2, 2023-01-18 (Piers Daniell)
  ** Add dynamic states for discard rectangle enable/disable and mode.

  * Revision 1, 2016-12-22 (Piers Daniell)
  ** Internal revisions
