Integerate into a project

Getting the files into the project

You have to write a valid commandline first, to let katie create the source code and header files of the concatenated data. You can read how to use and control katie via commandline parameters in the How to use the program section.

Once katie generated the source code files (.c or .s), they should be compiled and linked into the project. How to compile and link these files depend on your development kit and I won't describe this.

Integrate into source code

I assume you're writing the project in C or C++ and I recommend to pass --output-h-filename to katie, so it creates a C/C++ header file with identifiers to each added resource.

The generated header file also provides service macros to access each of the added resources. Unless you changed the default names, you'll find the following macros in the generated header file:

#define ResData(_identifier)                     ((const void*)&__ResourceData__[_identifier])
#define ResData8(_identifier)                    ((const unsigned char*)&__ResourceData__[_identifier])
#define ResData8X(_identifier, _index)           ((const unsigned char*)&__ResourceData__[(_identifier)+(_index)])
#define ResData16(_identifier)                   ((const unsigned short*)&__ResourceData__[_identifier])
#define ResData16X(_identifier, _index)          ((const unsigned short*)&__ResourceData__[(_identifier)+((_index)<<1)])
#define ResData32(_identifier)                   ((const unsigned long*)&__ResourceData__[_identifier])
#define ResData32X(_identifier, _index)          ((const unsigned long*)&__ResourceData__[(_identifier)+((_index)<<2)])
#define ResDataType(_type, _identifier)          ((const _type*)&__ResourceData__[_identifier])
#define ResDataTypeX(_type, _identifier, _index) ((const _type*)&__ResourceData__[(_identifier)+((_index)*sizeof(_type)])

The preceding macros are intended only to provide an easy to use mechanism to get a pointer to the resource in question. They are splitted into different macros which are basically only return a different type of pointer.

Beside the ResData macros, katie also generates numerical constants, represented by defines, for the size of each resource. For RES_PLAYER_RAW, the following defines are also available:

RES_PLAYER_RAW_SIZE
RES_PLAYER_RAW_SIZEPADDED
RES_PLAYER_RAW_SIZE16
RES_PLAYER_RAW_SIZE16PADDED
RES_PLAYER_RAW_SIZE32
RES_PLAYER_RAW_SIZE32PADDED

RES_PLAYER_RAW_SIZE represents the size of the resource, identified by RES_PLAYER_RAW, specified in bytes. RES_PLAYER_RAW_SIZE16 represents the size specified in 16bit words and RES_PLAYER_RAW_SIZE32 the size in 32bit words. Furthermore the size defines are also available with the padded filesize. That is, the filesize filled with zeros until it is a multiple of the alignment (--output-align).

If you want to copy the resource specified by RES_PLAYER_RAW to a memory location specified by pDest using the standard C lib function memcpy, you would do it as follows:

memcpy((void*)pDest, ResData(RES_PLAYER_RAW), RES_PLAYER_RAW_SIZE);

The ResDataType macro can be used to cast the resource data to a given datatype:

struct PlayerData
{
    int type;
    int x;
    int y;
    int z;
};

int type;

// own typecasting
type = ((PlayerData*)ResData(RES_PLAYER_RAW))->type;

// using ResDataType macro
type = ResDataType(PlayerData, RES_PLAYER_RAW)->type;
This is not the best example, but you get the point.
Generated on Sat Aug 12 13:40:21 2006 for Katie by  doxygen 1.4.7