Appendix G

Appendix G - RenderMan Interface Quick Reference

Interface Routines	Shading Language Routines
`Graphics State`	`Math Functions`
`Geometric Primitives`	`Geometric Functions`
`Motion`	`Color Functions`
`Texture Map Utilities`	`Matrix and Array Functions`
`External Resources and Archiving`	`String Functions`
	`Shading and Lighting Functions`
	`Language Control Structures`
	`Texture Mapping Functions`
	`Message Passing Functions`
	`Renderer State Functions`

Graphics State

Function	Description
`RiAreaLightSource( name, parameterlist )`	`creates an area light and makes it the current area light source. Each subsequent geometric primitive is added to the list of surfaces that define the area light.`
`RiAtmosphere( name, parameterlist )`	`sets the current atmosphere shader.`
`RiAttribute( name, parameterlist );`	`sets the parameters of the attribute name, using the values specified in the token-value list parameterlist.`
`RiAttributeBegin() RiAttributeEnd()`	`pushes and pops the current set of attributes.`
`RiBegin( name ) RiEnd()`	`initializes and terminates a rendering session.`
`RiBound( bound )`	`sets the current bound to bound.`
`RiClipping( near, far )`	`sets the position of the near and far clipping planes along the direction of view.`
`RiClippingPlane(n0, n1, n2, p0, p1, p2)`	`Clip all geometry on the positive side of the plane described by a point and normal.`
`RiColor( color )`	`sets the current color to color.`
`RiColorSamples( n, nRGB, RGBn )`	`controls the number of color components or samples to be used in specifying colors.`
`RiConcatTransform( transform )`	`concatenates the transformation transform onto the current transformation.`
`RiCoordinateSystem( space ) RiScopedCoordinateSystem( space )`	`marks the coordinate system defined by the current transformation with the name space and saves it.`
`RiCoordSysTransform( space )`	`established the named coordinate space as the current geometry transformation.`
`RiCropWindow( xmin, xmax, ymin, ymax )`	`renders only a subrectangle of the image.`
`RiDepthOfField( fstop, focallength, focaldistance )`	`focaldistance sets the distance along the direction of view at which objects will be in focus.`
`RiDetail( bound )`	`sets the current detail to the area of the bounding box bound in the raster coordinate system`
`RiDetailRange( minvisible, lowertransition, uppertransition, maxvisible )`	`sets the current detail range.`
`RiDisplacement( name, parameterlist )`	`sets the current displacement shader to the named shader.`
`RiDisplay( name, type, mode, parameterlist )`	`chooses a display by name and sets the type of output being generated.`
`RiDisplayChannel( channel, parameterlist )`	`defines a new display channel for use with RiDisplay.`
`RiExposure( gain, gamma )`	`controls the sensitivity and non-linearity of the exposure process.`
`RiExterior( name, parameterlist )`	`sets the current exterior volume shader.`
`RiFormat( xresolution, yresolution, pixelaspectratio )`	`sets the horizontal (xresolution) and vertical (yresolution) resolution (in pixels) of the image to be rendered.`
`RiFrameAspectRatio( frameaspectratio )`	`frameaspectratio is the ratio of the width to the height of the desired image.`
`RiFrameBegin( frame ) RiFrameEnd()`	`marks the beginning and end of a single frame of an animated sequence.`
`RiGeometricApproximation( type, value )`	`The predefined geometric approximation is "flatness".`
`RiHider( type, parameterlist )`	`The standard types are "hidden", "paint", and "null".`
`RiHierarchicalSubdivisionMesh( scheme, nfaces, nverrtices, vertices, ntags, tags, nargs, intargs, floatargs, stringargs, ...)`	`requests a hierarchical subdivision surface mesh.`
`RiIdentity()`	`sets the current transformation to the identity.`
`RiIlluminate( light, onoff )`	`If onoff is RI_TRUE and the light source referred to by the RtLightHandle is not currently in the current light source list, add it to the list.`
`RiImager( name, parameterlist )`	`selects an imager function programmed in the Shading Language.`
`RiInterior( name, parameterlist )`	`sets the current interior volume shader.`
`RiLightSource( name, parameterlist )`	`creates a non-area light, turns it on, and adds it to the current light source list.`
`RiMatte( onoff )`	`indicates whether subsequent primitives are matte objects.`
`RiOpacity( color )`	`sets the current opacity to color.`
`RiOption( name, parameterlist )`	`sets additional implementation-specific options.`
`RiOrientation( orientation )`	`sets the current orientation to be either left-handed or right-handed.`
`RiPerspective( fov )`	`concatenates a perspective transformation onto the current transformation.`
`RiPixelFilter( filterfunc, xwidth, ywidth )`	`performs antialiasing by filtering the geometry (or supersampling) and then sampling at pixel locations.`
`RiPixelSamples( xsamples, ysamples )`	`sets the effective ..sampling rate in the horizontal and vertical directions`
`RiPixelVariance( variation )`	`sets the amount computed image values are allowed to deviate from the true image values.`
`RiProjection( name, parameterlist )`	`sets the type of projection and marks the current coordinate system before projection as the camera coordinate system`
`RiQuantize( type, one, min, max, ditheramplitude )`	`sets the quantization parameters for colors or depth.`
`RiRelativeDetail( relativedetail )`	`The relative level of detail scales the results of all level of detail calculations.`
`RiReverseOrientation()`	`causes the current orientation to be toggled.`
`RiRotate( angle, dx, dy, dz`	`concatenates a rotation of angle degrees about the given axis onto the current transformation.`
`RiScale( sx, sy, sz )`	`concatenates a scaling onto the current transformation.`
`RiScreenWindow( left, right, bottom, top )`	`defines a rectangle in the image plane that gets mapped to the raster coordinate system and that corresponds to the display area selected.`
`RiShadingInterpolation( type )`	`controls how values are interpolated between shading samples (usually across a polygon).`
`RiShadingRate( size )`	`sets the current shading rate to size.`
`RiShutter( min, max )`	`sets the times at which the shutter opens and closes.`
`RiSides( sides )`	`If sides is 2, subsequent surfaces are considered two-sided and both the inside and the outside of the surface will be visible.`
`RiSkew( angle, dx1, dy1, dz1, dx2, dy2, dz2 )`	`oncatenates a skew onto the current transformation.`
`RiSurface( name, parameterlist )`	`sets the current surface shader. name is the name of a surface shader.`
`RiTextureCoordinates( s1,t1,s2,t2,s3, t3,s4,t4 )`	`sets the current set of texture coordinates to the values passed as arguments.`
`RiTransform( transform )`	`sets the current transformation to the transformation transform.`
`RiTransformBegin() RiTransformEnd()`	`saves and restores the current transformation.`
`RiTransformPoints( fromspace, tospace, n, points )`	`transforms the array of points from the coordinate system fromspace to the coordinate system tospace.`
`RiTranslate( dx, dy, dz )`	`concatenates a translation onto the current transformation.`
`RiWorldBegin() RiWorldEnd()`	`Starts and ends the description of the scene geometry for a specific image.`

Geometric Primitives

Function	Description
`RiBasis( ubasis, ustep, vbasis, vstep )`	`sets the current u-basis to ubasis and the current v-basis to vbasis.`
`RiBlobby( nleaf, ncode, code, nfloats, floats, nstrings, strings,...)`	`requests an implicit surface.`
`RiCone( height, radius, thetamax, parameterlist )`	`requests a cone.`
`RiCurves(type, ncurves, nvertices, wrap, ...);`	`requests a collection of lines, curves or ribbons.`
`RiCylinder( radius, zmin, zmax, thetamax, parameterlist )`	`requests a cylinder.`
`RiDisk( height, radius, thetamax, parameterlist )`	`requests a disk.`
`RiGeneralPolygon( nloops, nverts, parameterlist )`	`defines a general planar concave polygon with holes.`
`RiGeometry( type, parameterlist )`	`provides a standard way of defining an implementation-specific geometric primitive.`
`RiHyperboloid( point1, point2, thetamax, parameterlist )`	`requests a hyperboloid.`
`RiNuPatch(nu, uorder, uknot, umin, umax, nv, vorder, vknot, vmin, vmax, parameterlist)`	`creates a single tensor product rational or polynomial non-uniform B-spline surface patch.`
`RiObjectBegin() RiObjectEnd()`	`begins and ends the definition of an object.`
`RiObjectInstance( handle );`	`creates an instance of a previously defined object.`
`RiParaboloid( rmax, zmin, zmax, thetamax, parameterlist )`	`requests a paraboloid.`
`RiPatch( type, parameterlist )`	`define a single patch.`
`RiPatchMesh( type, nu, uwrap, nv, vwrap, parameterlist )`	`specifies in a compact way a quadrilateral mesh of patches.`
`RiPoints(numpoints, ...)`	`requests a collection of point-like particles.`
`RiPointsPolygons( npolys, nverts, parameterlist )`	`defines npolys planar convex polygons that share vertices.`
`RiPointsGeneralPolygons( npolys, nloops, nverts, verts, parameterlist )`	`defines npolys planar concave polygons, with holes, that share vertices.`
`RiPolygon( nverts, parameterlist )`	`nverts is the number of vertices in a single closed planar convex polygon. parameterlist is a list of token-array pairs where each token is one of the standard geometric primitive variables or a variable which has been defined with RiDeclare.`
`RiProcedural( data, bound, subdividefunc, freefunc )`	`defines a procedural primitive.`
`RiSolidBegin( operation ) RiSolidEnd()`	`starts and ends the definition of a CSG solid primitive.`
`RiSphere( radius, zmin, zmax, thetamax, parameterlist )`	`requests a sphere.`
`RiSubdivisionMesh( scheme, nfaces, nverrtices, vertices, ntags, tags, nargs, intargs, floatargs, ...)`	`requests a subdivision surface mesh.`
`RiTorus( majorradius, minorradius, phimin, phimax, thetamax, parameterlist )`	`requests a torus.`
`RiTrimCurve( order, knot, min, max, n, u, v, w )`	`sets the current trim curve.`

Motion

Function	Description
`RiMotionBegin( n, t0, t1,...,tnminus1)`	`starts the definition of a moving primitive.`
`RiMotionEnd()`	`ends the definition of a moving primitive.`

Texture Map Utilities

Function	Description
`RiMakeCubeFaceEnvironment( px, nx, py, ny, pz, nz, texturename, fov, filterfunc, swidth, twidth, parameterlist )`	`converts six images in a standard picture file representing six viewing directions into an environment map whose name is texturename.`
`RiMakeLatLongEnvironment( picturename, texturename, filterfunc, swidth, twidth, parameterlist )`	`converts an image in a standard picture file representing a latitude-longitude map whose name is picturename into an environment map whose name is texturename.`
`RiMakeShadow( picturename, texturename, parameterlist )`	`creates a depth image file named picturename into a shadow map whose name is texturename.`
`RiMakeTexture( picturename, texturename, swrap, twrap )`	`converts an image in a standard picture file whose name is picturename into a texture file whose name is texturefile`

External Resources and Archiving

Function	Description
`RiErrorHandler( handler )`	`sets the user error handling procedure.`
`RiArchiveRecord( type, format, ... )`	`writes a user data record into a RIB archive file.`
`RiReadArchive( type, format, ... )`	`reads RIB from an archive file.`
`RiArchiveBegin( nm, ... ) RiArchiveEnd()`	`creates in-line archive definitions`
`RiIfBegin(expression) RiElseIf(expression) RiElse() RiIfEnd()`	`describe conditions for Ri evaluation.`

Math Functions

Function	Description
`abs(x)`	`returns the absolute value of its argument.`
`acos(a)`	`returns the arc cosine in the range 0 to PI.`
`asin(a)`	`returns the arc sine in the range PI/2 to PI/2.`
`atan(yoverx), atan(y,x)`	`with one argument returns the arc tangent in the range PI/2 to PI/2 (1 argument) or PI to PI (2 arguments).`
`ceil(x)`	`returns the largest integer (expressed as a float) not greater than x.`
`cellnoise(v), cellnoise(u,v), cellnoise(pt), cellnoise(pt, t)`	`returns a value which is a pseudorandom function of its arguments.`
`clamp(a,min,max)`	`returns min if a < min, max if a > max; otherwise a.`
`cos(a)`	`standard trigonometric function of radian arguments.`
`degrees(radians)`	`converts from radians to degrees.`
`Du(p), Dv(p), Deriv(num, den)`	`computes the derivatives of the arguments. The type returned depends on the type of the first argument. Du and Dv compute the derivatives in the u and v directions, respectively. Deriv computes the derivative of the first argument with respect to the second argument.`
`exp(x)`	`returns pow(e,x).`
`filterstep(edge, s1, ...)`	`returns a filtered version of step.`
`floor(x)`	`returns the smallest integer (expressed as a float) not smaller than x.`
`log(x), log(x,base)`	`returns the natural logarithm of x (x=log(exp(x))) (1 arg.) or the logarithm in the specified base (x=log(pow(base,x),base)) (2 args).`
`max(a,b)`	`returns the argument with maximum value.`
`min(a,b)`	`returns the argument with minumum value.`
`mix(c0, c1, v)`	`returns a linearly interpolated color value.`
`mod(a,b)`	`returns 0 <= mod < b such that mod(a, b) = a - nb for an integer n.`
`noise( v ), noise( u,v ), noise( pt), noise(pt, t)`	`returns a value which is a random function of its arguments.Its value is always between 0 and 1. The domain of this noise function can be 1-D (one float), 2-D (two floats), or 3-D (one point).`
`PI`	`= 3.14159... ;`
`pnoise( v, vp ), pnoise( u,v, up, vp ), pnoise( pt, ptp), pnoise(pt, t, ptp, tp)`	`returns a value like noise, but with the given periods over its domain.`
`pow(x, y)`	`returns xy.`
`radians(degrees)`	`converts from degrees to radians.`
`random()`	`returns a float, color, or point whose components are a random number between 0 and 1.`
`round(x)`	`returns the integer closest to x.`
`sign(x)`	`returns 1 with a negative argument, 1 with a positive argument, and 0 if its argument is zero.`
`sin(a)`	`standard trigonometric function of radian arguments.`
`smoothstep(min,max,value)`	`returns 0 if value < min, 1 if value > max, and performs a smooth Hermite interpolation between 0 and 1 in the interval min to max.`
`spline( [basis,] value, f1, f2, ..., fn, fn1 )`	`fits a Catmull-Rom interpolatory spline to the control points given. At least four control points must always be given.`
`sqrt(x)`	`returns pow(x,.5).`
`step(min,value)`	`returns 0 if value < min; otherwise 1.`
`tan(a)`	`standard trigonometric function of radian arguments.`

Geometric Functions

Function	Description
`area( P )`	`returns the differential surface area.`
`calculatenormal( P )`	`returns surface normal given a point on the surface.`
`depth( P )`	`returns the depth of the point P in camera coordinates. The depth is normalized to lie between 0 (at the near clipping plane) and 1 (at the far clipping plane).`
`distance( P1,P2 )`	`returns the distance between two points.`
`faceforward( N, I )`	`flips N so that it faces in the direction opposite to I.`
`fresnel( I, N, eta, Kr, Kt, [R, T] )`	`returns the reflection coefficient Kr and refraction (or transmission) coefficient Kt given an incident direction I, the surface normal N, and the relative index of refraction eta. Optionally, this procedure also returns the reflected (R) and transmitted (T) vectors.`
`length(V)`	`returns the length of a vector.`
`normalize( V )`	`returns a unit vector in the direction of V.`
`ptlined(Q,P1,P2)`	`returns the distance from Q to the line segment joining P1 and P2.`
`reflect( I, N )`	`returns the reflection vector given an incident direction I and a normal vector N.`
`refract( I, N, eta )`	`returns the transmitted vector given an incident direction I, the normal vector N and the relative index of refraction eta.`
`rotate( point Q; float angle; point P1, P2 )`	`rotates a point Q by angle radians about the axis which passes through the points P1 and P2.`
`setxcomp(P, x)`	`sets x component.`
`setycomp(P, y)`	`sets y component.`
`setzcomp(P, z)`	`sets z component.`
`transform( fromspace, tospace, P )`	`transforms the point P from the coordinate system fromspace to the coordinate system tospace. If fromspace is absent, it is assumed to be the "current" coordinate system.`
`vtransform( fromspace, tospace, V )`	`transforms the vector V from the coordinate system fromspace to the coordinate system tospace. If fromspace is absent, it is assumed to be the "current" coordinate system.`
`ntransform( fromspace, tospace, N )`	`transforms the normal n from the coordinate system fromspace to the coordinate system tospace. If fromspace is absent, it is assumed to be the "current" coordinate system.`
`xcomp(P)`	`gets x component.`
`ycomp(P)`	`gets y component.`
`zcomp(P)`	`gets z component.`

Color Functions

Function	Description
`comp(c, index)`	`gets individual color component.`
`setcomp(c, index,value)`	`sets individual color component.`
`ctransform( string tospace; color C; )`	`transforms color C from "rgb" to color representation "tospace".`
`ctransform( string fromspace, tospace; color C; )`	`transforms color C from color representation "fromspace" to "tospace".`

Matrix and Array Functions

Function	Description
`arraylength( v )`	`Returns the length of an array.`
`comp( matrix m; float row, column ), setcomp( matrix m; float row, column, value )`	`Get and set individual components of a matrix.`
`determinant( matrix m )`	`Returns the determinant of matrix m.`
`rotate( matrix m; float angle; vector axis ), scale( matrix m; point s ), translate( matrix m; vector t )`	`Postconcatenate simple transformations onto the matrix m`

String Functions

Function	Description
`concat(str1, ..., strn)`	`Returns a concatenated string.`
`format(pattern, val1, ...)`	`Returns a formatted string using the same rules as printf.`
`match(pattern, subject)`	`String pattern matching.`
`printf( format, val1, val2, ..., valn )`	`Prints the values of the specified variables on the standard output stream of the renderer. format uses "%f", "%p", "%c", and "%s" to indicate float, point, color and string, respectively.`

Shading and Lighting Functions

Function	Description
`ambient()`	`returns the total amount of ambient light incident upon the surface.`
`caustic(P, N)`	`returns the total amount of caustic light incident upon the surface.`
`diffuse( N )`	`returns the diffuse component of the lighting model.`
`indirectdiffuse( point P, normal N, float samples, ... )`	`returns diffuse illumination arising from indirect illumination.`
`occlusion( point P, normal N, float samples, ... )`	`returns a measure of ambient occlusion defined as the percentage of the hemisphere that is occluded from view by the "environment".`
`phong( N, V, size )`	`implements the Phong specular lighting model.`
`specular( N, V, roughness )`	`returns the specular component of the lighting model. N is the normal to the surface. V is a vector from a point on the surface towards the viewer.`
`specularbrdf(L, N, V, roughness)`	`returns the specular reflection contribution of a particular light direction.`
`trace( P, R )`	`returns the incident light falling on a point P in a given direction R.`
`transmission( point Psrc, point Pdst, ... )`	`returns a color representing the ability of light to flow between Psrc and Pdst.`

Language Control Structures

Function	Description
`break`	`breaks out of for and while loops`
`continue`	`continues to next interation of for and while loop`
`for(...)`	`a standard looping construct`
`gather(...)`	`a special looping construct - loops over ray samples`
`illuminance( ..)`	`a special looping construct - loops over direct lights`
`illuminate(...)`	`a special block construct - directs light`
`return`	`returns values from a function`
`solar(...)`	`a special block construct - directs light`
`while(...)`	`a standard looping construct`

Texture Mapping Functions

Function	Description
`bake3d( string filename, string displaymode, point P, normal N, ... )`	`writes a point with associated data to the file given by filename.`
`environment( name[channel], texture coordinates [, parameterlist] )`	`accesses an environment map.`
`irradiancecache( string operation, string handle, string filemode, point P, normal N, ... )`	`performs an irradiance cache operation on the cache given by handle.`
`photonmap( string filename, point P, normal N, ... )`	`returns the result of a photonmap lookup at surface point P with surface normal N.`
`shadow( name[channel], texture coordinates [, parameterlist] )`	`accesses a shadow depth map.`
`texture( name[channel] [ ,texture coordinates] [, parameterlist] )`	`accesses a basic texture map.`
`texture3d( string filename, point P, normal N, ... )`	`reads texture values from the file given by filename.`
`textureinfo( texturename, paramname, variable )`	`returns information about a texture map.`

Message Passing Functions

Function	Description
`atmosphere( name,value )`	`looks up the value of a variable that is store in the atmosphere shader attached to the geometric primitive surface.`
`displacement( name,value )`	`looks up the value of a variable that is store in the displacement shader attached to the geometric primitive surface.`
`incident( name,value )`	`looks up the value of a variable that is store in the incident shader attached to the geometric primitive surface.`
`lightsource( name,value )`	`looks up the value of a variable that is store in the lightsource shader attached to the geometric primitive surface.`
`opposite( name, value )`	`returns the value of the opposite variable name that is stored in the volume shaders attached to geometric primitive surface.`
`surface( name,value )`	`looks up the value of a variable that is store in the surface shader attached to the geometric primitive surface.`

Renderer State Functions

Function	Description
`attribute( name,value )`	`looks up the value of a renderer attribute`
`option( name,value )`	`lookup of the value of a renderer option`
`rayinfo( uniform string keyword, result, ... )`	`provides access to state associated with the ray which resulted in the shader execution.`
`rendererinfo( name,value )`	`looks up the information about the render implementation itself.`
`shadername(), shadername( string shadertype )`	`If no parameter is passed, returns the name of the shader that is currently running. If the shadertype is supplied, this function returns the name of the shader of the specified type`

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Pixar. The information in this publication is furnished for informational use only, is subject to change without notice and should not be construed as a commitment by Pixar. Pixar assumes no responsibility or liability for any errors or inaccuracies that may appear in this publication.