diff --git a/docs/toolboxref.html b/docs/toolboxref.html new file mode 100644 index 0000000..39743df --- /dev/null +++ b/docs/toolboxref.html @@ -0,0 +1,2366 @@ +--- +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
RoutineDescription
Housekeeping Routines
GTEBootInitInitializes the GTE Tool Set; called only by the Tool Locator — must not be called by an application
GTEStartUpStarts up the GTE Tool Set for use by an application
GTEShutDownShuts down the GTE Tool Set when an application quits
GTEVersionReturns the version number of the GTE Tool Set
GTEResetResets the GTE Tool Set; called only when the system is reset — must not be called by an application
GTEStatusIndicates whether the GTE Tool Set is active
Sprite Routines
GTECreateSpriteStamp Creates a sprite stamp from the tile set
GTEAddSpriteAdd a active sprite to the scene
GTEMoveSpriteChanges a sprite's location
GTEUpdateSpriteChanges a sprite's tile set reference and display flags
GTERemoveSprite Removes a sprite from the scene
Tile Routines
GTELoadTileSetCopies a tileset into the GTE tileset memory
GTESetTileAssigns a tile to a tile store
GTEGetTileAtRetrieves the tile ID stored in the tile store
GTECopyTileToDynamicCopies 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()
GTEGetTileDataAddrReturns the base address of the tiledata memory
GTEFillTileStoreFills the entire tile store with a tile ID.
Primary Background Routines
GTESetBG0OriginSets the upper-left origin point in the primary background
GTERenderDraws the current scene to the graphics screen
GTEGetBG0TileMapInfoReturns a record describing the number of tiles in the primary tilemap and a pointer to the tilemap data. +
GTESetBG0TileMapInfoDefines a tile map for the primary background
GTERefreshForces all of the tiles in the tile store to be refreshed on the next render.
Secondary Background Routines
GTESetBG1OriginSets the upper-left origin point in the secondary background
GTECopyPicToBG1Copies an uncompressed pixel image into the secondard background buffer
GTESetBG1TileMapInfoDefines a tile map for the secondary background
Timer Routines
GTEAddTimerAdd a timer callback that is fired after a designated number of VBL ticks
GTERemoveTimerRemoves an active timer
GTEStartScriptRegisters a GTE script to be handled in the background
Overlay Routines
GTESetOverlayRegisters an overlay routine to be integrated into the renderer. Typically used for status bars or + messages.
GTEClearOverlayRemoves the current overlay from the renderer
Functions affecting the global state
GTESetScreenModeSets the playing field's port rectangle to a pre-defined size, or a specified width and height
GTESetPaletteCopies a palette to the Super HiRes palette memory
GTEBindSCBArrayTakes an array of SCB bytes and binds them to either the Primary or Secondary background's vertical + position
GTEGetScreenInfoReturns a records describing the origin, width and height of the playfield on the physical graphics + screen.
Misc. Functions
GTEReadControlReads the keyboard and returns key events in a gamepad structure
GTEGetSecondsReturns 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 numberTool set nameMinimal version needed
$01#01Tool Locator3.x
$02#02Memory Manager3.x
$03#03Miscellaneous Tool Set3.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
dPageAddrWord — 16-bit address of two pages of page-aligned Bank 0 memory
capFlagsWord — Capability flags to set the engine mode
userIDWord — 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$0001Enables the second background layer. This will have a moderate impact on rendering performance.
ENGINE_MODE_DYN_TILES$0002Enables 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$0004Allocates a 32KB buffer in Bank 0 for advanced graphical effects and customizations.
+
+ +
+
Errors
+ + + + + + + +
Memory Manager ErrorsReturned 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
wordspaceWord — Space for result
←SP
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
versionInfoWord — 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
wordspaceWord — Space for result
←SP
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
activeFlagWord — 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
wordspaceWord — Space for result
←SP
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
userInputWord — packed representation of user input +
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0AXX

+

GTESetScreenMode

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0BXX

+

GTESetTile

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0CXX

+

GTESetBG0Origin

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0DXX

+

GTERender

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0EXX

+

GTELoadTileSet

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$0FXX

+

GTECreateSpriteStamp

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$10XX

+

GTEAddSprite

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$11XX

+

GTEMoveSprite

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$12XX

+

GTEUpdateSprite

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$13XX

+

GTERemoveSprite

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$14XX

+

GTEGetSeconds

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$15XX

+

GTECopyTileToDynamic

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$16XX

+

GTESetPalette

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$17XX

+

GTECopyPicToBG1

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$18XX

+

GTEBindSCBArray

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$19XX

+

GTEGetBG0TileMapInfo

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1AXX

+

GTEGetScreenInfo

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1BXX

+

GTESetBG1Origin

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1CXX

+

GTEGetTileAt

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1DXX

+

GTESetBG0TileMapInfo

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1EXX

+

GTESetBG1TileMapInfo

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$1FXX

+

GTEAddTimer

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$20XX

+

GTERemoveTimer

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$21XX

+

GTEStartScript

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$22XX

+

GTESetOverlay

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$23XX

+

GTEClearOverlay

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$24XX

+

GTEGetTileDataAddr

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$25XX

+

GTEFillTileStore

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +
+

$26XX

+

GTERefresh

+

+
+
Parameters
+ + + + + + + + + + + + + + + + + + + +
Stack before call
previous contents
←SP
+ + + + + + + + + + + + + + + + + + + + +
Stack after call
previous contents
←SP
+
+
+
Errors
+
+
+
C
+
+
+ +