Commandline Options

Katie supports a couple of options to control the program behaviour. Here is a list of all available commandline options:




--input-filelist

--input-filelist <name>

The --input-filelist option must be followed by the filelist filename.

This option can be used to specify an additional filelist which will katie read in and use its content as input files. The filelist must be a plain textfile. C and C++ style comments are supported inside the filelist. If a filename contains spaces, it must be set in double quotes. Wildcards are not supported. Here is an example:

/*
  Author.: Katie Kate
  Date...: 2006-05-09
  Purpose: This filelist contains all graphic files from our awesome game.
*/

// Data for Level 1 starts here
level001.raw
level001.pal
level001.map

// Data for Level 2 starts here
level002.raw
level002.pal
level002.map
"level002 huge endboss.raw" // slap the artist, we don't want spaces in filenames!!!

// and so on...

--output-filename

--output-filename <name>

Filenames of all output files. This option sets the filenames of all supported output formats. The --output-filename option must be followed by the new output filename. The default name is ResourceData with the following file extension appended automatically:

ARM assembler = .s
C/C++ Source  = .c
C/C++ Header  = .h
RAW/Binary    = .raw

You can specify individual filenames for each output-format, which can be quite useful if you want them to be stored in different directories. Use the --ouput-*-filename options to specify individual filenames.

See also:
--output-raw-filename, --output-asm-arm-filename, --output-c-filename, --output-h-filename

--output-arrayname

--output-arrayname <name>

This option can be used to set the arrayname/.global of the concatenated output data, when generating sourcecode. The --output-arrayname option must be followed by the new arrayname. The default name is __ResourceData__.

--output-align

--output-align <n>

The alignment option specifies on what boundary each file should be aligned inside the concatenamed data. The --output-align option must be followed by the new alignment value. The default value is 4.

Note:
If a file is not a multiple of the alignment value, it gets padded with zeros until it is. The size define inside the generated header file (--output-h-filename), in case the option has been set, is set to the original, unpadded, filesize.

--output-labels

--output-labels

This option will create seperate labels/arrays for each file added. In other words, katie will not concatenate all files to one array, it will create a seperate array for each file instead. A declaration to each array is written to the output header file (--output-h).

--output-raw

--output-raw

This option activates the output of a RAW file, of the concatenated data, using either the default filename ResourceData.raw, or the one set by --output-filename.

--output-raw-filename

--output-raw-filename <name>

This option can be used to override the default filename or the filename specified by --output-filename. The --output-raw-filename option must be followed by the new filename.

Note:
--output-raw-filename internally activates --output-raw. This option does not append any fileextension to the specified name.

--output-h

--output-h

This option activates the output of a C/C++ header file of the concatenated data, using either the default filename ResourceData.h, or the one set by --output-filename.

Unless --output-labels has specified, it contains definitions to all files inside the concatenated data which include:

A comment with the filename of where the current definitions relate to, is placed above each entry.

A typical generated header file looks like:

#ifndef RESOURCEDATA_H
#define RESOURCEDATA_H

// gfx/level1.map
#define RES_LEVEL1_MAP               0
#define RES_LEVEL1_MAP_SIZE          2308
#define RES_LEVEL1_MAP_SIZEPADDED    2308
#define RES_LEVEL1_MAP_SIZE16        1154
#define RES_LEVEL1_MAP_SIZEPADDED16  1154
#define RES_LEVEL1_MAP_SIZE32        577
#define RES_LEVEL1_MAP_SIZEPADDED32  577

// gfx/level1.pal
#define RES_LEVEL1_PAL               2308
#define RES_LEVEL1_PAL_SIZE          633
#define RES_LEVEL1_PAL_SIZEPADDED    636
#define RES_LEVEL1_PAL_SIZE16        316
#define RES_LEVEL1_PAL_SIZEPADDED16  318
#define RES_LEVEL1_PAL_SIZE32        158
#define RES_LEVEL1_PAL_SIZEPADDED32  159

// gfx/level1.raw
#define RES_LEVEL1_RAW               2942
#define RES_LEVEL1_RAW_SIZE          72070
#define RES_LEVEL1_RAW_SIZEPADDED    72072
#define RES_LEVEL1_RAW_SIZE16        36035
#define RES_LEVEL1_RAW_SIZE16PADDED  36036
#define RES_LEVEL1_RAW_SIZE32        18017
#define RES_LEVEL1_RAW_SIZE32PADDED  18018


#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)])


#ifdef __cplusplus
  extern "C"{
#endif

extern const unsigned char __ResourceData__[];

#ifdef __cplusplus
  }
#endif

#endif // RESOURCEDATA_H

The ResData macros are provided for ease access to files inside the concatenated data. This is the recommended way of how to access the files inside.

The following code copies the palette data from gfx/level1.pal to the destination address specified by pDest:

memcpy((void*)pDest, ResData(RES_LEVEL1_PAL), RES_LEVEL1_PAL_SIZE);

If --output-labels has been passed to katie, the output header file contains declarations to each array instead.

A typical generated header file looks in this case like:

#ifndef RESOURCEDATA_H
#define RESOURCEDATA_H

#ifdef __cplusplus
  extern "C"{
#endif

// gfx/world1_layer0.map
extern const unsigned char world1_layer0_map[8192];

// gfx/world1_layer0.pal
extern const unsigned char world1_layer0_pal[32];

// gfx/world1_layer0.raw
extern const unsigned char world1_layer0_raw[896];

#ifdef __cplusplus
  }
#endif

#endif // RESOURCEDATA_H

Note:
If a file with the same filename and content already exists, Katie will set the filetime to the time of the old file. Advantage is the build process requires less time, because only the data file needs to be recompiled and not every file that includes the header.
See also:
--output-arrayname, --output-id-prefix, --output-id-suffix, --output-id-macroname, --output-labels, --output-h-nosize

--output-h-filename

--output-h-filename <name>

This option can be used to override the default filename or the filename specified by --output-filename. The --output-h-filename option must be followed by the new filename.

Note:
--output-h-filename internally activates --output-h. This option does not append any fileextension to the specified name.
See also:
--output-h, --output-arrayname

--output-h-nosize

--output-h-nosize

When specified, katie will not write size information defines in the C/C++ header (--output-h) file. When --output-labels has specified too, katie will not write the number of elements to the arrays in the C/C++ header (--output-h) file (extern unsigned char foo[];).

See also:
--output-h, --output-labels

--output-c

--output-c

This option activates the output of a C/C++ source file of the concatenated data, using either the default filename ResourceData.c, or the one set by --output-filename.

A typical generated C/C++ source file looks like:

const unsigned char ResourceData[]=
{
     47, 47, 32,102,105,108,101, 32, 97,117,116,111,109, 97,
     // lot of more data
     0,  0, 100, 32,119,105,100,116,104, 61, 48, 32, 97,117,
};

See also:
--output-arrayname

--output-c-filename

--output-c-filename <name>

This option can be used to override the default filename or the filename specified by --output-filename. The --output-c-filename option must be followed by the new filename.

Note:
--output-c-filename internally activates --output-c. This option does not append any fileextension to the specified name.
See also:
--output-c, --output-arrayname

--output-asm-arm

--output-asm-arm

This option activates the output of an ARM assembly file, compatible with GNU compilers, of the concatenated data, using either the default filename ResourceData.s, or the one set by --output-filename.

A typical generated assembly file looks like:

.global ResourceData
.section .rodata
.align
.type   ResourceData, %object
ResourceData:
.byte   47, 47, 32,102,105,108,101, 32, 97,117,116,111,109, 97,
@ lot of more data
.byte   0,  0, 100, 32,119,105,100,116,104, 61, 48, 32, 97,117,
ResourceDataend:
.align
.size   ResourceData, .-ResourceData

See also:
--output-arrayname

--output-asm-arm-filename

--output-asm-arm-filename <name>

This option can be used to override the default filename or the filename specified by --output-filename. The --output-asm-arm-filename option must be followed by the new filename.

Note:
--output-asm-arm-filename internally activates --output-asm-arm. This option does not append any fileextension to the specified name.
See also:
--output-asm-arm, --output-arrayname

--output-id-prefix

--output-id-prefix <name>

This option can be used to override the default prefix of the definitions inside the generated C/C++ header file. The default name is RES_, which means "Resource". The --output-id-prefix option must be followed by the new name.

See also:
--output-h, --output-id-suffix

--output-id-suffix

--output-id-suffix <name>

This option can be used to specify a suffix for the definitions inside the generated C/C++ header file. The --output-id-suffix option must be followed by the new name.

See also:
--output-h, --output-id-prefix

--output-id-macroname

--output-id-macroname <name>

This option can be used to override the default macroname of the ResData service macros inside the generated C/C++ header file. The default name is ResData. The --output-id-macroname option must be followed by the new name.

See also:
--output-h, --output-id-prefix, --output-id-suffix

--help

--help

This option displays the application help page and then exits.

--version

--version

This option displays the application version and compile date and then exits.

--dumpfilename

--dumpfilename

This option displays the application full filename and then exits.

--dumpversion

--dumpversion

This option displays the application version only and then exits.

--quiet

--quiet

The quiet option can be used to prevent the application from displaying any information message. Errormessages are still displayed.


Generated on Thu Jul 5 22:06:58 2007 for Katie by  doxygen 1.5.2