Message Passing and Information Functions

floatatmosphere( string paramname; outputtypevariable ) floatdisplacement( string paramname; outputtypevariable ) floatlightsource( string paramname; outputtypevariable ) floatsurface( string paramname; outputtypevariable )

Name Type Description

”blur” varying float Specifies an additional area to be added to the texture area filtered in both thesandtdirections, expressed in units of texture coordinates. A value of 1.0 would request that the entire texture file be blurred into the result. A value of 0.001 would request that one extra texture pixel be added in the case of a one-thousand by one-thousand texture file. ”sblur” varying float Specifies”blur”individually in thesdirection.

”tblur” varying float Specifies”blur”individually in thetdirection.

”width” uniform float This value multiplies the width of the area being filtered over in both thesandtdirections. A value of 0 effectively turns off texture antialiasing. The default value is 1.0. ”swidth” uniform float Specifies”width”individually in thesdirection. ”twidth” uniform float Specifies”width”individually in thetdirection. ”samples” uniform float The effective sampling rate when filtering.

”bias” varying float Specifies an additional bias to add to shadow depth lookups in order to prevent incorrect self-shadowing of objects.

”filter” uniform string Specifies the name of the filter to use for performing the percentage-closer filtering over an area of the shadow map. The default is ”box”. Individual implementations may allow additional filters.

Table 15.2: Shadow Map Access Parameters

Name Type Description

”resolution” uniform float[2] The highest resolution of the texture map. ”type” uniform string Returns the type of the texture map file: ”tex-

ture”,”shadow”, or”environment”. ”channels” uniform float The number of channels in the map.

”viewingmatrix” uniform matrix Returns a matrix that transforms points from ”current” space to the ”camera” space from which the texture was created. (*).

”projectionmatrix” uniform matrix Returns a matrix that transforms points from ”current” space to a 2D coordinate system wherexandyrange from -1 to 1. (*)

(*)”viewingmatrix”and”projectionmatrix”are only available for shadow maps or other tex- tures that were created by rendering an image, and assume a common world-space of all cameras.

These functions access the value of the parameter namedparamnameof one of the shaders attached to the geometric primitive that is currently being shaded. If the appropriate shader exists, and a parameter namedparamnameexists in that shader, and the parameter is the same type asvariable, then the value of that parameter is stored invariableand the function returns 1; otherwise,variable is unchanged and the function returns 0.

Note that if the data corresponding toname isuniform, but the variablevariableis varying, the appropriate uniform-to-varying conversion will take place, however, the reverse case is considered failure.

Thelightsourcefunction is only available insideilluminanceblocks and refers to the light being examined by the current iteration.

floatincident( string paramname; outputtypevariable ) floatopposite( string paramname; outputtypevariable )

These functions access the value of the volume shader parameterparamnamethat is stored in the volume shaders attached to geometric primitive surface. incident accesses values from the volume shader that describes the volume which contains the incident ray I. oppositeaccesses values from the volume shader that describes the volume on the other side of the surface. If the named variable exists and is of the correct type, thevalueis stored in value and the function returns 1; otherwise,value

is unchanged and the function returns 0.

Note that if the data corresponding toname isuniform, but the variablevariableis varying, the appropriate uniform-to-varying conversion will take place, however, the reverse case is considered failure.

floatattribute( string name; outputtypevariable )

Returns data that is part of the primitive’s attribute state, either from individual Ren- derMan Interface calls that set attributes or from theRiAttributecall. Thenamespec- ifies the piece of RenderMan Interface attribute state that will be returned invariable. If the datanameis known to the renderer and its type and storage class match that of variable, the named data will be written intovariableand attribute()will return a value of 1.0. If the data is unknown or the types do not match, variable will be unchanged andattribute()will return 0.0.

Note that if the data corresponding toname isuniform, but the variablevariableis varying, the appropriate uniform-to-varying conversion will take place, however, the reverse case is considered failure.

The standard data names supported byattributeare listed in Table 15.4. A particular implementation may support additional attribute queries.

floatoption( string name; outputtypevariable )

Returns data that is part of the renderer’s global option state, either from individual RenderMan Interface calls that set options or from theRiOptioncall. Thenamespec- ifies the piece of RenderMan Interface option state that will be returned invariable. If the datanameis known to the renderer and its type and storage class match that of

Name Type

”ShadingRate” uniform float

”Sides” uniform float

”Matte” uniform float

”GeometricApproximation:motionfactor” uniform float

”displacementbound:sphere”(*) uniform float

”displacementbound:coordinatesystem”(*) uniform string

”identifier:name” uniform string

(*) Note that ”displacementbound:sphere” does not return the value exactly as specified in the RIB file, but rather returns its length in the coordinate system returned by ”displacementbound:coordinatesystem”(which currently always returns”camera”).

Table 15.4: Data names known to theattributefunction.

variable, the named data will be written intovariableandoption()will return a value of 1.0. If the data is unknown or the types do not match,variablewill be unchanged and option()will return 0.0. Note that option data is alwaysuniform. Ifvariableis varying, the appropriate uniform-to-varying conversion will take place.

The standard data names supported byoptionare listed in Table 15.5. A particular implementation may support additional option queries.

Name Type Description

”Format” uniform float[3] xresolution,yresolution, pixel aspect ratio. ”DeviceResolution” uniform float[3] The resolution in x and y and the pixel as-

pect ratio. These are usually the three numbers passed toRiFormat, but may be different when

RiFrameAspectRatioorRiScreenWindoware non-square.

”FrameAspectRatio” uniform float Frame aspect ratio.

”CropWindow” uniform float[4] Boundaries of the crop window. ”DepthOfField” uniform float[3] Fstop, focallength, focaldistance. ”Shutter” uniform float[2] Shutter open and close time. ”Clipping” uniform float[2] Near and far clip depths.

Table 15.5: Data names known to theoptionfunction.

floatrendererinfo( string name; outputtypevariable )

Returns data that about the renderer itself. Thenamespecifies the piece of informa- tion that will be returned in variable. The the dataname is known to the renderer and its type and storage class match that ofvariable, the named data will be writ- ten intovariableandrendererinfo()will return a value of 1.0. If the data is unknown or the types do not match,variablewill be unchanged andrendererinfo()will return 0.0. Note that renderer data is alwaysuniform. Ifvariableisvarying, the appropriate uniform-to-varying conversion will take place.

The standard data names supported byrendererinfoare listed in Table 15.6. A partic- ular implementation may support additionalrendererinfoqueries.

Name Type Description

”renderer” uniform string The brand name of the renderer.

”version” uniform float[4] Major, minor, release, and patch numbers. ”versionstring” uniform string The release numbers expressed as a string.

Table 15.6: Data names known to therendererinfofunction.

stringshadername( )

stringshadername( string shadertype )

If no parameter is passed, returns the name of the shader that is currently running. If theshadertypeis supplied, this function returns the name of the shader of the speci- fied type that is bound to the geometric primitive which is being shaded. Acceptable values ofshadertypeare”surface”,”displacement”,”atmosphere”,”lightsource”,”inte- rior”,”exterior”. If the surface being shaded does not have a shader bound to it which matches the type, this function will return the empty string (””).