Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwChunkGroup
[Streaming]


Data Structures

struct  RwChunkGroup

Functions

void RwChunkGroupSetFreeListCreateParams (RwInt32 blockSize, RwInt32 numBlocksToPrealloc)
RwChunkGroup * RwChunkGroupCreate (void)
RwBool RwChunkGroupDestroy (RwChunkGroup *grp)
RwChunkGroup * RwChunkGroupBeginStreamRead (RwStream *stream)
RwChunkGroup * RwChunkGroupEndStreamRead (RwChunkGroup *grp, RwStream *stream)
const RwChunkGroup * RwChunkGroupBeginStreamWrite (const RwChunkGroup *grp, RwStream *stream)
const RwChunkGroup * RwChunkGroupEndStreamWrite (const RwChunkGroup *grp, RwStream *stream)
RwUInt32 RwChunkGroupStreamGetSize (const RwChunkGroup *grp)
RwChunkGroup * RwChunkGroupSetName (RwChunkGroup *grp, const RwChar *name)

Detailed Description

Stream Group

RwChunkGroup Overview

Requirements

RwChunkGroup Overview

RwChunkGroup is used to provide a mean to identify and group data elements within a stream. The basic RenderWare chunk header provides information on the type, size and version of the data element. It does not provide information on the use or purpose of the data.

RwChunkGroup provides a mean to attach identification to objects within the stream without modification to the object's data. This allows the application to sort and arrange the data accordingly after stream using the RwChunkGroup for identification. A RwChunkGroup can be identified by using a name string.

RwChunkGroup exists in pairs in a stream. Each group is prefixed by a begin marker using rwID_CHUNKGROUPSTART and postfix by an end marker using rwID_CHUNKGROUPEND. RwChunkGroup data are stored at the begin marker. Any RenderWare data chunks which belongs to a group are written between the markers.

RwChunkGroup can exist inside another RwChunkGroup, providing a hierarchical arrangement if required.

Function Documentation

RwChunkGroup* RwChunkGroupBeginStreamRead (  RwStream *    stream ) 
 

RwChunkGroupBeginStreamRead is used to read the start of a name group from the specified binary stream.

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

RwChunkGroup always exist in rwID_CHUNKGROUPSTART / rwID_CHUNKGROUPEND pairs in a stream. Thus a rwID_CHUNKGROUPEND marker must be read for each rwID_CHUNKGROUPSTART marker.

Parameters:
stream  Pointer to RwStream to read the group from.
Returns:
Pointer to a RwChunkGroup on success, else NULL.
The sequence to locate and read a RwChunkGroup pair from a binary stream is as follows: 
   RwStream *stream;
   RwChunkGroup *grp;

   stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
   if( stream )
   {
       if( RwStreamFindChunk(stream, rwID_CHUNKGROUPSTART, NULL, NULL) )
       {
           grp = RwChunkGroupBeginStreamRead(stream);
       }

       if( RwStreamFindChunk(stream, rwID_CHUNKGROUPEND, NULL, NULL) )
       {
           grp = RwChunkGroupEndStreamRead(grp, stream);
       }

       RwStreamClose(stream, NULL);
   }

See also:
RwChunkGroupEndStreamRead , RwChunkGroupBeginStreamWrite , RwChunkGroupEndStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk

const RwChunkGroup* RwChunkGroupBeginStreamWrite (  const RwChunkGroup *    grp,
RwStream *    stream
) 
 

RwChunkGroupBeginStreamWrite is used to write the specified RwChunkGroup begin marker to the given binary stream.

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

RwChunkGroup always exist in rwID_CHUNKGROUPSTART / rwID_CHUNKGROUPEND pairs in a stream. Thus a rwID_CHUNKGROUPEND marker must be written for each rwID_CHUNKGROUPSTART marker.

Parameters:
grp  Pointer to RwChunkGroup to write.
stream  Pointer to RwStream to write the RwChunkGroup begin maker to.
Returns:
Pointer to the RwChunkGroup argument if successful or NULL if there is an error.
See also:
RwChunkGroupStreamGetSize , RwChunkGroupBeginStreamRead , RwChunkGroupEndStreamRead , RwChunkGroupEndStreamWrite

RwChunkGroup* RwChunkGroupCreate (  void    ) 
 

RwChunkGroupCreate is used to create an empty RwChunkGroup.

Returns:
Pointer to a RwChunkGroup on success, else NULL.
See also:
RwChunkGroupDestroy

RwBool RwChunkGroupDestroy (  RwChunkGroup *    grp ) 
 

RwChunkGroupDestroy is used to destroy a RwChunkGroup.

Parameters:
grp  Pointer to RwChunkGroup to be destroyed.
Returns:
TRUE
See also:
RwChunkGroupCreate

RwChunkGroup* RwChunkGroupEndStreamRead (  RwChunkGroup *    grp,
RwStream *    stream
) 
 

RwChunkGroupEndStreamRead is used to read the end of a name group from the specified binary stream.

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

RwChunkGroup always exist in rwID_CHUNKGROUPSTART / rwID_CHUNKGROUPEND pairs in a stream. Thus a rwID_CHUNKGROUPEND marker must be read for each rwID_CHUNKGROUPSTART marker.

Note:
This is a place holder function to match with RwChunkGroupBeginStreamRead. There are no RwChunkGroup data to read after the chunk header rwID_CHUNKGROUPEND so it can omitted for the present.
Parameters:
grp  Pointer to RwChunkGroup to read the rwID_CHUNKGROUPEND data to.
stream  Pointer to RwStream to read the rwID_CHUNKGROUPEND data from.
Returns:
Pointer to a RwChunkGroup on success, else NULL.
The sequence to locate and read a RwChunkGroup pair from a binary stream is as follows: 
   RwStream *stream;
   RwChunkGroup *group;

   stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
   if( stream )
   {
       if( RwStreamFindChunk(stream, rwID_CHUNKGROUPSTART, NULL, NULL) )
       {
           group = RwChunkGroupBeginStreamRead(stream);
       }

       if( RwStreamFindChunk(stream, rwID_CHUNKGROUPEND, NULL, NULL) )
       {
           group = RwChunkGroupEndStreamRead(group, stream);
       }

       RwStreamClose(stream, NULL);
   }

See also:
RwChunkGroupBeginStreamRead , RwChunkGroupBeginStreamWrite , RwChunkGroupEndStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk

const RwChunkGroup* RwChunkGroupEndStreamWrite (  const RwChunkGroup *    grp,
RwStream *    stream
) 
 

RwChunkGroupEndStreamWrite is used to write the specified RwChunkGroup end maker to the given binary stream.

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

RwChunkGroup always exist in rwID_CHUNKGROUPSTART / rwID_CHUNKGROUPEND pairs in a stream. Thus a rwID_CHUNKGROUPEND marker must be written for each rwID_CHUNKGROUPSTART marker.

Parameters:
grp  Pointer to RwChunkGroup to write.
stream  Pointer to RwStream to write the RwChunkGroup end marker to.
Returns:
Pointer to the RwChunkGroup argument if successful or NULL if there is an error.
See also:
RwChunkGroupStreamGetSize , RwChunkGroupBeginStreamRead , RwChunkGroupEndStreamRead , RwChunkGroupBeginStreamWrite

void RwChunkGroupSetFreeListCreateParams (  RwInt32    blockSize,
RwInt32    numBlocksToPrealloc
) 
 

RwChunkGroupSetFreeListCreateParams allows the developer to specify how many RwChunkGroup s to preallocate space for. Call before RwEngineInit.

Parameters:
blockSize  number of entries per freelist block.
numBlocksToPrealloc  number of blocks to allocate on RwFreeListCreateAndPreallocateSpace.
See also:
RwFreeList

RwChunkGroup* RwChunkGroupSetName (  RwChunkGroup *    grp,
const RwChar *    name
) 
 

RwChunkGroupSetName is used to set the name of gourp to the specified string. The string is copied internally and must not exceed rwCHUNKGROUPMAXNAME in length. Setting an empty name will delete the existing name.

Parameters:
grp  Pointer to the RwChunkGroup.
name  Pointer to the string to set.
Returns:
Pointer to the RwChunkGroup argument if successful or NULL if there is an error.

RwUInt32 RwChunkGroupStreamGetSize (  const RwChunkGroup *    grp ) 
 

RwChunkGroupStreamGetSize is used to determine the size in bytes of the binary representation of the RwChunkGroup. This is used in the binary chunk header to indicate the size of the data chunk. The size does not include the size of the chunk header. The RwChunkGroup data is written out with the group begin marker with chunk id rwID_CHUNKGROUPSTART.

Parameters:
grp  Pointer to the RwChunkGroup whose binary size is required.
Returns:
RwUInt32 value equal to the chunk size, in bytes, of the group.
See also:
RwChunkGroupBeginStreamWrite , RwChunkGroupEndStreamWrite

Criterion Software © 1993-2004 Criterion Software Limited. All rights reserved. Built Thu Feb 12 13:46:52 2004. Send Feedback