7.1 OpenGL Backends

OpenGL defines a standard API for 3D rendering. In recent years much of the effort related to OpenGL has been towards making the rendering pipeline more programmable. Sh aims to target these recent advances in programmability with a set of backends.

There are multiple OpenGL-related backends which share various subsystems. At the time of writing the most complete OpenGL-like backend is the arb backend, which compiles to ARB_fragment_program and ARB_vertex_program assembly code.

Backends being constructed at the time of writing include the nv backend targeting the NV_fragment_program and NV_vertex_program assembly interfaces, as well as a glsl backend aiming to produce high-level code in the OpenGL 2.0 Shading Language. The glsl backend will probably become the most commonly used OpenGL backend in Sh, but at the time of writing the driver support for GLSL is still lacking.

7.1.1 Input and Output Binding

At both the vertex and fragment stage OpenGL provides several named inputs and outputs, corresponding to their purpose in the traditional fixed-function pipeline. The arb backend allows inputs and outputs in Sh programs to be mapped to these special tuples in a fairly intuitive manner. The alternative is to ignore any sort of special semantic meaning and only allocate attributes by their order, ignoring the type completely. / The arb backend also allows this mode of mapping Sh variables to OpenGL attributes.

The default method of assigning variables to attributes is the semantic approach. Here the mapping happens in two stages. In the first stage, any variables with types in the third column of Table 7.1 are assigned to the matching slots in order. In the second pass, any remaining variables are assigned to available slots marked as generic in the order they appear in the table.

The semantic method of binding is useful in particular when interacting with older applications, as it allows fairly straightforward interactions. However, especially when writing a new application, it may be simpler to ignore the semantic types and simply pass all data in order. / To this end the arb backend provides a generic attribute binding mode. In order to use this mode, you must set the opengl:matching metadata on your programs to generic by calling the meta() member function. Other values are reserved, you can enforce the semantic matching mode by setting the value to semantic.

Note that there is one semantic type which even under the generic mode has special meaning, and that is SH_POSITION. The first ShPosition will always be mapped to vertex.attrib[0], as that is where GL places the vertex and fragment positions by convention.

Table 7.2 gives an example of what a number of Sh types would be mapped to for a vertex program under the two mappings.

7.1.2 Texture Bindings

By default, Sh and the OpenGL backends will manage textures completely automatically, taking care of allocating texture units, uploading texture data (as needed), etc.

Sometimes it can be useful, however, to set up textures outside of Sh. This may be because you are adapting a legacy application, or because you want to use an extension or texture format which Sh does not (yet) support.

For this reason, the arb backend supports a few metadata settings on textures and programs.

/ Firstly, the opengl:reservetex metadata can be set on ShPrograms with a string representation of an integer texture unit to indicate that Sh should not use that texture unit to store any of its textures. This can be useful if you have some textures set up outside of Sh (e.g. using the fixed-function pipeline) and don’t want Sh to clobber them.

/ Another option is to set the opengl:preset property on a texture itself to a particular texture unit. This will cause texture data allocated to that texture to be ignored by the arb backend, and instead have it assume that the texture is already set up appropriately in the given texture unit.

7.1.3 Parameter Bindings

OpenGL defines a fairly large number of parameters corresponding to state mostly originating from the older fixed-function model. / It is possible to access this state in Sh shaders by setting the appropriate meta information on uniform parameters and accessing them as usual. This allows you to both change this state from Sh and access it from shaders.

/ By setting the opengl:state metadata to the name of an OpenGL state variable (following the same conventions as in the ARB_vertex_program specification) the corresponding OpenGL state will be set to the uniform parameter’s value when a program using it is bound or shUpdate() is called, and the value will be used directly when the parameter appears in a program.

/ In addition to setting the opengl:state information on a parameter, it is possible to define opengl:readonly as true. If this metadata is set, the arb backend will never write that variable’s data to the OpenGL state. This is particularily useful if you are still using traditional OpenGL calls to set up the OpenGL state. You should set the opengl:readonly property before setting the opengl:state to be sure that no OpenGL data will be overwritten accidentally.

Note: This manual is available as a bound book from AK Peters, including better formatting, in-depth examples, and about 200 pages not available on-line.