xref: /third_party/openGLES/extensions/NV/NV_scissor_exclusive.txt

Name

    NV_scissor_exclusive

Name Strings

    GL_NV_scissor_exclusive

Contact

    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)

Contributors

    Mark Kilgard, NVIDIA
    Pyarelal Knowles, NVIDIA

Status

    Shipping

Version

    Last Modified:      February 6, 2019
    Revision:           2

Number

    OpenGL Extension #529
    OpenGL ES Extension #311

Dependencies

    This extension is written against the OpenGL 4.5 Specification
    (Compatibility Profile), dated October 24, 2016.

    OpenGL 4.5 or OpenGL ES 3.2 is required.

    This extension is written against the OpenGL Shading Language
    Specification, version 4.50, dated April 14, 2016.

    This extension trivially interacts with EXT_draw_buffers2,
    EXT_transform_feedback, NV_transform_feedback, and
    EXT_direct_state_access.

    If implemented in OpenGL ES, at least one of NV_viewport_array or
    OES_viewport_array is required.

Overview

    In unextended OpenGL, applications can enable a per-viewport scissor test
    (SCISSOR_TEST) where fragments are discarded if their (x,y) coordinates
    lie outside the corresponding scissor rectangle.  In this extension, we
    provide a separate per-viewport exclusive scissor test, where fragments
    are discarded if their (x,y) coordinates lie *inside* the corresponding
    exclusive scissor rectangle.

    The regular (inclusive) scissor test and exclusive scissor test are
    orthogonal; applications can enable either or both tests for each
    viewport. If both tests are enabled, fragments will be discarded unless
    their (x,y) coordinates are both inside the regular scissor rectangle and
    outside the exclusive scissor rectangle.

New Procedures and Functions

    void ScissorExclusiveArrayvNV(uint first, sizei count, const int *v);
    void ScissorExclusiveNV(int x, int y, sizei width, sizei height);

New Tokens

    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by the
    <target> parameter of Enablei, Disablei, IsEnabledi, EnableIndexedEXT,
    DisableIndexedEXT, and IsEnabledIndexedEXT, and by the <pname> parameter
    of GetBooleanv, GetIntegerv, GetInteger64v, GetFloatv, GetDoublev,
    GetDoubleIndexedv, GetBooleani_v, GetIntegeri_v, GetInteger64i_v,
    GetFloati_v, GetDoublei_v, GetBooleanIndexedvEXT, GetIntegerIndexedvEXT,
    and GetFloatIndexedvEXT:

        SCISSOR_TEST_EXCLUSIVE_NV                       0x9555

    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
    GetInteger64v, GetFloatv, GetDoublev, GetBooleani_v, GetIntegeri_v,
    GetInteger64i_v, GetFloati_v, GetDoublei_v, GetDoubleIndexedv,
    GetBooleanIndexedvEXT, GetIntegerIndexedvEXT, and GetFloatIndexedvEXT:

        SCISSOR_BOX_EXCLUSIVE_NV                        0x9556

Modifications to the OpenGL 4.5 Specification (Compatibility Profile)

    Insert a new section after section 14.9.2, Scissor Test (p. 560)

    14.9.3  Exclusive Scissor Test

    Like the scissor test (section 14.9.2), the exclusive scissor test
    determines if (x_w, y_w) lies outside the exclusive scissor rectangles
    defined by four values for each viewport.  These values are set with

      void ScissorExclusiveArrayvNV(uint first, sizei count, const int *v);
      void ScissorExclusiveNV(int x, int y, sizei width, sizei height);

    ScissorExclusiveArrayvNV defines a set of exclusive scissor rectangles that
    are each applied to the corresponding viewport (see section 13.6.1).
    <first> specifies the index of the first exclusive scissor rectangle to
    modify, and <count> specifies the number of scissor rectangles.  <v>
    specifies an array of 4*<count> integers, where each group of four
    integers specifies the left column, bottom row, width, and height (in that
    order) of an individual exclusive scissor rectangle.

    ScissorExclusiveNV is equivalent to calling ScissorExclusiveArrayvNV with
    <first> set to 0, <count> set to the value of MAX_VIEWPORTS, and <v>
    filled with an array of 4*MAX_VIEWPORTS integer, with each group of four
    integers set to <x>, <y>, <width>, and <height>, respectively.

    When enabled, the exclusive scissor test passes only if the fragment is
    outside the selected exclusive scissor rectangle, which is the case if
    any of the following conditions is true:

      * x_w <  left,
      * x_w >= left + width,
      * y_w <  bottom, or
      * y_w >= bottom + height.

    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 section 13.6.1).  For bitmaps, pixel
    rectangles and buffer clears (see section 17.4.3), the scissor rectangle
    numbered zero is used for the scissor test.

      Errors

        An INVALID_VALUE error is generated by ScissorExclusiveArrayvNV if
        <first>+<count> is greater than the value of MAX_VIEWPORTS.

        An INVALID_VALUE error is generated if width or height is negative.

    The exclusive scissor test is enabled or disabled for all viewports using
    Enable or Disable with target SCISSOR_TEST_EXCLUSIVE_NV.  The test is enabled or
    disabled for a specific viewport using Enablei or Disablei with the
    constant SCISSOR_TEST_EXCLUSIVE_NV and the index of the selected viewport.
    When disabled, it is as if the exclusive scissor test always passes. The
    value of the scissor test enable for viewport <i> can be queried by
    calling IsEnabledi with target SCISSOR_TEST_EXCLUSIVE_NV and index <i>.
    The value of the exclusive scissor test enable for viewport zero may also
    be queried by calling IsEnabled with the same target, but no index
    parameter.

      Errors

        An INVALID_VALUE error is generated by Enablei, Disablei and
        IsEnabledi if target is SCISSOR_TEST_EXCLUSIVE_NV and <index> is
        greater than or equal to the value of MAX_VIEWPORTS.

    The state required for the exclusive scissor test consists of four integer
    values per viewport, and a bit indicating whether the test is enabled or
    disabled for each viewport. In the initial state for all viewports, the
    exclusive scissor test is disabled and the exclusive scissor rectangle has
    zero values for all of left, bottom, width, and height.

Interactions with EXT_draw_buffers2 or EXT_transform_feedback or
NV_transform_feedback or EXT_direct_state_access

    Ignore references to GetBooleanIndexedvEXT or GetIntegerIndexedvEXT if
    none of EXT_draw_buffers2, EXT_transform_feedback, NV_transform_feedback,
    or EXT_direct_state_access are supported.

Interactions with EXT_draw_buffers2 or EXT_direct_state_access

    Ignore references to EnableIndexedEXT, DisableIndexedEXT, and
    IsEnabledIndexedEXT if neither of EXT_draw_buffers2 or
    EXT_direct_state_access are supported.

Interactions with EXT_direct_state_access

    Ignore references to GetFloatIndexedvEXT and GetDoubleIndexedvEXT if
    EXT_direct_state_access is not supported.

Interactions with NV_viewport_array or OES_viewport_array

    If NV_viewport_array is supported, references to MAX_VIEWPORTS and
    GetFloati_v apply to MAX_VIEWPORTS_NV and GetFloati_vNV respecively.

    If OES_viewport_array is supported, references to MAX_VIEWPORTS and
    GetFloati_v apply to MAX_VIEWPORTS_OES and GetFloati_vOES respectively.

Interactions with OpenGL ES 3.2

    If implemented in OpenGL ES, remove all references to GetDoublev,
    GetDoublei_v, EnableIndexedEXT, DisableIndexedEXT, IsEnabledIndexedEXT,
    GetBooleanIndexedvEXT, GetIntegerIndexedvEXT, GetFloatIndexedvEXT and
    GetDoubleIndexedv.

    If implemented in OpenGL ES, remove all references to MAX_VIEWPORTS and
    GetFloati_v.

Additions to the AGL/GLX/WGL Specifications

    None

Errors

    Errors are described in "Errors" sections of the spec language above.

New State

    Get Value                  Type        Get Command   Initial Value   Description                    Sec     Attribute
    ------------------------   ----------  ------------  -------------   ----------------------------   -----   ---------
    SCISSOR_TEST_EXCLUSIVE_NV  16* x B     IsEnabledi    FALSE           Exclusive scissoring enabled   14.9.3  scissor/enable
    SCISSOR_BOX_EXCLUSIVE_NV   16* x 4 x Z GetIntegeri_v (0,0,0,0)       Exclusive scissor rectangles   14.9.3  scissor

New Implementation Dependent State

    None

Issues

    (1) How should we name this extension?

      RESOLVED:  NV_scissor_exclusive.  It defines scissor rectangles and
      tests that are "exclusive", where fragments pass only if they are
      outside the rectangle.

    (2) What should we use for the default values for exclusive scissor
        rectangles?

      RESOLVED:  For inclusive scissors, the default values for an OpenGL
      context are taken from the size of the drawable first used with the
      context.  While the inclusive scissor test is initially disabled, the
      default state allows for "normal" unscissored rendering to that drawable
      if the test is enabled without explicitly programming a scissor
      rectangle.

      If we used similar state for exclusive scissors, enabling the exclusive
      scissor test without programming a rectangle would scissor out all
      rendering to such drawables.  Instead, we specify the default rectangles
      as (0,0,0,0), which would cause the exclusive scissor test to discard
      nothing if enabled without programming a rectangle.  Additionally,
      this approach makes the default state independent of the drawable first
      used with the OpenGL context.

    (3) How does the exclusive scissor interact with the functionality
        of EXT_window_rectangles?

      RESOLVED:  The exclusive scissor, as with the inclusive scissor, is orthogonal
      to the window rectangles testing introduced by EXT_window_rectangles.

      The window rectangle testing applies to ALL viewports whereas the
      exclusive scissor, as with the inclusive scissor, are selected by the
      particular viewport index selected for rasterization.

      Additionally window rectangle testing is only support rendering
      to framebuffer objects (FBOs) whereas the exclusive scissor,
      as with the conventional inclusive scissor, works on all drawable.

Revision History

    Revision 2 (pknowles)
    - Add ES interactions.

    Revision 1 (pbrown)
    - Internal revisions.