1Name
2
3    ANGLE_robust_client_memory
4
5Name Strings
6
7    GL_ANGLE_robust_client_memory
8
9Contributors
10
11    Geoff Lang, Google
12
13Contacts
14
15    Geoff Lang, Google (geofflang 'at' google.com)
16
17Status
18
19    Draft
20
21Version
22
23    Version 4, March 30, 2017
24
25Number
26
27    OpenGL ES Extension #??
28
29Dependencies
30
31    OpenGL ES 2.0 is required.
32
33    This extension is written against the wording of the OpenGL ES
34    3.2 specification.
35
36    Interacts with GL_KHR_debug, GL_EXT_disjoint_timer_queries,
37    GL_KHR_robustness.
38
39Overview
40
41    This extension adds overloads of many OpenGL ES functions that read from
42    and write to client memory to ensure that all reads and writes done by the
43    OpenGL ES implementation are safe.  When the OpenGL ES API is exposed to
44    users through complex bindings such as WebGL, allowing undefined behaviour
45    that may result in crashing the implementation is not acceptable.
46
47New Types
48
49    None
50
51New Procedures and Functions
52
53    void GetBooleanvRobustANGLE(enum pname, sizei bufSize, sizei *length, boolean *data)
54    void GetBufferParameterivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
55    void GetFloatvRobustANGLE(enum pname, sizei bufSize, sizei *length, float *data)
56    void GetFramebufferAttachmentParameterivRobustANGLE(enum target, enum attachment, enum pname, sizei bufSize, sizei *length, int *params)
57    void GetIntegervRobustANGLE(enum pname, sizei bufSize, sizei *length, int *data)
58    void GetProgramivRobustANGLE(uint program, enum pname, sizei bufSize, sizei *length, int *params)
59    void GetRenderbufferParameterivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
60    void GetShaderivRobustANGLE(uint shader, enum pname, sizei bufSize, sizei *length, int *params)
61    void GetTexParameterfvRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, float *params)
62    void GetTexParameterivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
63    void GetUniformfvRobustANGLE(uint program, int location, sizei bufSize, sizei *length, float *params)
64    void GetUniformivRobustANGLE(uint program, int location, sizei bufSize, sizei *length, int *params)
65    void GetVertexAttribfvRobustANGLE(uint index, enum pname, sizei bufSize, sizei *length, float *params)
66    void GetVertexAttribivRobustANGLE(uint index, enum pname, sizei bufSize, sizei *length, int *params)
67    void GetVertexAttribPointervRobustANGLE(uint index, enum pname, sizei bufSize, sizei *length, void **pointer)
68    void ReadPixelsRobustANGLE(int x, int y, sizei width, sizei height, enum format, enum type, sizei bufSize, sizei *length, sizei *columns, sizei *rows, void *pixels)
69    void TexImage2DRobustANGLE(enum target, int level, int internalformat, sizei width, sizei height, int border, enum format, enum type, sizei bufSize, const void *pixels)
70    void TexParameterfvRobustANGLE(enum target, enum pname, sizei bufSize, const GLfloat *params)
71    void TexParameterivRobustANGLE(enum target, enum pname, sizei bufSize, const GLint *params)
72    void TexSubImage2DRobustANGLE(enum target, int level, int xoffset, int yoffset, sizei width, sizei height, enum format, enum type, sizei bufSize, const void *pixels)
73    void CompressedTexImage2D(enum target, int level, enum internalformat, sizei width, sizei height, int border, sizei imageSize, sizei bufSize, const void* data)
74    void CompressedTexSubImage2D(enum target, int level, int xoffset, int yoffset, sizei width, sizei height, enum format, sizei imageSize, sizei bufSize, const void* data)
75    void CompressedTexImage3D(enum target, int level, enum internalformat, sizei width, sizei height, sizei depth, int border, sizei imageSize, sizei bufSize, const void* data)
76    void CompressedTexSubImage3D(enum target, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, sizei imageSize, sizei bufSize, const void* data)
77
78    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);
79    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);
80    void GetQueryivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
81    void GetQueryObjectuivRobustANGLE(uint id, enum pname, sizei bufSize, sizei *length, uint *params)
82    void GetBufferPointervRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, void **params)
83    void GetIntegeri_vRobustANGLE(enum target, uint index, sizei bufSize, sizei *length, int *data)
84    void GetInternalformativRobustANGLE(enum target, enum internalformat, enum pname, sizei bufSize, sizei *length, int *params)
85    void GetVertexAttribIivRobustANGLE(uint index, enum pname, sizei bufSize, sizei *length, int *params)
86    void GetVertexAttribIuivRobustANGLE(uint index, enum pname, sizei bufSize, sizei *length, uint *params)
87    void GetUniformuivRobustANGLE(uint program, int location, sizei bufSize, sizei *length, uint *params)
88    void GetActiveUniformBlockivRobustANGLE(uint program, uint uniformBlockIndex, enum pname, sizei bufSize, sizei *length, int *params)
89    void GetInteger64vRobustANGLE(enum pname, sizei bufSize, sizei *length, int64 *data)
90    void GetInteger64i_vRobustANGLE(enum target, uint index, sizei bufSize, sizei *length, int64 *data)
91    void GetBufferParameteri64vRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int64 *params)
92    void SamplerParameterivRobustANGLE(uint sampler, enum pname, sizei bufSize, const GLint *param)
93    void SamplerParameterfvRobustANGLE(uint sampler, enum pname, sizei bufSize, const GLfloat *param)
94    void GetSamplerParameterivRobustANGLE(uint sampler, enum pname, sizei bufSize, sizei *length, int *params)
95    void GetSamplerParameterfvRobustANGLE(uint sampler, enum pname, sizei bufSize, sizei *length, float *params)
96
97    void GetFramebufferParameterivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
98    void GetProgramInterfaceivRobustANGLE(uint program, enum programInterface, enum pname, sizei bufSize, sizei *length, int *params)
99    void GetBooleani_vRobustANGLE(enum target, uint index, sizei bufSize, sizei *length, boolean *data)
100    void GetMultisamplefvRobustANGLE(enum pname, uint index, sizei bufSize, sizei *length, float *val)
101    void GetTexLevelParameterivRobustANGLE(enum target, int level, enum pname, sizei bufSize, sizei *length, int *params)
102    void GetTexLevelParameterfvRobustANGLE(enum target, int level, enum pname, sizei bufSize, sizei *length, float *params)
103
104    void GetPointervRobustANGLERobustANGLE(enum pname, sizei bufSize, sizei *length, void **params)
105    void ReadnPixelsRobustANGLE(int x, int y, sizei width, sizei height, enum format, enum type, sizei bufSize, sizei *length, sizei *columns, sizei *rows, void *data)
106    void GetnUniformfvRobustANGLE(uint program, int location, sizei bufSize, sizei *length, float *params)
107    void GetnUniformivRobustANGLE(uint program, int location, sizei bufSize, sizei *length, int *params)
108    void GetnUniformuivRobustANGLE(uint program, int location, sizei bufSize, sizei *length, uint *params)
109    void TexParameterIivRobustANGLE(enum target, enum pname, sizei bufSize, const GLint *params)
110    void TexParameterIuivRobustANGLE(enum target, enum pname, sizei bufSize, const GLuint *params)
111    void GetTexParameterIivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, int *params)
112    void GetTexParameterIuivRobustANGLE(enum target, enum pname, sizei bufSize, sizei *length, uint *params)
113    void SamplerParameterIivRobustANGLE(uint sampler, enum pname, sizei bufSize, const GLint *param)
114    void SamplerParameterIuivRobustANGLE(uint sampler, enum pname, sizei bufSize, const GLuint *param)
115    void GetSamplerParameterIivRobustANGLE(uint sampler, enum pname, sizei bufSize, sizei *length, int *params)
116    void GetSamplerParameterIuivRobustANGLE(uint sampler, enum pname, sizei bufSize, sizei *length, uint *params)
117
118    void GetQueryObjectivRobustANGLE(uint id, enum pname, sizei bufSize, sizei *length, int *params)
119    void GetQueryObjecti64vRobustANGLE(uint id, enum pname, sizei bufSize, sizei *length, int64 *params)
120    void GetQueryObjectui64vRobustANGLE(uint id, enum pname, sizei bufSize, sizei *length, uint64 *params)
121
122New Tokens
123
124    None
125
126Additions to the OpenGL ES Specification:
127
128    The xRobustANGLE entry points perform additional validation using <bufSize>
129    to indicate the maximum number of values that can be read from or written
130    to the provided buffer.  INVALID_OPERATION is generated if <bufSize> is not
131    large enough.  The optional <length> specifies an address of a variable to
132    recieve the number of values written to the buffer.  When an error is
133    generated nothing will be written to <length>.
134
135    The <columns> and <rows> parameters of ReadPixelsRobustANGLE and
136    ReadnPixelsRobustANGLE specify addresses of variables to recieve the number
137    of columns and rows of pixels written to the buffer which may be less than
138    the <width> and <height> parameters if they would have read outside of the
139    framebuffer.
140
141    Calls to "xRobustANGLE" will generate errors under the same conditions as
142    "x". Any instances of undefined behaviour in "x" will also be undefined in
143    "xRobustANGLE".  For example, it is invalid to call
144    GetPointervRobustANGLERobustANGLE without first verifying that the context
145    is at least OpenGL ES version 3.2 or the GL_KHR_debug extension is present.
146
147Issues
148
149    1) Should additional entry points be added to specify sizes of client side
150       data provided to the VertexAttribPointer functions?
151
152    2) Should <length> be allowed to be null?
153
154       RESOLVED: Yes, <length> will not be written to when it is a null
155       pointer.
156
157    3) Should <bufSize> be specified in bytes or values (uint, int, float,
158       etc)?
159
160       There is no consistancy in current entry points for this.  For example,
161       glGetnUniformuiv indicates that bufSize is in bytes while GetSynciv
162       uses values despite GetnUniformuiv having a clear value type.
163
164       RESOLOVED: <bufSize> always indicates size in values. Functions that
165       specify data by void* such as TexImage2DRobustANGLE treat the client
166       data as bytes.
167
168    4) Should <length> be written to if an error is generated?
169
170       RESOLVED: No, using the prescedent set by glGetSynciv.
171
172Revision History
173
174    Rev.    Date         Author     Changes
175    ----  -------------  ---------  -------------------------------------------
176      1   Sept 26, 2016  geofflang  Initial version
177      2   Sept 28, 2016  geofflang  Changed name from ANGLE_robust_queries to
178                                    ANGLE_robust_client_memory, added issue 3.
179      3   Oct 7, 2016    geofflang  Added and resolved issue 4.
180      4   Mar 30, 2017   geofflang  Added columns and rows to ReadPixels.
181