Home  ·  Downloads  ·  Your Account  ·  Submit News
Documentation Homepage
HAMLib reference
Back to HAM Homepage

HAMlib Introduction

What is HAMlib?
Very good question. HAMlib is a function library (unlike HAM itself, which is a library of Macros). A function library is linked to your Project at compile time, like the Standard C library.
Why use HAMlib?
The reason for the introduction of a second system was straightforward: The complexity of my own projects grew massively, and I kept writing special functions using Macros that handled rather complex tasks. I had to import these functions into every project I started, and it soon occured to me that a few things could be handled by a general library tailored specifically to the GBA hardware. This is when HAMlib was born.
Where to find more information on HAMlib
There are quite a few sources of information on HAMlib:
How does HAMlib work then, and how can I work with it?
For really simple uses, you might want to check the Hello World Tutorial and other tutorials available in this documentation.
Want to get into the system bit deeper? You found the right place to read: HAMlib works much like the GBA itself. To recap your memory:

The GBA has, depending on its display mode, up to 4 layers of backgrounds ( see Tiled Mode Functions ), which can be imagined like 4 Layers of glass you can put paint on. In addition to this, there is space for 128 Sprites (see Sprite Manipulation Functions ).

The two main components of HAMlib are structures holding information about these 4 backgrounds, and on the 128 sprites that can be displayed. These structures are contained in two main arrays available as soon as ham_Init completes:

ham_bg[0] - ham_bg[3] (structures of type bg_info) ham_obj[0] - ham_obj[127] (structures of type obj_info)

A Background, to be of any use for the GBA, needs two components itself, called the TileSet and the Map. You need a Tileset that will contain 8*8 pixel graphics blocks, and a map that will tell the GBA hardware where you want which block to be placed.

Allocating these blocks at the right spots in the hardware can be a big pain, that why HAMlib introduces a complete memory manager that will do this job for you. You do not have to know about what is allocated where, as long as the RAM is not full.

I know this sounds really confusing, but it is not. Let us have a look at what a HAMlib bg entry (read: the information that HAM needs to display one of the 4 available background layers on the GBA) looks like: 

typedef struct bg_info_typ
{
      map_info_ptr  mi;       // active map info for this BG
      tile_info_ptr ti;       // active tile info for this BG
          u16  mosaic;            // mosaic stat (0=off)
          u16  active;            // tells if BG should be active (0=off)
          u16  prio;              // priority of BG screen (0=highest,3=lowest)
      u8       is_rot_bg;      // tells the system if this is a rot/scale bg
      s16       x_scroll;      // in this place HAMlib stores scrolling info
      s16       y_scroll;          // same here
} bg_info,*bg_info_ptr;

Most of the fields should be pretty obvious, but I want to quickly talk about the mi and ti members. These are the Tileset and Maps assigned to this BG. This needs to be set for the BG to work. Since Tilesets themselves can be quite different depending what color mode you are in, and map sets can be quite different depending if they are used on rotation screens or the like, these got their own objects.

So, how do you assign a tileset to a bg then? Easy! Just create a new tileset using a HAMlib function (for example ham_InitTileSet() ), it will return a pointer to the newly created tileset. Set the ham_bg[your_bg_no].ti member to this pointer and thats it. Same goes for the maps, just use ham_InitMapSet() .

There is a wealth of topics that could be covered here, such as the numerous sprite functions, but for now you will have to bear with the example sources provided and the complete reference manual for all HAMlib functions in this documentation.


Documentation Homepage | HAMLib reference | Back to HAM Homepage
documentation created with Doxygen