1// Copyright 2016-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_EXT_discard_rectangles.adoc[]
6
7=== Other Extension Metadata
8
9*Last Modified Date*::
10    2023-01-18
11*Interactions and External Dependencies*::
12  - Interacts with `apiext:VK_KHR_device_group`
13  - Interacts with Vulkan 1.1
14*Contributors*::
15  - Daniel Koch, NVIDIA
16  - Jeff Bolz, NVIDIA
17
18=== Description
19
20This extension provides additional orthogonally aligned "`discard
21rectangles`" specified in framebuffer-space coordinates that restrict
22rasterization of all points, lines and triangles.
23
24From zero to an implementation-dependent limit (specified by
25pname:maxDiscardRectangles) number of discard rectangles can be operational
26at once.
27When one or more discard rectangles are active, rasterized fragments can
28either survive if the fragment is within any of the operational discard
29rectangles (ename:VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT mode) or be
30rejected if the fragment is within any of the operational discard rectangles
31(ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT mode).
32
33These discard rectangles operate orthogonally to the existing scissor test
34functionality.
35ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
36The discard rectangles can be different for each physical device in a device
37group by specifying the device mask and setting discard rectangle dynamic
38state.
39endif::VK_VERSION_1_1,VK_KHR_device_group[]
40
41Version 2 of this extension introduces new dynamic states
42ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT and
43ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT, and the corresponding
44functions flink:vkCmdSetDiscardRectangleEnableEXT and
45flink:vkCmdSetDiscardRectangleModeEXT.
46Applications that use these dynamic states must ensure the implementation
47advertises at least pname:specVersion `2` of this extension.
48
49include::{generated}/interfaces/VK_EXT_discard_rectangles.adoc[]
50
51=== Version History
52
53  * Revision 2, 2023-01-18 (Piers Daniell)
54  ** Add dynamic states for discard rectangle enable/disable and mode.
55
56  * Revision 1, 2016-12-22 (Piers Daniell)
57  ** Internal revisions
58