HuC explanation

explanation of forks

compatibility / changes for both versions

====== HuC Directives ======
  * 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 :
    - #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.
    - #incpal(identifier_name, "filename", start_pal);\\  Extract only from palette start_pal to the 15th
    - #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.
    - #incspr(identifier_name, "filename");\\  Extract all possible 16x16 sprites from the file called filename.
    - #incspr(identifier_name, "filename", col, row);\\  Extract only row rows and col columns of 16x16 sprites from the file.
    - #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.
    - #incchr(identifier_name, "filename");\\  Extract all possible 8x8 tiles from the file called filename.
    - #incchr(identifier_name, "filename", col, row);\\  Extract only row rows and col columns of 8x8 tiles from the file.
    - #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.
    - #incchr_ex(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.
    - #inctile(identifier_name, "filename");\\  Extract all possible 16x16 tiles from the file called filename.
    - #inctile(identifier_name, "filename", col, row);\\  Extract only row rows and col columns of 16x16 tiles from the file.
    - #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.
    - #inctile_ex(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).
    - #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.
    - #incbat(identifier_name, "filename", pcx_offset, col, row)\\  Extract only col columns and row rows from the file.
    - #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 :)

===== Notes =====

  * Offset can be added to far pointers. Offset are those name/pointer created when including tiles or sprites and such. This feature enables you to write such a piece of code :<code>
#include(tiles, "tiles.pcx", 1, 16);
load_vram(0x1400, tiles + (1 << 6), 64);</code>
  * All included data through #INC and #DEF directives can be accessed as const array too. #INCBIN directive creates a char array while others create int arrays.\\  After having wrote<code>#INCBIN(level1, "level1.fmp");</code>It's exactly as if you had wrote<code>const char level1[] = { <stuff inside level1.fmp> };</code>
  * Some functions have been added to the libC, get_tile(x,y) to return the index of the tile at position x,y in the current map (for sprite/tile collision checking, isn't it, gravis ?). get_map_width() and get_map_height() which work on the current map.\\  HUGE maps are supported! 16384x16384 tiles (which is 262144x262144 pixels) is what I call huge :-) Well, all maps functions are still limited to 256x256 maps but we can now gather all of them using a special array and a special function, scan_map_table() . This function returns the map at the requested position.\\  Here's an example :
<code>
        #incbin(level1, "level1.fmp") /* 256x256 */
        #incbin(level2, "level2.fmp") /* 256x256 */
        #incbin(level3, "level3.fmp") /* 256x256 */
        #incbin(level4, "level4.fmp") /* 256x256 */

        const int big_map[] = {
        /* width & height of all the maps
         * put together
         */
          512, 512,

        /* the following lines declare all
         * the small maps, one line per map :
         *
         * the two first values are the top/left
         * coordinates of the small map inside
         * the big map, the two followings values
         * are bottom/right coordinates (inclusive),
         * and the two last values are the map
         * address in ROM
         */

          0,   0, 255, 255, bank(level1), level1,
        256,   0, 511, 255, bank(level2), level2,
          0, 256, 255, 511, bank(level3), level3,
        256, 256, 511, 511, bank(level4), level4,

        /* -1 closes the table */

        -1
};</code>