3Delight 12.0 User's Manual: 10.4 Attaching annotations to shaders

Short Contents

10.4 Attaching annotations to shaders

An annotation is some textual information (or a "meta data") indexed with a key (the annotation key). Annotations were primarily designed for better integration with software that need to build user friendly graphical interfaces and let the user modify shader's parameters gracefully. Such software usually need informations about ranges of each parameter in the shader as well as some description about how to present them to the user. A classical example is to present a toggle to the user when some shader parameters represent an on/off state.

Annotations are specified in the shader source with a #pragma instruction formatted as such:

#pragma annotation "<key>" "<text>"

Where `<key>' is the annotation key and `<text>' the annotation itself(74). The preprocessor also supports C99's _Pragma operator:

_Pragma( "annotation \"<key>\" \"<text>\"" )

The advantage of this is that it can be used anywhere inside a macro to emit pragma directives. To perform substitution of macro parameters inside the pragma, a more advanced construct is required because substitution does not happen inside strings:

#define MAKE_STR2( str ) #str
#define MAKE_STR( str ) MAKE_STR2( str )

#define MAKE_PRAGMA( keysuffix, textdata ) \
    _Pragma( MAKE_STR( annotation MAKE_STR( key##keysuffix ) \
        MAKE_STR( annotation text with##textdata  ) ) )

MAKE_PRAGMA( special, a macro parameter. )

When run through the preprocessor, this results in:

#pragma annotation "keyspecial" "annotation text witha macro parameter."

There is no particular syntax for the annotation `key' or `text' fields and 3Delight will not perform any syntax checking on these, it is up to the shader writer to decide the syntax depending on the software which is reading it. Follows an example shader annotated with informations about its parameters, author and version:

**Listing 10.4**: An example annotated shader.
surface annotations( float Ks = 1.0; float has_shadow = 0; ) { /* code goes here */ } #pragma annotation "author" "Aghiles Kheffache" #pragma annotation "version" "1.0" #pragma annotation "Ks comment" "Specular intensity" #pragma annotation "Ks range" "[0..10]" #pragma annotation "has_shadow type" "toggle"

surface annotations( float Ks = 1.0; float has_shadow = 0; )
{
    /* code goes here */
}
#pragma annotation "author" "Aghiles Kheffache"
#pragma annotation "version" "1.0"
#pragma annotation "Ks comment" "Specular intensity"
#pragma annotation "Ks range" "[0..10]"
#pragma annotation "has_shadow type" "toggle"

Listing 10.4: An example annotated shader.

A user interface builder could then draw a toggle for the `has_shadow' parameter since the shader writer specifically said that it was a toggle and not a simple scalar value.

Annotations in a compiled shader are accessible through the shaderinfo utility (Using shaderinfo to Interrogate Shaders) or through 3Delight library calls (The Slo API). Here is the output of the shaderinfo -a command executed on the example in Listing 10.4:

% shaderdl annotations.sl
% shaderinfo -a annotations
surface test
5
"Ks comment" "Specular intensity"
"Ks range" "[0..10]"
"author" "Aghiles Kheffache"
"has_shadow type" "toggle"
"version" "1.0"

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]