--- layout: page title: Toolbox Reference style: toolref ---

- Housekeeping Functions
- Sprite Functions
- Tile Functions
- Primary Background Functions
- Secondary Background Functions
- Timer Functions
- Overlay Functions
- Global State Functions
- Miscellaneous Functions

# GTE Tool Set

The Generic Tile Engine (GTE) Tool Set enables tile-based games to be implemented in an efficient manner. The tool set provides support for sprites, animations, large scrolling backgrounds and special effects.

To effectively use this tool set, a user should be familiar with the following

- The IIgs Hardware Reference
- The QuickDraw II tool set
- IIgs Technical Note #70

## A preview of the GTE Tool Set routines

To introduce you to the capabilities of the GTE Tool Set the routines are grouped by function and briefly described in Table 1. These routines are descibed in detail later where they are separated into housekeeping routines (discussed in routine number order) and the rest of the GTE Tool Set routines (discussed in alphabetical order).

Table 1
GTE Tool Set routines and their functions
Routine | Description
--- | ---
Housekeeping Routines
GTEBootInit | Initializes the GTE Tool Set; called only by the Tool Locator — must not be called by an application
GTEStartUp | Starts up the GTE Tool Set for use by an application
GTEShutDown | Shuts down the GTE Tool Set when an application quits
GTEVersion | Returns the version number of the GTE Tool Set
GTEReset | Resets the GTE Tool Set; called only when the system is reset — must not be called by an application
GTEStatus | Indicates whether the GTE Tool Set is active
Sprite Routines |
GTECreateSpriteStamp | Creates a sprite stamp from the tile set
GTECompilepriteStamp | Created a compiled sprite from a sprite stamp
GTEAddSprite | Add a active sprite to the scene
GTEMoveSprite | Changes a sprite's location
GTEUpdateSprite | Changes a sprite's tile set reference and display flags
GTERemoveSprite | Removes a sprite from the scene
Tile Routines
GTELoadTileSet | Copies a tileset into the GTE tileset memory
GTESetTile | Assigns a tile to a tile store
GTEGetTileAt | Retrieves the tile ID stored in the tile store
GTECopyTileToDynamic | Copies a tile from the tileset memory into the managed dynamic tile memory. Changing the dynamic tile data will result in all of the tiles updating on the next call the `GTERender()`
GTEGetTileDataAddr | Returns the base address of the tiledata memory
GTEFillTileStore | Fills the entire tile store with a tile ID.
Primary Background Routines
GTESetBG0Origin | Sets the upper-left origin point in the primary background
GTERender | Draws the current scene to the graphics screen
GTEGetBG0TileMapInfo | Returns a record describing the number of tiles in the primary tilemap and a pointer to the tilemap data.
GTESetBG0TileMapInfo | Defines a tile map for the primary background
GTERefresh | Forces all of the tiles in the tile store to be refreshed on the next render.
Secondary Background Routines
GTESetBG1Origin | Sets the upper-left origin point in the secondary background
GTECopyPicToBG1 | Copies an uncompressed pixel image into the secondard background buffer
GTESetBG1TileMapInfo | Defines a tile map for the secondary background
GTESetBG1Displacement | Sets a displacement into the BG1 offset table.
GTESetBG1Rotation | Sets the rotation angle of the BG1 buffer.
GTEClearBG1Buffer | Clears the BG1 pixel buffer with a 16-bit value.
Timer Routines
GTEAddTimer | Add a timer callback that is fired after a designated number of VBL ticks
GTERemoveTimer | Removes an active timer
GTEStartScript | Registers a GTE script to be handled in the background
Overlay Routines
GTESetOverlay | Registers an overlay routine to be integrated into the renderer. Typically used for status bars or messages.
GTEClearOverlay | Removes the current overlay from the renderer
Functions affecting the global state
GTESetScreenMode | Sets the playing field's port rectangle to a pre-defined size, or a specified width and height
GTESetPalette | Copies a palette to the Super HiRes palette memory
GTEBindSCBArray | Takes an array of SCB bytes and binds them to either the Primary or Secondary background's vertical position
GTEGetScreenInfo | Returns a records describing the origin, width and height of the playfield on the physical graphics screen.
Misc. Functions
GTEReadControl | Reads the keyboard and returns key events in a gamepad structure
GTEGetSeconds | Returns the number of seconds elapsed since the toolset was started

## Using the GTE Tool Set

This section discusses how the GTE Tool Set routines fit into the general flow of an application and gives you an idea of which routines you'll need to use under normal circumstances. Each routine is described in detail later in this chapter. The GTE Tool Set depends on the presence of the tool sets shown in Table 2 and requires at least the indicated version of each tool set be present.

Table 2
GTE Tool Set — other tool sets required
Tool set number | Tool set name | Minimal version needed
--- | --- | ---
$01 | #01 | Tool Locator | 3.x
$02 | #02 | Memory Manager | 3.x
$03 | #03 | Miscellaneous Tool Set | 3.2

To use the GTE Tool Set routines, your application must call the GTEStartUp routine before making any other GTE calls. To save memory, the GTE Tool Set may be started up with some features disabled. See the section GTEStartUp in this chapter for further details.

Your application should also make the GTEShutDown call when the application quits.

#### $01XX

#### GTEBootInit

Initializes the GTE Tool Set; called only by the Tool Locator.

An application must never make this call

##### Parameters

The stack is not affected by this call. There are no input or output parameters.

##### Errors

None

##### C

Call must not be made by an application.

#### $02XX

#### GTEStartUp

Starts up the GTE Tool Set for use by an application.

Your application must make this call before it makes any other GTE Tool Set calls.

The GTE Tool Set uses two consecutive pages of bank zero for its direct page space starting at dPageAddr. If the `ENGINE_MODE_DYN_TILES` flag is set in the capFlags, the GTE will attempt to allocate an additional eight pages of bank zero space. If the `ENGINE_MODE_BNK0_BUFF` flag is set, then GTE will attempt to allocate an ~32KB buffer from $2000 to $9CFF in Bank 0.

##### Parameters

Stack before call
previous contents
dPageAddr |  | Word — 16-bit address of two pages of page-aligned Bank 0 memory
capFlags |  | Word — Capability flags to set the engine mode
userID |  | Word — User ID to be associated with the block. All memory allocated by GTE will use this ID
| ← | SP

Stack after call
previous contents
| ← | SP

capFlags |  |
--- | --- | ---
ENGINE_MODE_TWO_LAYER | $0001 | Enables the second background layer. This will have a moderate impact on rendering performance.
ENGINE_MODE_DYN_TILES | $0002 | Enables the use of dynamic (animated) tiles. This will have a small impact on performance and requires allocating 8 pages of Bank 0 memory
ENGINE_MODE_BNK0_BUFF | $0004 | Allocates a 32KB buffer in Bank 0 for advanced graphical effects and customizations.

##### Errors

Memory Manager Errors | Returned unchanged

##### C

`extern pascal GTEStartUp(dPageAddr, capFlags, userID)`

`Word dPageAddr;`

`Word capFlags;`

`Word userID;`

#### $03XX

#### GTEShutDown

Shuts down the GTE Toolset when an application quits.

##### Parameters

The stack is not affected by this call. There are no input or output parameters.

##### Errors

None

##### C

`extern pascal void GTEShutDown()`

#### $04XX

#### GTEVersion

Returns the version number of the GTE Tool Set.

##### Parameters

Stack before call
previous contents
wordspace |  | Word — Space for result
| ← | SP

Stack after call
previous contents
versionInfo |  | Word — Version number of the GTE Tool Set.
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEVersion()`

#### $05XX

#### GTEReset

Resets the GTE Tool Set; called only when the system is reset.

An application must never make this call

##### Parameters

The stack is not affected by this call. There are no input or output parameters

##### Errors

None

##### C

Call must not be made by an application.

#### $06XX

#### GTEStatus

Indicates whether the GTE Tool Set is active.

##### Parameters

Stack before call
previous contents
wordspace |  | Word — Space for result
| ← | SP

Stack after call
previous contents
activeFlag |  | Word — boolean; TRUE if GTE Tool Set active, FALSE if inactive
| ← | SP

##### Errors

None

##### C

`extern pascal Boolean GTEStatus()`

GTE Tool Set routines

#### $09XX

#### GTEReadControl

##### Parameters

Stack before call
previous contents
wordspace |  | Word — Space for result
| ← | SP

Stack after call
previous contents
userInput |  | Word — packed representation of user input
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEReadControl()`

##### Returned value

The value returned in userInput bitfield are show below.

15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Bits 0-6 | keyCode | Keyboard code read from the Keyboard register. If no key is currently pressed, this value is zero.
Bit 7 | Reserved | Always zero.
Bit 8 | PAD_BUTTON_B | Set to 1 if the `B` button of the gamepad is pressed. Mapped to the option key by default.
Bit 9 | PAD_BUTTON_A | Set to 1 if the `A` button of the gamepad is pressed. Mapped to the command key by default.
Bit 10 | PAD_KEY_DOWN | Set to 1 on the initial press of a key. If a key is held down, the `keyCode` will be set and this bit will be zero.
Bits 11-15 | Reserved | Always zero.

#### $0AXX

#### GTESetScreenMode

##### Parameters

Stack before call
previous contents
width |  | Word—Width of the playfield in bytes. Must be even.
height |  | Word—Height of the playfield in scanlines.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetScreenMode(width, height)`

`Word width;`

`Word height;`

##### Predefined Screen Sizes

If the width value is set to a small number, then one of the pre-defined screen sizes will be selected. Set the width to the index number of the screen sizes in the table below to set the screen size to those dimension. The height value must still be passed, but is ignored.

Play Field Id | Width | Height |  | Size (bytes) | Percent of Full Screen
--- | --- | --- | --- | --- | ---
0 | 320 | 200 | Full Screen | 32,000 | 100%
1 | 272 | 192 | Sword of Sodan | 26,112 | 81.6%
2 | 256 | 200 | NES (approx.) | 25,600 | 80.0%
3 | 256 | 176 | Task Force | 22,528 | 70.4%
4 | 280 | 160 | Defender of the World | 22,400 | 70.0%
5 | 256 | 160 | Rastan | 20,480 | 64.0%
6 | 240 | 160 | Game Boy Advanced | 19,200 | 60.0%
7 | 288 | 128 | Ancient Land of Y's | 18,432 | 57.6%
8 | 160 | 144 | Game Boy Color | 11,520 | 36.0%
9 | 288 | 192 | Agony (Amiga) | 27,648 | 86.4%
10 | 160 | 102 | Atari Lynx | 8,160 | 25.5%

#### $0BXX

#### GTESetTile

##### Parameters

Stack before call
previous contents
x |  | Word—Horizontal index of the TileStore tile to set. Must be in the range of 0 to 40.
y |  | Word—Vertical index of the TileStore tile to set. Must be in the range of 0 to 25.
tileID |  | Word—Tile ID to place in the TileStore.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetTile(x, y, tileID)`

`Word x;`

`Word y;`

`Word tileID;`

##### Tile Identifiers

The tile ID word is defined as follows

15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Bits 0-8 | tileIndex | The index of the tile in the current Tile Set. A Tile Set can be defined by calling the `GTELoadTileSet` function
Bit 9 | fTileHFlip | Flips the tile horizontally when set.
Bit 10 | fTileVFlip | Flips the tile vertically when set.
Bit 11 | fTileDynamic | Identifies this tile as a dynamic tile. The `tileIndex` is used to identify the dynamic tile data slow and must be in the range 0 to 31.
Bit 12 | fTileSolid | Hint bit that marks a tile as having no mask. Can improve performance when ENGINE_MODE_TWO_LAYER is set.
Bit 13 | fTileFringe | Unused. Must be zero.
Bit 14 | fTilePriority | Sets the tile to high priority. Sprites will render under this tile, if supported.
Bit 15 | Reserved | Must be zero.

#### $0CXX

#### GTESetBG0Origin

Sets the coordinate of the upper-left corner of the playfield within the primary background buffer. The coordiate values are unsigned, so transitioning from 0 to -1 will result in a discontinuous jump in the background position.

##### Parameters

Stack before call
previous contents
xpos |  | Word—Unsigned horizontal position
ypos |  | Word—Unsigned vertical position
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG0Origin(x, y)`

`Word x;`

`Word y;`

#### $0DXX

#### GTERender

Renders the current playfield to the graphics screen.

##### Parameters

Stack before call
previous contents
flags |  | Word—Render control flags
| ← | SP

Stack after call
previous contents
| ← | SP

flags |  |
--- | --- | ---
RENDER_ALT_BG1 | $0001 | Set the data bank register to the alternate secondary background.
RENDER_BG1_HORZ_OFFSET | $0002 | Offsets each scanline of the secondary background's horizontal position.
RENDER_BG1_VERT_OFFSET | $0004 | Offsets each column of the secondary background's vertical position. Unimplemented.
RENDER_BG1_ROTATIONT | $0004 | Use the internal rotation tables to render the secondary background

##### Errors

None

##### C

`extern pascal void GTERender(flags)`

`Word flags;`

#### $0EXX

#### GTELoadTileSet

Loads a tileset into the internal GTE memory buffer. The pointer must point to tiles that are already in GTE tile format.

A tile set is an array of (up to) 512 tile definitions and each tile definition is 128 bytes. The tile definition is comprised of four, 32-byte tiles; a normal tile, its mask, a horizontally flipped version of the tile and its mask. The first 128 bytes of a tileset must be set to zero.

The start and finish parameters define a subset of tiles to be copied into the GTE memory buffer. This is most commonly used to load a small number of tiles to avoid needing to store a full set of 512 tiles that are mostly unushed. For eample, loading in 16 tiles can be performed as `GTELoadTileSet(0, 17, tilePtr)`.

This function can also be used to swap out subsets of tiles on the fly. Any tiles that are replaced which may be on-screen are not automatically refreshed.

##### Parameters

Stack before call
previous contents
start |  | Word—index of the first tile to copy
finish |  | Word—terminating index. This tile is not copied.
tileSetPtr |  | Long—pointer to the tile set data.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTELoadTileSet(start, finish, tileSetPtr)`

`Word start;`

`Word finish;`

`Pointer tileSetPtr;`

#### $0FXX

#### GTECreateSpriteStamp

Creates a sprite stamp (cache sprite pixel data copy) from a sprite identifier and the current tile set. The vBuffAddr points to a location in the internal virtual buffer area. In most cases, an address for a sprite can be calculated from the `VBUFF_SPRITE_START` and `VBUFF_SPRITE_STEP` constants as `ADDR(n) = VBUFF_SPRITE_START + n*VBUFF_SPRITE_STEP`.

##### Parameters

Stack before call
previous contents
spriteIdent |  | Word—sprite identifier word
vBuffAddr |  | Word—Location in the sprite vitual buffer to allocate the stamp.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTECreateSpriteStamp(spriteIdent, vBuffAddr)`

`Word spriteIdent;`

`Word vBuffAddr;`

##### Sprite Identifier

The sprite identifier is a subset of the full sprite descriptor. Only the starting Tile Index and the size bits are used.

When a sprite has a size greater than 8x8, the horizontal tiles are taken from the next tile index and the vertical tiles are taken from `tileID + 32`. This is why tile sheets should be saved with a width of 256 pixels.

15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Bits 0-8 | tileIndex | The index of a tile in the current Tile Set that defines the top-left part of the sprite
Bit 9-10 | Reserved | Must be zero.
Bits 11-12 | fSpriteSize | Sets the size of the sprite 00 - 8x8 01 - 8x16 10 - 16x8 11 - 16x16
Bit 13-15 | Reserved | Must be zero.

#### $2DXX

#### GTECompileSpriteStamp

Creates a compiled sprite in a special compilation buffer from an existing sprite stamp. The return value is an address token that can be passed into the AddSprite function in place of the vBuffAddr parameter as long as the `SPRITE_COMPILED` flag is set.

##### Parameters

Stack before call
previous contents
wordspace |  | Word—Space for result
spriteIdent |  | Word—sprite identifier word
vBuffAddr |  | Word—Location in the sprite vitual buffer.
| ← | SP

Stack after call
previous contents
addr |  | Word—Location in the sprite compilation buffer.
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTECompileSpriteStamp(spriteIdent, vBuffAddr)`

`Word spriteIdent;`

`Word vBuffAddr;`

#### $10XX

#### GTEAddSprite

Adds a new sprite to the current scene. If a sprite is already assigned to the sprite slot, then that sprite is removed and replaced with the new sprite.

A sprite can have negative coordinates and be placed off-screen. A sprite's coordinates are local coordinates on the playfield; a sprite will not move automatically when `GTESetBG0Origin` is changed.

##### Parameters

Stack before call
previous contents
spriteSlot |  | Word—The slot to assign the sprite to. There are 16 slots and sprites in lower slots are drawn above the sprites in higher slots.
spriteFlags |  | Word—Sprite flags that define the sprite's properties.
vBuffAddr |  | Word—Sprite address in the VBUFF space, or a compiled sprite address
x |  | Word—Signed horizontal sprite position on the playfield.
y |  | Word—Signed vertical sprite position on the playfield.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEAddSprite(spriteSlot, spriteFlags, vBuffAddr, x, y)`

`Word spriteSlot;`

`Word spriteDescriptor;`

`Word vBuffAddr;`

`Word x;`

`Word y;`

##### Sprite Descriptor

The sprite descriptor defines the rendering properties of a sprite.

When a sprite has a size greater than 8x8, the horizontal tiles are taken from the next tile index and the vertical tiles are taken from `tileID + 32`. This is why tile sheets should be saved with a width of 256 pixels.

15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Bits 0-8 | tileIndex | The index of a tile in the current Tile Set that defines the top-left part of the sprite
Bit 9 | SPRITE_HFLIP | Flips the sprite horizontally.
Bit 10 | SPRITE_VFLIP | Flips the sprite vertically.
Bits 11-12 | SPRITE_SIZE | Sets the size of the sprite 00 - 8x8 01 - 8x16 10 - 16x8 11 - 16x16
Bit 13 | SPRITE_HIDE | When set, does not render the sprite.
Bit 14-15 | Reserved | Must be zero.

#### $11XX

#### GTEMoveSprite

Repositions a sprite on the play field.

##### Parameters

Stack before call
previous contents
spriteSlot |  | Word—Slot where the target sprite is located.
x |  | Word—New horizontal position.
y |  | Word—New vertical position
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEMoveSprite(spriteSlot, x, y)`

`Word spriteSlot;`

`Word x;`

`Word y;`

#### $12XX

#### GTEUpdateSprite

Changes the stamp or the status flags of a sprite. The size of the sprite cannot be changed. Typically, an application will call `GTEUpdateSprite` immediately after `GTEAddSprite` to set all of th desired sprite properties.

##### Parameters

Stack before call
previous contents
spriteSlot |  | Word—Sprite slot of the target sprite to update.
spriteFlags |  | Word—A new set of sprite flags.
vBuffAddr |  | Word—Sprite stamp virtual buffer address.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEUpdateSprite(spriteSlot, spriteFlags, vBuffAddr)`

`Word spriteSlot;`

`Word spriteFlags;`

`Word vBuffAddr;`

#### $13XX

#### GTERemoveSprite

Removes a sprite from the play field.

##### Parameters

Stack before call
previous contents
spriteSlot |  | Word—Sprite slot of the target sprite to update.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTERemoveSprite(spriteSlot)`

`Word spriteSlot;`

#### $14XX

#### GTEGetSeconds

Returns the number of seconds that have elapsed since the engine was started. This is a 16-bit value and will wrap around after 65536 seconds (~18 hours)

##### Parameters

Stack before call
previous contents
wordspace |  | Word—Space for result.
| ← | SP

Stack after call
previous contents
numSeconds |  | Word—Number of elapsed seconds.
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEGetSeconds()`

#### $15XX

#### GTECopyTileToDynamic

Copies a tile by ID into one of the dynamic tile slots. If a dynamic tile associated with the slot is visible, it will show the new data after the next call to `GETRender`.

The `ENGINE_MODE_DYN_TILES` flag must be set, otherwise this function does nothing.

##### Parameters

Stack before call
previous contents
tileID |  | Word—ID of the tile (0 to 511)
dynID |  | Word—ID of the dynamic tile slot (0 to 31)
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTECopyTileToDynamic(tileID, dynID)`

`Word tileID;`

`Word dynID;`

#### $16XX

#### GTESetPalette

Sets one of the 16 palettes to the RGB values in the passed array. This is a convenience function that immediately updated the visible palette. The palette change is not deferred.

##### Parameters

Stack before call
previous contents
palNum |  | Word—Palette number to changes (0 - 15)
palettePtr |  | Long—pointer to the 32 bytes of RGB values.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetPalette(palNum, palettePtr)`

`Word palNum;`

`Pointer palettePtr;`

#### $17XX

#### GTECopyPicToBG1

Copies an uncompressed SHR image into the secondard background pixel buffer. This is an easy way to load a background image into the secondary layer. SCB values and palettes are not copied.

##### Parameters

Stack before call
previous contents
width |  | Word—Width of the source image data to be copied in bytes. Maximum value of 256.
height |  | Word—Height of the source image data to be copied in rows. Maximum value of 208.
stride |  | Word—Number of bytes in each row
picPtr |  | Long—pointer to the uncompressed SHR data
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTECopyPicToBG1(width, height, stride, picPtr)`

`Word width;`

`Word height;`

`Word stride;`

`Pointer picPtr;`

#### $18XX

#### GTEBindSCBArray

Binds an array of SCB values to either the primary or secondard background layer. This will automatically update the SHR screen SCB values as the vertical offset of the designated background layer changes.

The SCB updates are not synchronized with the VBL, so care should be taken to select palette values that minimize flicker when adjacent lines have different palette assignements and the page is scrolling quickly.

##### Parameters

Stack before call
previous contents
scbPtr |  | Long—pointer to an array of SCB values. The size of the array is defined by the largest verical offset that the application expects to use.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEBindSCBArray(scbPtr)`

`Pointer scbPtr;`

#### $19XX

#### GTEGetBG0TileMapInfo

Returns information about the current BG0 tile map.

##### Parameters

Stack before call
previous contents
longspace |  | Long—Space for result
wordspace |  | Word—Space for result
wordspace |  | Word—Space for result
| ← | SP

Stack after call
previous contents
tileMapPtr |  | Long—pointer to the tile map.
height |  | Word—Height of the tilemap in tiles.
width |  | Word—Width of the tilemap in tiles.
| ← | SP

##### Errors

None

##### C

`extern pascal struct TileMapInfo GTEGetBG0TileMapInfo()`

#### $1AXX

#### GTEGetScreenInfo

Returns information about the current position and size of the play field.

##### Parameters

Stack before call
previous contents
wordspace |  | Word—Space for result
wordspace |  | Word—Space for result
wordspace |  | Word—Space for result
wordspace |  | Word—Space for result
| ← | SP

Stack after call
previous contents
height |  | Word—Height of the playfield in lines.
width |  | Word—Width of the playfield in bytes.
y |  | Word—Vertical coordinate of the upper-left corner.
x |  | Word—Horizontal coordinate of the upper-left corner.
| ← | SP

##### Errors

None

##### C

`extern pascal struct ScreenInfo GTEGetScreenInfo()`

#### $1BXX

#### GTESetBG1Origin

Sets the coordinate of the upper-left corner of the playfield within the secondary background buffer. The coordiate values are unsigned, so transitioning from 0 to -1 will result in a discontinuous jump in the background position.

##### Parameters

Stack before call
previous contents
xpos |  | Word—Unsigned horizontal position
ypos |  | Word—Unsigned vertical position
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG1Origin(x, y)`

`Word x;`

`Word y;`

#### $1CXX

#### GTEGetTileAt

Returns the tile at a local coordinate poiint. The primary use of this function is to lookup a Tile ID using a sprite's coordinates.

##### Parameters

Stack before call
previous contents
wordspace |  | Word—Space for result
x |  | Word—Local play field horizontal coordinate
y |  | Word—Local play field vertical coordinate
| ← | SP

Stack after call
previous contents
TileID |  | Word—Tile ID at the play field coordinates.
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEGetTileAt(x, y)`

`Word x;`

`Word y;`

#### $1DXX

#### GTESetBG0TileMapInfo

Sets a tile map that will be used to automatically populate the primary background layer based on the current origin. Behavior is undefined if the origin is set to a value that is outside the bounds of the tilemap.

##### Parameters

Stack before call
previous contents
width |  | Word—Width of the tilemap in tiles.
height |  | Word—Height of the tilemap in tiles.
tileMapPtr |  | Long—pointer to the tile map
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG0TileMapInfo(width, height, tileMapPtr)`

`Word width;`

`Word height;`

`Pointer tileMapPtr;`

##### Tile Map Entries

The values in a tilemap are an array of 16-bit values.

15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

Bits 0-8 | tileIndex | The index of a tile in the current Tile Set
Bit 9 | TILE_HFLIP_BIT | Flip the tile horizontally when rendering.
Bit 10 | TILE_VFLIP_BIT | Flip the tile vertically when rendering.
Bit 11 | TILE_DYN_BIT | Marks a tile to use the dynamic tile data. The tileIndex must be between 0 and 31 if this bit is set.
Bit 12 | TILE_SOLID_BIT | A hint bit that is used in ENGINE_MODE_TWO_LAYER to improve performance.
Bit 13 | TILE_FRINGE_BIT | Unused. Must be zero.
Bit 14 | TILE_PRIORITY_BIT | Sets the tile to be high priority to render on top of sprites.
Bit 15 | Reserved | Must be zero.

#### $1EXX

#### GTESetBG1TileMapInfo

Sets a tile map that will be used to automatically populate the secondary background layer based on the current origin. Behavior is undefined if the origin is set to a value that is outside the bounds of the tilemap.

##### Parameters

Stack before call
previous contents
width |  | Word—Width of the tilemap in tiles.
height |  | Word—Height of the tilemap in tiles.
tileMapPtr |  | Long—pointer to the tile map
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG1TileMapInfo(width, height, tileMapPtr)`

`Word width;`

`Word height;`

`Pointer tileMapPtr;`

#### $1FXX

#### GTEAddTimer

Adds a timer with a callback function and a delay in VBL ticks. Timers may be repeated or one-shot timers. A one-shot timer will remove itself after firing. Timers are handled on a best-effort basis. It is possible that a timer callback could be invoked multiple times in a single frame and the callback functions should account for this possibility.

The intended use for timers is to provide a way to perform animations and game physics at a consistent rate, regardless of the speed of the machine. If a timer has not been invoked for over one second, then it will not fire multiple times, but treat the current timestamp as its starting point. This is to avoid a "callback storm" if timers are added then a long period of time elapses. It is recommended that timers be removed if they are not expected to be fired on a regular basis.

##### Parameters

Stack before call
previous contents
wordspace |  | Word—Space for result.
numTicks |  | Word—Number of VBL ticks to wait before firing.
callback |  | Long—A pointer to a user function.
flags |  | Word—The only valid values are `$0001` for a one-shot timer or `$0000` for a timer that resets.
| ← | SP

Stack after call
previous contents
timerID |  | Word—An opaque identifier of the timer. This value must be passed to the `GTERemoveTimer()` function.
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEAddTimer(numTicks, callback, flags)`

`Word numticks;`

`Pointer callback;`

`Word flags;`

#### $20XX

#### GTERemoveTimer

Removed a timer that had been added to the system.

##### Parameters

Stack before call
previous contents
timerID |  | Word—ID of the timer.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTERemoveTimer(timerID)`

`Word timerID;`

#### $21XX

#### GTEStartScript

This API is under active development at this time.

##### Parameters

Stack before call
previous contents
numTicks |  | Word—Number of ticks between script invocations.
scriptAddr |  | Long—pointer to the script bytecode.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEStartScript(numTicks, scriptAddr)`

`Word numTicks;`

`Pointer scriptAddr;`

#### $22XX

#### GTESetOverlay

This API is under active development at this time.

##### Parameters

Stack before call
previous contents
top |  | Word—Top screen line of the overlay
bottom |  | Word—Bottom screen line of the overlay.
procPtr |  | Long—pointer to the callback function.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTESetOverlay(top, bottom, procPtr)`

`Word top;`

`Word bottom;`

`Pointer procPtr;`

#### $23XX

#### GTEClearOverlay

Removes the active overlay. This API is under active development at this time.

##### Parameters

Stack before call
previous contents
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal Word GTEClearOverlay()`

#### $24XX

#### GTEGetTileDataAddr

Returns a pointer to the bottom of the internal tile data memory. The data for each tile can be found at offset `N * 128`

##### Parameters

Stack before call
previous contents
longspace |  | Long—Space for result
| ← | SP

Stack after call
previous contents
tileDataPtr |  | Long—pointer to the tile data
| ← | SP

##### Errors

None

##### C

`extern pascal Pointer GTEGetTileDataAddr()`

#### $25XX

#### GTEFillTileStore

Fills the entire Tile Store with a specific Tile ID value.

##### Parameters

Stack before call
previous contents
tileID |  | Word—Tile ID to store into the tile store memory.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEFillTileStore(tileID)`

`Word tileID;`

#### $26XX

#### GTERefresh

Forces a refresh of the play field. This is implemented by adding all of the visible tiles to the dirty tile queue which will force them to be redrawn on the next call to `GTERender()`.

##### Parameters

The stack is not affected by this call. There are no input or output parameters.

##### Errors

None

##### C

`extern pascal void GTERefresh()`

#### $27XX

#### GTESetBG1Displacement

Sets a displacement into the BG1 offset table. Must be a value between 0 and 31.

##### Parameters

Stack before call
previous contents
offset |  | Word—Offset index.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG1Displacement(offset)`

`Word offset;`

#### $28XX

#### GTESetBG1Rotation

Sets the rotation angle of the BG1 buffer. There are 64 sets in the angle tables, so the value must be between 0 and 63.

##### Parameters

Stack before call
previous contents
rotIndex |  | Word—Rotation index. Must be between 0 and 63.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTESetBG1Rotation(rotIndex)`

`Word rotIndex;`

#### $29XX

#### GTEClearBG1Buffer

Clears the BG1 pixel buffer with a 16-bit value.

##### Parameters

Stack before call
previous contents
value |  | Word—16-bit value to fill all of BG1 memeory.
| ← | SP

Stack after call
previous contents
| ← | SP

##### Errors

None

##### C

`extern pascal void GTEClearBG1Buffer(value)`

`Word value;`