Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwFreeList
[Initialization & Resource Management]


Data Structures

struct  RwFreeList

Defines

#define rwFREELISTFLAG_STATIC   0x00000001
#define rwFREELISTFLAG_FREEBLOCKS

Typedefs

typedef void(* RwFreeListCallBack )(void *pMem, void *pData)

Functions

RwFreeList * RwFreeListCreate (RwInt32 entrySize, RwInt32 entriesPerBlock, RwInt32 alignment, RwUInt32 hint)
RwFreeList * RwFreeListCreateAndPreallocateSpace (RwInt32 entrySize, RwInt32 entriesPerBlock, RwInt32 alignment, RwInt32 numBlocksToPreallocate, RwFreeList *inPlaceSpaceForFreeListStruct, RwUInt32 hint)
RwBool RwFreeListDestroy (RwFreeList *freeList)
void RwFreeListSetFlags (RwFreeList *freeList, RwUInt32 flags)
RwUInt32 RwFreeListGetFlags (RwFreeList *freeList)
void * RwFreeListAlloc (RwFreeList *freelist, RwUInt32 hint)
RwFreeList * RwFreeListFree (RwFreeList *freelist, void *pBlock)
RwInt32 RwFreeListPurge (RwFreeList *freeList)
RwFreeList * RwFreeListForAllUsed (RwFreeList *freeList, RwFreeListCallBack fpCallBack, void *pData)
RwInt32 RwFreeListPurgeAllFreeLists (void)

Detailed Description

Free lists

RwFreeList Overview

Requirements

Overview

This object provides a platform-neutral memory allocation API.

A free list can be used to allocate memory for lists of identical data types. As the list is filled, the free list mechanism can be set to automatically allocate more memory in developer-defined chunks. Getting the most out of this system can require some fine-tuning work, but the result should be an optimal trade-off between the amount of memory used and speed.

RenderWare's internal freelists can be configured as appropriate for your application's usage.

See also:
RwCameraSetFreeListCreateParams , RwFrameSetFreeListCreateParams , RwImageSetFreeListCreateParams , RwImageFormatSetFreeListCreateParams , RwRasterSetFreeListCreateParams , RwTextureSetFreeListCreateParams , RwTexDictionarySetFreeListCreateParams , RwMatrixSetFreeListCreateParams , RwStreamSetFreeListCreateParams , RwPluginRegistrySetFreeListCreateParams , RxPipelineSetFreeListCreateParams , RpAtomicSetFreeListCreateParams , RpClumpSetFreeListCreateParams , RpLightSetFreeListCreateParams , RpLightTieSetFreeListCreateParams , RpMaterialSetFreeListCreateParams , RpTieSetFreeListCreateParams , RpHAnimHierarchySetFreeListCreateParams , RpLODAtomicCacheSetFreeListCreateParams , RpMatFXMaterialDataSetFreeListCreateParams , RpPatchAtomicSetFreeListCreateParams , RpPatchGeometrySetFreeListCreateParams , RpSkinSetFreeListCreateParams , Rt2dBrushSetFreeListCreateParams , Rt2dFontSetFreeListCreateParams , Rt2dFontDictNodeSetFreeListCreateParams , Rt2dObjectSetFreeListCreateParams , Rt2dPathSetFreeListCreateParams , RtAnimAnimationFreeListCreateParams
Freelists -- from Page 131 Advanced Animation and Rendering Techniques Alan Watt and Mark Watt Addison-Wesley 1993, ISBN 0-201-54412-1:

"Lastly, on a more general note concerning speedups for renderers, the implementor should be aware that a lot of suggestions for improving efficiency fall into the category of ingenious, but complex, algorithms for very specific contexts that may save a few microseconds but which make your code unreadable. A more general computer science perspective that takes a `global view' of the renderer can be more fruitful. For example, the renderer devotes a lot of time to allocating and deallocating chunks of memory for storing data. A lot of these chunks are always the same size - such as those that are continually required to store the data structure for fragment lists. Using memory management techniques that recognize this fact can yield considerable dividends. One such scheme would be to hold a series of empty lists in memory for all the commonly used data structures. An empty list for fragments, say, would contain a list of previously allocated, but no longer needed, fragment structures. When the renderer needs memory for a new fragment, it looks first at this empty list. If there is nothing there it allocates space directly, otherwise it takes a fragments off the end of the list and uses that. Conversely, when the renderer no longer needs a fragment, instead of freeing it, it goes onto the end of the empty list. In the authors' experience, replacing the naive allocate/deallocate scheme with this way of managing memory can result in 100% speedup. "

Define Documentation

#define rwFREELISTFLAG_FREEBLOCKS
 

Free blocks as soon as they are empty.

See also:
RwFreeListSetFlags

#define rwFREELISTFLAG_STATIC   0x00000001
 

The free list was statically allocated

See also:
RwFreeListSetFlags

Typedef Documentation

typedef void(* RwFreeListCallBack)(void *pMem, void *pData)
 

RwFreeListCallBack represents the function called from RwFreeListForAllUsed for all used entries in a given free list.

Parameters:
pMem  Pointer to the start of the current entries.
pData  User-defined data pointer.
See also:
RwFreeListForAllUsed

Function Documentation

void* RwFreeListAlloc (  RwFreeList *    freelist,
RwUInt32    hint
) 
 

RwFreeListAlloc is used to retrieve an unused entry from the specified free list. If, prior to this function call, the free list is empty, the whole free list block is allocated memory. If there are no more unused entries left, new entries are retrieved from another allocated block. Note that this function can be coerced to call RwMalloc through the second argument to RwEngineInit. This is actually implemented as a macro that expands to either _rwFreeListAllocReal or RwMalloc.

Parameters:
freelist  Pointer to the free list.
hint  An RwInt32 hint value Refer to RwMemoryFunctions for more details about the hints.
Returns:
Returns pointer to an unused entry if successful or NULL is there is an error.
See also:
RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwFreeList* RwFreeListCreate (  RwInt32    entrySize,
RwInt32    entriesPerBlock,
RwInt32    alignment,
RwUInt32    hint
) 
 

RwFreeListCreate is deprecated. RwFreeListCreateAndPreallocateSpace should be used instead to give better control over freelist allocations.

Parameters:
entrySize  An RwInt32 value equal to the size of each entry (in bytes)
entriesPerBlock  An RwInt32 value equal to the number of entries per block
alignment  An RwInt32 value equal to the desired byte alignment of entries. The alignment must be a power of two. Zero indicates don't care.
hint  An RwInt32 hint value. Refer to RwMemoryFunctions for more details about the hints.
Returns:
Returns a pointer to the new free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwFreeList* RwFreeListCreateAndPreallocateSpace (  RwInt32    entrySize,
RwInt32    entriesPerBlock,
RwInt32    alignment,
RwInt32    numBlocksToPreallocate,
RwFreeList *    inPlaceSpaceForFreeListStruct,
RwUInt32    hint
) 
 

RwFreeListCreateAndPreallocateSpace is used to create a new free list that will contain the specified number of entries, each of the specified size (in bytes), in a single block of memory. More blocks can be be allocated or freed as necessary in response to RwFreeListAlloc or RwFreeListFree.

Parameters:
entrySize  An RwInt32 value equal to the size of each entry (in bytes)
entriesPerBlock  An RwInt32 value equal to the number of entries per block
alignment  An RwInt32 value equal to the desired byte alignment of entries. The alignment must be a power of two.
numBlocksToPreallocate  An RwInt32 value specifying how many blocks to allocate now. 0 will wait until the first RwFreeListAlloc called on this list. Note that this isn't always a good policy and can cause fragmentation - allocating at least one block is often better.
inPlaceSpaceForFreeListStruct  A pointer to enough memory to store an RwFreeList structure. If NULL is passed memory will instead be allocated for the structure with RwMalloc.
hint  An RwInt32 hint value. Refer to RwMemoryFunctions for more details about the hints.
Returns:
Returns a pointer to the new free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwBool RwFreeListDestroy (  RwFreeList *    freeList ) 
 

RwFreeListDestroy is used to release the block (or blocks) of memory used by the specified free list.

Parameters:
freeList  A pointer to the free list
Returns:
Returns TRUE if successful or FALSE if there is an error
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListPurgeAllFreeLists

RwFreeList* RwFreeListForAllUsed (  RwFreeList *    freeList,
RwFreeListCallBack    fpCallBack,
void *    pData
) 
 

RwFreeListForAllUsed is used to apply the given callback function to all used entries in the specified free list. The format of the callback function is: 

        void (*RwFreeListCallBack)(void *mem, void *data);
where "data" is a pointer to user-defined data pointer to pass to the callback function.
Parameters:
freeList  A pointer to the free list
fpCallBack  A pointer to the callback to apply to call with each used block
pData  A pointer to user-supplied data to pass to callback function.
Returns:
Returns pointer to the free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwFreeList* RwFreeListFree (  RwFreeList *    freelist,
void *    pBlock
) 
 

RwFreeListFree is used to mark the specified entry contained in the given free list as unused. Note that this function can be coerced to call RwFree through the second argument to RwEngineInit. This function is actually implemented as a macro that expands to either _rwFreeListFreeReal or RwFree.

Parameters:
freelist  A pointer a to freelist
pBlock  A pointer to a used entry.
Returns:
Returns a pointer to the free list if successful or NULL if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListPurge , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwUInt32 RwFreeListGetFlags (  RwFreeList *    freeList ) 
 

RwFreeListGetFlags Get the allocation mode of a freelist. For more information see RwFreeListSetFlags

Parameters:
freeList  Pointer to the free list to retrieve flags from.
Returns:
Currently set flags for the specified freelist
See also:
RwFreeListSetFlags

RwInt32 RwFreeListPurge (  RwFreeList *    freeList ) 
 

RwFreeListPurge is used to the release the memory for any blocks in the specified free list that wholly contain unused entries. It returns the amount of memory (in bytes) recovered.

Parameters:
freeList  A pointer to free list.
Returns:
Returns the amount of memory freed, or -1 if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListForAllUsed , RwFreeListDestroy , RwFreeListPurgeAllFreeLists

RwInt32 RwFreeListPurgeAllFreeLists (  void    ) 
 

RwFreeListPurgeAllFreeLists is used to purge all free lists in the system. It returns the amount of memory freed as a result.

Returns:
Returns the amount of memory freed if successful, or -1 if there is an error.
See also:
RwFreeListAlloc , RwFreeListCreate , RwFreeListFree , RwFreeListPurge , RwFreeListDestroy , RwFreeListForAllUsed

void RwFreeListSetFlags (  RwFreeList *    freeList,
RwUInt32    flags
) 
 

RwFreeListSetFlags Set the allocation mode of a freelist. Currently the only flag available is rwFREELISTFLAG_FREEBLOCKS. This flag is set by default and causes free blocks to be deallocated from the heap as soon as a freelist entry is freed. If this flag is cleared all free freelist blocks will remain.

Parameters:
freeList  Pointer to the free list to change the flags on.
flags  The new flags for the free list.
Returns:
Nothing
See also:
RwFreeListGetFlags , RwFreeListAlloc , RwFreeListFree

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