The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoBkg

Background specific functions. More...

Files

file  SoBkg.c
file  SoBkg.h

Defines

#define SO_BKG_MAX_NUM_BACKGROUNDS
 The number of valid backgrounds.

#define SO_BKG_NONE
 Invalid background index used in SoBkgMap to disassociate from any backgrounds.

#define SO_BKG_PRIORITY_0
 screen priority 0 (highest)

#define SO_BKG_PRIORITY_1
 screen priority 1

#define SO_BKG_PRIORITY_2
 screen priority 2

#define SO_BKG_PRIORITY_3
 screen priority 3 (lowest)

#define SO_BKG_CHARBASE(n)
 starting tile offset in VRAM (n*16384)

#define SO_BKG_MOSAIC_DISABLE
 mosaic mode disabled

#define SO_BKG_MOSAIC_ENABLE
 mosaic mode enabled

#define SO_BKG_CLRMODE_MASK
 mode bits for the color mode

#define SO_BKG_CLRMODE_16
 tile color mode (16 color)

#define SO_BKG_CLRMODE_256
 tile color mode (256 color)

#define SO_BKG_SCRBASE_MASK
 mode bits for the screen base

#define SO_BKG_SCRBASE(n)
 screen offset in VRAM (n*2048)

#define SO_BKG_SIZE_MASK
 mode bits for the bkg size

#define SO_BKG_TEXTSIZE_256x256
 text screen size 256x256 pixels (32x32 tiles)

#define SO_BKG_TEXTSIZE_512x256
 text screen size 512x256 pixels (64x32 tiles)

#define SO_BKG_TEXTSIZE_256x512
 text screen size 256x512 pixels (32x64 tiles)

#define SO_BKG_TEXTSIZE_512x512
 text screen size 512x512 pixels (64x64 tiles)

#define SO_BKG_ROTSIZE_128x128
 rot/scale screen size 128x128 pixels (16x16 tiles)

#define SO_BKG_ROTSIZE_256x256
 rot/scale screen size 256x256 pixels (32x32 tiles)

#define SO_BKG_ROTSIZE_512x512
 rot/scale screen size 512x512 pixels (64x64 tiles)

#define SO_BKG_ROTSIZE
 rot/scale screen size 1024x1024 pixels (128x128 tiles)

#define SoBkgPrintAt(a_Index, a_X, a_Y, a_String)
 Print a string at a given location.


Functions

void SoBkgSetup (u32 a_Index, u32 a_Options)
 Prepares a background for use.

void SoBkgEnable (u32 a_Index, bool a_Enable)
 Turns off the given background.

void SoBkgSetMosaicEnable (u32 a_Index, bool a_Enable)
 Enables or disables the mosaic effect for a particular background.

void SoBkgSetPriority (u32 a_Index, u32 a_Priority)
 changes the display priority for a particular background

bool SoBkgIsEnabled (u32 a_Index)
 Tests to see if a background is enabled.

void SoBkgSetOffset (u16 a_Index, u16 a_XPos, u16 a_YPos)
 Sets the display offset of a background.

u16 * SoBkgGetData (u32 a_Index)
 brief Gets a pointer to the BKG data in VRAM

void SoBkgLoadSolidColorTile (u16 a_Index, u32 a_Tilenum, u16 a_ColorIndex)
 Loads data for a single solid color tile into background VRAM.

void SoBkgFill (u16 a_Index, u16 a_Data)
 Fills the contents of a background.

void SoBkgFillBlock (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Width, u16 a_Height, u16 a_Data)
 Fills a rectangular block of a background.

void SoBkgWrite (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Len, u16 *a_buffer)
 Writes a horizontal strip of data to a background.

void SoBkgWriteV (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Len, u16 *a_buffer)
 Writes a vertical strip of data to a background.

void SoBkgWriteBlock (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Width, u16 a_Height, u16 a_Pitch, u16 *a_buffer)
 Writes a block of data to a background.

void SoBkgWriteBlock16Color (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Width, u16 a_Height, u16 a_Pitch, u16 a_PalIndex, u16 *a_buffer)
 Writes a block of data to a background while translating the data to use a specific background palette.

void SoBkgClearIndirect (u16 a_Index)
 Clears the contents of an indirectly loaded background.

void SoBkgWriteIndirect (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Len, u16 *a_buffer)
 Writes a horizontal strip of data to a background.

void SoBkgWriteVIndirect (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Len, u16 *a_buffer)
 Writes a vertical strip of data to a background.

void SoBkgWriteBlockIndirect (u16 a_Index, u16 a_XIndex, u16 a_YIndex, u16 a_Width, u16 a_Height, u16 a_Pitch, u16 *a_buffer)
 Writes data to a background.

void SoBkgPrint (u16 a_Index, const char *a_String)
 Draws a string to a background.

void SoBkgPrintf (u16 a_Index, const char *a_Format,...)
 Formatted print routine.

void SoBkgSetTextWindow (u16 a_Index, u16 a_UpperLeftX, u16 a_UpperLeftY, u16 a_LowerRightX, u16 a_LowerRightY)
 Sets the window in which printing is restricted.

void SoBkgSetTextWrapping (u16 a_Index, bool a_DoWrapping)
 enables or disables text wrapping

void SoBkgSetTextCursor (u16 a_Index, u16 a_X, u16 a_Y)
 Sets the position that the next print will occur.

const SoVector2 * SoBkgGetTextCursor (u16 a_Index)
 Gets the position that the next print will occur.

void SoBkgSetFont (u16 a_Index, const SoBkgFont *a_Font)
 Sets the font associated with a background.

const SoBkgFont * SoBkgGetFont (u16 a_Index)
 Gets the font associated with a background.

Detailed Description

Background specific functions.

Singleton

This file handles everthing that has to do with a specific background instance. This module works together with the SoBkgManager, SoBkgMemManager and SoBkgMap modules.

Todo:
Add support for screen sizes other than 256x256 pixels

Change to not do demand load for tiles that are not visible due to windowing.

Add support for mode 1, 2 screens

Define Documentation

#define SoBkgPrintAt (  a_Index,
a_X,
a_Y,
a_String    ) 
 

Print a string at a given location.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_X  X-coordinate of target
a_Y  Y-coordinate of target
a_String  The string you want to write.
This function causes a text string to be copied to a specified location on a background. It is really just a convenience wrapper around SoBkgSetTextCursor and SoBkgPrint

void SoBkgPrintAt(u16 a_Index, u16 a_X, u16 a_Y, const char *a_String);

Function Documentation

void SoBkgClearIndirect (  u16    a_Index ) 
 

Clears the contents of an indirectly loaded background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
This function releases all of the tiles that were dynamically loaded into a background and clears the background to 0's.

void SoBkgEnable (  u32    a_Index,
bool    a_Enable
) 
 

Turns off the given background.

Parameters:
a_Index  Background index, 0, 1, 2 or 3.
a_Enable  true to enable the background, false to disable it

void SoBkgFill (  u16    a_Index,
u16    a_Data
) 
 

Fills the contents of a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_Data  value to use to fill background
This function fills an entire background with a single tile value

void SoBkgFillBlock (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Width,
u16    a_Height,
u16    a_Data
) 
 

Fills a rectangular block of a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Width  width of the block of data to be written
a_Height  height of the block of data to be written
a_Data  value to use to fill
This function fills a rectangular block of a background with a single tile value

u16* SoBkgGetData (  u32    a_Index ) 
 

brief Gets a pointer to the BKG data in VRAM

Parameters:
a_Index  Background index: 0, 1, 2, or 3
Returns :
a pointer to the BKG's data in VRAM
I'm not sure that anyone will ever need this function, but here it is just in case.

I should point out that modifying the contents of a background that was created using the *Indirect calls is a very big no-no. Doing this will result in tiles being loaded and unloaded at the wrong times since their use counts in SoBkgMemManager will be incorrect.

const SoBkgFont* SoBkgGetFont (  u16    a_Index ) 
 

Gets the font associated with a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
This function retrieves a pointer to the current font used by a given background.

const SoVector2* SoBkgGetTextCursor (  u16    a_Index ) 
 

Gets the position that the next print will occur.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
This function retrieves a pointer to the current text cursor position for a given background.

bool SoBkgIsEnabled (  u32    a_Index ) 
 

Tests to see if a background is enabled.

Parameters:
a_Index  Background index 0, 1, 2, or 3.

void SoBkgLoadSolidColorTile (  u16    a_Index,
u32    a_Tilenum,
u16    a_ColorIndex
) 
 

Loads data for a single solid color tile into background VRAM.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_Tilenum  index value of the tile to write
a_ColorIndex  The color value to fill the tile
This function is used to manually load a solid color tile into the tile memory for a given background. This could also have been done using a SoTileSet instance containing the data for the solid-color tile, but this function should be smaller.

void SoBkgPrint (  u16    a_Index,
const char *    a_String
) 
 

Draws a string to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_String  The string you want to write.
This function causes a text string to be copied to the specified background. Before calling this function, you must first load a font and associate it with the background you are using.

void SoBkgPrintf (  u16    a_Index,
const char *    a_Format,
...   
) 
 

Formatted print routine.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_Format  Format string (see your stdlib references)
This function provides printf-style printing to backgrounds. It uses the currently active font, cursor position and text window.

void SoBkgSetFont (  u16    a_Index,
const SoBkgFont *    a_Font
) 
 

Sets the font associated with a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_Font  the Font to be associated
This function sets the font to be used by a given background

void SoBkgSetMosaicEnable (  u32    a_Index,
bool    a_Enable
) 
 

Enables or disables the mosaic effect for a particular background.

Parameters:
a_Index  Identifier for the background, 0, 1, 2 or 3.
a_Enable  True if you want mosaic enabled, false otherwise.
Note:
If the mosaic values set with SoBkgManagerSetMosaic are still zero you won't notice a thing of course.

void SoBkgSetOffset (  u16    a_Index,
u16    a_XPos,
u16    a_YPos
) 
 

Sets the display offset of a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XPos  X pixel position -- positive distance from the left-most edge of the Screen
a_YPos  Y pixel position -- positive distance from the top-most edge of the Screen
This function changes the current display offset position of a background screen. Each offset value may be a maximum of 9 bits (0-511).

Todo:
consider validating the X/Y offsets against the actual screen size instead of a fixed 512 max

void SoBkgSetPriority (  u32    a_Index,
u32    a_Priority
) 
 

changes the display priority for a particular background

Parameters:
a_Index  Identifier for the background, 0, 1, 2 or 3.
a_Priority  Display priority for the background
This function updates the display priority for a given background. Backgrounds with lower priority are displayed in front of backgrounds or objects with highter priority.

When the priority of two backgrounds is the same, the background with the lower index number is displayed on top. When the priority of a sprite is the same as the priority of a background, the sprite is displayed on top.

void SoBkgSetTextCursor (  u16    a_Index,
u16    a_X,
u16    a_Y
) 
 

Sets the position that the next print will occur.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_X  X-coordinate of cursor
a_Y  Y-coordinate of cursor
This function sets the current text cursor position for a given background.

void SoBkgSetTextWindow (  u16    a_Index,
u16    a_UpperLeftX,
u16    a_UpperLeftY,
u16    a_LowerRightX,
u16    a_LowerRightY
) 
 

Sets the window in which printing is restricted.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_UpperLeftX  left edge of wrapping window
a_UpperLeftY  top edge of wrapping window
a_LowerRightX  right edge of wrapping window
a_LowerRightY  bottom edge of wrapping window
This function sets the boundaries in which text wrapping is done. All edges are inclusive.

void SoBkgSetTextWrapping (  u16    a_Index,
bool    a_DoWrapping
) 
 

enables or disables text wrapping

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_DoWrapping  flag: true to enable, false to disable wrapping
This function turns text wrapping on or off for a given background. With text wrapping off, printed text is truncated when it goes off the right or bottom edge of the BKG.

void SoBkgSetup (  u32    a_Index,
u32    a_Options
) 
 

Prepares a background for use.

Parameters:
a_Index  Background index, 0, 1, 2 or 3.
a_Options  Combination of BG priority (SO_BKG_PRIORITY_* -- bits 0-1), tile/char base (SO_BKG_CHARBASE -- bits 2-3), mosaic enable (SO_BKG_MOSAIC_ENABLE -- bit 6), tile color mode (SO_BKG_CLRMODE_* -- bit 7), screen base (SO_BKG_SCRBASE -- bits 8-12), and BG size (SO_BKG_TEXTSIZE_* or SO_BKG_ROTSIZE_* -- bits 14-15)
This function sets up all of the internal variables needed to work with a background. This function must be called prior to calling SoBkgEnable to turn on the background. If you are going to be using the SoBkgMemManager to dynamically load your tiles, you should call its SoBkgMemManagerAllocScreen call to ensure it doesn't try to allocate tiles in the memory used by your screen.

Todo:
extend to handle mode 1 & 2 screens

extend to handle 512 pixel screen widths (which use rather odd tile ordering)

void SoBkgWrite (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Len,
u16 *    a_buffer
) 
 

Writes a horizontal strip of data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Len  length of the strip of data to be written
a_buffer  buffer containing the strip of data to be written
This function writes a one-tile high strip of data to the screen. Data is written from left to right and is wrapped. Data that is wrapped is written to the same display row as unwrapped data. The data does not have to be displayed on the screen for it to be written.

void SoBkgWriteBlock (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Width,
u16    a_Height,
u16    a_Pitch,
u16 *    a_buffer
) 
 

Writes a block of data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Width  width of the block of data to be written
a_Height  height of the block of data to be written
a_Pitch  number of tiles per line in the buffer (may be different from width)
a_buffer  buffer containing the block of data to be written
This function writes a two dimensional block of data to the screen. Data is written from left to right on successive lines is wrapped. The data does not have to be displayed on the screen for it to be written.

void SoBkgWriteBlock16Color (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Width,
u16    a_Height,
u16    a_Pitch,
u16    a_PalIndex,
u16 *    a_buffer
) 
 

Writes a block of data to a background while translating the data to use a specific background palette.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Width  width of the block of data to be written
a_Height  height of the block of data to be written
a_Pitch  number of tiles per line in the buffer (may be different from width)
a_PalIndex  the palette slot that the data will use
a_buffer  buffer containing the block of data to be written
This function writes a two dimensional block of data to the screen. Data is written from left to right on successive lines is wrapped. The data does not have to be displayed on the screen for it to be written. (Same as SoBkgWriteBlock, except the data is translated to use a specific 16-color palette) ---------------------------------------------------- This will be the first of more functions to come that will deal with backgrounds in 16 color mode

void SoBkgWriteBlockIndirect (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Width,
u16    a_Height,
u16    a_Pitch,
u16 *    a_buffer
) 
 

Writes data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Width  width of the block of data to be written
a_Height  height of the block of data to be written
a_Pitch  number of tiles per line in the buffer (may be different from width)
a_buffer  buffer containing the block of data to be written
This function writes a two dimensional block of data to the screen. Data in a_buffer represents logical tile numbers. Actual tile numbers are demand loaded using SoBkgMemManager. Data is written from left to right on successive lines and is wrapped. The data does not have to be displayed on the screen for it to be written.

void SoBkgWriteIndirect (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Len,
u16 *    a_buffer
) 
 

Writes a horizontal strip of data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Len  length of the strip of data to be written
a_buffer  buffer containing the strip of data to be written
This function writes a one-tile high strip of data to the screen. Data in a_buffer represents logical tile numbers. Actual tile numbers are demand loaded using SoBkgMemManager. Data is written from left to right and is wrapped. The data does not have to be displayed on the screen for it to be written.

void SoBkgWriteV (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Len,
u16 *    a_buffer
) 
 

Writes a vertical strip of data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Len  length of the strip of data to be written
a_buffer  buffer containing the strip of data to be written
This function writes a one-tile wide strip of data to the screen. Data is written from top to bottom and is wrapped. Data that is wrapped is written to the same display column as unwrapped data. The data does not have to be displayed on the screen for it to be written.

void SoBkgWriteVIndirect (  u16    a_Index,
u16    a_XIndex,
u16    a_YIndex,
u16    a_Len,
u16 *    a_buffer
) 
 

Writes a vertical strip of data to a background.

Parameters:
a_Index  Background index: 0, 1, 2, or 3
a_XIndex  destination X tile index -- counted from the left edge of the screen
a_YIndex  destination Y tile index -- counted from the top edge of the screen
a_Len  length of the strip of data to be written
a_buffer  buffer containing the strip of data to be written
This function writes a one-tile wide strip of data to the screen. Data in a_buffer represents logical tile numbers. Actual tile numbers are demand loaded using SoBkgMemManager. Data is written from top to bottom and is wrapped. The data does not have to be displayed on the screen for it to be written.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.