...
The graphics state also maintains the interface mode. The different modes of the interface are entered and exited by matching Begin-End command sequences.
...
RiBegin ( RtToken name )
RiEnd ( void )
...
RiEnd terminates the active rendering context, including performing any cleanup operations that need to be done. After RiEnd` is called, there is no active rendering context until another RiBegin or RiContext is called. All other RenderMan Interface procedures must be called within an active context (the only exceptions are RiErrorHandler, RiOption, and RiContext).
...
RtContextHandle RiGetContext ( void )
RiContext ( RtContextHandle handle )
...
Note that only RIB contexts may be created by calling RiBegin(), with the filename for that RIB being the name supplied to RiBegin(). An immediate rendering context cannot be created, save for the one already created for you by the renderer. Thus, the primary purpose of the RiContext call in PRMan is to create RIB files from within a procedural DSO. It is important in this case to always call RiGetContext() at the beginning of the DSO, and then restore the context to its previous value using RiContext() at the end if you create or set any contexts within your DSO. The active context upon entry should always be the immediate rendering context unless you violate this recommendation.
...
RiFrameBegin ( RtInt frame )
RiFrameEnd ( void )
...
All of the information that changes from frame to frame should be inside a frame block. In this way, all of the information that is necessary to produce a single frame of an animated sequence may be extracted from a command stream by retaining only those commands within the appropriate frame block and any commands outside all of the frame blocks. This command need not be used if the application is producing a single image.
RIB BINDING
FrameBegin int
FrameEnd -
EXAMPLE
RiFrameBegin (14);
...
RiWorldBegin ()
RiWorldEnd ()
...
a database for re-rendering will be written to disk by the time RiWorldEnd returns.
RIB BINDING
WorldBegin -
WorldEnd -
EXAMPLE
RiWorldBegin ();
RiGeometry ("teapot", RI_NULL);
RiWorldEnd ();
...
The following begin-end pairs also place the interface into special modes.
RiSolidBegin () RiSolidEnd () RiMotionBegin () RiMotionEnd ()
...
RiObjectBegin ()
RiObjectEnd ()
...
Define an object master or object group definition that can be instantiated with ObjectInstance. This calls resets the graphics state so that no attributes are active. Attribute values existing at the time ObjectInstance is called will be inherited by the instance. Any attribute explicitly defined inside an ObjectBegin/ObjectEnd block will have higher precedence and will override those attributes. This is similar to behavior of ArchiveBegin/ArchiveEnd block overriding the attribute values present when using ReadArchive.
...
RiAttributeBegin ()
RiAttributeEnd ()
RiTransformBegin ()
RiTransformEnd ()
These pairs save and restore the attributes in the graphics state, and save and restore the current transformation, respectively. All begin-end pairs (except RiTransformBegin-RiTransformEnd andRiMotionBegin-RiMotionEnd) implicitly save and restore attributes. Begin-End blocks of the various types may be nested to any depth, subject to their individual restrictions, but it is never legal for the blocks to overlap.
...
RtToken
RiDeclare (char *name, char *declaration)
...
RiDeclare also installs name into the set of known tokens and returns a constant token that can be used to indicate that variable. This constant token will generally have the same efficient parsing properties as the RI_ versions of the predefined tokens.
RIB BINDING
Declare name declaration
EXAMPLE
RiDeclare ( "Np", "uniform point" );
RiDeclare ( "Cs", "varying color" );
Declare "st" "varying float[2]"
...
The following three transformation commands set or concatenate a 4x4 matrix onto the current transformation:
...
RiIdentity ()
Set the current transformation to the identity.
RIB BINDING
Identity -
EXAMPLE
RiIdentity ( );
...
RiTransform ( RtMatrix transform )
Set the current transformation to the transformation transform.
RIB BINDING
Transform transform
EXAMPLE
Transform [.5 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1]
...
RiConcatTransform ( RtMatrix transform )
Concatenate the transformation transform onto the current transformation. The transformation is applied before all previously applied transformations, that is, before the current transformation.
RIB BINDING
ConcatTransform transform
EXAMPLE
RtMatrix foo = { 2.0, 0.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0,
0.0, 0.0, 2.0, 0.0, 0.0, 0.0, 0.0, 1.0 };
RiConcatTransform ( foo );
...
The following commands perform local concatenations of common linear transformations onto the current transformation.
...
RiPerspective ( RtFloat fov )
...
To request a perspective projection from camera space to screen space, an RiProjection request should be used; RiPerspective is used to request a perspective modeling transformation from object space to world space, or from world space to camera space.
RIB BINDING
Perspective fov
EXAMPLE
Perspective 90
...
RiTranslate ( RtFloat dx, RtFloat dy, RtFloat dz )
Concatenate a translation onto the current transformation.
RIB BINDING
Translate dx dy dz
EXAMPLE
RiTranslate (0.0, 1.0, 0.0);
...
RiRotate ( RtFloat angle, RtFloat dx, RtFloat dy, RtFloat dz )
Concatenate a rotation of angle degrees about the given axis onto the current transformation.
RIB BINDING
Rotate angle dx dy dz
EXAMPLE
RiRotate (90.0, 0.0, 1.0, 0.0);
...
RiScale ( RtFloat sx, RtFloat sy, RtFloat sz )
Concatenate a scaling onto the current transformation.
RIB BINDING
Scale sx sy sz
EXAMPLE
Scale .5 1 1
...
RiSkew ( RtFloat angle, RtFloat dx1, RtFloat dy1, RtFloat dz1,
RtFloat dx2, RtFloat dy2, RtFloat dz2 )
Concatenate a skew onto the current transformation. This operation shifts all points along lines parallel to the axis vector (dx2, dy2, dz2). Points along the axis vector (dx1, dy1, dz1) are mapped onto the vector (x, y, z), where angle specifies the angle (in degrees) between the vectors (dx1, dy1, dz1) and (x, y, z), The two axes are not required to be perpendicular, however it is an error to specify an angle that is greater than or equal to the angle between them. A negative angle can be specified, but it must be greater than 180 degrees minus the angle between the two axes.
RIB BINDING
Skew angle dx1 dy1 dz1 dx2 dy2 dz2
Skew [angle dx1 dy1 dz1 dx2 dy2 dz2]
EXAMPLE
RiSkew (45.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0);
...
Shaders often need to perform calculations in non-standard coordinate systems. The coordinate systems with predefined names are: "raster," "screen," "camera," "world," and "object." At any time, the current coordinate system can be marked for future reference.
RiCoordinateSystem ( RtToken space )
This function marks the coordinate system defined by the current transformation with the name space and saves it. This coordinate system can then be referred to by name in subsequent shaders, or in RiTransformPoints. A shader cannot refer to a coordinate system that has not already been named. The list of named coordinate systems is global.
RIB BINDING
CoordinateSystem space
EXAMPLE
CoordinateSystem "lamptop"
...
RiScopedCoordinateSystem ( RtToken name )
Like RiCoordinateSystem, this function marks the coordinate system defined by the current transformation with the indicated name and saves it. Unlike that call, the marked transformation is saved on a separate stack, independent of the global list maintained by RiCoordinateSystem. This stack is pushed and popped by RiAttributeBegin andRiAttributeEnd calls (but not by RiTransformBegin and RiTransformEnd). Scoped coordinate system can then be referred to by name in subsequent shaders, or in RiTransformPoints and RiCoordSysTransform, just like global coordinate systems. When searching for a named coordinate system, a renderer should first check the scoped coordinate system stack; failing that, the global coordinate system list should be checked.
RIB BINDING
ScopedCoordinateSystem space
EXAMPLE
ScopedCoordinateSystem "lamptop"
...
RiCoordSysTransform ( RtToken name )
This function replaces the current transformation matrix with the matrix that forms the coordinate system. This permits objects to be placed directly into special or user-defined coordinate systems by their names.
RIB BINDING
CoordSysTransform name
EXAMPLE
CoordSysTransform "lamptop"
...
RtPoint *
RiTransformPoints ( RtToken fromspace, RtToken tospace,
RtInt n, RtPoint points )
This procedure transforms the array of points from the coordinate system fromspace to the coordinate system tospace. This array contains n points. If the transformation is successful, the array points is returned. If the transformation cannot be computed for any reason (e.g., one of the space names is unknown or the transformation requires the inversion of a noninvertable transformation), NULL is returned.
EXAMPLE
RtPoint four_points[4];
RiTransformPoints ("current," "lamptop," 4, four_points);
...
Transformations can be saved and restored recursively. Note that pushing and popping the attributes also pushes and pops the current transformation.
RiTransformBegin ()
RiTransformEnd ()
Push and pop the current transformation. Pushing and popping must be properly nested with respect to the various begin-end constructs.
RIB BINDING
TransformBegin -
TransformEnd -
EXAMPLE
RiTransformBegin ();
...
Motion
...
Moving geometry is created by bracketing the definitions at different times between RiMotionBegin and RiMotionEnd calls.
RiMotionBegin ( RtInt n, RtFloat t0, RtFloat t1,..., RtFloat tnminus1 )
RiMotionEnd ()
...
RiMotionEnd terminates the definition of the moving primitive.
RIB BINDING
MotionBegin [ t0 t1... tn-1 ]
MotionEnd -
...
Resources generally encapsulate some part of the graphics state, or other information specific to the renderer such as a in-memory RIB archive. Resources are always named and have a type associated with them. Resources are unique in that they can exist outside the rest of the graphics state, and are thus not subject to standard scoping rules; instead, they have their own scoping block mechanism. An example of a resource is the ability to save the entirety of the current attribute state, and restore it at a future point, independent of the current attribute stack.
RiResource ( RtToken handle, RtToken type, ...)
...
A named resource type which is recommended for all implementations of the RenderMan Interface is the encapsulation of the entirety of the current attribute state. This resource is selected by specifying "attributes" for the type. In this case, the parameter list must contain at least the parameter "string operation" which takes a value of "save" (in order to create the saved attribute state with the given handle) or "restore" (to restore a previously saved attribute state). Furthermore, when restoring the state, a further optional parameter is accepted: "string subset", which specifies the subset of the saved attribute state to restore. (i.e. "shading", "transform", or "all").
RIB BINDING
Resource handle type
EXAMPLE
...
Resources can be explicitly saved and restored with the following commands:
RiResourceBegin ()
RiResourceEnd ()
Push and pop the current set of resources. Resources defined (named) in the current ResourceBegin scope will cease to exist at ResourceEnd. If a resource is defined outside any ResourceBegin/End scope, that resource is deemed to be global and will persist indefinitely, or at least until FrameEnd depending on the nature of the resource. Otherwise, pushing and popping of resources must be properly nested with respect to various Begin-End constructs.
RIB BINDING
ResourceBegin -
ResourceEnd -
...