Sloargs Library

Synopsis

Description

Plugin Dependencies

Meta Data

Files

Diagnostics

Slo_SetPath, Slo_SetShader, Slo_EndShader, 
Slo_GetName, Slo_GetType, Slo_GetNArgs, 
Slo_GetArgById, Slo_GetArgByName, 
Slo_GetArrayArgElement, Slo_TypetoStr, 
Slo_StortoStr, Slo_DetailtoStr,  
Slo_GetMetaData, Slo_GetAllMetaData  

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

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		surface shader
    SLO_TYPE_LIGHT		light shader
    SLO_TYPE_VOLUME		volume shader
    SLO_TYPE_DISPLACEMENT	displacement shader
    SLO_TYPE_TRANSFORMATION	transformation shader
    SLO_TYPE_IMAGER		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		three floating point values
    SLO_TYPE_VECTOR		three floating point values
    SLO_TYPE_NORMAL		three floating point values
    SLO_TYPE_COLOR		three floating point values
    SLO_TYPE_SCALAR		one floating point value
    SLO_TYPE_STRING		null-terminated ascii string
    SLO_TYPE_MATRIX		sixteen floating point values

svd_storage

The storage class of the symbol; currently either:

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

svd_detail

The breadth of the symbol; currently either:

    SLO_DETAIL_VARYING	symbol's value varies over a geometric primitive
    SLO_DETAIL_UNIFORM	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 which 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>
     */

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 } 

FILES

include/slo.h		- header file definition for sloargs
lib/shaders		- standard shader definitions.
lib/libprmansdk.a	- sloargs entry points defined here

DIAGNOSTICS

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

BUGS

All information is contained in a static area so it must be copied if it is to be saved.