224 MISCELLANEOUS OPENGL ES FEATURES CHAPTER 10 is used for clearing the various buffers all at the same time. The input parameter mask is a bitwise OR of sy mbolic constants that indicate which buffers should be cleared. Supported constants are GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, and GL_STENCIL_BUFFER_BIT. The value that the buffer is filled with during the clear- ing is set with the following functions: void glClearColor{fx}(T red, T green, T blue, T alpha) void glClearDepth{fx}(T depth) void glClearStencil(GLint s) The color or depth argument values are clamped to the range [0, 1], whereas the stencil value is ANDed with 2 s − 1,wheres is the number of stencil bits in the stencil buffer. Their initial values, respectively, are (0, 0, 0, 0), 1.0, and 0. Here is an example of how these calls are used: glClearColorf( 1.0f, 0.0f, 0.0f, 0.0f ); glClearDepthf( 1.0f ); glClear( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT ); 10.1.2 READING BACK THE COLOR BUFFER Of the different frame buffer channels only the color buffer can be read back. OpenGL ES 1.x does not provide any mechanism for reading the contents of the depth or stencil buffers. One should note that even reading back the color buffer can be a very time- consuming operation. This is because the call has to flush the rendering pipeline as all buffered rendering commands need to be executed before the function returns. Modern graphics hardware have very deep pipelines, often buffering hundreds or thousands of triangles, in some architectures even from different frames. Also, if the rendering server is implemented on an external accelerator chip, the bus connecting it back to the client can be very slow. void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, GLvoid * pixels) is used for reading back the contents of the color buffer. The parameters x, y, width, and height are all expressed in pixels, and define a rectangular portion of the screen that is copied. The only supported format–type pair copied from desktop OpenGL is GL_RGBA and GL_UNSIGNED_BYTE. OpenGL ES implementations must support one additional format–type pair which can be chosen by the implementation. This usually corresponds to the native format of the color buffer, so that no expensive conversion operations need take place while reading pixels, and must be one of the combinations in Table 9.1. The values of format and type in this case may be obtained by calling glGetIntegerv with the tokens GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES and GL_IMPLEMENTATION_COLOR_READ_TYPE_OES, respectively. The last par ame- ter pixels points to a memory block into which the requested portion of the frame buffer is copied. SECTION 10.2 STATE QUERIES 225 void glPixelStorei(GL_PACK_ALIGNMENT, GLint param) is used to control the packing alignment of pixel transfer operations. As explained in Section 9.2.2, this command specifies the memory alignment at the beginning of each row. The default value is 4, meaning that at the beginning of a new row the storage pointer is advanced between 0 and 3 bytes before writing so that the memory address of the first pixel in the row becomes divisible by 4. If the value is 1 no alignment is done. Other possible values are 2 and 8. The following code sets word-aligned packing (a word is 4 bytes), and reads in the lower- left 240 × 320 pixel box. Aligned writes are likely to execute faster than unaligned ones. GLubyte buffer[4*240*320 + 3]; /* get aligned pointer */ pixels = ((buffer + 3) >> 2) << 2; glPixelStorei( GL_PACK_ALIGNMENT, 4 ); glReadPixels( 0, 0, 240, 320, GL_RGBA, GL_UNSIGNED_BYTE, pixels ); 10.1.3 FLUSHING THE COMMAND STREAM Some commands, such as glReadPixels, implicitly synchronize the client and the server. You can also perform the synchronization explicitly. Calling void glFlush(void) gives the server an asynchronous signal telling that now would be a good time to start executing all the possibly buffered GL calls—new ones might not be coming for a while. However, you do not know when the rendering has completed, just that it will sometime in the future. A synchronous version that only returns after all the rendering has been completed is void glFinish(void) Even though glFinish guarantees that all calls have been completed, applications using double-buffered window surfaces cannot verify it, as eglSwapBuffers is the actual call that finally triggers the buffer swap. eglSwapBuffers implicitly calls glFinish. With pbuffer surfaces the application really gets the pixels only after eglCopyBuffers or glReadPixels . For more details, see Chapter 11. 10.2 STATE QUERIES State queries can be divided into two broad categories: static and dynamic. Static queries are the ones that produce the same result throughout the lifetime of a context, such as querying the number of supported texturing mapping units, or the list of supported extensions. Dynamic state queries return information that may vary during the execution of a program, for example the current line width or dimensions of the scissor rectangle. 226 MISCELLANEOUS OPENGL ES FEATURES CHAPTER 10 With the exception of the error state, OpenGL ES 1.0 does not support querying any of the dynamic state. OpenGL ES 1.1, on the other hand, has wide support for dynamic state queries. 10.2.1 STATIC STATE In OpenGL ES 1.0 only the static state describing the implementation can be queried. With void glGetIntegerv(GLenum pname, GLint * params) you can query for the following values. GL_ALIASED_POINT_SIZE_RANGE the smallest and largest supported size for aliased points, the range must include 1. GL_ALIASED_LINE_WIDTH_RANGE the smallest and largest supported width for aliased lines the range must include 1. GL_ALPHA_BITS the number of alpha bitplanes in the color buffer. GL_BLUE_BITS the number of blue bitplanes in the color buffer. GL_COMPRESSED_TEXTURE_FORMATS a list of supported compressed texture formats, GL_NUM_COMPRESSED_TEXTURE_FORMATS of them. GL_DEPTH_BITS the number of bitplanes in the depth buffer. GL_GREEN_BITS the number of green bitplanes in the color buffer. GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES the preferred format for pixel read-back. GL_IMPLEMENTATION_COLOR_READ_TYPE_OES the preferred type for pixel read-back. GL_MAX_ELEMENTS_INDICES the recommended maximum vertex array index count. GL_MAX_ELEMENTS_VERTICES the recommended maximum vertex array vertex count. GL_MAX_LIGHTS the number of supported lights (≥ 8). GL_MAX_MODELVIEW_STACK_DEPTH the depth of the modelview matrix stack (≥ 16). GL_MAX_PROJECTION_STACK_DEPTH the depth of the projection matrix stack (≥ 2). GL_MAX_TEXTURE_SIZE an estimate of the largest texture the engine can handle (≥ 64). GL_MAX_TEXTURE_STACK_DEPTH the depth of the texture matrix stacks (≥ 2). GL_MAX_TEXTURE_UNITS the number of supported texture units (≥ 1). SECTION 10.2 STATE QUERIES 227 GL_MAX_VIEWPORT_DIMS two numbers: the maximum supported width and height of the viewport. Must be at least as large as the visible dimensions of the display. GL_NUM_COMPRESSED_TEXTURE_FORMATS the number of supported com- pressed texture formats. GL_RED_BITS the number of red bitplanes in the color buffer. GL_SMOOTH_LINE_WIDTH_RANGE the smallest and largest widths of antialiased lines. GL_SMOOTH_POINT_SIZE_RANGE the smallest and largest sizes of antialiased points. GL_STENCIL_BITS the number of bitplanes in the stencil buffer. GL_SUBPIXEL_BITS an estimate of the number of bits for subpixel resolution for window coordinate positions in rasterization (≥ 4). const GLubyte * glGetString(GLenum name) can be used to query the following null-terminated strings: GL_EXTENSIONS a space-separated list of supported extensions. GL_RENDERER the name of the renderer, typically specific to a particular configura- tion of a hardware platform. GL_VENDOR the name of the company responsible for this implementation. GL_VERSION “OpenGL ES-XX Y.Z” where XX = CM for Common Profile, XX = CL for Common Lite Profile, Y is the major version, Z is the minor version. For OpenGL ES Common Profile version 1.0 the string is “OpenGL ES-CM 1.0” (without the quotes). Here is an example on how to use the query functions. GLint red_bits, max_viewport[2]; GLubyte *str_ptr; glGetIntegerv( GL_RED_BITS, &red_bits ); glGetIntegerv( GL_MAX_VIEWPORT_DIMS, max_viewport ); str_ptr = glGetString( GL_EXTENSIONS ); 10.2.2 DYNAMIC STATE QUERIES OpenGL ES 1.1 introduces many more queries that can be performed with variants of glGet. In addition to glGetIntegerv we have void glGetBooleanv(GLenum pname, GLboolean * params) void glGetFixedv(GLenum pname, GLfixed * params) void glGetFloatv(GLenum pname, GLfloat * params) 228 MISCELLANEOUS OPENGL ES FEATURES CHAPTER 10 If a glGet command is issued that returns value t ypes different from the type of the value being obtained, a type conversion is performed. With glGetBooleanv,azero converts to GL_FALSE and other values convert to GL_TRUE. With glGetIntegerv a boolean converts to 1 or 0, and a float is rounded to the nearest integer, except for colors, depths, or normal coordinates, which are mapped so that 1.0 maps to the most positive representable integer value, and −1.0 to the most negative one. For glGetFloatv,a boolean maps to either 1.0 or 0.0, and an integer is coerced to float. If a value is too large to be represented with the requested type, the nearest representable value is returned. The new pnames that are supported in addition to those already in OpenGL ES 1.0 are listed below. GL_ALPHA_TEST_FUNC the alpha test function. GL_ALPHA_TEST_REF the reference value for alpha test. GL_BLEND_DST the destination blend function. GL_BLEND_SRC the source blend function. GL_COLOR_ARRAY_BUFFER_BINDING the bufferobject name bound to the color array. GL_COLOR_ARRAY_SIZE the number of components per color in the color array. GL_COLOR_ARRAY_STRIDE the byte offset between consecutive colors. GL_COLOR_ARRAY_TYPE the data type of each component in the color array. GL_COLOR_CLEAR_VALUE four values, the RGBA clear color. GL_COLOR_WRITEMASK four booleans indicating whether RGBA writes to color buffer are enabled. GL_CULL_FACE a symbolic constant indicating whether front or back faces are culled. GL_DEPTH_CLEAR_VALUE the depth buffer clear value. GL_DEPTH_FUNC the depth comparison function. GL_DEPTH_RANGE two values, the near and far mapping limits for depth. GL_DEPTH_WRITEMASK a boolean indicating whether the depth buffer is enabled for writing. GL_FOG_COLOR four values, the RGBA fog color. GL_FOG_DENSIT Y the fog density. GL_FOG_END the end fog distance for linear fog. GL_FOG_HINT the current fog hint. GL_FOG_MODE the current fog equation. GL_FOG_START the start fog distance for linear fog. GL_FRONT_FACE whetherclockwise or counterclockwise winding is treated as front- facing. SECTION 10.2 STATE QUERIES 229 GL_LIGHT_MODEL_AMBIENT the four RGBA components for the global ambient light color. GL_LIGHT_MODEL_TWO_SIDE a boolean stating whether two-sided lighting is enabled. GL_LINE_SMOOTH_HINT the current line antialiasing hint. GL_LINE_WIDTH the current line width. GL_LOGIC_OP_MODE the current logic operation mode. GL_MATRIX_MODE which matrix stack is currently the target of matrix operations. GL_MAX_CLIP_PLANES how many clip planes the implementation supports (≥ 1). GL_MODELVIEW_MATRIX sixteen values, the matrix on top of the modelview matrix stack. GL_MODELVIEW_MATRIX_FLOAT_AS_INT_BITS modelview matrix elements as integer array, according to the IEEE 754 floating-point single format bit layout. GL_MODELVIEW_STACK_DEPTH the number of matri ces in the modelview matrix stack. GL_NORMAL_ARRAY_BUFFER_BINDING the buffer object name bound to the normal array. GL_NORMAL_ARRAY_STRIDE byte offset between normals. GL_NORMAL_ARRAY_TYPE type of each normal. GL_PACK_ALIGNMENT the byte alignment used for writing pixel data to memory. GL_PERSPECTIVE_CORRECTION_HINT the current perspective correction hint. GL_POINT_SIZE the current point size. GL_POINT_SIZE_ARRAY_BUFFER_BINDING_OES the buffer object name bound to the point size array. GL_POINT_SIZE_ARRAY_STRIDE_OES byte offset between elements. GL_POINT_SIZE_ARRAY_TYPE_OES ty pe of point sizes. GL_POINT_SMOOTH_HINT the current point antialiasing hint. GL_POLYGON_OFFSET_FACTOR the polygon offset scaling factor. GL_POLYGON_OFFSET_UNITS the units argument for polygon offset. GL_PROJECTION_MATRIX sixteen values, the matrix on top of the projection matrix stack. GL_PROJECTION_MATRIX_FLOAT_AS_INT_BITS projection matrix elements as integer array, according to the IEEE 754 floating-point single format bit layout. GL_PROJECTION_STACK_DEPTH the number of matrices in the projection matrix stack. GL_SAMPLE_COVERAGE_INVERT a boolean indicating whether the sample coverage set by glSampleCoverage is inverted. 230 MISCELLANEOUS OPENGL ES FEATURES CHAPTER 10 GL_SAMPLE_COVERAGE_VALUE the sample coverage value set by glSample- Coverage. GL_SCISSOR_BOX four values describing the cur rent scissor box: x, y, width, he ight. GL_SHADE_MODEL the current shade model. GL_STENCIL_CLEAR_VALUE value stencil buffer is cleared to. GL_STENCIL_FAIL the action that is taken when the stencil test fails. GL_STENCIL_FUNC the cur rent stencil test function. GL_STENCIL_PASS_DEPTH_FAIL the action taken when the stencil test passes and the depth test fails. GL_STENCIL_PASS_DEPTH_PASS the action taken when both the stencil test and the depth test pass. GL_STENCIL_REF the current reference value used for stencil comparison. GL_STENCIL_VALUE_MASK the current mask that is applied both to the stencil reference value and the stencil buffer value before comparison. GL_STENCIL_WRITEMASK the current mask controlling writing to stencil buffer. GL_TEXTURE_BINDING_2D the name of the texture currently bound to GL_TEXTURE_2D. GL_TEXTURE_ARRAY_BUFFER_BINDING the buffer object name bound to the texture array. GL_TEXTURE_ARRAY_SIZE the number of coordinates per element. GL_TEXTURE_ARRAY_STRIDE the byte offset between elements. GL_TEXTURE_ARRAY_TYPE the coordinate data type. GL_TEXTURE_MATRIX sixteen values, the matrix on top of the texture matrix stack. GL_TEXTURE_MATRIX_FLOAT_AS_INT_BITS texture matrix elements as integer array, according to the IEEE 754 floating-point single format bit layout. GL_TEXTURE_STACK_DEPTH the number of matrices in the texture matrix stack. GL_UNPACK_ALIGNMENT the byte alignment used for reading pixel data from memory. GL_VIEWPORT four values describing the current viewport: x, y, width, height. GL_VERTEX_ARRAY_BUFFER_BINDING the buffer object name bound to the ver- tex array. GL_VERTEX_ARRAY_SIZE the number of coordinates per element array. GL_VERTEX_ARRAY_STRIDE the byte offset between elements. GL_VERTEX_ARRAY_TYPE the coordinate data type. There are also several additional query functions. void glGetBufferParameteriv( GL_ARRAY_BUFFER, GLenum pname, GLint * params) SECTION 10.2 STATE QUERIES 231 is used for querying information about buffer objects. Supported pnamesare: GL_BUFFER_SIZE size of the data storage. GL_BUFFER_USAGE expected usage, either GL_STATIC_DRAW or GL_DYNAMIC_ DRAW. GL_BUFFER_ACCESS access capability, always GL_WRITE_ONLY. void glGetClipPlane{fx}(GLenum pname, T eqn[4]) returns the plane equation of the clip plane pname (e.g., GL_CLIP_PLANE0)ineye coordinates. void glGetLight{fx}v(GLenum light, GLenum pname, T*params) returns the parameters of the light source light such as GL_LIGHT0. The valid pnamesare GL_AMBIENT four-component ambient RGBA light intensity. GL_DIFFUSE four-component diffuse RGBA light intensity. GL_SPECULAR four-component specular RGBA light intensity. GL_EMISSION four-component emissive RGBA light intensity. GL_SPOT_DIRECTION three-component spot light direction. GL_SPOT_EXPONENT spot exponent [0, 128]. GL_CONSTANT_ATTENUATION attenuation factor. GL_LINEAR_ATTENUATION attenuation factor. GL_QUADRATIC_ATTENUATION attenuation factor. void glGetMaterial{fx}v( GL_FRONT_AND_BACK, GLenum pname, T*params) returns material parameter values. Accepted symbols for pname are GL_AMBIENT four-component ambient RGBA reflectance. GL_DIFFUSE four-component diffuse RGBA reflectance. GL_SPECULAR four-component specular RGBA reflectance. GL_EMISSION four-component emissive RGBA reflectance. GL_SHININESS specular exponent of the material. void glGetPointerv(GLenum pname, void ** params) returns client-side pointer information. Accepted values for pname are GL_COLOR_ARRAY_POINTER GL_NORMAL_ARRAY_POINTER GL_TEXTURE_ARRAY_POINTER 232 MISCELLANEOUS OPENGL ES FEATURES CHAPTER 10 GL_VERTEX_ARRAY_POINTER GL_POINT_SIZE_ARRAY_POINTER_OES void glGetTexEnv{ifx}v( GL_TEXTURE_ENV, GLenum pname, T*params) returns information about the texture environment. Accepted values for pname are GL_TEXTURE_ENV_MODE texture environment mode such as GL_MODULATE. GL_TEXTURE_ENV_COLOR four-component RGBA texture environment color. GL_COMBINE_RGB texture combine function for color. GL_COMBINE_ALPHA texture combine function for alpha. GL_SRC012_RGB texture combine source 012 for color. GL_SRC012_ALPHA texture combine source 012 for alpha. GL_OPERAND012_RGB texture combine operand 012 for color. GL_OPERAND012_ALPHA texture combine operand 012 for alpha. GL_RGB_SCALE texture combine color scale. GL_ALPHA_SCALE texture combine alpha scale. void glGetTexParameter{ifx}v( GL_TEXTURE_2D, GLenum pname, T*params) returns infor mation about the current texture. Accepted values for pname are GL_MIN_FILTER texture minification function. GL_MAG_FILTER texture magnification function. GL_TEXTURE_WRAP_S wrap parameter for texture coordinate s. GL_TEXTURE_WRAP_T wrap parameter for texture coordinate t. GL_GENERATE_MIPMAP whether mipmap generation is enabled. GLboolean glIsBuffer(GLuint buffer) returns a boolean value indicating whether the specified name corresponds to a buffer object. GLboolean glIsEnabled(GLenum cap) returns a boolean value indicating whether the specified capability is enabled. The valid capabilities are SECTION 10.3 HINTS 233 GL_ALPHA_TEST, GL_ARRAY_BUFFER_BINDING, GL_BLEND, GL_CLIP_PLANEi, GL_COLOR_ARRAY, GL_COLOR_LOGIC_OP, GL_COLOR_MATERIAL, GL_CULL_FACE, GL_DEPTH_TEST, GL_DITHER, GL_FOG, GL_LIGHTi, GL_LIGHTING, GL_LINE_SMOOTH, GL_MULTISAMPLE, GL_NORMAL_ARRAY, GL_NORMALIZE, GL_POINT_SIZE_ARRAY_OES, GL_POINT_SMOOTH, GL_POINT_SPRITE_OES, GL_POLYGON_OFFSET_FILL, GL_RESCALE_NORMAL, GL_SAMPLE_ALPHA_TO_COVERAGE, GL_SAMPLE_ALPHA_TO_ONE, GL_SAMPLE_COVERAGE, GL_SCISSOR_TEST, GL_STENCIL_TEST, GL_TEXTURE_2D, GL_TEXTURE_COORD_ARRAY, GL_VERTEX_ARRAY. GLboolean glIsTexture(GLuint texture) returns a boolean value indicating whether the specified name corresponds to a texture object. 10.3 HINTS Hints are used to control quality-speed tr ade-offs for certain features that are regarded as implementation-specific details. They are set by calling void glHint(GLenum target, GLenum mode) The mode can be either GL_FASTEST indicating that the highest-performance option should be used, GL_NICEST asking for the highest quality, or GL_DONT_CARE indicat- ing that the user has no preference. The default value for all targets is GL_DONT_CARE. The valid targets are: GL_PERSPECTIVE_CORRECTION_HINT gives a hint whether vertex data such as texture coordinates (and maybe even colors) are interpolated using perspective- correct interpolation, as opposed to faster but lower-quality screen-linear inter- polation. The effect is usually most visible with large textured polygons (see Figure 3.16 and Section 3.4.2). GL_POINT_SMOOTH_HINT and GL_LINE_SMOOTH_HINT control the rendering quality of antialiased points and lines. GL_FOG_HINT relates to the quality of fog calculations. The typical trade-off would be computing fog at each pixel versus only computing it at the vertices and inter- polating the resulting gradients across the primitive. GL_GENERATE_MIPMAP_HINT was introduced in OpenGL ES 1.1. It controls the quality of automatically generated mipmaps. . CHAPTER 10 With the exception of the error state, OpenGL ES 1.0 does not support querying any of the dynamic state. OpenGL ES 1.1, on the other hand, has wide support for dynamic state queries. 10.2.1. requested type, the nearest representable value is returned. The new pnames that are supported in addition to those already in OpenGL ES 1.0 are listed below. GL_ALPHA_TEST_FUNC the alpha test. the smallest and largest sizes of antialiased points. GL_STENCIL_BITS the number of bitplanes in the stencil buffer. GL_SUBPIXEL_BITS an estimate of the number of bits for subpixel resolution