3D Graphics with OpenGL ES and M3G- P25 pdf

The value that the buffer is filled with during the clear-ing is set with the followclear-ing functions: void glClearColor{fx}T red, T green, T blue, T alpha void glClearDepth{fx}T depth

is used for clearing the various buffers all at the same time The input parameter mask

is a bitwise OR of symbolic 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 followclear-ing 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 with2s −1, where s 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

parame-ter pixels points to a memory block into which the requested portion of the frame

buffer is copied

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 is1 no alignment is done Other possible values are2 and 8

The following code sets word-aligned packing (a word is 4 bytes), and reads in the lower-left240 × 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

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).

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)

If a glGet command is issued that returns value types different from the type of the

value being obtained, a type conversion is performed With glGetBooleanv, a zero

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 buffer object 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_DENSITY 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 whether clockwise or counterclockwise winding is treated as

front-facing

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 matrices 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 type 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

GL_SAMPLE_COVERAGE_VALUE the sample coverage value set by

glSample-Coverage

GL_SCISSOR_BOX four values describing the current scissor box: x, y, width, height.

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 current 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,

params)

is used for querying information about buffer objects Supported pnames are:

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) in eye

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 pnames are

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

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 information 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

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 trade-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_HINTgives 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_HINTand GL_LINE_SMOOTH_HINT control the rendering quality of antialiased points and lines

GL_FOG_HINTrelates 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_HINTwas introduced in OpenGL ES 1.1 It controls the quality of automatically generated mipmaps