Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwTexDictionary
[Texture Dictionaries]


Data Structures
struct   RwTexDictionary

Typedefs
typedef RwTexDictionary *(*  RwTexDictionaryCallBack )(RwTexDictionary *dict, void *data)

Functions
RwInt32  RwTexDictionaryRegisterPluginStream (RwUInt32 pluginID, RwPluginDataChunkReadCallBack readCB, RwPluginDataChunkWriteCallBack writeCB, RwPluginDataChunkGetSizeCallBack getSizeCB)
RwInt32  RwTexDictionarySetStreamAlwaysCallBack (RwUInt32 pluginID, RwPluginDataChunkAlwaysCallBack alwaysCB)
RwUInt32  RwTexDictionaryStreamGetSize (const RwTexDictionary *texDict)
const RwTexDictionary *  RwTexDictionaryStreamWrite (const RwTexDictionary *texDict, RwStream *stream)
RwTexDictionary *  RwTexDictionaryStreamRead (RwStream *stream)
RwTexDictionary *  RwTexDictionaryCreate (void)
RwBool  RwTexDictionaryDestroy (RwTexDictionary *dict)
const RwTexDictionary *  RwTexDictionaryForAllTextures (const RwTexDictionary *dict, RwTextureCallBack fpCallBack, void *pData)
RwBool  RwTexDictionaryForAllTexDictionaries (RwTexDictionaryCallBack fpCallBack, void *pData)
RwTexture *  RwTexDictionaryAddTexture (RwTexDictionary *dict, RwTexture *texture)
RwTexture *  RwTexDictionaryRemoveTexture (RwTexture *texture)
RwTexture *  RwTexDictionaryFindNamedTexture (RwTexDictionary *dict, const RwChar *name)
RwTexDictionary *  RwTexDictionarySetCurrent (RwTexDictionary *dict)
RwTexDictionary *  RwTexDictionaryGetCurrent (void)
RwInt32  RwTexDictionaryRegisterPlugin (RwInt32 size, RwUInt32 pluginID, RwPluginObjectConstructor constructCB, RwPluginObjectDestructor destructCB, RwPluginObjectCopy copyCB)
RwInt32  RwTexDictionaryGetPluginOffset (RwUInt32 pluginID)
RwBool  RwTexDictionaryValidatePlugins (const RwTexDictionary *dict)

Detailed Description

Texture Dictionary

RwTexDictionary Overview

Requirements

Overview

This object represents a Texture Dictionary: a database of Textures (RwTexture) and their associated Rasters (RwRaster). They may be used in two main ways:

Any number of dictionaries may be managed by the system, one of which may be set as the 'current' active dictionary. On initialization, RenderWare Graphics creates a single dictionary as the current one.

See:-

Finding textures

When an attempt is made to load a texture, the current dictionary is first searched if one is defined. If there is no current dictionary, then all dictionaries in the system are searched. If the texture is not found, then the image file is read from disk. See also:-

Adding textures to dictionaries

If a texture is loaded from a file, then it is automatically added to the current dictionary if one is defined. Alternatively, a texture may be added to a dictionary manually using RwTexDictionaryAddTexture, but note that a texture may only be attached to one dictionary at a time.

A texture's reference count is not actually incremented when it is added to a dictionary. When the texture is destroyed ( RwTextureDestroy is called for the last reference) it is also removed from the dictionary. Any other objects that are created or loaded and require the texture after this will cause it to be loaded again. To avoid this, a texture may be made to persist in the dictionary by incrementing its reference count with RwTextureAddRef. Note that if a texture dictionary is read in from a stream, then its textures are automatically made persistent.

A dictionary should not be destroyed until all objects referencing textures in the dictionary have been destroyed first. After this, the only textures that should remain are those that have been made persistent, and they should have a reference count of 1. They will be destroyed during a call to RwTexDictionaryDestroy since this calls RwTextureDestroy for any remaining textures.

See:-

Iterators

These are for iterating over all textures in a dictionary or all dictionaries in the system. See:-

Streaming texture dictionaries

See:-

When a saved dictionary is streamed in, the textures do have reference counts for their dictionary entry. This means that objects using the textures may be created and destroyed without the textures being completely destroyed and removed from the dictionary. When the textures are no longer required, destruction of the dictionary will cause them to be destroyed.

Developers should note that, when written to a RenderWare Binary Stream, Texture Dictionaries also store the associated Rasters. Rasters are, by definition, platform-dependent, so Texture Dictionaries cannot normally be read on platforms other than those on which they were generated.

If a texture dictionary would be usefully read on multiple platforms, then a Platform Independent Texture Dictionary can be created. See RtPITexD for more details.

Texture dictionary plugins

See:-

Typedef Documentation

typedef RwTexDictionary*(* RwTexDictionaryCallBack)(RwTexDictionary *dict, void *data)
 

RwTexDictionaryCallBack represents the function called from RwTexDictionaryForAllTexDictionaries for all texture dictionaries that currently exist. This function should return the current texture dictionary to indicate success. The callback may return NULL to terminate further callbacks on the texture dictionary. It may safely destroy the current texture dictionary without adversely affecting the iteration process.

Parameters:
dict  Pointer to the current texture dictionary.
pData  User-defined data pointer.
Returns:
Pointer to the current texture dictionary
See also:
RwTexDictionaryForAllTexdictionaries

Function Documentation

RwTexture* RwTexDictionaryAddTexture (  RwTexDictionary *    dict,
RwTexture *    texture
) 
 

RwTexDictionaryAddTexture is used to add the specified texture to the given texture dictionary. It is recommended that the texture is named so that it can be identified when searching the texture dictionaries.

Note:
If the texture already belongs to another texture dictionary, the texture is first removed from that dictionary before being added to the new one. A texture may only be a member of one texture dictionary.
The texture does not receive a reference count for its dictionary entry (see RwTexDictionary Overview).
Parameters:
dict  A pointer to the texture dictionary that will receive the texture
texture  A pointer to the texture that will be added to the dictionary
Returns:
Returns a pointer to the texture
See also:
RwTexDictionaryRemoveTexture , RwTextureGetDictionary , RwTextureSetName
RwTexDictionary* RwTexDictionaryCreate (  void    ) 
 

RwTexDictionaryCreate is used to create a new texture dictionary for storing textures.

Returns:
Returns a pointer to newly created texture dictionary if successful or NULL if there is an error
See also:
RwTexDictionaryDestroy , RwTexDictionaryAddTexture , RwTexDictionaryRemoveTexture
RwBool RwTexDictionaryDestroy (  RwTexDictionary *    dict ) 
 

RwTexDictionaryDestroy is used to destroy the specified texture dictionary. If the dictionary is the current one, the current dictionary is set to NULL.

Any objects that reference textures in the dictionary must be destroyed first. The only textures that should then remain in the dictionary are those that were either streamed in with the dictionary, or forced to be persistent by incrementing their reference count. The reference count should be 1. RwTexDictionaryDestroy will call RwTextureDestroy for these remaining textures so that they will be removed from the system.

Parameters:
dict  A pointer to the texture dictionary to destroy
Returns:
Returns TRUE if successful or FALSE if there is an error
See also:
RwTexDictionaryCreate , RwTexDictionaryRemoveTexture , RwTextureDestroy
RwTexture* RwTexDictionaryFindNamedTexture (  RwTexDictionary *    dict,
const RwChar *    name
) 
 

RwTexDictionaryFindNamedTexture is used to find the specified named texture in the given texture dictionary. The search is only performed on the texture's name and not on the texture's pointer. Hence, the texture must have been named prior to this function call.

Parameters:
dict  Pointer to the texture dictionary that will be searched.
name  Pointer to the texture name that will be searched for.
Returns:
Returns a pointer to the texture if successful or NULL if there is an error or if the texture was not found
See also:
RwTextureSetName , RwTextureCreate , RwTextureRead , RwTexDictionaryForAllTextures
RwBool RwTexDictionaryForAllTexDictionaries (  RwTexDictionaryCallBack    fpCallBack,
void *    pData
) 
 

RwTexDictionaryForAllTexDictionaries is used to execute the given callback function on all currently existing texture dictionaries.

The format of the callback function is:

   RwTexDictionary * (*RwTexDictionaryCallBack) (RwTexDictionary *dict, void *data)

where data is a user-supplied data pointer to pass to the callback function.

Note:
Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RwTexDictionaryForAllTexDictionaries will still return successfully. Also, the callback function may safely destroy the current texture dictionary without adversely affecting the iteration process.
Parameters:
fpCallBack  a pointer to the function to call with each texture dictionary
pData  A user data pointer to pass to callback function
Returns:
Returns TRUE on success, FALSE otherwise
See also:
RwTexDictionaryForAllTextures , RwTexDictionaryFindNamedTexture
const RwTexDictionary* RwTexDictionaryForAllTextures (  const RwTexDictionary *    dict,
RwTextureCallBack    fpCallBack,
void *    pData
) 
 

RwTexDictionaryForAllTextures is used to execute the given callback function on all textures in the specified texture dictionary.

The format of the callback function is:

   RwTexture * (*RwTextureCallBack) (RwTexture *texture, void *data)

where data is a user-supplied data pointer to pass to the callback function.

Note:
Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RwTexDictionaryForAllTextures will still return successfully.
Parameters:
dict  A pointer to the texture dictionary
fpCallBack  A pointer to the function to call with each texture in the dictionary
pData  A user data pointer to pass to the callback function
Returns:
Returns a pointer to the texture dictionary
See also:
RwTexDictionaryForAllTexDictionaries , RwTexDictionaryFindNamedTexture
RwTexDictionary* RwTexDictionaryGetCurrent (  void    ) 
 

RwTexDictionaryGetCurrent is used to retrieve the current texture dictionary, if any. See RwTexDictionary Overview for details of how the current dictionary is used.

Returns:
Returns a pointer to the current texture dictionary if successful or NULL if there is no current dictionary defined
See also:
RwTexDictionarySetCurrent
RwInt32 RwTexDictionaryGetPluginOffset (  RwUInt32    pluginID ) 
 

RwTexDictionaryGetPluginOffset is used to get the offset of a previously registered plugin.

Parameters:
pluginID  The plugin ID for which to get the data offset
Returns:
Returns the data block offset or -1 if the plugin is not registered
See also:
RwTexDictionaryRegisterPlugin , RwTexDictionaryValidatePlugins
RwInt32 RwTexDictionaryRegisterPlugin (  RwInt32    size,
RwUInt32    pluginID,
RwPluginObjectConstructor    constructCB,
RwPluginObjectDestructor    destructCB,
RwPluginObjectCopy    copyCB
) 
 

RwTexDictionaryRegisterPlugin is used to register a plugin and reserve some space within a texture dictionary. This must happen after the engine has been initialized but before the engine is opened.

Parameters:
size  An RwInt32 value equal to the size of the memory block to reserve
pluginID  An RwInt32 value equal to the plugin ID. (This must be unique. It is used to identify binary chunks)
constructCB  A constructor for the plugin data block
destructCB  A destructor for the plugin data block
copyCB  A copy constructor for the plugin data block
Returns:
Returns the byte offset within the texture dictionary of memory reserved for this plugin or a negative value if there is an error
See also:
RwTexDictionaryValidatePlugins , RwTexDictionaryGetPluginOffset
RwInt32 RwTexDictionaryRegisterPluginStream (  RwUInt32    pluginID,
RwPluginDataChunkReadCallBack    readCB,
RwPluginDataChunkWriteCallBack    writeCB,
RwPluginDataChunkGetSizeCallBack    getSizeCB
) 
 

RwTexDictionaryRegisterPluginStream is used to associate a set of binary stream functionality with a previously registered TexDictionary Plugin.

Parameters:
pluginID  An RwInt32 value equal to the plugin ID. (This must be unique. It is used to identify binary chunks)
readCB  A callback used when a chunk is read that is identified as being for this plugin
writeCB  A callback used when a chunk should be written out for this plugin
getSizeCB  A callback used to determine the binary stream size required for this plugin (return negative to suppress chunk writing)
Returns:
Returns an RwInt32 containing the byte offset within the texture of memory reserved for this plugin, or -1 if there is an error
See also:
RwTexDictionarySetStreamAlwaysCallBack , RwTexDictionaryRegisterPlugin , RwTexDictionaryGetPluginOffset , RwTexDictionaryValidatePlugins
RwTexture* RwTexDictionaryRemoveTexture (  RwTexture *    texture ) 
 

RwTexDictionaryRemoveTexture is used to remove the specified texture from the texture dictionary it is a member of. Removing the texture from the dictionary does not actually destroy it, so if this is the intention, use RwTextureDestroy in place of this function (see also the discussion in RwTexDictionary Overview).

Parameters:
texture  A pointer to the texture to remove from dictionary
Returns:
Returns a pointer to the texture
See also:
RwTexDictionaryAddTexture , RwTextureGetDictionary , RwTextureDestroy
RwTexDictionary* RwTexDictionarySetCurrent (  RwTexDictionary *    dict ) 
 

RwTexDictionarySetCurrent is used to specify the current texture dictionary. Use NULL to indicate that there is no default texture dictionary. See RwTexDictionary Overview for details of how the current dictionary is used.

Parameters:
dict  A pointer to the texture dictionary that will become the current dictionary
Returns:
Returns a pointer to the texture dictionary
See also:
RwTexDictionaryGetCurrent , RwTextureRead , RwTextureCreate
RwInt32 RwTexDictionarySetStreamAlwaysCallBack (  RwUInt32    pluginID,
RwPluginDataChunkAlwaysCallBack    alwaysCB
) 
 

RwTexDictionarySetStreamAlwaysCallBack is used to associate a binary stream functionality with a previously registered TexDictionary Plugin. This callback is called for all plugins after stream data reading has completed.

Parameters:
pluginID  An RwInt32 value equal to the plugin ID (This must be unique. It is used to identify binary chunks)
alwaysCB  The callback used when object base and plugin data reading is complete
Returns:
Returns an RwInt32 containing the byte offset within the texture of memory reserved for this plugin, or -1 if there is an error
See also:
RwTexDictionaryRegisterPluginStream , RwTexDictionaryRegisterPlugin , RwTexDictionaryGetPluginOffset , RwTexDictionaryValidatePlugins
RwUInt32 RwTexDictionaryStreamGetSize (  const RwTexDictionary *    texDict ) 
 

RwTexDictionaryStreamGetSize is used to determine the size in bytes of the binary representation of the specified texture dictionary. 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.

Note:
Note that texture dictionaries are device specific, and cannot generally be used on multiple platforms.
Parameters:
texDict  A pointer to the texture dictionary whose binary size is required
Returns:
Returns the chunk size of the texture dictionary if successful or zero if there is an error.
See also:
RwTexDictionaryStreamRead , RwTexDictionaryStreamWrite
RwTexDictionary* RwTexDictionaryStreamRead (  RwStream *    stream ) 
 

RwTexDictionaryStreamRead is used to read a texture dictionary from the specified binary stream. Prior to this function call, a binary texture dictionary chunk must have been found in the stream.

Note:
Note that texture dictionaries are device specific, and cannot generally be used on multiple platforms.
The sequence to locate and read a texture dictionary from a binary stream connected to a disk file is as follows: 
   RwStream *stream;
   RwTexDictionary *newTexDictionary;
  
   stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx");
   if( stream )
   {
       if( RwStreamFindChunk(stream, rwID_TEXDICTIONARY, NULL, NULL) )
       {
           newTexDictionary = RwTexDictionaryStreamRead(stream);
       }
   
       RwStreamClose(stream, NULL);
   }
Parameters:
stream  A pointer to the binary stream from which the texture dictionary will be read
Returns:
Returns pointer to the texture dictionary if successful or NULL if there is an error.
See also:
RwTexDictionaryStreamGetSize , RwTexDictionaryStreamWrite , RwStreamOpen , RwStreamClose , RwStreamFindChunk
const RwTexDictionary* RwTexDictionaryStreamWrite (  const RwTexDictionary *    texDict,
RwStream *    stream
) 
 

RwTexDictionaryStreamWrite is used to write the specified texture dictionary to the given binary stream. The stream must have been opened prior to this function call.

Note:
Note that texture dictionaries are device specific, and cannot generally be used on multiple platforms.
Parameters:
texDict  A pointer to the texture dictionary to be written
stream  A pointer to the binary stream
Returns:
Returns a pointer to the texture dictionary if successful or NULL if there is an error.
See also:
RwTexDictionaryStreamGetSize , RwTexDictionaryStreamRead , RwStreamOpen , RwStreamClose
RwBool RwTexDictionaryValidatePlugins (  const RwTexDictionary *    dict ) 
 

RwTexDictionaryValidatePlugins is used to validate the plugin memory allocated within the specified texture dictionary. This function is useful for determining where memory trampling may be occurring within an application.

This function only returns a meaningful response under a debug library.

Parameters:
dict  A pointer to the texture dictionary to validate
Returns:
Returns TRUE is the texture dictionary data is valid or FALSE if there is an error or if the texture dictionary data has become corrupt
See also:
RwTexDictionaryRegisterPlugin , RwTexDictionaryGetPluginOffset
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:15 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)