The format of the various texture map files is implementation dependent. However, there are standard utilities that convert image files into texture map files.
During two-dimensional texture access, texture coordinates (s, t) are mapped onto the texture such that s=0 maps to xmin, s=1 maps to xmax+1, t=0 maps to ymin, and t=1 maps to ymax+1. To be precise, all accesses to the half-open interval [0,1) in s and t will lie within the picture data.
A wrapmode describes how the texture is accessed if the texture
coordinates are outside the unit square (less than zero, or greater than or
equal to one). The swrap and twrap strings specify the
wrapping behavior of the s and t coordinates. The standard
wrapping behavior for s and t, "black," is to
return the value zero for all accesses outside the unit square. (Thus an RGBa
texture will be transparent black, zero on all four channels.) The keyword "periodic"
indicates that values of s (or t) outside [0,1) will be
mapped into [0,1) by subtracting the largest integer less than or equal to the
coordinate (the ``floor'' of the coordinate). This will wrap the value 1 back to
0, the value 1.25 to 0.25, and the value -0.1 to 0.9. The result will be to
repeat the texture as a tile that fills texture space in the s (or t) direction.
The keyword "clamp" indicates that values of s
(or t) outside [0,1) will be mapped into [0,1) by clamping them
at their minimum and maximum values. All values below zero will be clamped
to zero and all values greater than or equal to one will be clamped to a
value slightly less than one (at the last texture pixel).
Textures are often prefiltered so that subsequent antialiasing calculations can be done more quickly at run-time. This is controlled by giving a filterfunc, which is the same as the filterfunc used in RiPixelFilter, and an swidth and twidth.
Surface textures are used to modify the properties of a surface, such as color and opacity. A surface texture consists of one or more channels. A single channel or a group of n channels (usually an RGB color) can be accessed using the texture function of the Shading Language. The texture function requires the name of a texture file containing the texture.
RiMakeTexture( picturename, texturename, swrap, twrap,
filterfunc, swidth, twidth, parameterlist )
char *picturename;
char *texturename;
RtToken swrap, twrap;
RtFloatFunc filterfunc;
RtFloat swidth, twidth;
Convert an image in a standard picture file whose name is picturename into a texture file whose name is texturename. All channels of the picture file will be converted (in order) to texture channels. The storage format of the texture file and the precision of stored texture channels are implementation-dependent.
The picture file used as input is not changed or otherwise affected by RiMakeTexture.
RIB BINDING
MakeTexture picturename texturename swrap twrap filter swidth twidth
parameterlist
The filter parameter should be one of "box," "triangle," "catmull-rom," "b-spline," "gaussian" and "sinc." These correspond to the predefined filter functions described in RiPixelFilter.
EXAMPLE
RiMakeTexture("globe.pic," "globe.tx," "periodic," "clamp,"
RiGaussianFilter, 2.0, 2.0, RI_NULL);
Bump maps are used to perturb surface normals to simulate a bumpy surface without actually moving the points on the surface. A bump map is accessed using the surface texture coordinates. A bump map image consists of one channel of data which indicates the relative displacement of the surface. A bump map texture can be accessed using the bump function of the Shading Language. The bump function requires the name of a texture file containing the texture.
RiMakeBump( picturename, texturename, swrap, twrap,
filterfunc, swidth, twidth, parameterlist )
char *picturename;
char *texturename;
RtToken swrap, twrap;
RtFloatFunc filterfunc;
RtFloat swidth, twidth;
Convert a height field image in a standard picture file whose name is picturename into a bump map file whose name is texturename. The storage format of the texture file and the precision of stored texture channels are implementation-dependent.
The picture file used as input is not changed or otherwise affected by RiMakeBump.
RIB BINDING
MakeBump picturename texturename swrap twrap filter swidth twidth
parameterlist
The filter parameter should be one of "box," "triangle," "catmull-rom," "b-spline," "gaussian" and "sinc." These correspond to the predefined filter functions described with RiPixelFilter.
EXAMPLE
Bump "hills.pic" "hills.tx" "periodic" "clamp" "catmull-rom" 3 3
Environment maps are images representing the color of an environment in a particular direction. An environment map is accessed using a point representing direction; this direction is often the direction of a mirror reflection and hence environment maps are often referred to as reflection maps. However, any direction can be computed by a user-defined shader. An environment map image consists of one or more channels. A single channel or a group of n channels (usually an RGB color) can be accessed using the environment function in the Shading Language. Environment maps can be input in two formats. The first is as a single latitude-longitude image. Environment maps in this form are fairly easy to create using a paint system. The second format is a set of six cube face projections. Environment maps in this form are naturally created by the rendering program.
RiMakeLatLongEnvironment( picturename, texturename,
filterfunc, swidth, twidth, parameterlist );
char *picturename:
char *texturename:
RtFloatFunc filterfunc;
RtFloat swidth, twidth
Convert an image in a standard picture file representing a latitude-longitude map whose name is picturename into an environment map whose name is texturename. The storage format of the texture file and the precision of stored texture channels are implementation-dependent.
This image has longitude equal to 0 degrees at the left, and 360 degrees at the right. The latitude at the bottom is -90 degrees and at the top is 90 degrees. The bottom of the picture is at the south pole and the top the north pole. The direction in space corresponding to each of the points on the image is given by:
RIB BINDING
MakeLatLongEnvironment picturename texturename filter swidth twidth
parameterlist
The filter parameter should be one of "box," "triangle," "catmull-rom," "b-spline," "gaussian" and "sinc." These correspond to the predefined filter functions described with RiPixelFilter.
EXAMPLE
MakeLatLongEnvironment "long.pic" "long.tx""catmull-rom" 3 3
RiMakeCubeFaceEnvironment( px, nx, py, ny, pz, nz, texturename, fov,
filterfunc, swidth, twidth, parameterlist );
char *px, *nx, *py, *ny, *pz, *nz;
char *texturefile;
RtFloat fov;
RtFloatFunc filterfunc;
RtFloat swidth, twidth;
Convert six images in standard picture files representing six viewing directions into an environment map whose name is texturename. The image pz (nz) is the image as viewed in the positive (negative) z direction. The remaining images are those viewed along the positive and negative x and y directions. The storage format of the texture file and the precision of stored texture channels are implementation-dependent.
Each image is normally produced by a rendering program by placing the eye at the center of the environment (usually the origin) and generating a picture in each of the six directions. These pictures are the projection of the environment onto a set of cube faces. Each face is usually assumed to be unit distance from the eye point. Cube face environment maps should be generated with the following orientations:
| Image | Forward Axis | Up Axis | Right Axis |
|---|---|---|---|
| px | +X | +Y | -Z |
| nx | -X | +Y | +Z |
| py | +Y | -Z | +X |
| ny | -Y | +Z | +X |
| pz | +Z | +Y | +X |
| nz | -Z | +Y | -X |
Notice that cube face environment maps are sensitive to the handedness of the coordinate system in which they will be accessed. Environment maps which are intended to be accessed in a right-handed coordinate system will, if displayed, appear as a mirror image of those intended to be accessed in a left-handed coordinate system.
The fov is the full horizontal field of view used to generate these images. A value of 90 degrees will cause the cube face edges to meet exactly. Using a slightly larger value will cause the cube faces to intersect. Having a slight overlap helps remove artifacts along the seams where the different pictures are joined.
RIB BINDING
MakeCubeFaceEnvironment px nx py ny pz nz texturename fov filter
swidth twidth parameterlist
The filter parameter should be one of "box," "triangle," "catmull-rom," "b-spline," "gaussian" and "sinc." These correspond to the predefined filter functions described with RiPixelFilter.
EXAMPLE
RiMakeCubeFaceEnvironment("foo.x," "foo.nx," "foo.y," "foo.ny,"
"foo.z," "foo.nz," "foo.env," 95.0, RiTriangleFilter,
2.0, 2.0, RI_NULL);
Shadow maps are depth buffer images from a particular view. They are generally used in light source shaders to cast shadows onto objects. A shadow map is accessed by point in the camera coordinate system corresponding to that view. This point must be computed in the shader. A shadow map texture can be accessed using the shadow function of the Shading Language. The shadow function requires the name of a texture file containing the texture.
RiMakeShadow( picturename, texturename, parameterlist )
char *picturename;
char *texturename;
Create a depth image file named picturename into a shadow map whose name is texturename. The storage format of the shadow map texture file and the precision of stored texture channels are implementation-dependent.
RIB BINDING
MakeShadow picturename texturename parameterlist
EXAMPLE
MakeShadow "shadow.pic" "shadow.tex"
RenderMan Interface procedures do not return error status codes. Instead, the user may specify an error handling routine that will be called whenever an error is encountered.
RiErrorHandler( handler )
RtFunc handler;
This procedure sets the error handling procedure invoked by the renderer when an error is detected. Error handling procedures have the following form:
RtVoid handler( code, severity, message )
RtInt code, severity;
char *message;
code indicates the type of error, and severity indicates how serious the error is. Values for code and severity are defined in <ri.h>. The message is a character string containing an error message formatted by the renderer which can be printed or displayed, as the handler desires.
The following standard error handlers are defined:
RtVoid RiErrorIgnore;
RtVoid RiErrorPrint;
RtVoid RiErrorAbort;
RtInt RiLastError;
If RiErrorIgnore is specified, all errors are ignored and no diagnostic messages are generated. If RiErrorPrint is specified, a diagnostic message is generated for each error. The rendering system will attempt to ignore the erroneous information and continue rendering. If RiErrorAbort is specified, the first error will cause a diagnostic message to be generated and the rendering system will immediately terminate. Each of the standard error handlers saves the last error code in the global variable RiLastError. This procedure can be called outside an RiBegin-RiEnd block.
RIB BINDING
ErrorHandler "ignore"
ErrorHandler "print"
ErrorHandler "abort"
If "ignore," "print" or "abort"
is specified, the equivalent predefined error handling procedure will be
invoked in the RIB server. Notice that the RIB parser process may detect
RIB stream syntax errors which make it impossible to correctly parse a
request. In this case, the error procedure will be invoked and the parser
will do its best to resynchronize the input stream by scanning for the next
recognizable token.
EXAMPLE
ErrorHandler "ignore"
One important use of the RIB protocol is to store a scene description in an archive file for rendering at a later time or in a remote location from the modeling application.
RiArchiveRecord( type, format [, arg ...] )
RtToken type
char *format;
This call writes a user data record (data which is outside the scope of the
requests described in the rest of Part I of this document) into a RIB archive
file or stream. type is either "comment" or "structure". "comment"
begins the user data record with a RIB comment marker and terminates it
with a newline. "structure" begins the user data record with
a RIB structuring convention preface and terminates it with a newline. The user
data record itself is supplied as a printf() format string with
optional arguments. It is an error to embed newline characters in the
format or any of its string arguments.
Copyright - Sudhir R Kaushik (sudhir@cs.wpi.edu)