Previous Book Contents Book Index Next

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-50Parameter type error or out of range error
memFullErr-108Unable to allocate memory required for task
kSSpInternalErr-30340Corrupted SoundSprocket or other error
kSSpVersionErr-30341Sound Manager 3.2.1 or later not installed
kSSpCantInstallErr-30342Filter installation failure
kSSpParallelUpVectorErr-30343Orientation and up vector are parallel
kSSpScaleToZeroErr-30344Transformation 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

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996