iigs-game-engine/docs/toolboxref.markdown

layout	title	style	permalink
page	Toolbox Reference	toolref	/tool-ref/

• Intialization Functions
• Sprite Functions
• Tile Functions
• Buffer Functions
• I/O 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
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
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
$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.

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	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.

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

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

Errors

None

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

Error

None

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

Erros

None

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

Error

None

C

extern pascal void GTEDisposeTile(tileHandle)
Handle       tileHandle

$11XX

GTESetTile

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

$12XX

GTEGetTile

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

Buffer Functions

GTESetBG0Fringe

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG0Mask

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG0Dynamic

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG0Palettes

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG0Origin

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG1Tiles

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTESetBG1Origin

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTERefreshAll

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTERefreshBG0

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTERefreshBG1

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

I/O Functions

GTELoadAPF

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTELoadBMP

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTELoadSHR

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern

GTELoadFile

Parameters

Stack before call
previous contents
	←	SP

Stack after call
previous contents
	←	SP

Errors	None
C	extern