3Delight 8.5 User's Manual: 9.9 Attaching annotations to shaders

Short Contents

9.9 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(71).
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 9.1**: 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 9.1: 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 (Using `lib3delight' to Interrogate Shaders). Here is the output of the shaderinfo -a command exectued on the example in Listing 9.1:

% 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 ]

[ >> ]