Here’s a little demo of what we are going to make in this article shown running on the iPhone simulator.

Well today what we’ll look at is the CDAudioManager class of the CocosDenshion package itself and see if we can produce some neat effects to spice up our games.

Let’s understand CDAudioManager a bit by looking at the comments in the source.

/** CDAudioManager is a wrapper around AVAudioPlayer.
 CDAudioManager is basically a thin wrapper around an AVAudioPlayer object used for playing
 background music and a CDSoundEngine object used for playing sound effects. It manages the
 audio session for you deals with audio session interruption. It is fairly low level and it
 is expected you have some understanding of the underlying technologies. For example, for
 many use cases regarding background music it is expected you will work directly with the
 backgroundMusic AVAudioPlayer which is exposed as a property.

 Requirements:
 - Firmware: OS 2.2 or greater
 - Files: CDAudioManager.*, CocosDenshion.*
 - Frameworks: OpenAL, AudioToolbox, AVFoundation
 @since v0.8
 */

Since it’s a wrapper around AVAudioPlayer we have some functionality for obtaining data that you can use for playback-level metering.

The methods to use for level metering are:

• the meteringEnabled property
• -(void)updateMeters
• -(float)averagePowerForChannel:(NSUInteger)channelNumber
• -(float)peakPowerForChannel:(NSUInteger)channelNumber

Since we’re just quickly setting up some background audio, let’s do this as simple as possible by using SimpleAudioEngine.

Accessing CDAudioManager

SimpleAudioEngine (as of this post) won’t give us direct access to the audio manager for our background music so let’s quickly add a get method to return the audio manager.

SimpleAudioEngine.m

-(CDAudioManager*)audioManager
{
	return am;
}

Update: The alternative for accessing is through the sharedInstance of audio manager and I’ve now reworked the code to use that instead. So now you don’t need to modify SimpleAudioEngine anymore.

We needed access to CDAudioManager so we can get access to AVAudioPlayer to access metering methods. We do this below:

Updated for performance by weak referencing the AVAudioPlayer instance into a class variable.

audioPlayer_ = [[SimpleAudioEngine sharedEngine] audioManager].backgroundMusic;
audioPlayer_.meteringEnabled = YES;

Well we have enabled metering but what we now need to do is call updateMeters every time we need
to get meter level values. Cocos2D has functionality for scheduling timers so we set that up and call updateMeters.

-(void)tick:(ccTime) dt
{
	[audioPlayer_ updateMeters];
}

While still in the loop where we update our meter, we can now get values for the average and peak power of our background music.

-(void)tick:(ccTime) dt
{
	[audioPlayer_ updateMeters];
	double peakPowerForChannel = 0.f, avgPowerForChannel = 0.f;

	for(ushort i = 0; i < audioPlayer_.numberOfChannels; ++i){
		//	convert the -160 to 0 dB to [0..1] range
		peakPowerForChannel = pow(10, (0.05 * [audioPlayer_ peakPowerForChannel:i]));
		avgPowerForChannel = pow(10, (0.05 * [audioPlayer_ averagePowerForChannel:i]));

		filteredPeak_[i] = filterSmooth_ * peakPowerForChannel + (1.0 - filterSmooth_) * filteredPeak_[i];
		filteredAverage_[i] = filterSmooth_ * avgPowerForChannel + (1.0 - filterSmooth_) * filteredAverage_[i];
	}
}

What I’ve done is set all this up in the class AudioVisualization which will handle all the background audio metering for you. You access the class through the sharedAV method which returns a shared singleton instance.

All you need to do is add your delegate with the method:

-(void)addDelegate:(id<AudioVisualizationProtocol>)delegate forChannel:(ushort)channel;

The forChannel argument specifies the channel you want to meter for your background music. If it is mono then just set it to 0.

Now you just need to implement one of the AudioVisualizationProtocol‘s to receive level values for your delegate.

-(void)avAvgPowerLevelDidChange:(float)level channel:(ushort)aChannel;

That’s pretty much it! Hope you find this as cool as I did when I figured it out.

Just download the example demo file below to try it out.

This demo uses the fast, easy and open source cocos2d framework.
CocosDenshion is the sound engine for the cocos2d framework if you didn’t know that from reading this whole post =/.

Creating, Initializing, Allocating

The first major thing that jumps out to those new to Obj-C is the little plus (+) or minus (-) sign sitting in front of methods. I’ll make use of the NSNumber class throughout this tutorial since it’s simple and it can also be useful in real programming.
If you look into the Apple documentation for NSNumber you’ll find both “Creating an NSNumber Object” and “Initializing an NSNumber Object”. What the heck is the difference there? Take a look!

// These would be found as part of the interface of NSNumber
// Creating an NSNumber
+ (NSNumber *)numberWithInt:(int)value;

// Initializing an NSNumber
- (id)initWithInt:(int)value;

Hmmmm, there isn’t much difference there but those little (+/-) are very important. First off a little bit of terminology, those methods starting with the (+) are called class methods and the ones with (-) are called instance methods. In simple terms this means you need to have an instance of a class to be able to use the (-) instance methods. This means that to use those initialization instance methods we have to first allocate our class. It’s easiest to see if we look at an example.

// Use a class method to get a new NSNumber
// Using
//	+ (NSNumber *)numberWithInt:(int)value;
NSNumber *newNumber = [NSNumber numberWithInt:5];

// Calling an instance method on our new number
NSLog(@"%d", [newNumber intValue]);

// Allocating and initialization of NSNumber
// Using
//	- (id)initWithInt:(int)value;
NSNumber *newAllocedInitNumber = [[NSNumber alloc] initWithInt:5]];

// Calling an instance method on our other new number
NSLog(@"%d", [newAllocedInitNumber intValue]);

So we can see the difference in use here, but initially it looks like we get the same usage for both of our new numbers, the NSLog calls in both cases will print out a “5″. So why should we care about all of this? If this was all the code we have then our program would have a memory leak! Despicable! A memory leak in such a simple little piece of code. That [NSNumber alloc] call is the issue here, this means that our newAllocedInitNumber is being retained; it will hang around forever. We can look at a quick fix for this and hopefully it should make a little more sense. There’s also some nuances about our newNumber object but we’ll go over that in a little bit.

// Allocating and initialization of NSNumber
// Using
//	- (id)initWithInt:(int)value;
NSNumber *newAllocedInitNumber = [[NSNumber alloc] initWithInt:5]];

// Calling an instance method on our other new number
NSLog(@"%d", [newAllocedInitNumber intValue]);

// All done with our new number, lets smash that memory leak
[newAllocedInitNumber release];

Fixed! In this case it’s really just that simple and gives us a great general rule to follow. If you alloc you must release. Make sure you’ve always got that one in the back of your brain. If you alloc you must release.

Now let’s get back to the newNumber object and see what’s happening there. There’s no memory leak for this guy. In fact there’s nothing wrong with it at all, so what is there to talk about? Autorelease. When you create an object in this way it will be automatically released for you. Sounds great; and it is! For the beginner and for a lot of programs that’s all you need to know and you won’t really need to worry about manually managing your memory. Nothing in life is free though and the same is true for auto release. You must remember that you can’t be sure about how long any auto released object will hang around for so it might possibly sit around for awhile taking up memory before it gets released. If you’re writing a game or some other memory intensive program this may matter to you.

Dealloc to the Rescue!

Now that we understand a little bit about how our memory is or isn’t being managed we can look at an another important example that you’ll be sure to come across. You want to make a spiffy new class that holds onto an NSNumber so you can do fancy things with it at a later time. What does that look like? Maybe something like this.

// Declare our spiffy new class
@interface SpiffyClass : NSObject {
	NSNumber *fancyNumber_;
}
@end

// Implement our spiffy new class
@implementation SpiffyClass
- (id) init {
	// A little bit of initialization, this is generally how most of your init methods will start
	if ((self=[super init])) {
		fancyNumber_ = [[NSNumber alloc] initWithInt:111];
	}
	return self;
}

// Doing fancy things with a fancy number
- (void)fancyPants {
	NSLog(@"Fancy %d pants", [fancyNumber_ intValue]);
}
@end

Alright, we have a sparkly new SpiffyClass declaration with our fancyNumber_ object and a call to our fancyPants method will result in the logged message “Fancy 111 pants”. Everything looks fine and dandy here, let’s move on. Wait! Another memory leak is lurking here. We were so close! Remember our little rule, if you alloc you must release. We’re missing our release. Let’s try again.

// . . . interface is the same

// Implement our spiffy new class
@implementation SpiffyClass
- (id) init {
	// A little bit of initialization, this is generally how most of your init methods will start
	if ((self=[super init])) {
		fancyNumber_ = [[NSNumber alloc] initWithInt:111];
	}
	return self;
}

// Doing fancy things with a fancy number
- (void)fancyPants {
	NSLog(@"Fancy %d pants", [fancyNumber_ intValue]);

	// We must remember, if we alloc then we release
	[fancyNumber_ release];
}
@end

Hmmm. Not too bad, we remembered our rule. Let’s try printing our fancy pants message 2 times. Crash, burn, blech! What happened? Trying to call fancyPants more than once will try to release the fancyNumber_ object more than once. Since it’s already been released and it was only allocated once this can cause some problems. (This would be a good point to look up retain count, but I won’t go over it here). How then do we know when to release our fancyNumber_ object? We probably want to hold onto fancyNumber_ until SpiffyClass dies.

// . . . interface is the same
// . . . init is the same

// Ahhhh, I'm dying!
- (void)dealloc {
	[fancyNumber_ release];

	// You'll pretty much always need this
	[super dealloc];
}

// Doing fancy things with a fancy number
- (void)fancyPants {
	NSLog(@"Fancy %d pants", [fancyNumber_ intValue]);
}
@end

Adding the dealloc method is what we need here. dealloc is called automatically whenever an instance of an object gets released. No more memory leaks, no more crashing. Fantastic!

Hopefully this little beginner tutorial is helpful to get you started on the road to understanding memory management in Objective-C. Pages and pages could be written about memory management and some key topics that I skipped over include, retain count, what is super dealloc, and more about auto release and auto release pools. In the future we’ll be covering more of these topics in depth and piece-meal so check back often.

The problem at hand

Sometimes we will need to process data or have an in-game wait or delay. We can’t let users wait without any visual indication so generally we’ll implement a loading progress image. This simple concept is shown below.

If that’s what you are also aiming to do then read ahead!

Discovery

We want a solution that can work for any image type and is setup for cocos2d-iphone. A really neat idea is that we can map triangles using opengl to show certain portions of the image.

We see that for the mapping to work, we’ll use:

1. the midpoint vertex (vertex 0)
2. the 12 o’clock vertex (vertex 1)
3. each corner edge up-to, (vertex 2-5)
4. the point created from the progress percentage (vertex 6)

Not too hard when we really get down to solving it.

Let’s implement the thing

First we setup a ProgressTimer class that inherits a CCNode so we can add it to the engine.
ProgressTimer, at it’s core, will hold the percentage value, a texture, and the vertex data so we can render the object in opengl. (Note that the sample below has more because I’ve implemented the option to change its opacity and color. I’ve also added different progress timer types.)

ProgressTimer.h

typedef enum {
	kProgressTimerTypeRadialCCW,
	kProgressTimerTypeRadialCW,
	kProgressTimerTypeHorizontalBarLR,
	kProgressTimerTypeHorizontalBarRL,
	kProgressTimerTypeVerticalBarBT,
	kProgressTimerTypeVerticalBarTB,
} ProgressTimerType;

@interface ProgressTimer : CCNode {
	ProgressTimerType	type_;
	float				percentage_;
	CCTexture2D			*texture_;

	int					vertexDataCount_;
	ccV2F_C4F_T2F		*vertexData_;

	int					indicesCount_;
	GLubyte				*indices_;

	GLubyte				opacity_;
	ccColor3B			color_;
	ccBlendFunc			blendFunc_;
}
///
//	Change the percentage to change progress.
///
@property ProgressTimerType type;
///
//     The percentage of progress from 0..100
///
@property float percentage;
@property (retain) CCTexture2D *texture;
@property ccColor3B color;
@property GLubyte opacity;
@property ccBlendFunc blendFunc;

///
//	Creates a progress timer with the texture as the shape the timer goes through
///
+ (id) progressWithTexture:(CCTexture2D*) aTexture;
- (id) initWithTexture:(CCTexture2D*) aTexture;

@end

We’ll skip the basic initializing and destruction of variables and get right to the most important piece. The mapping of the image in order to create the radial indicator.

Every time a user changes the percentage we will update the ProgressTimer vertex data.

-(void)setPercentage:(float) percentage
{
	if(percentage_ < 0.f)
		percentage_ = 0.f;
	else if(percentage > 100.0f)
		percentage_  = 100.f;
	else
		percentage_ = percentage;

	[self updateProgress];
}

ProgressTimer‘s updateProgress will call updateRadial if our type is set to kProgressTimerTypeRadialCCW or kProgressTimerTypeRadialCCW. Radial type is our pie slice indicator and the CW/CCW suffix represents it’s rotation direction (clockwise or counter-clockwise).

What we will do is understand the implementation details of developing the radial slices.

Every radial update, we will release all vertex data memory on the heap.

ProgressTimer.m updateRadial

	//	release all previous information
	if(vertexData_){
		free(vertexData_);
		vertexData_ = 0;
		vertexDataCount_ = 0;
	}

	if(indices_){
		free(indices_);
		indices_ = 0;
		indicesCount_ = 0;
	}

	//	If percentage is zero it's quicker not to create the vertexData
	if(percentage_ == 0.f)
		return;

Finding that midpoint

The easiest vertex point to find on the image is the midpoint and as an added bonus we will use a CCNode‘s anchorPoint so we have a choice for the center. The midpoint has to be adjusted by the actual texture maximums since we don’t always deal with texture sizes with powers of 2. Once we have the midpoint we now have enough information to find the next needed vertex.

	CGPoint tMax = ccp(texture_.maxS,texture_.maxT);
	CGPoint midpoint = ccpCompMult(self.anchorPoint, tMax);

ccCompMult is just a multiplying each component of the two points together

CGPoint ccpCompMult(CGPoint a, CGPoint b)
{
	return ccp(a.x * b.x, a.y * b.y);
}

The percentage point

Now we find the vertex point based on the ProgressTimer percentage.

We can find the angle needed to rotate from the 12 o’clock position.
Taking that angle, the point of rotation is found by doing a vector rotation from the vertex at the 12 o’clock to the percentage point.

	float alpha = percentage_ / 100.f;
	//	Otherwise we can get the angle from the alpha
	float angle = 2.f*M_PI * ( type_ == kProgressTimerTypeRadialCW? alpha : 1.f - alpha);

	//	We find the vector to do a hit detection based on the percentage
	//	We know the first vector is the one @ 12 o'clock (top,mid) so we rotate
	//	from that by the progress angle around the midpoint pivot
	CGPoint percentagePt = ccpRotateByAngle(ccp(midpoint.x, 0.f), midpoint, angle);

ccpRotateByAngle takes our point and a pivot and rotates it around the pivot by the angle.

CGPoint ccpRotateByAngle(CGPoint v, CGPoint pivot, float angle) {
	CGPoint r = ccpSub(v, pivot);
	float t = r.x;
	double cosa = cosf(angle), sina = sinf(angle);
	r.x = t*cosa - r.y*sina;
	r.y = t*sina + r.y*cosa;
	r = ccpAdd(r, pivot);
	return r;
}

We’re almost there but the rotated point isn’t the correct point needed for the vertex data. What we really need is the intersection point from the line edge of the texture and the percentage line.

How I attacked this problem is that the texture coordinates need to be in an array so we can quickly find the correct edge for the intersection test.

#define kProgressTextureCoordsCount 4
const CGPoint kProgressTextureCoords[kProgressTextureCoordsCount] = {{0,0},{0,1},{1,1},{1,0}};

As I finished writing this I noted that maximum texture coordinate values are always 0 and 1 so let’s represent the array as a sequence of bits 00011110 (which corresponds to 0x1e).

So I rewrote the array as

#define kProgressTextureCoordsCount 4
const char kProgressTextureCoords = 0x1e;

And a function that will give me the corresponding texture coordinates for an index value. It pretty much operates at the bit level to retrieve the correct value (if this is confusing I may write a lesson on bit operations).

-(CGPoint)boundaryTexCoord:(char)index
{
	if (index < kProgressTextureCoordsCount) {
		switch (type_) {
			case kProgressTimerTypeRadialCW:
				return ccp((kProgressTextureCoords>>((index<<1)+1))&1,(kProgressTextureCoords>>(index<<1))&1);
			case kProgressTimerTypeRadialCCW:
				return ccp((kProgressTextureCoords>>(7-(index<<1)))&1,(kProgressTextureCoords>>(7-((index<<1)+1)))&1);
			default:
				break;
		}
	}
	return CGPointZero;
}

Now we have the texture corner coordinates; we now need the edge of the texture and the percentage point line.

We can find the nearest edge based on the alpha value. Since we need 2 points for the line, we grab the previous index and make sure the previous index is wrapped within our array bounds.

	int index = roundf(kProgressTextureCoordsCount*alpha);
	int pIndex = (index + (kProgressTextureCoordsCount - 1))%kProgressTextureCoordsCount;

	CGPoint edgePtA = [self boundaryTexCoord:index % kProgressTextureCoordsCount];
	CGPoint edgePtB = [self boundaryTexCoord:pIndex];

The percentage line is just the midpoint and the percentage point.

ccpLineIntersect returns true if an intersection occurred. We pass it 4 points that make up 2 lines.
L1 = p2 – p1
L2 = p4 – p3
Then we grab the hit point using the returned ‘s’ or ‘t’ value.
hit = midpoint + (percentagePoint – midpoint)*t;

bool ccpLineIntersect(CGPoint p1, CGPoint p2,
								 CGPoint p3, CGPoint p4,
								 float *s, float *t){
	CGPoint p13, p43, p21;
	float d1343, d4321, d1321, d4343, d2121;
	float numer, denom;

	p13 = ccpSub(p1, p3);

	p43 = ccpSub(p4, p3);

	//Roughly equal to zero but with an epsilon deviation for float
	//correction
	if (ccpFuzzyEqual(p43, CGPointZero, kCGPointEpsilon))
		return false;

	p21 = ccpSub(p2, p1);

	//Roughly equal to zero
	if (ccpFuzzyEqual(p21,CGPointZero, kCGPointEpsilon))
		return false;

	d1343 = ccpDot(p13, p43);
	d4321 = ccpDot(p43, p21);
	d1321 = ccpDot(p13, p21);
	d4343 = ccpDot(p43, p43);
	d2121 = ccpDot(p21, p21);

	denom = d2121 * d4343 - d4321 * d4321;
	if (fabs(denom) < kCGPointEpsilon)
		return false;
	numer = d1343 * d4321 - d1321 * d4343;

	*s = numer / denom;
	*t = (d1343 + d4321 *(*s)) / d4343;
	return true;
}

We pass the points into our intersect formula (notice we multiply the corner components by tMax since we need the actual texture coordinates and sometimes we’ll have images that are not powers of 2.

//	s and t are returned by ccpLineIntersect which explains how to use them
	float s = 0, t = 0;
	ccpLineIntersect(ccpCompMult(edgePtA,tMax), ccpCompMult(edgePtB,tMax),
					 midpoint, percentagePt, &s, &t);

	//	get the hit point
	CGPoint hit = ccpAdd(midpoint, ccpMult(ccpSub(r2, midpoint),t));

We have all our needed points calculated! Now all that’s left is creating the vertex data.

Creating Our Vertex Data

To create the vertex data we first need to convert texture coordinates (in the 0..1) range to actual vertex coordinates [0..imageSize] which I have written below.

///
//	@returns the vertex position from the texture coordinate
///
-(CGPoint)vertexFromTexCoord:(CGPoint) texCoord
{
	if (texture_) {
		float min = 0, maxW = texture_.contentSize.width, maxH = texture_.contentSize.height;
		return ccp(lerp(min, maxW, texCoord.x/texture_.maxS),
				   lerp(min, maxH, (1.f -(texCoord.y/texture_.maxT))));
	} else {
		return CGPointZero;
	}
}

Now we have all that we need to create our vertex data what we’ll do is first store the midpoint position. Then the point at 12 o’clock on the texture.

Now we add each corner of the texture into the vertex array until we reach the hit point and we add the hit point last.

After the vertex data is complete we begin creating the triangle by setting up the indexes. Let’s take a look at our original setup of vertex data.

To create triangles from the example vertexes above we can see that the indexes will hold.

indices_ = {0,1,2, 0,2,3, 0,4,5, 0,5,6};

The code is shown below:

	//	The size of the vertex data is the index from the hitpoint
	//	the 3 is for the midpoint, 12 o'clock point and hitpoint position.
	vertexDataCount_ = index + 3;
	vertexData_ = malloc(vertexDataCount_ * sizeof(ccV2F_C4F_T2F));

	//	First we populate the array with the midpoint, then all
	//	vertices/texcoords/colors of the 12 'o clock start and edges and the hitpoint
	vertexData_[0].texCoords = (ccTex2F){midpoint.x, midpoint.y};
	vertexData_[0].vertices = [self vertexFromTexCoord:midpoint];

	vertexData_[1].texCoords = (ccTex2F){midpoint.x, 0.f};
	vertexData_[1].vertices = [self vertexFromTexCoord:ccp(midpoint.x, 0.f)];

	for(int i = 0; i < index; ++i){
		CGPoint texCoords = ccpCompMult([self boundaryTexCoord:i], tMax);

		vertexData_[i+2].texCoords = (ccTex2F){texCoords.x, texCoords.y};
		vertexData_[i+2].vertices = [self vertexFromTexCoord:texCoords];
	}

	//	hitpoint will go last
	vertexData_[vertexDataCount_ - 1].texCoords = (ccTex2F){hit.x, hit.y};
	vertexData_[vertexDataCount_ - 1].vertices = [self vertexFromTexCoord:hit];	

	indicesCount_ = 3 * (index + 1);
	indices_ = malloc(indicesCount_ * sizeof(GLubyte));

	//	We only go up to index since we do three increments
	for(int i=0;i < indicesCount_/3; ++i){
		indices_[3*i] = 0;
		indices_[3*i + 1] = i + 1;
		indices_[3*i + 2] = i + 2;
	}

The only thing left to do is draw our vertex data

ProgressTimer draw

	glBindTexture(GL_TEXTURE_2D, texture_.name);
	glVertexPointer(2, GL_FLOAT, sizeof(ccV2F_C4F_T2F), &vertexData_[0].vertices);
	glTexCoordPointer(2, GL_FLOAT, sizeof(ccV2F_C4F_T2F), &vertexData_[0].texCoords);
	glColorPointer(4, GL_FLOAT, sizeof(ccV2F_C4F_T2F), &vertexData_[0].colors);
	glDrawElements(GL_TRIANGLES, indicesCount_, GL_UNSIGNED_BYTE, indices_);

And now we have a ProgressTimer indicator. If you want to see the demo file of this tutorial then just click on the link.

This demo uses the fast, easy and open source cocos2d framework.

Get for only $0.99

We found during the recording of this short Pixel Pile demo that the screen capture didn’t work out perfectly so the video is a little bit washed out. Rest assured that the retail game will be bright and vibrant and those stars pulsing to the beat of the music will definitely stand out. We were really lucky to find music from mattmcfarland.com, be sure to check it out for some great music if you happen to be developing an indie game.

More information on Pirates vs Ninjas will be added soon to the PvN Page, if you would like to receive updates or contact us about the game you can reach us at pvn@fancyratstudios.com

Arrrrrr.