---

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

• Headers: rwcore.h
• Libraries: rwcore.lib

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:

• As a simple cache to prevent the same textures being loaded more than once.
• As an object that may be streamed in or out to load or save a set of textures efficiently when required.

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:

• RwTexDictionaryCreate
• RwTexDictionaryDestroy
• RwTexDictionarySetCurrent
• RwTexDictionaryGetCurrent

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:

• RwTextureRead
• RwTexDictionaryFindNamedTexture

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:

• RwTexDictionaryAddTexture
• RwTexDictionaryRemoveTexture

Iterators

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

• RwTexDictionaryForAllTextures
• RwTexDictionaryForAllTexDictionaries

Streaming texture dictionaries

See:

• RwTexDictionaryStreamRead
• RwTexDictionaryStreamWrite
• RwTexDictionaryStreamGetSize

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:

• RwTexDictionaryRegisterPlugin
• RwTexDictionaryRegisterPluginStream
• RwTexDictionarySetStreamAlwaysCallBack
• RwTexDictionaryValidatePlugins
• RwTexDictionaryGetPluginOffset

---

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

---