Functions to load GRF files. More...

#include <stdint.h>
#include <stdio.h>

Data Structures
struct	GRFHeader
	Header chunk of a GRF file. More...

Enumerations
enum	GRFError { GRF_NO_ERROR = 0 , GRF_NULL_POINTER = -1 , GRF_FILE_NOT_OPENED = -2 , GRF_FILE_NOT_READ = -3 , GRF_INVALID_ID_RIFF = -4 , GRF_INVALID_ID_GRF = -5 , GRF_INCONSISTENT_SIZES = -6 , GRF_NOT_ENOUGH_MEMORY = -7 , GRF_UNKNOWN_COMPRESSION = -8 }
	Possible errors that can happen while reading GRF files. More...

enum	GRFTextureTypes
	Special values for the GFX attribute field for NDS textures.

Functions
GRFError	grfLoadFile (FILE file, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize)
	From a FILE* to a GRF file, extract all data and allocate memory for it. More...

GRFError	grfLoadFileEx (FILE file, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize, void *mtilDst, size_t mtilSize, void *mmapDst, size_t mmapSize)
	From a FILE* to a GRF file, extract all data and allocate memory for it. More...

GRFError	grfLoadMem (const void src, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize)
	From a GRF file in RAM, extract all data and allocate memory for it. More...

GRFError	grfLoadMemEx (const void src, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize, void *mtilDst, size_t mtilSize, void *mmapDst, size_t mmapSize)
	From a GRF file in RAM, extract all data and allocate memory for it. More...

GRFError	grfLoadPath (const char path, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize)
	From a path to a GRF file, extract all data and allocate memory for it. More...

GRFError	grfLoadPathEx (const char path, GRFHeader header, void *gfxDst, size_t gfxSize, void *mapDst, size_t mapSize, void *palDst, size_t palSize, void *mtilDst, size_t mtilSize, void *mmapDst, size_t mmapSize)
	From a path to a GRF file, extract all data and allocate memory for it. More...

Detailed Description

Functions to load GRF files.

This is one of the formats that GRIT can generate, and it's useful because it packs multiple graphics blobs as well as metadata such as compression type and size.

GRF files may contain compressed and uncompressed data blobs in the same file. Compressed blobs may use different compression algorithms. Check the documentation of decompress() for more information about the supported formats. Note that all compression formats supported by grit are also supported by decompress().

Check https://www.coranac.com/man/grit/html/grit.htm for more information.

Enumeration Type Documentation

◆ GRFError

enum GRFError

Possible errors that can happen while reading GRF files.

Enumerator
GRF_NO_ERROR	No error happened.
GRF_NULL_POINTER	NULL pointer passed as argument.
GRF_FILE_NOT_OPENED	Failed to open file with fopen()
GRF_FILE_NOT_READ	Failed to read file.
GRF_INVALID_ID_RIFF	Chunk ID "RIFF" not found.
GRF_INVALID_ID_GRF	Chunk ID "GRF " not found.
GRF_INCONSISTENT_SIZES	Sizes of "RIFF" and "GRF " don't match.
GRF_NOT_ENOUGH_MEMORY	Not enough memory for malloc()
GRF_UNKNOWN_COMPRESSION	Unknown graphics compression format.

Function Documentation

◆ grfLoadFile()

GRFError grfLoadFile	(	FILE *	file,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize
	)

From a FILE* to a GRF file, extract all data and allocate memory for it.

Note: Check grfLoadMemEx() for details about how to use this function.

Parameters

file	FILE handle to the GRF file.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.

Returns: Returns 0 on success, a negative number on error.

◆ grfLoadFileEx()

GRFError grfLoadFileEx	(	FILE *	file,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize,
		void **	mtilDst,
		size_t *	mtilSize,
		void **	mmapDst,
		size_t *	mmapSize
	)

From a FILE* to a GRF file, extract all data and allocate memory for it.

Note: Check grfLoadMemEx() for details about how to use this function.

Parameters

file	FILE handle to the GRF file.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.
mtilDst	Pointer to pointer to load metatile data.
mtilSize	Location to store the metatile data size.
mmapDst	Pointer to pointer to load metamap data.
mmapSize	Location to store the metamap data size.

Returns: Returns 0 on success, a negative number on error.

◆ grfLoadMem()

GRFError grfLoadMem	(	const void *	src,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize
	)

From a GRF file in RAM, extract all data and allocate memory for it.

Note: Check grfLoadMemEx() for details about how to use this function.

Parameters

src	Pointer to the GRF file in RAM.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.

Returns: Returns 0 on success, a negative number on error.

◆ grfLoadMemEx()

GRFError grfLoadMemEx	(	const void *	src,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize,
		void **	mtilDst,
		size_t *	mtilSize,
		void **	mmapDst,
		size_t *	mmapSize
	)

From a GRF file in RAM, extract all data and allocate memory for it.

This function lets you decide which components of the GRF file have to be loaded and whether they have to be loaded to a hardcoded address or if the function needs to allocate memory for them. Values that aren't needed can be ignored by passing NULL to the specific argument of the function.

Note that Huffman decompression isn't VRAM-safe. RLE and LZ77 are VRAM-safe. If using Huffman compression with your GRF files, don't hardcode the destination address to VRAM.

Let function allocate memory and inform you of the size of the buffer:

void *gfxDst = NULL;
size_t gfxSize;
GRFError ret = grfLoadMemEx(grf_file, NULL, &gfxDst, &gfxSize, NULL, NULL,
                            NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
if (ret == GRF_NO_ERROR)
{
    // Use data here...
}
free(gfxDst);

Hardcode destination address, ignore resulting size:

uint16_t palette[256];
void *palDst = (void *)&palette[0]; // Load data to the array
GRFError ret = grfLoadMemEx(grf_file, NULL, NULL, NULL, NULL, NULL,
                            &palDst, NULL, NULL, NULL, NULL, NULL);
if (ret == GRF_NO_ERROR)
{
    // Use data here...
}

Example of reading the header:

GRFHeader header = {0};
GRFError ret = grfLoadMemEx(grf_file, &header, NULL, NULL, NULL, NULL,
                            NULL, NULL, NULL, NULL, NULL, NULL);
if (ret == GRF_NO_ERROR)
{
    // Use data here...
}

Parameters

src	Pointer to the GRF file in RAM.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.
mtilDst	Pointer to pointer to load metatile data.
mtilSize	Location to store the metatile data size.
mmapDst	Pointer to pointer to load metamap data.
mmapSize	Location to store the metamap data size.

Returns: Returns 0 on success, a negative number on error.

◆ grfLoadPath()

GRFError grfLoadPath	(	const char *	path,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize
	)

From a path to a GRF file, extract all data and allocate memory for it.

Note: Check grfLoadMemEx() for details about how to use this function.

Parameters

path	Path to the GRF file in the filesystem.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.

Returns: Returns 0 on success, a negative number on error.

◆ grfLoadPathEx()

GRFError grfLoadPathEx	(	const char *	path,
		GRFHeader *	header,
		void **	gfxDst,
		size_t *	gfxSize,
		void **	mapDst,
		size_t *	mapSize,
		void **	palDst,
		size_t *	palSize,
		void **	mtilDst,
		size_t *	mtilSize,
		void **	mmapDst,
		size_t *	mmapSize
	)

From a path to a GRF file, extract all data and allocate memory for it.

Note: Check grfLoadMemEx() for details about how to use this function.

Parameters

path	Path to the GRF file in the filesystem.
header	Pointer to a header structure to be filled.
gfxDst	Pointer to pointer to load graphics data.
gfxSize	Location to store the graphics data size.
mapDst	Pointer to pointer to load map data.
mapSize	Location to store the map data size.
palDst	Pointer to pointer to load palette data.
palSize	Location to store the palette data size.
mtilDst	Pointer to pointer to load metatile data.
mtilSize	Location to store the metatile data size.
mmapDst	Pointer to pointer to load metamap data.
mmapSize	Location to store the metamap data size.

Returns: Returns 0 on success, a negative number on error.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ GRFError

Function Documentation

◆ grfLoadFile()

◆ grfLoadFileEx()

◆ grfLoadMem()

◆ grfLoadMemEx()

◆ grfLoadPath()

◆ grfLoadPathEx()