LoadFile

Loads a cel file from disk

Synopsis

void * LoadFile (char *fileName, long *fileSizePtr, uint32 memTypeBits)

Description

Loads an entire file into a buffer in memory. This function allocates a buffer, loads the file into it, and returns a pointer to the allocated buffer. The size of the file is returned into a longword via the fileSizePtr parameter.

Note that the buffer is allocated to an even multiple of the device's blocksize (2 KB for CD-ROM and the Mac link), and thus may be slightly larger than the actual size of the file. The file size returned via fileSizePtr, however, reflects the actual size of the file without the extra padding required to achieve an integral device block size.

This function is approximately 3-4 times as fast as the old method of loading a file using GetFileSize(), allocating a buffer, calling ReadFile(). When you are finished with the file, use UnloadFile() to free the file buffer.

If an error returns, the function return value is NULL and the longword at the *fileSizePtr contains the error status. A return value of NULL with an error status of zero indicates that the file exists but contains no data; in this cas, no buffer was allocated.

Arguments

fileName: Pointer to the file name string.

fileSizePtr: Pointer to a longword which receives the length of file (in bytes). If you don't need the length, a NULL pointer can be passed for this parameter.

memTypeBits: Type of memory to use when loading the file; usually MEMTYPE_ANY or MEMTYPE_VRAM.

Return Value

Pointer to loaded file in memory, or NULL if an error occurred.

Associated Files