+
+
+
+
+
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 |
+
+
+
+ | 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 |
+ | 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 map index |
+
+ | Primary Background Routines |
|---|
+ | GTESetBG0Origin | Sets the upper-left origin point in the primary background |
+ | GTERender | Draws the current scene to the graphics screen |
+
+ | Functions affecting the global state |
|---|
+ | GTESetScreenMode | Sets the playing field's port rectangle to a pre-defined size, or a specified width and height |
+
+ | 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 |
|---|
+
+ | $01 | #01 | Tool Locator | 3.x |
+ | $02 | #02 | Memory Manager | 3.x |
+ | $03 | #03 | Miscellaneous Tool Set | 3.2 |
+ | $06 | #06 | Event Manager | 3.1 |
+
+
+
+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.
+
+
+
+
+
+
+
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 | Application word returned by the Memory Manager. All memory allocated by GTE will use this userId |
+ | ← | 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
+
+
+
Parameters
+
+ The stack is not affected by this call. There are no input or output parameters.
+
+
+
+
+
+
+
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 |
+
+
+
+
+
+
+
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
+
+
+
+
+
+
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 |
+
+
+
+
+
+
+
C
+
extern pascal Boolean GTEStatus()
+
+
+
+
+GTE Tool Set routines
+
+
+
+
$09XX
+
GTEGetAddress
+
+
+ Returns the address of an internal GTE Tool Set array.
+
+
+
+
+ | Stack before call |
|---|
+ | previous contents |
+ | addrId | | WORD — INTEGER id |
+ | longspace | | Long — Space for result |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+
| address | | Long — POINTER to data structure |
+ | ← | SP |
+
+
+
+
+
Errors
+
+ | $XX04 | gteBadAddress | The id is invalid |
+
+
+
+
+
C
+
extern pascal Pointer GTEGetAddress(id)
+Word id
+
+
+
+
+
+
$0CXX
+
GTENewSprite
+
+
+ Allocates space for a new sprite and compiles it based on the pixel data in the locInfoPtr arguement. The sprite flags word is used to enable or disable certain capabilities. If an application does not need the all the features enabled, features may be disabled to save memory and slightly increase performance.
+
+
+
+
+
+
Parameters
+
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ptrToDataLocInfo | | Long — POINTER to data location information. |
+ | ptrToDataRect | | Long — POINTER to a Rect that defines the sprite bounds. |
+ | ptrToMaskLocInfo | | Long — POINTER to mask location information; may be nil. |
+ | ptrToMaskRect | | Long — POINTER to a Rect that defines the sprite bounds; may be nil. |
+ | spriteFlags | | Word — INTEGER; sprite flags |
+ | longspace | | Long — Space for result |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+
| spriteHandle | | Long — HANDLE to new sprite |
+ | ← | SP |
+
+
+
+
+
+
+
C
+
extern pascal SpriteHandle GTENewSprite(data, mask, spriteFlags)
+locInfoPtr data
+locInfoPtr mask
+Word spriteFlags
+
+
+
+
+
+
Sprite Flags
+
+
+
+
+ The values available for spriteFlags are shown in Figure ??-??.
+
+
+
+
+
+
+ | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+
+
+
+
+
+ | | |
|---|
+ | Bits 0 | spriteType | Reserved; must be zero |
+ | Bit 1 | fNoHFlip | Do not create a horizontally flipped version of the sprite. Setting the horizontal flip bit in the Object Attribute Memory will have no effect. |
+ | Bit 2 | fNoVFlip | Do not create a vertically flipped version of the sprite. Setting the vertical flip bit in the Object Attribute Memory will have no effect. |
+ | Bit 3 | fNoPriority | Do not generate code to honor the field mask. Seting the priority bit in the Object Attribute Memory will have no effect. |
+ | Bit 4 | fNoMask | This sprite will not clip itself to the playing fields. This is potentially dangerous since, if the sprite move off screen, it may corrupt system memory. Only use this bit if the sprite will never leave the playing field. |
+ | Bits 5-15 | Reserved | must be zero. |
+
+
+
+
+
$0DXX
+
GTEDisposeSprite
+
+
+
Parameters
+
+
+ | Stack before call |
|---|
+ | previous contents |
+ | spriteHandle | | Long — Handle to a sprite returned by GTENewSprite. |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
C
+
extern pascal void GTEDisposeSprite(spriteHndl)
+Handle spriteHndl
+
+
+
+
+
+
+
+
$0FXX
+
GTENewTile
+
+
+ Allocates space for a new tile and compiles it based on the pixel data referenced by the locInfoPtr arguements. If the mask infoRecPtr is nil, then the mask is computed using the current backgound color. The mask is only used when the tile map specifies the tile to be drawn at high priority.
+
+
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ptrToDataLocInfo | | Long — POINTER to data location information. |
+ | ptrToDataOrigin | | Long — POINTER to Point that marks the top-left corner. |
+ | ptrToMaskLocInfo | | Long — POINTER to mask location information; may be nil. |
+ | ptrToMaskOrigin | | Long — POINTER to Point that marks the top-left corner; may be nil. |
+ | longspace | | Long — Space for result |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | tileHandle | | Long — HANDLE to new tile |
+ | ← | SP |
+
+
+
+
+
+
+
C
+
extern pascal TileHandle GTENewTile(ptrToDataLocInfo, ptrToDataOrigin, ptrToMaskLocInfo, ptrToMaskOrigin)
+locInfoPtr ptrToDataLocInfo
+Point* ptrToDataOrigin
+locInfoPtr ptrToMaskLocInfo
+Point* ptrToMaskOrigin
+
+
+
+
+
+
$10XX
+
GTEDisposeTile
+
+
+
Parameters
+
+
+ | Stack before call |
|---|
+ | previous contents |
+ | tileHandle | | Long — Handle to a tile returned by GTENewTile. |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
C
+
extern pascal void GTEDisposeTile(tileHandle)
+Handle tileHandle
+
+
+
+
+
+
$11XX
+
GTESetTile
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
$12XX
+
GTEGetTile
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
Buffer Functions
+
+
+
GTESetBG0Fringe
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG0Mask
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG0Dynamic
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG0Palettes
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG0Origin
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG1Tiles
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTESetBG1Origin
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTERefreshAll
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTERefreshBG0
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTERefreshBG1
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
I/O Functions
+
+
+
GTELoadAPF
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTELoadBMP
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTELoadSHR
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+
+
+
GTELoadFile
+
+
Parameters
+
+ | Stack before call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+ | Stack after call |
|---|
+ | previous contents |
+ | ← | SP |
+
+
+
+
+
+