RESOURCE

Resource File System. More...

Data Structures
struct	T_loadLinkTag

Typedefs
typedef struct T_loadLinkTag	T_loadLink

Functions
T_byte8 *	JustEnd (T_byte8 *p_string)
T_void	ResourceCheckByPtr (T_byte8 *p_resData)
T_void	ResourceClose (T_resourceFile resourceFile)
T_void	ResourceDumpDir (FILE *fp, T_resourceEntry *p_entry)
T_void	ResourceDumpIndex (T_resourceFile resourceFile)
T_resource	ResourceFind (T_resourceFile resourceFile, T_byte8 *p_resourceName)
T_byte8 *	ResourceGetName (T_void *p_data)
T_word32	ResourceGetSize (T_resource resource)
T_void *	ResourceLock (T_resource resource)
T_resourceFile	ResourceOpen (T_byte8 *filename)
T_void	ResourcePrint (FILE *fp, T_resource res)
T_void	ResourceUnfind (T_resource res)
T_void	ResourceUnlock (T_resource resource)

Detailed Description

Resource File System.

Resource files are any .RES file that contains pictures, sounds, animations etc. Resources are also a bit sneakier because they are locked in memory when needed and unlocked when not needed. But they are not discarded from memory immediately. If memory becomes tight, they are unloaded. If memory does not become tight, on the next lock, they are just marked as locked and are ready to use immediately. Resources are loaded on an as needed basis. A map load will typically walk through all the resources desired and lock them in.

See Also

http://www.amuletsandarmor.com/AALicense.txt

Typedef Documentation

typedef struct T_loadLinkTag T_loadLink

Function Documentation

T_byte8* JustEnd

(

T_byte8 *

p_string)

T_void ResourceCheckByPtr

(

T_byte8 *

p_resData)

ResourceCheckByPtr is a debugging routine used to validate that the given pointer points to data that is a resource block.

Parameters

p_resData

– Pointer to res data (not res handle)

T_void ResourceClose

(

T_resourceFile

resourceFile)

ResourceClose is used to close out the resource and remove all the blocks in memory. You cannot call this routine on a resource that still has locked resource blocks, but you can call it on a resource that has discarded blocks.

Parameters

resourceFile

– handle to resource file to close

T_void ResourceDumpDir	(	FILE *	fp,
		T_resourceEntry *	p_entry
	)

For debuggine purposes only, this can be used to dump out a list of indexes for a particular resource file. Places list in external file, "RESOURDB.TXT"

Parameters

fp	– file to scan through index.
p_entry	– Starting entry in resource

T_void ResourceDumpIndex

(

T_resourceFile

resourceFile)

T_resource ResourceFind	(	T_resourceFile	resourceFile,
		T_byte8 *	p_resourceName
	)

ResourceFind is used to find the index into the current resource file for a particular resource block (referenced by the given name). You use the returned resource handle to lock and unlock the resource. (Unlocking the resource will give you a pointer to where it is located).

NOTE: Speed is the first problem. Calling functions should try to use this routine rarely. Second, the resource file MUST have it's entries in alpabetical order.

Parameters

resourceFile	– handle to resource file
p_resourceName	– Pointer to resource block name

Returns

Handle to resource that is found, or returns RESOURCE_BAD.

T_byte8* ResourceGetName

(

T_void *

p_data)

ResourceGetName finds the name that goes with the corresponding data pointer.

Parameters

p_data

– Pointer to data to find name of

Returns

Pointer to name

T_word32 ResourceGetSize

(

T_resource

resource)

ResourceGetSize returns the size of the given resource.

Parameters

resource

– Resource to get the size of

Returns

Size of resource

T_void* ResourceLock

(

T_resource

resource)

If you need to get a resource, you should call ResourceLock first. If you don't already have a resource handle, you need to call ResourceFind first. You then can call this routine to "lock" the block at a certain memory location. This routine will take care of all cases of where the block may originally be (on disk, in memory, or discarded).

NOTE: Not a whole lot.

Parameters

resource

– handle to resource as returned by ResourceFind()

Returns

Pointer to memory block that is locked.

T_resourceFile ResourceOpen

(

T_byte8 *

filename)

Open a resource file for locking and unlocking of blocks. The resource file allows you to have several "files" grouped together into one real world file. In addition, it also makes sure that blocks stay in memory as long as possible (based on the computer's available memory).

NOTE: The biggest problem is not in the opening file, it is how the items are ordered in the resource. All names used in a resource should alphabetical, or else searches for items may fail.

Parameters

filename

– Name of resource file (may include the path to the file).

Returns

handle to resource block.

T_void ResourcePrint	(	FILE *	fp,
		T_resource	res
	)

ResourcePrint prints out the information tied to the given resource to the given output.

Parameters

fp	– File to output picture info
res	– Resource to print

T_void ResourceUnfind

(

T_resource

res)

ResourceUnfind is called after a resource has been used and no longer needs to be valid. In effect, this routine closes out any items that might be locked from this resource.

NOTE: Given T_resource must only have been Unfind once. T_resource cannot be locked.

Parameters

res	– resource to unfind

T_void ResourceUnlock

(

T_resource

resource)

Unlock a resource that is in memory. This doesn't actually destory the resource. Instead the resource goes on the discardable memory list that allows it to be destroyed when more memory is needed. ResourceLock later to get the block back (or load from disk). Note, however, that if a resource has been multiply locked, there has to be an equal number of unlocks to allow the block to be discarded.

Parameters

resource

– Resource you no longer need.