Dconvert tutorial

From Uzebox Wiki
Revision as of 04:41, 5 November 2017 by D3thAdd3r (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Introduction

TODO TODO TODO FINISH TUTORIAL///////////////////////////////////////////////////////////////////////////////////////////////////////////

dconvert is a utility that needs a tutorial. This is a placeholder for now, sorry.

Usage

dconvert takes only one argument, and that is the name of a configuration file from which it shall operate. This configuration file is of a simple format which is easy to process, that allows the tool's source code to be small and simple to understand. The options should be enough for anyone's requirements. It is important to remember that, though the tool does cope with some deviance on spaces, etc. it is recommended to closely follow the format examples. The tool can be triggered from the command line like so:

dconvert ../path/to/config.file

It is likely better to call it directly from your makefile, so that you do not need to manually intervene when things change. This is similar to what you will find in the tutorial for gconvert, in the makefile integration section: Generating Tiles and Maps with gconvert

....
## Build
all: SD_DATA.DAT $(TARGET) $(GAME).hex $(GAME).eep $(GAME).lss size

## Regenerate the PCM resources
SD_DATA.DAT: ../data/sdImageConfig.cfg
	$(UZEBIN_DIR)dconvert ../data/sdImageConfig.cfg

## Compile Kernel files
....

Check out the SPIRamMusicDemo makefile in the streaming-music branch for a full example of this usage.


Configuration File

The format of this file is not nearly as fancy or flexible as xml, but the entire program is 400% smaller source code than just the xml parser found in fancier tools. This was the reasoning for going this route, as it should flexible enough for all needs, and be easy to understand as it uses nothing external from the familiar C library. The following is an example of the format:

0,1,512,1024,1,131072,DATAOUT.DAT,
../data/gfx.inc,1,2,0,NULL,
../data/PCM.inc,0,0,0,NULL,
# this is a comment line

That is it. Let's think about what these arguments mean. The first line is the setup line which will dictate some things about how the entries will be processed. The 1st byte, '0' in this case, specifies that we will be reading a C array file. If this was 1, the input files would be read as if they were raw binary data. The 2nd argument specifies the type of output file to put converted data into. '1' in this case, specifies a binary file which is useful for putting onto an SD card otherwise 0 for C array. The 3rd argument in this example is "512", which means that a directory of 4 byte pointers will be written corresponding to all items processed(specifying a number < 0 will turn off the directory creation). The directory entries start at this offset and move upwards 4 bytes per entry. The 4th argument "1024" indicates the output data will start at 1024(which keeps it from overwriting the directory information, and vice versa). The 5th argument which is '1' here, is whether or not to apply sector padding after each data entry is processed. 1 will add as many bytes after the end of each file conversion as required to be an even multiple of 512 bytes. This potentially has advantages when reading/loading from SD; 0 disables it. The 6th argument is the minimum number of bytes the file should be, in this case 131072 which is 128*1024 which happens to be the size of the SPI Ram on the expansion module. If you do not want the filesize padded out, specify 0. Keep in mind this padding only happens after the end of file data if it is smaller(including data that might have already been there), so is safe and will not overwrite data written by another program if present. The 7th and last entry on the setup line is the name of the output file.

Now lets think on the entry lines, for which you can have as many as you want following the setup line. The first one: ../data/gfx.inc,1,2,0,NULL,

The 1st argument there is the path to the file you want to read such as "../data/gfx.inc". The 2nd argument is the number of C arrays to skip(meaningless for binary input). This is useful as example, to extract the map data from a file output by gconvert. If you know the map data is the 2nd array and the tile data is the first(which you may not want to put onto the SD image), then specify 1 to skip past the tile data array. The 3rd argument specifies the number of bytes to skip in the array, before reading. This could be useful for a large amount of same sized tile maps, where you do not want to write the width and height for each one. The 4th argument is the transform type....which is currently underdevelopment so just leave it as 0 for now. TODO TODO. The 5th argument for the entry lines is the name of the C array(meaningless for binary)which is output.



TODO TODO TODO FINISH TUTORIAL///////////////////////////////////////////////////////////////////////////////////////////////////////////