We will start by creating a new class to encapsulate the listener. We currently have a EWSoundSourceObject to encapsulate source objects. Let's create a new class called EWSoundListenerObject to complement it.

Do you remember that we made EWSoundSourceObject a subclass of EWSoundState? The reason is now revealed. There are some properties, such as gain level, that are common between sources and listeners. Why not share those commonalities by sharing a common parent class? So we will also make our EWSoundListenerObject a subclass of EWSoundState.

You might be thinking that we should do something extra because multiple sources are allowed, but there is only one listener per context. For simplicity, we are not going to worry about this issue. We will know to create only one instance of the listener in Space Rocks!^[24]

We will continue extending our code using the project SpaceRocksSoundResourceManager2 from the end of the previous chapter as our starting position. The completed project for this next part of the example for implementing the listener is named SpaceRocksOpenAL3D_0_Listener.

Let's create the class. In EWSoundListenerObject.h, make EWSoundListenerObject a subclass of EWSoundState:

@interface EWSoundListenerObject : EWSoundState
{
}

@end

As with our EWSoundSourceObject from the previous chapter, we will expect to have two methods defined: update and applyState. The update method just calls applyState. This is also a good time to remind you that our EWSoundState parent class has the property gainLevel, which we implemented in EWSoundSourceObject. The OpenAL listener also supports the gain property (which is why we put it in the parent class), so let's take this opportunity to implement it in EWSoundListenerObject.m. The code is an almost identical mirror of EWSoundSourceObject. The only difference is that we need to use the AL_GAIN parameter, rather than alSourcef, to set the gain level on the listener.

- (void) applyState
{
    [super applyState];
    if([[OpenALSoundController sharedSoundController] inInterruption])
    {
        return;
    }
    alListenerf(AL_GAIN, gainLevel);
}

- (void) update
{
    [super update];
    [self applyState];
}

And that's all we need for the basic infrastructure for the listener. But first, we want to integrate the use of our new listener class.

We now come to a design decision point in our game. Who or what is going to be our listener in the game? Perhaps a clearer and more pointed version of this question is this: Where in the game world is our listener going to be located?

I think the most natural thing to do is to make our spaceship the listener, as in Figure 11-1. That means we put our "head and ears" where the spaceship is in the game. Thus, when the spaceship moves or turns, we move the listener with it. But we could make other choices. We could decide the listener is always in the dead center of the screen and never moves. This might actually seem very natural to the player. Or we could get creative and put the listener on the UFO or an asteroid. We could even make the listener a game selectable option, so it can be moved around. However, for this example, we will make the spaceship the listener, as it is easiest to conceptualize.

Now that we have chosen our designated listener, we need to integrate the code. If you recall, we gave every BBSceneObject an instance of EWSoundSourceObject. Well, let's follow that analogy and also add a EWSoundListenerObject to the BBSpaceShip class.

First, we add the new instance variable/property to the class in BBSpaceShip.h. Then we make sure to allocate a new instance of it at the end of BBSpaceShip.m's awake method.

soundListenerObject = [[EWSoundListenerObject alloc] init];

Don't forget to release it in the dealloc method.

[soundListenerObject release];

Finally, add the following line to the end of BBSpaceShip.m's update method. This will make sure the changes are applied at during every update loop.

[self.soundListenerObject update];

That's all there is to it. We have integrated the listener into Space Rocks!.

You may be wondering what the gain level does for the listener. You might think of it as the master volume control for OpenAL. By default, the listener gain is set to 1.0. If you changed it to 0.5, everything you hear will have its volumes cut by half. If you set it to 0.0, you will hear nothing. If you would like to experiment, try adding something like the following line right after you allocate the soundListenerObject at the end of the awake method:

soundListenerObject.gainLevel = 0.5;

We will not utilize our gainLevel property in Space Rocks!. For an example of the listener gain used as a master volume control, see the BasicOpenALStreaming example in the next chapter.

There is one more thing we need to do, which is simple, but a little tedious. We currently have a corner-case bug where our source and listener classes do not have the correct position value on the initial creation. Right now, our code depends on the update loop to synchronize our sound objects with the actual values from the BBSceneObject. So it is possible for an object to start playing sound in the wrong position, and it won't be corrected until the update loop is reached.

The easiest place to fix this is in the awake method. And the best place to do this is in the BBSceneObject's awake method so all the subclasses inherit the behavior. But there is a slight problem with that because not all the BBSceneObject subclasses call [super awake]. So, we need to refactor and fix all the code in the project to call [super awake] and implement BBSceneObject's awake method to be as follows:

-(void)awake
{
    soundSourceObject.objectPosition = translation;
}

Finally, we need to handle the same corner case for the listener, so at the end of the BBSpaceShip's awake method, directly after we allocate the new object, we need to copy the position:

soundListenerObject          = [[EWSoundListenerObject alloc] init];
soundListenerObject.objectPosition = translation;

You now have enough code to actually try it. If you do, you might hear positional audio (provided you have headphones or external speakers). Wait for the UFO to come in. The engine noise should pan from your left speaker to the right speaker as it moves across the screen (see Figure 11-2).

But more likely, you will have a very hard time hearing the UFO. At best, the noise is generally really quiet when it first comes in, then gets louder as the UFO moves to the center, and then gets quiets as it moves away. This is because OpenAL has its distance attenuation feature enabled by default. Because we won't talk about distance attenuation until later in the chapter, let's just disable this feature for now.

OpenAL provides a simple function to change the distance attenuation model, called alDistanceModel(ALenum distance_model). The distance attenuation models are covered in detail later in this chapter. For the curious, the default model is AL_INVERSE_DISTANCE_CLAMPED. To disable it, we just need to set the value to AL_NONE:

alDistanceModel(AL_NONE);

Let's create a setter and getter in our OpenALSoundController class:

- (void) setDistanceModel:(ALenum)distance_model
{
    alDistanceModel(distance_model);
}

- (ALenum) distanceModel
{
    ALint distance_model;
    distance_model = alGetInteger(AL_DISTANCE_MODEL);
    return (ALenum)distance_model;
}

Notice that there is no direct function to query the distance model. Instead, we use the generic alGet* functions to retrieve the value.

And let's make BBSceneController the controller of the distance model. In BBSceneController's init method, we invoke our newly implemented setDistanceModel to turn off distance attenuation:

- (id) init
{
    self = [super init];
    if(nil != self)
    {
        [[OpenALSoundController sharedSoundController] setSoundCallbackDelegate:self];
        [self invokeLoadResources];
        [[OpenALSoundController sharedSoundController] setDistanceModel:AL_NONE];
    }
    return self;
}

That's all you need if you have a properly working implementation of OpenAL.

ALfloat rolloffFactor;

@property(nonatomic, assign) ALfloat rolloffFactor;

rolloffFactor = 0.0; // 0.0 disables attenuation

alSourcef(sourceID, AL_ROLLOFF_FACTOR, rolloffFactor);

First, let's focus on determining the up vector. OpenGL and OpenAL use a right-handed coordinate system. In layman's terms, all this means is which way the z axis points if you have an x axis and a y axis. If you take your right hand, extend your thumb and index finger so it looks like a cocked gun, and then extend your middle finger so it is perpendicular to both your index finger and thumb, these fingers represent the axes you see in a right-handed coordinate system (see Figure 11-3). This is the right-hand rule.

Figure 11.3. The right-hand rule using three fingers to represent the x, y, and z axes. Picture by Abdull from Wikimedia Commons under the Creative Commons Attribution ShareAlike 3.0 License (http://commons.wikimedia.org/wiki/File:Rechte-hand-regel.jpg)

Once you have your fingers in the correct position, the trick is to orient your hand so the axes line up with what you are trying to compare against. In Space Rocks!, if we spend a little time looking at the position values for all the objects, we see that x increases toward the right of the screen, and y increases toward the top of the screen. I like to point my middle finger to the right (x axis) and my thumb up (y axis), so that my index finger is pointing toward me. My index finger is pointing in the direction of the up vector, which is coming through the screen toward my body. Even though my hand is contorted, I like this convention because the common base case is to have the game-space axes match the computer-screen axes, where the x axis goes to the right and the y axis to goes up. This results in a gun-pointing-at-myself (shooting myself) position, which is something I could always easily remember for some strange reason.

If you got all that, then you can just move on to the next segment. But if you need more clarification, there is a variation of the right-hand rule for rotation called the right-hand grip rule that can be used as a substitute. Extend your palm with your thumb pointed up, as if to shake someone's hand, and then curl your fingers (see Figure 11-4). Your curled fingers point to the rotation direction. Your thumb is the vector.

Figure 11.4. The right-hand grip rule. Curl your fingers around the axis of rotation, and the thumb points in the direction of the up vector. This is often used in physics to find the direction of electric current (I) in a magnetic field (B), but we can also use it for audio purposes. Image from Wikimedia Commons under Public Domain (http://commons.wikimedia.org/wiki/File:Right_hand_rule.png)

In physics, this would be used for torque and force, or magnetic fields and electric currents. In OpenGL, we often use it to figure out which way the normal vectors point when drawing a triangle. For OpenAL, we can also use it to find our up vector.

If we look at how we rotate the ship in the code, we find that the rotation.z instance variable in BBSceneObject contains an angle in degrees. The value increases as we turn counterclockwise in the game. Match your curled fingers to your screen so they go counterclockwise with the ship, and you'll see that your thumb points at you.

So we have systematically determined that our z axis points toward us when looking at the iPhone/iPod touch screen. Since we see the top of our spaceship (instead of the bottom), we know our ship's up orientation is aligned with the z axis. Since we also know our ship moves only in the x-y plane (because we have a 2D game), we can conclude that our listener's up vector needs to be <0.0, 0.0, 1.0>.

This section's title may sound scary, especially if you hated high school math. But my intention is not to do a math lesson, but determine how to compute our listener's at vector. So I am going to zoom through this section and focus on just getting what we need.

Our problem is that we need to map our spaceship's BBSceneObject rotation.z value to the OpenAL listener coordinate system. Even though we know we are in a right-handed coordinate system, we have two obstacles:

Let's start with the first problem.

First, I'm going to ask you to remember the unit circle, which is a way of converting angles to x and y coordinates (see Figure 11-5). This is exactly what we need to convert our rotation angle to a vector.

Figure 11.5. Unit circle with angles. By Gustavb from Wikimedia Commons under the Creative Commons License (http://commons.wikimedia.org/wiki/File:Unit_circle_angles.svg)

The unit circle can be more generally expressed in terms of cosine and sine of an angle (see Figure 11-6).

Figure 11.6. Unit circle with cosine and sine. By Gustavb from Wikimedia Commons under the Creative Commons Attribution ShareAlike 3.0 License (http://commons.wikimedia.org/wiki/File:Unit_circle.svg)

This leads us directly into polar-to-rectangular coordinate conversions. You can convert the angles to x and y values by these simple formulas:

Radius (r) is always 1 in the unit circle. Since we just need a direction vector, we are free to set r=1 to drop r out of the equation.

There, that wasn't so painful, right?

So all we need to do is drop in our angle (don't forget to convert from degrees to radians if you are using C math library functions), and we have our vector—well, almost. The second problem still needs to be solved.

The other problem is that our spaceship's starting orientation is different from the unit circle. Notice that when we start our game, for angle = 0, the ship is pointing toward the top of the screen (along the y axis). But the unit circle for angle = 0 points along the x axis (refer to Figure 11-6).

This means our spaceship is turned, or phase-shifted, by 90 degrees compared to the unit circle. So if we just plug into the above equations, our results will be wrong.

If you look at the x and y values around the unit circle in Figure 11-6, you'll notice that their magnitudes repeat around the circle, and it is only the positive and negative signs that change. I point this out to also remind you that cosine and sine are periodic (repeating) functions. (You can think of waveforms, too.) In fact, you can express sine in terms of cosine or vice versa, because they are essentially the same function, just shifted (based on the angle parameter).

This means that we can just look up a table of trigonometric identities (or derive it, if you really want to) to figure out what it means to phase-shift cosine and sine by 90 degrees to handle the fact that our spaceship starting orientation points along the y axis. This reveals the following useful identities:

Substituting the identities into our original polar-to-rectangular conversion formulas, our equations change to the following:

You can now breathe a big sigh of relief. Despite all those fancy math terms, we are left with two simple equations that we can drop directly into our source code.

Now we finally get to code. We are going to make the listener orientation match the spaceship orientation. So when the spaceship turns, the listener orientation will turn with it. For demonstration purposes, we will implement this, but you will need to decide whether it makes sense for your own game.

We will continue from the SpaceRocksOpenAL3D_1_Position project. The completed project for this example is named SpaceRocksOpenAL3D_2_Orientation.

In EWSoundListenerObject, we will add two BBPoint instance variables to represent our at and up vectors. OpenAL actually wants a six-element array, but I prefer to use two BBPoint values for our class.

Create an init method in EWSoundListenerObject.m so we can initialize the vectors with legal default values:

- (id) init
{
    self = [super init];
    if(nil != self)
    {
        atOrientation = BBPointMake(0.0f, 1.0f, 0.0f); // looking along Y
        upOrientation = BBPointMake(0.0f, 0.0f, 1.0f); // Z is up
    }
    return self;
}

Note that the up vector will never change, since we are in a 2D game and the up direction for the ship never changes.

In the applyState method, we set the value in OpenAL. Place it directly after the line where we set the AL_POSITION:

ALfloat orientation_array[6] = {
    atOrientation.x, atOrientation.y, atOrientation.z,
    upOrientation.x, upOrientation.y, upOrientation.z
};
alListenerfv(AL_ORIENTATION, orientation_array);

As I said, OpenAL wants a six-element array to set the listener orientation, so we must stuff our values in an array to hand it off.

Finally, to synchronize our listener value with BBSpaceShip's, in BBSpaceShip.m's awake method, we add the following two lines to the very end of the method utilizing the equations presented in the previous section:

CGFloat radians = rotation.z/BBRADIANS_TO_DEGREES;
self.soundListenerObject.atOrientation = BBPointMake(-sinf(radians), cosf(radians), 0.0);

And in the update method, we can add the following line at the end of the method immediately before we call update on the soundListenerObject. The value of radians was already computed earlier in the same method.

self.soundListenerObject.atOrientation = BBPointMake(-sinf(radians), cosf(radians), 0.0);

Now run the program and try rotating your ship into different positions to see how it affects from which speaker sound emits. For fun, try re-creating the scenario in Figure 11-3.

Now hold on. Things might get a little tricky here. OpenAL provides not one, but two cones to play with per source: an inner cone and an outer cone. The inner cone is probably what you were thinking of when I first said cones. Any listener within this cone will play at its normal volume level.

In our megaphone example, if you (the listener) are standing directly in front of the person speaking into the megaphone (you are in the inner cone), you will hear the person speaking at his normal volume level. So think of an unpowered, nonamplified, acoustical bullhorn. OpenAL doesn't amplify sound.^[27] Therefore, "full blast" is just normal sound.

The other important point is that OpenAL defines an outer cone. If the listener is outside both the inner and outer cone, the volume will play at a special gain level you can set, called the AL_CONE_OUTER_GAIN.

This leaves the area between the inner cone and the outer cone, which is called the transitional zone. When a listener is inside this zone, the volume is interpolated between the inner cone gain level and the outer cone gain level.

Stare at the illustration in Figure 11-7 to try to make sense of what I just said. You may want to reread the above paragraphs a few times to see how that information matches with the diagram.

Figure 11.7. OpenAL directional cones with their angles and zones labeled

Continuing with our megaphone example, let's say you are standing directly behind the person with the megaphone and define this as part of the outer zone. Let's say the outer cone gain level is 0. This means you can't hear anything the person is saying. But if we say the outer cone gain level is 0.5, this means you hear the person at half volume. (You might conceptualize this as the ambient background sound.)

Finally, let's say you are standing next to the person speaking and define this as part of the transitional zone. The volume you hear will be somewhere between normal (full blast), and the outer cone gain level. So, for simplicity, we might say if the outer cone gain level is 0, and the normal gain is 1, you might hear the volume at 0.5 (though the actual value would be determined by the actual cone sizes you set).

Now that you have an understanding of OpenAL directional cones for sources, we should have an example of how to use them. For demonstration purposes, we will utilize the fact that the UFO spins. We will apply a directional cone to the UFO engine hum. When the inner cone is facing the spaceship, you will hear normal volume. As the inner cone spins away, you will hear the volume level decay. And, of course, it will spin back and the volume will increase again.

Now it's time to implement source direction and cones in Space Rocks! We continue from SpaceRocksOpenAL3D_2_Orientation. The finished project for this example is named SpaceRocksOpenAL3D_3_DirectionCones.

In EWSoundSourceObject.h, we add the following instance variables:

BBPoint atDirection;
ALfloat coneInnerAngle;
ALfloat coneOuterAngle;
ALfloat coneOuterGain;

Also declare properties for these so we can access them outside the class later. Don't forget to synthesize them in the implementation.

@property(nonatomic, assign) ALfloat coneInnerAngle;
@property(nonatomic, assign) ALfloat coneOuterAngle;
@property(nonatomic, assign) ALfloat coneOuterGain;

In EWSoundSourceObject.m's init method, let's set the values to the same values that OpenAL uses as the default. Note that if you want direction disabled, you set the vector to <0, 0, 0>. If you don't want either of the cones, you set the angle to 360.0, which means the sound goes in all directions. By default, OpenAL sets the outer cone gain to 0, so we will do the same.

- (id) init
{
    self = [super init];
    if(nil != self)
    {
        audioLooping = AL_FALSE;
        pitchShift = 1.0f;
        rolloffFactor = 0.0; // 0.0 disables attenuation
        atDirection = BBPointMake(0.0, 0.0, 0.0);
        coneInnerAngle = 360.0;
        coneOuterAngle = 360.0;
        coneOuterGain = 0.0;
    }
    return self;
}

And in EWSoundSourceObject.m's applyState method, we set the source properties.

alSource3f(sourceID, AL_DIRECTION, atDirection.x, atDirection.y, atDirection.z);
alSourcef(sourceID, AL_CONE_INNER_ANGLE, coneInnerAngle);
alSourcef(sourceID, AL_CONE_OUTER_ANGLE, coneOuterAngle);
alSourcef(sourceID, AL_CONE_OUTER_GAIN, coneOuterGain);

We need to remember to keep the soundSourceObject's direction in sync with the BBSceneObject's rotation.z value. So we add the following two lines to BBSceneObject.m's awake and update methods, directly after where we synchronized the object positions:

CGFloat angle_in_radians = rotation.z/BBRADIANS_TO_DEGREES;
soundSourceObject.atDirection = BBPointMake(-sinf(angle_in_radians), cosf(angle_in_radians), 0.0);

Now let's actually use a directional cone. In BBUFO.m, we'll set some cone properties. In the awake method, immediately before the playSound: invocation, we can try these values:

self.soundSourceObject.coneInnerAngle = 90.0;
self.soundSourceObject.coneOuterAngle = 270.0;
self.soundSourceObject.coneOuterGain = 0.5;

At this point, try running the program and experience the noise change for yourself. When the UFO inner cone (90 degrees wide) is directed at the spaceship, you hear the loudest sound. When both the cones are directed away from the spaceship, you hear the least gain. If you want something really explicit, you can set the coneOuterGain value to 0, and experience the UFO noise turning off completely when it is facing away from the spaceship.

But now I'm going to advocate leaving the coneOuterGain value at 0.5, and then doing a cheap, but interesting trick.

In BBSceneController.m's addUFO method, let's increase the rotationalSpeed of the UFO dramatically:

ufo.rotationalSpeed = BBPointMake(0.0, 0.0, 1000.0);

Now when you run the program, you will hear a pronounced oscillation in the sound effect because the UFO is spinning so fast. I think this is a neat little effect that goes well with our UFO, so I'm going to leave the fast spin rate set for the rest of the examples.

To use the Doppler effect in OpenAL, we need several things. First and foremost, the listener and the sound source need velocities. This brings up a subtle point. We have already been moving the positions of the objects in our game. So, does OpenAL automatically infer the velocities based on the changes in position? The answer is no. OpenAL requires you to explicitly set velocities as a separate property from position. But this is generally a good thing. Otherwise, you would need to work around corner cases such as when an object first materializes into the game, because the initial velocity is undefined. Another corner case to consider is if an object has a teleportation feature where it can instantly change to a new position. In this case, it may not make sense to have a pitch shift in frequency, which might imply extremely fast speed instead of teleportation.

An interesting side effect of setting the velocity properties separately from position is that you aren't obligated to portray realism. For example, perhaps for artistic reasons like a dream sequence or alternate reality, you decide you want to do the opposite of a real Doppler effect. When objects move toward the listener, maybe you decide you want a lower frequency instead of a higher one. Since OpenAL has separate properties for position and velocity, you can easily achieve this.

In addition to requiring velocities, OpenAL also provides two global scaling factors to let you manipulate how strong the Doppler effect is in your program:

So without further ado, the formula OpenAL uses to compute the pitch shift is as follows:

The formula solves for the shifted frequency, which is what you hear play through your speakers.

For you astute, mathematically inclined people out there, I need to clarify what velocity_listener and velocity_source really are, because the equation is slightly inaccurate for the sake of being more aesthetically pleasing. The velocities in this equation are not true vectors. Instead, each velocity is just a scalar (a simple float value). The values are the projection of each velocity projected onto the source-to-listener vector. What does this mean?

Imagine the UFO and the spaceship moving across the screen from left to right, parallel with each other, never getting closer to or farther from one another. No matter how fast they are moving, the pitch due to the Doppler effect will never change, because the Doppler effect happens only when the objects get closer or farther apart. So, we care only about the part of the velocity that travels along an imaginary line that connects the UFO and spaceship, which is the source-to-listener vector. The good news is that OpenAL automatically extracts the projected scalars from regular velocity vectors you provide, so you really don't need to worry about this detail. But the formula as a whole is presented to allow you to understand how changing all the factors impacts the results, because you will most likely be tweaking multiple values.

You may be wondering why you will be tweaking values, when OpenAL provides things that imply precision, such as precise-sounding factors like the speed of sound and unit systems like meters per second. In practice, more often than not, you will be filling these numbers in the equation by trial and error and experimentation, rather than mathematical rigor. Most game worlds are exaggerated and do not perfectly reflect reality. Frequently, distances are shorter and speeds are greater in game worlds to make things more exciting. Usually, this means needing to tweak things until they sound right.

Once again, it is example time. We will continue from the previous project, SpaceRocksOpenAL3D_3_DirectionCones. The finished project for this example is named SpaceRocksOpenAL3D_4_VelocityDoppler.

In EWSoundState.h, add a new instance variable for objectVelocity for the velocity vector:

BBPoint objectVelocity;

Initialize it in EWSoundState.m's init method after objectPosition is initialized:

objectVelocity = BBPointMake(0.0, 0.0, 0.0);

In EWSoundSourceObject.m, apply it OpenAL in applyState after the lines following the directional cones we added in the previous section:

alSource3f(sourceID, AL_VELOCITY, objectVelocity.x, objectVelocity.y, objectVelocity.z);

In EWSoundListenerObject.m, do the same for the listener in applyState after the AL_ORIENTATION line:

alListener3f(AL_VELOCITY, objectVelocity.x, objectVelocity.y, objectVelocity.z);

OK, one minor surprise. The speed property is not in BBSceneObject, but in the subclass BBMobileObject. So, in BBMobileObject.m, synchronize the source velocities with the scene object, in its awake method, which must be created:

- (void) awake
{

[super awake];
    soundSourceObject.objectVelocity = speed;
}

You may be wondering how I know that the speed vector used by the Space Rocks! game engine is going to map directly to OpenAL's notion of velocity without some scaling factor. The truth is that I don't know. But I thought I would try this first, and then tweak the Doppler factor and speed of sound values as appropriate.

In OpenALSoundController.m, we will implement accessors for these two parameters:

- (void) setDopplerFactor:(ALfloat)doppler_factor
{
    alDopplerFactor(doppler_factor);
}

- (ALfloat) dopplerFactor
{
    return alGetFloat(AL_DOPPLER_FACTOR);
}

- (void) setSpeedOfSound:(ALfloat)speed_of_sound
{
    alSpeedOfSound(speed_of_sound);
}

- (ALfloat) speedOfSound
{
        return alGetFloat(AL_SPEED_OF_SOUND);
}

In OpenALSoundController.h, declare the interfaces or properties so they can be used publicly without warnings. No synthesize is necessary, since we explicitly implemented them.

@property(nonatomic, assign) ALfloat dopplerFactor;
@property(nonatomic, assign) ALfloat speedOfSound;

Finally, let's use our accessors in BBSceneController.m's init method after setDistanceModel. To start with, we will set the Doppler factor to 1.0 and the speed of sound to 343.3, which are the OpenAL defaults:

[[OpenALSoundController sharedSoundController] setDopplerFactor:1.0];
[[OpenALSoundController sharedSoundController] setSpeedOfSound:343.3];

As it turns out, I like how all our default values work for this instructional example. I think these values are strong enough that you can easily notice the Doppler effect being applied, but not too strong that everything becomes incomprehensible. But I encourage you to play with these parameters to see how they manipulate the effect.

OpenAL provides six different built-in attenuation models that you can pick from to make distance attenuation seem more realistic or more artistic. The models are inverse, linear, exponential, and clamped versions of the aforementioned three models. (The default is Inverse Distance Clamped.) Clamped versions are the same as the nonclamped versions, except that for distances less than the reference distance, the gain is set (clamped) to 1. In addition, clamped versions also clamp distances to the maximum distance value if the distance exceeds that value.

The formulas and graphs are shown in the following sections. In all formulas, x represents the distance between the source and listener, and x≥0. Also note that OpenAL implementations are free to clamp gain values if the result exceeds hardware capabilities.

Inverse Distance

In the Inverse Distance model (see Figure 11-10), the gain decays quickly and then starts to level off as the distance gets greater. Smaller rolloff factors will reduce how quickly the gain drops. Reference distance shifts the curve to the right so that gain equals 1 at the reference distance. Note that even though the equation and graph allows gains greater than 1, OpenAL is free to clamp the maximum value at 1.

Figure 11.10. Graph of the Inverse Distance model

Inverse Distance Clamped

The Inverse Distance Clamped model (see Figure 11-11) behaves like the nonclamped model, except that gain greater than 1 is explicitly clamped. Also, there is a maximum distance parameter that prevents the gain from decaying any more beyond the designated distance.

Figure 11.11. Graph of the Inverse Distance Clamped model

Linear Distance

The Linear Distance model (see Figure 11-12) makes the gain decay in a linear (straight-line) fashion. The reference distance value shifts the line so that the gain is 1 at the reference distance. Remember that OpenAL is free to clamp gain values greater than 1, even though the equation and graph allow for larger values.

Figure 11.12. Graph of the Linear Distance model

Linear Distance Clamped

The Linear Distance Clamped model (see Figure 11-13) explicitly clamps gains greater than 1 to 1. From the graph, it is also more apparent that the reference distance is the trigger point for where the gain starts to decay. Comparing Figures 11-12 and 11-13, you can also see both the reference distance and the rolloff factor contribute to the slope of the line.

Figure 11.13. Graph of the Linear Distance Clamped model

Exponential Distance

You can tell that Exponential Distance model (see Figure 11-14) gets its name from the equation where there is an exponential value there. The curve exponentially drops based on the size of the rolloff factor. The reference distance shifts the curve so the gain is 1 where the reference distance is. Remember that OpenAL is free to clamp gain values greater than 1.

Figure 11.14. Graph of the Exponential Distance model

Exponential Distance Clamped

Like all the other clamped models, the Exponential Distance Clamped model (see Figure 11-15) explicitly clamps gains greater than 1 to 1. Gain decay stops when the maximum distance is reached. The rolloff factor affects the slope.

Figure 11.15. Graph of the Exponential Distance Clamped model

Time to add distance attenuation to Space Rocks!. Again, by now you pretty much know the drill. We will continue from the previous project, SpaceRocksOpenAL3D_4_VelocityDoppler. The finished project for this example is named SpaceRocksOpenAL3D_5_DistanceAttenuation.

First, EWSoundSourceObject must support properties for rolloffFactor, referenceDistance, and maxDistance. We already added rolloffFactor from our earlier work-around to disable attenuation at the beginning of the chapter, so we are already partway there. So first, add the remaining two instance variables and properties to EWSoundSourceObject.h and remember to synthesize them in the implementation.

ALfloat rolloffFactor;
                ALfloat referenceDistance;
                ALfloat maxDistance;


@property(nonatomic, assign) ALfloat rolloffFactor;
@property(nonatomic, assign) ALfloat referenceDistance;
@property(nonatomic, assign) ALfloat maxDistance;

In EWSoundSourceObject.m, Initialize the defaults to match the OpenAL defaults in the init method:

rolloffFactor = 1.0; // 0.0 disables attenuation
referenceDistance = 1.0;
maxDistance = FLT_MAX;

Set the properties in applyState:

alSourcef(sourceID, AL_ROLLOFF_FACTOR, rolloffFactor);
alSourcef(sourceID, AL_REFERENCE_DISTANCE, referenceDistance);
alSourcef(sourceID, AL_MAX_DISTANCE, maxDistance);

In BBSceneController.m, change the distance model in init from AL_NONE to something else. For our example, we will use AL_INVERSE_DISTANCE_CLAMPED.

[[OpenALSoundController sharedSoundController]
setDistanceModel:AL_INVERSE_DISTANCE_CLAMPED];

Now it's time to actually set our three properties for our specific game needs. First, in BBSceneObject's init method, set the maxDistance immediately after we create the soundSourceObject:

soundSourceObject.maxDistance = 600.0;

The maximum size of our game field is approximately 600 units wide. It is unchanging, so we just hard-code this value here.

Finally, we need to go through every BBSceneObject subclass we have (for every object we care about) and set the rolloffFactor and referenceDistance properties to something that will work well with our attenuation model. The following are the values I picked. I encourage you to play with them and try other models.

PREPARING YOUR SOUND SAMPLES

There are a lot of things to consider when creating and editing your sound files for your game—too many to cover here. But to give you an idea, you might want to think about things like prenormalizing/balancing your sounds so volume levels for different samples overpower others. You might also want to think about and test how a sample will sound when looped if you need to deal with sounds that repeat.

As an example, for this book, I took some care in preparing the missile sample used in our game. Both the UFO and UFO missile are prime subjects for showing off our 3D effects, because they make long-duration noises and move gradually across the screen. Therefore, I wanted to put a little more effort into creating these effects. But usually, missile recordings already attenuate, because most test firings watch the missile from a stationary fixed point from which the missile moves away at a high speed. For our example, I wanted fairly constant burn amplitude so I could let OpenAL be the main driver of any attenuation you hear and avoid getting a double attenuation effect.

Figure 11-16 shows my modified missile launch waveform in GarageBand. The original waveform's amplitude dropped off toward zero much more quickly than what's pictured here. I modified the sample to try to keep it roughly constant, so any attenuation you hear in the game will be due to OpenAL's distance attenuation feature and not the original audio sample. As you can see, the waveform is mostly consistent (a little attenuation, but not too bad). There is a quick drop off at the end, just so it didn't end too abruptly. (Imagine the missile running out of fuel, I suppose.)

Figure 11.16. Missile launch waveform in GarageBand

On a related subject, you might be wondering about the tools that are available for editing audio files. I will suggest two:

• GarageBand by Apple (shown in Figure 11-16) ships as part of iLife with every new Mac. Assuming you are using a Mac, it should already be installed on your computer. GarageBand has a lot of features that go beyond just PCM files, which also means there tends to be more of a learning curve.

• Audacity (shown in Figure 11-17), containing the same missile waveform as in the GarageBand screenshot) is an open source (and free) cross-platform sound application for recording and editing sounds. I like using Audacity for a lot of simpler things. I also like using Audacity because I can run it on other platforms, which is convenient for cross-platform development. Check out Audacity at http://audacity.sourceforge.net.

Figure 11.17. Missile launch waveform in Audacity