Inside Macintosh: Apple Game Sprockets Guide /

Chapter 3 - InputSprocket / InputSprocket Reference

InputSprocket Functions / Configuring the Application

ISpInit

You can use the ISpInit function to initialize the InputSprocket layer and autoconfigure all the devices.

OSStatus ISpInit (
	UInt32 count,
	ISpNeed *needs,
	ISpElementReference *inReferences,
	OSType appCreatorCode,
	OSType subCreatorCode,
	UInt32 flags,
	short setListResourceID
	UInt32 version);

count

The number of input requirements the game has. Each requirement is described in an ISpNeed structure.

needs

A pointer to an array of ISpNeed structures. The order of the need structures in the array is important because the input devices will try to fulfill input requirements beginning with the first need structure in the array. More important requirements should be put first--for example, "jump" before "look at map."

inReferences

A pointer to an array of virtual elements identifying the elements that can meet your game's input requirements. The array will contain the number of element references specified in the count parameter. You can use all the usual calls to get events or poll these element references.

appCreatorCode

The creator code of the application.

subCreatorCode

The subcreator code. InputSprocket and device drivers use a union of the creator and subcreator codes to save and restore preferences. For every pair of codes the game's requirements for input should be identical; otherwise, there is an unknown result. The subcreator code gives you a domain in which to have multiple different preference settings within any given application.

flags

Leave as 0.

setListResourceID

A resource of type kISpSetListResourceType. See "The InputSprocket Set List Resource" (page 3-58)

version

The version of InputSprocket the game depends on.

function result

A result code.

DESCRIPTION

The ISpInit function takes the number of input requirements in the count parameter, a pointer to an array of need structures in the needs parameter, and a pointer to an array of virtual element references in the inReferences parameter. A virtual element reference does not correspond to any physical control on a physical device. Devices push data into a virtual element reference when they have data that corresponds to the input requirement that reference represents. DrawSprocket provides two functions for creating virtual elements--ISpElement_NewVirtual (page 3-36) and ISpElement_NewVirtualFromNeeds (page 3-36).

To determine which elements can meet the game's requirements for input, ISpInit goes down a list of system devices and asks each device in turn if it can meet any of the requirements listed in the needs array. On the list of system devices, which is created the first time InputSprocket is loaded, the keyboard appears last and the mouse next to last; there is no particular order for other devices. The game can use the following InputSprocket routines for extracting devices from the list and deactivating or activating devices to eliminate devices that are unsuited to the game from the list: the ISpDevices_Extract function (page 3-38), the ISpDevices_ExtractByClass function (page 3-39), the ISpDevices_ExtractByIdentifier function (page 3-40), the ISpDevices_Activate function (page 3-41), and the ISpDevices_Deactivate function (page 3-41).

As each device tries to fulfill the input requirements, it looks at the need structures in the order in which they appear in the array. If a particular requirement has already been fulfilled by a prior device and has the kInputSprocketNoMultiConfig flag set in the ISpNeed structure flags field, the device will ignore it. The device driver keeps track of how its actual device elements are matched to the virtual element references it creates-- in other words, which elements will meet which input requirements.

For each device driver, InputSprocket stores its configuration information, using the codes passed in the appCreatorCode and subCreatorCode parameters to identify them for future use.

The game passes a resource of type kISpSetListResourceType in the setListResourceID parameter. The game also passes a version number in the version parameter so that if the system is running an incompatible version of InputSprocket, the user can be alerted.

CALLING RESTRICTIONS

Do not call during interrupt time.