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:
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 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.
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
.
[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
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 }
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.
[in] | BgNo | Background number of Background Text System to delete |
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.
[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); // ... }
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.
[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 );
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
.
[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 );
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.