Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwResources
[Initialization & Resource Management]


Data Structures
struct   RwResEntry

Typedefs
typedef void(*  RwResEntryDestroyNotify )(RwResEntry *resEntry)

Functions
RwBool  RwResourcesFreeResEntry (RwResEntry *entry)
RwResEntry *  RwResourcesAllocateResEntry (void *owner, RwResEntry **ownerRef, RwInt32 size, RwResEntryDestroyNotify destroyNotify)
RwResEntry *  RwResourcesUseResEntry (RwResEntry *entry)
RwBool  RwResourcesSetArenaSize (RwUInt32 size)
RwInt32  RwResourcesGetArenaSize (void)
RwInt32  RwResourcesGetArenaUsage (void)
RwBool  RwResourcesEmptyArena (void)

Detailed Description

Resource handling. Resources are used to instance objects into.

RwResources Overview

Requirements

Overview

This object represents the RenderWare Resource Arena cache.

During rendering RenderWare stores platform-dependent instances of model geometry within this cache. If the model is not changed substantially from one cycle to the next, the instanced data is simply fetched and transferred to the rendering hardware, rather than being recomputed.

This system improves the speed of the rendering process, but the size of the Resource Arena needs to be fine-tuned for best results. It is possible for a badly-tuned Resource Arena to affect performance.

Typedef Documentation

typedef void(* RwResEntryDestroyNotify)(RwResEntry * resEntry)
 

RwResEntryDestroyNotify type represents the function called from RwResourcesFreeResEntry (and indirectly from RwResourcesEmptyArena) immediately before the memory used by the specified resources entry is released.

Parameters:
resEntry  Pointer to the instanced data.

Function Documentation

RwResEntry* RwResourcesAllocateResEntry (  void *    owner,
RwResEntry **    ownerRef,
RwInt32    size,
RwResEntryDestroyNotify    destroyNotify
) 
 

RwResourcesAllocateResEntry is a function used to allocate a resources entry for the specified object of the given size.

Also use this function to specify a callback function that will be executed immediately before the resources entry is removed from the resources arena (pass NULL to indicate there is no callback).

Parameters:
owner  Pointer to the object that will own the resources entry.
ownerRef  Pointer to a pointer that will receive a reference to the resources entry.
size  A RwInt32 value equal to the size of the resources entry to allocate (in bytes).
destroyNotify  Pointer to destroy notify callback function. Specify NULL to ignore.
Returns:
Returns pointer to the allocated resources block if successful or NULL if there is an error.
See also:
RwResourcesFreeResEntry , RwResourcesUseResEntry
RwBool RwResourcesEmptyArena (  void    ) 
 

RwResourcesEmptyArena is used to release all the memory in the instancing arena. Any resources entries that have registered a destroy notify callback will have their callback function executed before the arena memory is freed.

Returns:
Returns TRUE.
See also:
RwResourcesAllocateResEntry , RwResourcesGetArenaSize , RwResourcesGetArenaUsage , RwResourcesSetArenaSize
RwBool RwResourcesFreeResEntry (  RwResEntry *    entry ) 
 

RwResourcesFreeResEntry is used to release the memory allocated to the specified resources entry. The destroy notify callback (if one was specified at allocation time) will be called before the memory is freed. The pointer that was filled in at creation time will be set back to NULL to indicate that the memory has been freed.

Parameters:
entry  Pointer to the resources entry.
Returns:
Returns TRUE is successful or FALSE if there is an error.
See also:
RwResourcesAllocateResEntry , RwResourcesUseResEntry
RwInt32 RwResourcesGetArenaSize (  void    ) 
 

RwResourcesGetArenaSize is used to determine the size (in bytes) of the current instancing arena.

Returns:
Returns a RwInt32 value equal to the size of the resources arena (in bytes)
See also:
RwResourcesEmptyArena , RwResourcesGetArenaUsage , RwResourcesSetArenaSize
RwInt32 RwResourcesGetArenaUsage (  void    ) 
 

RwResourcesGetArenaUsage is used to calculate the total amount of instance arena memory used in the last rendering frame. The number returned may be larger than the arena size if the arena has started thrashing: this will cause performance to degrade and the application may wish to resize the arena to prevent this.

Note that the value returned by this function is only meaningful before a call to RwCameraShowRaster (which purges the resources cache).

Returns:
Returns a RwInt32 value equal to the size of the resources arena (in bytes)
See also:
RwResourcesEmptyArena , RwResourcesGetArenaSize , RwResourcesSetArenaSize
RwBool RwResourcesSetArenaSize (  RwUInt32    size ) 
 

RwResourcesSetArenaSize is used to specify the size of the memory block reserved for the resources instancing arena.

This should be used in between RwEngineInit and RwEngineStart to set the default size for the arena before the memory is allocated. If used at a later stage, the arena will be emptied and the memory reallocated.

Parameters:
size  A RwUInt32 value equal to the arena size (in bytes)
Returns:
Returns TRUE if successful or FALSE if there is an error.
See also:
RwResourcesEmptyArena , RwResourcesGetArenaSize , RwResourcesGetArenaUsage
RwResEntry* RwResourcesUseResEntry (  RwResEntry *    entry ) 
 

RwResourcesUseResEntry is used to mark the specified resources entry as still in use. It should be called every rendering frame that a resources entry is used to protect the resource against being unnecessarily freed.

Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.

Parameters:
entry  Pointer to the resources entry.
Returns:
Returns pointer to the resources entry if successful or NULL if there is an error.
See also:
RwResourcesAllocateResEntry , RwResourcesFreeResEntry
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:13 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)