Name

    ANGLE_robust_client_memory

Name Strings

    GL_ANGLE_robust_client_memory

Contributors

    Geoff Lang, Google

Contacts

    Geoff Lang, Google (geofflang 'at' google.com)

Status

    Draft

Version

    Version 4, March 30, 2017

Number

    OpenGL ES Extension #??

Dependencies

    OpenGL ES 2.0 is required.

    This extension is written against the OpenGL ES 3.0 specification.

    This extension interacts with OpenGL ES 3.0.

    This extension interacts with OpenGL ES 3.1.

    This extension interacts with OES_mapbuffer.

    This extension interacts with OES_texture_3d.

    This extension interacts with EXT_disjoint_timer_query.

    This extension interacts with EXT_occlusion_query_boolean.

    This extension interacts with ANGLE_texture_multisample.

    This extension interacts with ANGLE_get_tex_level_parameter.

    This extension interacts with ANGLE_shader_pixel_local_storage.

Overview

    This extension adds overloads of many OpenGL ES functions that read from
    and write to client memory to ensure that all reads and writes done by the
    OpenGL ES implementation are safe.  When the OpenGL ES API is exposed to
    users through complex bindings such as WebGL, allowing undefined behavior
    that may result in crashing the implementation is not acceptable.

New Types

    None

New Procedures and Functions

    void GetBooleanvRobustANGLE(enum pname, sizei paramCount, sizei *length,
                                boolean *data);

    void GetBufferParameterivRobustANGLE(enum target, enum pname,
                                         sizei paramCount, sizei *length,
                                         int *params);

    void GetFloatvRobustANGLE(enum pname, sizei paramCount, sizei *length,
                              float *data);

    void GetFramebufferAttachmentParameterivRobustANGLE(enum target,
                                                        enum attachment,
                                                        enum pname,
                                                        sizei paramCount,
                                                        sizei *length,
                                                        int *params);

    void GetIntegervRobustANGLE(enum pname, sizei paramCount, sizei *length,
                                int *data);

    void GetProgramivRobustANGLE(uint program, enum pname, sizei paramCount,
                                 sizei *length, int *params);

    void GetRenderbufferParameterivRobustANGLE(enum target, enum pname,
                                               sizei paramCount, sizei *length,
                                               int *params);

    void GetShaderivRobustANGLE(uint shader, enum pname, sizei paramCount,
                                sizei *length, int *params);

    void GetTexParameterfvRobustANGLE(enum target, enum pname, sizei paramCount,
                                      sizei *length, float *params);

    void GetTexParameterivRobustANGLE(enum target, enum pname, sizei paramCount,
                                      sizei *length, int *params);

    void GetUniformfvRobustANGLE(uint program, int location, sizei bufSize,
                                 sizei *length, float *params);

    void GetUniformivRobustANGLE(uint program, int location, sizei bufSize,
                                 sizei *length, int *params);

    void GetVertexAttribfvRobustANGLE(uint index, enum pname, sizei paramCount,
                                      sizei *length, float *params);

    void GetVertexAttribivRobustANGLE(uint index, enum pname, sizei paramCount,
                                      sizei *length, int *params);

    void GetVertexAttribPointervRobustANGLE(uint index, enum pname,
                                            sizei paramCount, sizei *length,
                                            void **pointer);

    void ReadPixelsRobustANGLE(int x, int y, sizei width, sizei height,
                               enum format, enum type, sizei bufSize,
                               sizei *length, sizei *columns, sizei *rows,
                               void *pixels);

    void TexImage2DRobustANGLE(enum target, int level, int internalformat,
                               sizei width, sizei height, int border,
                               enum format, enum type, sizei bufSize,
                               const void *pixels);

    void TexParameterfvRobustANGLE(enum target, enum pname, sizei paramCount,
                                   const float *params);

    void TexParameterivRobustANGLE(enum target, enum pname, sizei paramCount,
                                   const int *params);

    void TexSubImage2DRobustANGLE(enum target, int level, int xoffset,
                                  int yoffset, sizei width, sizei height,
                                  enum format, enum type, sizei bufSize,
                                  const void *pixels);

    void TexImage3DRobustANGLE(enum target, int level, int internalformat,
                               sizei width, sizei height, sizei depth,
                               int border, enum format, enum type,
                               sizei bufSize, const void *pixels);

    void TexSubImage3DRobustANGLE(enum target, int level, int xoffset,
                                  int yoffset, int zoffset, sizei width,
                                  sizei height, sizei depth, enum format,
                                  enum type, sizei bufSize, const void *pixels);

    void GetQueryivRobustANGLE(enum target, enum pname, sizei paramCount,
                               sizei *length, int *params);

    void GetQueryObjectuivRobustANGLE(uint id, enum pname, sizei paramCount,
                                      sizei *length, uint *params);

    void GetBufferPointervRobustANGLE(enum target, enum pname, sizei paramCount,
                                      sizei *length, void **params);

    void GetIntegeri_vRobustANGLE(enum target, uint index, sizei paramCount,
                                  sizei *length, int *data);

    void GetInternalformativRobustANGLE(enum target, enum internalformat,
                                        enum pname, sizei paramCount,
                                        sizei *length, int *params);

    void GetVertexAttribIivRobustANGLE(uint index, enum pname, sizei paramCount,
                                       sizei *length, int *params);

    void GetVertexAttribIuivRobustANGLE(uint index, enum pname,
                                        sizei paramCount, sizei *length,
                                        uint *params);

    void GetUniformuivRobustANGLE(uint program, int location, sizei bufSize,
                                  sizei *length, uint *params);

    void GetActiveUniformBlockivRobustANGLE(uint program,
                                            uint uniformBlockIndex, enum pname,
                                            sizei paramCount, sizei *length,
                                            int *params);

    void GetInteger64vRobustANGLE(enum pname, sizei paramCount, sizei *length,
                                  int64 *data);

    void GetInteger64i_vRobustANGLE(enum target, uint index, sizei paramCount,
                                    sizei *length, int64 *data);

    void GetBufferParameteri64vRobustANGLE(enum target, enum pname,
                                           sizei paramCount, sizei *length,
                                           int64 *params);

    void SamplerParameterivRobustANGLE(uint sampler, enum pname,
                                       sizei paramCount, const int *param);

    void SamplerParameterfvRobustANGLE(uint sampler, enum pname,
                                       sizei paramCount, const float *param);

    void GetSamplerParameterivRobustANGLE(uint sampler, enum pname,
                                          sizei paramCount, sizei *length,
                                          int *params);

    void GetSamplerParameterfvRobustANGLE(uint sampler, enum pname,
                                          sizei paramCount, sizei *length,
                                          float *params);

    void GetMultisamplefvRobustANGLE(enum pname, uint index, sizei paramCount,
                                     sizei *length, float *val);

    void GetTexLevelParameterivRobustANGLE(enum target, int level, enum pname,
                                           sizei paramCount, sizei *length,
                                           int *params);

    void GetTexLevelParameterfvRobustANGLE(enum target, int level, enum pname,
                                           sizei paramCount, sizei *length,
                                           float *params);

    void GetQueryObjectivRobustANGLE(uint id, enum pname, sizei paramCount,
                                     sizei *length, int *params);

    void GetQueryObjecti64vRobustANGLE(uint id, enum pname, sizei paramCount,
                                       sizei *length, int64 *params);

    void GetQueryObjectui64vRobustANGLE(uint id, enum pname, sizei paramCount,
                                        sizei *length, uint64 *params);

    void GetFramebufferPixelLocalStorageParameterfvRobustANGLE(int plane,
                                                               enum pname,
                                                               sizei paramCount,
                                                               sizei *length,
                                                               float *params);

    void GetFramebufferPixelLocalStorageParameterivRobustANGLE(int plane,
                                                               enum pname,
                                                               sizei paramCount,
                                                               sizei *length,
                                                               int *params);

    void GetFramebufferPixelLocalStorageParameteruivRobustANGLE(int plane,
                                                                enum pname,
                                                                sizei paramCount,
                                                                sizei *length,
                                                                uint *params);

New Tokens

    None

Additions to the OpenGL ES Specification:

    The xRobustANGLE entry points perform additional validation using the
    <paramCount> or <bufSize> parameters to indicate the maximum number of
    values or bytes respectively that can be read from or written to the
    provided buffer.

    The optional <length> parameter specifies an address of a variable to
    receive the number of values or bytes written to the buffer.  Only
    ReadPixelsRobustANGLE outputs the number of bytes; all other entry points
    defined in this extension output the number of values.  If <length> is NULL
    or an error is generated, nothing is written to <length>.

    The optional <columns> and <rows> parameters of ReadPixelsRobustANGLE
    specify addresses of variables to receive the number of columns and rows of
    pixels written to the buffer which may be less than the <width> and <height>
    parameters if they would have read outside of the framebuffer. If <columns>
    is NULL, nothing is written to <columns>; if <rows> is NULL, nothing is
    written to <rows>; if an error is generated, nothing is written to <columns>
    and <rows>.

    Calls to "xRobustANGLE" will generate errors under the same conditions as
    "x". Any instances of undefined behavior in "x" will also be undefined in
    "xRobustANGLE".  For example, it is invalid to call GetQueryivRobustANGLE
    if the context version is less than OpenGL ES version 3.0 and
    neither the EXT_disjoint_timer_query nor EXT_occlusion_query_boolean
    extensions are supported.

    It is invalid to call GetInternalformativRobustANGLE with the <paramCount>
    value less than the expected number of returned values for the requested
    parameter name. This behavior is different from GetInternalformativ,
    which uses the <count> parameter to clamp the number of returned values.

Errors

    The error INVALID_VALUE is generated by xRobustANGLE commands if
    <paramCount> is negative.

    The error INVALID_VALUE is generated by xRobustANGLE commands if <bufSize>
    is negative.

    The error INVALID_OPERATION is generated by xRobustANGLE commands if
    <paramCount> is less than the number of parameters to be read from or
    written to client memory.

    The error INVALID_OPERATION is generated by xRobustANGLE commands if
    <bufSize> is less than the number of bytes to be read from or written to
    client memory.

Interactions with OpenGL ES 3.0

    If OpenGL ES 3.0 is not supported, remove all references to
    GetIntegeri_vRobustANGLE, GetInternalformativRobustANGLE,
    GetVertexAttribIivRobustANGLE, GetVertexAttribIuivRobustANGLE,
    GetUniformuivRobustANGLE, GetActiveUniformBlockivRobustANGLE,
    GetInteger64i_vRobustANGLE, GetBufferParameteri64vRobustANGLE,
    SamplerParameterivRobustANGLE, SamplerParameterfvRobustANGLE,
    GetSamplerParameterivRobustANGLE, and GetSamplerParameterfvRobustANGLE.

Interactions with OpenGL ES 3.0 and OES_mapbuffer

    If neither OpenGL ES 3.0, nor OES_mapbuffer are supported, remove all
    references to GetBufferPointervRobustANGLE.

Interactions with OpenGL ES 3.0 and OES_texture_3d

    If neither OpenGL ES 3.0, nor OES_texture_3d are supported, remove all
    references to TexImage3DRobustANGLE and TexSubImage3DRobustANGLE.

Interactions with OpenGL ES 3.0, EXT_disjoint_timer_query, and
EXT_occlusion_query_boolean

    If neither OpenGL ES 3.0, nor EXT_disjoint_timer_query, nor
    EXT_occlusion_query_boolean are supported, remove all references to
    GetQueryivRobustANGLE and GetQueryObjectuivRobustANGLE.

Interactions with OpenGL ES 3.0 and EXT_disjoint_timer_query

    If neither OpenGL ES 3.0, nor OES_texture_3d are supported, remove all
    references to GetInteger64vRobustANGLE, GetQueryObjectivRobustANGLE,
    GetQueryObjecti64vRobustANGLE, and GetQueryObjectui64vRobustANGLE.

Interactions with OpenGL ES 3.1 and ANGLE_texture_multisample

    If neither OpenGL ES 3.1, nor ANGLE_texture_multisample are supported,
    remove all references to GetMultisamplefvRobustANGLE.

Interactions with OpenGL ES 3.1 and ANGLE_get_tex_level_parameter

    If neither OpenGL ES 3.1, nor ANGLE_get_tex_level_parameter are supported,
    remove all references to GetTexLevelParameterfvRobustANGLE and
    GetTexLevelParameterivRobustANGLE.

Interactions with ANGLE_shader_pixel_local_storage

    If ANGLE_shader_pixel_local_storage is not supported,
    remove all references to
    GetFramebufferPixelLocalStorageParameter{f,i,ui}vRobustANGLE.

Issues

    1) Should additional entry points be added to specify sizes of client side
       data provided to the VertexAttribPointer functions?

    2) Should <length> be allowed to be null?

       RESOLVED: Yes, <length> will not be written to when it is a null
       pointer.

    3) Should <bufSize> be specified in bytes or values (uint, int, float,
       etc)?

       RESOLVED: <bufSize> is specified in bytes; <paramCount> is specified
       in values.

    4) Should <length> be written to if an error is generated?

       RESOLVED: No, using the precedent set by glGetSynciv.

Revision History

    Rev.    Date         Author     Changes
    ----  -------------  ---------  -------------------------------------------
      1   Sept 26, 2016  geofflang  Initial version
      2   Sept 28, 2016  geofflang  Changed name from ANGLE_robust_queries to
                                    ANGLE_robust_client_memory, added issue 3.
      3   Oct 7, 2016    geofflang  Added and resolved issue 4.
      4   Mar 30, 2017   geofflang  Added columns and rows to ReadPixels.
