Inside Macintosh: Apple Game Sprockets Guide /

Chapter 1 - SoundSprocket / SoundSprocket Reference

Data Structures

Source Location Structure

You specify the position of a sound source relative to the listener using a source location structure. (For example, the currentLocation field of a 3D sound information structure is a source location structure.) A source location structure is defined by the SSpLocationData data type.

Note

You use a source location structure to specify the position of both real and virtual sound sources. See Figure 1-5 (page 1-11) for an illustration showing how to interpret the elevation and azimuth fields.

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

Field Description

elevation

The angle, in radians, from the orientation vector of the listener to the meridian of longitude on which the sound source lies. The value of this field must lie between -p and p, inclusive, where 0 indicates the meridian of longitude that intersects the listener's orientation vector. Positive values are up, and negative values are down.

azimuth

The angle, in radians, from the orientation vector of the listener to the parallel of latitude on which the sound source lies. The value of this field must lie between -p/2 and p/2, inclusive, where 0 indicates the parallel of latitude that intersects the listener's orientation vector. Positive values are right, and negative values are left.

distance

The distance, in meters, between the listener and the sound source. The value in this field should be greater than 0.0; if the value reaches 0.0, the source mode (specified by the sourceMode field of the SSpLocalizationData structure) should be set to kSSpSourceMode_Ambient.

projectionAngle

The cosine of the angle between the sound source's attenuation cone axis and the vector from the source to the listener. When the attenuation cone points directly at the listener, the value in this field should be 1.0 (because cos(0) = 1.0).

sourceVelocity

The velocity, in meters per second, of the source along the vector from the listener to the source. The value in this field is positive when the source is moving toward the listener.

listenerVelocity

The velocity, in meters per second, of the listener along the vector from the listener to the source. The value in this field is positive when the listener is moving toward the source.