xref: /third_party/openGLES/extensions/ARB/ARB_robustness.txt

Name

    ARB_robustness

Name Strings

    GL_ARB_robustness

Contributors

    Acorn Pooley, NVIDIA
    Anton Staaf, Google
    Barthold Lichtenbelt, NVIDIA
    Bruce Merry, ARM
    Chris Marrin, Apple
    Greg Roth, NVIDIA
    Jeff Bolz, NVIDIA
    Jon Leech 
    Kenneth Russell, Google
    Kent Miller, Apple
    Piers Daniell, NVIDIA
    Vladimir Vukicevic, Mozilla

Contact

    Mark Kilgard, NVIDIA (mjk 'at' nvidia.com)

Notice

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

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL Working Group. For
    extensions which have been promoted to a core Specification, fixes will
    first appear in the latest version of that core Specification, and will
    eventually be backported to the extension document. This policy is
    described in more detail at
        https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Status

    Complete. Approved by the ARB on June 9, 2010.
    Approved by the Khronos Board of Promoters on July 23, 2010.

Version

    Last Modified Date:  June 25, 2014
    Version:             18

Number

    ARB Extension #105

Dependencies

    This extension is written against the OpenGL 3.2 Compatibility
    Profile Specification but can apply to OpenGL 1.1 and up.

    This specification interacts with the ARB_imaging subset of the OpenGL
    3.2 Compatibility Profile.

    This specification interacts with the OpenGL 3.2 Core Profile.

    This specification interacts with EXT_direct_state_access.

    GLX_ARB_create_context_robustness and
    WGL_ARB_create_context_robustness are used to determine if a context
    implementing this extension supports robust buffer access, and if it
    supports reset notification. Equivalent platform-dependent
    mechanisms in other window-system integration layers such as EGL and
    AGL may exist for those platforms.

Overview

    Several recent trends in how OpenGL integrates into modern computer
    systems have created new requirements for robustness and security
    for OpenGL rendering contexts.
    
    Additionally GPU architectures now support hardware fault detection;
    for example, video memory supporting ECC (error correcting codes)
    and error detection.  OpenGL contexts should be capable of recovering
    from hardware faults such as uncorrectable memory errors.  Along with
    recovery from such hardware faults, the recovery mechanism can
    also allow recovery from video memory access exceptions and system
    software failures.  System software failures can be due to device
    changes or driver failures.

    Demands for increased software robustness and concerns about malware
    exploiting buffer overflows have lead API designers to provide
    additional "safe" APIs that bound the amount of data returned by
    an API query.  For example, the safer "snprintf" or "_snprintf"
    routines are prefered over "sprintf".
    
    The OpenGL API has many such robustness perils.  OpenGL queries
    return (write) some number of bytes to a buffer indicated by a
    pointer parameter.  The exact number of bytes written by existing
    OpenGL queries is not expressed directly by any specific parameter;
    instead the number of bytes returned is a complex function of one
    or more query arguments, sometimes context state such as pixel
    store modes or the active texture selector, and the current state
    of an object (such as a texture level's number of total texels).
    By the standards of modern API design, such queries are not "safe".
    Making these queries safer involves introducing a new query API with
    an additional parameter that specifies the number of bytes in the
    buffer and never writing bytes beyond that limit.

    Multi-threaded use of OpenGL contexts in a "share group" allow
    sharing of objects such as textures and programs.  Such sharing in
    conjunction with concurrent OpenGL commands stream execution by two
    or more contexts introduces hazards whereby one context can change
    objects in ways that can cause buffer overflows for another context's
    OpenGL queries.

    The original ARB_vertex_buffer_object extension includes an issue
    that explicitly states program termination is allowed when
    out-of-bounds vertex buffer object fetches occur. Modern GPUs
    capable of DirectX 10 enforce the well-defined behavior of always
    returning zero values for indices or non-fixed components in this
    case. Older GPUs may require extra checks to enforce well-defined
    (and termination free) behavior, but this expense is warranted when
    processing potentially untrusted content.

    The intent of this extension is to address some specific robustness
    goals:

    *   For all existing OpenGL queries, provide additional "safe" APIs 
        that limit data written to user pointers to a buffer size in 
        bytes that is an explicit additional parameter of the query.

    *   Provide a mechanism for an OpenGL application to learn about
        graphics resets that affect the context.  When a graphics reset
        occurs, the OpenGL context becomes unusable and the application
        must create a new context to continue operation. Detecting a
        graphics reset happens through an inexpensive query.

    *   Provide an enable to guarantee that out-of-bounds buffer object
        accesses by the GPU will have deterministic behavior and preclude
        application instability or termination due to an incorrect buffer
        access.  Such accesses include vertex buffer fetches of
        attributes and indices, and indexed reads of uniforms or
        parameters from buffers.

    In one anticipated usage model, WebGL contexts may make use of these
    robust features to grant greater stability when using untrusted code.
    WebGL contexts cannot call OpenGL commands directly but rather must
    route all OpenGL API calls through the web browser.  It is then the
    web browser that configures the context, using the commands in this
    extension, to enforce safe behavior. In this scenario, the WebGL
    content cannot specify or change the use of this extension's features
    itself; the web browser enforces this policy.

    There are other well-known robustness issues with the OpenGL API
    which this extension does not address.  For example, selector-based
    OpenGL commands are a well-known source of programming errors.
    Code to manipulate texture state may assume the active texture
    selector is set appropriately when an intervening function call
    obscures a change to the active texture state resulting in
    incorrectly updated or queried state.  The EXT_direct_state_access
    extension introduces selector-free OpenGL commands and queries to
    address that particular issue so this extension does not.

    The intent of this extension is NOT to deprecate any existing API
    and thereby introduce compatibility issues and coding burdens on
    existing code, but rather to provide new APIs to ensure a level of
    robustness commensurate with the expectations of modern applications
    of OpenGL.

IP Status

    No known IP claims.

New Procedures and Functions

    GRAPHICS RESET DETECTION AND RECOVERY

        enum GetGraphicsResetStatusARB();

    SIZED BUFFER QUERIES

    OpenGL 1.0 sized buffer queries

        void GetnMapdvARB(enum target, enum query, sizei bufSize, double *v);
        void GetnMapfvARB(enum target, enum query, sizei bufSize, float *v);
        void GetnMapivARB(enum target, enum query, sizei bufSize, int *v);

        void GetnPixelMapfvARB(enum map, sizei bufSize, float *values);
        void GetnPixelMapuivARB(enum map, sizei bufSize, uint *values);
        void GetnPixelMapusvARB(enum map, sizei bufSize, ushort *values);

        void GetnPolygonStippleARB(sizei bufSize, ubyte *pattern);

        void GetnTexImageARB(enum target, int level, enum format,
                             enum type, sizei bufSize, void *img);

        void ReadnPixelsARB(int x, int y, sizei width, sizei height,
                            enum format, enum type, sizei bufSize,
                            void *data);

    ARB_imaging sized buffer queries

        void GetnColorTableARB(enum target, enum format, enum type,
                               sizei bufSize, void *table);
        void GetnConvolutionFilterARB(enum target, enum format,
                                      enum type, sizei bufSize, void *image);
        void GetnSeparableFilterARB(enum target, enum format, enum type,
                                    sizei rowBufSize, void *row,
                                    sizei columnBufSize, void *column,
                                    void *span);
        void GetnHistogramARB(enum target, boolean reset, enum format,
                              enum type, sizei bufSize, void *values);
        void GetnMinmaxARB(enum target, boolean reset, enum format,
                           enum type, sizei bufSize, void *values);

    OpenGL 1.3 sized buffer queries

        void GetnCompressedTexImageARB(enum target, int lod,
                                       sizei bufSize, void *img);

    OpenGL 2.0 sized buffer queries

        void GetnUniformfvARB(uint program, int location, sizei bufSize,
                              float *params);
        void GetnUniformivARB(uint program, int location, sizei bufSize,
                              int *params);
        void GetnUniformuivARB(uint program, int location, sizei bufSize,
                               uint *params);
        void GetnUniformdvARB(uint program, int location, sizei bufSize,
                              double *params);

New Tokens

    Returned by GetGraphicsResetStatusARB:

        NO_ERROR                                        0x0000
        GUILTY_CONTEXT_RESET_ARB                        0x8253
        INNOCENT_CONTEXT_RESET_ARB                      0x8254
        UNKNOWN_CONTEXT_RESET_ARB                       0x8255

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

        RESET_NOTIFICATION_STRATEGY_ARB                 0x8256

    Returned by GetIntegerv and related simple queries when
    <value> is RESET_NOTIFICATION_STRATEGY_ARB:

        LOSE_CONTEXT_ON_RESET_ARB                       0x8252
        NO_RESET_NOTIFICATION_ARB                       0x8261

    Returned by GetIntegerv when <pname> is CONTEXT_FLAGS:

        CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB          0x00000004


Additions to Chapter 2 of the OpenGL 3.2 (Compatibility Profile)
Specification (OpenGL Operation)

Add a new subsection after 2.5 "GL Errors" and renumber subsequent
sections accordingly

    2.6 "Graphics Reset Recovery"

    Certain events can result in a reset of the GL context. Such a reset
    causes all context state to be lost. Recovery from such events
    requires recreation of all objects in the affected context. The
    current status of the graphics reset state is returned by

        enum GetGraphicsResetStatusARB();

    The symbolic constant returned indicates if the GL context has been
    in a reset state at any point since the last call to
    GetGraphicsResetStatusARB. NO_ERROR indicates that the GL context
    has not been in a reset state since the last call.
    GUILTY_CONTEXT_RESET_ARB indicates that a reset has been detected
    that is attributable to the current GL context.
    INNOCENT_CONTEXT_RESET_ARB indicates a reset has been detected that
    is not attributable to the current GL context.
    UNKNOWN_CONTEXT_RESET_ARB indicates a detected graphics reset whose
    cause is unknown.

    If a reset status other than NO_ERROR is returned and subsequent
    calls return NO_ERROR, the context reset was encountered and
    completed. If a reset status is repeatedly returned, the context may
    be in the process of resetting.

    Reset notification behavior is determined at context creation time,
    and may be queried by calling GetIntegerv with the symbolic constant
    RESET_NOTIFICATION_STRATEGY_ARB.

    If the reset notification behavior is NO_RESET_NOTIFICATION_ARB,
    then the implementation will never deliver notification of reset
    events, and GetGraphicsResetStatusARB will always return
    NO_ERROR[fn1].
       [fn1: In this case it is recommended that implementations should
        not allow loss of context state no matter what events occur.
        However, this is only a recommendation, and cannot be relied
        upon by applications.]

    If the behavior is LOSE_CONTEXT_ON_RESET_ARB, a graphics reset will
    result in the loss of all context state, requiring the recreation of
    all associated objects. In this case GetGraphicsResetStatusARB. may
    return any of the values described above.

    If a graphics reset notification occurs in a context, a notification
    must also occur in all other contexts which share objects with that
    context[fn2].
       [fn2: The values returned by GetGraphicsResetStatusARB in the
        different contexts may differ.]

    Add to Section 2.8 "Vertex Arrays" before 2.8.1 "Drawing Commands"

    Robust buffer access is enabled by creating a context with robust
    access enabled through the window system binding APIs. When enabled,
    indices within the vertex array that lie outside the arrays defined
    for enabled attributes result in undefined values for the
    corresponding attributes, but cannot result in application failure.


Additions to Chapter 3 of the OpenGL 3.2 (Compatibility Profile)
Specification (Rasterization)

    None

Additions to Chapter 4 of the OpenGL 3.2 (Compatibility Profile)
Specification (Per-Fragment Operations and the Frame Buffer)

    Modify section 4.3.2 "Reading Pixels"

    Pixels are read using

        void ReadPixels(int x, int y, sizei width, sizei height,
                        enum format, enum type, void *data);
        void ReadnPixelsARB(int x, int y, sizei width, sizei height,
                            enum format, enum type, sizei bufSize,
                            void *data);

    The arguments after <x> and <y> to ReadPixels are described in
    section 3.7.4. The pixel storage modes that apply to ReadPixels and
    other commands that query images (see section 6.1) are summarized in
    table 4.7.  ReadnPixelsARB behaves identically to ReadPixels except
    that it does not write more than <bufSize> bytes into <data>.

Additions to Chapter 5 of the OpenGL 3.2 (Compatibility Profile)
Specification (Special Functions)

    None

Additions to Chapter 6 of the OpenGL 3.2 (Compatibility Profile)
Specification (State and State Requests)

      Modify Section 6.1.3 "Enumerated Queries"

          void GetPixelMap{ui us f}v(enum map, T data);
          void GetnPixelMap{ui us f}vARB(enum map, sizei bufSize, T data);

      return all values in the pixel map <map> in <data>. <map> must be
      a map name from table 3.3. GetPixelMapuiv, GetnPixelMapuivARB,
      GetPixelMapusv, and GetnPixelMapusvARB convert floating point pixel
      map values to integers according to the UNSIGNED_INT and
      UNSIGNED_SHORT entries, respectively, of table 4.9.
          GetnPixelMap{ui us f}vARB does not write more than <bufSize>
      bytes into <data>.
          If a pixel pack buffer ...
      ... an INVALID_OPERATIONS_ERROR results. When calling
      GetnPixelMap{ui us f}vARB, if a pixel pack buffer object is bound
      and <n> is greater than <bufSize>, but <data>+<n> does not exceed
      the size of the buffer, no error results.

      ... 

          void GetMap{ifd}v(enum map, enum value, T data);
          void GetnMap{ifd}vARB(enum map, enum value, sizei bufSize, T data);

      places information about <value> for <map> in <data>. <map> must
      be one of the map types described in section 5.1, and <value> must
      be one of ORDER, COEFF, or DOMAIN. GetnMap{ifd}vARB does not write
      more than <bufSize> bytes into <data>.

      Section 6.1.4 "Texture Queries"

      
      Modify the description of GetTexImage:

      "The commands

          void GetTexImage(enum tex, int lod, enum format, enum type,
                           void *img );
          void GetnTexImageARB(enum tex, int lod, enum format, enum type,
                               sizei bufSize, void *img );

      are used to obtain texture images. ...
      ... <type> is a pixel type from table 3.5. GetnTexImageARB does
      not write more than <bufSize> bytes into <img>."

      Add to the end of the sixth paragraph:

      "When calling GetnTextureImageARB, if a pixel pack buffer object
      is bound and packing a texture image into buffer memory would
      exceed <bufSize> but not the size of the buffer, no error results."

      Modify the description of GetCompressedTexImage:

      "The commands

          void GetCompressedTexImage(enum target, int lod, void *img);
          void GetnCompressedTexImageARB(enum target, int lod, sizei bufSize,
                                         void *img );
          
      are used to obtain texture images stored in compressed form. The
      parameters <target>, <lod>, and <img> are interpreted in the same
      manner as in GetTexImage and GetnTexImageARB respectively. When
      called, GetCompressedTexImage and GetnCompressedTexImageARB write
      MIN(n,bufSize) ubytes of compressed image data ...

      ... If a pixel pack buffer object is bound and img + n is greater
      than the size of the buffer, an INVALID_OPERATION error results.
      When calling GetnCompressedTextureImageARB, if a pixel pack buffer
      object is bound and <n> is greater than <bufSize> but <img>+<n>
      does not exceed the size of the buffer, no error results."

      Modify Section 6.1.5 "Stipple Query"
      
      The commands

          void GetPolygonStipple(void *pattern);
          void GetnPolygonStippleARB(sizei bufSize, void *pattern);

      obtain the polygon stipple. The pattern is packed into pixel pack
      buffer or client memory according to the procedure given in section
      4.3.2 for ReadPixels; it is as if the <height> and <width> passed
      to that command were both equal to 32, the type were BITMAP, and
      the format were COLOR_INDEX. GetnPolygonStippleARB does not write
      more than <bufSize> bytes into <pattern>.

      Modify Section 6.1.7 "Color Table Query"

      The current contents of a color table are queried using

          void GetColorTable(enum target, enum format, enum type,
                             void *table );
          void GetnColorTableARB(enum target, enum format, enum type,
                                 sizei bufSize, void *table);
          
      <target> must be one of the regular color table names listed in
      table 3.4. ...
      ... to the components requested by format are described in table
      6.1. GetnColorTableARB does not write more than <bufSize> bytes
      into <table>.

      Modify Section 6.1.8 "Convolution Query"

      The current contents of a convolution filter image are queried
      with the command

          void GetConvolutionFilter(enum target, enum format, enum type,
                                    void *image );
          void GetnConvolutionFilterARB(enum target, enum format,
                                     enum type, sizei bufSize, void *image);

      <target> must be CONVOLUTION_1D or CONVOLUTION_2D. ...
      ... Pixel processing and component mapping are identical to those
      of GetTexImage. GetnConvolutionFilterARB does not write more than
      <bufSize> bytes into <image>.

      ...

      The current contents of a separable filter image are queried using

          void GetSeparableFilter(enum target, enum format, enum type,
                                  void *row, void *column, void *span );
          void GetnSeparableFilterARB(enum target, enum format, enum type,
                                      sizei rowBufSize, void *row,
                                      sizei columnBufSize, void *column,
                                      void *span);

      ... The row and column images are returned to pixel pack buffer or
      client memory starting at row and column respectively.
      GetnSeparableFilterARB does not write more than <rowBufSize> bytes
      into <row> and no more than <columnBufSize> bytes into <column>.
      <span> is currently unused. ...
      

      Modify Section 6.1.9 "Histogram Query"

      The current contents of the histogram table are queried using

          void GetHistogram(enum target, boolean reset, enum format,
                            enum type, void* values );
          void GetnHistogramARB(enum target, boolean reset, enum format,
                             enum type, sizei bufSize, void* values);

      ... component values are simply clamped to the range of the target
      data type. GetnHistogramARB does not write more than <bufSize>
      bytes into <values>.

      Modify Section 6.1.10 "Minmax Query"

      The current contents of the minmax table are queried using

          void GetMinmax(enum target, boolean reset, enum format,
                         enum type, void* values );
          void GetnMinmaxARB(enum target, boolean reset, enum format,
                          enum type, sizei bufSize, void* values);

      ... A one-dimensional image of width 2 is returned to pixel pack
      buffer or client memory starting at <values>. GetnMinmaxARB does
      not write more than <bufSize> bytes into <values>.

      Modify Section 6.1.11 "Pointer and String Queries"

      Add to the paragraph describing the context profile mask and flags
      (preceding the description of GetStringi) on page 379:

     "If CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB is set in CONTEXT_FLAGS,
      then robust buffer access will be enabled for drawing commands
      using vertex arrays, as described in section 2.8."

      Modify Section 6.1.16 "Shader and Program Queries"

      The commands

          void GetUniformfv(uint program, int location, float *params);
          void GetnUniformfvARB(uint program, int location, sizei bufSize,
                                float *params);
          void GetUniformiv(uint program, int location, int *params);
          void GetnUniformivARB(uint program, int location, sizei bufSize,
                                int *params);
          void GetUniformuiv(uint program, int location, uint *params);
          void GetnUniformuivARB(uint program, int location, sizei bufSize,
                                 uint *params);
          void GetUniformdv(uint program, int location, double *params);
          void GetnUniformdvARB(uint program, int location, sizei bufSize,
                                double *params);

      return the value or values of the uniform at location location of
      the default uniform block for program object program in the array
      params. GetnUniformfvARB, GetnUniformivARB, GetnUniformuivARB and
      GetnUniformdvARB do not write any data to <params> if <bufSize> is
      less than the size of the requested data.
      ...

Additions to the AGL/GLX/WGL Specifications

    None

Additions to The OpenGL Shading Language Specification, Version 1.50.11

    Change the first paragraph of section 4.1.9 "Arrays"

    ... Undefined behavior results from indexing an array with a
    non-constant expression that's greater than or equal to the array's
    size or less than 0. If robust buffer access is enabled via the
    OpenGL API, such indexing must not result in abnormal program
    termination. The results are still undefined, but implementations
    are encouraged to produce zero values for such accesses. Only
    one-dimensional arrays may be declared. ...

GLX Protocol

    XXX

Interactions with GLX_ARB_create_context_robustness

    If the GLX window-system binding API is used to create a context,
    the GLX_ARB_create_context_robustness extension is supported, and
    the bit GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in
    GLX_CONTEXT_FLAGS when glXCreateContextAttribsARB is called, the
    resulting context will perform robust buffer access as described
    above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit
    will be set in CONTEXT_FLAGS as described above in section 6.1.11.

    If the GLX window-system binding API is used to create a context and
    the GLX_ARB_create_context_robustness extension is supported, then
    the value of attribute GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB
    determines the reset notification behavior and the value of
    RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6.

Interactions with WGL_ARB_create_context_robustness

    If the WGL window-system binding API is used to create a context,
    the WGL_ARB_create_context_robustness extension is supported, and
    the bit WGL_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in
    WGL_CONTEXT_FLAGS when wglCreateContextAttribsARB is called, the
    resulting context will perform robust buffer access as described
    above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit
    will be set in CONTEXT_FLAGS as described above in section 6.1.11.

    If the WGL window-system binding API is used to create a context and
    the WGL_ARB_create_context_robustness extension is supported, then
    the value of attribute WGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB
    determines the reset notification behavior and the value of
    RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6.

Errors

    GetnMapdvARB, GetnMapfvARB, GetnMapivARB, GetnPixelMapfvARB,
    GetnPixelMapuivARB, GetnPixelMapusvARB, GetnPolygonStippleARB,
    GetnTexImageARB, ReadnPixelsARB, GetnColorTableARB,
    GetnConvolutionFilterARB, GetnSeparableFilterARB, GetnHistogramARB,
    GetnMinmaxARB, GetnCompressedTexImageARB, GetnUniformfvARB,
    GetnUniformivARB, GetnUniformuivARB and GetnUniformdvARB share all the
    errors of their unsized buffer query counterparts with the addition
    that INVALID_OPERATION is generated if the buffer size required to
    fill all the requested data is greater than <bufSize>.

New State

    Get Value                            Type  Get Command            Value     Description                  Sec     Attribute
    --------------------------      ----  -----------   ------------  ---------------------------  ------  ---------
    RESET_NOTIFICATION_STRATEGY_ARB Z_2   GetIntegerv   See sec. 2.6  Reset notification behavior  2.6     -


New Implementation Dependent State

    None

Dependencies on the ARB_imaging subset

    If the ARB_imaging subset of the OpenGL 3.2 Compatibility Profile is not
    supported, the commands GetnColorTableARB, GetnConvolutionFilterARB,
    GetnHistogramARB, GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, and
    GetnSeparableFilterARB defined by this extension are not supported, and
    all references to them should be ignored.

Dependencies on OpenGL 3.2 (Core Profile)

    If only the core profile of OpenGL 3.2 is supported, the commands
    GetnColorTableARB, GetnConvolutionFilterARB, GetnHistogramARB,
    GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, GetnPolygonStippleARB, and
    GetnSeparableFilterARB defined by this extension are not supported, and
    all references to them should be ignored.

Issues

    1.  Does robust buffer access affect vertex pulling from vertex
        buffer objects, client vertex arrays, or both?

        RESOLVED:  Only vertex buffer objects.

        DirectX 10-era GPUs are guaranteed to provide guarantees
        consistent with those required by robust buffer access.

        Client memory vertex arrays should not be expected to be used
        directly in situations requiring robust operation.

        Historically the original EXT_vertex_array extension provided a
        "GLsizei count" parameter to indicate how long vertex arrays
        should be.  This proved to be unworkable in practice because
        applications typically found it too difficult to properly compute
        the count; instead a very large integer was passed, obviating any
        practical use for the parameter.  When vertex arrays were added
        to core OpenGL in version 1.1, the "GLsizei count" parameter
        was eliminated for this reason.

        There are other problems too.  Clever applications using client
        memory vertex arrays can specify the base pointer to be NULL
        (address 0) and then use indices that essentially correspond
        to pointers divided by the stride.  There's also no guarantee a
        pointer itself has a contiguous range of memory allocate within
        a given range.

        Moreover client memory vertex arrays are no longer a performance
        path so they simply are not particularly interesting to address.

        The result is there's really no practical way to bound client
        vertex array access in a way that's likely to be practically
        useful.

        Vertex buffer objects do not have this same problem because
        buffer objects have a bounded index-able range.

        Robust applications should simply use vertex buffer objects for
        robust vertex pulling (ignoring client memory vertex arrays for
        an rendering that must be done robustly).

    2.  If robust buffer access is supported and a vertex index is large
        enough to fetch beyond the size of an enabled vertex buffer
        object, what happens?

        RESOLVED:  Undefined values are read for the varying (non-fixed)
        components.

        A fixed-component would be a component such as the W component
        when only a 2- or 3-component position is fetched.  In this case,
        the W component is fixed as 1.0 and that will be the case still
        if the index would have resulted in an out-of-bounds fetch.

        Undefined results are required for implementations that can't
        guarantee any particular value. It make testing this behavior
        difficult, but it's required for certain implementations.

    3.  If robust buffer access is supported and an element array buffer
        is accessed beyond the size of the element array buffer so
        there's not a valide index, what happens?

        RESOLVED:  The value of the index is undefined.

        Undefined results are required for implementations that can't
        guarantee any particular value. It make testing this behavior
        difficult, but it's required for certain implementations.

    4.  What query commands actually need a new "GLsizei bufSize"
        parameter?

        RESOLVED:  If the number of bytes returned by the query is not
        *completely* determined by the parameters to the function (in
        the absence of errors) and not already bounded by an existing
        GLsizei buffer size parameter, a new query is needed.

        This means commands such as glGetClipPlane, glGetIntegerv,
        etc. do NOT need new versions.

        This means queries that depend on pixel store pack state need
        new queries.  Examples: glReadPixels, glGetPolygonStipple,
        glGetTexImage, glGetConvolutionFilter, etc.

        This means queries that query an object's state which can
        vary in size need new queries.  Examples:  glGetTexImage,
        glGetCompressedTexImage, glGetUniformfv, glGetUniformuiv, etc.

        This means queries that query context state which can vary
        depending on other context state variables need new queries.
        Examples:  glGetHistogram, glGetPixelMapfv, glGetColorTable, etc.

        If the command already has a parameter that limits the amount
        of data returned through a pointer, no new command is needed.
        Examples: glGetActiveAttrib, glGetActiveUniform, glGetInfoLog,
        glGetAttachedShaders, glGetAttachedObjects, glGetShaderSource,
        glGetActiveAttrib, glGetBufferSubData, glGen*, etc.

    5.  If a new query with an explicit buffer size is called and the buffer
        size is not sufficient to return the data, what happens?

        RESOLVED:  Return an INVALID_OPERATION error and ignore the query.

        Some consideration was given to clearing the entire buffer range.
        This might arguably avoid applications subsequently reading from
        uninitialized buffers.

        This was rejected for several reasons:

        1)  Doing something when there's an error is inconsistent with
            the rest of OpenGL's operation.

        2)  If the buffer is left untouched, the application can initialize
            the buffer to some bogus value (NaN or an invalid negative
            value) and notice that the buffer was left unmodified after
            the query without the expense of checking for OpenGL errors.

        3)  Many commands return information through packing pixels based
            on the pixel store state.  The pixel store state allows skipping
            over some data (GL_SKIP_PIXELS, GL_SKIP_ROWS, etc.) so zero'ing
            memory for the entire buffer isn't a good idea.


    6.  Can you explain why various glGet queries do NOT have new
        "sized" versions?

        RESOLVED:

        Queries always returning a constant number of bytes:

            OpenGL 1.0
                glGetClipPlane
                    - always 4*sizeof(GLdouble)
            OpenGL 2.0
                glGetVertexAttribdv
                    - always 4*sizeof(GLdouble)
                glGetVertexAttribfv
                    - always 4*sizeof(GLfloat)
                glGetVertexAttribiv
                    - always 4*sizeof(GLint)

        Queries with an effective buffer size parameter already:

            OpenGL 1.5
                glGetBufferSubData
                    - returns size (parameter) bytes

        Queries with an effective buffer bound (no more bytes than)
        parameter already:

            OpenGL 2.0
                glGetAttachedShaders
                    - returns no more than sizeof(GLuint)*maxCount
                      to count and no more than sizeof(GLuint)*maxCount
                      to shaders
                glGetShaderInfoLog
                glGetProgramInfoLog
                glGetShaderSource
                glGetActiveAttrib
                glGetActiveUniform
                    - returns no more than bufSize bytes
            OpenGL 3.0
                glGetTransformFeedbackVarying
                    - returns no more than bufSize bytes
            OpenGL 3.2
                glGetUniformIndices
                    - returns sizeof(GLuint)*uniformCount bytes
                glGetActiveUniformName
                glGetActiveUniformBlockName
                    - returns no more than bufSize bytes

        Query's some function of enumeration parameters fully determine
        the number bytes returned:

            OpenGL 1.0
                glGetIntegerv
                glGetFloatv
                glGetDoublev
                glGetBooleanv
                glGetLightiv
                glGetLightfv
                glGetMaterialfv
                glGetMaterialiv
                glGetTexEnvfv
                glGetTexEnviv
                glGetTexGendv
                glGetTexGenfv
                glGetTexGeniv
                glGetTexParameterfv
                glGetTexParameteriv
                glGetTexLevelParameterfv
                glGetTexLevelParameteriv
                    - fully determined by pname parameter
            OpenGL 1.1
                glGetPointerv
                    - fully determined by pname parameter
                glGenTextures
                    - sizeof(GLuint)*n
            ARB_imaging
                glGetColorTableParameterfv
                glGetColorTableParameteriv
                glGetConvolutionParameterfv
                glGetConvolutionParameteriv
                glGetHistogramParameterfv
                glGetHistogramParameteriv
                glGetMinmaxParameterfv
                glGetMinmaxParameteriv
                    - fully determined by pname parameter
            OpenGL 1.5
                glGenBuffers
                glGenQueries
                    - sizeof(GLuint)*n
                glGetBufferParameteriv
                glGetQueryObjectiv
                glGetQueryObjectfv
                glGetQueryiv
                    - fully determined by pname parameter
            OpenGL 2.0
                glGetVertexAttribPointerv
                glGetShaderiv
                glGetProgramiv
                    - fully determined by pname parameter
            OpenGL 3.0
                glGenRenderbuffers
                glGenFramebuffers
                glGenVertexArrays
                    - sizeof(GLuint)*n
            OpenGL 3.2
                glGetActiveUniformBlockiv
                    - function of pname and uniformCount
                glGetActiveUniformsiv
                    - function of pname

            NV_vertex_program
                glGenProgramsNV
                    - sizeof(GLuint)*n
            ARB_vertex_program
                glGenProgramsARB
                    - sizeof(GLuint)*n

    7. What can cause a graphics reset?

       Either user or implementor errors may result in a graphics reset.
       If the application attempts to perform a rendering that takes too long
       whether due to an infinite loop in a shader or even just a rendering
       operation that takes too long on the given hardware. Implementation
       errors may produce badly formed hardware commands. Memory access errors
       may result from user or implementor mistakes. Any of these events may
       result in a graphics reset event that will be detectable by the mechanism
       described in this extension.

    8. How should the application react to a reset context event?

       RESOLVED: For this extension, the application is expected to query
       the reset status until NO_ERROR is returned. If a reset is encountered,
       at least one *RESET* status will be returned. Once NO_ERROR is
       encountered, the application can safely destroy the old context and
       create a new one.

       After a reset event, apps should not use a context for any purpose
       other than determining its reset status, and then destroying it. If a
       context receives a reset event, all other contexts in its share group
       will also receive reset events, and should be destroyed and
       recreated.

       Apps should be cautious in interpreting the GUILTY and INNOCENT reset
       statuses. These are guidelines to the immediate cause of a reset, but
       not guarantees of the ultimate cause.

    9. If a graphics reset occurs in a shared context, what happens in
       shared contexts?

       RESOLVED: A reset in one context will result in a reset in all other
       contexts in its share group. This is mandated, not recommended
       behavior as of revision 14.

   10. How can an application query for robust buffer access support,
       since this is now determined at context creation time?

       RESOLVED. The application can query the CONTEXT_FLAGS bitfield
       using GetIntegerv and check for the presence of CONTEXT_FLAG_-
       ROBUST_ACCESS_BIT_ARB.

   11. How is the reset notification behavior controlled?

       RESOLVED: Reset notification behavior is determined at context
       creation time using GLX/WGL/etc. mechanisms. In order that shared
       objects be handled predictably, a context cannot share with
       another context unless both have the same reset notification
       behavior.

Revision History

    Rev.    Date       Author     Changes
    ----  ------------ ---------  --------------------------------------------
     18   25 Jun 2014  Jon Leech  Fix type of <params> in Get*Uniformdv.
     17   17 Sep 2012  Jon Leech  Clarify that GetnUniform* does not write
                                  any data if bufSize is less than required
                                  (Bug 8739).
     16   25 Jun 2012  Jon Leech  Add interactions with ARB_imaging and 
                                  core profile.
     15   10 Apr 2012  Jon Leech  Fix description of INVALID_OPERATION
                                  error to be when required data size is
                                  *greater* than bufSize, not *less*.
     14   22 Jul 2010  Jon Leech  Require resets to be delivered to all
                                  contexts which share objects. Expand on
                                  recommended recovery behavior in Issues 8
                                  and 9. Assign enum for new token.
     13   21 Jul 2010  Jon Leech  Remove RequestGraphicsResetNotificationARB
                                  and determine graphics reset notification
                                  behavior at context creation time in
                                  separate GLX/WGL extensions.
     12   19 Jul 2010  pdaniell   Added missing GetnUniformdARB. Add additional
                                  language to the "Graphics Reset Recovery"
                                  section to clarify objects of shared contexts.
                                  Revert revision #7 changes to restore the
                                  old "bufSize" behavior and remove the new
                                  "length" parameter, both of which proved
                                  problematic with implementation. Truncating
                                  the output buffer data written to "bufSize"
                                  length is hard to implement efficiently in
                                  software and impossible with some hardware
                                  paths. Also the additional "length" parameter
                                  caused PBO based async calls to become sync,
                                  which is undesirable.
     11   07 Jun 2010  groth      Clarify PBO errors/sized queries interaction
                                  Make consistent the app response to a reset
                                  Resolve issue 10 per revision 10 changes.
     10   07 Jun 2010  Jon Leech  Add a bit to the context flags query
                                  indicating whether or not robust buffer
                                  access was enabled at context creation.
      9   06 Jun 2010  Jon Leech  Note interactions with context creation
                                  extensions enabling robust buffer
                                  access, and add issue 10 regarding
                                  queries for robust buffer access.
                                  Remove dangling references to old
                                  ROBUST_BUFFER_ACCESS token.
      8   21 May 2010  groth      bmerry comment response
                                  Restore ARB suffixes in light of rejection from core
      7   20 May 2010  groth      Allow bounds checking using context creation flag
                                  Fix issues.
                                  Revise bounded queries to take and return lengths.
                                  Add query for current reset strategy.
                                  72 column resizing.
      6   06 May 2010  groth      ARBify, catch a few sized gets that hadn't
                                  been named correctly.
      5   05 May 2010  groth      Add clarification regarding recovered reset
                                  detection.
      4   02 May 2010  groth      Remove references to deleted functionality.
                                  Add issue addressing differences with 
      3   15 Apr 2010  groth      Describe GLSL array behavior when using
                                  robust arrays.
                                  Add issue explaining graphics reset causes.
      2   22 Mar 2010  groth      Flesh out missing secions. Remove vestiges of
                                  specified limits API. Rename sized queries.
                                  Various grammar corrections and clarifications.
      1   19 Jan 2010  mjk        Initial version