File import

INCLUDE 'filename'

INCLUDE 'myfile.asm'
 ; NO MORE Winape compatibility with READ !!!

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.

You can protect any source from re-entrance with a code like this :

ifndef __SYMBOL__
__SYMBOL__ = 1

;; Code
endif

INCBIN binary_filename,options

INCBIN is able to import data by many ways

Each parameter is optional except those working two by two

INCBIN 'monfichier.bin'
INCBIN 'monfichier.bin',offset
INCBIN 'monfichier.bin',offset,length

The tag usage does not care about the order. Numeric values for offset,length and extended offset will be interpreted in this ordre (extended offset is only for Winape compatibility, use any offset and forget about this

INCBIN 'monfichier.bin',EXISTS,offset,length
INCBIN 'monfichier.bin',offset,EXISTS,length
INCBIN 'monfichier.bin',offset,length,EXISTS

The following options may be cumulated

INCBIN 'monfichier.bin',OFF ; read data in memory and disable overwrite check (use this to initialise memory)
INCBIN 'monfichier.bin',EXISTS ; load the file only if it exists
INCBIN 'monfichier.bin',SKIPHEADER ; skip first 128 bytes if an AMSDOS header is found
INCBIN 'monfichier.bin',REVERT ; read data in reverse order
; the following command have the very same result
INCBIN 'monfichier.bin',REVERT,EXISTS,SKIPHEADER,offset,OFF,length
INCBIN 'monfichier.bin',OFF,REVERT,offset,EXISTS,length,SKIPHEADER

The following tags are mutually exclusives

INCBIN 'monfichier.bin',REMAP,numColumn
INCBIN 'monfichier.bin',VTILES,numLines
INCBIN 'monfichier.bin',ITILES,width
INCBIN 'monfichier.bin',GTILES,width

INCBIN is able to import WAV files. they are decoded regarding their format, then audio channels are downmixed to mono

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 EXISTS tag will import file only if it exists, if not, no error is triggered
  • The REVERT tag allows you to import a binary file in the opposite direction of reading
  • ITILES allows you to import tiles with a height that is a multiple of 8, interleaving the rows in the following order: 0,1,3,2,6,7,5,4. In addition, the bytes are encoded in a zigzag pattern. The parameter corresponds to the width of the tiles in bytes.
  • GTILES does the same thing as ITILES without the zigzag
  • REMAP calculates the height of the columns from the argument (number of columns), then flattens the columns (from a global 2D image)
  • VTILES calculates the width of a row from a given number of rows, then flattens the data into columns
  • 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