File import

INCLUDE 'filename'

INCLUDE 'myfile.asm'
READ 'myfile.asm' ; For Winape compatibility

The directive reads the text file and includes it in the source code at the location of the read statement. The relative read path is rooted at the location of the file from which the embedding is done. By using an absolute path, the reference to the root of the source can be overridden. If the file is not found, it will be searched for in the possible include directories declared with the command line. There is no limit to recursiveness in inclusion, so be careful what you do.

INCBIN binary_filename,offset,size,extended_offset,OFF

INCBIN 'monfichier.bin',offset
INCBIN 'monfichier.bin',REVERT
INCBIN 'monfichier.bin',REMAP,numcol
INCBIN 'monfichier.bin',VTILES,numtiles
INCBIN 'monfichier.bin',ITILES,largeur
INCBIN 'monfichier.wav',SMP
INCBIN 'monfichier.wav',SM2
INCBIN 'monfichier.wav',SM4
INCBIN 'monfichier.wav',DMA,preamp,options,options,...

The read data will be directly injected into the destination binary. The optional parameters are compatible with the INCBIN function of Winape. However, the offset is not limited to 64K as with Winape which can only handle 16 bits values. The extended offset is there for compatibility, its use should be avoided to remain readable.

  • It is possible to give a negative offset, which will then be relative to the end of the file
  • It is possible to give a negative file size. The size read will be equal to the total size of the file + this negative value. To read everything except the last 10 bytes, a size of -10 will be used.
  • A zero size will load the whole file (you will need this to use the optional OFF parameter)
  • The OFF parameter allows to load a file to initialize the memory. This means that it will be possible to assemble or produce binary over it because this parameter disables the overwrite control.
  • The REVERT tag allows you to import a binary file in the opposite direction of reading
  • The REMAP, VTILES and ITILES variants are used to import tiles or sprites
  • ITILES is used to import tiles with a height multiple of 8, by interlacing the lines in the following order: 0,1,3,2,6,7,5,4. Moreover the bytes are encoded in zig zag. The parameter corresponds to the width in bytes of the tiles.
  • WAV files are supported regardless of their format, single or multi-channel. The voices will be merged in the case of multi-channel files. The sampling frequency is not taken into account.
  • The SMP format contains one value (0-15) per byte
  • SM2 format contains two values per byte, the first sample being stored in the most significant quartet
  • The SM4 format contains four sample values per byte, at a rate of two bits per byte, the values 0,1,2 and 3 corresponding to volumes 0,13,14 and 15. We can thus encode the entire audio amplitude of the AY with 2 bits.
  • The DMA format will convert each sample into a list of DMA commands specific to the Amstrad Plus. The sample must first be converted to 15600Hz.
  • The DMA format can have several additional options: DMA_INT to trigger an interrupt at the end of the sample, DMA_CHANNEL_A, B or C to choose the default AY channel (C) and DAM_REPEAT,repetition to repeat the sample from 1 to 4095 times.
org #4000
incbin 'bank.raw',0,0,0,OFF ; load binary at #4000 with overwrite control disabled
org #4000
defb #BB ; overwrite the first byte without error

INCBIN many files

It is possible to use variable tags in the name of the files to be loaded, allowing batch loading of sequences.

repeat 10,cpt
  incbin 'monfichier{cpt}.bin'
rend

File import with on-the-fly compression

Rasm integrates many compression methods that can be used directly in the assembly code, either by defining sections to be compressed, or by including binaries that will be compressed on the fly. For decompression, you can use the routines distributed with RASM (recommended, some crunchers evolve with time).

List of INCBIN command equivalents with compression

  • INCL48 same operation as INCBIN with LZ48 compression on the fly
  • INCL49 same operation as INCBIN with LZ49 on-the-fly compression
  • INCLZ4 same as INCBIN with LZ4 on-the-fly compression
  • INCZX0 same operation as INCBIN command with ZX0 on-the-fly compression
  • INCZX0B same operation as INCBIN with ZX0 BACKWARD compression on the fly
  • INCZX7 same as INCBIN with ZX7 compression on the fly
  • INCEXO same as INCBIN with EXOMIZER compression on the fly
  • INCAPU same operation as INCBIN with AP-Ultra compression on the fly
  • INCLZSA1 same as INCBIN with LZSA1 on-the-fly compression
  • INCLZSA2 same as INCBIN with LZSA2 on-the-fly compression

Special imports

It is possible to preload the RASM memory spaces with a snapshot or a cartridge

SNAPINIT fichier_snapshot

CPRINIT fichier_cartouche

Sauf mention contraire, le contenu de cette page est protégé par la licence Creative Commons Attribution-ShareAlike 3.0 License