Functions For Reading RIB Files

(Last Updated 4-25-98)

The functions listed here provide a set of tools for reading RIB and RIB-like files. There is only a small set of functions that a person using the Affine Toolkit needs to become familiar with. This small set of functions rely on the remaining set of functions shown in the alphabetical list below. To help skip over some of the lower level functions refer to the Quick Reference List below to get some pointers to the most commonly used functions.

Quick Reference List to Commonly Used Rib Functions

RibOpen() -- Prepare to read a RIB file.
RibRead() -- Read a RIB file.
RibClose() -- Free resources and close RIB file.
RibBegin() -- Allow an output filename to be given.
RibOption() -- Set options for the output file.
RibGetUserParameters() -- Sort through a vector form of a parameter list for certain token names.
RibKeepData() -- Tells the RIB Reader not to free up data given to a RI call.
RibMalloc() -- Allocate a memory block.
RibFree() -- Deallocate a memory block.
RibFreeVectorData() -- Deallocate data in the parameter list of token/param pairs.
RibQueryKeepData() -- Returns nonzero value if pointers given in present Ri call point to memory areas that should not be freed.
RibSetRITable() -- Associates a table of Ri calls to a RIB handle.

Alphabetical Listing of Rib Functions

PRIB_HASHATOM RibAddItem( RIB_HASHHND hash, RIB_UINT32 type, ... )

Adds an item to the hash table hash given the item's type and data. The data is given in a variable argument list in a format dependent on the value type.

Refer to Hash Item Types for the parameters that are used for the "..." in RibAddItem().

To get a hash table handle from a RIB handle refer to RibGetHashHandle().

A hash atom can be one of the following types:

     kRIB_HASH_RIREQUESTCODE
     kRIB_HASH_LIGHTHANDLE
     kRIB_HASH_OBJECTHANDLE
     kRIB_HASH_STRINGTOKEN
     kRIB_HASH_STRING
     kRIB_HASH_VARIABLE
     kRIB_HASH_COORDSYS
     kRIB_HASH_USER

Values assigned to type that are from kRIB_HASH_USER upto kRIB_HASH_TYPEMASK & (kRIB_HASH_USER + n) inclusively can be used to store data in a format specific to the tool using the hash library. Refer to User Hash Item Types for placing user data into a hash table.

Two flags kRIB_HASH_FREEDATA and kRIB_HASH_FREEEXTDATA can be ORed into the value given to type to indicate to RibDestroyHashTable() what data can be freed. By default the data referred to by a hash item is not freed without the appropriate flags set.

The pointers given to RibAddItem() are used in the hash table and can not be freed until the item is removed from the hash table or the hash table is destroyed with RibDestroyHashTable().

int RibBegin( RIB_HANDLE rib, RtToken name )

Note that RibBegin() has the Prefix Rib, not simply Ri.

The RenderMan Interface has a function RiBegin() that takes a filename indicating where the output is to be written. If the value is RI_NULL, then standard output is used.

To allow the output filename to be specified, the RIB Reader library provides RibBegin() to allow a RiBegin-like function listed in the RI table at position kRIB_BEGIN to be called with the parameter name. Once RibBegin() has been called the string name can be freed.

To prevent multiple RiBegin() calls reaching the output library that hooks out the ritable, use RibBegin() if an output file must be specified.

RibBegin() does not have to be called unless an output filename needs to be given. RibRead() will call RibBegin() automatically. A flag is set that prevents multiple Begin/End calls reaching the output library. If you call RibBegin() a matching RibEnd() call is optional because RibClose() makes a call to RibEnd(). RibEnd() is really provided to allow the source code to have matching Begin/End calls. Although it can be used to terminate the output of a RIB file before RibRead() has completed reading the input RIB file or stream.

RibBegin() sets a status flag called kRIB_STATUS_BEGUN after the RI Table's kRIB_BEGIN function is called.

Refer to Functions For Reading RIB Files for a description of what RI Tables are and how they provide a mechanism for subclassing RI functions.

Refer to A Real Quick Overview for examples using RibBegin().

Also refer to RibEnd().

int RibBufferRead( RIB_HANDLE rib, char *buffer, unsigned int size ): Acts like fread() except that the number of bytes read is kept track of for RibGetByteOffset(). The number of lines ('\n' characters) is not accounted for.

int RibClearError( RIB_HANDLE rib )

Clears the last error encountered.

Refer to RibGetError() and RibSetError().

int RibClose( RIB_HANDLE rib )

Closes the file represented by rib and frees resources such as a hash table and any buffers used by rib. The RIB handle rib is no longer a valid handle after RibClose() is called. RibClose also calls RibEnd().

If the hash table associated with rib was created with RibCreateHashTable() and the RIB file was opened with RibOpenWithHashTable(), the hash table is treated as an external resource that needs to be freed separately from closing rib. To free a hash table use RibDestroyHashTable().

If rib was opened with the function RibOpenSubfile() then any tables and buffers used by the parent are left alone and are not freed.

Refer to A Real Quick Overview for examples using RibClose().

int RibCloseFile( RIB_HANDLE rib ): Closes the file represented by rib and does not free any buffers or tables. This function allows a tool to fclose() a file without loosing any data such as the data in the RIB's associated hash table. The RIB handle rib is still valid and can be used in subsequent Rib calls.

int RibCacheVector( RIB_HANDLE rib, RtInt n, RtToken **paTokens, RtPointer **paParams )

This function is used by RibReadParameterList() in affine/readrib/paraml.c. Most tools should not need to call this function directly.

RibCacheVector() increases the size of four arrays associated with each RIB handle so that each can hold a minimum of nparams items of data. The arrays are used for reading of token/parameter pairs that form the parameter lists of RIB statements. Two of the arrays are used to separately store the token names and a pointer to the parameter data associated with each token name. The other two of the four arrays provide information about each token/parameter pair: the type of data the token name represents and the number of items of the token type the parameter data holds.

The four arrays together are referred to as the vector cache in the Affine Toolkit source code. The name vector cache is from the token/parameter arrays used in the vector form of the RI calls. Once RibReadParameterList() has read a RIB statement's parameter list, data is stored in four arrays storing the token names, parameter data arrays, the type of each parameter data array, and the number of items in each parameter data array.

Initially when a RIB handle is created the four arrays (tokencache, paramcache, typecache, and ncache) are each given the size of kRIB_VECTORCACHEINCR (about 30) values. This size is normally large enough for most RIB statement's parameter list, but if needed these arrays can be grown by increments of kRIB_VECTORCACHEINCR.

RibCacheVector() is the function used to check if the vector cache needs to be grown. The value nparams indicates the number of additional token/parameter pairs that are going to be added. Typically the token/parameter pairs are read-in one at a time and RibCacheVector() is called with nparams equal to one to indicate one more item is being added to the vector cache.

RibGetVectorCacheInfo() is used to access the types and sizes of the token/parameter pairs. It also returns the number of vertices found in the "P", "Pw", or "Pz" arrays if present. RibGetVectorCacheInfo() and RibCacheVector() were designed for functions doing the actual reading of a RIB statement. Information such as the number of vertices found in a given positional array ("P", "Pw", or "Pz") is stored in an internal array ncache for parsing such things as a Polygon statement.

int RibCopyVectorCache( RIB_HANDLE rib, RtInt n, RtToken **paTokens, RtPointer **paParams ): Makes a copy of n items from the start of a RIB statement's token/parameter pairs based on the vector cache. The token names and parameter data are copied into two newly malloc'ed blocks of memory that can be used in the vector form of an RI call. RibCopyVectorCache() assumes that it is being called from a RI-like function hooked into rib's associated RI table.

PRIB_BUFFER RibCreateBuffer( RIB_HANDLE rib )

The RIB Reader library uses a linked list of 255 character long buffers to handle reading strings and arrays of unknown length. During RibOpen() and RibOpenWithHashTable(), RibCreateBuffer() is called to setup a structure (RIB_BUFFER) that keeps track of the linked list of 255 character buffers (RIB_BUFFERITEM).

Refer to RibDestroyBuffer().

RtFloat *RibCreateFloatArrayFromBuffer( RIB_HANDLE rib, RIB_UINT32 options )

If RibSaveToBuffer() was called to save characters retrieved by RibGetChar() into a buffer and a set of IEEE 32-bit floats has been read, RibCreateFloatArrayFromBuffer() will malloc a block of memory for the array, copy the contents of the rib's buffer into the malloc'ed memory block and return a pointer to it.

The data in the buffer is not removed and anymore characters read by RibGetChar() will be appended to the contents of the buffer until RibSaveToBuffer() or RibResetBuffer() is called.

RIB_HASHHND RibCreateHashTable( int size )

Creates a double hash table of length size and width kRIB_HASH_SECONDSIZE. To find an element in the hash table two hash functions are used. The first reduces the search to row position inclusively between 0 and size-1. The second hash function narrows the search further to a column position inclusively between 0 and kRIB_HASH_SECONDSIZE-1.

By default RibOpen() calls RibCreateHashTable() with size kRIB_HASH_TABLESIZE. The value size should be a prime number, so the hashing functions can work efficiently.

RtInt *RibCreateIntegerArrayFromBuffer( RIB_HANDLE rib, RIB_UINT32 options )

If RibSaveToBuffer() was called to save characters retrieved by RibGetChar() into a buffer and a set of 32-bit integers has been read, RibCreateIntegerArrayFromBuffer() will malloc a block of memory for the array, copy the contents of the rib's buffer into the malloc'ed memory block and return a pointer to it.

The data in the buffer is not removed and anymore characters read by RibGetChar() will be appended to the contents of the buffer until RibSaveToBuffer() or RibResetBuffer() is called.

char *RibCreateStringFromBuffer( RIB_HANDLE rib, RIB_UINT32 options )

If RibSaveToBuffer() was called to save characters retrieved by RibGetChar() into a buffer and a set of ASCII characters has been read, RibCreateStringFromBuffer() will malloc a block of memory for the array, copy the contents of the rib's buffer into the malloc'ed memory block and return a pointer to it.

Binary characters are replaced with an ASCII representation such as '\n' or an ASCII octal value '\000'.

The data in the buffer is not removed and anymore characters read by RibGetChar() will be appended to the contents of the buffer until RibSaveToBuffer() or RibResetBuffer() is called.

int RibCreateStringsFromBuffer( RIB_HANDLE rib, RtInt n, RtString **r )

Parameter lists can have arrays of strings for tokens defined as varying or vertex strings. Once the entire array of n strings has been read into rib's buffer, RibCreateStringsFromBuffer() creates a block of memory large enough for n pointers and the n NULL terminated strings. The pointers to the beginning of the strings.

One memory block is used for the array of pointers and the character strings so that a function listed in the RI table receives this data it can free it the same way all other arrays are freed by making a single call to RibFree() with the pointer to the array.

PRIB_HASHATOM RibDeclare( RIB_HANDLE rib, char *name, char *declaration )

Associates the RIB file or stream rib with a type declaration for the variable or attribute name name. Subsequent statements that are read from rib will be able to handle parameter lists using name. Refer to the RI Specification regarding RiDeclare().

RibDeclare() adds name to a hash table associated with rib. The string pointed to by name is freed when its entry in the hash table is removed by RibRemoveItem() or destroyed when RibClose() or RibDestroyHashTable() is called.

RibClose() happens to simply call RibDestroyHashTable() if the status flag kRIB_STATUS_EXTERNHASHTBL is not set. Refer to RibOpenWithHashTable() regarding the status flag kRIB_STATUS_EXTERNHASHTBL.

Because name is added to a hash table as a pointer to a string, RibDeclare() assumes that name was a malloced piece of data that is freeable.

The library libribhash.a calls RibAddItem() directly not RibDeclare(). RibDeclare() is provided for the libraries libribrdr.a, libribwrtr.a and libributil.a to use. Utilities can also use RibDeclare() to extend the standard set of attribute and variables names that may appear in a parameter list.

int RibDefaultArchiveRecordHandler( RIB_HANDLE rib )

Handles reading a hint or comment after a '#' has already been read. By default RibReadArchiveRecord() is called to read the input until a '\n' is encountered, it then calls RibCreateStringFromBuffer() to create a memory block to store the entire hint or comment, and then the function at the kRIB_ARCHIVERECORD position of rib's Ri table is called with "comment" or "structure" to identify if one or two '#' charcters prefixed the line of data.

The default behavior of RibDefaultArchiveRecordHandler() can be altered with RibSetHintTable(). If RibSetHintTable() is used to associate a hint table to rib, RibDefaultArchiveRecordHandler() will identify standard hints and call the appropriate hint function.

Refer to RibGetHintTableSize() and RibGetHintTable(). By default a RIB handle has no hint table and RibGetHintTable() will return NULL.

int RibDefaultErrorHandler( RIB_HANDLE rib, int code, int severity, PRIB_ERROR error )

Prints the standard error message indicated by the RenderMan Specification using the values code and severity. If the status flag kRIB_OPTION_ERRMSG_VERBOSE is set, a more verbose error message follows based on data given in error. By default the flag kRIB_OPTION_ERRMSG_VERBOSE is set when rib is opened. RibSetOptions() can be used to turn the verbose flag off.

Refer to RibSetErrorHandler() and RibGetErrorHandler().

int RibDefaultHintHandler( RIB_HANDLE rib )

Used as a basic function in hint tables assigned to RIB handles. The preceding '##' should have already been read and the hint name should be in rib's buffer.

RibDefaultHintHandler() reads the input until a '\n' is encountered, calls RibCreateStringFromBuffer() to create a memory block to store the entire hint, and calls the function at the kRIB_ARCHIVERECORD position of the archive table is called with "structure" as the first parameter. Once the RI Table function returns, RibDefaultHintHandler() checks for the kRIB_STATUS_KEEPDATA flag and if not there frees the string that has the hint statement.

Refer to RibGetHintTableSize(), RibGetHintTable() and RibSetHintTable().

int RibDestroyBuffer( PRIB_BUFFER pbuf ): Used by RibClose() to destroy an internal structure used to read long strings and arrays of unknown length.

int RibDestroyHashTable( RIB_HASHHND hash ): Frees all data listed in the hash table hash and then the arrays used to store the hash table itself. Once complete, hash is no longer a valid handle.

int RibDestroyHashTableKeepData( RIB_HASHHND hash ): Destroys the hash table and the hash atoms listed in the hash table, but the data pointed to by each atom is left untouched.

int RibEnd( RIB_HANDLE rib )

Note that RibEnd() has the Prefix Rib, not simply Ri.

RibEnd() sets a status flag called kRIB_STATUS_ENDED after the RI Table's kRIB_END function is called. The flag prevents RibEnd() from calling the RI Table's kRIB_END call again.

RibEnd() can be used to cleanly terminate the reading of a RIB file rib before the RIB file has been entirely read. Using RibEnd() in this manner requires that it be called from a RI function hooked in rib's RI Table. Once RibEnd() sets the status flag kRIB_STATUS_ENDED, RibRead() will return control to the tool that called it instead of reading the next available RIB statement.

Refer to RibBegin(). RibEnd() can be called from a tool using the RIB Reader library without having called a matching RibBegin(). RibRead() will call RibBegin() and RibClose() makes a call to RibEnd(). Special status flags kRIB_STATUS_BEGUN and kRIB_STATUS_ENDED prevent begin and end functions listed in the RI Table from getting multiple calls.

int RibErrorNumberOfValues( RIB_HANDLE hrib, RtToken parameterID, RtInt expected_nitems, RtInt received_nitems )

Reports an error where a token/parameter pair has an array of data of the wrong length. The token that identifies the token/parameter pair is parameterID. The values expected_nitems and received_nitems gives the number of expected and actual items respectively. Each item can be made up of any number of floats, integers or strings. For example a matrix involves 16 floats. Error messages measure in the number of floats, integers and strings and not the number of matrices or colors. RibErrorNumberOfValues() converts expected_nitems and received_nitems into values compatible with the phrasing of the error messages by finding the type associated with the parameterID in declarations stored in rib's hash table.

Refer to RibSetError().

PRIB_HASHATOM RibFindMatch( RIB_HASHHND hash, RIB_UINT32 type, int code, void *data )

Used to retrieve an item that has been added to a hash table hash. A type using one of the following constants is required:

   enum {
      kRIB_HASH_UNKNOWN,
      kRIB_HASH_RIREQUESTCODE,
      kRIB_HASH_LIGHTHANDLE,
      kRIB_HASH_OBJECTHANDLE,
      kRIB_HASH_STRINGTOKEN,
      kRIB_HASH_STRING,
      kRIB_HASH_VARIABLE,
      kRIB_HASH_COORDSYS,
      kRIB_HASH_LAST,
      kRIB_HASH_USER = 1024
   };

Values of kRIB_HASH_USER and greater only have meaning for a tool using the hash table library. When searching RibFindMatch() uses the value code as a hash value and unique ID along with type only if data is NULL. If data points to a string, the hash library will use the string to create a hash value and use strcmp() to find a match after a possible matching item's type matched.

Light and object handles are identified by a code value that represents their sequence number. Variables and coordinate systems are identified by their string names. Strings and RI requests are identified by the code given in the RIB file's binary encoding.

PRIB_HASHATOM RibFindNextMatch( RIB_HASHHND hash, PRIB_HASHATOM atom ): To allow for application specific user items in the hash table that have a type of kRIB_HASH_USER or greater, the hash table library allows for multiple user items to have matching types and codes. Each hash item has an extended field that can be given a pointer to the data making the hash item unique. A tool making use of this ability calls RibFindMatch() first, determines if there actually is a match given by looking at the extended data and if there is no match continues the search with RibFindNextMatch().

void RibFree( void *p )

Frees a memory block pointed to by p. This allows a central place for altering how the memory is freed. The Affine Toolkit source code uses a macro _RibFree() defined in affine/include/ribhash.h instead of calling RibFree() directly. This macro is used so that if a flag RIB_MEMORY_TESTS is defined, the macro will call special compiled version of RibFree() that keeps track of memory leaks.

If the Affine libraries are compiled with RIB_MEMORY_TESTS not defined, the macro _RibFree() is simply replaced with free(). This is to avoid the extra function call involved in calling RibFree() which without the memory tests simply calls free().

Refer to Rib Memory Functions for more detail on the memory handling functions.

Refer to Memory Allocations in the section More Advanced Subclassing for how pointers to memory are handled in Ri-like calls called from the RIB Reader Library.

void RibFreeBasisMatrix( void *p )

Frees a memory block pointed to by p. A check is done to see if the memory is one of the RI_ constants which can not be freed. If an RI_ constant such RiPowerBasis is given, RibFreeBasisMatrix() simply returns without error.

Refer to Rib Memory Functions for more detail on the memory handling functions.

Refer to Memory Allocations in the section More Advanced Subclassing for how pointers to memory are handled in Ri-like calls called from the RIB Reader Library.

int RibFreeVectorCache( RIB_HANDLE rib ): Internal call used to free a set of arrays that store pointers for token/parameter pairs, number of elements found and type of the parameter data.

int RibFreeVectorData( RIB_HANDLE hrib, RtInt nparms, RtToken *tokens, RtPointer *parms ): RibFreeVectorData() frees nparms of strings used by the array tokens and nparms data arrays pointed to by the array parms.

PRIB_HINTTABLE RibGetArcRecHandler( RIB_HANDLE rib ): Returns the function pointer to the archieve record handler registered with rib by the function RibSetArchiveRecordHandler().

PRIB_BUFFERITEM RibGetBufferItem( PRIB_BUFFER pBuffer )

This function is used by functions in affine/readrib/streamio.c. Most tools should not need to call this function directly.

Returns an available RIB_BUFFERITEM structure or creates a new one.

unsigned int RibGetBufferLength( RIB_HANDLE rib ): Returns the number of bytes stored in rib's buffer. This function is used when an array has been read into the buffer and a contiguous block of memory needs to be created to copy the array into.

unsigned long int RibGetByteOffset( RIB_HANDLE rib ): Returns the presnt position in the file or number of bytes read from the input stream.

int RibGetChar( RIB_HANDLE rib ): Returns the next character in a file or stream.

PRIB_HASHATOM RibGetConflictingHashAtom( RIB_HASHHND hash )

If a RibAddItem() returns NULL, an existing item matching in the hash table hash matches the item being added. RibGetConflictingHashAtom() returns a non-NULL pointer if an existing item did in fact conflict with an item being added to a hash table.

Normally the already existing hash item is then altered to match the data the new item would have provided in the hash table.

To alter an existing hash table's item, refer to the functions RibSetDefinedLightHandle(), RibSetDefinedObjectHandle(), RibSetDefinedString(), RibSetDefinedRIRequest(). RibSetHashExtendedData(), and RibSetStringAtom().

To access data in a hash table's item, use RibGetDefinedLightHandle(), RibGetDefinedObjectHandle(), RibGetDefinedString(), RibGetDefinedRIRequest(). RibGetHashExtendedData(), and RibGetStringAtom().

int RibGetDefinedRIRequest( PRIB_HASHATOM a ): The RIB binary format includes statements that associate a number to a given RIB statement name. The number is a part of an abbreviated form of the RIB statement name. If an hash table atom represents the association of a number to a RIB statement name, the number can be retrieved using RibGetDefinedRIRequest(). The atom can be found by calling RibFindMatch() given type kRIB_HASH_RIREQUESTCODE and the RIB statement name as a string.

RtLightHandle RibGetDefinedLightHandle( PRIB_HASHATOM atom )

Light sources are given ID numbers in a RIB file or stream. These ID numbers are called sequence numbers because they normally enumerate the light sources from 1 to n. The RenderMan Interface C bindings gives each light source a LightHandle to identify each light source. To show the association between a seuence number and its light source handle, the hash table stores atoms that can be found given the sequence number. RibGetDefinedLightHandle() returns the light source handle once the hash atom is found.

The correct atom can be found by calling RibFindMatch() given type kRIB_HASH_LIGHTHANDLE and the sequence number.

RtObjectHandle RibGetDefinedObjectHandle( PRIB_HASHATOM atom )

Objects are given ID numbers in a RIB file or stream. These ID numbers are called sequence numbers because they normally enumerate the objects from 1 to n. The RenderMan Interface C bindings gives each object an ObjectHandle to identify each object. To show the association between a seuence number and its object handle, the hash table stores atoms that can be found given the sequence number. RibGetDefinedObjectHandle() returns the light source handle once the hash atom is found.

The correct atom can be found by calling RibFindMatch() given type kRIB_HASH_OBJECTHANDLE and the sequence number.

char *RibGetDefinedString( PRIB_HASHATOM atom )

The RIB binary format allows strings to be referred to with a simple ID number once that ID number has been assigned in a RIB statement to the given string. To show the association between a strings ID number and its NULL terminated string of characters, the hash table stores atoms that can be found given the ID number. RibGetDefinedString() returns a NULL terminated string once the hash atom is found.

The correct atom can be found by calling RibFindMatch() given type kRIB_HASH_STRING and the ID number.

Refer to RibSetDefinedString().

PRIB_ERROR RibGetError( RIB_HANDLE rib )

Returns a pointer to RIB_ERROR structure that describes the last error set. This pointer points to a memory block included in a larger structure that is freed when rib is closed.

Do not free the returned pointer.

Refer to RibSetError().

PRIB_ERRORFILTERPROC RibGetErrorHandler( RIB_HANDLE rib )

Returns a function pointer of the presently set error handler.

Refer to RibSetErrorHandler() and RibDefaultErrorHandler().

char *RibGetErrorMsg( int code )

Returns the RenderMan Standard error message for the following codes:

#define RIE_NOERROR       ((RtInt)0)
#define RIE_NOMEM         ((RtInt)1)  
#define RIE_SYSTEM        ((RtInt)2)  
#define RIE_NOFILE        ((RtInt)3)  
#define RIE_BADFILE       ((RtInt)4)  
#define RIE_VERSION       ((RtInt)5)  

#define RIE_INCAPABLE     ((RtInt)11)  
#define RIE_UNIMPLEMENT   ((RtInt)12)  
#define RIE_LIMIT         ((RtInt)13)  
#define RIE_BUG           ((RtInt)14)  

#define RIE_NOTSTARTED    ((RtInt)23)  
#define RIE_NESTING       ((RtInt)24)  
#define RIE_NOTOPTIONS    ((RtInt)25)  
#define RIE_NOTATTRIBS    ((RtInt)26)  
#define RIE_NOTPRIMS      ((RtInt)27)  
#define RIE_ILLSTATE      ((RtInt)28)  
#define RIE_BADMOTION     ((RtInt)29)  
#define RIE_BADSOLID      ((RtInt)30)  

#define RIE_BADTOKEN      ((RtInt)41)  
#define RIE_RANGE         ((RtInt)42)  
#define RIE_CONSISTENCY   ((RtInt)43)  
#define RIE_BADHANDLE     ((RtInt)44)  
#define RIE_NOSHADER      ((RtInt)45)  
#define RIE_MISSINGDATA   ((RtInt)46)  
#define RIE_SYNTAX        ((RtInt)47)

#define RIE_MATH          ((RtInt)61)    

#define RIE_INFO          ((RtInt)0)  
#define RIE_WARNING       ((RtInt)1)  
#define RIE_ERROR         ((RtInt)2)  
#define RIE_SEVERE        ((RtInt)3)

unsigned int RibGetFileName( RIB_HANDLE rib ): Returns the filename given to RibOpen(), RibOpenWithHashTable(), or RibOpenSubfile().

void* RibGetHashExtendedData( PRIB_HASHATOM atom )

Returns the extended data field of atom.

Refer to RibGetConflictingHashAtom().

RIB_HASHHND RibGetHashHandle( RIB_HANDLE rib ): Returns the handle of rib's hash table.

PRIB_HINTTABLE RibGetHintTable( RIB_HANDLE rib )

Returns a pointer to a table of function pointers that handle the RenderMan standard hints. The table has the following order and default values:

PRIB_ARCRECFILTERPROC gRibHintTable[] = {
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##CameraOrientation */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##CapabilitiesNeeded */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##CreationDate */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##Creator */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##For */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##Frames */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##Include */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##RenderMan */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##Scene */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler,/* ##Shaders */
   (PRIB_ARCRECFILTERPROC)RibDefaultHintHandler /* ##Textures */
};

Refer to RibGetHintTableSize() and RibSetHintTable(). By default a RIB handle has no hint table and RibGetHintTable() will return NULL.

Also refer to RibDefaultHintHandler() for an example of a hint handler function.

int RibGetHintTableSize( RIB_HANDLE rib )

Returns size in bytes of a table of function pointers to handle all the supported hints.

Refer to RibGetHintTable() and RibSetHintTable()

Also refer to RibDefaultHintHandler() for an example hint handling function used in a hint table.

int RibGetLastChar( RIB_HANDLE hrib ): Returns the last character read by RibGetChar().

int RibGetLastErrorCode( RIB_HANDLE rib ): Returns the last error code set by RibSetError().

int RibGetLastErrorSeverity( RIB_HANDLE rib ): Returns the level of severity for the last error code set by RibSetError().

int RibGetLastNUniform(

int RibGetLastNUniform( RIB_HANDLE rib )

Returns a the number of uniform parameters that the RIB Reader library calculated for a given Ri call. This function should only be called from a Ri-like function hooked into the Ri table of rib.

Refer to RibSetLastNUniform()

int RibGetLastNVarying(

int RibGetLastNVarying( RIB_HANDLE rib )

Returns a the number of varying parameters that the RIB Reader library calculated for a given Ri call. This function should only be called from a Ri-like function hooked into the Ri table of rib.

Refer to RibSetLastNVarying()

int RibGetLastNVertex(

int RibGetLastNVertex( RIB_HANDLE rib )

Returns a the number of vertex parameters that the RIB Reader library calculated for a given Ri call. This function should only be called from a Ri-like function hooked into the Ri table of rib.

Refer to RibSetLastNVertex()

int RibGetLastSequence( RIB_HANDLE rib )

To get the last read sequence number, use RibGetLastSequence(). RibGetLastSequence() is typically called from a RI function that was listed in the RI table associated with a RIB handle or a RI call that has hooked into the calling chain that starts at a given RI table.

There is a sequence number when reading a RIB binding. The sequence number is not there when calling such calls as RiLightSource() as shown below:

     ##RenderMan RIB
     version 3.03
     LightSource "ambientlight" 1

Refer to RibSetLastSequence().

unsigned int RibGetLineCount( RIB_HANDLE rib ): Returns the number of '\n' characters that have been encounted so far. This value may not be very helpful if the input is a binary encoded RIB file. To query whether any binary characters were encountered use RibGetStatus() and check for the status flag kRIB_STATUS_ENCODEDDATA.

int RibGetNColorSamples( RIB_HANDLE rib ): Returns the number of color channels set by RibSetNColorSamples(). When a RIB handle is created the default number of channels is 3. This value affects how Color statements are read and the size of RtColor structures.

RIB_UINT32 RibGetOptions( RIB_HANDLE hrib )

Returns the option flags set for a given RIB handle. The possible option flags are kRIB_OPTION_READ_SUBFILES and kRIB_OPTION_ERRMSG_VERBOSE.

The option flag kRIB_OPTION_READ_SUBFILES makes the RIB Reader Library open subfiles referenced by ReadArchive calls.

The option flag kRIB_OPTION_ERRMSG_VERBOSE makes the RIB Reader Library print a longer error message along with the rather undescriptive RenderMan Standard error message.

Refer to RibSetOptions().

int RibGetParameterTypeInfo(

PRIB_RITABLE RibGetParameterTypeInfo( RIB_HANDLE rib, int *uniform, int *varying, int *vertex )

Returns a the number of uniform, varying and vertex parameters that the RIB Reader library calculated for a given Ri call. This function should only be called from a Ri-like function hooked into the Ri table of rib.

Refer to macros RibGetLastNUniform() RibGetLastNVarying() RibGetLastNVertex() RibSetLastNUniform() RibSetLastNVarying() RibSetLastNVertex()

PRIB_RITABLE RibGetRITable( RIB_HANDLE rib )

Returns a pointer to a table of Ri calls that has been associated to the RIB handle rib.

The function RibSetRITable() changes what RI table is associated with rib.

int RibGetRITableSize( RIB_HANDLE rib ): Returns the size in bytes needed to store a Ri table. Refer to gRibRITable[] as an example table.

RIB_UINT32 RibGetStatus( RIB_HANDLE hrib ): Returns the Status Flags that are set for the RIB input hrib.

char *RibGetStringAtom( PRIB_HASHATOM a )

Retrieves the string of hash atom a if it is of hash atom type kRIB_HASH_STRING.

Refer to RibSetStringAtom().

int RibGetTypeClassNames( unsigned int code, char **c, char **t )

Variable names must have their class and type declared with a Declare statement before they can be used in a parameter list. The RIB Reader library automatically adds variable declarations to a hash table associated to a RIB file. A tool can also call RibDeclare() to perform this function for additional variable names unique to the tool being implemented. RibFindMatch() can be used to query a variable already in a hash table.

Once a variable has been declared and added to a RIB's hash table, its class and type has been converted into a single integer. RibGetTypeClassNames() can be used to return two strings naming the class and type. If either the c or t parameters are NULL, RibGetTypeClassNames() simply skips over the code that would have returned a string pointer for that parameter without giving an error.

The following lists the class and type strings along with their assocaited KRIB_ integer values used to encode them:

      kRIB_FLOATTYPE      -- "float"
      kRIB_STRINGTYPE     -- "string";
      kRIB_POINTTYPE      -- "point";
      kRIB_COLORTYPE      -- "color";
      kRIB_NORMALTYPE     -- "normal";
      kRIB_VECTORTYPE     -- "vector";
      kRIB_HPOINTTYPE     -- "hpoint";
      kRIB_INTTYPE        -- "int";
      kRIB_FLOATPAIRTYPE  -- "float pair";
      kRIB_INTPAIRTYPE    -- "integer pair";
      kRIB_STANDALONETYPE -- "standalone";
      no type code set    -- "unknown";

      kRIB_VERTEXCLASS  -- "vertex";
      kRIB_VARYINGCLASS -- "varying";
      kRIB_UNIFORMCLASS -- "uniform";
      no class code set -- "uniform";

The pointers to strings given to c and t should not be freed. They are constant strings linked into the Affine library being used.

int RibGetUserParameters( char *table, int ntable, RtInt n, RtToken tokens[], RtPointer parms[], RtPointer output[] )

Refer to the tool tokentbl for a description of the format of ntable.

Refer to Sorting Through the Data for an example using RibGetUserParameters().

int RibGetUVStep( RIB_HANDLE hrib, RtInt *ustep, RtInt *vstep )

When reading a RIB file statements such as Patch and PatchMesh require u and v step values. Refer to specification for the use of step values. By default the u and v step values are set to 3. To query the present setting use RibGetUVStep()

Refer to RibSetUVStep() for more information on U and V step values and setting them.

int RibGetVectorCache( RIB_HANDLE rib, RtInt *n, RtToken **tokens, RtPointer **params )

Returns the last read parameter list using vector form in *n, *tokens, *params.

The pointers assigned to n, tokens, params should not be freed.

int RibGetVectorCacheInfo( RIB_HANDLE rib, RtInt *n, RtInt *nvertices, unsigned int **types, unsigned int **sizes )

Returns information about the last read parameter list read. Associated with each token/parameter pair returned by RibGetVectorCache() is a type and parameter data size. The type uses the following flags for a token's declaration:

   kRIB_UNKNOWNCLASS
   kRIB_UNIFORMCLASS
   kRIB_VARYINGCLASS
   kRIB_VERTEXCLASS
   kRIB_CONSTANTCLASS
   kRIB_UNKNOWNTYPE
   kRIB_FLOATTYPE
   kRIB_STRINGTYPE
   kRIB_POINTTYPE 
   kRIB_COLORTYPE 
   kRIB_NORMALTYPE
   kRIB_VECTORTYPE
   kRIB_HPOINTTYPE
   kRIB_INTTYPE 
   kRIB_MATRIXTYPE 
   kRIB_FLOATPAIRTYPE
   kRIB_INTPAIRTYPE 
   kRIB_STANDALONETYPE

int RibHandleArchiveRecord( RIB_HANDLE rib ): Calls rib's archive record handler if there is one, otherwise the comment or structure that has been found is read and discarded. By default RibDefaultArchiveRecordHandler() is called.

int RibHandlePrefix( RIB_HANDLE rib ): Comments, binary encoded RI requests, or binary encoded string definitions can be located inbetween statement data and token/parameter pairs. RibHandlePrefix() is called before each atomic item of data to handle any comments or special codes that may appear.

int RibHashValueFromInt( RIB_HASHHND hash, int key ): Creates a hash value from integer value key.

int RibHashValueFromString( RIB_HASHHND hash, char* p ): Creates a hash value from string p.

int RibHashValueFromStringN( RIB_HASHHND hash, char *p, int n ): Creates a hash value from n characters in string p.

int RibIgnoreArchiveRecords( RIB_HANDLE rib ): Sets rib's pointer to an archive record handler to NULL and disables lines of text following a '#' character from being forwarded to a RiArchiveRecord() function in rib's RI table.

int RibIgnoreLastChar( RIB_HANDLE rib ): Removes a character from rib's input buffer if the status flag kRIB_STATUS_SAVETOBUFFER is set.

int RibIncrLineCount( RIB_HANDLE rib ): Increments rib's present line count by one. Line count is used when printing error messages.

int RibIncrBufferLength( RIB_HANDLE rib ): Increments the count of bytes used in a buffer that RibGetChar() can be set to copy input to when a status flag of kRIB_STATUS_SAVETOBUFFER is set.

int RibIncrByteOffset( RIB_HANDLE rib ): Increments rib's present byte offset count into the input file by one. Byte offset count is used when printing error messages for binary encoded RIBs.

int RibIsaBinaryChar( char c ): Returns RI_TRUE if the character c has the bit 0200 set. Otherwise RI_FALSE is returned.

int RibIsaDelimitor( char c )

Returns RI_TRUE if the character c meets the following condition:

       (c)=='[' || (c)=='#' || c=='\"' )