Slo Library

Slo Library

Introduction

This document describes the software available from Pixar that can be used by application programs to interrogate the parameters of PRMan shaders.

PRMan allows small procedures to be written in the RenderMan Shading Language to allow user extensible shading features to be added to the rendering algorithm. These procedures are known as shaders, and provide one of the most powerful concepts and features of the RenderMan Interface.

Many modeling applications that support the RenderMan Interface wish to present information about shaders to their users, including which shaders are available, the parameters for each shader, and the default values for each shader parameter. Since source code to shaders may not be available for shaders that a user may wish to apply to his model, an alternate means for interrogating shaders is provided.

The Slo API is a library of procedures (sloargs) that can be used to interrogate the parameters of a shader. The reference documentation for this library is provided below. Use of the sloargs library will ensure that shaders are interrogated in a simple and consistent fashion by all applications.


Synopsis

Slo_SetPath(path) char *path;
int Slo_SetShader(name) char *name;
char *Slo_GetName()
SLO_TYPE Slo_GetType()
int Slo_GetNArgs()
SLO_VISSYMDEF *Slo_GetArgById(id) int id;
SLO_VISSYMDEF *Slo_GetArgByName(name) char *name;
SLO_VISSYMDEF *Slo_GetArrayArgElement(array, index) SLO_VISSYMDEF *array; int index;
Slo_EndShader()
char *Slo_TypetoStr(type) SLO_TYPE type;
char *Slo_StortoStr(storage) SLO_STORAGE storage;
char *Slo_DetailtoStr(detail) SLO_DETAIL detail;
const char** Slo_GetPlugins();
const char* Slo_GetMetaData(const char* name);
const char** Slo_GetAllMetaData();

Description

This set of API calls is used to get shader information from a .slo file. Slo_SetPath sets the colon-delimited search path used to locate compiled shaders. The routine returns 0 on success, -1 with errno set if unable to do so.

Slo_SetShader attempts to locate and read the specified shader (in compiled format) using the same search path used by the renderer. It returns 0 if successful making the specified shader the current shader. It returns -1 on error with the global variable errno set to indicate the error condition.

Slo_GetName returns a pointer to a null terminated ascii string containing the name of the current shader. (This storage for the string name is freed when a new shader is made current or Slo_EndShader is executed.)

Slo_GetType returns the type of the current shader, where type is one of the following:

SLO_TYPE_SURFACE
SLO_TYPE_LIGHT
SLO_TYPE_VOLUME
SLO_TYPE_DISPLACEMENT
SLO_TYPE_TRANSFORMATION
SLO_TYPE_IMAGER
surface shader
light shader
volume shader
displacement shader
transformation shader
imager shader

Slo_GetNArgs returns the number of arguments accepted by the current shader.

Slo_GetArgByName, and Slo_GetArgById each return a pointer to an object with the following structure containing the visible fields of a shader symbol definition:

typedef struct slovissymdef {
        char          *svd_name;      /* name of symbol */
        SLO_TYPE      svd_type;       /* symbol type */
        SLO_STORAGE   svd_storage;    /* symbol storage class */
        SLO_DETAIL    svd_detail;     /* symbol variance */
        char          *svd_spacename; /* name of space in which */
                                      /* to interpret symbol's value */
        int           svd_arraylen;   /* #elements in array symbol */
        union {
               POINT  *pointval;      /* pointers to default value */
               SCALAR *scalarval;
               char   *stringval;
        } svd_default;
} SLO_VISSYMDEF;

The members of this structure are:

  • svd_name

    The ascii symbol name

  • svd_type

    The type of the symbol where type is one of the following:

SLO_TYPE_POINT
SLO_TYPE_VECTOR
SLO_TYPE_NORMAL
SLO_TYPE_COLOR
SLO_TYPE_SCALAR
SLO_TYPE_STRING
SLO_TYPE_MATRIX
three floating point values
three floating point values
three floating point values
three floating point values
one floating point value
null-terminated ascii string
sixteen floating point values
  • svd_storage

    The storage class of the symbol; currently either:

SLO_STOR_PARAMETER
SLO_STOR_OUTPUTPARAMETER
symbol is a standard read-only parameter
symbol is an output parameter
  • svd_detail

    The breadth of the symbol; currently either:

SLO_DETAIL_VARYING
SLO_DETAIL_UNIFORM
symbol's value varies over a geometric primitive
symbol's value is constant over a geometric primitive
  • svd_spacename

    An ASCII string specifying the space the variable is to be evaluated in. (This only has meaning for geometric and color variables and is the NULL string "" for variables of type SLO_TYPE_SCALAR and SLO_TYPE_STRING).

  • svd_arraylen

    For a variable which is a Shading Language array, this member contains an integer which specifies how many elements are in the array. For such a variable, the svd_default is never valid, and instead Slo_GetArrayArgElement is used to access individual element default values. This member is 0 for any variable that is not an array.

  • svd_default

    A pointer (typed) to its default value if the parameter has one.

The storage for this structure is static and must be copied elsewhere if its value is to be retained across calls. Slo_GetArgByName returns a pointer to a symbol definition based on the name parameter. Slo_GetArgById uses the argument id where id is an integer between 1 and the value returned by Slo_GetNArgs inclusive.

Slo_GetArrayArgElement returns a SLOVISSYMDEF structure for a single element of an array. It takes as arguments the SLOVISSYMDEF pointer of the array variable, and an index into the array, which is an integer between 0 and array->svd_arraylen - 1

Slo_EndShader releases the storage used internally for the shader definition.

Slo_TypetoStr, Slo_StortoStr, and Slo_DetailtoStr return ASCII representations of SLO_TYPE, SLO_STORAGE, and SLO_DETAIL values, respectively.

Plugin dependencies

Slo_GetPlugins can be used to determine which plugins a shader depends upon. It returns an array of plugin filenames, which is terminated by a NULL pointer.

Important: the array must be freed by the caller (but not the strings).

Meta Data

Meta data is specified in comments in shader source code like the following:

/* This meta data describes a shader parameter:
   <meta id="Ks_label">Specular Response</meta>
   <meta id="Ks_min">0</meta>
   <meta id="Ks_precision">0.001</meta>
 */

The shader must be compiled with the -C command-line argument, which instructs the preprocessor to preserve comments, in order for the meta data to be recorded in the SLO file.

Slo_GetMetaData returns a pointer to the meta data with the specified name, or NULL if not found. Slo_GetAllMetaData returns an array containing all the meta data in the shader. The array contains name/value pairs and is terminated by a pair of NULL pointers. For example:

{ "Ks_label", "Specular Response",
  "Ks_min", "0",
  "Ks_precision", "0.001",
  NULL, NULL }

Important: the array must be freed by the caller (but not the strings).

Files

include/slo.h - header file definition for sloargs

lib/shaders - standard shader definitions

lib/libprman.so - sloargs entry points defined here

Diagnostics

Null pointer (0) returned by Slo_GetArgByName() and Slo_GetArgById() on error.