5.3 Introspection

Sh program objects support introspection, allowing host applications to inspect them in various ways. This is particularily useful for host programs that provide some user interface layer on top of arbitrary Sh programs, such as the shrike application, which provides widgets to control uniform parameters and textures accessed by Sh programs. These introspection methods are also used internally by some of the built in Sh functions, such as the “shader algebra” operators discussed in Section 5.4.

The compilation target assigned to the program at definition time is available by calling the target member function on ShProgram objects, which returns a string such as "gpu:vertex". This string may be empty, which indicates that the program is generic. The generic compilation target is used for glue programs; programs with a generic target need a target assigned before they can be used.

Perhaps the most important introspection facilities for programs are accessors for scanning dependencies: the lists of uniforms, inputs, outputs, textures, streams, and temporary variables used by every program object. All of these lists are accessible using STL (standard template library) iterators. These iterators can be dereferenced, incremented and compared to one another. The available iterator accessors are given in Table 5.1.

typedef std::list<ShVariableNodePtr> VarList;

Variable node container

typedef std::list<ShTextureNodePtr> TextureList;

Texture node container

typedef std::list<ShChannelNodePtr> ChannelList;

Channel node container

VarList::iterator begin_inputs()

SH_INPUT variable nodes

VarList::iterator end_inputs()

SH_INPUT variable nodes

VarList::iterator begin_outputs()

SH_OUTPUT variable nodes

VarList::iterator end_outputs()

SH_OUTPUT variable nodes

VarList::iterator begin_parameters()

Uniform parameter nodes

VarList::iterator end_parameters()

Uniform parameter nodes

VarList::iterator begin_temps()

Local (internal) variable nodes

VarList::iterator end_temps()

Local (internal) variable nodes

TextureList::iterator begin_textures()

Texture nodes accessed in program

TextureList::iterator end_textures()

Texture nodes accessed in program

ChannelList::iterator begin_channels()

Stream channel nodes accessed in program

ChannelList::iterator end_channels()

Stream channel nodes accessed in program

Table 5.1:

Accessor iterators for ShProgram objects

Several functions are also available to make setting up program objects more convenient. These descriptor functions return human readable strings describing some aspect of an ShProgram. For instance, rather than trying to figure out the results of the rules for binding a vertex shader to the vertex attributes in OpenGL, you can just ask the shader to describe the binding it requires, and it will generate a report that states which OpenGL vertex attributes will get bound to which vertex shader inputs.

describe_bindings()

Human-readable binding description under current backend.

describe_bindings(std::string target)

Human-readable binding description for target.

describe_interface()

Human-readable description of inputs and outputs.

Table 5.2:

Describer member functions for ShProgram objects. All these functions return std::strings

Programs, like most other Sh objects, also have all the metadata provided by the ShMeta class, as explained in Section 2.7. This is also true for the variables made available through the iterators listed in Table 5.1. The describers access this metadata to make a report. A describer function is really querying the metadata of the objects the program depends on. Note that you have to actually provide this data, such as names and titles, for the describers to be useful.

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.