Rez file manager. More...
Classes | |
struct | FilenameToRezNum_t |
Sorted list of filenames. More... | |
struct | FileRezEntry_t |
Data image of a resource entry. More... | |
struct | FileRezGroup_t |
Data image of a resource group. More... | |
struct | RezEntry_t |
Data to describe each individual resource in memory. More... | |
struct | RezGroup_t |
Data to describe a group of resources in memory. More... | |
struct | RootHeader_t |
Data image for the start of a Rez file. More... | |
Public Types | |
enum | { MAXCODECS =3 , ROOTHEADERSIZE = static_cast<int>(sizeof(uint32_t)*2)+(MAXCODECS*4)+4 , ENTRYFLAGSNAMEOFFSETMASK =0x0007FFFF , ENTRYFLAGSDECOMPMASK =0x00180000 , ENTRYFLAGSHIGHMEMORY =0x00200000 , ENTRYFLAGSREFCOUNT =0xFF000000 , ENTRYFLAGSREFSHIFT =24 , ENTRYFLAGSREFADD =(1<<ENTRYFLAGSREFSHIFT) , ENTRYFLAGSDECOMPSHIFT =19 } |
Public Member Functions | |
RezFile (MemoryManagerHandle *pMemoryManager) | |
Initialize the RezFile class to a power up state. | |
~RezFile () | |
Dispose of all allocated resources. | |
uint_t | Init (const char *pFileName, uint32_t uStartOffset=0) |
Open a resource file for reading. | |
void | Shutdown (void) |
Dispose of the contents of a resource file. | |
void | PurgeCache (void) |
Release all cached memory. | |
uint_t | SetExternalFlag (uint_t bEnable) |
Enable or disable reading external files. | |
uint_t | GetExternalFlag (void) const |
Return the state of reading external files. | |
void | LogDecompressor (uint_t uCompressID, Decompress *pProc) |
Log a resource decompressor. | |
uint_t | GetRezNum (const char *pRezName) const |
Given a resource name, return the resource number. | |
uint_t | GetName (uint_t uRezNum, char *pBuffer, uintptr_t uBufferSize) const |
Return the filename associated with a resource number. | |
uint_t | AddName (const char *pRezName) |
Add a new filename to be managed by the RezFile. | |
void | Remove (uint_t uRezNum) |
Remove a resource from the rez file. | |
void | Remove (const char *pRezName) |
Remove a resource from the rez file by name. | |
const FilenameToRezNum_t * | GetNameArray (void) const |
Get the pointer to the list of filenames managed by the RezFile. | |
uint_t | GetNameArraySize (void) const |
Return the number of elements returned by Burger::RezFile::GetNameArray(void) const. | |
uint_t | GetLowestRezNum (void) const |
Return the lowest valid resource number. | |
uint_t | GetHighestRezNum (void) const |
Return the highest valid resource number. | |
uintptr_t | GetSize (uint_t uRezNum) const |
Return the size of bytes of the resource. | |
uintptr_t | GetCompressedSize (uint_t uRezNum) const |
Return the size of bytes of the resource. | |
uint_t | GetIDFromHandle (const void **ppRez, uint_t *pRezNum, char *pBuffer, uintptr_t uBufferSize) const |
Find a resource by a data handle. | |
uint_t | GetIDFromPointer (const void *pRez, uint_t *pRezNum, char *pBuffer, uintptr_t uBufferSize) const |
Find a resource by a data pointer. | |
void ** | LoadHandle (uint_t uRezNum, uint_t *pLoadedFlag=0) |
Load in a resource and return the handle. | |
void ** | LoadHandle (const char *pRezName, uint_t *pLoadedFlag=0) |
Load in a resource and return the handle. | |
void * | Load (uint_t uRezNum, uint_t *pLoadedFlag=0) |
Load in a resource. | |
void * | Load (const char *pRezName, uint_t *pLoadedFlag=0) |
Load in a resource. | |
uint_t | Read (uint_t uRezNum, void *pBuffer, uintptr_t uBufferSize) |
Load in a resource into a static buffer. | |
uint_t | Read (const char *pRezName, void *pBuffer, uintptr_t uBufferSize) |
Load in a resource into a static buffer. | |
void | Release (uint_t uRezNum) |
Reduce the data reference count. | |
void | Release (const char *pRezName) |
Reduce the data reference count. | |
void | Kill (uint_t uRezNum) |
Destroy the data associated with a resource. | |
void | Kill (const char *pRezName) |
Destroy the data associated with a resource. | |
void | Detach (uint_t uRezNum) |
Detach the data associated with a resource. | |
void | Detach (const char *pRezName) |
Detach the data associated with a resource. | |
void | Preload (uint_t uRezNum) |
Preload in a resource. | |
void | Preload (const char *pRezName) |
Preload in a resource. | |
Static Public Member Functions | |
static RezFile * | New (MemoryManagerHandle *pMemoryManager, const char *pFileName, uint32_t uStartOffset=0) |
Create a new RezFile instance. | |
Static Public Attributes | |
static const char | g_RezFileSignature [4] = {'B','R','G','R'} |
'BRGR' | |
static const uint_t | INVALIDREZNUM = static_cast<uint_t>(-1) |
Illegal resource number, used as an error code. | |
Private Types | |
enum | { MAXBUFFER = 65536 , REZOFFSETFIXED =0x80000000 , REZOFFSETDECOMPMASK =0x60000000 , REZOFFSETMASK =0x1FFFFFFF , REZOFFSETDECOMPSHIFT =29 , ENTRYFLAGSTESTED =0x00000001 , ENTRYFLAGSFILEFOUND =0x0000002 , SWAPENDIAN =0x01 , OLDFORMAT =0x02 } |
Private Member Functions | |
RezFile (const RezFile &)=delete | |
RezFile & | operator= (const RezFile &)=delete |
RezFile (RezFile &&)=delete | |
RezFile & | operator= (RezFile &&)=delete |
uintptr_t | GetRezGroupBytes (void) const |
Calculate the number of bytes m_pGroups occupies. | |
void | AdjustNamePointers (uintptr_t uAdjust) |
Adjust pointers for text strings. | |
RezEntry_t * | Find (uint_t uRezNum) const |
Locate a resource entry by using a resource number. | |
uint_t | FindName (const char *pRezName, FilenameToRezNum_t **ppOutput) const |
Find a resource number from a resource name. | |
void | ProcessRezNames (void) |
Create a hash table for all of the filenames. | |
void | FixupFilenames (char *pText) |
Compact and sort the filenames when a name is inserted or deleted. | |
Static Private Member Functions | |
static int | QSortNames (const void *pFirst, const void *pSecond) |
Used to sort between filenames. | |
static RezGroup_t * | ParseRezFileHeader (const uint8_t *pData, const RootHeader_t *pHeader, uint_t uSwapFlag, uint32_t uStartOffset) |
Create the in memory rez file dictionary from a file image. | |
Private Attributes | |
Decompress * | m_Decompressors [MAXCODECS] |
Decompressor functions. | |
File | m_File |
Open file reference. | |
MemoryManagerHandle * | m_pMemoryManager |
Pointer to the handle based memory manager to use. | |
uint32_t | m_uGroupCount |
Number of resource groups. | |
uint32_t | m_uRezNameCount |
Number of resource names in m_pRezNames. | |
RezGroup_t * | m_pGroups |
Array of resource groups. | |
FilenameToRezNum_t * | m_pRezNames |
Pointer to sorted resource names if present. | |
uint_t | m_bExternalFileEnabled |
TRUE if external file access is enabled | |
Rez file manager.
Using the tool MakeRez, an archive file can be generated and quickly used to access data used by a game or application
The manager has the ability to load compressed data and decompress it on the fly if need be. The high level code has no need to know where the data is coming from and how it's cached in memory for performance
Enumerator | |
---|---|
MAXCODECS | Maximum number of compression codecs available. |
ROOTHEADERSIZE | Size of RootHeader_t on disk. |
ENTRYFLAGSNAMEOFFSETMASK | Filename offset. |
ENTRYFLAGSDECOMPMASK | Mask for decompressors (2 bits) |
ENTRYFLAGSHIGHMEMORY | True if load in fixed memory. |
ENTRYFLAGSREFCOUNT | Refcount mask. |
ENTRYFLAGSREFSHIFT | Bits to shift for the refcount. |
ENTRYFLAGSREFADD | 1 in refcount format |
ENTRYFLAGSDECOMPSHIFT | Shift value to get the decompression type index (2 bits) |
|
privatedelete |
Burger::RezFile::RezFile | ( | Burger::MemoryManagerHandle * | pMemoryManager | ) |
Initialize the RezFile class to a power up state.
This constructor initializes the variables to ensure the structure doesn't have dangling pointers
pMemoryManager | Pointer to a valid handle based memory manager |
Burger::RezFile::~RezFile | ( | ) |
Dispose of all allocated resources.
Close any open files and release all memory. Any pointers that were given to the application from this RezFile will now be considered invalid.
uint_t BURGER_API Burger::RezFile::AddName | ( | const char * | pRezName | ) |
Add a new filename to be managed by the RezFile.
If the named resource doesn't already exist in the resource dictionary, insert it into the first free slot.
There is no check performed to see if the file exists. The name is added to the dictionary.
|
private |
Adjust pointers for text strings.
Traverse all of the in memory RezGroup_t structures, adjust the offsets for all the string pointers based on the new data padding difference from the file image and the in memory image
uAdjust | Number of bytes to add to all of the string offsets |
void BURGER_API Burger::RezFile::Detach | ( | const char * | pRezName | ) |
Detach the data associated with a resource.
Release responsibility for this resource to the application.
pRezName | Resource name |
void BURGER_API Burger::RezFile::Detach | ( | uint_t | uRezNum | ) |
Detach the data associated with a resource.
Release responsibility for this resource to the application.
uRezNum | Resource number |
|
private |
Locate a resource entry by using a resource number.
Scan for a resource entry in the resource map.
uRezNum | Resource item number |
|
private |
Find a resource number from a resource name.
Using a resource name list (Sorted so that a binary search can be performed), look if there is a match in the resource list Return TRUE if an entry was found, FALSE if there was no match. However, if FALSE is returned, then the entry that will FOLLOW the string is returned for new entry insertion
pRezName | Pointer to a "C" string of the requested filename |
ppOutput | Pointer to accept the pointer to the matching Burger::RezFile::FilenameToRezNum_t structure |
|
private |
Compact and sort the filenames when a name is inserted or deleted.
The filenames are stored sorted to enable a quick lookup via a binary search. When filenames are added or removed at runtime, a fixup may be necessary.
pText | Pointer to the array of filenames to insert or compact |
uintptr_t BURGER_API Burger::RezFile::GetCompressedSize | ( | uint_t | uRezNum | ) | const |
Return the size of bytes of the resource.
uRezNum | Resource number |
Return the state of reading external files.
uint_t BURGER_API Burger::RezFile::GetHighestRezNum | ( | void | ) | const |
Return the highest valid resource number.
uint_t BURGER_API Burger::RezFile::GetIDFromHandle | ( | const void ** | ppRez, |
uint_t * | pRezNum, | ||
char * | pBuffer, | ||
uintptr_t | uBufferSize ) const |
Find a resource by a data handle.
Given a handle, scan the resource map to see if it is under Resource manager control. If so, return the resource ID number and the resource name. Return error code if not present (Right now it's TRUE), otherwise return zero for no error if I found it.
ppRez | Handle to the memory to check for |
pRezNum | Pointer to a uint_t to receive the valid resource number |
pBuffer | Pointer to a buffer to hold the name of the resource |
uBufferSize | Number of bytes in size for the resource name buffer |
uint_t BURGER_API Burger::RezFile::GetIDFromPointer | ( | const void * | pRez, |
uint_t * | pRezNum, | ||
char * | pBuffer, | ||
uintptr_t | uBufferSize ) const |
Find a resource by a data pointer.
Given a pointer, scan the resource map to see if it is under Resource manager control. If so, return the resource ID number and the resource name. Return error code if not present (Right now it's TRUE), otherwise return zero for no error if I found it.
pRez | Pointer to the memory to check for |
pRezNum | Pointer to a uint_t to receive the valid resource number |
pBuffer | Pointer to a buffer to hold the name of the resource |
uBufferSize | Number of bytes in size for the resource name buffer |
uint_t BURGER_API Burger::RezFile::GetLowestRezNum | ( | void | ) | const |
Return the lowest valid resource number.
uint_t BURGER_API Burger::RezFile::GetName | ( | uint_t | uRezNum, |
char * | pBuffer, | ||
uintptr_t | uBufferSize ) const |
Return the filename associated with a resource number.
uRezNum | Resource number |
pBuffer | Pointer to a buffer to receive the filename string |
uBufferSize | Size, in bytes, of the buffer to receive the filename string |
|
inline |
Get the pointer to the list of filenames managed by the RezFile.
Return the number of elements returned by Burger::RezFile::GetNameArray(void) const.
|
private |
Calculate the number of bytes m_pGroups occupies.
By traversing a valid RezGroup_t, determine the number of bytes it would take to store a RezGroup_t structure (Used for rebuilding the structure when an entry is added or removed)
uint_t BURGER_API Burger::RezFile::GetRezNum | ( | const char * | pRezName | ) | const |
Given a resource name, return the resource number.
Scan the entries for the filename and return the resource entry number
pRezName | Pointer to a "C" string with the filename to locate in the rez file |
uintptr_t BURGER_API Burger::RezFile::GetSize | ( | uint_t | uRezNum | ) | const |
Return the size of bytes of the resource.
uRezNum | Resource number |
uint_t BURGER_API Burger::RezFile::Init | ( | const char * | pFileName, |
uint32_t | uStartOffset = 0 ) |
Open a resource file for reading.
pFileName | Pointer to "C" string of the filename to open |
uStartOffset | Offset from the start of the file where the rezfile image resides. Normally zero. |
void BURGER_API Burger::RezFile::Kill | ( | const char * | pRezName | ) |
Destroy the data associated with a resource.
Release all memory associated with this specific resource
pRezName | Resource name |
void BURGER_API Burger::RezFile::Kill | ( | uint_t | uRezNum | ) |
Destroy the data associated with a resource.
Release all memory associated with this specific resource
uRezNum | Resource number |
void *BURGER_API Burger::RezFile::Load | ( | const char * | pRezName, |
uint_t * | pLoadedFlag = 0 ) |
void *BURGER_API Burger::RezFile::Load | ( | uint_t | uRezNum, |
uint_t * | pLoadedFlag = 0 ) |
void **BURGER_API Burger::RezFile::LoadHandle | ( | const char * | pRezName, |
uint_t * | pLoadedFlag = 0 ) |
void **BURGER_API Burger::RezFile::LoadHandle | ( | uint_t | uRezNum, |
uint_t * | pLoadedFlag = 0 ) |
void BURGER_API Burger::RezFile::LogDecompressor | ( | uint_t | uCompressID, |
Burger::Decompress * | pProc ) |
Log a resource decompressor.
uCompressID | Compressor ID (1-3) |
pProc | Pointer to a decompression codec |
|
static |
Create a new RezFile instance.
Allocate memory using Burger::Alloc() and initialize a RezFile with it.
pMemoryManager | Pointer to a valid handle based memory manager |
pFileName | Pointer to a "C" string of a filename to a rez file |
uStartOffset | Offset in bytes from the start of the file where the rezfile image resides. Normally this is zero. |
|
staticprivate |
Create the in memory rez file dictionary from a file image.
pData | Pointer to the Rez File image |
pHeader | Pointer to the parsed file header |
uSwapFlag | TRUE if endian should be swapped |
uStartOffset | Number of bytes the header was from the start of file (For data index offset adjustments) |
void BURGER_API Burger::RezFile::Preload | ( | const char * | pRezName | ) |
Preload in a resource.
Load in the resource data and then immediate release it and keep it in the cache
If the resource name is not in the dictionary, add it.
pRezName | Resource name |
void BURGER_API Burger::RezFile::Preload | ( | uint_t | uRezNum | ) |
Preload in a resource.
Load in the resource data and then immediate release it and keep it in the cache
uRezNum | Resource number |
|
private |
Create a hash table for all of the filenames.
Release the previous m_pRezNames array and create a new one from scratch. m_pRezNames contains a sorted filename lookup list that is used by Burger::RezFile::FindName(const char *,RezFile::FilenameToRezNum_t **) const to quickly look up a resource entry
void BURGER_API Burger::RezFile::PurgeCache | ( | void | ) |
Release all cached memory.
Scan all entries in the resource map and dispose of all the entries that loaded in the cache but not actually discarded. I will only dispose of unlocked purgable handles This is useful before a level or map load to help prevent memory fragmentation in low memory situations. Not really needed to call this routine unless memory is a a premium.
|
staticprivate |
Used to sort between filenames.
Called by qsort()
pFirst | First FilenameToRezNum_t * to compare |
pSecond | Second FilenameToRezNum_t * to compare |
uint_t BURGER_API Burger::RezFile::Read | ( | const char * | pRezName, |
void * | pBuffer, | ||
uintptr_t | uBufferSize ) |
Load in a resource into a static buffer.
pRezName | Resource name |
pBuffer | Pointer to the buffer to copy the data to |
uBufferSize | Number of bytes for the buffer to store the data into |
uint_t BURGER_API Burger::RezFile::Read | ( | uint_t | uRezNum, |
void * | pBuffer, | ||
uintptr_t | uBufferSize ) |
Load in a resource into a static buffer.
uRezNum | Resource number |
pBuffer | Pointer to the buffer to copy the data to |
uBufferSize | Number of bytes for the buffer to store the data into |
void BURGER_API Burger::RezFile::Release | ( | const char * | pRezName | ) |
Reduce the data reference count.
Release a resource by marking it purgeable and leave it in the cache.
pRezName | Resource name |
void BURGER_API Burger::RezFile::Release | ( | uint_t | uRezNum | ) |
Reduce the data reference count.
Release a resource by marking it purgeable and leave it in the cache.
uRezNum | Resource number |
void BURGER_API Burger::RezFile::Remove | ( | const char * | pRezName | ) |
Remove a resource from the rez file by name.
pRezName | Pointer to a "C" string of the name of the resource to remove |
void BURGER_API Burger::RezFile::Remove | ( | uint_t | uRezNum | ) |
Remove a resource from the rez file.
Look for the entry and if found, it will be removed from the resource dictionary.
uRezNum | Number of the resource to remove |
uint_t BURGER_API Burger::RezFile::SetExternalFlag | ( | uint_t | bEnable | ) |
Enable or disable reading external files.
Set the new state of the reading of external file and return the current state of the flag before the modification
void BURGER_API Burger::RezFile::Shutdown | ( | void | ) |
Dispose of the contents of a resource file.
Release all resources allocated by a resource file. All pointers that have been given to the application are now all invalid.
|
static |
Illegal resource number, used as an error code.
|
private |
Decompressor functions.
|
private |
Open file reference.
|
private |
Array of resource groups.
|
private |
Pointer to the handle based memory manager to use.
|
private |
Pointer to sorted resource names if present.
|
private |
Number of resource groups.
|
private |
Number of resource names in m_pRezNames.