Appendix
C - Language Binding DetailsAppendix
C - Language Binding DetailsThe 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 int RtInt;
typedef float RtFloat;
typedef char *RtToken;
typedef RtFloat RtColor[3];
typedef RtFloat RtPoint[3];
typedef RtFloat RtVector[3];
typedef RtFloat RtNormal[3];
typedef RtFloat Hpoint[4];
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 (*RtErrorHandler)(RtInt, RtInt, char *);
typedef RtVoid (*RtProcSubdivFunc)(RtPointer, RtFloat);
typedef RtVoid (*RtProcFreeFunc)(RtPointer);
typedef RtVoid (*RtArchiveCallback)(RtToken, char *, ...);
typedef RtPointer RtObjectHandle;
typedef RtPointer RtLightHandle;
typedef RtPointer RtContextHandle;
typedef RtPointer RtArchiveHandle;
/* 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(),
RiFrameBegin(RtInt frame),
RiFrameEnd(),
RiWorldBegin(),
RiWorldEnd();
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),
RiClippingPlane(RtFloat Nx, RtFloat Ny, RtFloat Nz, RtFloat Px,
RtFloat Py, RtFloat Pz),
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(),
RiAttributeEnd(),
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),
RiDisplacement(RtToken name, ...),
RiDisplacementV(RtToken name,RtInt n,RtToken tokens[],RtPointer
parms[]),
RiCoordinateSystem(RtToken space),
RiCoordSysTransform(RtToken space);
extern RtPoint *
RiTransformPoints(RtToken fromspace, RtToken tospace, RtInt n,
RtPoint points[]);
extern RtVoid
RiTransformBegin(),
RiTransformEnd();
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
RiBlobby(RtInt nleaf, RtInt ncode, RtInt code[],
RtInt nflt, RtFloat flt[],
RtInt nstr, RtToken str[], ...),
RiBlobbyV(RtInt nleaf, RtInt ncode, RtInt code[],
RtInt nflt, RtFloat flt[],
RtInt nstr, RtToken str[],
RtInt n, RtToken tokens[], RtPointer parms[] ),
RiCurves(RtToken type, RtInt ncurves,
RtInt nvertices[], RtToken wrap, ...);
RiCurvesV(RtToken type, RtInt ncurves,
RtInt nvertices[], RtToken wrap,
RtInt n, RtToken tokens[], RtPointer parms[] ),
RiPoints(RtInt nverts, ...),
RiPointsV(RtInt nverts,
RtInt n, RtToken tokens[], RtPointer parms[] ),
RiSubdivisionMesh(RtToken mask, RtInt nf, RtInt nverts[],
RtInt verts[],
RtInt ntags, RtToken tags[], RtInt numargs[],
RtInt intargs[], RtFloat floatargs[], ...),
RiSubdivisionMeshV(RtToken mask, RtInt nf, RtInt nverts[],
RtInt verts[],
RtInt ntags, RtToken tags[], RtInt numargs[],
RtInt intargs[], RtFloat floatargs[],
RtInt n, RtToken tokens[], RtPointer parms[] );
extern RtVoid
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() ;
extern RtObjectHandle
RiObjectBegin();
extern RtVoid
RiObjectEnd(),
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[]),
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
RiArchiveRecord(RtToken type, char *format, ...),
RiReadArchive(RtToken name, RtArchiveCallback callback, ...),
RiReadArchiveV(RtToken name, RtArchiveCallback callback,
RtInt n, RtToken tokens[], RtPointer parms[]);
extern RtArchiveHandle
RiArchiveBegin(RtToken name, ....);
extern RtVoid RiArchiveEnd(); extern RtVoid RiIfBegin(RtToken), RiIfEnd(), RiElseIf(RtToken ), RiElse(); extern RtVoid RiErrorHandler(RtErrorHandle handler); extern RtVoid RiDisplayChannel(RtToken channel, ...), RiDisplayChannelV(RtToken channel, RtInt n, RtToken tokens[], RtPointer parms[]); /* 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_DISKFULL ((RtInt)6) /* Target disk is full */ #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 */
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
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.
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.
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.
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 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.
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.
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.
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.
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.
| Values | Span | Interpreted as... |
|---|---|---|
| 0-0177 | 128 | ASCII characters |
| 0200-0217 | 16 | encoded integers and fixed-point numbers |
| 0220-0237 | 16 | encoded strings of no more than 15 characters |
| 0240-0243 | 4 | encoded strings longer than 15 characters |
| 0244 | 1 | encoded single precision IEEE floating point value |
| 0245 | 1 | encoded double precision IEEE floating point value |
| 0246 | 1 | encoded RI request |
| 0247-0307 | 32 | nothing (reserved) |
| 0310-0313 | 4 | encoded single precision array (length follows) |
| 0314 | 1 | define encoded request |
| 0315-0316 | 2 | define encoded string token |
| 0317-0320 | 2 | interpolate defined string |
| 0321-0377 | 46 | nothing (reserved) |
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.
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 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:
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
| Name | Description |
|---|---|
| arraytoobig | insufficient memory to construct array |
| badargument | incorrect parameter value |
| badarray | invalid array specification |
| badbasis | undefined basis matrix name |
| badcolor | invalid color specification |
| badhandle | invalid light or object handle |
| badparamlist | parameter list type mismatch |
| badripcode | invalid encoded RIB request code |
| badstringtoken | undefined encoded string token |
| badtoken | invalid binary token |
| badversion | protocol version number mismatch |
| limitcheck | overflowing an internal limit |
| outofmemory | generic instance of insufficient memory |
| protocolbotch | malformed binary encoding |
| stringtoobig | insufficient memory to read string |
| syntaxerror | general syntactic error |
| unregistered | undefined RIB request |
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.
arraytoobigbadargumentEXAMPLE Polygon "N" [...] # no "P" specified PointsGeneralPolygons [2 2] [4 3 4]... # bad nloops
badarrayEXAMPLE Basis [0 1 2 3] Cone [1.5] Bound [0 1 0 "oops"]
badbasisEXAMPLE Basis "my-favorite-basis"
badcolorEXAMPLE Opacity [.5 1] # with 3-channel colors
badhandleEXAMPLE LightSource "finite" 1 lluminate 99999
badparamlistEXAMPLE Declare "gridsize" "uniform float[2]" Option "limits" "gridsize" "not a number"
badripcodebadstringtokenbadtokenEXAMPLE \300
badversionSEE ALSO
versionlimitcheckoutofmemoryprotocolbotchstringtoobigSEE ALSO
outofmemory, limitchecksyntaxerrorEXAMPLE "this is an unterminated string 01a3 # invalid integer
unregisteredEXAMPLE Basis power
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.
|
Pixar Animation Studios
|