The fields in csSound specify the sound source to play by specifying a csAudioClip object. csSound can optionally specify the location, the direction of the sound, and the spatial characteristics of the sound.

void                setSource(csAudioClip* audioClip);
void                setSpatialize(csBool spatialize);

void                setControl(ControlEnum control);

void                setLocation(const csVec3f& location);
void                setLocation(csFloat v0, csFloat v1, csFloat v2);
void                setDirection(const csVec3f& direction);
void                setDirection(csFloat v0, csFloat v1, csFloat v2);

void                setIntensity(csFloat intensity);
void                setMaxIntensity(csFloat maxIntensity);
void                setCullIntensity(csFloat cullIntensity);

void                setCurrentFrame(csFloat currentFrame);
void                setPriority(csFloat priority);

void                setMinFront(csFloat minFront);
void                setMaxFront(csFloat maxFront);
void                setMinBack(csFloat minBack);
void                setMaxBack(csFloat maxBack);
const csIntArray&   getEvents();

The following sections describe these fields.

To specify how to play a sound file, pass a csAudioClips object to setSource(). The csAudioClips object identifies a csAudioSample object, which contains the sound file to play. For more information about csAudioClips, see “How to Play a Sound File”.

A sound file commonly contains more than one sound sample. Some samples may contain more than one sound channel per sound interval to create, for example, stereo.

To choose a starting location in a sound file, pass the starting frame to the setCurrentFrame() field. A frame is equal to (1/SampleRate) of a second. The sample rate might be, for example, 44KHz, or 44,000 Hz. If, for example, you pass 44000.0 into the setCurrentFrame() field, the sound would begin playing one second (44000 × 1/44000 = 1) into the sound file.

The setControl() field provides an intuitive interface for playing the sound sample in sound files. You pass into setControl() any of the ControlEnum values, including PLAY, PAUSE, REWIND, FASTFORWARD, and STOP.

To enable all of the other effects implemented by the fields in the csSound node, covered in the next section, pass a non NULL value to setSpatialize(). If you pass a NULL value to the field, the volume is a constant value throughout the scene. This choice is appropriate, for example, for background music.

To locate the sound source in a scene, pass its coordinates to the setLocation() field.

Cosmo 3D gives you a great deal of control over how sound propagates from the source. When you supply a vector describing the direction of the sound, the sound propagates in all directions, but attenuates least in specified direction. The attenuation of the sound over distance is characterized by an ellipse, as shown in Figure 15-2.

Figure 15-2. Sound Direction

In this figure, (1.0, 1.0, 0.0) is passed as the direction vector to setDirection(). The ellipse tips, accordingly, at a 45 degree angle.

---

Note: A transformation node can reorient the sound's location and direction.

---

Cosmo 3D provides the following limiting tools to fashion the attenuation of the sound over the ellipse:

The setIntensity() field specifies the volume of the sound at its source. The setMaxIntensity() field specifies the maximum volume of a sound. If a maximum intensity is set, as is the case in Figure 15-2, the intensity of the sound within the maximum intensity perimeter does not attenuate and is equal to the volume specified by setIntensity(). The maxFront() field specifies the maximum intensity perimeter within which the listener hears the maximum volume of the sound.

Outside of the maximum intensity perimeter, the intensity of the sound attenuates over distance until it reaches the minimum intensity perimeter. Beyond the minimum intensity perimeter, the volume of the sound source is constant, defined by the setCullIntensity() field.

Reverse Direction Sound

Cosmo 3D also provides a complimentary set of fields that allow you to define the propagation and attenuation of the same sound in the opposite direction, as shown in Figure 15-3.

Figure 15-3. Forward and Reverse Sound Propagation

The minimum and maximum intensities in the reverse direction are the same as those in the forward direction. The minimum and maximum intensity perimeters, however, are specified separately with the minBack(), and maxBack() fields.

csAudioSample::samples() returns the multivalued array field that contains the actual audio samples. This handle allows you to directly manipulate the array field. For example, to set a sound value, use the following code:

samples->set(index, value);

To set the number of samples and then edit the array directly, use the following code:

samples->setCount(16*44400);
char *samps = samples->edit();
for(i=0;i<16*44400);i++)
    samps[i]=DETERMINE_SAMPLE(i);
samples->editDone();

Example 15-2 sets all of the fields in a csAudioSamples node.

// create an audio sample node
csAudioSamples* horn = new csAudioSamples;

// attach the audio sample node to a specific file
horn->setFileName(“truck_horn.xxx”);

// Set the parameters for the source sound file
horn->setNumFrames(44000.0);
horn->setSampleRate(44000.0);
horn->setSampleSize(2000);
horn->setSampleType(UNSIGNED_INT_SAMPLE_TYPE);
horn->setNumChannels(2);
horn->setSampleScale(1.0);
...

// Load the sound sample by setting the audiosample filename
horn->load();

// Make sure the sound loaded successfully
if (horn->getLoadStatus() == LOAD_FAILED)
    abort();

When load() is called, Cosmo 3D reads the samples in the file into the sample field directly.

csSoundPlayer methods provide sophisticated control over the sound source and the “microphone” recording the sound. Some of those controls include: