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

Name

    NV_viewport_array

Name Strings

    GL_NV_viewport_array

Contributors

    Contributors to ARB_viewport_array
    Mathias Heyer, NVIDIA
    James Helferty, NVIDIA
    Daniel Koch, NVIDIA

Contact

    Mathias Heyer, NVIDIA (mheyer 'at' nvidia.com)

Notice

    Copyright (c) 2010-2014 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

    Portions Copyright (c) 2014 NVIDIA Corporation.

Status

    Complete

Version

    Last Modified Date:         10/24/2014
    Author Revision:            5

Number

    OpenGL ES Extension #202

Dependencies

    This extension is written against the OpenGL ES 3.1 (March 14, 2014)
    Specification.

    This extension is written against the OpenGL ES Shading Language
    Specification version 3.10 (March 14, 2014)

    OpenGL ES 3.1 and the EXT_geometry_shader extension are required.

    This extension interacts with EXT_draw_buffers_indexed.

Overview

    OpenGL ES is modeled on a pipeline of operations. The final stage in this
    pipeline before rasterization is the viewport transformation. This stage
    transforms vertices from view space into window coordinates and allows the
    application to specify a rectangular region of screen space into which
    OpenGL should draw primitives. Unextended OpenGL implementations provide a
    single viewport per context. In order to draw primitives into multiple
    viewports, the OpenGL viewport may be changed between several draw calls.
    With the advent of Geometry Shaders, it has become possible for an
    application to amplify geometry and produce multiple output primitives for
    each primitive input to the Geometry Shader. It is possible to direct these
    primitives to render into a selected render target. However, all render
    targets share the same, global OpenGL viewport.

    This extension enhances OpenGL by providing a mechanism to expose multiple
    viewports. Each viewport is specified as a rectangle. The destination
    viewport may be selected per-primitive by the geometry shader. This allows
    the Geometry Shader to produce different versions of primitives destined
    for separate viewport rectangles on the same surface. Additionally, when
    combined with multiple framebuffer attachments, it allows a different
    viewport rectangle to be selected for each. This extension also exposes a
    separate scissor rectangle for each viewport. Finally, the viewport bounds
    are now floating point quantities allowing fractional pixel offsets to be
    applied during the viewport transform.

New Procedures and Functions

    void ViewportArrayvNV(uint first, sizei count, const float * v);
    void ViewportIndexedfNV(uint index, float x, float y, float w, float h);
    void ViewportIndexedfvNV(uint index, const float * v);
    void ScissorArrayvNV(uint first, sizei count, const int * v);
    void ScissorIndexedNV(uint index, int left, int bottom, sizei width, sizei height);
    void ScissorIndexedvNV(uint index, const int * v);
    void DepthRangeArrayfvNV(uint first, sizei count, const float * v);
    void DepthRangeIndexedfNV(uint index, float n, float f);
    void GetFloati_vNV(enum target, uint index, float *data);

    void EnableiNV(enum target, uint index);
    void DisableiNV(enum target, uint index);
    boolean IsEnablediNV(enum target, uint index);

New Tokens

    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv,
    and GetInteger64v:

        MAX_VIEWPORTS_NV                                0x825B
        VIEWPORT_SUBPIXEL_BITS_NV                       0x825C
        VIEWPORT_BOUNDS_RANGE_NV                        0x825D
        VIEWPORT_INDEX_PROVOKING_VERTEX_NV              0x825F

    Accepted by the <pname> parameter of GetIntegeri_v:

        SCISSOR_BOX                                     0x0C10

    Accepted by the <pname> parameter of GetFloati_vNV:

        VIEWPORT                                        0x0BA2
        DEPTH_RANGE                                     0x0B70

    Accepted by the <pname> parameter of EnableiNV, DisableiNV,
    and IsEnablediNV:

        SCISSOR_TEST                                    0x0C11

Additions to Chapter 11 of the OpenGL ES 3.1 Specification
(Programmable Vertex Processing)

    Modify section Section 11.1gs.4.5 Layer Selection

    Rename the the "Layer Selection" subsection to "Layer and Viewport
    Selection".

    After the first paragraph, insert:

    Geometry shaders may also select the destination viewport for each
    output primitive. The destination viewport for a primitive may be
    selected in the geometry shader by writing to the built-in output
    variable gl_ViewportIndex. This functionality allows a geometry
    shader to direct its output to a different viewport for each
    primitive, or to draw multiple versions of a primitive into several
    different viewports.

    Replace the first two sentences of the second paragraph with:

    The specific vertex of a primitive that is used to select the
    rendering layer or viewport index is implementation-dependent and
    thus portable applications will assign the same layer and viewport
    index for all vertices in a primitive. The vertex conventions
    followed for gl_Layer and gl_ViewportIndex may be determined by
    calling GetIntegerv with the symbolic constants
    LAYER_PROVOKING_VERTEX_EXT and VIEWPORT_INDEX_PROVOKING_VERTEX_NV,
    respectively.

    Modify section 12.5.1 "Controlling the Viewport", page 284.

    Change the first paragraph of section 12.5.1 to read

    The viewport transformation is determined by the selected viewport's
    width and height in pixels, p_x and p_y, respectively, and its
    center (o_x,o_y) (also in pixels) ...

        { leave equations intact }

    Multiple viewports are available and are numbered zero through the
    value of MAX_VIEWPORTS_NV minus one. If a geometry shader is active
    and writes to gl_ViewportIndex, the viewport transformation uses the
    viewport corresponding to the value assigned to gl_ViewportIndex
    taken from an implementation-dependent primitive vertex. If the
    value of the viewport index is outside the range zero to the value
    of MAX_VIEWPORTS_NV minus one, the results of the viewport
    transformation are undefined. If no geometry shader is active, or if
    the active geometry shader does not write to gl_ViewportIndex, the
    viewport numbered zero is used by the viewport transformation.

    A single vertex may be used in more than one individual primitive, in
    primitives such as TRIANGLE_STRIP.  In this case, the viewport
    transformation is applied separately for each primitive.

    The factor and offset applied to Z_d for each viewport encoded by n
    and f are set using

        void DepthRangeArrayfvNV(uint first, sizei count, const float * v);
        void DepthRangeIndexedfNV(uint index, float n, float f);
        void DepthRangef(float n, float f);

    DepthRangeArrayfvNV is used to specify the depth range for multiple
    viewports simultaneously. <first> specifies the index of the first
    viewport to modify and <count> specifies the number of viewports. If
    (<first> + <count>) is greater than the value of MAX_VIEWPORTS_NV then
    an INVALID_VALUE error will be generated. Viewports whose indices
    lie outside the range [<first>, <first> + <count>) are not modified.
    The <v> parameter contains the address of an array of float types
    specifying near (n) and far (f) for each viewport in that order.
    (n) and (f) of each viewport will be clamped to [0.0, 1.0].

    DepthRangeIndexedfNV specifies the depth range for a single viewport
    and is equivalent (assuming no errors are generated) to:

        float v[] = { n, f };
        DepthRangeArrayfvNV(index, 1, v);

    DepthRangef sets the depth range for all viewports to the same values
    and is equivalent (assuming no errors are generated) to:

        for (uint i = 0; i < MAX_VIEWPORTS_NV; i++)
            DepthRangeIndexedfNV(i, n, f);

    Z_w is represented as either ...

    Replace the end of section 12.5.1, starting from "Viewport transformation
    parameters are specified using..."

    Viewport transformation parameters are specified using

        void ViewportArrayvNV(uint first, sizei count, const float * v);
        void Viewport(int x, int y, sizei w, sizei h);
        void ViewportIndexedfNV(uint index, float x, float y, float w, float h);
        void ViewportIndexedfvNV(uint index, const float * v);

    ViewportArrayvNV specifies parameters for multiple viewports
    simultaneously. <first> specifies the index of the first viewport to
    modify and <count> specifies the number of viewports. If (<first> +
    <count>) is greater than the value of MAX_VIEWPORTS_NV then an
    INVALID_VALUE error will be generated. Viewports whose indices lie
    outside the range [<first>, <first> + <count>) are not modified.
    <v> contains the address of an array of floating point values
    specifying the left (x), bottom (y), width (w) and height (h) of
    each viewport, in that order. <x> and <y> give the location of the
    viewport's lower left corner and <w> and <h> give the viewport's
    width and height, respectively.

    ViewportIndexedfNV and ViewportIndexedfvNV specify parameters for a
    single viewport and are equivalent (assuming no errors are
    generated) to:

        float v[4] = { x, y, w, h };
        ViewportArrayvNV(index, 1, v);

    and

        ViewportArrayvNV(index, 1, v);

    respectively.

    Viewport sets the parameters for all viewports to the same values
    and is equivalent (assuming no errors are generated) to:

        for (uint i = 0; i < MAX_VIEWPORTS_NV; i++)
            ViewportIndexedfNV(i, (float)x, (float)y, (float)w, (float)h);

    The viewport parameters shown in the above equations are found from these
    values as

        o_x = x + w /2,
        o_y = y + h / 2,
        p_x = w,
        p_y = h.

    The location of the viewport's bottom-left corner, given by (x,y), are
    clamped to be within the implementation-dependent viewport bounds range.
    The viewport bounds range [min, max] tuple may be determined by
    calling GetFloatv with the symbolic constant VIEWPORT_BOUNDS_RANGE_NV
    (see chapter 20).

    Viewport width and height are clamped to implementation-dependent maximums
    when specified. The maximum width and height may be found by calling
    GetFloatv with the symbolic constant MAX_VIEWPORT_DIMS. The maximum
    viewport dimensions must be greater than or equal to the larger of
    the visible dimensions of the display being rendered to (if a
    display exists), and the largest renderbuffer image which can be
    successfully created and attached to a framebuffer object (see
    chapter 9). INVALID_VALUE is generated if either w or h is negative.

    The state required to implement the viewport transformations is four
    floating-point values and two clamped floating-point values for each
    viewport. In the initial state, w and h for each viewport are set to
    the width and height, respectively, of the window into which the GL
    is to do its rendering. If the default framebuffer is bound but no
    default framebuffer is associated with the GL context (see chapter
    9), then w and h are initially set to zero. o_x and o_y are set to
    w/2 and h/2, respectively. n and f are set to 0.0 and 1.0,
    respectively.

    The precision with which the GL interprets the floating point viewport
    bounds is implementation-dependent and may be determined by querying the
    implementation-defined constant VIEWPORT_SUBPIXEL_BITS_NV.

Additions to Chapter 15 of the OpenGL ES 3.1 Specification (Writing
Fragments and Samples to the Framebuffer)

    Replace section 15.1.2 "Scissor Test", page 309.

    The scissor test determines if (xw, yw) lies within the scissor rectangle
    defined by four values for each viewport. These values are set with

        void ScissorArrayvNV(uint first, sizei count, const int * v);
        void ScissorIndexedNV(uint index, int left, int bottom, sizei width, sizei height);
        void ScissorIndexedvNV(uint index, int * v);
        void Scissor(int left, int bottom, sizei width, sizei height);

    ScissorArrayvNV defines a set of scissor rectangles that are each
    applied to the corresponding viewport (see section 12.5.1
    "Controlling the Viewport"). <first> specifies the index of the
    first scissor rectangle to modify, and <count> specifies the number
    of scissor rectangles. If (<first> + <count>) is greater than the
    value of MAX_VIEWPORTS_NV, then an INVALID_VALUE error is generated.
    <v> contains the address of an array of integers containing the
    left, bottom, width and height of the scissor rectangles, in that
    order.

    If left <= x_w < left + width and bottom <= y_w < bottom + 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 section 12.5.1).

    The scissor test is enabled or disabled for all viewports using
    Enable or Disable with the symbolic constant SCISSOR_TEST. The test
    is enabled or disabled for a specific viewport using EnableiNV or
    DisableiNV with the constant SCISSOR_TEST and the index of the
    selected viewport. When disabled, it is as if the scissor test
    always passes. The value of the scissor test enable for viewport <i>
    can be queried by calling IsEnablediNV with <target> SCISSOR_TEST and
    <index> <i>. The value of the scissor test enable for viewport zero
    may also be queried by calling IsEnabled with the same symbolic
    constant, but no <index> parameter. If either width or height is
    less than zero for any scissor rectangle, then an INVALID_VALUE
    error is generated. If the viewport index specified to EnableiNV,
    DisableiNV or IsEnablediNV is greater or equal to the value of
    MAX_VIEWPORTS_NV, then an INVALID_VALUE error is generated.

    The state required 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, left = bottom = 0, and width and
    height are determined by the size of the window into which the GL is
    to do its rendering for all viewports. If the default framebuffer is
    bound but no default framebuffer is associated with the GL context
    (see chapter 9), then with and height are initially set to zero.
    Initially, the scissor test is disabled for all viewports.

    ScissorIndexedNV and ScissorIndexedvNV specify the scissor rectangle for
    a single viewport and are equivalent (assuming no errors are
    generated) to:

        int v[] = { left, bottom, width, height };
        ScissorArrayvNV(index, 1, v);

    and

        ScissorArrayvNV(index, 1, v);

    respectively.

    Scissor sets the scissor rectangle for all viewports to the same
    values and is equivalent (assuming no errors are generated) to:

        for (uint i = 0; i < MAX_VIEWPORTS_NV; i++) {
            ScissorIndexedNV(i, left, bottom, width, height);
        }

    Calling Enable or Disable with the symbolic constant SCISSOR_TEST is
    equivalent, assuming no errors, to:

    for (uint i = 0; i < MAX_VIEWPORTS_NV; i++) {
        EnableiNV(SCISSOR_TEST, i);
        /* or */
        DisableiNV(SCISSOR_TEST, i);
    }

Additions to Chapter 19 of the OpenGL ES 3.1 Specification (Context State
Queries)

    Modifications to Section 19.1 Simple Queries

        Add to the list of indexed query functions:

        void GetFloati_vNV(enum target, uint index, float *data);

Additions to the OpenGL ES Shading Language Version 3.10 Specification

    Add a new Section 3.4.x, GL_NV_viewport_array Extension (p. 13)

    3.4.x GL_NV_viewport_array Extension

    To use the GL_NV_viewport_array extension in a shader it must be
    enabled using the #extension directive.

    The shading language preprocessor #define GL_NV_viewport_array will
    be defined to 1 if the GL_NV_viewport_array extension is supported.

    Modify Section 7.1.1gs, "Geometry Shader Special Variables"

    Add to the list of geometry shader built-in variables:

        out highp int gl_ViewportIndex;    // may be written to


    Additions to Section 7.1.1gs.2, "Geometry Shader Output Variables"

    Add a paragraph after the paragraph describing gl_Layer, starting
    "gl_Layer is used to select a specific layer (or face and layer of a
    cube map) of a multi-layer framebuffer attachment.":

    The built-in variable gl_ViewportIndex is available as an output variable
    in the geometry shader and an input variable in the fragment shader. In the
    geometry shader it provides the index of the viewport to which the next
    primitive emitted from the geometry shader should be drawn. Primitives
    generated by the geometry shader will undergo viewport transformation and
    scissor testing using the viewport transformation and scissor rectangle
    selected by the value of gl_ViewportIndex. The viewport index used will
    come from one of the vertices in the primitive being shaded. Which vertex
    the viewport index comes from is implementation-dependent, so it is best to
    use the same viewport index for all vertices of the primitive. If a
    geometry shader does not assign a value to gl_ViewportIndex, viewport
    transform and scissor rectangle zero will be used. If a geometry shader
    assigns a value to gl_ViewportIndex and there is a path through the shader
    that does not set gl_ViewportIndex, then the value of gl_ViewportIndex is
    undefined for executions of the shader that take that path. See section
    11.1gs.4 "Geometry Shader Outputs" of the OpenGL ES Specification for more
    information.

    Modify section 7.1.2 "Fragment Shader Special Variables", as modified by
    EXT_geometry_shader:

    Add to the list of built-in variables:

        in highp int gl_ViewportIndex;

    Add description of the variable:

    The input variable gl_ViewportIndex will have the same value that was
    written to the output variable gl_ViewportIndex in the geometry stage. If
    the geometry stage does not dynamically assign to gl_ViewportIndex, the
    value of gl_ViewportIndex in the fragment shader will be undefined. If the
    geometry stage makes no static assignment to gl_ViewportIndex, the fragment
    stage will read zero. Otherwise, the fragment stage will read the same
    value written by the geometry stage, even if that value is out of range. If
    a fragment shader contains a static access to gl_ViewportIndex, it will
    count against the implementation defined limit for the maximum number of
    inputs to the fragment stage.

    Add to Section 7.2 "Built-In Constants", as modified by
    EXT_geometry_shader, to the list of built-in constants matching the
    corresponding API implementation-dependent limits:

        const highp int gl_MaxViewports = 16;

Errors

    INVALID_VALUE is generated by ViewportArrayvNV if <first> + <count> is
    greater than or equal to the value of MAX_VIEWPORTS_NV, or if any
    viewport's width or height is less than 0.

    INVALID_VALUE is generated by ScissorArrayvNV if <first> + <count> is
    greater than or equal to the value of MAX_VIEWPORTS_NV, or if any
    scissor rectangle's width or height is less than zero.

    INVALID_VALUE is generated by DepthRangeArrayfvNV if <first> + <count> is
    greater than or equal to the vaue of MAX_VIEWPORTS_NV.

    INVALID_VALUE is generated by EnableiNV, DisableiNV and IsEnablediNV if
    <index> is greater than or equal to the value of MAX_VIEWPORTS_NV.

New State

    Table 20.5 (p. 356)

    Get Value                 Type             Get Command       Initial Value   Description                 Sec
    ------------------------  ---------------- ------------      -------------   --------------------------  -----
    VIEWPORT                  16* x 4 x R      GetFloati_vNV       See 2.11.1      Viewport origin & extent  12.5.1
    DEPTH_RANGE               16* x 2 x R[0,1] GetFloati_vNV       See 2.16.1      Depth range near & far    12.5.1

NOTE: The changes are that VIEWPORT and DEPTH_RANGE are extended to
accommodate 16* copies and now consist of floating-point and
double-precision values, respectively.

    Table 20.12 (p. 363)

    Get Value                 Type        Get Command           Initial Value   Description               Sec
    ------------------------  ----------  -------------         -------------   -------------------       ------
    SCISSOR_TEST              16* x B     IsEnablediNV          FALSE           Scissoring enabled        15.1.2
    SCISSOR_BOX               16* x 4 x Z GetIntegeri_v         See 4.1.2       Scissor box               15.1.2

NOTE: The only change is that SCISSOR_TEST and SCISSOR_BOX are extended
to accommodate 16* copies.

New Implementation Dependent State

    Get Value                          Type   Get Command     Minimum Value   Description                     Sec.
    ---------                          ----   -----------     -------------   -------------------             -----
    MAX_VIEWPORT_DIMS    (NOTE 1)      2 x Z+ GetFloatv       See 2.16.1      Maximum viewport dimensions     12.5.1
    MAX_VIEWPORTS_NV                   Z+     GetIntegerv     16              Maximum number of               12.5.1
                                                                              active viewports
    VIEWPORT_SUBPIXEL_BITS_NV          Z+     GetIntegerv     0               Number of bits of sub-pixel     12.5.1
                                                                              precision for viewport bounds
    VIEWPORT_BOUNDS_RANGE_NV           2 x R  GetFloatv       (NOTE 2)        Viewport bounds range [min,max] 12.5.1
    LAYER_PROVOKING_VERTEX_NV          Z_4    GetIntegerv     -- (NOTE 3)     vertex convention followed by   12.5.1
                                                                              the gl_Layer GLSL variable
    VIEWPORT_INDEX_PROVOKING_VERTEX_NV Z_4    GetIntegerv     -- (NOTE 3)     vertex convention followed by   12.5.1
                                                                              the gl_ViewportIndex GLSL
                                                                              variable

NOTE 1: The recommended get command is changed from GetIntegerv to GetFloatv.
NOTE 2: range for viewport bounds:
  * On ES3.1-capable hardware the VIEWPORT_BOUNDS_RANGE_NV should be at least
    [-32768, 32767].
NOTE 3: Valid values are: FIRST_VERTEX_CONVENTION_NV,
LAST_VERTEX_CONVENTION_NV, UNDEFINED_VERTEX_NV.


Interactions with EXT_draw_buffers_indexed

    If EXT_draw_buffers_indexed is supported, EnableiNV, DisableiNV and
    IsEnablediNV alias EnableiEXT, DisableiEXT and IsEnablediEXT, respectively.


Issues

    See issues section in ARB_viewport_array.

    #1 What are the differences from ARB_viewport_array?

    - OpenGL ES does not support the double datatype. The changed interfaces of
    glDepthRangeArrayfvNV and DepthRangeIndexedfNV reflect that. 'float' is
    being used instead of 'clampf', with additional constraints in the text
    that the values will get clamped.
    - The ability to access gl_ViewportIndex from the fragment shader was added
    from ARB_fragment_layer_viewport.


Revision History

    Rev.    Date      Author    Changes
    ----  --------    --------  -----------------------------------------
     1    06/18/2014  mheyer    Based on ARB_viewport_array, stripped for ES3.1
                                - replaced clampd with float for glDepthRangef
                                - instead of EnableIndexed and DisableIndexed, use
                                  Enablei and Disablei
                                - PROVOKING_VERTEX_NV removed
     2    07/24/2014  mheyer    Minor edits.
     3    08/10/2014  mheyer    Edit for consistency.
     4    09/04/2014  jhelferty Add viewport part of ARB_fragment_layer_viewport
                                as was done with layer in EXT_geometry_shader
     5    10/24/2014  dkoch     Cleanup for publishing.