Toolbox Reference
- 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 | |
| GTECompileSpriteStamp | 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
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()
$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_ROTATION | $0008 | Use the internal rotation tables to render the secondary background |
| RENDER_PER_SCANLINE | $0010 | Set individual scanline properties for the primary and secondary backgrounds from a table. |
| RENDER_WITH_SHADOWING | $0020 | Uses a rendering mode that does not draw sprites into the tiles but uses shadowing to draw sprites on top of the rendered background and then expose the final composited image. This mode is required to use compiled sprites. |
| RENDER_SPRITES_SORTED | $0040 | Draws the sprite in y-sorted order instead of sprite slot order. |
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
|
| 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
|
| 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;