Chipmunk is a

Fast and lightweight 2D rigid body physics library in C

That last bit is important for iPhone development, because, as we all know, ‘C’ plays very well with Objective-C.  Once I figured out how to call Objective-C methods from the Chipmunk related ‘C’ code, integration was very smooth.  It’s worth mentioning that the standard ‘C’ code in the Chipmunk distribution compiles fine in Xcode and runs with no problems on the iPhone and iPod touch.  I was worried that I might run into some issues, but it was perfect.  By the way, we plan to use Chipmunk for other projects, so I set it up as a “Source Tree” in Xcode, rather than just dumping the files directly into the iPuck project space.  Paul wrote an excellent post on doing this for Oolong.  I just followed his directions.

I won’t list all of Chipmunk’s features, they are nicely presented on the project page, but it is fast and straightforward to use.

The documentation is a bit sparse, especially for someone just getting started.  The demos are very helpful, but generally seem to assume that we already have a pretty good understanding of Chipmunk.  A set of demo programs is bundled with the ChipmunkLatest.tgz download.  Even nicer demo programs are available in the project repository. 

Fortunately, Alexandre Gomes has prepared a nice tutorial on getting started with Chipmunk.  I noticed a few typos in the sample code, but it gave me a great start towards learning the library and figuring out how to slide it on to the iPuck chassis.  Mr. Gomes does a good job of explaining the basic concepts.  I highly recommend taking a look at the tutorial if you’re considering using Chipmunk.

Once I got started actually porting iPuck, I only encountered a couple of small snags.  The first came when I was still working with permutations of Mr. Gomes’ sample.  I couldn’t figure out how to grab an object and drag it around on the screen.  After a bit of searching on the extremely useful Chipmunk forum, I found some sample code that provided most of what I needed.  I’m led to believe that there will soon be better ways to do this in Chipmunk.  However, after a bit of customization, cpMouse met the needs for iPuck v1.1.  I plan to look at some of the other methods to see whether I can continue to improve the code.  Look out v1.2.

The other problem was my fault for not reading the cpShape documentation more thoroughly.  I had originally modeled a number of my static objects as cpSegmentShapes.  This worked really well as long as my active objects were all cpCircleShapes.  Unfortunately, when I tried to model an active object using segments, I discovered that the current version of Chipmunk does not support cpSegment-to-cpSegment collisions.  After I went back and converted to cpPolyShapes, everything was perfect.  If I had carefully read the Chipmunk documentation, before I started coding, I would have seen:

Line segments: Meant mainly as a static shape. They can be attached to moving bodies, but they don’t currently generate collisions with other line segments.

I needed to develop against a stable library, so I chose to stick with the 4.1.0 version.  Judging by the activity in the project archive, there has been substantial progress since 4.1.0 and I’m looking forward to working with the latest revisions when they’ve settled into a steady state.

If you’re working with rigid bodies, and you need a fast, accurate, easy to use and, best of all, license fee free, 2D physics library, Chipmunk may be a perfect match for your needs.

 
——–
Note:  Instructions for using Subversion to check out the code and demos are here.
——–
Technorati Tags:  iPhone, iPod Touch, Apple, mobile, chipmunk physics

With 3.0, several methods that were used in 2.x.y are now deprecated.  Use of these methods will generate warnings in 3.0.  Unfortunately, the correct code for 3.0 won’t work in 2.2.1, for example:

Perfectly good 2.2.1 code:

    [startButton setFont:playFont];

Clean compiling 3.0 code:

    [[startButton titleLabel] setFont:playFont];

So we’re faced with a problem.  How do we write code that compiles cleanly in 3.0, while maintaining our ability to do clean 2.2.1 (I’m tired of the 2.x.y notation – just assume that I’m talking generically about version 2 of the SDK) builds?

When we first encountered this, I found several suggestions, most of which were wrong to one degree or another.  As nearly as I can tell, the method that I’m suggesting is more generally workable.

Restating the problem, we need to write our code so that it compiles cleanly, and works, with both a strictly 2.2.1 version of the SDK and with a 3.0 version.  We get extra bonus points if the code won’t need to be revised when the successor to 3.0 comes out.

Because of the requirement to continue to work with strict 2.2.1, we can’t rely on the preprocessor constant for 3.0 being defined.  There’s also an interesting issue between the simulator and the device that I’ll cover later.

Anyway, here’s what we came up with:

#ifndef __IPHONE_3_0
#define __IPHONE_3_0 30000
#endif
#if __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_3_0
    [[startButton titleLabel] setFont:playFont];
#else
    [startButton setFont:playFont];
#endif

When I’m building against the 3.0 SDK, __IPHONE_3_0 is defined by Xcode, so my directives don’t interfere.  If all you wanted was the answer, you can stop here.  If you’d like more background on this issue, please continue reading.

First, a bit about where the pertinent preprocessor #defines are specified.  The file is Availability.h

For the simulator, the full pathname to Availability.h is:

    /Developer/Platforms/iphoneSimulator.platform/Developer/SDKs/  ↵
      …   iPhoneSimulator2.2.1.sdk/usr/include/Availability.h

For the device the path is:

    /Developer/Platforms/iphoneOS.platform/Developer/SDKs/  ↵
      …   iPhoneOS2.2.1.sdk/usr/include/Availability.h

In the version of Availability.h that goes along with 2.2.1, the following are defined:

#define __IPHONE_2_0 20000
#define __IPHONE_2_1 20100
#define __IPHONE_2_2 20200

Note that there is no __IPHONE_2_2_1

Now, here’s the tricky bit.  With Xcode, the mechanisms for communicating the version of the SDK that you’re using differ between builds for the simulator and builds for the device.  When compiling for the simulator, Xcode’s default configuration for a 2.2.1 build sets a flag as follows:

    -D__IPHONE_OS_VERSION_MIN_REQUIRED=20000

If you’re paying attention, you’ll notice that, when building for the simulator, targeting the 2.2.1 SDK, Xcode is setting the flag to 20000.

When building for the device, on the other hand, Xcode uses a completely different technique.  Instead of defining a version value for the preprocessor, the preprocessor substitutes:

    __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__

in place of:

    __IPHONE_OS_VERSION_MIN_REQUIRED.

Xcode (according to the comments in AvailabilityInternal.h) then has the compiler set:

    __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__

by using -miphoneos-version-min.  The actual compile directive when building for the 2.2.1 SDK is:

    -miphoneos-version-min=2.2.1

The implication of this is that, when you build for the simulator, the following code:

    NSLog(@"MIN VERS REQD: %d -- Current Version: %d",  ↵
      …   __IPHONE_OS_VERSION_MIN_REQUIRED,__IPHONE_2_2);

Causes this string to be output to the console:

    MIN VERS REQD: 20000 -- Current Version: 20200

The exact same code, running on the actual device, produces:

    MIN VERS REQD: 20201 -- Current Version: 20200

The reason I shared this in painful detail is to explain why some of the solutions that people are suggesting for this issue might not work in the general case.

Assuming that we’re building for the simulator as many of us do during development, the default Xcode configuration won’t let us find out whether we’re using any SDK later than 2.0.  For example, if we have code that goes something like:

// DO NOT DO THIS
#if __IPHONE_OS_VERSION_MIN_REQUIRED > __IPHONE_2_2
    [[startButton titleLabel] setFont:playFont];
#else
    [startButton setFont:playFont];
#endif

This code will work on the simulator because __IPHONE_OS_VERSION_MIN_REQUIRED will be 20000, which is not greater than 20200.  It will not work on the device, however, because 20201 is greater than 20200.  Remember that there is no official definition of _IPHONE_2_2_1.  Sigh…

Another approach that I considered was:

// THIS MIGHT WORK, BUT I DON’T RECOMMEND IT
#ifndef __IPHONE_3_0
    NSLog(@"THE 3.0 SDK IS NOT DEFINED");
#else
    NSLOG(@"THE 3.0 SDK IS DEFINED");
#endif

The problem here is that I’m not testing the value, I’m simply seeing if it’s defined.  If the variable ever gets defined in my code (perhaps due to a bit like what I’m proposing) or if the Xcode ever picks up a version of Availability.h that defines __IPHONE_3_0 when you’re building for 2.2.1 (I know that this shouldn’t happen, but better safe than sorry) the preproccesor will eliminate the wrong lines of code.  Remember that there are multiple versions of Availability.h kicking around on your system.  Check out the one at /usr/include/Availability.h sometime.

——–
Technorati Tags:  iPhone, iPod Touch, iPhone OS, Xcode,Apple, mobile

One of the questions that I’ve faced myself, and that I’ve now tried to answer many times for others, is, “Which method should I use to play sounds for my app?”

Here’s the overview, right from Apple’s Getting Started with Audio & Video document:

Playing Audio and Invoking Vibration
Depending on your needs, you play audio in iPhone OS using System Sound Services, the AVAudioPlayer class, Audio Queue Services, OpenAL, or the I/O audio unit.

• To play alerts and user-interface sound effects, or to invoke vibration, use System Audio Services. This technology can play .caf, .wav, and .aif files containing sounds with durations of 30 seconds or less. Refer to “Using Sound in iPhone OS” in iPhone Application Programming Guide and to System Sound Services Reference.
• To play sounds of any duration, to play multiple sounds simultaneously [dgs- see comments on this below], or to play sounds with level control, use the AVAudioPlayer class. This technology can play any audio format supported in iPhone OS including MP3, AAC, ALAC (Apple Lossless), IMA4, linear PCM, and others. See iPhone Application Programming Guide and AVAudioPlayer Class Reference.
• To play sounds with precise control—such as for synchronization—or to play audio captured from an Internet stream, use Audio Queue Services. See Audio Queue Services Programming Guide and Audio Queue Services Reference. For sample code, see SpeakHere.
• To play positional audio, especially if your application is a game, use OpenAL, an open source technology documented at http://openal.org. See OpenAL FAQ for iPhone OS for important information on using this technology in iPhone OS. For sample code, see oalTouch.
• To play sounds with lowest I/O latency, or to provide simultaneous audio input and output, use the I/O audio unit. See the aurioTouch sample.

Some details that are left out of this overview, including:

Compressed Formats on the iPhone — The bottom line here is that the higher level frameworks on the iPhone will only play one highly compressed sound at a time.  This is due to limitations in the processing available to decompress sounds in the audio pipeline.  You might be able to get around this by implementing your own decoder and feeding the resulting uncompressed audio to either OpenAL, or AudioQueue, but that’s beyond my interests at this point.  Apple’s statement above regarding AVAudioPlayer could be a bit misleading, because AVAudioPlayer will not play multiple MP3 sounds simultaneously.  Here’s the section from Coding How-Tos: Audio and Video:

The following limitations pertain for simultaneous sounds in iPhone OS, depending on the audio data format:

• AAC, MP3, and ALAC (Apple Lossless) audio: no simultaneous playback; one sound at a time.

Can I Play an MP3 with SystemAlerts? — No.  SystemAudioServices only plays sounds in linear PCM or IMA4 (IMA/ADPCM) format, packaged as a .caf, .aif, or .wav file.  AVAudioPlayer, on the other hand, supports the playback of any audio format available in the iPhone OS.  This is documented in the iPhone Application Programming Guide: Multimedia Support

Why not just stick with AVAudioPlayer? — AVAudioPlayer is fine, if you don’t need positional audio and if you’re not worried about some significant delays in starting up each player.  This latter bit can be especially important if you’re trying to fire off sounds in a tight loop, or if you need to synchronize effects in a multi-threaded environment.

What I you recommend? — Use SystemAudioServices if your sounds are short and available in the proper formats.  It’s by far the simplest player and, within its constraints, it pretty much handles everything for you.  Use AVAudioPlayer for operations like playing songs or recorded speech.  Unfortunately, Apple doesn’t sanction SoundEngine anymore, but I’ve become a big fan of using SoundEngine on top of OpenAL for games.  This combination hides some of the complexities of OpenAL while still giving you access to most of the standard stuff.  Also, it’s easy to extend SoundEngine to get at pretty much any OpenAL functionality you need.  We downloaded the source for SoundEngine from the Oolong site, but it might be a bit easier to grab it directly from coocos2d.

A final word.  With pretty much everything beyond SystemAudioServices, you’ll want to seriously consider managing the Audio Session yourself.  As always, Apple provides excellent documentation.  Even Apple encourages you to take care of this detail:

Each iPhone OS application gets an audio session object, usually called an audio session. This object comes with some default behavior that you can use to get started in development. Except for certain special cases, however, the default behavior is unsuitable for a shipping application.

You don’t need to instantiate an AudioSession object.  The iPhone OS provides every app with a singleton AudioSession when the app launches.  However, you do have to initialize the AudioSession.  You may also need to set properties, and you’ll probably want to Activate/Deactivate the session.

Happy sounds!

——–
Technorati Tags:  iPhone, iPod Touch, Apple, mobile

First, let’s consider Code Completion.  Two keys here are particularly useful.  <ctl>+. (control + period) cycles through the list of possible completions for the token that you’ve typed, while pressing <esc> brings up the full list of possible completions.  The Xcode menu suggests <opt>+<esc> (alt/option + escape) for this action, but just <esc> seems to work fine.

If code completion doesn’t seem to be working for you, be sure to check the setting for the Automatically Suggest menu in Xcode’s Code Sense preferences.

Another shortcut that I use frequently is <ctl>+/ (control + slash), which cycles between the placeholders highlighted by Code Completion.  Sometimes you can also accomplish this with the arrow keys, but <ctl>+forward slash always works.

Happy Xcoding!

 
——–
Technorati Tags:  iPhone, iPod Touch, Apple, mobile

Before I go any further, I should share some of the details of the sounds for this app.  They are all relatively short (roughly 2 seconds, or less).  Their intensity peaks early, tapers quickly to a relatively low level, then trails off very gently for most of their duration.  Their time domain plot looks something like a question mark rotated -90 degrees, then mirrored across the x-axis.

Since, as previously discussed, I couldn’t use AudioServices, I had to figure out a way to make either SoundEngine/OpenAL, or AVAudioPlayer (which was later rejected for a different reason), work.  Some of my less embarrassing attempts to solve this included:

The first tactic that I tried was to simply stop the currently playing effect/player (for the sake of simplicity, I’ll just refer to both as players for the rest of this post) and start it again.  Unfortunately, this introduced a distinct, and very unpleasant, click when the stop/start happened.  If your app is a shooter, with lots of sharp explosions and weapon reports, this might not be a problem, but it was a showstopper for us.

The next thing that I tried was gradually reducing the volume of the current player before stopping it.  That didn’t help, much.

With AVAudioPlayer, I also tried just setting the player back to the beginning, instead of stopping it. [myPlayer setCurrentTime:0.0] – the results were actually worse than a stop/restart.

At that point, I decided to try a combination approach.  If the subsequent attempt to play came early in the original player’s span, I just skipped the later attempt.  If the attempt came well into the original, I gradually reduced the volume of the original, stopped it and then started the player again.  This was better, because there were fewer stop/starts, but it still wasn’t perfect.  Which leads us to the solution that I ended up implementing…

In the end, I went with a backup player technique.  I have two players set up to play each sound (I used players here to be consistent.  They’re really effects, since I’m using SoundEngine/OpenAL).  If the first one is busy, I use the second one.  If both are busy, I skip playing the sound.  I was all set to go even deeper, to three, or even four, players for each sound.  Fortunately, two gave good results, and the code was straightforward, so I stuck with a single level of backup.

I probably should have tried this first, but I was worried about both the memory and the execution overhead of having multiple players for each sound.  My concern was not warranted.  With the current implementation, the overhead is negligible, and the results are great.

——–

Technorati Tags:  iPhone, iPod Touch, Apple, mobile, SoundEngine, AVAudio, AudioServices

The problem with that approach quickly became apparent.  There was a noticeable distortion when more than 2-3 sounds were playing at the same time.  The unpleasant effect was kind of a stuttering static, sort of like one might hear if one over-drives speakers.  This, unfortunately, pretty much ruined the effect of the app, so Paul suggested lowering the volume of the sounds.  Sadly, one can’t do that for an AudioServices system sound.

At that point, I switched the app over to using AVAudioPlayer.  This seemed like it was going to be a good solution, so I wrote a utility app to help me test the individual sound volume settings and spent quite a bit of time experimenting to find the “right” level for each possible combination of sounds.  I really thought that I was in the home stretch until I fired up the app and found that the motion went from butter smooth to unacceptably jerky.  Since actual playback of AVAudioPlayer is asynchronous with regards to the main thread, the last thing that I looked at (after wasting more time than I should have on optimization) was the actual call to [myAVAudioPlayer play].  Big mistake.

After eliminating everything else, I bracketed the [myAVAudioPlayer play] calls with a timer and was amazed to discover that the calls were taking 0.04 – 0.05 seconds, on the calling thread, just to get started.  After that, the player went along asynchronously, as expected.  Since my simulation loop was running in increments of 0.0167 seconds, having each call to [myAVAudioPlayer play] block for 3x that amount made for a very unhappy user experience.  My next thought was to bounce right to OpenAL, but I decided that the (apparently) no longer sanctioned (at least it’s not available from Apple anymore) SoundEngine might give me most of what I needed, without my having to worry about managing buffers and sources.

Unfortunately, SoundEngine lacked some OpenAL functionality that I really needed (being able to find out if a given effect is currently playing and also to find out how far along the effect is).  I ended up implementing extensions to SoundEngine to get at the OpenAL stuff, and, so far, everything is working.  The most recent discovery was that the SoundEngine/OpenAL combination does not initialize and properly configure an AudioSession.  This means that our app stopped when the device went into Auto-Lock.  Not necessarily a good thing for a “lifestyle” app.  Once I took care of that, I’m back to calibrating the sound levels and doing more testing on the functionality.  I constantly have my fingers crossed that I don’t encounter any more problems that will force me to abandon the extended SoundEngine.

I may do a longer post on the perils of using compressed audio formats in the future, but let’s wrap this bit up with a warning.  While compression can really help with your download times, you may want to be careful about choosing when to employ compressed formats.  There are a couple of reasons for this.  First, some of the iPhone SDK playback options support only a limited subset of the compressed formats.  Second, the device won’t play the highly compressed formats simultaneously.  If you plan to play multiple sounds at the same time, highly compressed formats might not be an option.

Most of the points covered here are well documented in the Getting Started with Audio & Video document.  If I’d had the discipline to read the whole thing before I started down this path, the trip would have been much less frustrating.

Technorati Tags:  iPhone, iPod Touch, Apple, mobile

    <Command>+<Option>+↑   (that’s <UpArrow>)

…toggles between header and source.  As the result is a toggle, a similarly modified ↓ isn’t required to invert the operation.   If I’d looked through Xcode’s menus, I could also have dug it up – it’s under the View menu – but I’m not a menu guy, I’d never even looked at the View menu until I started this post.

That’s it for today’s tip, enjoy…

Postscript:  I tried to use angle brackets:  〈 and 〉 in this post. Every browser that I checked, except IE, handled them just fine.  Sigh…

Technorati Tags:  iPhone, iPod Touch, Apple, mobile, Xcode

IB lets me position my controls interactively, and it provides somewhat straightforward hooks for connecting my program to the new controls.  One of the big complaints that I noticed, and one that frustrated me a bit, at least at first, was that IB doesn’t provide full access to all of the settings on the controls that it specifies.  The specific example for me was setting the font for the Title text for the regular "Round Rect Button."  Support for this operation is clearly evident via the "setfont:" method specified in the class header file, but I couldn’t find any way to get at the method through the IB Attributes Inspector.

As suggested above, I’m pretty lazy, so I didn’t want to abandon IB just to change the font face and size, then a solution appeared.  I simply established an outlet to the specific button:

@interface ButtonTestViewController : UIViewController {
…
IBOutlet UIButton *theButton;
…

and wrote the following code:
…
UIFont *theFont = [UIFont boldSystemFontOfSize:30];
[theButton setFont:theFont];
CGSize tOff = CGSizeMake(2.0,2.0);
[theButton setTitleShadowOffset:tOff];
…

For what it’s worth, my situation was such that I was able to put the code to set the button in the viewDidLoad method.

One other thing to keep in mind when you’re loading your application from a nib, the ViewController’s initWithCoder is the initialization method that gets called.  Thanks to Jeff LaMarche for the explanation of initializers in his response to this question.

Unless you just love writing and maintaining UI code, I strongly urge you to take a careful look at IB.  I’ll continue to use it whenever I can.

Technorati Tags:  iPhone , iPod Touch , Apple , mobile

BTW, if you order an iMac, be sure to consider whether the full size keyboard (with Numeric Keypad) is a better fit for you than the now standard Apple Keyboard.  The full size keyboard doesn’t add to the cost of the system, but you do have to select it explicitly as you order.  I didn’t realize how much I used both “Delete” and “Backspace,” until I used the MacBook keyboard and had to use Fn-Del for forward Delete.

Technorati Tags:  iPhone, iPod Touch, Apple, mobile