Spec 3.0

OpenGL ES is a set of commands that affect the operation of graphics hardware.
We distinguish two types of state.
The first type of state, called GL server state, resides in the GL server. The majority of GL state falls into this category.
The second type of state, called GL client state, resides in the GL client.

Each instance of a GL context implies one complete set of GL server state;
each connection from a client to a server implies a set of both GL client state and GL server state.

OpenGL ES maintains a considerable amount of state information. This state controls how objects are drawn into the framebuffer.

OpenGL ES is concerned only with rendering into a framebuffer (and reading values stored in that framebuffer).

In the GL, data binding occurs on call.
This means that data passed to a command are interpreted when that command is received.
Even if the command requires a pointer to data, those data are interpreted when the call is made,
and any subsequent changes to the data have no effect on the GL (unless the same pointer is used in a subsequent command).

The model for interpretation of GL commands is client-server.
That is, a program (the client) issues commands,
and these commands are interpreted and processed by the GL (the server).
A server may maintain a number of GL contexts,
each of which is an encapsulation of current GL state.
A client may choose to connect to any one of these contexts.

number: converted by normalizing to [0, 1] (for unsigned types) or [1, 1] (for signed types)

The GL interacts with two classes of framebuffers:

• window system-provided
• application-created.

There is at most one window system-provided framebuffer at any time, referred to as the default framebuffer.
Application-created framebuffers, referred to as framebuffer objects, may be created as desired.
It is possible to use a GL context without a default framebuffer,
in which case a framebuffer object must be used to perform all rendering.
This is useful for applications needing to perform offscreen rendering.

The GL uses many types of data supplied by the client.
Some of this data must be stored in server memory,
and it is usually desirable to store other types of frequently used client data,
such as vertex array and pixel data, in server memory even if the option to store it in client memory exists.
Buffer objects provide a mechanism to allocate, initialize, and render from such memory.
The name space for buffer objects is the unsigned integers, with zero reserved for the GL.

If the buffer object named buffer has not been previously bound, or has been deleted since the last binding,
the GL creates a new state vector, initialized with a zero-sized memory buffer
and comprising all the state and with the same initial values listed below.

Name                   Type     Initial Value    Legal Values
BUFFER_SIZE            int64    0                any non-negative integer
BUFFER_USAGE           enum     STATIC_DRAW      STREAM_DRAW, STREAM_READ, STREAM_COPY,STATIC_DRAW, STATIC_READ, STATIC_COPY, DYNAMIC_DRAW, DYNAMIC_READ, DYNAMIC_COPY
BUFFER_ACCESS_FLAGS    int      0
BUFFER_MAPPED          boolean  FALSE            TRUE, FALSE
BUFFER_MAP_POINTER     void*    NULL             address
BUFFER_MAP_OFFSET      int64    0                any non-negative integer
BUFFER_MAP_LENGTH      int64    0                any non-negative integer

The shader objects that are to be used by the programmable stages of the GL are collected together to form a program object.
The programs that are executed by these programmable stages are called executables.
All information necessary for defining an executable is encapsulated in a program object.

When LinkProgram is called, the GL builds lists of active variables and interface blocks for the program.
Each active variable or interface block is assigned an associated name string,
which may be returned as a null-terminated string by commands such as GetActiveUniform and GetActiveUniformBlockName.

Vertex attributes are the per vertex values.
Uniforms are per program variables that are constant during program execution.
Samplers are a special form of uniform used for texturing.

Vertex Array Object

The buffer objects that are to be used by the vertex stage of the GL are collected together to form a vertex array object.
All state related to the definition of data used by the vertex processor is encapsulated in a vertex array object.

vertex shaders can access the read-only built-in variables gl_VertexID and gl_InstanceID.

gl_VertexID holds the integer index i implicitly passed by DrawArrays.
The value of gl_VertexID is defined if and only if all enabled vertex arrays have non-zero buffer object bindings.

gl_InstanceID holds the integer instance number of the current primitive in an instanced draw call.

The built-in output gl_Position is intended to hold the homogeneous vertex position. Writing gl_Position is optional.

The built in output gl_PointSize, if written, holds the size of the point to be rasterized, measured in pixels.

Clip coordinates for a vertex result from vertex shader execution, which yields a vertex coordinate gl_Position.

Perspective division on clip coordinates yields normalized device coordinates,
followed by a viewport transformation to convert these coordinates into window coordinates.

After a primitive is formed, it is clipped to a clip volume.
This may alter the primitive by altering vertex coordinates and vertex shader outputs.

Flatshading a vertex shader output means to assign all vertices of the primitive the same value for that output.
The output values assigned are those of the provoking vertex of the primitive.

A grid square along with its z (depth) and shader output parameters is called a fragment.

A fragment is located by its lower left corner, which lies on integer grid coordinates.
Rasterization operations also refer to a fragment’s center, which is offset by (1/2, 1/2)
from its lower left corner (and so lies on half-integer coordinates).

Grid squares need not actually be square in the GL.
Rasterization rules are not affected by the actual aspect ratio of the grid squares.

The rule for determining which fragments are produced by polygon rasterization is called point sampling.
The two-dimensional projection obtained by taking the x and y window coordinates of the polygon’s vertices is formed.

When cube map texturing is enabled, the (s t r) texture coordinates are treated as a direction vector (rx ry rz) emanating from the center of a cube.

Major Axis Direction   Target                       sc   tc   ma
+rx                    TEXTURE_CUBE_MAP_POSITIVE_X  −rz  −ry  rx
−rx                    TEXTURE_CUBE_MAP_NEGATIVE_X  rz   −ry  rx
+ry                    TEXTURE_CUBE_MAP_POSITIVE_Y  rx   rz   ry
−ry                    TEXTURE_CUBE_MAP_NEGATIVE_Y  rx   −rz  ry
+rz                    TEXTURE_CUBE_MAP_POSITIVE_Z  rx   −ry  rz
−rz                    TEXTURE_CUBE_MAP_NEGATIVE_Z  −rx  −ry  rz

s = 1/2( sc/|ma| + 1)
t = 1/2( tc/|ma| + 1)

The built-in variable gl_FragCoord holds the fragment coordinate (xw yw zw 1/wc)
for the fragment where (xw yw zw) is the fragment’s window-space position and wc is the w component of the fragment’s clip-space position.

The zw component of gl_FragCoord undergoes an implied conversion to floating-point.
This conversion must leave the values 0 and 1 invariant.
Note that zw already has a polygon offset added in, if enabled.

The built-in variable gl_FrontFacing is set to TRUE if the fragment is generated from a front-facing primitive, and FALSE otherwise.

These outputs are split into two categories,
user-defined outputs and the built-in outputs gl_FragColor, gl_FragData[n] and gl_FragDepth.

Writing to gl_FragColor specifies the fragment color (color number zero) that will be used by subsequent stages of the pipeline.

Writing to gl_FragData[n] specifies the value of fragment color number n.
Any colors, or color components, associated with a fragment that are not written by the fragment shader are undefined.

Writing to gl_FragDepth specifies the depth value for the fragment being processed.
If the active fragment shader does not statically assign a value to gl_FragDepth,
then the depth value generated during rasterization is used by subsequent stages of the pipeline.
Otherwise, the value assigned to gl_FragDepth is used,
and is undefined for any fragments where statements assigning a value to gl_FragDepth are not executed.
Thus, if a shader statically assigns a value to gl_FragDepth, then it is responsible for always writing it.

The framebuffer consists of a set of pixels arranged as a two-dimensional array.

Ownership Test

The first test is to determine if the pixel at location (xw, yw) in the framebuffer
is currently owned by the GL (more precisely, by this GL context).

If the draw framebuffer is a framebuffer object, the pixel ownership test always passes,
since the pixels of framebuffer objects are owned by the GL, not the window system.

If the draw framebuffer is the default framebuffer, the window system controls pixel ownership.

Scissor Test

The scissor test determines if (xw, yw) lies within the scissor rectangle defined by four values.

Stencil Test

The stencil test conditionally discards a fragment based on the outcome of
a comparison between the value in the stencil buffer at location (xw, yw) and a reference value.

Depth Buffer Test

The depth buffer test discards the incoming fragment if a depth comparison fails.
The comparison is enabled or disabled by calling Enable and Disable with target DEPTH_TEST.