Inside Macintosh: Apple Game Sprockets Guide /

Chapter 3 - InputSprocket

About InputSprocket

InputSprocket is the part of Apple Game Sprockets through which games can communicate with joysticks and other game-oriented input devices, as well as the keyboard and mouse. Most games on the MacOS access game input devices through emulation on the keyboard and mouse. This strategy suffers from two problems--complex devices and configuration difficulties.

Todays input devices may have directional pads, levers, point of view hats, wheels, and several buttons and a game may use several input devices. Such complexity becomes impossible to emulate through a mouse and keyboard. Even with simple devices, configuration can be a two-step process. The user has to go to the device to configure what keys and mouse actions it generates and then go to the game to configure which keys and mouse actions it accepts. The user can become confused if the configurations of device and game don't mesh.

InputSprocket solves these problems by creating an input device architecture that allows games developers to create innovative games that can use a wide variety of input devices. Input device developers can use InputSprocket to build device drivers that provide a description of input device controls that the game can use to automatically configure its control options. The device driver can also provide a user interface that allows the user to change default control options.

During game play, the game determines the state and transitions of input device controls through polling or a simple event queue.

Elements

InputSprocket bases communication between games and input devices on elements. An element is a building block used to describe a device. Each control on the device has a corresponding element, so any device, no matter how complex, can be described by a handful of elements. For example, a simple input device with two buttons and a thrust lever consisting of an x-axis and y-axis could be described by four elements. A complex device with many more axes, several buttons, and directional pads might require 12 or more elements.

Three pieces of data describe a given element: a human readable identifier, a kind, and a label. The human readable identifier is a string that a game can display to identify that element for the user during configuration--for example, "trigger" or "thumb button".

The kind is an four-character sequence that identifies the type of data the element produces. For example, it produces data like a button (two states) or like an axis (continuous data). Currently, InputSprocket defines four kinds of elements to correspond to four kinds of controls-- button, directional pad, axis, and general movement. (A fifth element kind identifies virtual elements.)

• A button element is a two-state element. It both generates events and can be polled--for example, a mouse button, keyboard key, or joystick trigger. It is by far the most common input element.
• A directional pad element is a nine state element. It has an idle position and eight states corresponding to eight directions--for example, a point of view hat on a joystick or a directional pad on a Sega controller. (Some directional pads have only four directions.)
• There are two types of axis elements. One is a symmetrical axis that the user sees as being continuous and having a meaningful center position--for example, the axis of a joystick. The other type of axis is one that the user sees as being continuous but without a meaningful center position--for example, a gas pedal or a brake.
• A movement element produces data that is given both as x-y axis data and directional pad data, allowing the game to use whichever is suitable.

Apple may define other element kinds later, and device driver developers can create element kinds as well. The kind imposes a structure on the data. For a description of existing element kinds, see "Built-in Element Kinds" (page 3-18).

A label is a four-character sequence that gives the suggested use for an element. For example, a button element may be intended as the start button or the firing button. During configuration, a game uses labels to find the elements it requires for play. For a description of existing labels, see "Built-in Element Labels" (page 3-19).

Device Configuration

When InputSprocket is loaded, it loads all the InputSprocket drivers, which it finds by scanning the Extensions folder. Each device driver provides information about its controls, which InputSprocket stores for use by the game during configuration and play.

For each element corresponding to a control, the driver specifies the element kind, label, and human readable identifier and identifies elements that work as a unit--for example, sets of x-axis and y-axis elements on a control that has both a joystick and a throttle. It gives the size of the data produced by the element so that functions that get data can allocate sufficient memory to hold it.

The device driver also fills out a configuration information structure for each control. These structures contain information specific to the element kind, for example, whether a directional pad has four directions or eight. The game may use the information during configuration and to interpret data from the control during play.

For more information, see the documentation provided for input device developers on Apple's Web site.

Game Configuration

Games must match their input requirements with input device controls on the system. InputSprocket makes this easy by

• giving the games a standard way to publish their requirements for input
• providing functions for autoconfiguration and user reconfiguration

When a game is loaded, it fills out a need structure to provide information about each type of input it wants to receive. When the game is ready for configuration, it calls the ISpInit function. This function organizes the information in the need structures into a list of input requirements that InputSprocket can pass around to the input device drivers. Each device driver inspects the list and checks off requirements it can fulfill. The device driver keeps track of which of its device elements will be providing data to the game. For more information on need structures see "Need Structure" (page 3-29).

After calling ISpInit to perform autoconfiguration, the game can call the ISpConfigure function to put up a modal window where the user can make changes to the configuration. Each device driver manages its own user configuration process with some help from InputSprocket, which is still aware of the game's input requirements.

In one possible model for user configuration, the device driver lists the requirements the game has for control--for example, move horizontally, fire, jump, duck, and so on. Next to the list of input requirements, it displays a list of controls, using the elements' human readable identifiers to name the controls that can meet those needs. The user could select a requirement from the list and then activate one of the controls to indicate which control the user wants to use to meet that input requirement. For example, after selecting "duck" the user could push button three on the joystick.

Apple recommends that game developers take advantage of the configuration functions provided by InputSprocket. However, it is possible for a game to perform configuration using other functions. Since every element in the system has a label suggesting a use for the control that element represents, the game can search for elements with specific labels. If the game can't find an element with that label, it can use the element kind information to find an element that generates the type of data it wants. InputSprocket provides functions to help you search for elements by kind and by label.

Devices that provide several elements of the same kind that have the same label or no meaningful label can order the elements. This lets the game know which control to use first. The device driver puts ordering information in the id field of the trigger, button, and directional pad configuration structures. After finding the elements that best match its input needs, the game would need to let the user know which physical controls correspond to the game controls.

Obtaining Data During Play

There are two ways for the game to obtain information from the input device during play--polling and events. It takes only a single call to determine the state of any element.

You can get events over all the elements in the system, but a game usually polls elements such as axes and uses an event queue for elements such as buttons. InputSprocket provides several functions for searching the system and building a list of elements so that the game can get the next event on the list. Don't add those elements you don't want to get events for to your element list; instead, get their current state by polling.

InputSprocket uses the element event structure to pass event data. See "Element Event Data Structure" (page 3-28).