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

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

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.

1514131211109876543210
Bits 0-6keyCodeKeyboard code read from the Keyboard register. If no key is currently pressed, this value is zero.
Bit 7ReservedAlways zero.
Bit 8PAD_BUTTON_BSet to 1 if the B button of the gamepad is pressed. Mapped to the option key by default.
Bit 9PAD_BUTTON_ASet to 1 if the A button of the gamepad is pressed. Mapped to the command key by default.
Bit 10PAD_KEY_DOWNSet 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-15ReservedAlways 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

1514131211109876543210
Bits 0-8tileIndexThe index of the tile in the current Tile Set. A Tile Set can be defined by calling the GTELoadTileSet function
Bit 9fTileHFlipFlips the tile horizontally when set.
Bit 10fTileVFlipFlips the tile vertically when set.
Bit 11fTileDynamicIdentifies 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 12fTileSolidHint bit that marks a tile as having no mask. Can improve performance when ENGINE_MODE_TWO_LAYER is set.
Bit 13fTileFringeUnused. Must be zero.
Bit 14fTilePrioritySets the tile to high priority. Sprites will render under this tile, if supported.
Bit 15ReservedMust 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.

1514131211109876543210
Bits 0-8tileIndexThe index of a tile in the current Tile Set that defines the top-left part of the sprite
Bit 9-10ReservedMust be zero.
Bits 11-12fSpriteSizeSets the size of the sprite
  • 00 - 8x8
  • 01 - 8x16
  • 10 - 16x8
  • 11 - 16x16
Bit 13-15ReservedMust 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.

1514131211109876543210
Bits 0-8tileIndexThe index of a tile in the current Tile Set that defines the top-left part of the sprite
Bit 9SPRITE_HFLIPFlips the sprite horizontally.
Bit 10SPRITE_VFLIPFlips the sprite vertically.
Bits 11-12SPRITE_SIZESets the size of the sprite
  • 00 - 8x8
  • 01 - 8x16
  • 10 - 16x8
  • 11 - 16x16
Bit 13SPRITE_HIDEWhen set, does not render the sprite.
Bit 14-15ReservedMust 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
xpos ypos
Stack before call
previous contents
Word—Unsigned horizontal position
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.

1514131211109876543210
Bits 0-8tileIndexThe index of a tile in the current Tile Set
Bit 9TILE_HFLIP_BITFlip the tile horizontally when rendering.
Bit 10TILE_VFLIP_BITFlip the tile vertically when rendering.
Bit 11TILE_DYN_BITMarks a tile to use the dynamic tile data. The tileIndex must be between 0 and 31 if this bit is set.
Bit 12TILE_SOLID_BITA hint bit that is used in ENGINE_MODE_TWO_LAYER to improve performance.
Bit 13TILE_FRINGE_BITUnused. Must be zero.
Bit 14TILE_PRIORITY_BITSets the tile to be high priority to render on top of sprites.
Bit 15ReservedMust 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;