Definitions

Outdated :

• newbank : This instruction must be used at top level only (that's to say outside any function, at the same 'level' than main function for example). Its goal is to provide an easy way to take advantage of pc engine banking ability (in fact, to use more than 8 kilobytes of memory :). You can use it of 4 different ways :

  1. newbank(); Without argument, all that follow this instruction is placed in the next free bank, and code which will be in will be designed to be placed at a compiler chosen position (If you want to know more, you can check a brief summary of the pc engine hardware). This is the most used form. It's typical use is when you get an assembler error such as "Out of range, bank offset > 0x1FFF". This means you have filled a bank (which is 0x2000 bytes long, that's to say 8192 bytes). In order to solve this you have to 'break' your code. Indeed, currently, since newbank can only occur at top level, you can't have a function the flow of which goes from one bank to another. Each function must reside in one bank. It's then up to you to put the 'overflowing' code into a newer bank including the newbank instruction before it. From this moment, you still have another 0x2000 bytes of data for your use (in the limit of 128 banks, which still represent 1 megabyte). I fear this point is relatively unprecise but we'll try our best to improve it.

  2. newbank(bank_number); You can specify the number of the bank you want to 'tackle'. This number must be in 0-127 range. Usually you shouldn't have to deal with this form of newbank. Only people who see what's its use should use it :)

  3. newbank(offset_value); This version of newbank must be used in certain situation by non pc engine expert coders. It's used to tell the compiler we want a new bank but designed to be placed in a certain position (here again, check the brief summary of the pc engine hardware if you want to learn more). When you want to import any kind of graphical data (such as palettes, sprites patterns, tiles and such), you must declare this bank with newbank(0x4000); because we've decided it would make things much more easier to have all data mapped at 0x4000. This version is recognized from the previous because the argument is a multiple of 0x2000 and is greater than 128.

  4. newbank(bank_number, offset_value); Here is a combination of the two later forms and its use is pretty rare.

• incpal : This top level instruction allows to include a palette coming from a .pcx file. It's basically a wrapper for the magic kit equivalent instruction. It exists in 3 flavors :

  1. #incpal(identifier_name, "filename"); Creates a series of palette identified by identifier_name coming from the file called filename. It extracts 16 palettes from the 0th to the 15th.

  2. #incpal(identifier_name, "filename", start_pal); Extract only from palette start_pal to the 15th

  3. #incpal(identifier_name, "filename", start_pal, number_pal); Extract number_pal palettes from palette start_pal.

• incspr : This instruction includes data for sprite patterns from a .pcx file.

  1. #incspr(identifier_name, "filename"); Extract all possible 16x16 sprites from the file called filename.

  2. #incspr(identifier_name, "filename", col, row); Extract only row rows and col columns of 16x16 sprites from the file.

  3. # incspr(identifier_name, "filename", begin_x, begin_y, col, row); Extract row rows and col columns of 16x16 sprites starting at position (begin_x, begin_y)

• incchr : This instruction includes data for character patterns from a .pcx file.

  1. #incchr(identifier_name, "filename"); Extract all possible 8x8 tiles from the file called filename.

  2. #incchr(identifier_name, "filename", col, row); Extract only row rows and col columns of 8x8 tiles from the file.

  3. #incchr(identifier_name, "filename", begin_x, begin_y, col, row); Extract row rows and col columns of 8x8 tiles starting at position (begin_x, begin_y)

• incchr_ex : This instruction includes data for character patterns from a series of .pcx files, and sets up for the "new style" of 8x8 scroll-tiling.

  1. #incchr(identifier_name, "filename_1", begin_x, begin_y, col, row, pal_idx1, \ "filename_2", begin_x, begin_y, col, rox, pal_idx2, \ "filename_n", begin_x, begin_y, col, rox, pal_idxn ); Extract row rows and col columns of 8x8 tiles starting at position (begin_x, begin_y), and using the stated pal_idx from filename_1 (etc.), assembling them as a single list of tiles in memory, available for use in the map and scrolling functions

• inctile : This instruction includes data for tile patterns from a .pcx file.

  1. #inctile(identifier_name, "filename"); Extract all possible 16x16 tiles from the file called filename.

  2. #inctile(identifier_name, "filename", col, row); Extract only row rows and col columns of 16x16 tiles from the file.

  3. #inctile(identifier_name, "filename", begin_x, begin_y, col, row); Extract row rows and col columns of 16x16 tiles starting at position (begin_x, begin_y)

• inctile_ex : This instruction includes data for character patterns from a series of .pcx files, and sets up for the "new style" of 16x16 scroll-tiling.

  1. #inctile(identifier_name, "filename_1", begin_x, begin_y, col, row, pal_idx1, \ "filename_2", begin_x, begin_y, col, rox, pal_idx2, \ "filename_n", begin_x, begin_y, col, rox, pal_idxn ); Extract row rows and col columns of 16x16 tiles starting at position (begin_x, begin_y), and using the stated pal_idx from filename_1 (etc.), assembling them as a single list of tiles in memory, available for use in the map and scrolling functions

• incbat : This is a special instruction that include a kind of map used to recreate a background picture in conjunction with inclusion of tiles pattern. We've set another pseudo instruction that does that but it's not completely flexible (see load_background).

  1. #incbat(identifier_name, "filename", pcx_offset); Extract the map for displaying the whole pcx containing in the file filename. pcx_offset is the position in the video ram where will be stored the pattern to draw the picture. I advise you to let 0x1000 for this argument, if you want to use the load_background instruction for now.

  2. #incbat(identifier_name, "filename", pcx_offset, col, row) Extract only col columns and row rows from the file.

  3. #incbat(identifier_name, "filename", pcx_offset, begin_x, begin_y, col, row); Extract only col columns and row rows starting at position (begin_x, begin_y)

• defpal : This instruction allows you to define a palette data in your code. Instead of referencing it from a picture, you will simply tell the RGB components for each color of the palette.

  #defpal(identifier_name, <color component> * 16); You are not obliged to define all 16 colors of a palette. As for the components, they are easy to use if you use the hexa decimal notation in which only the 3 last digits are used and represent (from left to right) red, green and blue. The maximum for each component is 7, thus a perfect while is 0x777, while a purple is something like 0x607...

• defspr : With this one, you'll define your own sprites using also inline data, not coming from a picture.

  #defspr(identifier_name, vram_address, default_palette, <8 pixels data> * 32); The vram_address is a value in the range 0-0x10000 which tell the assembler where you want to see these data in the video ram. Don't forget that before using a sprite and such, you'll have to load data into video ram before the real use. In fact, this argument just tells a preference and its value doesn't oblige you to respect this. This is also true for the default_palette (there are 16 palettes for sprites). As for the data, I recommand you to use the hexadecimal notation, in which each 32 bits number easily represent 8 pixels using a digits for each. I bet a little example will make this appear clearer. To declare 8 pixels beginning by 3 pixels of color 5, then 2 of color 10 and finishing by color 1, you'll use the number 0x555AA111. Since we're defining 16x16 sprites, we need two of these numbers to define a line and thus we'll have 32 arguments to define the whole sprite pattern.

• defchr : basically, you should have guessed what this one is for :) (I'm also pretty tired to make documentation ***yawn*** )

  #defchr(identifier_name, vram_address, default_palette, <8 pixels data> * 8); See defspr for most information. I just want to confirm that you also have 16 palettes for tiles data (which makes a total of 32 differents palettes). And since a tile is only 8x8, you have only one hexa number per line and 8 of these numbers. You can have a look at the debug.c file which has the font used for printing defined this way (notice how the vram_address is useless :)

• set_sprpal : We're arriving to pseudo functions built to be used inside functions, as the same place you would write down statements, function calls, declarations and such... This function change a palette using data included or defined.

  set_sprpal(first_palette, palette_name [, number_palette ] ); first_palette is the number of the palette to alter (in the range 0-15) while palette_name is an identifier to a palette to load or to the first palette you want to load (in this case, you should have included or defined all your palettes without any other actions between them). The last argument is optionnal and assumed to be 1 is missing. It's the number of palette you'll load from the rom into the hardware.

• set_bgpal : This one is exactly the same as the previous one expected that it will alter one of the 16 tile palettes.

• load_sprites : This function is just a wrapper for a magic kit macro but it's pretty important. It's the function that permit to load sprite from the rom to the video ram. Don't forget it only become useful there. Once in the video ram, you'll be able to use it in the spr_pattern function (see sprite handling).

  load_sprites(vram_address, data_name, number_sprites); vram_address is the address in the video ram where you want to transfert your sprites. This is this value that you need to pass to the spr_pattern function. data_name is an identifier of the sprites you want to copy and number_sprites is the amount of sprites to transfert. Be careful however that the unit of transfert data is in 32x64 sprites. This mean that for transfering 4 16x16 sprites, putting 1 for number_sprites is enough.

• load_background : contrary to what you could think about, this function isn't the tiles equivalent of load_sprites. It used to load a whole background picture using tiles. I consider this function as unperfect, it still requires some improvements, some flexibility but as it is, it works :)

  load_background(data_name, palette_name, bat_name, width, height); data_name is the identifier of the first tile that compose the picture. As it is currently, it must be beginning a bank; you can't have some data between the last newbank(0x4000) statement and the label you're referencing. The palette_name identifier must refer to the whole palette which have been extracted from the picture. It is HIGHLY recommended to convert your picture to 16 colors only before including them because if you know that each 8x8 tile must use only 16 colors consecutive, you'll quickly understand that it's not so easy to have more than 16 colors on a whole picture. bat_name is the identifier of the BAT which is in fact the way to use tiles to compose anew the original picture. Finally width and height are self explicite ^^, the only thing I could add is that the unit is the tile, that's to say a 8x8 piece of graphic. The best to see how this function works is to check sources of Pong.