3D Sound Information Structure (GameSprockets)

Inside Macintosh: Apple Game Sprockets Guide /

Chapter 1 - SoundSprocket / SoundSprocket Reference

3D Sound Information Structure
You use a 3D sound information structure to get and set the characteristics of the filtering to be applied to a specific sound channel. A 3D sound information structure is defined by the SSpLocalizationData data type.
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;
Field Description

cpuLoad
The current CPU load and sound quality setting for the sound localization filters. The value 0 indicates the greatest CPU load (and hence the best sound quality). The value returned by SndGetInfo for the siSSpCPULoadLimit selector indicates the least CPU load (and hence the worst sound quality).
medium
The medium through which sound is traveling. See "Sound Media" (page 1-25) for a description of constants that specify the available sound media. In version 1.0 of SoundSprocket, this field is ignored and the medium is always assumed to be dry (zero humidity) air.
humidity
The relative humidity of the atmosphere. The value of this field should be a floating-point value between 0.0 (indicating dry air) and 100.0 (indicating dense fog). This field is used only if the value of the medium field is kSSpMedium_Air. In version 1.0 of SoundSprocket, this field is ignored.
roomSize
The distance, in meters, between the reverberant walls. For no reverberation, set this field to 0.0.
roomReflectivity
The amount of attenuation, in decibels (dB), that occurs each time a sound bounces off a reverberant wall. The value of this field should be less than 0.0. This field is ignored if the value in the roomSize field is 0.
reverbAttenuation
The amount of reverberant signal, in decibels (dB), to mix into the output sound. This field is ignored if the value in the roomSize field is 0.
sourceMode
The type of filtering to be applied to the source sound. See "Source Modes" (page 1-26) for a description of constants that specify the available source filtering modes.
referenceDistance
The distance, in meters, from the listener to the point at which the sound was recorded. This field is used when the sourceMode field has the value kSSpSourceMode_Localized or kSSpSourceMode_Ambient. The value of this field must be greater than 0.0.
coneAngleCos
The cosine of half of the angle at the apex of the angular attenuation cone. This field is used when the sourceMode field has the value kSSpSourceMode_Localized or kSSpSourceMode_Ambient.
coneAttenuation
The amount of attenuation, in decibels (dB), that occurs outside the angular attenuation cone. This field is used when the sourceMode field has the value kSSpSourceMode_Localized or kSSpSourceMode_Ambient.
currentLocation
The current location of the sound source relative to the listener. See (page 1-28) for a description of the SSpLocationData data structure.
reserved0
Reserved for use by Apple Computer, Inc. You should set this field to 0.
reserved1
Reserved for use by Apple Computer, Inc. You should set this field to 0.
reserved2
Reserved for use by Apple Computer, Inc. You should set this field to 0.
reserved3
Reserved for use by Apple Computer, Inc. You should set this field to 0.
virtualSourceCount
The number of virtual sound sources contained in the array specified by the SSpVirtualSourceData parameter. This field is used when the sourceMode field has the value kSSpSourceMode_Localized or kSSpSourceMode_Ambient. In SoundSprocket version 1.0, this field is ignored.
virtualSource
An array containing up to four virtual source structures describing the virtual sound sources (that is, the reflections) associated with the sound channel. See (page 1-30) for a description of the virtual source structure. This field is used only if the sourceMode field has the value kSSpSourceMode_Localized. In SoundSprocket version 1.0, this field is ignored.