Inside Macintosh: Apple Game Sprockets Guide /

Chapter 1 - SoundSprocket

Summary of SoundSprocket

Constants

Component Types and Subtypes

enum {
   kSoundEffectsType                   = 'snfx'
};
enum {
   kReverbSubType                      = 'revb',
   kSSpLocalizationSubType             = 'snd3'
};

Sound Channel Information Selectors

enum {
   siPreMixerSoundComponent            = 'prmx',
   siSSpCPULoadLimit                   = '3dll',
   siSSpSetup                          = '3dst',
   siSSpLocalization                   = '3dif',
   siSSpFilterVersion                  = '3dfv'
};

Speaker Types

enum {
   kSSpSpeakerKind_Stereo              = 0,
   kSSpSpeakerKind_Mono                = 1,
   kSSpSpeakerKind_Headphones          = 2
};

Sound Media

enum {
   kSSpMedium_Air                      = 0,
   kSSpMedium_Water                    = 1
};

Source Modes

enum {
   kSSpSourceMode_Unfiltered           = 0,
   kSSpSourceMode_Localized            = 1,
   kSSpSourceMode_Ambient              = 2,
   kSSpSourceMode_Binaural             = 3
};

Data Types

typedef struct SSpSourcePrivate        *SSpSourceReference;
typedef struct SSpListenerPrivate      *SSpListenerReference;

Filter Version Structure

typedef struct SSpFilterVersionData {
   OSType                     manufacturer;
   NumVersion                 version;
   UInt32                     reserved;
} SSpFilterVersionData;

Sound Component Link Structure

struct SoundComponentLink {
   ComponentDescription       description;
   SoundSource                mixerID;
   SoundSource *              linkID;
};
typedef struct SoundComponentLink SoundComponentLink;
typedef SoundComponentLink *SoundComponentLinkPtr;

3D Sound Setup Structure

typedef struct SSpSetupData {
   UInt32                     speakerKind;
   float                      speakerAngle;
   UInt32                     reserved0;
   UInt32                     reserved1;
} SSpSetupData;

Source Location Structure

typedef struct SSpLocationData {
   float                      elevation;
   float                      azimuth;
   float                      distance;
   float                      projectionAngle;
   float                      sourceVelocity;
   float                      listenerVelocity
} SSpLocationData;

Virtual Source Structure

typedef struct SSpVirtualSourceData {
   float                      attenuation;
   SSpLocationData            location;
} SSpVirtualSourceData;

3D Sound Information Structure

typedef struct SSpLocalizationData {
   UInt32                     cpuLoad;
   UInt32                     medium;
   float                      humidity;
   float                      roomSize;
   float                      roomReflectivity;
   float                      reverbAttenuation;
   UInt32                     sourceMode;
   float                      referenceDistance;
   float                      coneAngleCos;
   float                      coneAttenuation;
   SSpLocationData            currentLocation;
   UInt32                     reserved0;
   UInt32                     reserved1;
   UInt32                     reserved2;
   UInt32                     reserved3;
   UInt32                     virtualSourceCount;
   SSpVirtualSourceData       virtualSource[4];
} SSpLocalizationData;
typedef Boolean (*SSpEventProcPtr) (EventRecord* InEvent);

SoundSprocket Functions

Controlling Sound Output Devices

OSStatus SSpConfigureSetup(SSpEventProcPtr inEventProcPtr);

Creating and Managing Listeners

OSStatus SSpListener_New(SSpListenerReference *outListenerReference);
OSStatus SSpListener_Dispose(SSpListenerReference inListenerReference);
OSStatus SSpListener_GetTransform(SSpListenerReference inListenerReference, 
TQ3Matrix4x4 *outTransform);
OSStatus SSpListener_SetTransform(SSpListenerReference inListenerReference, 
const TQ3Matrix4x4 *inTransform);
OSStatus SSpListener_GetPosition(SSpListenerReference inListenerReference, 
TQ3Point3D *outPosition);
OSStatus SSpListener_SetPosition(SSpListenerReference inListenerReference, 
const TQ3Point3D *inPosition);
OSStatus SSpListener_GetOrientation (
SSpListenerReference inListenerReference, 
TQ3Vector3D *outOrientation);
OSStatus SSpListener_SetOrientation (
SSpListenerReference inListenerReference, 
const TQ3Vector3D *inOrientation);
OSStatus SSpListener_GetUpVector(SSpListenerReference inListenerReference, 
TQ3Vector3D *outUpVector);
OSStatus SSpListener_SetUpVector(SSpListenerReference inListenerReference, 
const TQ3Vector3D *inUpVector);
OSStatus SSpListener_GetCameraPlacement (
SSpListenerReference inListenerReference, 
TQ3CameraPlacement *outCameraPlacement);
OSStatus SSpListener_SetCameraPlacement (
SSpListenerReference inListenerReference, 
const TQ3CameraPlacement *inCameraPlacement);
OSStatus SSpListener_GetVelocity(SSpListenerReference inListenerReference, 
TQ3Vector3D *outVelocity);
OSStatus SSpListener_SetVelocity(SSpListenerReference inListenerReference, 
const TQ3Vector3D *inVelocity);
OSStatus SSpListener_GetActualVelocity (
SSpListenerReference inListenerReference, 
TQ3Vector3D *outVelocity);
OSStatus SSpListener_GetMedium(SSpListenerReference inListenerReference, 
UInt32 *outMedium, 
float *outHumidity);
OSStatus SSpListener_SetMedium(SSpListenerReference inListenerReference, 
UInt32 inMedium, 
float inHumidity);
OSStatus SSpListener_GetReverb(SSpListenerReference inListenerReference, 
float *outRoomSize, 
float *outRoomReflectivity, 
float *outReverbAttenuation);
OSStatus SSpListener_SetReverb(SSpListenerReference inListenerReference, 
float inRoomSize, 
float inRoomReflectivity, 
float inReverbAttenuation);
OSStatus SSpListener_GetMetersPerUnit (
SSpListenerReference inListenerReference, 
float *outMetersPerUnit);
OSStatus SSpListener_SetMetersPerUnit (
SSpListenerReference inListenerReference, 
float inMetersPerUnit);

Creating and Managing 3D Sound Sources

OSStatus SSpSource_New(SSpSourceReference *outSourceReference);
OSStatus SSpSource_Dispose(SSpSourceReference inSourceReference);
OSStatus SSpSource_CalcLocalization (
SSpSourceReference inSourceReference, 
SSpListenerReference inListenerReference, 
SSpLocalizationData *outLocalization);
OSStatus SSpSource_GetTransform(SSpSourceReference inSourceReference, 
TQ3Matrix4x4 *outTransform);
OSStatus SSpSource_SetTransform(SSpSourceReference inSourceReference, 
const TQ3Matrix4x4 *inTransform);
OSStatus SSpSource_GetPosition(SSpSourceReference inSourceReference, 
TQ3Point3D *outPosition);
OSStatus SSpSource_SetPosition(SSpSourceReference inSourceReference, 
const TQ3Point3D *inPosition);
OSStatus SSpSource_GetOrientation(SSpSourceReference inSourceReference, 
TQ3Vector3D *outOrientation);
OSStatus SSpSource_SetOrientation(SSpSourceReference inSourceReference, 
const TQ3Vector3D *inOrientation);
OSStatus SSpSource_GetUpVector(SSpSourceReference inSourceReference, 
TQ3Vector3D *outUpVector);
OSStatus SSpSource_SetUpVector(SSpSourceReference inSourceReference, 
const TQ3Vector3D *inUpVector);
OSStatus SSpSource_GetCameraPlacement (
SSpSourceReference inSourceReference, 
TQ3CameraPlacement *outCameraPlacement);
OSStatus SSpSource_SetCameraPlacement (
SSpSourceReference inSourceReference, 
const TQ3CameraPlacement *inCameraPlacement);
OSStatus SSpSource_GetVelocity(SSpSourceReference inSourceReference, 
TQ3Vector3D *outVelocity);
OSStatus SSpSource_SetVelocity(SSpSourceReference inSourceReference, 
const TQ3Vector3D *inVelocity);
OSStatus SSpSource_GetActualVelocity (
SSpSourceReference inSourceReference, 
TQ3Vector3D *outVelocity);
OSStatus SSpGetCPULoadLimit(UInt32 *outCPULoadLimit);
OSStatus SSpSource_GetCPULoad(SSpSourceReference inSourceReference, 
UInt32 *outCPULoad);
OSStatus SSpSource_SetCPULoad(SSpSourceReference inSourceReference, 
UInt32 inCPULoad);
OSStatus SSpSource_GetMode(SSpSourceReference inSourceReference, 
UInt32 *outMode);
OSStatus SSpSource_SetMode(SSpSourceReference inSourceReference,
UInt32 inMode);
OSStatus SSpSource_GetReferenceDistance (
SSpSourceReference inSourceReference, 
float *outReferenceDistance);
OSStatus SSpSource_SetReferenceDistance (
SSpSourceReference inSourceReference, 
float inReferenceDistance);
OSStatus SSpSource_GetSize(SSpSourceReference inSourceReference, 
float *outLength, 
float *outWidth, 
float *outHeight);
OSStatus SSpSource_SetSize(SSpSourceReference inSourceReference, 
float inLength, 
float inWidth, 
float inHeight);
OSStatus SSpSource_GetAngularAttenuation (
SSpSourceReference inSourceReference, 
float *outConeAngle, 
float *outConeAttenuation);
OSStatus SSpSource_SetAngularAttenuation (
SSpSourceReference inSourceReference, 
float inConeAngle, 
float inConeAttenuation);

Sound Manager Functions

Getting and Setting Sound Channel Information

pascal OSStatus SndGetInfo(SndChannelPtr chan, OSType selector, void *infoPtr);
pascal OSStatus SndSetInfo(SndChannelPtr chan, OSType selector, void *infoPtr);

Result Codes

paramErr	-50	Parameter type error or out of range error
memFullErr	-108	Unable to allocate memory required for task
kSSpInternalErr	-30340	Corrupted SoundSprocket or other error
kSSpVersionErr	-30341	Sound Manager 3.2.1 or later not installed
kSSpCantInstallErr	-30342	Filter installation failure
kSSpParallelUpVectorErr	-30343	Orientation and up vector are parallel
kSSpScaleToZeroErr	-30344	Transformation matrix has a vector of 0

---

Subtopics

Constants

Component Types and Subtypes

Sound Channel Information Selectors

Speaker Types

Sound Media

Source Modes

Data Types

Filter Version Structure

Sound Component Link Structure

3D Sound Setup Structure

Source Location Structure

Virtual Source Structure

3D Sound Information Structure

SoundSprocket Functions

Controlling Sound Output Devices

Creating and Managing Listeners

Creating and Managing 3D Sound Sources

Sound Manager Functions

Getting and Setting Sound Channel Information

Result Codes