12.2. Import of Binary Files

It's possible to load any file into a variable. This is done with the LoadBinary function. To extract bytes of the file from the variable you use the get function. You can also get the size of the file with the getSize function. Here is an example:

// Load the file into the variable ’data’
.var data = LoadBinary("myDataFile")

// Dump the data to the memory
myData: .fill data.getSize(), data.get(i)

The get function extracts signed bytes as defined by java, which means the byte value $ff gives the number -1. This is not a problem when dumping bytes to memory, however if you want to process the data you might want an unsigned byte. To get an unsigned byte use the uget function instead. The byte value $ff will then return 255.

When you know the format of the file, you can supply a template string that describes the memory blocks. Each block is given a name and a start address relative to the start of the file. When you supply a template to the LoadBinary function, the returned value will contain a get and a size function for each memory block:

.var dataTemplate = "Xcoord=0,Ycoord=$100, BounceData=$200"
.var file = LoadBinary(“moveData”, dataTemplate)
Xcoord:     .fill file.getXCoordSize(), file.getXCoord(i) 
Ycoord:     .fill file.getYCoordSize(), file.getYCoord(i) 
BounceData: .fill file.getBounceDataSize(), file.getBounceData(i)

Again, file.ugetXCoord(i) will return an unsigned byte.

There is a special template tag named ‘C64FILE’ that is used to load native c64 files. When this is in the template string, the LoadBinary function will ignore the two first byte of the file, since the first two bytes of a C64 file are used to tell the loader the start address of the file. Here is an example of how to load and display a Koala Paint picture file:

.const KOALA_TEMPLATE = "C64FILE, Bitmap=$0000, ScreenRam=$1f40, ColorRam=$2328, BackgroundColor = $2710"
.var picture = LoadBinary("picture.prg", KOALA_TEMPLATE)

        *=$0801 "Basic Program"

        *=$0810 "Program"
        lda #$38
        sta $d018
        lda #$d8
        sta $d016
        lda #$3b
        sta $d011
        lda #0
        sta $d020
        lda #picture.getBackgroundColor()
        sta $d021
        ldx #0
        .for (var i=0; i<4; i++) {
           lda colorRam+i*$100,x
           sta $d800+i*$100,x
        bne !loop-
        jmp *

*=$0c00;            .fill picture.getScreenRamSize(), picture.getScreenRam(i)
*=$1c00; colorRam:  .fill picture.getColorRamSize(), picture.getColorRam(i)
*=$2000;            .fill picture.getBitmapSize(), picture.getBitmap(i)

Notice how easy it is to reallocate the screen and color ram by combining the *= and .fill directives. To avoid typing in format types too often, Kick Assembler has some build in constants you can use:

Table 12.1. BinaryFile Constants

Binary format constant Blocks Description
BF_C64FILE   A C64 file (The two first bytes are skipped)
BF_BITMAP_SINGLECOLOR ScreenRam,Bitmap The Bitmap single color format outputted from Timanthes.
BF_KOALA Bitmap,ScreenRam,ColorRam,BackgroundColor Files from Koala Paint
BF_FLI ColorRam,ScreenRam,Bitmap Files from Blackmails FLI editor.
BF_DOODLE ColorRam,Bitmap Files from Doodle

So if you want to load a FLI picture, just write

.var fliPicture = LoadBinary("GreatPicture", BF_FLI)

The formats were chosen so they cover the outputs of Timanthes (NB. Timanthes doesn’t save the background color in koala format, so if you use that you will get an overflow error).

TIP: If you want to know how data is placed in the above formats, just print the constant to the console while assembling. Example:

.print "Koala format="+BF_KOALA