Inside Macintosh: Apple Game Sprockets Guide /

Chapter 3 - InputSprocket

Summary of InputSprocket

Constants

Built-in Device Categories

enum {
   kIspDeviceClass_SpeechRecognition ='talk',
   kISpDeviceClass_Mouse =    'mous',
   kISpDeviceClass_Keyboard = 'keyd',
   kISpDeviceClass_Joystick = 'joys',
   kISpDeviceClass_Wheel =    'whel',
   kISpDeviceClass_Pedals =   'pedl',
   kISpDeviceClass_Levers =   'levr'
};

Built-in Element Kinds

enum {
   kISpElementKind_Button =   'butn',
   kISpElementKind_DPad =     'dpad',
   kISpElementKind_Axis =     'axis',
   kISpElementKind_Movement = 'move'
   kISpElementKind_Virtual =  'virt'
};

Built-in Element Labels

enum {
   kISpElementLabel_None = 'none',

   kISpElementLabel_XAxis = 'xaxi',
   kISpElementLabel_YAxis = 'yaxi',
   kISpElementLabel_ZAxis = 'zaxi',

   kISpElementLabel_Rx =   'rxax',
   kISpElementLabel_Ry =   'ryax',
   kISpElementLabel_Rz =   'rzax',

   kISpElementLabel_Gas =  'gasp',
   kISpElementLabel_Brake ='brak',
   kISpElementLabel_Clutch = 'cltc',

   kISpElementLabel_Throttle = 'thrt',
   kISpElementLabel_Trim = 'trim',
   kISpElementLabel_POVHat = 'povh',
   kISpElementLabel_PadMove = 'move',

   kISpElementLabel_Fire = 'fire',
   kISpElementLabel_Start = 'strt',
   kISpElementLabel_Select = 'optn'
};

Button Element Data Information

typedef enum {
   kISpButtonUp =             0,
   kISpButtonDown =           1
} ISpButtonData;

Directional Pad Element Data Information

typedef enum {
   kISpPadIdle =            0,
   kISpPadLeft,
   kISpPadUpLeft,
   kISpPadUp,
   kISpPadUpRight,
   kISpPadRight,
   kISpPadDownRight,
   kISpPadDown,
   kISpPadDownLeft
} ISpDPadData;

Axis Element Data Information

#define kISpAxisMinimum  0x00000000U
#define kISpAxisMiddle   0x7FFFFFFFU
#define kISpAxisMaximum  0xFFFFFFFFU

Need Flags

typedef enum ISpNeedFlagBits {
   kISpNeedFlag_NoMultiConfig = 1
};

Virtual Element Flag

{
   kISpVirtualElementFlag_UseTempMem = 1
};

Element List Flag

enum
{
   kISpElementListFlag_UseTempMem = 1
};

Resource Types

enum
{
   kISpSetListResourceType =  'setl',
   kISpSetDataResourceType =  'setd'
};

Data Types

typedef struct ISpDevicePrivate  *ISpDeviceReference; 
typedef struct ISpElementPrivate *ISpElementReference; 
typedef struct ISpElementListPrivate *ISpElementListReference; 
typedef OSType ISpDeviceClass;
typedef OSType ISpDeviceIdentifier;
typedef OSType ISpElementLabel;
typedef OSType ISpElementKind;

Device Definition Structure

typedef struct ISpDeviceDefinition {
   Str63             deviceName; 
   ISpDeviceClass    theDeviceClass;
   ISpDeviceIdentifier theDeviceIdentifier;
   UInt32            permanentId;
   UInt32            flags;
   UInt32            reserved1;
   UInt32            reserved2;
   UInt32            reserved3;
} ISpDeviceDefinition;

Element Information Structure

typedef struct ISpElementInfo {
   ISpElementLabel      theLabel;
   ISpElementKind       theKind;
   Str63                theString;
   UInt32               reserved1;
   UInt32               reserved2;
} ISpElementInfo, *ISpElementInfoPtr;

Button Configuration Information Structure

typedef struct {
   UInt32               id;
} ISpButtonConfigurationInfo;

Directional Pad Configuration Information Structure

typedef struct {
   UInt32               id;
   Boolean              fourWayPad;
} ISpDPadConfigurationInfo;

Axis Configuration Information Structure

typedef struct {
   Boolean              SymetricAxis; 
} ISpAxisConfigurationInfo;

Movement Data Structure

typedef struct ISpMovementData {
   UInt32               xAxis;
   UInt32               yAxis;
   UInt32               direction; 
};

Element Event Data Structure

typedef struct {
   AbsoluteTime      when;
   ISpElementReference element;
   UInt32            refCon;
   Uint32            data; 
} ISpElementEvent, *ISpElementEventPtr;

Need Structure

typedef struct ISpNeed {
   Str63             name;
   short             iconSuiteResourceId;
   ISpElementKind    theKind;
   ISpElementLabel   theLabel;
   UInt32            flags;
   UInt32            emulateHow;
   UInt32            emulationData1;
   UInt32            emulationData2;
} ISpNeed;

InputSprocket Functions

Configuring the Application

OSStatus ISpInit              (UInt32 count,
                               ISpNeed *needs,
                               ISpElementReference *inReferences,
                               OSType appCreatorCode,
                               OSType subCreatorCode,
                               UInt32 flags,
                               short setListResourceID
                               UInt32 version);
OSStatus ISpConfigure         (ISpEventProcPtr inEventProcPtr);
OSStatus ISpStop              (void);
OSStatus ISpSuspend           (void);
OSStatus ISpResume            (void);
NumVersion ISpGetVersion      (void);
OSStatus ISpElement_NewVirtual(UInt32 dataSize, 
                               ISpElementReference *outElement;
                               UInt32 flags);
OSStatus ISpElement_NewVirtualFromNeeds(UInt32 count, 
                               ISpNeed *needs,
                               ISpElementReference *outElements
                               UInt32 flags);
OSStatus ISpElement_DisposeVirtual(UInt32 count, 
                               ISpElementReference
                               *inElements);
OSStatus ISpDevices_Extract   (UInt32 inBufferCount, 
                               UInt32 *outCount,
                               ISpDeviceReference *buffer);
OSStatus ISpDevices_ExtractByClass(ISpDeviceClass theClass, 
                               UInt32 inBufferCount, 
                               UInt32 *outCount, 
                               ISpDeviceReference *buffer);
OSStatus ISpDevices_ExtractByIdentifier(ISpDeviceIdentifier theIdentifier,
                               UInt32 inBufferCount, 
                               UInt32 *outCount, 
                               ISpDeviceReference *buffer);
OSStatus ISpDevices_Activate  (UInt32 inDeviceCount, 
                               ISpDeviceReference *inDevicesToActivate);
OSStatus ISpDevices_Deactivate(UInt32 inDeviceCount, 
                               ISpDeviceReference *inDevicesToDeactivate);
OSStatus ISpDevice_IsActive   (ISpDeviceReference inDevice, 
                               Boolean *outIsActive);
OSStatus ISpDevice_GetDefinition(const ISpDeviceReference inDevice, 
                               UInt32 buflen,
                               ISpDeviceDefinition *outStruct);
OSStatus ISpDevice_GetElementList(const ISpDeviceReference inDevice, 
                               ISpElementListReference *outElementList);
OSStatus ISpElement_GetDevice (const ISpElementReference inElement, 
                               ISpDeviceReference *outDevice);
OSStatus ISpElement_GetGroup  (const ISpElementReference inElement, 
                               UInt32 *outGroup); 
OSStatus ISpElement_GetInfo   (const ISpElementReference inElement, 
                               ISpElementInfoPtr outInfo); 
OSStatus ISpElement_GetConfigurationInfo(const ISpElementReference inElement, 
                               UInt32 buflen, void *configInfo);

Obtaining Data From Elements

OSStatus ISpElement_GetSimpleState(const ISpElementReference inElement, 
                               Uint32 *state); 
OSStatus ISpElement_GetComplexState(const ISpElementReference inElement, 
                               UInt32 buflen, void *state);
OSStatus ISpElement_GetNextEvent(ElemenReference inElement, 
                               UInt32 bufSize, 
                               ISpElementEventPtr event, 
                               Boolean *wasEvent); 
OSStatus ISpElementList_GetNextEvent(ISpElementListReference inElementList, 
                               UInt32 bufSize, 
                               ISpElementEventPtr event, 
                               Boolean *wasEvent); 
OSStatus ISpElement_Flush     (ISpElementReference inElement); 
OSStatus ISpElementList_Flush (ISpElementListReference inElementList);

Managing Element Lists

OSStatus ISpElementList_New   (UInt32 inCount, 
                               ISpElementReference *inElements, 
                               ISpElementListReference *outElementList
                               UInt32 flags); 
OSStatus ISpElementList_Dispose(ISpElementListReference inElementList); 
OSStatus ISpGetGlobalElementList(ISpElementListReference *outElementList); 
OSStatus ISpElementList_AddElements(ISpElementListReference inElementList, 
                               UInt32 refCon,
                               UInt32 count,
                               ISpElementReference *newElements);
OSStatus ISpElementList_RemoveElements(ISpElementListReference inElementList,
                               UInt32 count,
                               ISpElementReference *oldElement);
OSStatus ISpElementList_Extract(ISpElementListReference inElementList, 
                               UInt32 inBufferCount, 
                               UInt32 *outCount, 
                               ISpElementReference *buffer); 
OSStatus ISpElementList_ExtractByKind(ISpElementListReference inElementList,
                               ISpElementKind theKind, 
                               UInt32 inBufferCount, 
                               UInt32 *outCount, 
                               ISpElementReference *buffer);
OSStatus ISpElementList_ExtractByLabel(ISpElementListReference inElementList,
                               ISpElementLabel theLabel, 
                               UInt32 inBufferCount, 
                               UInt32 *outCount, 
                               ISpElementReference *buffer);

Result Codes

kISpInternalErr	-30420	Internal error.
kISpSystemListErr	-30421	Operation is not allowed a system-maintained element list.
kISpBufferToSmallErr	-30422	The buffer is too small.
kISpElementInListErr	-30423	The element is already in the element list.
kISpElementNotInListErr	-30424	The element is not in the element list.
kISpSystemInactiveErr	-30425	InputSprocket is currently inactive.
kISpDeviceInactiveErr	-30426	The device is currently inactive.
kISpSystemActiveErr	-30427	Input Sprocket is currently active.
kISpDeviceActiveErr	-30428	The device is currently active.
kISpListBusyErr	-30429	The element list is marked as busy.