4.9 slparams -- Extracting RenderMan Shader parameters

4.9 slparams -- Extracting RenderMan Shader parameters

This module can be used to extract the parameters of a RenderMan shader from the shader source file.

slparams( slfile, cpp=None, cpperrstream=sys.stderr, includedirs=None, defines=None)

Extracts the shader parameters from a Shading Language source file.

The argument slfile is either the name of the shader source file (*.sl) or it is a file-like object that provides the shader sources.

cpp determines how the shader source is preprocessed. It can be either a string containing the name of an external preprocessor tool (such as cpp) that must take the file name as parameter and dump the preprocessed output to stdout. If the preprocessor does not produce any data a PreprocessorNotFound exception is thrown. The error stream of the preprocessor is written to the object that is specified by cpperrstream which must have a write() method. If cpperrstream is None, the error stream is ignored. cpp can also be a callable object that takes a filename as input and returns the filtered contents as a string. If cpp is None a simple internal preprocessor based on the simplecpp module is used.

includedirs is a list of strings that contain directories where to look for include files. defines is a list of tuples (name, value) that specify the predefined symbols to use.

The function returns a list of 3-tuples, one for each shader found in the file. The tuple contains the type, the name and the parameters of the shader. The parameters are given as a list of 7-tuples describing each parameter. The tuple contains the following information (in the given order):

The output specifier (either "output" or an empty string)
The storage class ("uniform" or "varying")
The parameter type
The array length or None if the parameter is not an array
The name of the parameter
The space in which a point-like type or a color was defined. If the parameter is an array then this is also an array of space names.
The default value (always given as a string)

Example (output slightly reformatted for better readability):

>>> import slparams
>>> slparams.slparams("plastic.sl")
[('surface', 'plastic', 
  [('', 'uniform', 'float', None, 'Ka', None, '1'),
   ('', 'uniform', 'float', None, 'Kd', None, '0.5'),
   ('', 'uniform', 'float', None, 'Ks', None, '0.5'),
   ('', 'uniform', 'float', None, 'roughness', None, '0.1'),
   ('', 'uniform', 'color', None, 'specularcolor', 'rgb', '1')])]

The parser used inside this function was generated using the parser generator Yapps by Amit Patel.

convertdefault( paramtuple)

Converts the default value of a shader parameter into a Python type. The argument paramtuple must be a 7-tuple as returned by slparams(). The function returns a Python object that corresponds to the default value of the parameter. If the default value can't be converted then None is returned. Only the functions that are present in the sl module are evaluated. If a default value calls a user defined function then None is returned. The SL types will be converted into the following Python types:

SL type	Python type
`float`	`float`
`string`	`string`
`color`	`vec3`
`point`	`vec3`
`vector`	`vec3`
`normal`	`vec3`
`matrix`	`mat4`

Arrays will be converted into lists of the corresponding type.

The module defines the following exception classes:

exception SLParamsError

Base class for the exceptions in this module. This class is derived from the Exception class.

exception PreprocessorNotFound

This exception is thrown when calling the preprocessor didn't produce any data.

exception SyntaxError

This exception is thrown when a syntax error is found in any function or shader definition. The exception has the following attributes:

filename: The filename where the error was found
lineno: The line number where the error was found
line: The entire line that contains the error
errpos: The character position where the error token starts

exception NoMoreTokens

This exception is thrown when the parser runs out of tokens.