Background Text Functions

Defines

Functions


Detailed Description

The Background Text Functions can be used to print text on tile based backgrounds. Own "character-sets" can be used, which are basically only bitmap-fonts though. Any character size is supported, as long as the width and height is multiple 8. Each character must have the same width and height.

The space character should be located in the upper left corner of the character-set texture. This limitation is due to the fact that ham_InitEmptyMapSet function from HAM uses 0 to fill the map. In other words, if you have an "A" as first character on your texture (upper left corner), the empty map is filled entirely with the "A" tile.

See this bitmap for an example. The space character is located at the upper left corner of the graphic:

helBgText_charset.png

The character order you would pass to hel_BgTextCreate for this graphic is:

// That's the order of characters how they
// appear on the source graphic.
const char CHARORDER[] =
    " BCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn"\
    "opqrstuvwxyz0123456789?ÖÄÜöäü,.-;:A#^+*@"\
    "!\"§%\%&/()=?|\\<>[]{}¹²³°";

Define Documentation

#define HEL_SUBSYSTEM_BGTEXT_REQUIREDMEMORY

Required memory for the Background Text System.

This define represents the amount of memory, specified in bytes, the Background Text System from HEL requires to manage its internal states. When you initialize the Background Text System, you must pass a buffer which equals the size of HEL_SUBSYSTEM_BGTEXT_REQUIREDMEMORY.

See also:
hel_TileInit


Function Documentation

void hel_BgTextCreate ( u32  BgNo,
u32  CharW,
u32  CharH,
const void *  pMap,
const char *  pszCharOrder,
void *  pCharLUT,
u32  Flags 
)

Create a Background Text System.

The hel_BgTextCreate creates a Background Text System for the background specified by BgNo.

Parameters:
[in] BgNo Background number to create the Text System for.
[in] CharW Width of one character specified in tiles.
[in] CharH Height of one character specified in tiles.
[in] pMap Pointer to the source map of the character-tileset.
[in] pszCharOrder Pointer to a NULL-terminated string that reflects the order of the characters as they appear in the source graphic. This parameter must be specified only when BGTEXT_FLAGS_GENERATELUT is present in the Flags, otherwise set it to NULL;
[in,out] pCharLUT Pointer to a buffer/lookup-table which contains offsets for each character into pMap. If you don't specify BGTEXT_FLAGS_GENERATELUT in Flags, the pCharLUT buffer is used as is. A pre-generated lookup-table increases creation performance and saves RAM, since it can be stored in ROM.
[in] Flags Flags which control the creation and text printing behaviors. It can be a combination of the following values:
  • BGTEXT_FLAGS_GENERATELUT - Generates a lookup table and stores the result at pCharLUT
  • BGTEXT_FLAGS_DYNAMICTILERELOADING - Text System will use dynamic tile reloading. A Tile-System must have been created already (Tile Functions)
Note:
If flags has BGTEXT_FLAGS_GENERATELUT set, the hel_BgTextCreate function generates the lookup table this way:
    size_t i;
    size_t OrderLength = strlen(pszCharOrder);  // String length of character order

    // reset BgText Buffer before 
    // creating the lookup table
    hel_DmaSet16(pCharLUT, 0, 256);

    // Now create the character lookup table
    for(i=0; i<OrderLength; i++)
    {
        // Array spot in pBuffer of
        // the character in question
        // This is the ASCII code actually
        u8 Spot = (u8)pszCharOrder[i];

        // Store offset where the current 
        // character is located inside pMap
        ((u16*)pCharLUT)[Spot] = i * CharW * CharH; // CharW = Character width in tiles
                                                    // CharH = Character height in tiles
    }
If you want to pass a precomputed lookup table, you can use this code to create such table.
See also:
hel_BgTextDelete

void hel_BgTextDelete ( u32  BgNo  ) 

Delete a Background Text System.

This function deletes a Background Text System which has been earlier created by hel_BgTextCreate.

Parameters:
[in] BgNo Background number of Background Text System to delete
Note:
This function will not clear any printed text.
See also:
hel_BgTextCreate

void hel_BgTextInit ( void *  pBuffer  ) 

Initialize Background Text System.

The hel_BgTextInit function initializes the Background Text System and must be called before any other function from it.

Parameters:
[in] pBuffer Must point to a buffer of at least HEL_SUBSYSTEM_BGTEXT_REQUIREDMEMORY allocated bytes. The buffer must be word-aligned and should be located in EWRAM. It must not be changed after initialization as long as the Background Text System is running!
// Allocate memory for Background Text System
u8 ATTR_EWRAM ATTR_ALIGNED(4) g_BgTextSystemBuffer[HEL_SUBSYSTEM_BGTEXT_REQUIREDMEMORY];

int main(void)
{
    // ...

    // Initialize Background Text System
    hel_BgTextInit((void*)g_BgTextSystemBuffer);

    // ...
}

See also:
hel_BgTextQuit, hel_BgTextCreate

void hel_BgTextPrint ( u32  BgNo,
u32  X,
u32  Y,
u32  Flags,
const char *  pszString 
)

Print a text.

The hel_BgTextPrint function prints the text specified by pszString to the background BgNo at the position specified by X and Y.

Parameters:
[in] BgNo Background number of Background Text System to use.
[in] X Destination horizontal position in tiles of output text.
[in] Y Destination vertical position in tiles of output text.
[in] Flags Reserved for future usage. Must be zero at this time.
[in] pszString Pointer to NULL-terminated string to print.
    // Prints a text over two lines
    hel_BgTextPrint
        (
            0, // BgNo
            1, // X
            1, // Y
            "hello,\n"\
            "this is your gba", // pszString
            0  // Flags
        );

See also:
hel_BgTextPrintF

void hel_BgTextPrintF ( u32  BgNo,
u32  X,
u32  Y,
u32  Flags,
const char *  pszString,
  ... 
)

Print a formatted text.

The hel_BgTextPrintF function prints the text specified by pszString to the background BgNo at the position specified by X and Y. It supports optional arguments and works pretty much the same as sprintf.

Parameters:
[in] BgNo Background number of Background Text System to use.
[in] X Destination horizontal position in tiles of output text.
[in] Y Destination vertical position in tiles of output text.
[in] Flags Reserved for future usage. Must be zero at this time.
[in] pszString Pointer to NULL-terminated format control string plus optional arguments.
    // Prints a text over two lines
    hel_BgTextPrintF
        (
            0,            // BgNo
            1,            // X
            1,            // Y
            0,            // Flags
            "3+2 = %d", 5 // pszString
        );

Note:
The text to print must not be longer than 128 characters, otherwise the program behaviour is undefined.
See also:
hel_BgTextPrint

void hel_BgTextQuit ( void   ) 

Uninitialize Background Text System.

The hel_BgTextQuit must be called to uninitialize the Background Text System. Once the Background Text System has been uninitialized, the buffer earlier passed to hel_BgTextInit is no longer used by the Background Text System.

Note:
This function does not clear any printed texts, it just releases the preceding mentioned buffer from the Background Text System.
See also:
hel_BgTextInit


Generated on Mon Apr 9 16:39:00 2007 for HEL Library by  doxygen 1.5.1