
      HuC v1.4 C library reference, 2000.08.17 (60 functions)


** VIDEO FUNCTIONS **

  disp_off();

      Blank the display.

  disp_on();

      Enable display output.

  cls();
  cls(int val);

      Clear all the screen. Without parameters the screen
      is filled with a space character, else it's filled
      with the bat-value given as argument.

  vsync();
  vsync(char nb_frame);

      Synchronize your program to the video vertical blanking
      signal (VBL), which is 1/60th of a second.
      Without parameters this function return as soon as
      a VBL signal has been received, else your program will
      be synchronized to the number of frame you requested.
      So for example to run your game at 20fps, just use
      vsync(3) at the end of your game loop.

  vreg(char idx);
  vreg(char idx, int val);

      This function gives you direct access to the video
      processor (VDC) registers. The first form of this function
      is used to just select a VDC register (for custom accesses),
      and the second is used to set the value of a register
      (it also selects this register).

  vram_addr(char x, char y);

      Simple function to return the screen video memory address
      of the character located at position x/y.

  set_screen_size(char size);

      Change the virtual screen size. By default the startup
      code initialize a virtual screen of 64 characters wide
      and 32 character tall, but other values are possible,
      namely : 32x32, 128x32, 32x64, 64x64, or 128x64.
      More the virtual screen is big, less video memory
      you have for your graphics (font, tiles, sprites).

  load_vram(int vaddr, int *data, int nb);

      Generic function to load data (BAT, CG, sprites)
      in video memory, at address 'vaddr'.
      'nb' is the number of 16-bit words to load.

  load_bat(int vaddr, int *bat_data, char w, char h);

      Load a rectangular character attribute table (BAT)
      of width 'w' and of height 'h' in video memory,
      at address 'vaddr'.

  load_background(char *gfx, int *pal, int *bat, char width, char height);

      This function is an all-in-one function, it is used
      to display a whole background image on the screen, like
      a game title image. It will load BG character data,
      it will load the palette, and finaly if will load the BAT.
      Use it with directives #incchr, #incpal and #incbat
      to manage the different type of data. The BG character
      data will be stored at address 0x1000 to 0x5000 in video
      memory.


** PALETTE FUNCTIONS **

  set_color(int num, int rgb);

      Set the specified color (0-511) to the given rgb-value.

  set_color_rgb(int num, char r, char g, char b);

      Set the specified color to the given rgb component
      values. This function is easier to use than set_color(),
      but it is slower.

  get_color(int num);

      Retrieve the rgb-value of the specified color.

  load_palette(char pal_num, int *pal, char nb_pal);

      Load one or more 16-color palette-blocks at once.
      'pal_num' is the index of the first block (0-31)
      to load, and 'nb_pal' the number of block.
      This function can be used to load palette defined
      using #defpal or included with #incpal directive.

  set_sprpal(char pal_num, int *pal);
  set_sprpal(char pal_num, int *pal, int nb_pal);

      Exactly the same function has load_palette(),
      but this function offers direct access to sprite
      palette-blocks. Sprite palette-blocks are
      standard block number 16 to 31, but with this function
      you can simply access them with indexes 0 to 15.
      This function and set_bgpal() function make sprite
      and character palette-blocks manipulation easier;
      with them you don't have to know the real block indexes.
      Without the third arguments, the function loads
      only one block.

  set_bgpal(char pal_num, int *pal);
  set_bgpal(char pal_num, int *pal, int nb_pal);

      Same function as set_sprpal() but for character
      palette-blocks.


** FONT FUNCTIONS **

  set_font_color(char fg, char bg);

      Set the default font foreground and background colors
      (colors range from 0 to 15). Changes won't take effect
      immediately, you must re-load the font by calling
      load_default_font().

  set_font_pal(char pal);

      Set the font palette index (0-15).

  set_font_addr(int vaddr);

      Set the font address in video memory.
      Use this function to change the current font;
      to use several font on the same screen, or when
      you load yourself a font and need to tell the
      library where it is.

  get_font_pal();

      Return the current font palette index.

  get_font_addr();

      Return the current font address in video memory.

  load_default_font();
  load_default_font(char num);
  load_default_font(char num, int vaddr);

      Load a default font in video memory. Without parameters
      the first default font is loaded just above the
      BAT in video memory; usualy it's address 0x800.
      Otherwise you can select the font number, and eventualy
      the address in video memory.
      In its current implementation the library support only
      one default font, but in the future more fonts could
      be available.

  load_font(char *font, char nb_char);
  load_font(char *font, char nb_char, int vaddr);

      Load a custom font in video memory. Used together
      with the #incchr directive it will allow you to load
      a font from a PCX file. Note that custom fonts are
      colored fonts, so they won't be affected by any
      previous call to set_font_color().
      The number of character to load range from 0 to 224,
      ASCII characters 0 to 31 are never used, and can't
      be defined, you must start your font at the space
      character, which is ASCII code 32.
      If you don't implicitely give a video memory address,
      the function will load your font just above
      the BAT (usualy it's address 0x800).


** TEXT OUTPUT FUNCTIONS **

      All the text output functions have two forms, one where
      you directly specify the video memory address, and another
      one where you specify x/y coordinates (in character unit).
      The second form is a bit slower but more user-friendly.

  put_digit(char digit, int vaddr);
  put_digit(char digit, char x, char y);

      Output a digit character '0'-'9' given its numeric
      value. Hexa digits ('A'-'F') are also supported,
      a value of 10 will output 'A', a value of 11 will
      output 'B', and so on...

  put_char(char c, int vaddr);
  put_char(char c, char x, char y);

      Output an ASCII character.

  put_raw(int bat_val, int vaddr);
  put_raw(int bat_val, char x, char y);

      Output a raw bat-value.

  put_number(int number, char width, int vaddr);
  put_number(int number, char width, char x, char y);

      Output a signed number. The 'width' argument is used
      to format the number. As much as 'width' digit(s)
      will be displayed. If the number has less than 'width'
      digit(s), blank spaces will be added at its left.
      If the number is negative, a '-' sign is added.

  put_hex(int number, char width, int vaddr);
  put_hex(int number, char width, char x, char y);

      Output an hexa number.

  put_string(char *string, int vaddr);
  put_string(char *string, char x, char y);

      Output a null terminated ASCII string.

 
** TILE & MAP FUNCTIONS **

  set_tile_data(char *tile_data, int nb_tile, char *pal_ref);

      Define an array of tile to be used by all the tile
      and map functions. 'tile_data' is the address of
      the tile graphics data in memory, 'nb_tile' is
      the number of tile (max. 256), and 'pal_ref' is
      the address of a palette-index array to use
      for tiles; each tile has its own palette index
      attached to it (note that palette indexes must be
      shifted to the left by four bits, ie. 0x40 for
      palette index 4).

  load_tile(int vaddr);

      Load tile graphics data in video memory, at address
      'vaddr'. You must first have defined a tile array with
      set_tile_data() before using this function.

  put_tile(int num, int vaddr);
  put_tile(int num, char x, char y);

      Put individual tiles on the screen, either directly
      at video memory location 'vaddr', or at screen coordinates
      'x/y' (in tile unit). 'num' is a tile index in the tile
      array defined by the most recent call to set_tile_data().

  set_map_data(char *map, char w, char h);

      Define a tile-index map to be used by load_map().
      'map' is the address of a map of width 'w' (max. 256)
      and of height 'h' (max. 256).

  load_map(char sx, char sy, int mx, int my, char w, char h);

      Load a part of a map on the screen. 'sx' and 'sy' are
      screen coordinates (in tile unit; 16 pixels), 'mx' and 'my'
      are position in the map, and 'w' and 'h' are respectively
      the number of tile-index to load horizontaly and verticaly.
      This function doesn't do any screen clipping, so you must
      not pass incorrect or too big screen coordinates to it,
      that would corrupt the video memory.

  scroll(char num, int x, int y, char top, char bottom, char disp);

      Define screen window 'num'. Up to four window can be defined.
      'top' and 'bottom' are the screen top and bottom limits
      of the window (limits are included in the window area).
      'disp' controls the type of the window, if bit 7 is set
      background graphics will be displayed in this window,
      and if bit 6 is set sprites will also be displayed.
      If none of these bits are set the window will stay blank.
      'x' and 'y' are the top-left coordinates of the area
      in the virtual screen that will be displayed in
      the window.


** SPRITE FUNCTIONS **

  load_sprites(int vaddr, int *spr_data, int nb_spr);

      Load sprite graphics data in video memory, at address
      'vaddr'. This function load sprites by chunk of 8 sprites
      of 16x16 pixels. 'nb_spr' is the number of chunk to load.
      If you need to load less 16x16 sprites than the eight
      contained in a chunk, use load_vram() function instead.

  init_satb();

      Initialize the internal sprite attribute table
      (SATB) used by the library to handle sprites.
      This function must be called before any other
      sprite function is called.

  reset_satb();

      Reset the internal SATB, this has the effect
      to disable and reset all the sprites.

  satb_update();
  satb_update(char nb);

      Copy the internal sprite attribute table
      to the video ram. This will refresh sprites
      on the screen. Use this function regularly
      to update the sprite display. The best place
      to call satb_update() is after every vsync()
      call, but no need to call satb_update if you
      didn't change any sprite attribute.
      'nb' specifys the number of sprite to refresh;
      starting from sprite 0. By default the library
      refreshes only the sprites you use, but if you
      need to implicitely refresh a certain number
      of sprites then you can use 'nb'.

  spr_set(char num);

      Select sprite 'num' (0-63) as the current sprite.

  spr_x(int value);

      Set the x coordinate of the current sprite.
      Negative values will make the sprite disappear
      under the left border, while values higher than
      the screen width will make it disappear under
      the right border.

  spr_y(int value);

      Set the y coordinate of the current sprite.

  spr_pattern(int vaddr);

      Set the pattern address in video memory of
      the current sprite.

  spr_ctrl(char mask, char value);

      Set different attributes of the current sprite.
      With this function you can change the sprite
      size (16x16, 32x32, ...) and the sprite
      orientation (horizontal/vertical flipping).

  spr_pal(char pal);

      Set the palette-block index (0-15) of the current sprite.

  spr_pri(char pri);

      Set the priority of the current sprite. '0' will make
      it appear behind the background (through color 0),
      '1' will make it appear in front of the background.

  spr_get_x();

      Return the x coordinate of the current sprite.

  spr_get_y();

      Return the y coordinate of the current sprite.

  spr_get_pal();

      Return the palette-block index (0-15) of the current
      sprite.

  spr_get_pattern();

      Return the pattern address in video memory of
      the current sprite.

  spr_hide();
  spr_hide(char num);

      Without parameters this function will hide the current
      sprite. Use 'num' to hide a different sprite than
      the current one.

  spr_show();
  spr_show(char num);

      Show a sprite that has been hidden using the spr_hide()
      function.


** JOYPAD FUNCTIONS **

  joy(char num);

      Return the current status of joypad number 'num'.

  joytrg(char num);

      Return informations about newly pressed buttons
      and directions of joypad number 'num'.
      But beware of this function, these informations
      are refreshed every frame, so if your game loop
      is not fast enough you could miss some keypresses.
      In such a case use the joy_events() functions, they
      do keep trace of all the keypresses.

  set_joy_callback(char num, char mask, char keys, void (*proc)());

      You can program the library to call one of your function
      when a certain joypad key as been pressed.
      The best use of this function is to handle game pause
      mode when the player press the START button.
      'num' is the numero of the callback to install,
      for now there's only one callback (0), but future
      versions of the library may have more.
      'mask' indicates which joypad to scan (one bit
      for each joypad, with bit 0 for joypad 0, etc...),
      and 'keys' indicates which keypresses to look,
      usualy just JOY_STRT. 'proc' is the address
      of the function you want to be called by the library.

  get_joy_events(char num);
  get_joy_events(char num, char rst);

      Return all the joypad keypresses for joypad 'num'
      that has happened since this function was last called.
      With this function you can't miss any keypress.
      'rst' tells the function if the keypress events
      will be reset after having being read, by default
      they are reset after each read, but if 'rst'
      is equal to zero events won't be reset.

  clear_joy_events(char mask);

      Reset the joypad keypress event list(s).
      'mask' indicates which joypad event list you want
      to reset. One bit for each joypad, bit 0 is joypad 0,
      bit 1 is joypad 1, etc... All the event lists
      can be reset by setting 'mask' to 0x1F.


** MISC FUNCTIONS **

  poke(int offset, char val);

     Write 'val' value at memory location 'offset'.
     This function can be used to access the hardware
     I/O ports located at 0x0000 to 0x1FFF.

  peek(int offset);

     Read the content of memory location 'offset'.

  rand();

     Return a 16-bit random number.


