.incbin filename [, rle] [, label=size] [, start=index] [, end=index] [, rule=expr]
Inserts a binary file straight into the output - no assembling is done. This can be useful to hold data (such as sprites or large amounts of text) in an external file in a raw format, rather than having to expand to multiple .db statements.
A more novel use of .incbin would be to use it to load a preassembled chunk of code into your program. By using the .export directive you could also get it to export the correct label addresses as you assemble the original block.
Setting the flag RLE causes the binary to be RLE compressed using the current RLE mode settings.
Specifying a label name, followed by =size, creates a new label containing the size of the original binary (uncompressed).
file_start
.incbin "readme.txt", rle, uncompressed = size
file_end
compressed = file_end - file_start
.echo "README.TXT compressed from "
.echo uncompressed
.echo "b to "
.echo compressed
.echo "b ("
.echo (compressed * 100) / uncompressed
.echo "%)\n"
The start and end flags allow you to specify the range of data inside the file that you want to include (zero-indexed). For example, a start = 256 would ignore the first 256 bytes of data in the file. end points to the last byte you want included. start=1, end=3 would include bytes 1, 2 and 3 into the final binary. By combining them with a size label, you could do things like this:
.incbin "hello.txt", start=1, end=total-2, total=size
...which would strip out the first and last byte from the binary.
Last of all is the rule field. This works like the .asciimap directive - for each byte of the binary, an expression is evaluated to translate the byte in some way. The special string {*}represents the byte being translated. For example, the rule rule={*}+1 would add 1 to each byte.
rule=({*}>='a'&&{*}<='z')?(({*}-'a')+13)%26+'a':(({*}>='A'&&{*}<='Z')?(({*}-'A')+13)%26+'A':{*})
The above rule would perform rot13 on all alphabetic characters. How useful. Note that if you use the $ symbol as the current program counter in your rule then it will be set to the program counter at the start location the binary is loaded into. It is not updated during the translation (as this would cause all sorts of madness).