---

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.

---

             

---

SoBkgMap

Background map handling specific functions. More...

Files
file	SoBkgMap.c
file	SoBkgMap.h
file	SoTileMap.h
Data Structures
struct	SoBkgMap
	Background Map structure. More...
Defines
#define	SO_BKG_MAP_MODE_RAW
	flag - raw mode map
#define	SO_BKG_MAP_MODE_DYNAMIC
	flag - dynamic mode map
#define	SoBkgMapIsDynamic(a_This)
	Checks to see if the map is uses demand loaded tiles.
#define	SoBkgMapGetBackground(a_This)
	Returns the background used by the map.
Functions
void	SoBkgMapInit (SoBkgMap *a_This, u16 a_Mode)
	Initializes the SoBkgMap for use.
void	SoBkgMapSetBackground (SoBkgMap *a_This, u32 a_Bkg)
	Associates the map with a background.
void	SoBkgMapSetTileMap (SoBkgMap *a_This, SoTileMap *a_TileMap)
	Associates a TileMap with the BkgMap.
void	SoBkgMapSetScroll (SoBkgMap *a_This, u16 a_XPos, u16 a_YPos)
	Sets the scroll position of a map on a background.

---

Detailed Description

Background map handling specific functions.

Singleton

This module provides a simple interface to efficiently scroll a large virtual playfield on a Background. It works together with the SoBkg and SoTileMap modules.

When using a SoBkgMap, it is useful to remember that it assumes that associated SoBkg's are set to 256x256 pixels. Using larger SoBkg's will cause strange artifacts to occur.

Here is the minimum code required to associate a SoBkg, SoTileMap and SoBkgMap.

        SoBkgMapSetTileMap(a_This, a_TileMap);
        SoBkgMapSetScroll(a_This, a_XPos, a_YPos);
        SoBkgMapSetBackground(a_This, iBkg);

Here is the fastest code to change the SoTileMap associated with a SoBkgMap and SoBkg.

        SoBkgDisable(a_Bkg);                        // turn off BKG (optional: to avoid nasty artifacts)

        SoBkgMapSetBkg(a_This, SO_BKG_NONE);        // disassociate from the BKG
        SoBkgMapSetTileMap(a_This, NULL);           // disassociate the old tile map
        SoBkgMapSetTileMap(a_This, a_TileMap);      // change the associated tile map
        SoBkgMapSetScroll(a_This, a_XPos, a_YPos);  // pre-load scroll position
        SoBkgMapSetBkg(a_This, a_Bkg);              // reassociate the BKG (reloads tiles)

        SoBkgEnable(a_Bkg, a_Bkg);                  // turn on BKG

This code is faster than the shorter, and potentially more obvious method of just associating the new tile map and setting the new scroll position because it minimizes the amount of data written to the BKG.

---

Function Documentation

void SoBkgMapInit (  SoBkgMap *    a_This, u16    a_Mode )

Initializes the SoBkgMap for use. Parameters: a_This  this pointer a_Mode  operation mode (SO_BKG_MAP_MODE_RAW or SO_BKG_MAP_MODE_DYNAMIC) Todo: add optional lazy/aggressive release mode when using dynamic mode

void SoBkgMapSetBackground (  SoBkgMap *    a_This, u32    a_Bkg )

Associates the map with a background. Parameters: a_This  this pointer a_Bkg  The background to associate This function associates or disassociates a background with the background map. To disassociate, call this function with a_Bkg set to SO_BKG_NONE.

void SoBkgMapSetScroll (  SoBkgMap *    a_This, u16    a_XPos, u16    a_YPos )

Sets the scroll position of a map on a background. Parameters: a_This  this pointer a_XPos  X pixel position -- positive distance from the left-most edge of the map a_YPos  Y pixel position -- positive distance from the top-most edge of the map This function changes the current scroll position of a background. If the map has an associated background, this routine will cause any tiles that are hidden to be unloaded, and any tiles that are exposed to be loaded.

void SoBkgMapSetTileMap (  SoBkgMap *    a_This, SoTileMap *    a_TileMap )

Associates a TileMap with the BkgMap. Parameters: a_This  this pointer a_TileMap  The tile map to associate

---

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

---