Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RtTOC
[Streaming]


Data Structures
struct   RtTOC
struct   RtTOCEntry

Functions
RtTOC *  RtTOCCreate (RwStream *stream)
void  RtTOCDestroy (RtTOC *toc)
RwInt32  RtTOCGetNumEntries (const RtTOC *toc)
RtTOCEntry *  RtTOCGetEntry (RtTOC *toc, RwInt32 entry)
RwUInt32  RtTOCStreamGetSize (const RtTOC *toc)
const RtTOC *  RtTOCStreamWrite (RtTOC *toc, RwStream *stream)
RtTOC *  RtTOCStreamRead (RwStream *stream)

Detailed Description

Table Of Contents (TOC) - creating a TOC for a stream.

RtTOC toolkit overview

Requirements

Overview

The RtTOC toolkit provides functionality to generate a Table Of Contents (TOC) for a stream. The TOC can be serialized at the head of a stream providing an easy listing of the contents of the stream. A TOC will be found at the head of the .rws files (RWS Format) exported using a RenderWare Graphics Exporter.

The TOC can also be used to skip through a stream to read specific chunks, rather than reading the stream sequentially. The offset element of the RtTOCEntry structure contains the byte offset of its entry's chunk header from the beginning of the file. Hence the sequence of events to read a TOC entry's chunk is:

  1. Open the RwStream for reading using RwStreamOpen and the rwSTREAMREAD flag.
  2. Find the TOC chunk using RwStreamFindChunk with the ID rwID_TOC.
  3. Read the TOC using RtTOCStreamRead.
  4. Identify the RtTOCEntry required by looping over all TOC entries from index 0 to RtTOCGetNumEntries - 1, inclusive.
  5. Close the RwStream using RwStreamClose, and re-open it for reading. This resets the stream position.
  6. Skip through the stream to the TOC entry's chunk header using the offset element of the RtTOCEntry as the argument to RwStreamSkip.
  7. Read the chunk header using RwStreamReadChunkHeaderInfo. Alternatively use RwStreamFindChunk with the chunk ID in the RtTOCEntry.
  8. Read the chunk with the appropriate API stream read function, e.g. RpWorldStreamRead for rwID_WORLD chunks.
It should be observed that after applying the appropriate skip from the RtTOCEntry, chunks should be read in the usual way as if the stream had been read sequentially.

Use of a TOC in an RWS file

RWS files, as output from the RenderWare Graphics exporters, contain a TOC at their head. As the first chunk of the file, this is easy to find, and the TOC interface allows the remaining chunks in the RWS file to be located with ease.

The code fragment below shows one possible use of the TOC. The TOC is obtained from an .rws file, and all TOC entries are queried whether they need to be loaded with an application defined function IsTOCEntryWanted.

   RwStream *stream;

   stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "myartwork.rws");
   if( stream )
   {
       RtTOC *toc = (RtTOC *)NULL;


       // get the TOC
       if( RwStreamFindChunk(stream, rwID_TOC, NULL, NULL) )
       {
           toc = RtTOCStreamRead(stream);
       }

       RwStreamClose(stream, NULL);

       if ( NULL != toc )
       {
           RwInt32  numTOCEntries;

           RwInt32  i;


           // determine the number of entries in the TOC
           numTOCEntries = RtTOCGetNumEntries( toc );

           for ( i = 0; i < numTOCEntries; i += 1 )
           {
                RtTOCEntry  *tocEntry;


                // get the next TOC entry
                tocEntry = RtTOCGetEntry( toc, i );

                // determine if the TOC entry is wanted through an application
                // specific function
                if ( FALSE != IsTOCEntryWanted( tocEntry ) )
                {
                    // re-open the stream to reset the position
                    stream = RwStreamOpen( rwSTREAMFILENAME, rwSTREAMREAD,
                                           "myartwork.rws" );
                    if ( NULL != stream )
                    {
                        RwChunkHeaderInfo   chunkHdrInfo;

                        
                        // skip to the chunk header of the TOC entry
                        RwStreamSkip( stream, tocEntry->offset );
        
                        // read the chunk header
                        RwStreamReadChunkHeaderInfo( stream, &chunkHdrInfo );
                        
                        // stream read clunk with appropriate function
                        // e.g. world = RpWorldStreamRead( stream );

                        RwStreamClose( stream, NULL );
                    }
                }
           }

           // destroy the TOC when finished
           RtTOCDestroy( toc );
       }
   }

Function Documentation

RtTOC* RtTOCCreate (  RwStream *    stream ) 
 

RtTOCCreate creates a Table Of Contents (TOC) for a stream. This function parses the input stream and generates a TOC entry for chunks listed in RwCorePluginID.

Note:
The stream must have been opened for reading prior to calling this function.
Note:
This function parses the stream. On return from this function the stream position will need to be reset. This can be done by closing and then re-opening the stream.
Parameters:
stream  Pointer to RwStream to create a TOC for.
Returns:
Pointer to an RtTOC on success, else NULL.
See also:
RtTOCDestroy , RtTOCGetNumEntries , RtTOCGetEntry , RtTOCStreamGetSize , RtTOCStreamWrite , RtTOCStreamRead
void RtTOCDestroy (  RtTOC *    toc ) 
 

RtTOCDestroy destroys a TOC that was created by calling RtTOCCreate.

Parameters:
toc  Pointer to the RtTOC to destroy.
See also:
RtTOCCreate , RtTOCGetNumEntries , RtTOCGetEntry , RtTOCStreamGetSize , RtTOCStreamWrite , RtTOCStreamRead
RtTOCEntry* RtTOCGetEntry (  RtTOC *    toc,
RwInt32    entry
) 
 

RtTOCGetEntry gets the specified TOC entry from the TOC.

Parameters:
toc  Pointer to the RtTOC to get the TOC entry from.
entry  RwInt32 containing the zero-based index of the TOC entry to obtain.
Returns:
Pointer to the RtTOCEntry containing the required TOC entry data.
See also:
RtTOCCreate , RtTOCDestroy , RtTOCGetNumEntries , RtTOCStreamGetSize , RtTOCStreamWrite , RtTOCStreamRead
RwInt32 RtTOCGetNumEntries (  const RtTOC *    toc ) 
 

RtTOCGetNumEntries gets the number of entries in the TOC.

Parameters:
toc  Pointer to the RtTOC to get the number of entries from.
Returns:
RwInt32 containing the number of entries in the TOC.
See also:
RtTOCCreate , RtTOCDestroy , RtTOCGetEntry , RtTOCStreamGetSize , RtTOCStreamWrite , RtTOCStreamRead
RwUInt32 RtTOCStreamGetSize (  const RtTOC *    toc ) 
 

RtTOCStreamGetSize is used to determine the size in bytes of the binary representation of the TOC. This is used in the binary chunk header to indicate the size of the texture chunk. The size does not include the size of the chunk header.

Parameters:
toc  Pointer to the RtTOC whose binary size is required.
Returns:
RwUInt32 value equal to the chunk size, in bytes, of the TOC.
See also:
RtTOCCreate , RtTOCDestroy , RtTOCGetNumEntries , RtTOCGetEntry , RtTOCStreamWrite , RtTOCStreamRead
RtTOC* RtTOCStreamRead (  RwStream *    stream ) 
 

RtTOCStreamRead is used to read a TOC from the specified binary stream.

Note that prior to this function call a binary TOC chunk must be found in the stream using the RwStreamFindChunk API function.

Parameters:
stream  Pointer to RwStream to read the TOC from.
Returns:
Pointer to an RtTOC on success, else NULL.
The sequence to locate and read a TOC from a binary stream is as follows: 
   RwStream *stream;
   RtTOC *toc;

   stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
   if( stream )
   {
       if( RwStreamFindChunk(stream, rwID_TOC, NULL, NULL) )
       {
           toc = RtTOCStreamRead(stream);
       }

       RwStreamClose(stream, NULL);
   }
See also:
RtTOCCreate , RtTOCDestroy , RtTOCGetNumEntries , RtTOCGetEntry , RtTOCStreamGetSize , RtTOCStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk
const RtTOC* RtTOCStreamWrite (  RtTOC *    toc,
RwStream *    stream
) 
 

RtTOCStreamWrite is used to write the specified TOC to the given binary stream.

Note that the stream will have been opened prior to this function call.

Parameters:
toc  Pointer to RtTOC to write.
stream  Pointer to RwStream to write the TOC to.
Returns:
Pointer to the RtTOC argument if successful or NULL if there is an error.
See also:
RtTOCCreate , RtTOCDestroy , RtTOCGetNumEntries , RtTOCGetEntry , RtTOCStreamGetSize , RtTOCStreamRead
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:47:01 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)