• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    NV_scissor_exclusive
4
5Name Strings
6
7    GL_NV_scissor_exclusive
8
9Contact
10
11    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)
12
13Contributors
14
15    Mark Kilgard, NVIDIA
16    Pyarelal Knowles, NVIDIA
17
18Status
19
20    Shipping
21
22Version
23
24    Last Modified:      February 6, 2019
25    Revision:           2
26
27Number
28
29    OpenGL Extension #529
30    OpenGL ES Extension #311
31
32Dependencies
33
34    This extension is written against the OpenGL 4.5 Specification
35    (Compatibility Profile), dated October 24, 2016.
36
37    OpenGL 4.5 or OpenGL ES 3.2 is required.
38
39    This extension is written against the OpenGL Shading Language
40    Specification, version 4.50, dated April 14, 2016.
41
42    This extension trivially interacts with EXT_draw_buffers2,
43    EXT_transform_feedback, NV_transform_feedback, and
44    EXT_direct_state_access.
45
46    If implemented in OpenGL ES, at least one of NV_viewport_array or
47    OES_viewport_array is required.
48
49Overview
50
51    In unextended OpenGL, applications can enable a per-viewport scissor test
52    (SCISSOR_TEST) where fragments are discarded if their (x,y) coordinates
53    lie outside the corresponding scissor rectangle.  In this extension, we
54    provide a separate per-viewport exclusive scissor test, where fragments
55    are discarded if their (x,y) coordinates lie *inside* the corresponding
56    exclusive scissor rectangle.
57
58    The regular (inclusive) scissor test and exclusive scissor test are
59    orthogonal; applications can enable either or both tests for each
60    viewport. If both tests are enabled, fragments will be discarded unless
61    their (x,y) coordinates are both inside the regular scissor rectangle and
62    outside the exclusive scissor rectangle.
63
64New Procedures and Functions
65
66    void ScissorExclusiveArrayvNV(uint first, sizei count, const int *v);
67    void ScissorExclusiveNV(int x, int y, sizei width, sizei height);
68
69New Tokens
70
71    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by the
72    <target> parameter of Enablei, Disablei, IsEnabledi, EnableIndexedEXT,
73    DisableIndexedEXT, and IsEnabledIndexedEXT, and by the <pname> parameter
74    of GetBooleanv, GetIntegerv, GetInteger64v, GetFloatv, GetDoublev,
75    GetDoubleIndexedv, GetBooleani_v, GetIntegeri_v, GetInteger64i_v,
76    GetFloati_v, GetDoublei_v, GetBooleanIndexedvEXT, GetIntegerIndexedvEXT,
77    and GetFloatIndexedvEXT:
78
79        SCISSOR_TEST_EXCLUSIVE_NV                       0x9555
80
81    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
82    GetInteger64v, GetFloatv, GetDoublev, GetBooleani_v, GetIntegeri_v,
83    GetInteger64i_v, GetFloati_v, GetDoublei_v, GetDoubleIndexedv,
84    GetBooleanIndexedvEXT, GetIntegerIndexedvEXT, and GetFloatIndexedvEXT:
85
86        SCISSOR_BOX_EXCLUSIVE_NV                        0x9556
87
88Modifications to the OpenGL 4.5 Specification (Compatibility Profile)
89
90    Insert a new section after section 14.9.2, Scissor Test (p. 560)
91
92    14.9.3  Exclusive Scissor Test
93
94    Like the scissor test (section 14.9.2), the exclusive scissor test
95    determines if (x_w, y_w) lies outside the exclusive scissor rectangles
96    defined by four values for each viewport.  These values are set with
97
98      void ScissorExclusiveArrayvNV(uint first, sizei count, const int *v);
99      void ScissorExclusiveNV(int x, int y, sizei width, sizei height);
100
101    ScissorExclusiveArrayvNV defines a set of exclusive scissor rectangles that
102    are each applied to the corresponding viewport (see section 13.6.1).
103    <first> specifies the index of the first exclusive scissor rectangle to
104    modify, and <count> specifies the number of scissor rectangles.  <v>
105    specifies an array of 4*<count> integers, where each group of four
106    integers specifies the left column, bottom row, width, and height (in that
107    order) of an individual exclusive scissor rectangle.
108
109    ScissorExclusiveNV is equivalent to calling ScissorExclusiveArrayvNV with
110    <first> set to 0, <count> set to the value of MAX_VIEWPORTS, and <v>
111    filled with an array of 4*MAX_VIEWPORTS integer, with each group of four
112    integers set to <x>, <y>, <width>, and <height>, respectively.
113
114    When enabled, the exclusive scissor test passes only if the fragment is
115    outside the selected exclusive scissor rectangle, which is the case if
116    any of the following conditions is true:
117
118      * x_w <  left,
119      * x_w >= left + width,
120      * y_w <  bottom, or
121      * y_w >= bottom + height.
122
123    Otherwise, the test fails and the fragment is discarded. For points,
124    lines, and polygons, the scissor rectangle for a primitive is selected in
125    the same manner as the viewport (see section 13.6.1).  For bitmaps, pixel
126    rectangles and buffer clears (see section 17.4.3), the scissor rectangle
127    numbered zero is used for the scissor test.
128
129      Errors
130
131        An INVALID_VALUE error is generated by ScissorExclusiveArrayvNV if
132        <first>+<count> is greater than the value of MAX_VIEWPORTS.
133
134        An INVALID_VALUE error is generated if width or height is negative.
135
136    The exclusive scissor test is enabled or disabled for all viewports using
137    Enable or Disable with target SCISSOR_TEST_EXCLUSIVE_NV.  The test is enabled or
138    disabled for a specific viewport using Enablei or Disablei with the
139    constant SCISSOR_TEST_EXCLUSIVE_NV and the index of the selected viewport.
140    When disabled, it is as if the exclusive scissor test always passes. The
141    value of the scissor test enable for viewport <i> can be queried by
142    calling IsEnabledi with target SCISSOR_TEST_EXCLUSIVE_NV and index <i>.
143    The value of the exclusive scissor test enable for viewport zero may also
144    be queried by calling IsEnabled with the same target, but no index
145    parameter.
146
147      Errors
148
149        An INVALID_VALUE error is generated by Enablei, Disablei and
150        IsEnabledi if target is SCISSOR_TEST_EXCLUSIVE_NV and <index> is
151        greater than or equal to the value of MAX_VIEWPORTS.
152
153    The state required for the exclusive scissor test consists of four integer
154    values per viewport, and a bit indicating whether the test is enabled or
155    disabled for each viewport. In the initial state for all viewports, the
156    exclusive scissor test is disabled and the exclusive scissor rectangle has
157    zero values for all of left, bottom, width, and height.
158
159Interactions with EXT_draw_buffers2 or EXT_transform_feedback or
160NV_transform_feedback or EXT_direct_state_access
161
162    Ignore references to GetBooleanIndexedvEXT or GetIntegerIndexedvEXT if
163    none of EXT_draw_buffers2, EXT_transform_feedback, NV_transform_feedback,
164    or EXT_direct_state_access are supported.
165
166Interactions with EXT_draw_buffers2 or EXT_direct_state_access
167
168    Ignore references to EnableIndexedEXT, DisableIndexedEXT, and
169    IsEnabledIndexedEXT if neither of EXT_draw_buffers2 or
170    EXT_direct_state_access are supported.
171
172Interactions with EXT_direct_state_access
173
174    Ignore references to GetFloatIndexedvEXT and GetDoubleIndexedvEXT if
175    EXT_direct_state_access is not supported.
176
177Interactions with NV_viewport_array or OES_viewport_array
178
179    If NV_viewport_array is supported, references to MAX_VIEWPORTS and
180    GetFloati_v apply to MAX_VIEWPORTS_NV and GetFloati_vNV respecively.
181
182    If OES_viewport_array is supported, references to MAX_VIEWPORTS and
183    GetFloati_v apply to MAX_VIEWPORTS_OES and GetFloati_vOES respectively.
184
185Interactions with OpenGL ES 3.2
186
187    If implemented in OpenGL ES, remove all references to GetDoublev,
188    GetDoublei_v, EnableIndexedEXT, DisableIndexedEXT, IsEnabledIndexedEXT,
189    GetBooleanIndexedvEXT, GetIntegerIndexedvEXT, GetFloatIndexedvEXT and
190    GetDoubleIndexedv.
191
192    If implemented in OpenGL ES, remove all references to MAX_VIEWPORTS and
193    GetFloati_v.
194
195Additions to the AGL/GLX/WGL Specifications
196
197    None
198
199Errors
200
201    Errors are described in "Errors" sections of the spec language above.
202
203New State
204
205    Get Value                  Type        Get Command   Initial Value   Description                    Sec     Attribute
206    ------------------------   ----------  ------------  -------------   ----------------------------   -----   ---------
207    SCISSOR_TEST_EXCLUSIVE_NV  16* x B     IsEnabledi    FALSE           Exclusive scissoring enabled   14.9.3  scissor/enable
208    SCISSOR_BOX_EXCLUSIVE_NV   16* x 4 x Z GetIntegeri_v (0,0,0,0)       Exclusive scissor rectangles   14.9.3  scissor
209
210New Implementation Dependent State
211
212    None
213
214Issues
215
216    (1) How should we name this extension?
217
218      RESOLVED:  NV_scissor_exclusive.  It defines scissor rectangles and
219      tests that are "exclusive", where fragments pass only if they are
220      outside the rectangle.
221
222    (2) What should we use for the default values for exclusive scissor
223        rectangles?
224
225      RESOLVED:  For inclusive scissors, the default values for an OpenGL
226      context are taken from the size of the drawable first used with the
227      context.  While the inclusive scissor test is initially disabled, the
228      default state allows for "normal" unscissored rendering to that drawable
229      if the test is enabled without explicitly programming a scissor
230      rectangle.
231
232      If we used similar state for exclusive scissors, enabling the exclusive
233      scissor test without programming a rectangle would scissor out all
234      rendering to such drawables.  Instead, we specify the default rectangles
235      as (0,0,0,0), which would cause the exclusive scissor test to discard
236      nothing if enabled without programming a rectangle.  Additionally,
237      this approach makes the default state independent of the drawable first
238      used with the OpenGL context.
239
240    (3) How does the exclusive scissor interact with the functionality
241        of EXT_window_rectangles?
242
243      RESOLVED:  The exclusive scissor, as with the inclusive scissor, is orthogonal
244      to the window rectangles testing introduced by EXT_window_rectangles.
245
246      The window rectangle testing applies to ALL viewports whereas the
247      exclusive scissor, as with the inclusive scissor, are selected by the
248      particular viewport index selected for rasterization.
249
250      Additionally window rectangle testing is only support rendering
251      to framebuffer objects (FBOs) whereas the exclusive scissor,
252      as with the conventional inclusive scissor, works on all drawable.
253
254Revision History
255
256    Revision 2 (pknowles)
257    - Add ES interactions.
258
259    Revision 1 (pbrown)
260    - Internal revisions.
261