APPENDIX C - LANGUAGE BINDING DETAILS

C Binding

The following is the file ri.h for the C binding of the RenderMan Interface. This file contains all of the type, procedure, and global variable declarations and predefined constant definitions that must be supported by a RenderMan renderer.

/*
 *	RenderMan Interface Standard Include File
 *	(for Kernighan & Ritchie 1978 "C Classic")
 */

	/* Definitions of Abstract Types used in RI */

typedef short	RtBoolean;
typedef long	RtInt;
typedef float	RtFloat;

typedef char	*RtToken;

typedef RtFloat	RtColor[3];
typedef RtFloat	RtPoint[3];
typedef RtFloat	RtMatrix[4][4];
typedef RtFloat	RtBasis[4][4];
typedef RtFloat	RtBound[6];

typedef char	*RtString;

typedef char	*RtPointer;
typedef int	RtVoid;

typedef RtFloat	(*RtFloatFunc)();
typedef RtVoid	(*RtFunc)();

typedef RtPointer RtObjectHandle;
typedef RtPointer RtLightHandle;

		/* Extern Declarations for Predefined RI Data Structures */

#define RI_FALSE	0
#define RI_TRUE		(! RI_FALSE)
#define RI_INFINITY	1.0e38
#define RI_EPSILON	1.0e-10
#define RI_NULL		((RtToken)0)

extern RtToken	RI_FRAMEBUFFER, RI_FILE;
extern RtToken	RI_RGB, RI_RGBA, RI_RGBZ, RI_RGBAZ, RI_A, RI_Z, RI_AZ;
extern RtToken	RI_PERSPECTIVE, RI_ORTHOGRAPHIC;
extern RtToken	RI_HIDDEN, RI_PAINT;
extern RtToken	RI_CONSTANT, RI_SMOOTH;
extern RtToken	RI_FLATNESS, RI_FOV;

extern RtToken	RI_AMBIENTLIGHT, RI_POINTLIGHT, RI_DISTANTLIGHT,
          	RI_SPOTLIGHT; 
extern RtToken	RI_INTENSITY, RI_LIGHTCOLOR, RI_FROM, RI_TO,
          	RI_CONEANGLE, RI_CONEDELTAANGLE, RI_BEAMDISTRIBUTION;
extern RtToken	RI_MATTE, RI_METAL, RI_SHINYMETAL,
          	RI_PLASTIC, RI_PAINTEDPLASTIC;
extern RtToken	RI_KA, RI_KD, RI_KS, RI_ROUGHNESS, RI_KR,
          	RI_TEXTURENAME, RI_SPECULARCOLOR;
extern RtToken	RI_DEPTHCUE, RI_FOG, RI_BUMPY;
extern RtToken	RI_MINDISTANCE, RI_MAXDISTANCE, RI_BACKGROUND,
          	RI_DISTANCE, RI_AMPLITUDE;
extern RtToken	RI_RASTER, RI_SCREEN, RI_CAMERA, RI_WORLD, RI_OBJECT;
extern RtToken	RI_INSIDE, RI_OUTSIDE, RI_LH, RI_RH;
extern RtToken	RI_P, RI_PZ, RI_PW, RI_N, RI_NP, RI_CS, RI_OS,
          	RI_S, RI_T, RI_ST;
extern RtToken	RI_BILINEAR, RI_BICUBIC;
extern RtToken	RI_PRIMITIVE, RI_INTERSECTION, RI_UNION, RI_DIFFERENCE;
extern RtToken	RI_PERIODIC, RI_NONPERIODIC, RI_CLAMP, RI_BLACK;
extern RtToken	RI_IGNORE, RI_PRINT, RI_ABORT, RI_HANDLER;

extern RtBasis	RiBezierBasis, RiBSplineBasis, RiCatmullRomBasis,
          	RiHermiteBasis, RiPowerBasis;

#define RI_BEZIERSTEP		((RtInt)3)
#define RI_BSPLINESTEP		((RtInt)1)
#define RI_CATMULLROMSTEP	((RtInt)1)
#define RI_HERMITESTEP		((RtInt)2)
#define RI_POWERSTEP		((RtInt)4)

extern RtInt	RiLastError;


      	/* Declarations of All the RenderMan Interface Subroutines */

extern RtFloat	RiGaussianFilter(), RiBoxFilter(), RiTriangleFilter(),
		RiCatmullRomFilter(), RiSincFilter();
extern RtVoid	RiErrorIgnore();
extern RtVoid	RiErrorPrint();
extern RtVoid	RiErrorAbort();

extern RtToken	RiDeclare();

extern RtVoid	RiBegin(), RiEnd(),
		RiFrameBegin(), RiFrameEnd(),
		RiWorldBegin(), RiWorldEnd();

extern RtVoid	RiFormat(), RiFrameAspectRatio(), RiScreenWindow(),
		RiCropWindow(), RiProjection(), RiProjectionV(),
		RiClipping(), RiDepthOfField(), RiShutter();

extern RtVoid	RiPixelVariance(), RiPixelSamples(), RiPixelFilter(),
		RiExposure(), RiImager(), RiImagerV(),
		RiQuantize(), RiDisplay(), RiDisplayV();

extern RtVoid	RiHider(), RiHiderV(), RiColorSamples(), RiRelativeDetail(),
		RiOption(), RiOptionV();

extern RtVoid	RiAttributeBegin(), RiAttributeEnd(),
		RiColor(), RiOpacity(), RiTextureCoordinates();

extern RtLightHandle	RiLightSource(), RiLightSourceV(),
			RiAreaLightSource(), RiAreaLightSourceV();

extern RtVoid	RiIlluminate(),
		RiSurface(), RiSurfaceV(), RiAtmosphere(), RiAtmosphereV(),
		RiInterior(), RiInteriorV(), RiExterior(), RiExteriorV(),
		RiShadingRate(), RiShadingInterpolation(), RiMatte();

extern RtVoid	RiBound(), RiDetail(), RiDetailRange(),
		RiGeometricApproximation(),
		RiOrientation(), RiReverseOrientation(), RiSides();

extern RtVoid	RiIdentity(), RiTransform(), RiConcatTransform(),
		RiPerspective(), RiTranslate(), RiRotate(), RiScale(), RiSkew(),
		RiDeformation(), RiDeformationV(),
		RiDisplacement(), RiDisplacementV(), RiCoordinateSystem();
extern RtPoint	*RiTransformPoints();
extern RtVoid	RiTransformBegin(), RiTransformEnd();

extern RtVoid	RiAttribute(), RiAttributeV();

extern RtVoid	RiPolygon(), RiPolygonV(),
		RiGeneralPolygon(), RiGeneralPolygonV(),
		RiPointsPolygons(), RiPointsPolygonsV(),
		RiPointsGeneralPolygons(), RiPointsGeneralPolygonsV(),
		RiBasis(), RiPatch(), RiPatchV(), RiPatchMesh(), RiPatchMeshV(),
		RiNuPatch(), RiNuPatchV(), RiTrimCurve();

extern RtVoid	RiSphere(), RiSphereV(), RiCone(), RiConeV(),
		RiCylinder(), RiCylinderV(), RiHyperboloid(), RiHyperboloidV(),
		RiParaboloid(), RiParaboloidV(), RiDisk(), RiDiskV(),
		RiTorus(), RiTorusV(),
		RiProcedural(), RiGeometry(), RiGeometryV();

extern RtVoid	RiSolidBegin(), RiSolidEnd() ;
extern RtObjectHandle  	RiObjectBegin();
extern RtVoid	RiObjectEnd(), RiObjectInstance(), 
		RiMotionBegin(), RiMotionBeginV(), RiMotionEnd() ;

extern RtVoid	RiMakeTexture(), RiMakeTextureV(), RiMakeBump(), RiMakeBumpV(),
		RiMakeLatLongEnvironment(), RiMakeLatLongEnvironmentV(),
		RiMakeCubeFaceEnvironment(), RiMakeCubeFaceEnvironmentV(),
		RiMakeShadow(), RiMakeShadowV();

extern RtVoid	RiErrorHandler();

/*
	Error Codes

	 1 - 10		System and File Errors
	11 - 20		Program Limitations
	21 - 40		State Errors
	41 - 60		Parameter and Protocol Errors
	61 - 80		Execution Errors

*/

#define RIE_NOERROR	((RtInt)0)

#define RIE_NOMEM	((RtInt)1)	/* Out of memory */
#define RIE_SYSTEM	((RtInt)2)	/* Miscellaneous system error */
#define RIE_NOFILE	((RtInt)3)	/* File nonexistent */
#define RIE_BADFILE	((RtInt)4)	/* Bad file format */
#define RIE_VERSION	((RtInt)5)	/* File version mismatch */

#define RIE_INCAPABLE	((RtInt)11)	/* Optional RI feature */
#define RIE_UNIMPLEMENT	((RtInt)12)	/* Unimplemented feature */
#define RIE_LIMIT	((RtInt)13)	/* Arbitrary program limit */
#define RIE_BUG		((RtInt)14)	/* Probably a bug in renderer */

#define RIE_NOTSTARTED	((RtInt)23)	/* RiBegin not called */
#define RIE_NESTING	((RtInt)24)	/* Bad begin-end nesting */
#define RIE_NOTOPTIONS	((RtInt)25)	/* Invalid state for options */
#define RIE_NOTATTRIBS	((RtInt)26)	/* Invalid state for attribs */
#define RIE_NOTPRIMS	((RtInt)27)	/* Invalid state for primitives */
#define RIE_ILLSTATE	((RtInt)28)	/* Other invalid state */
#define RIE_BADMOTION	((RtInt)29)	/* Badly formed motion block */
#define RIE_BADSOLID	((RtInt)30)	/* Badly formed solid block */

#define RIE_BADTOKEN	((RtInt)41)	/* Invalid token for request */
#define RIE_RANGE	((RtInt)42)	/* Parameter out of range */
#define RIE_CONSISTENCY	((RtInt)43)	/* Parameters inconsistent */ 
#define RIE_BADHANDLE	((RtInt)44)	/* Bad object/light handle */
#define RIE_NOSHADER	((RtInt)45)	/* Can't load requested shader */
#define RIE_MISSINGDATA	((RtInt)46)	/* Required parameters not provided */
#define RIE_SYNTAX	((RtInt)47)	/* Declare type syntax error */

#define RIE_MATH	((RtInt)61)	/*Zerodivide, noninvert matrix, etc.*/




	/* Error severity levels */

#define RIE_INFO	((RtInt)0)	/* Rendering stats and other info */
#define RIE_WARNING	((RtInt)1)	/* Something seems wrong, maybe okay */
#define RIE_ERROR	((RtInt)2)	/* Problem. Results may be wrong */
#define RIE_SEVERE	((RtInt)3)	/* So bad you should probably abort */

ANSI C Binding

The following is the version of ri.h required for the ANSI-standard C binding of the RenderMan Interface. It differs from the previous version only in the expected ways.

/*
 *	RenderMan Interface Standard Include File
 *		(for ANSI Standard C)
 */


      	/* Definitions of Abstract Types used in RI */

typedef short	RtBoolean;
typedef long	RtInt;
typedef float	RtFloat;

typedef char	*RtToken;

typedef RtFloat	RtColor[3];
typedef RtFloat	RtPoint[3];
typedef RtFloat	RtMatrix[4][4];
typedef RtFloat	RtBasis[4][4];
typedef RtFloat	RtBound[6];
typedef char	*RtString;
typedef void	*RtPointer;

#define RtVoid	void
typedef RtFloat	(*RtFilterFunc)(RtFloat, RtFloat, RtFloat, RtFloat);
typedef RtVoid	(*RtErroandler)(RtInt, Rtnt, char *);

typedef RtPointer	RtObjectHandle; 
typedef RtPointer	RtLightHandle;


	/* Extern Declarations for Predefined RI Data Structures */

#define RI_FALSE	0
#define RI_TRUE		(! RI_FALSE)
#define RI_INFINITY	1.0e38
#define RI_EPSILON	1.0e-10
#define RI_NULL		((RtToken)0)

extern RtToken	RI_FRAMEBUFFER, RI_FILE; 
extern RtToken	RI_RGB, RI_RGBA, RI_RGBZ, RI_RGBAZ, RI_A, RI_Z, RI_AZ;
extern RtToken	RI_PERSPECTIVE, RI_ORTHOGRAPHIC;
extern RtToken	RI_HIDDEN, RI_PAINT;
extern RtToken	RI_CONSTANT, RI_SMOOTH;
extern RtToken 	RI_FLATNESS, RI_FOV;

extern RtToken	RI_AMBIENTLIGHT, RI_POINTLIGHT, RI_DISTANTLIGHT,
		RI_SPOTLIGHT;

extern RtToken	RI_INTENSITY, RI_LIGHTCOLOR, RI_FROM, RI_TO, RI_CONEANGLE,
	 	RI_CONEDELTAANGLE, RI_BEAMDISTRIBUTION;

extern RtToken	RI_MATTE, RI_METAL, RI_SHINYMETAL,
		RI_PLASTIC, RI_PAINTEDPLASTIC;

extern RtToken	RI_KA, RI_KD, RI_KS, RI_ROUGHNESS, RI_KR,
	 	RI_TEXTURENAME, RI_SPECULARCOLOR;
extern RtToken	RI_DEPTHCUE, RI_FOG, RI_BUMPY;

extern RtToken	RI_MINDISTANCE, RI_MAXDISTANCE, RI_BACKGROUND,
		RI_DISTANCE, RI_AMPLITUDE;

extern RtToken	RI_RASTER, RI_SCREEN, RI_CAMERA, RI_WORLD, RI_OBJECT;
extern RtToken	RI_INSIDE, RI_OUTSIDE, RI_LH, RI_RH;
extern RtToken	RI_P, RI_PZ, RI_PW, RI_N, RI_NP, RI_CS, RI_OS, RI_S, RI_T, RI_ST;
extern RtToken	RI_BILINEAR, RI_BICUBIC;
extern RtToken	RI_PRIMITIVE, RI_INTERSECTION, RI_UNION, RI_DIFFERENCE;
extern RtToken	RI_PERIODIC, RI_NONPERIODIC, RI_CLAMP, RI_BLACK;
extern RtToken	RI_IGNORE, RI_PRINT, RI_ABORT, RI_HANDLER;

extern RtBasis	RiBezierBasis, RiBSplineBasis, RiCatmullRomBasis,
		RiHermiteBasis, RiPowerBasis;

#define RI_BEZIERSTEP		((RtInt)3)
#define RI_BSPLINESTEP		((RtInt)1)
#define RI_CATMULLROMSTEP	((RtInt)1)
#define RI_HERMITESTEP		((RtInt)2) 
#define RI_POWERSTEP		((RtInt)4)

extern RtInt	RiLastError;


	/* Declarations of All the RenderMan Interface Subroutines */

extern RtFloat	RiGaussianFilter(RtFloat x, RtFloat y,
			RtFloat xwidth, RtFloat ywidth);
extern RtFloat	RiBoxFilter(RtFloat x, RtFloat y,
			RtFloat xwidth, RtFloat ywidth);
extern RtFloat	RiTriangleFilter(RtFloat x, RtFloat y,
			RtFloat xwidth, RtFloat ywidth);
extern RtFloat	RiCatmullRomFilter(RtFloat x, RtFloat y,
			RtFloat xwidth, RtFloat ywidth);
extern RtFloat	RiSincFilter(RtFloat x, RtFloat y,
			RtFloat xwidth, RtFloat ywidth);
extern RtVoid	RiErrorIgnore(RtInt code, RtInt severity, char *msg);
extern RtVoid	RiErrorPrint(RtInt code, RtInt severity, char *msg);
extern RtVoid	RiErrorAbort(RtInt code, RtInt severity, char *msg);

extern RtToken
	RiDeclare(char *name, char *declaration);

extern RtVoid
	RiBegin(RtToken name),
	RiEnd(void),
	RiFrameBegin(RtInt frame),
	RiFrameEnd(void),
	RiWorldBegin(void),
	RiWorldEnd(void);

extern RtVoid
	RiFormat(RtInt xres, RtInt yres, RtFloat aspect),
	RiFrameAspectRatio(RtFloat aspect),
	RiScreenWindow(RtFloat left, RtFloat right, RtFloat bot, RtFloat top),
	RiCropWindow(RtFloat xmin, RtFloat xmax, RtFloat ymin, RtFloat ymax),
	RiProjection(RtToken name, ...),
	RiProjectionV(RtToken name, RtInt n,RtToken tokens[],RtPointer parms[]),
	RiClipping(RtFloat hither, RtFloat yon),
	RiShutter(RtFloat min, RtFloat max);

extern RtVoid
	RiPixelVariance(RtFloat variation),
	RiPixelSamples(RtFloat xsamples, RtFloat ysamples),
	RiPixelFilter(RtFilterFunc filterfunc, RtFloat xwidth, RtFloat ywidth),
	RiExposure(RtFloat gain, RtFloat gamma),
	RiImager(RtToken name, ...),
	RiImagerV(RtToken name, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiQuantize(RtToken type, RtInt one, RtInt min, RtInt max, RtFloat ampl),
	RiDisplay(char *name, RtToken type, RtToken mode, ...),
	RiDisplayV(char *name, RtToken type, RtToken mode,
		RtInt n, RtToken tokens[], RtPointer parms[]);

extern RtVoid
	RiHider(RtToken type, ...),
	RiHiderV(RtToken type, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiColorSamples(RtInt n, RtFloat nRGB[], RtFloat RGBn[]),
	RiRelativeDetail(RtFloat relativedetail),
	RiOption(RtToken name, ...),
	RiOptionV(RtToken name, RtInt n, RtToken tokens[], RtPointer parms[]);

extern RtVoid
	RiAttributeBegin(void),
	RiAttributeEnd(void),
	RiColor(RtColor color),
	RiOpacity(RtColor color),
	RiTextureCoordinates(RtFloat s1, RtFloat t1, RtFloat s2, RtFloat t2,
		RtFloat s3, RtFloat t3, RtFloat s4, RtFloat t4);

extern RtLightHandle
	RiLightSource(RtToken name, ...),
	RiLightSourceV(RtToken name,RtInt n,RtToken tokens[],RtPointer parms[]),
	RiAreaLightSource(RtToken name, ...),
	RiAreaLightSourceV(RtToken name,
		RtInt n, RtToken tokens[], RtPointer parms[]);
extern RtVoid
	RiIlluminate(RtLightHandle light, RtBoolean onoff),
	RiSurface(RtToken name, ...),
	RiSurfaceV(RtToken name, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiAtmosphere(RtToken name, ...),
	RiAtmosphereV(RtToken name,RtInt n,RtToken tokens[],RtPointer parms[]),
	RiInterior(RtToken name, ...),
	RiInteriorV(RtToken name,RtInt n,RtToken tokens[],RtPointer parms[]),
 	RiExterior(RtToken name, ...),
	RiExteriorV(RtToken name,RtInt n,RtToken tokens[],RtPointer parms[]),
	RiShadingRate(RtFloat size),
	RiShadingInterpolation(RtToken type),
 	RiMatte(RtBoolean onoff);

extern RtVoid
	RiBound(RtBound bound),
	RiDetail(RtBound bound),
	RiDetailRange(RtFloat minvis, RtFloat lowtran, RtFloat uptran, RtFloat
		maxvis),
	RiGeometricApproximation(RtToken type, RtFloat value),
	RiOrientation(RtToken orientation),
	RiReverseOrientation(void),
	RiSides(RtInt sides);

extern RtVoid
	RiIdentity(void),
	RiTransform(RtMatrix transform),
	RiConcatTransform(RtMatrix transform),
	RiPerspective(RtFloat fov),
	RiTranslate(RtFloat dx, RtFloat dy, RtFloat dz),
	RiRotate(RtFloat angle, RtFloat dx, RtFloat dy, RtFloat dz),
	RiScale(RtFloat sx, RtFloat sy, RtFloat sz),
	RiSkew(RtFloat angle, RtFloat dx1, RtFloat dy1, RtFloat dz1,
		RtFloat dx2, RtFloat dy2, RtFloat dz2),
	RiDeformation(RtToken name, ...),
	RiDeformationV(RtToken name,RtInt n,RtToken tokens[],RtPointer parms[]),
	RiDisplacement(RtToken name, ...),
	RiDisplacementV(RtToken name,RtInt n,RtToken tokens[],RtPointer
		parms[]),
	RiCoordinateSystem(RtToken space);

extern RtPoint *
	RiTransformPoints(RtToken fromspace, RtToken tospace, RtInt n,
		RtPoint points[]);

extern RtVoid
	RiTransformBegin(void),
	RiTransformEnd(void);

extern RtVoid
	RiAttribute(RtToken name, ...),
	RiAttributeV(RtToken name, RtInt n, RtToken tokens[], RtPointer parms[]);

extern RtVoid
	RiPolygon(RtInt nverts, ...),
	RiPolygonV(RtInt nverts, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiGeneralPolygon(RtInt nloops, RtInt nverts[], ...),
	RiGeneralPolygonV(RtInt nloops, RtInt nverts[],
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiPointsPolygons(RtInt npolys, RtInt nverts[], RtInt verts[], ...),
	RiPointsPolygonsV(RtInt npolys, RtInt nverts[], RtInt verts[],
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiPointsGeneralPolygons(RtInt npolys, RtInt nloops[], RtInt nverts[],
		RtInt verts[], ...),
	RiPointsGeneralPolygonsV(RtInt npolys, RtInt nloops[], RtInt nverts[],
		RtInt verts[], RtInt n, RtToken tokens[], RtPointer parms[]),
	RiBasis(RtBasis ubasis, RtInt ustep, RtBasis vbasis, RtInt vstep),
	RiPatch(RtToken type, ...),
	RiPatchV(RtToken type, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiPatchMesh(RtToken type, RtInt nu, RtToken uwrap,
		RtInt nv, RtToken vwrap, ...),
	RiPatchMeshV(RtToken type, RtInt nu, RtToken uwrap,
		RtInt nv, RtToken vwrap,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiNuPatch(RtInt nu, RtInt uorder, RtFloat uknot[], RtFloat umin,
		RtFloat umax, RtInt nv, RtInt vorder, RtFloat vknot[],
		RtFloat vmin, RtFloat vmax, ...),
	RiNuPatchV(RtInt nu, RtInt uorder, RtFloat uknot[], RtFloat umin,
		RtFloat umax, RtInt nv, RtInt vorder, RtFloat vknot[],
		RtFloat vmin, RtFloat vmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiTrimCurve(RtInt nloops, RtInt ncurves[], RtInt order[],
		RtFloat knot[], RtFloat min[], RtFloat max[], RtInt n[],
		RtFloat u[], RtFloat v[], RtFloat w[]);

extern RtVoid
	RiSphere(RtFloat radius, RtFloat zmin, RtFloat zmax, RtFloat tmax, ...),
	RiSphereV(RtFloat radius, RtFloat zmin, RtFloat zmax, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiCone(RtFloat height, RtFloat radius, RtFloat tmax, ...),
	RiConeV(RtFloat height, RtFloat radius, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiCylinder(RtFloat radius,RtFloat zmin,RtFloat zmax,RtFloat tmax, ...),
	RiCylinderV(RtFloat radius, RtFloat zmin, RtFloat zmax, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiHyperboloid(RtPoint point1, RtPoint point2, RtFloat tmax, ...),
	RiHyperboloidV(RtPoint point1, RtPoint point2, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiParaboloid(RtFloat rmax,RtFloat zmin,RtFloat zmax,RtFloat tmax, ...),
	RiParaboloidV(RtFloat rmax, RtFloat zmin, RtFloat zmax, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiDisk(RtFloat height, RtFloat radius, RtFloat tmax, ...),
	RiDiskV(RtFloat height, RtFloat radius, RtFloat tmax,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiTorus(RtFloat majrad, RtFloat minrad, RtFloat phimin, RtFloat phimax,
		RtFloat tmax, ...),
	RiTorusV(RtFloat majrad,RtFloat minrad,RtFloat phimin,RtFloat phimax,
		RtFloat tmax, RtInt n, RtToken tokens[], RtPointer parms[]),
	RiProcedural(RtPointer data, RtBound bound,
		RtVoid (*subdivfunc)(RtPointer, RtFloat),
		RtVoid (*freefunc)(RtPointer)
	RiGeometry(RtToken type, ...),
	RiGeometryV(RtToken type, RtInt n, RtToken tokens[], RtPointer parms[]);

extern RtVoid
	RiSolidBegin(RtToken operation),
	RiSolidEnd(void) ;

extern RtObjectHandle
	RiObjectBegin(void);

extern RtVoid
	RiObjectEnd(void),
	RiObjectInstance(RtObjectHandle handle),
	RiMotionBegin(RtInt n, ...),
	RiMotionBeginV(RtInt n, RtFloat times[]),
	RiMotionEnd(void) ;

extern RtVoid
	RiMakeTexture(char *pic, char *tex, RtToken swrap, RtToken twrap,
		RtFilterFunc filterfunc, RtFloat swidth, RtFloat twidth, ...),
	RiMakeTextureV(char *pic, char *tex, RtToken swrap, RtToken twrap,
	 	RtFilterFunc filterfunc, RtFloat swidth, RtFloat twidth,
	 	RtInt n, RtToken tokens[], RtPointer parms[]),
	RiMakeBump(char *pic, char *tex, RtToken swrap, RtToken twrap,
		RtFilterFunc filterfunc, RtFloat swidth, RtFloat twidth, ...),
	RiMakeBumpV(char *pic, char *tex, RtToken swrap, RtToken twrap,
		RtFilterFunc filterfunc, RtFloat swidth, RtFloat twidth,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiMakeLatLongEnvironment(char *pic, char *tex, RtFilterFunc filterfunc,
		RtFloat swidth, RtFloat twidth, ...),
	RiMakeLatLongEnvironmentV(char *pic, char *tex, RtFilterFunc filterfunc,
		RtFloat swidth, RtFloat twidth,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiMakeCubeFaceEnvironment(char *px, char *nx, char *py, char *ny,
		char *pz, char *nz, char *tex, RtFloat fov,
		RtFilterFunc filterfunc, RtFloat swidth, RtFloat ywidth, ...),
	RiMakeCubeFaceEnvironmentV(char *px, char *nx, char *py, char *ny,
		char *pz, char *nz, char *tex, RtFloat fov,
		RtFilterFunc filterfunc, RtFloat swidth, RtFloat ywidth,
		RtInt n, RtToken tokens[], RtPointer parms[]),
	RiMakeShadow(char *pic, char *tex, ...),
	RiMakeShadowV(char *pic, char *tex,
		RtInt n, RtToken tokens[], RtPointer parms[]);

extern RtVoid
	RiErrorHandler(RtFunc handler);


/*
	Error Codes

	 1 - 10		System and File Errors
	11 - 20		Program Limitations
	21 - 40		State Errors
	41 - 60		Parameter and Protocol Errors
	61 - 80		Execution Errors
*/

 #define RIE_NOERROR	((RtInt)0)

#define RIE_NOMEM	((RtInt)1)	/* Out of memory */
#define RIE_SYSTEM	((RtInt)2)	/* Miscellaneous system error */
#define RIE_NOFILE	((RtInt)3)	/* File nonexistent */
#define RIE_BADFILE	((RtInt)4)	/* Bad file format */
#define RIE_VERSION	((RtInt)5)	/* File version mismatch */

#define RIE_INCAPABLE	((RtInt)11)	/* Optional RI feature */
#define RIE_UNIMPLEMENT	((RtInt)12)	/* Unimplemented feature */
#define RIE_LIMIT	((RtInt)13)	/* Arbitrary program limit */
#define RIE_BUG		((RtInt)14)	/* Probably a bug in renderer */

#define RIE_NOTSTARTED	((RtInt)23)	/* RiBegin not called */
#define RIE_NESTING	((RtInt)24)	/* Bad begin-end nesting */
#define RIE_NOTOPTIONS	((RtInt)25)	/* Invalid state for options */
#define RIE_NOTATTRIBS	((RtInt)26)	/* Invalid state for attribs */
#define RIE_NOTPRIMS	((RtInt)27)	/* Invalid state for primitives */
#define RIE_ILLSTATE	((RtInt)28)	/* Other invalid state */
#define RIE_BADMOTION	((RtInt)29)	/* Badly formed motion block */
#define RIE_BADSOLID	((RtInt)30)	/* Badly formed solid block */

#define RIE_BADTOKEN	((RtInt)41)	/* Invalid token for request */
#define RIE_RANGE	((RtInt)42)	/* Parameter out of range */
#define RIE_CONSISTENCY	((RtInt)43)	/* Parameters inconsistent */
#define RIE_BADHANDLE	((RtInt)44)	/* Bad object/light handle */
#define RIE_NOSHADER	((RtInt)45)	/* Can't load requested shader */
#define RIE_MISSINGDATA	((RtInt)46)	/* Required parameters not provided */
#define RIE_SYNTAX	((RtInt)47)	/* Declare type syntax error */

#define RIE_MATH	((RtInt)61)	/* Zerodivide, noninvert matrix, etc. */



	/* Error severity levels */

#define RIE_INFO	((RtInt)0)	/* Rendering stats and other info */
#define RIE_WARNING	((RtInt)1)	/* Something seems wrong, maybe okay */
#define RIE_ERROR	((RtInt)2)	/* Problem. Results may be wrong */
#define RIE_SEVERE	((RtInt)3)	/* So bad you should probably abort */

RIB Binding

The RenderMan Interface Bytestream Protocol, abbreviated RIB, is a byte-oriented protocol for specifying requests to the RenderMan Interface (RI) library. RIB permits clients of the RenderMan Interface to communicate requests to a remote rendering service, or to save requests in a file for later submission to a renderer. To satisfy the many different needs of clients, the protocol is designed to provide both

• an understandable (potentially) interactive interface to a rendering server, and
• a compact encoded format that minimizes transmission time (and space when stored in a file)

RIB also strives to minimize the amount of communication from a server to a client. This is particularly important in the situation where no communication is possible; e.g., when recording RIB in a file.

RIB is a byte stream protocol. That is, RIB interpreters work by scanning the input stream one byte at a time. This implies interpreters should make no assumptions about data alignment. The protocol is best thought of as a command language where tokens in the input stream can be transmitted either as 7-bit ASCII strings or, optionally, as compressed binary data. The ASCII interface provides a convenient interface for users to interactively communicate with a rendering server and for developers to debug systems that generate RIB. The binary encoding significantly compresses the data stream associated with an RI description with an associated savings in communication overhead and/or file storage cost.

Syntax rules

RenderMan Interface Protocol requests are constructed from sequences of tokens. Tokens are formed by the input scanner by grouping characters according to the RIB syntax rules (described below). Other than requirements associated with delimiting tokens, RIB employs a free format syntax.

Character set

The standard character set is the printable subset of the ASCII character set, plus the characters space, tab, and newline (return or line-feed). Non-printing characters are accepted, but are discouraged as they impair portability.

The characters space, tab, and newline are referred to as white space characters and are treated equivalently (except when they appear in comments or strings). White space is used to delimit syntactic constructs such as identifiers or numbers. Any number of consecutive white space characters are treated as a single white space character.

The characters `"', '#', '[', and ']' are special: they delimit syntactic entities. All other characters are termed regular characters and may be used in constructing syntactic entities such as identifiers and numbers.

Comments

Any occurrence of the `#' character, except when in a string, indicates a comment. The comment consists of all characters between the `#' and the next newline character. Comments are treated as white space when they are encountered by the input scanner.

Numbers

Numbers include signed integers and reals. An integer consists of an optional sign (`+', `-') followed by one or more decimal digits. The number is interpreted as a signed decimal integer.

A real consists of an optional sign and one or more decimal digits, with an embedded period (decimal point), a trailing exponent, or both. The exponent, if present, consists of `E' or `e' followed by an optional sign and one or more decimal digits. The number is interpreted as a real number and converted to an internal floating point value.

Strings

A string is an arbitrary sequence of characters delimited by double quote marks (`"'). Within a string the only special characters are `"' and the `\' (back-slash) character. The `\' character is used as an `escape' to include the `"' character, non-printing characters, and the `\' character itself. The character immediately following the `\' determines the precise interpretation, as follows:

          	\n	linefeed (newline)
          	\r	carriage return
          	\t	horizontal tab
          	\b	backspace
          	\f	form feed
          	\\	backslash
          	\"	double quote
          	\ddd	character code ddd (octal)
          	\newline	no character -- both are ignored

If the character following the `\' is not one of the above, the `\' is ignored.

The \ddd form may be used to include any 8-bit character constant in a string. One, two, or three octal digits may be specified (with high-order overflow ignored).

The \newline form is used to break a string into a number of lines but not have the newlines be part of the string.

Names

Any token that consists entirely of regular characters and that cannot be interpreted as a number is treated as a name. All characters except specials and white space can appear in names.

Arrays

The characters `[' and `]' are self-delimiting tokens that specify the construction of an array of numbers or strings. An array cannot contain both numbers and strings. If an array contains at least one floating point value, all integer values in the array are converted to floating point. Arrays of numbers are used, for example, to specify matrices and points. Arrays of strings are used in specifying options.

Binary encoding

For efficiency, compressed binary encodings of many types of data are also supported. These encodings may be freely intermixed with the normal ASCII strings. The two encodings are differentiated by the top bit of the eight-bit bytes in the input stream. If the top bit is zero, then the byte is interpreted as a 7-bit ASCII character. Otherwise, if the top bit is one, the byte is interpreted as a compressed token according to the rules given below. This differentiation is not applied within string constants or the parameter bytes which follow the initial byte of a compressed token. Table C1 shows the encoding for compressed tokens with all byte values displayed in octal.

Table C1 Binary Encoding

Four separate data types are supported: signed integers, signed fixed-point numbers, strings, and floating-point numbers. Integers and fixed-point numbers are encoded using a single format while strings are encoded with two different formats according to the length of the string. Both single- and double-precision IEEE format floating-point numbers are supported. Strings that are used repeatedly can be defined and then subsequently referenced with a compact form that is usually more space efficient.

Arrays of floating-point values are directly supported for efficiency (they can also be specified using the array definition symbols). Single-precision matrices (arrays of 16 floating-point values) can be specified in a total of 66 bytes, while other arrays may require slightly more.

In the following sections the syntax for each encoding is presented as a sequence of bytes separated by `|' symbols. Numeric values should interpreted as octal values (base 8) if they have a leading `0' digit, otherwise as decimal values. Items shown in angle brackets `< >' represent varying items, such as a numeric value or string that is being encoded.

Integers and fixed-point numbers. Integer and fixed-point values can be transmitted in 2-5 bytes. The encoded token has the form:

          	0200 + (d á 4) + w | <value>

where the next w+1 bytes form a signed integer taken from the most significant byte to the least significant byte, and the bottom d bytes are after the decimal point.

Strings. Strings shorter than 16 bytes, say w bytes, can be transmitted with a prefixing token:

          	0220 + w  | <string>

Other strings must use a prefixing token followed by a variable length string length, and then followed by the string itself:

           	0240 + l | <length>  | <string>

where l+1 is the number of bytes needed to specify the length of the string, 0 <= l <= 3. The string length is an unsigned value and is transmitted from most significant byte to least significant byte. Unlike unencoded strings, there are no escape or special characters in an encoded string.

Defining strings. For strings that are to be transmitted repeatedly, a string token can be defined with:

          	0315 + w | <token> | <string>

where w+1 is the number of bytes needed to specify the token, (1 or 2), and the string being defined is transmitted in an encoded or unencoded form. The token is an unsigned value and is transmitted from most significant byte to least significant byte. For efficiency, the range of tokens defined should be as compact as possible.

Referencing defined strings. To interpolate a string that has previously been defined (as described above), the following is used:

          	0317 + w | <token>

where the token refers to the string to be interpolated.

Floating-point values. Floating-point values are transmitted in single-precision or double-precision IEEE format from most significant byte to least significant byte. Single-precision floating-point values occupy four bytes in the input stream and double-precision values occupy eight bytes.

Floating point arrays. Aggregates of single-precision floating-point values can be transmitted with a prefixing token byte. Variable sized arrays are transmitted as a token byte followed by a variable length array size, and then followed by the array itself:

          	0310 + l | <length> | <array of floats>

The array length is an unsigned value, l+1 bytes long, and is transmitted from most significant byte to least significant byte.

Defining RI requests. Before an encoded request can be used, it must first be bound to its ASCII equivalent with:

          	0314 | <code> | <string>

where the code is one byte and string is the ASCII form of the request.

Referencing defined RI requests. A previously defined RI request is referenced with two bytes; a prefixing token, 0246, followed by a request code.

          	0246 | <code>

This means that no more than 256 RI requests can be directly encoded in the binary protocol.

Example. Consider the following sequence of RIB commands:

          	version 3.03
          	ErrorHandler "print"
          	Display "test.25.pic" "file" "rgba"
          	Format 512 307 1
          	Clipping 0.1 10000
          	WorldBegin
          	Declare "direction" "point"
          	LightSource "windowlight" 0 "direction" [1 0 -0.1]
          	Color [1 1 1]
          	Orientation "lh"
          	Sides 1
          	AttributeBegin
          	MotionBegin [0 1]
          	Translate 1.91851 0.213234 1.55
          	Sphere 2 -0.3 1.95 175
          	MotionEnd
          	AttributeEnd

This could translate into the encoded sequence of bytes shown in Figure C1.

Version Number

The RIB stream supports a special version request that is used internally to ensure that the syntax of the stream is compatible with the parser being used.

version num

Specifies the protocol version number of the RIB stream. The stream specified in this document is version 3.03. A RIB parser may refuse to parse streams with incompatible version numbers.

Error handling

There are two types of errors that may be encountered while processing a RIB input stream: syntactic errors and semantic errors. Syntactic errors occur when the stream of tokens fails to form a syntactically legal statement or request. For example, a syntactic error occurs when a required parameter is missing, or when a string is left unterminated. Semantic errors occur when a syntactically legal statement contains incorrect data; e.g., when a parameter that must be non-negative is specified to be -1.

RIB defines a number of syntactic errors and a limited number of semantic errors. In theory RIB should be responsible only for syntactic errors. However, due to the weak typing of programming languages such as C, semantic errors that can not be easily recognized within the RenderMan Interface software are checked at the RIB level. For example, RIB checks arrays that are to be converted to matrices to be sure they have 16 values.

Table C2 shows the set of errors recognized by RIB. Detailed descriptions of the errors are given below.

All errors encountered by a RIB interpreter require some associated action to be performed. In the case of syntax errors, if input processing is to be continued, the input scanner must resynchronize itself with the input stream. This synchronization is done by reading and discarding tokens from the input stream until a valid RIB request token is encountered. That is, any tokens between the point of the syntax error and the next request token are discarded. The protocol has been designed so that no more than one request (along with any associated parameters) must be discarded when recovering from an error.

Errors are handled in one of three ways:

• They are ignored and the rendering process will proceed to its completion no matter what input stream is provided.
• They cause diagnostic messages to be generated on the renderer's standard error stream, but they are otherwise ignored (the default).
• The first error causes a diagnostic message to be generated and the renderer terminates immediately without creating an image.

Figure C1 Example encoded RIB byte stream

v	e	r	s	i	o	n	212	# version
003	007	256	E	r	r	o	r	# 3.03 Error
H	a	n	d	l	e	r	225	# Handler "
p	r	i	n	t	D	i	s	# print" Dis
p	l	a	y	315	\0	233	t	# play <defstr 0 "t
e	s	t	.	2	5	.	p	# est.25.p
i	c	317	\0	315	001	224	f	# ic"> <str 0> <defstr 1 "f
i	l	e	317	001	315	002	224	# ile"> <str 1> <defstr 2 "
r	g	b	a	317	002	F	o	# rgba"> <str 2> Fo
r	m	a	t	201	002	\0	201	# rmat 512
001	3	200	001	C	l	i	p	# 307 1 Clip
p	i	n	g	211	031	231	201	# ping 0.1
'	020	314	272	232	W	o	r	# 10000 <defreq 0272 "Wor
l	d	B	e	g	i	n	246	# ldBegin"> <req
272	314	207	227	D	e	c	l	# 0272> <defreq 0207 "Decl
a	r	e	246	207	315	003	231	# are"> <req 0207> <defstr 3 "
d	i	r	e	c	t	i	o	# directio
n	317	003	315	004	225	p	o	# n"> <str 3> <defstr 4 "po
i	n	t	317	004	314	224	233	# int"> <str 4> <defreq 0224 "
L	i	g	h	t	S	o	u	# LightSou
r	c	e	246	224	315	005	233	# rce"> <req 0224> <defstr 5 "
w	i	n	d	o	w	l	i	# windowli
g	h	t	317	005	200	001	317	# ght"> <str 5> 1 <str
003	310	003	?	200	\0	\0	\0	# 3> [1
\0	\0	\0	275	314	314	315	314	# 0 -0.1] <defreq
203	225	C	o	l	o	r	246	# 0203 "Color"> <req
203	310	003	?	200	\0	\0	?	# 0203> [1
200	\0	\0	?	200	\0	\0	314	# 1 1] <defreq
237	233	O	r	i	e	n	t	# 0237 "Orient
a	t	i	o	n	246	237	315	# ation"> <req 0237> <defstr
006	222	l	h	317	006	314	254	# 6 "lh"> <str 6> <defreq 0254
225	S	i	d	e	s	246	254	# "Sides"> <req 0254>
200	001	314	177	236	A	t	t	# 1 <defreq 0177 "Att
r	i	b	u	t	e	B	e	# ributeBe
g	i	n	246	177	314	227	233	# gin"> <req 0177> <defreq 0227 "
M	o	t	i	o	n	B	e	# MotionBe
g	i	n	246	227	310	002	\0	# gin"> <req 0227> [
\0	\0	\0	?	200	\0	\0	314	# 0 1] <defreq
270	231	T	r	a	n	s	l	# 0270 "Transl
a	t	e	246	270	212	001	353	# ate"> <req 0270> 1.91851
#	211	6	226	212	001	214	314	# 0.213234 1.55
314	260	226	S	p	h	e	r	# <defreq 0260 "Spher
e	246	260	200	002	211	263	4	# e"> <req 0260> 2 -0.3
212	001	363	3	201	\0	257	314	# 1.95 1.75 <defreq
230	231	M	o	t	i	o	n	# 0230 "Motion
E	n	d	246	230	314	200	234	# End"> <req 0230> <defreq 0200 "
A	t	t	r	i	b	u	t	# Attribut
e	E	n	d	246	200			# eEnd"> <req 0200>

Table C2 RIB Errors

If the RIB interpreter is acting as a network server, in direct communication with a client application, the interpreter may send parsing error signals back to the client. These signals take the form of the following RIB requests, though they are not valid in the client-to-server stream. None of these error requests have arguments. Note that some errors may not be recognized immediately by a RIB interpreter upon parsing a request. This may be due to buffering or queuing built into the interface between the intepreter and the renderer. In a client-server environment this may have implications for the client application.

arraytoobig

The interpreter was unable to allocate sufficient memory to store an array specified in the input stream. This error is dependent on the interpreter's implementation. Good implementations of a RIB interpreter support arrays as large as memory will permit.

badargument

The RIB interpreter encountered an invalid parameter value in parsing a request.

EXAMPLE

	Polygon "N" [...]			# no "P" specified
	PointsGeneralPolygons [2 2] [4 3 4]...	# bad nloops 

badarray

The number of items in an array is inappropriate for the specified parameter, or an array has both string and number elements.

EXAMPLE

	Basis [0 1 2 3] Cone [1.5] Bound [0 1 0 "oops"] 

badbasis

The basis matrix name specified in a basis request is not known by the RIB interpreter.

EXAMPLE

	Basis "my-favorite-basis" 

badcolor

An invalid color was supplied as a parameter to a request. That is, an array was specified with an incorrect number of elements.

EXAMPLE

 Opacity [.5 1]		# with 3-channel colors 

badhandle

An invalid light or object handle was supplied as a parameter to an Illuminate, ObjectInstance, LightSource, AreaLightSource, or ObjectBegin request. For Illuminate, the light handle must be an integer value specified in a previous LightSource or AreaLightSource request. For ObjectInstance, the object handle must be an integer value specified in a previous ObjectBegin request. For LightSource, AreaLightSource, and ObjectBegin this error is raised if the number specified for a light handle is significantly larger than any previous handle; for example, specifying 3000 when the largest previous handle was 10 (this is used as a ãsanity checkä to guard against corrupted input data.)

EXAMPLE

	LightSource "finite" 1
	lluminate 99999

badparamlist

badparamlist In a token-value pair of a parameter list, the type of a value did not agree with the declared type of the token.

EXAMPLE

	Declare "gridsize" "uniform float[2]"
	Option "limits" "gridsize" "not a number" 

badripcode

A binary encoded token that specified a RIB request used an undefined request code. Request codes must be defined, prior to their use, with the binary encoding protocol; see the section on Binary Encoding.

badstringtoken

A binary encoded string token referenced a string that had not previously been defined. The binary encoding scheme is described in Binary encoding.

badtoken

A byte with the most significant bit set was not recognized as a valid binary encoding. The binary encoding scheme is described in Binary encoding.

EXAMPLE

	\300 

badversion

The RIB protocol version number specified in a version request was greater than the protocol version number of the interpreter.

SEE ALSO

	version

limitcheck

An internal limit was encountered during normal operation of the interpreter. Implementers of RIB interpreters are expected to avoid imposing arbitrary limits. Some implementations may, however, need to limit the maximum size of strings, arrays, etc. due to memory constraints.

outofmemory

The interpreter ran out of memory in the normal course of operation. Interpreters are expected to utilize whatever memory is available in their operating environment. If only a limited amount of memory is present on the machine they are operating on, they may restrict their use. If memory is arbitrarily limited, however, running out of space should result in a limitcheck error, not outofmemory.

protocolbotch

A protocol error was encountered while parsing binary encoded data in the input stream. In particular, when defining a string or request code, an expected string was not encountered. The binary encoding scheme is described in Binary encoding.

stringtoobig

The interpreter ran out of space while parsing a string. This error is a specific instance of the outofmemory error.

SEE ALSO

	outofmemory, limitcheck

syntaxerror

The interpreter recognized a syntax error of indeterminate nature. Syntax errors can occur from unterminated strings or invalid numbers.

EXAMPLE

	"this is an unterminated string
	01a3	# invalid integer 

unregistered

The interpreter encountered a name token that was not a valid request. This is usually due to misspelling a request name, or not enclosing a string in quote marks (").

EXAMPLE

	Basis power