Understanding what memory management is and why you need to do it.

There are two main points that form the basis of all of this:

• Every device has a limited amount of memory available, which means it can only store a limited amount of information. Imagine the memory as a pile of empty boxes, ready to be filled with stuff.
• Every time you create an object, you are grabbing one of these empty boxes and using it to store your object in. That object will now hapilly live inside the box for the rest of its life.

Note the term “for the rest of its life” – this is the important bit. While an object exists, it holds on to its box, so nothing else can live in it. If you want to create another object, you’ve got to grab another box from the pile for it to live in, and so on.

Now, if you destroy an object, its box becomes empty again and gets thrown back onto the pile, ready to get used again.

OK, so now what happens if we keep creating objects, but never destroy them when we’re done using them? (Incidently, this is what is known as a memory leak) Well, we keep needing empty boxes to put our objects in. But remember, our device only has a limited amount of memory, so we’re going to run out eventually. And when that happens, it’s game over. A number of things can happen to your application, depending on the device and operating system, including:

• An exception is thrown when you try and create a new object when there’s no more space
• The operating system can just force your application to close and grab back all of its memory without even notifying you
• Nothing happens, but your memory allocation returns an invalid address. If you try and use this address, your application and device might just crash

Obviously, we don’t want any of these to occur, so we’d better make sure we tidy up after ourselves and put the boxes back.

Memory management in C

Firstly, we’ll look at the basic functions for managing memory. Starting with plain C, we’ve got:

* – The heap is our pile of boxes (i.e. all of our application’s memory)

Simple. We’ve got our function that grabs some memory, and one that puts it back. This is great for basic programs, but in larger applications, you’ll soon realise that you need to be very careful about what you do with that memory. Take the following:

// This function returns a copy of a C-style string
char* String_Copy(const char* pString)
{
	int SizeOfMemoryNeeded = 0;
	char* pMemoryToReturn = NULL;
 
	// Get the length of the string
	SizeOfMemoryNeeded = strlen(pString);
 
	// Add 1 byte on for the null terminator
	// strlen returns the number of characters in the string,
	// but C-style strings need a byte at the end set to 0
	// to mark where the string stops. (This is known as being null-terminated)
	SizeOfMemoryNeeded += 1;
 
	// Allocate our memory
	pMemoryToReturn = (char*)malloc(SizeOfMemoryNeeded);
 
	// Copy our string
	strcpy(pMemoryToReturn, pString);
 
	// Return the newly allocated memory
	return pMemoryToReturn;
}
 
int main()
{
	const char* pMyString = "This is my string";
	char* pCopiedString = NULL;
 
	// Copy MyString
	pCopiedString = String_Copy(pMyString);
 
	// Now we have a pointer, pCopiedString, which
	// points at the memory we grabbed in String_Copy.
 
	// ....
 
	// We pass our copied string into a function
	SomeFunction(pCopiedString);
 
	// ....
 
	// So now we decide we're going to play nice and clean up
	// our memory that we allocated:
	free(pCopiedString);
}

Ownership

So that’s all fine and good. We’ve played nice and put our box back on the pile when we’re done with it. Then one day, after lots of code has been added to our project, suddenly we get BOOM! when we try and free our memory. What gives? Well, after hours of searching, we eventually find this travesty somewhere deep in the program:

void SomeFunctionDeepInTheProgram(char* pAString)
{
	// Do some stuff
 
	// We don't need the string any more, so lets delete it
	free(pAString);
}

Gah! Whoever wrote that should be shot. It turns out that our copied string was being passed into this function, and the function was freeing up its memory ready to be used by something else.

The key here is ownership. Who’s in charge of the memory that was created in String_Copy? Who should be the one that frees it up? One good way to decide this is through the use of certain key words in our function names. We can define a simple rule that we’ll always stick to:

• If a function with the word Copy or Create in its name returns memory, then whoever called that function owns the memory.

See how our main() function calls String_Copy? Under our rule, that means that the main() function is responsible for cleaning up that memory, and no one else. SomeFunctionDeepInTheProgram is being naughty, because it’s trying to free up memory that it didn’t get via a Copy or Create function. If everyone follows our simple rule, then we can avoid this situation.

Hopefully that gives you a bit of an introduction into why you need to really think about memory management. Next time we’ll talk about more complex memory management, garbage collectors, reference counting and automatic memory management.

This tutorial is based on the Skinned Model sample, so grab it from the App Hub if you want to follow along, or skip to the end if you want the final version (which is released under the same license as the original).

What we’ll be doing is creating an XML file to go with our exported model, which will define our animation clips and events. The animations defined in this file will replace animations defined in the source model file. So, first thing is to define the class that will be represented by the XML file. Create a class in the SkinnedModelPipeline project named AnimationDefinition, like so:

using System;
using System.Collections.Generic;
using System.Text;
 
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Content;
using Microsoft.Xna.Framework.Content.Pipeline;
using Microsoft.Xna.Framework.Content.Pipeline.Serialization;
using Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate;
 
namespace SkinnedModelPipeline
{
    /// <summary>
    /// A class for storing our animation definitions
    /// </summary>
    public class AnimationDefinition
    {
        /// <summary>
        /// The original clip name that was exported by the modelling package
        /// Usually this will be Take 001
        /// </summary>
        public string OriginalClipName
        {
            get;
            set;
        }
 
        /// <summary>
        /// The number of frames in the original animation
        /// </summary>
        public int OriginalFrameCount
        {
            get;
            set;
        }
 
        /// <summary>
        /// A class for storing information about individual clips that we want to create
        /// </summary>
        public class ClipPart
        {
            /// <summary>
            /// The name we have given the clip
            /// </summary>
            public string ClipName
            {
                get;
                set;
            }
 
            /// <summary>
            /// The starting frame of the clip
            /// </summary>
            public int StartFrame
            {
                get;
                set;
            }
 
            /// <summary>
            /// The ending frame of the clip
            /// </summary>
            public int EndFrame
            {
                get;
                set;
            }
 
            /// <summary>
            /// A class for defining events in an animation
            /// </summary>
            public class Event
            {
                /// <summary>
                /// The name of the event
                /// </summary>
                public string Name
                {
                    get;
                    set;
                }
 
                /// <summary>
                /// The frame that the event fires on
                /// </summary>
                public int Keyframe
                {
                    get;
                    set;
                }
            };
 
            /// <summary>
            /// Our list of events in this animation clip
            /// Animation clips do not require events, so this is marked as optional
            /// </summary>
            [Microsoft.Xna.Framework.Content.ContentSerializer(Optional = true)]
            public List<Event> Events
            {
                get;
                set;
            }
        };
 
        /// <summary>
        /// The list of clip parts that we are breaking the original clip into
        /// </summary>
        public List<ClipPart> ClipParts
        {
            get;
            set;
        }
    }
}

Next, we’ll need to modify the runtime project to add information about our events to the animations. Create a class in the SkinnedModelWindows project named AnimationEvent, with this in it:

#region Using Statements
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
#endregion
 
namespace SkinnedModel
{
    /// <summary>
    /// Information about an event in our animation
    /// </summary>
    public class AnimationEvent
    {
        /// <summary>
        /// The name of the event
        /// </summary>
        public String EventName
        {
            get;
            set;
        }
 
        /// <summary>
        /// The time of the event
        /// </summary>
        public TimeSpan EventTime
        {
            get;
            set;
        }
    }
}

Now, we need to add our events store to the animation clip, as well as the clip name. So open up AnimationClip.cs, and add this to the end of the class:

	/// <summary>
        /// Callback events for the animation clips
        /// </summary>
        [ContentSerializer]
        public List<AnimationEvent> Events { get; private set; }
 
	/// <summary>
        /// The name of the clip
        /// </summary>
        [ContentSerializer]
        public string Name { get; private set; }

We also need to modify the constructor so that we can pass in the list of animation events when we create the clip. Our new constructor looks like this:

	/// <summary>
        /// Constructs a new animation clip object.
        /// </summary>
        public AnimationClip(TimeSpan duration, List<Keyframe> keyframes, List<AnimationEvent> events, string name)
        {
            Duration = duration;
            Keyframes = keyframes;
            Events = events;
            Name = name;
        }

Almost there. We need to modify the SkinnedModelProcessor class so that it reads in our XML files describing our animations and stores them in the model file that it generates, replacing the original animation (the Take 001). So, in SkinnedModelProcessor.cs, in the ProcessAnimations function, we need to first check if an animation definition file exists that we will use to override the ones in the model. By having this check, it means that we don’t need to create an animation definition for every skinned model, just the ones that we want custom animations on. You’ll also need to modify the ProcessAnimations function to take two extra parameters, which are the ContentProcessorContext and ContentIdentity. We use these to get information about the current file we are processing, so we can look for an animation definition with the same name. The below code is the updated ProcessAnimations function:

        /// <summary>
        /// Converts an intermediate format content pipeline AnimationContentDictionary
        /// object to our runtime AnimationClip format.
        /// </summary>
        static Dictionary<string, AnimationClip> ProcessAnimations(
            AnimationContentDictionary animations, IList<BoneContent> bones,
            ContentProcessorContext context, ContentIdentity sourceIdentity)
        {
            // Build up a table mapping bone names to indices.
            Dictionary<string, int> boneMap = new Dictionary<string, int>();
 
            for (int i = 0; i < bones.Count; i++)
            {
                string boneName = bones[i].Name;
 
                if (!string.IsNullOrEmpty(boneName))
                    boneMap.Add(boneName, i);
            }
 
            // Convert each animation in turn.
            Dictionary<string, AnimationClip> animationClips;
            animationClips = new Dictionary<string, AnimationClip>();
 
            // We process the original animation first, so we can use their keyframes
            foreach (KeyValuePair<string, AnimationContent> animation in animations)
            {
                AnimationClip processed = ProcessAnimation(animation.Value, boneMap, animation.Key);
 
                animationClips.Add(animation.Key, processed);
            }
 
            // Check to see if there's an animation clip definition
            // Here, we're checking for a file with the _Anims suffix.
            // So, if your model is named dude.fbx, we'd add dude_Anims.xml in the same folder
            // and the pipeline will see the file and use it to override the animations in the
            // original model file.
            string SourceModelFile = sourceIdentity.SourceFilename;
            string SourcePath = Path.GetDirectoryName(SourceModelFile);
            string AnimFilename = Path.GetFileNameWithoutExtension(SourceModelFile);
            AnimFilename += "_Anims.xml";
            string AnimPath = Path.Combine(SourcePath, AnimFilename);
            if (File.Exists(AnimPath))
            {
                // Add the filename as a dependency, so if it changes, the model is rebuilt
                context.AddDependency(AnimPath);
 
                // Load the animation definition from the XML file
                AnimationDefinition AnimDef = context.BuildAndLoadAsset<XmlImporter, AnimationDefinition>(new ExternalReference<XmlImporter>(AnimPath), null);
 
                // Break up the original animation clips into our new clips
                // First, we check if the clips contains our clip to break up
                if (animationClips.ContainsKey(AnimDef.OriginalClipName))
                {
                    // Grab the main clip that we are using
                    AnimationClip MainClip = animationClips[AnimDef.OriginalClipName];
 
                    // Now remove the original clip from our animations
                    animationClips.Remove(AnimDef.OriginalClipName);
 
                    // Process each of our new animation clip parts
                    foreach (AnimationDefinition.ClipPart Part in AnimDef.ClipParts)
                    {
                        // Calculate the frame times
                        TimeSpan StartTime = GetTimeSpanForFrame(Part.StartFrame, AnimDef.OriginalFrameCount, MainClip.Duration.Ticks);
                        TimeSpan EndTime = GetTimeSpanForFrame(Part.EndFrame, AnimDef.OriginalFrameCount, MainClip.Duration.Ticks);
 
                        // Get all the keyframes for the animation clip
                        // that fall within the start and end time
                        List<Keyframe> Keyframes = new List<Keyframe>();
                        foreach (Keyframe AnimFrame in MainClip.Keyframes)
                        {
                            if ((AnimFrame.Time >= StartTime) && (AnimFrame.Time <= EndTime))
                            {
                                Keyframe NewFrame = new Keyframe(AnimFrame.Bone, AnimFrame.Time - StartTime, AnimFrame.Transform);
                                Keyframes.Add(NewFrame);
                            }
                        }
 
                        // Process the events
                        List<AnimationEvent> Events = new List<AnimationEvent>();
                        if (Part.Events != null)
                        {
                            // Process each event
                            foreach (AnimationDefinition.ClipPart.Event Event in Part.Events)
                            {
                                // Get the event time within the animation
                                TimeSpan EventTime = GetTimeSpanForFrame(Event.Keyframe, AnimDef.OriginalFrameCount, MainClip.Duration.Ticks);
 
                                // Offset the event time so it is relative to the start of the animation
                                EventTime -= StartTime;
 
                                // Create the event
                                AnimationEvent NewEvent = new AnimationEvent();
                                NewEvent.EventTime = EventTime;
                                NewEvent.EventName = Event.Name;
                                Events.Add(NewEvent);
                            }
                        }
 
                        // Create the clip
                        AnimationClip NewClip = new AnimationClip(EndTime - StartTime, Keyframes, Events, Part.ClipName);
                        animationClips[Part.ClipName] = NewClip;
                    }
                }
            }
 
            if (animationClips.Count == 0)
            {
                throw new InvalidContentException(
                            "Input file does not contain any animations.");
            }
 
            return animationClips;
        }
 
        /// <summary>
        /// Gets a TimeSpan value for a frame index in an animation
        /// </summary>
        private static TimeSpan GetTimeSpanForFrame(int FrameIndex, int TotalFrameCount, long TotalTicks)
        {
            float MaxFrameIndex = (float)TotalFrameCount - 1;
            float AmountOfAnimation = (float)FrameIndex / MaxFrameIndex;
            float NumTicks = AmountOfAnimation * (float)TotalTicks;
            return new TimeSpan((long)NumTicks);
        }

What we do is process the original animations, so that all the keyframe data is there, then we check for an animation definition file and, if it exists, use it to replace the animation clips from the original model. We also need to modify ProcessAnimation to handle the new AnimationClip constructor:

        /// <summary>
        /// Converts an intermediate format content pipeline AnimationContent
        /// object to our runtime AnimationClip format.
        /// </summary>
        static AnimationClip ProcessAnimation(AnimationContent animation,
                                              Dictionary<string, int> boneMap,
                                              string clipName)
        {
            List<Keyframe> keyframes = new List<Keyframe>();
 
            // For each input animation channel.
            foreach (KeyValuePair<string, AnimationChannel> channel in
                animation.Channels)
            {
                // Look up what bone this channel is controlling.
                int boneIndex;
 
                if (!boneMap.TryGetValue(channel.Key, out boneIndex))
                {
                    throw new InvalidContentException(string.Format(
                        "Found animation for bone '{0}', " +
                        "which is not part of the skeleton.", channel.Key));
                }
 
                // Convert the keyframe data.
                foreach (AnimationKeyframe keyframe in channel.Value)
                {
                    keyframes.Add(new Keyframe(boneIndex, keyframe.Time,
                                               keyframe.Transform));
                }
            }
 
            // Sort the merged keyframes by time.
            keyframes.Sort(CompareKeyframeTimes);
 
            if (keyframes.Count == 0)
                throw new InvalidContentException("Animation has no keyframes.");
 
            if (animation.Duration <= TimeSpan.Zero)
                throw new InvalidContentException("Animation has a zero duration.");
 
            return new AnimationClip(animation.Duration, keyframes, new List<AnimationEvent>(), clipName);
        }

OK, so now we can override animations in the models using our XML file. Before I show you an example file, there’s one last thing to do, which is to add in the event callback system into the runtime. So, we need to add in a place to register our event callbacks into the AnimationPlayer class. At the end of the ‘Fields’ region, we need to add:

	// The delegate template for the event callbacks
        public delegate void EventCallback(string Event);
 
        // The reigstered events
        Dictionary<string, Dictionary<string, EventCallback>> registeredEvents = new Dictionary<string, Dictionary<string, EventCallback>>();
        public Dictionary<string, Dictionary<string, EventCallback>> RegisteredEvents
        {
            get { return registeredEvents; }
        }

And initialise the registeredEvents dictionary in the constructor:

	// Construct the event dictionaries for each clip
        foreach (string clipName in skinningData.AnimationClips.Keys)
        {
            registeredEvents[clipName] = new Dictionary<string, EventCallback>();
        }

Now we can add events, so the last thing to do is to add the code that calls them, then we’ll be done. In the UpdateBoneTransforms function in AnimationPlayer, we need to modify it like so:

        /// <summary>
        /// Helper used by the Update method to refresh the BoneTransforms data.
        /// </summary>
        public void UpdateBoneTransforms(TimeSpan time, bool relativeToCurrentTime)
        {
            if (currentClipValue == null)
                throw new InvalidOperationException(
                            "AnimationPlayer.Update was called before StartClip");
 
            // Store the previous time
            TimeSpan lastTime = time;
 
            // Update the animation position.
            if (relativeToCurrentTime)
            {
                lastTime = currentTimeValue;
                time += currentTimeValue;
 
                // Check for events
                CheckEvents(ref time, ref lastTime);
 
                // If we reached the end, loop back to the start.
                bool hasLooped = false;
                while (time >= currentClipValue.Duration)
                {
                    hasLooped = true;
                    time -= currentClipValue.Duration;
                }
 
                // If we've looped, reprocess the events
                if (hasLooped)
                {
                    CheckEvents(ref time, ref lastTime);
                }
            }
 
            if ((time < TimeSpan.Zero) || (time >= currentClipValue.Duration))
                throw new ArgumentOutOfRangeException("time");
 
            // If the position moved backwards, reset the keyframe index.
            bool HasResetKeyframe = false;
            if (time < currentTimeValue)
            {
                HasResetKeyframe = true;
                currentKeyframe = 0;
                skinningDataValue.BindPose.CopyTo(boneTransforms, 0);
            }
 
            currentTimeValue = time;
 
            // Read keyframe matrices.
            IList<Keyframe> keyframes = currentClipValue.Keyframes;
 
            while (currentKeyframe < keyframes.Count)
            {
                Keyframe keyframe = keyframes[currentKeyframe];
 
                // Stop when we've read up to the current time position.
                if ((keyframe.Time > currentTimeValue) && (!HasResetKeyframe))
                    break;
 
                // Use this keyframe.
                boneTransforms[keyframe.Bone] = keyframe.Transform;
 
                currentKeyframe++;
 
                if(HasResetKeyframe)
                {
                    currentTimeValue = keyframe.Time;
                    HasResetKeyframe = false;
                }
            }
        }

And add the CheckEvents function:

        /// <summary>
        /// Checks to see if any events have passed
        /// </summary>
        private void CheckEvents(ref TimeSpan time, ref TimeSpan lastTime)
        {
            foreach (string eventName in registeredEvents[currentClipValue.Name].Keys)
            {
                // Find the event
                foreach (AnimationEvent animEvent in currentClipValue.Events)
                {
                    if (animEvent.EventName == eventName)
                    {
                        TimeSpan eventTime = animEvent.EventTime;
                        if ((lastTime < eventTime) && (time >= eventTime))
                        {
                            // Call the event
                            registeredEvents[currentClipValue.Name][eventName](eventName);
                        }
                    }
                }
            }
        }

So now we can define custom animations with events. Lets see it in action…

Add a new file to your content project, giving it the same name as the model, but with _Anims.xml. In our case, our model file is dude.fbx, so we want dude_Anims.xml. We don’t actually want the content pipeline to build this directly, so set the Build Action property to None, the Content Processor to No Processing Required, and Copy to Output Directory to Do not copy. Our XML looks like this:

<?xml version="1.0" encoding="utf-8" ?>
<XnaContent>
 
  <Asset Type="SkinnedModelPipeline.AnimationDefinition">
 
    <!-- The original name of the clip we are breaking up -->
    <OriginalClipName>Take 001</OriginalClipName>
 
    <!-- The total number of frames in the original clip -->
    <OriginalFrameCount>100</OriginalFrameCount>
 
    <!-- The new parts we want -->
    <ClipParts>
 
      <!-- Each item is one of our new clips -->
      <Item>
        <ClipName>Idle</ClipName>
        <StartFrame>0</StartFrame>
        <EndFrame>50</EndFrame>
      </Item>
 
      <Item>
        <ClipName>Fire</ClipName>
        <StartFrame>51</StartFrame>
        <EndFrame>99</EndFrame>
 
        <!-- We can register events in this clip, so we can know when certain frames are hit -->
        <Events>
          <Item>
            <Name>FireFrame</Name>
            <Keyframe>70</Keyframe>
          </Item>
        </Events>
 
      </Item>
 
    </ClipParts>
 
  </Asset>
 
</XnaContent>

Now we can play our new clips like normal. We can also add callbacks for events. For example, the FireFrame event, we add like this:

            // Create an animation player, and start decoding an animation clip.
            animationPlayer = new AnimationPlayer(skinningData);
 
            // Register an event
            animationPlayer.RegisteredEvents["Fire"].Add("FireFrame", new AnimationPlayer.EventCallback(OnFire));
 
            AnimationClip clip = skinningData.AnimationClips["Fire"];
 
            animationPlayer.StartClip(clip);

And our function just looks like this:

        private void OnFire(string EventName)
        {
            // Do something here like create a bullet
        }

So there you have it. You can download the updated sample here. You can use the ’1′ and ’2′ keys to switch between animation clips. The second one has a callback registered to it. One thing to note is that you’ll have to make sure you do a Rebuild Solution if you’re adding an animation XML to an existing model, because the content pipeline doesn’t know that the model depends on the animation definition until after it has built it once with the animation file there. Enjoy!

It is useful to be able to quickly and easily generate texture atlases from a number of source sprites to speed up development. A useful tool when developing using the XNA framework is the SpriteSheet Sample available on the XNA Creators Club website. One downside of this, however, is that you must still manually generate the XML file list by hand, which can be a pain if you have a lot of textures to place on the sprite sheet. Another is that it is XNA only

Because we also do development on the iPhone, it was useful to have a similar generator for that platform, as well as for the XNA framework, so we created a tool to easily generate the texture atlases for us. The packing code is based on the SpriteSheet Sample code, though the tool is written in plain .NET, so does not require the XNA framework to be installed (though it does require the .NET framework). The tool can produce a PNG file with the combined textures, as well as an accompanying binary file, called a TXA file, with the information on each of the packed textures. It also supports removing transparent borders from textures to produce a more compact output. It can also optionally produce a C style header with enums in, so you don’t have to look up the textures by their names.

The help files for the texture atlas generator tool contain information on the format of the TXA files, so you can write your own loaders if you wish.

As well as the PNG + TXA combination, the tool can produce an XNA XML file (and optionally a C# file with enums in) which can be imported into your Content project to build the sprite sheet during compile time. You do need to include the XNA projects in yours to access the Content Processor and runtime types. The runtime library also includes extensions to the SpriteBatch class, to make it easier to draw using the textures.

Finally, there is a runtime library to load the texture atlas on an iPhone. The iPhone code uses the PVRTexture class from Apple’s sample code, so you can convert the PNG to a PVR if you wish using Apple’s texturetool (though this can be problematic as the textures may ‘bleed’ into each other). The iPhone runtime library also requires zlib and libpng

Each zip contains a Readme.txt file containing license information and other tips. You’re pretty much free to do what you want with these things, use them however you see fit (commercial or non-commercial), but remember they are provided as-is, and we accept no responsibility for anything We’ve tried to tidy them up to make them usable by other people, but if you’ve got any problems or questions, post in the comments and we’ll try and help. There may be bugs in these, so let us know if you find any!

• Texture Atlas Generator
• XNA Runtime and Pipeline Libraries
• iPhone Runtime – Requires zlib and libpng

So, the problem is: Given a regular tile map, where each tile is either a square or a triangle taking up half of the square, generate sets of vertices which describe each ‘chunk’ of geometry in the map. E.g.:

The first method I tried was adapting this method, by representing each tile in a 2×2 way, like so:

Then performing the contour tracing algorithm in the link above, and removing every other point in the resulting list of points. At first it looked like this worked, but there were a couple of cases where a triangle was placed next to another triangle where the algorithm failed.

After thinking about it for a while, I came up with this method, which I’m pretty sure works, but if anyone can see any errors with it, please do let me know. I’ll give you the algorithm, then go through it in detail. The algorithm goes as follows:

Pick a start tile
    Add the start tile to the open list
    Remove the tile from the tile map
    Add each of the tile's vertices to the vertex list
    Add each of the tile's edges to the edge list
    While the open list is not empty
        CurrentTile = Tile at the end of the open list
        NextTile = Tile in the "forward" direction of the current tile
        If NextTile exists and shares a common edge with the current shape
            Add NextTile to the open list
            Remove NextTile from the tile map
            Add NextTile's vertices to the vertex list (without creating duplicates)
            Generate an edge list for NextTile
            Remove edges that overlap from the main edge list and the edge list for NextTile
            Add the remaining edges from NextTile to the main edge list
        Else
            Move on to the next "forward" direction for CurrentTile
            If "forward" direction for CurrentTile = initial "forward" direction
                Remove CurrentTile from the open list
 
Traverse the edge list and add the vertices that are used to the vertex list for your shape

So, what does that all mean? Well, lets go through it step by step:

Add the start tile to the open list

The easiest way to search for a start tile is to do a row by row search. Start at 0,0 and scan along the first row, then the second and so on until you find an occupied tile. This is your start tile. The open list is a list of tiles currently being looked at. The start tile will be the first tile in this list.

Remove the tile from the tile map

Removing the tile from the tile map means that the algorithm will no longer visit them. Obviously, if you need your tile map after running the algorithm, create a copy of it

Add each of the tile’s vertices to the vertex list

The vertex list stores each corner point that has been used by each tile. For the first tile, just add the world space corner points to the list.

Add each of the tile’s edges to the edge list

The edge list is an list of, you guessed it, edges! Each edge is a pair of indices into the vertex list. Note that edges should always be specified in the same winding order and should always start at the same corner. I.e. pick clockwise or counter-clockwise and use that for both the square and triangle tiles, like so:

Notice on the last triangle that we started at the top left (as there is no vertex in the bottom left, and this would be the next one round in our clockwise winding order).

While the open list is not empty

I.e. While we’re still examining tiles for our current shape.

CurrentTile = Tile at the end of the open list

Set the current tile to the last tile added to the open list

NextTile = Tile in the “forward” direction of the current tile

Each tile in the open list maintains the direction of the neighbour that it is currently examining. Each time a tile is added to the open list, its “forward” direction (i.e. the direction in which to examine) is set to “up”. I just use an integer here, with the range 0 – 3, representing up, right, down and left, in that order. When we’re on a tile, we examine the neighbour in the tile’s “forward” direction, and pursue that path as far as possible. The next time the algorithm comes back to a tile, it rotates to the next “forward” direction and tries that path, until all four directions have been exhausted.

If NextTile exists and shares a common edge with the current shape

If there is a neighbour in our current tile’s “forward” direction, then we check to see if the neighbour and the current tile share common edges. One way to do this is to generate a list of edges for NextTile using the current vertex list. Any edges which contain vertices in the current vertex list will use the same vertex indices as the existing edges, but in reverse order (due to each tile having the same winding order), like so:

In the above image, the shared edge is V2 -> V3 for the left tile, and V3 -> V2 for the right tile.

Add NextTile to the open list

Add NextTile to the end of the open list, initialising its “forward” direction to 0 (up)

Remove NextTile from the tile map

Remove NextTile from the tile map so it is not revisited by the algorithm (except for when it is returned to by the open list).

Add NextTile’s vertices to the vertex list (without creating duplicates)

Add each world space vertex for the tile to the vertex list, but don’t create duplicates for vertices that are already in the vertex list.

Generate an edge list for NextTile

Generate a list of edges (remember, each edge is a pair of indices into the vertex list), using vertices from the vertex list.

Remove edges that overlap from the main edge list and the edge list for NextTile

Remove any edges that overlap from both the edge list that was just generated for NextTile, and the main edge list. Remember, neighbouring tiles with overlapping edges will specify the indices of the overlapping edge in opposite order from each other. I.e. If a tile has an edge V2 -> V3, and the neighbouring tile has an edge that shares these vertices, the neighbouring tile’s edge will be V3 -> V2. This is due to the winding order, as shown above.

Add the remaining edges from NextTile to the main edge list

Any edges that do not overlap can now be added to the main edge list

Move on to the next “forward” direction for CurrentTile

When you reach here, it means there are no tiles to check in the current direction, so we should rotate to look in the next direction. If you’re storing your “forward” direction as an integer, simply increment it.

If “forward” direction for CurrentTile = initial “forward” direction

This is a check to see if we’ve exhausted each of the four directions. The initial “forward” direction will be 4 if you’re representing directions as an integer in the range 0 – 3. If the “forward” direction reaches 4, it means we have tested each direction (0 – 3) and we are done with this tile.

Remove CurrentTile from the open list

As we are done with this tile, we can remove it from the open list.

So, after we’ve generated our edge list, we now need to traverse it. Simply start at the first edge and follow the trial of edges around the shape until you reach the start vertex again. E.g.: First edge: V0 -> V1, so add V0 and V1 to your shape, then search for an edge that starts at V1. Next edge: V1 -> V4, so add V4 to your shape and search for an edge that starts at V4, and so on, until you reach V0 again. You’ve now got a list of vertices that represent your shape.

After this, two possible further steps are to optimize your final list of vertices (i.e. remove co-linear ones, so you are only left with the corner vertices), and remove any tiles which are inside your shape (unless you want to create shapes within shapes). Note, that the final step will only produce the outline shape of an object, so will not handle holes in closed objects. You may be able to handle holes in closed objects by recursively performing the last step and removing edges from the final edge list as you visit them, until the list is empty. This should give you multiple shapes, the first being the outer shape and the rest being the holes inside the shape, but I haven’t really looked in to this that much, so it may not work

Here’s a little animation of the algorithm. The grey edges are overlapping ones that have been removed.

Anyway, the problem is in the FBDialog.m file. There are a couple of lines that read:

UIWindow* window = [UIApplication sharedApplication].keyWindow;
if (!window) {
    window = [[UIApplication sharedApplication].windows objectAtIndex:0];
}
[window addSubview:self];

The problem comes when you try and show the Facebook dialog just after something other than the main window is the key window. This could happen if you’ve popped up a UIAlertView to ask if the user wants to publish to Facebook. The UIAlertView is the application’s key window and when you display your Facebook dialog, it adds itself as a subview of the UIAlertView (which is currently closing). So, your dialog will start to display, then when the UIAlertView finishes closing, it’ll disappear. The easy fix is to just change the FBDialog.m file so that it always uses the second line, and doesn’t try to use the keyWindow property:

UIWindow* window = [[UIApplication sharedApplication].windows objectAtIndex:0];
[window addSubview:self];

So, I’m guessing you have to set your release date way off into the future (because you have no idea how long it’s going to take Apple to approve your app), so that when it’s approved, you can bring it forward to the current date and it’ll be top of the new releases list. I’m going to be trying this with our next iPhone game, so I’ll keep you posted how it turns out. The one potential problem is that if Apple looks at the release date to determine when they’ll test your app, it might be a while before it gets tested.

Update: Apparently, from reading around, the release date will be listed as the earliest of (i) the date you set when submitting, and (ii) the date it is approved by Apple. So even if you set your availability date to some distant future date, then set it to something sensible when it’s released, it’ll be down in iTunes as the date it was approved. So I guess the moral of the story is this:

When submitting your app to the App Store, set the availability date to a month or two ahead (and remember to update it if you have to re-submit or if it takes Apple ages to approve it), so that it’s always ahead of the date it gets approved. Then, once it’s approved, set the release date to the date it was approved (so it actually appears on the App Store). You need to set it as soon as you receive the “Ready for sale” e-mail from apple, and remember to set the availability date to the date that Apple sent the e-mail (remember to take into account the time difference between you and Apple in Cupertino). E.g. If you receive the e-mail in the early hours of Tuesday morning, and you’re in the UK, then Apple will have sent the e-mail on Monday (their time), so your availability date should be Monday.

The first is using a custom font with a UILabel. Although you can set the font property of a UILabel, the only fonts you can create are system fonts. What you have to do is subclass the UILabel class and override the – (void)drawTextInRect:(CGRect)rect method with your own implementation.

First things first though, you need to load in your font. Note: With this method, you need to distribute the .ttf file with your app. Make sure this is ok in the font’s license.

// Get the path to our custom font and create a data provider.
NSString *fontPath = [[NSBundle mainBundle] pathForResource: @"FontFilename" ofType:@"ttf"];
CGDataProviderRef fontDataProvider = CGDataProviderCreateWithFilename([fontPath UTF8String]);
 
// Create the font with the data provider, then release the data provider.
 
// Note: s_CustomFont is a static variable, not an instance variable
// so that it can be shared between all instances of the custom font UILabel class
s_CustomFont = CGFontCreateWithDataProvider(fontDataProvider);
CGDataProviderRelease(fontDataProvider);

Now that you’ve got the font loaded in, you need to draw your text with it. Unfortunately, you can’t just set the font then call [super drawTextInRect: rect]. This is because there are actually two different methods of drawing fonts in Quartz. CGContextShowText displays a string of text using the currently selected font. You select the font using CGContextSelectFont, but this function is only capable of selecting a built in system font. The other option is to use CGContextShowGlyphs and CGContextSetFont. Notice that’s SetFont and not SelectFont.

The SelectFont / ShowText combination uses the name of the font to look up the font data and the glyph mapping table in the system. The glyph mapping table is used by the font renderering routines to match up glyphs from the font with characters in your string. There’s no way to programatically set the glyph mapping table, which is why there are the two methods of drawing text.

When using the SetFont / ShowGlyphs method, you need to manually convert the characters in your string to glyph indices in the font. Fortunately, this generally works out pretty easily, which we’ll see later.

Now that we have our font loaded in, we can write our custom drawTextInRect function. So, first thing’s first, you need to set the font to use:

CGContextSetFont(UIGraphicsGetCurrentContext(), s_CustomFont);
 
// We need to tell the system which font size to use too
float FontSize = 18; // 18-pt font size
CGContextSetFontSize(UIGraphicsGetCurrentContext(), FontSize);

Then we need to convert our string to glyph indices. Like I said before, this mostly works out quite easily. Usually, you just need to offset the character index by a “magic number”, and most of the time this number turns out to be -29:

// Convert the text to glyphs
int StringLength = [self.text length];
 
// Make sure you remember to free these after rendering
CGGlyph* Glyphs = malloc(sizeof(CGGlyph) * StringLength);
char* Chars = malloc(sizeof(char) * (StringLength + 1));
 
// Convert characters to glyph indices
[self.text getCString: Chars maxLength: (StringLength + 1) encoding: NSASCIIStringEncoding];
for(int CurrentChar = 0; CurrentChar < StringLength; ++CurrentChar)
{
    Glyphs[CurrentChar] = Chars[CurrentChar] - 29;
}

One thing to consider here is that any new line escape sequences will end up with some really high glyph index (as CGGlyph is just an unsigned short). But you have to handle new lines manually anyway, so it shouldn’t be too bad.

Finally, we can draw our text. You need to setup your text matrix and text position before drawing the text, like this:

// Set the text matrix, otherwise it draws upside down
CGAffineTransform TextMatrix = CGAffineTransformIdentity;
 
TextMatrix.d = -1;
CGContextSetTextMatrix(UIGraphicsGetCurrentContext(), TextMatrix);
 
// Set the text position - Remember, 0, 0 is the top left of the text's draw rectangle, not the screen
CGContextSetTextPosition(UIGraphicsGetCurrentContext(), 0, 0);

Note that CGContextSetTextPosition sets the same translation values that the translation component of the text matrix sets, so in the above case it’s obsolete. But when you start adding multi-line and alignment support, it’s cleaner to just set the text matrix once and then just use CGContextSetTextPosition to set the position.

Now just draw your glyphs:

CGContextShowGlyphs(UIGraphicsGetCurrentContext(), Glyphs, StringLength);

So there’s our basic custom font drawing routing. If I recall correctly, it’ll crash as soon as you have a newline in your string, because it tries to just use a glyph that isn’t there. What you have to do is, during renderering, scan along your glyphs until there is a new line, draw the glyphs up until the new line, then start again from just after the new line.

You can also implement alignment and word wrapping. To do this, you need to be able to measure the string, so here’s how you do that:

After a call to CGContextShowGlyphs, the current text position is updated and can be retrieved like this:

CGPoint EndPoint = CGContextGetTextPosition(UIGraphicsGetCurrentContext());

So EndPoint.x is the length of your string (assuming your initial text position was at 0, 0). You can prevent Quartz from actually doing any drawing while you’re measuring the string’s length by setting the text drawing mode to invisible:

CGContextSetTextDrawingMode(UIGraphicsGetCurrentContext(), kCGTextInvisible);

Remember to set your drawing mode and text position back to normal when you want to actually draw your text:

CGContextSetTextDrawingMode(UIGraphicsGetCurrentContext(), kCGTextFill);
 
// You can also set to the text colour to the UILabel's textColor property
CGContextSetFillColorWithColor(UIGraphicsGetCurrentContext(), self.textColor.CGColor);

Now that you have the text size, you can use the UILabel’s textAlignment property to determine how to align your text when you actually draw it. Word wrapping can be achieved using a standard word wrapping algorithm. Just keep drawing glyphs until EndPoint.x is greater than self.frame.size.width. Then you know you’ve exceeded the frame and need to word wrap. So then you can jump back to the previous word, reset the text position to 0, 0 and continue on. It’s best to store each line length during your measuring stage so that they can be used to align the text during drawing.

One problem I haven’t yet figured out is the height of a line. At the moment I’m just using FontSize * 1.2, which seems to work OK for the font I’ve tried this on. I’m sure there’s probably some better way to do it, but I haven’t looked into it too much.

You can use the measuring technique to automatically size the height of your custom UILabel, to prevent it from being clipped (seeing as how you can’t actually see your custom font in Interface Builder). I added a new function to my custom font label class to calculate the height of the word wrapped text. I then use the height to set the height of the frame. This does mean that I have to set the frame’s width, call the function then set the frame’s height to the returned value. It also means you have to make sure the graphics context is correctly set up during the heigh measuring function (which it probably won’t be if it’s called from outside the drawTextInRect function. The easiest way to do this is to create a temporary graphics context, like this:

CGSize ContextSize;
ContextSize.width = 480;
ContextSize.height = 320;
UIGraphicsBeginImageContext(ContextSize);
 
// Measure the string's height
 
.....
 
UIGraphicsEndImageContext();

So there you have it. That’s how I’ve got my custom font UILabels to be used.

The other awkward thing is a lot simpler. I didn’t realise how long that last one was going to be

The problem arises when you want to display a modal view controller straight after another one has been dismissed. It seems the best place to show the second one is in the viewDidDisappear function of the first UIViewController. However, calling presentModalViewController on the parent UIViewController from this function doesn’t work (nothing seems to happen). I’m guessing it’s because the modal view controller for the parent view controller is still pointing to the one that’s just disappeared, and that this gets cleaned up after viewDidDisappear is called, so any new modal view controller you set in viewDidDisappear is reset straight after the function returns (because the parent view controller is still in the process of cleaning up the first one). The solution is to use the performSelector function on the parent view controller with a delay of 0:

[self.parentViewController performSelector: @selector(myDisplayNextModalViewControllerFunction) withObject: nil afterDelay: 0];

The delay of 0 doesn’t mean that the selector is performed straight away. Because of the order of events in the run loop, the selector will be performed after the parent view controller has fully dismissed its modal view controller, so the next one will display fine.

Hope this helps