Archive for the ‘iPhone’ Tag

OpenGL ES: Batch Rendering on the iPhone

This one took me a while, simply because there was a LOT of research to do on my part. This is not going to be a tutorial post, per-se… but more so a “This is what I’ve found” and a request that someone take a look through it and see what I could have done better, and then let me know ! :)

Simply put, I was getting a few FPS problems with the development of my game, and thought I would come up with a way to batch all of my drawing into as few OpenGL calls as I could. I came across a few interesting tidbits, including a Stanford ‘iTunes U’ course (look that up in iTunes, its WELL worth viewing) Especially the one on OpenGL from Tim Omernick (Slide can be found HERE).

A copy of the code can be found at the google code repository, direct link to the TextureController is HERE. Well then, lets have a look at it!

The first thing that I attempted to do, was make a struct with the vertices, color information, and uv information. This is a result from Tim’s lecture and heavily influenced by his code. The hiccup was that I wanted to be able to batch based on the GLuint being drawn so I would only have to bind a texture once and then draw all vertices associated with that texture. I came up with the following solution:

struct Vertex
{
 short v[2];
 unsigned color;
 float uv[2];
};

struct VertexInfo
{
 Vertex vertex[MAX_VERTICES];
 int _vertexCount;
};

What will happen here, is VertexInfo will be stored in a map, while the Vertex struct houses all of the information that will be thrown at OpenGL to draw. MAX_VERTICES is defined at the top of the header file, and I really have not played around with it much so I am not sure how slow or fast it will be with a full game running. Currently its set for 100,000 but that was just a number I pulled out of nowhere :D I imagine it should be reduced.

The Map containing the vertex information looks like this;

typedef std::map<GLuint, VertexInfo> VertexMap;
VertexMap vertices;

You’ll see how to use this in a minute. My idea for this class was to sort of clone the way the SpriteBatch works from the XNA framework. This is another of my nods to how well this framework is put together, and how much I enjoy working with XNA. I wanted to be able to call a begin function to let the TextureController know if I plan to use blending (or any other parameter I may add, such as sorting), and then throw a bunch of stuff to draw using the Textures->draw functions provided. Each call to the Textures->draw function will take the texture to be drawn and any information needed (such as the location, source rectangle, color, etc) and pack that information into the VertexMap waiting to be thrown to OpenGL. Once all of my draw commands have been executed, a Textures->end() will initiate all drawing for the batch.

Keep in mind, is this the best way to put something like this together? Probably not.. although its my first time doing such an interesting task.. :) Lets see how it works!

NOTE: I will input breaks to make some comments… so if you want the full file, be sure to visit the code repository at code.google.com

void TextureController::draw( const Texture2D& texture, const Rectangle& destination,
 const Rectangle& source, const Color& color, const GLfloat depth )
{	

As you can see, we’re plugging in a few informational tidbits, but this is only one of the drawing commands that i’ve implemented. The simplest draw command, you only have to provide a texture and a destination rectangle… and “default” values will be put to fill in the blanks when calling this function.

 GLuint glid = texture.getId();

 //	if we don't have any vertices with the texture being drawn, create a
 //	vertex map for it.
 VertexMap::iterator it = vertices.find(glid);
 if (it == vertices.end())
 vertices[glid]._vertexCount = 0;		

 //	find all of the vertices we'll need for this sprite
 float topLeftX = destination.x;
 float topLeftY = destination.y;
 float topRightX = destination.x + destination.width;
 float topRightY = destination.y;
 float bottomLeftX = destination.x;
 float bottomLeftY = destination.y + destination.height;
 float bottomRightX = destination.x + destination.width;
 float bottomRightY = destination.y + destination.height;

The above section is interesting in that it will first find out if we’ve already batched a sprite using the texture. If we have, we’ll just add the vertices into that batch. Otherwise, we’ll create a new batch of vertices and start that new batch. Next, we find all of the vertices! This is done through the destination rectangle passed in. The destination rectangle is going to be the spritebox that the texture is drawn to. In other words, its your canvas and your texture is the paint.

 // Texture atlas
 float minUV[2];
 float maxUV[2];

 //	if the source rectangle of ZERO was passed in, it means the client want to just
 //	draw the texture as is.. otherwise, the client wishes to draw a portion of
 //	the rectangle
 if (source == Rectangle::ZERO())
 {
 float maxS = texture.getMaxS();
 float maxT = texture.getMaxT();
 float minS = 0;
 float minT = 0;

 minUV[0] = minS;
 minUV[1] = minT;
 maxUV[0] = maxS;
 maxUV[1] = maxT;
 }
 else
 {
 float minS = source.x / texture.getWidth();
 float minT = source.y / texture.getHeight();
 float maxS = source.width / texture.getWidth();
 float maxT = source.height / texture.getHeight();

 minUV[0] = minS;
 minUV[1] = minT;
 maxUV[0] = maxS;
 maxUV[1] = maxT;
 }

This section took me the longest to really figure out, because I had not done any research how Texture Atlas’s work. As I said, this was heavily influenced by Tim’s code and I really wanted to understand this section before I moved on. What we’re doing here, is if a blank rectangle is passed into the function (meaning the client didn’t specify a rectangle and therefore wishes to just use the texture ‘as is’) we’ll use the maxS and maxT coordinates for the TextureCoordinates. The way we find out what maxS and maxT are, is after the image goes through its modification to become a power of two texture (see my last article), maxS will become imageWidth / newTextureWidth. In other words
if the texture is passed into your game at 30 pixels by 30 pixels, it was re-sized by the Texture2D class to become 32 by 32. maxS will be 30 / 32, or 0.9375f. This value indicates that when using the default values, 93% of the image is drawn, while the remaining 7% of the image contains nothing more than padding in order to ensure it was a power of two texture.

What if we wanted to use a sub image, only draw a portion? This would be useful if we had several images on one texture. Lets say you have a texture with 2 frames of animation, both frames are 24 by 24. This means your texture is 48 pixels wide, by 24 pixels tall. If you only want to draw the last half of the texture (your “2nd” frame of animation) your source rectangle would be:

x=24, y=0, width=24, height=24
Meaning you’re starting 24 pixels into the picture, at the top pixel of the picture, and you’re going 24 pixels wide and 24 pixels high. This is going to be the sub-image you’re drawing.

In order to change these numbers into texture coordinates, we need to divide by the image width or height. For example, 24 / 48 is .5, so your texture coordinate for x is .5, then 0, then .5, and .5.

 //	Convert the colors into bytes
 unsigned char red = color.red * 255.0f;
 unsigned char green = color.green * 255.0f;
 unsigned char blue = color.blue * 255.0f;
 unsigned char shortAlpha = color.alpha * 255.0f;

 //	pack all of the color data bytes into an unsigned int
 unsigned _color = (shortAlpha << 24) | (blue << 16) | (green << 8) | (red << 0);

 // Triangle #1
 addVertex(glid, topLeftX, topLeftY, minUV&#91;0&#93;, minUV&#91;1&#93;, _color);
 addVertex(glid, topRightX, topRightY, maxUV&#91;0&#93;, minUV&#91;1&#93;, _color);
 addVertex(glid, bottomLeftX, bottomLeftY, minUV&#91;0&#93;, maxUV&#91;1&#93;, _color);

 // Triangle #2
 addVertex(glid, topRightX, topRightY, maxUV&#91;0&#93;, minUV&#91;1&#93;, _color);
 addVertex(glid, bottomLeftX, bottomLeftY, minUV&#91;0&#93;, maxUV&#91;1&#93;, _color);
 addVertex(glid, bottomRightX, bottomRightY, maxUV&#91;0&#93;, maxUV&#91;1&#93;, _color);
}
&#91;/sourcecode&#93;

Aah, bit packing... how do I love thee, let me count the ways! When I first learned how to manipulate bits of data, I asked myself "Why would this ever be useful?" ... guess I learned the hard way, that its a very necessary skill to have. I don't fully understand it as much as I would like to, but I do a little research on it every day.

What we're doing in the above code is taking the red / green / blue / alpha color value (which is passed in as a 'between 0 and 1' value), multiplying that by 255, and packing the bits into a single value called _color. Apparently, its a lot faster for OpenGL to use this data in this way, so hi ho, hi ho.. its off to pack we go!

&#91;sourcecode="cpp"&#93;
void TextureController::addVertex(GLuint glid, float x, float y, float uvx, float uvy, unsigned color)
{
 VertexInfo *vertexInfo = &vertices&#91;glid&#93;;
 Vertex *vert = &vertexInfo->vertex[vertexInfo->_vertexCount];
 vert->v[0] = x;
 vert->v[1] = y;
 vert->uv[0] = uvx;
 vert->uv[1] = uvy;
 vert->color = color;
 vertexInfo->_vertexCount++;
}

And packing we do! This is where the batch work is done. What we’re doing is passing in a single Vertex data (the x location, y location, texture coordinates, color, and the texture used) and packing it into the struct I showed you above. Once we do that, we increase the _vertexCount, so we’re keeping tabs on how many vertices we’re batching.

So.. thats how we batch, how do we render? Simple!

NOTE: Keep in mind, this is only a portion of the code. This function is called from the “end()” function I talked about eariler. end() will ensure that beginning was called, and then pass the buck to the render function.

void TextureController::renderToScreen()
{
 glPushMatrix();
 glMatrixMode(GL_MODELVIEW);

 //	Texture Blending fuctions
 if ( blendAdditive )
 {
 glEnable(GL_BLEND);
 glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
 }

 //	needed to draw textures using Texture2D
 glEnable(GL_TEXTURE_2D);		

 //	enables alpha for transparent textures
 //	I forget where I got these commands, iDevGames.net I think
 glAlphaFunc(GL_GREATER, 0.1f);
 glEnable(GL_ALPHA_TEST);

 //	Enable the various arrays used to draw texture to screen
 glEnableClientState(GL_VERTEX_ARRAY);
 glEnableClientState(GL_NORMAL_ARRAY);
 glEnableClientState(GL_TEXTURE_COORD_ARRAY);
 glEnableClientState(GL_COLOR_ARRAY);

 glLoadIdentity();

The above is just standard stuff to get ready for rendering. In fact, I think this was just cut / pasted from my Texture2D class. The real interesting part happens next!

 //	loop through all of the elements of the map and draw the vertices
 VertexMap::iterator it = vertices.begin();
 for (/* none */; it != vertices.end(); it++)
 {
 //	easy access to our data
 VertexInfo *vertexInfo = &it->second;
 Vertex *vert = vertexInfo->vertex;

 //	bind the texture for the following vertices
 bindTexture( (*it).first );

 //	throw everything to OpenGL
 glVertexPointer(2, GL_SHORT, sizeof(Vertex), &vert->v);
 glTexCoordPointer(2, GL_FLOAT, sizeof(Vertex), &vert->uv);
 glColorPointer(4, GL_UNSIGNED_BYTE, sizeof(Vertex), &vert->color);
 glDrawArrays(GL_TRIANGLES, 0, vertexInfo->_vertexCount);

 //	reset this batches vertex count
 vertexInfo->_vertexCount = 0;
 }

What we’re doing here is looping through every key (which is the GLuit of the texture, if you recall) binding that texture so that OpenGL knows which texture to draw with, and then throws all of the vertices and texture coordinates and all other info needed to render the batch. A few notes that some people might not know (I didn’t when I was researching this)

glVertexPointer(2, GL_SHORT, sizeof(Vertex), &vert->v);
the 2 means that there will be 2 vertices, and x and a y. This number could be a 3, if you’re also storing a z value. We will be using GL_SHORT (remember in the struct, all vertices are declared as short), and the interesting portion of this is the sizeof(Vertex). This is called a STRIDE, and basically tells OpenGL the distance between the data in memory. (I hope I explained that correctly!) The last value is the array of vertices!

glTexCoordPointer(2, GL_FLOAT, sizeof(Vertex), &vert->uv);
This is very similar to the above.. except we’re using different values. The 2 is referring to the fact that we have 2 points per vertex for the texture coordinates (an x and a y) but if you’re going to be using a z value, this number will be changed to 3. Remember, we are using floats for this (check the struct), and the STRIDE value stays the same. Then just pass it in the array of information.

glColorPointer(4, GL_UNSIGNED_BYTE, sizeof(Vertex), &vert->color);
Again, similar concept, except we did a few things differently with this. Remember our color scheme is 4 colors (red, green, blue, and alpha) but we packed all that information into a single value? We specify that via the GL_UNSIGNED_BYTE. otherwise, everything else remains similar.

glDrawArrays(GL_TRIANGLES, 0, vertexInfo->_vertexCount);
This is the reason we’re keeping track of how many vertices we have! What we’re doing here is telling OpenGL to draw the arrays using triangles, the 0 is referring to the starting index (obviously we’re going to be starting at index 0, just as if we were looping through the index ourselves), and how many elements are in the arrays.

What this will do, is put together the information in a single stream of information.. something like:

XY RGBA USUV, XY RGBA USUV, XY RGBA USUV
This is much more efficient for OpenGL to render, and therefore it will chew through the data and at much greater speeds than if you render your data once per texture. (ala, my old method)

now all thats left to do is clean up by disabling any states we enabled

 //	disable all the stuff we enabled eariler
 glDisableClientState(GL_VERTEX_ARRAY);
 glDisableClientState(GL_TEXTURE_COORD_ARRAY);
 glDisableClientState(GL_COLOR_ARRAY);
 glDisable( GL_BLEND );
 glDisable( GL_TEXTURE_2D );
 glDisable( GL_ALPHA_TEST );

 glPopMatrix();
}

and voila!

Again, this is my first pass at writing such a system.. and I am still learning the form of graphics programming. I urge you to pick up the code from the svn repository (http://code.google.com/p/djinnengine) and play around with it. If you find anything that I could do better, or things that may help me understand this process a little better, feel free to post for everyone to learn from!

Happy Coding everyone!

Advertisements

OpenGL ES Texture2D: Power of two

As most of you have figured out, OpenGL ES doesn’t like textures to be non power of two, and I really didn’t want to have to force all of my textures to be powers of two before loading them into my game. This presented me with a problem that had to be solved in-code.

To really understand texture mapping, especially if you’re doing iPhone development or OpenGL ES development in general, it is a good idea to visit Jeff’s blog on the subject located: HERE, and look up chapter 6 on Texture Mapping. I’ll wait, its a great read and should be glanced over at the very least!

Back? OKAY! So the problem is only powers of two can be used in OpenGL ES, so how do we convert our texture to a power of two? There are several ways to do this, but I chose to look at apples version of a texture file and learn from them.

They came up with the following to convert the width and height into a power of two:

//     Adjust the width and height to be a power of two
if( (_width != 1) && (_width & (_width - 1)) ) 
        {
                i = 1;
                while((sizeToFit ? 2 * i : i) < _width)
                        i *= 2;
                _width = i;
        }
        
        if( (_height != 1) && (_height & (_height - 1)) ) 
        {
                i = 1;
                while((sizeToFit ? 2 * i : i) < _height)
                        i *= 2;
                _height = i;
        }
&#91;/sourcecode&#93;

The first portion of the code will convert the texture to a power of 2. Since the texture will be stretched, and never shrunk, apple had to figure out a way  to shrink the texture if it became larger than the max texture size of 1024. The following code will do just that:

&#91;sourcecode="cpp"&#93;
        //      scale down an image greater than the max texture size
        while((_width > kMaxTextureSize) || (_height > kMaxTextureSize)) 
        {
                _width /= 2;
                _height /= 2;
                transform = CGAffineTransformScale(transform, 0.5, 0.5);
                imageSize.x *= 0.5;
                imageSize.y *= 0.5;
        }

the ‘transform’ is nothing more than a CGAffineTransform; in case you were confused with that. So, now that you’ve glanced over the code, you remember in the article where Jeff was talking about S and T coordinates? We’ll take care of those like this:

        _maxS = imageSize.x / (float)_width;
        _maxT = imageSize.y / (float)_height;

This will give us a number between 0 and 1, depending if the texture was re-sized or not. _maxS and _maxT will also be used in our textureCoordinates array for drawing the texture to screen. This should only render the portion of the texture that has any data, and not the padding we added to the texture.

While I am still learning OpenGL, I figured that a lot of people would be interested in the following solution.. especially if you did what I had, and had thrown out the Apple Texture2D file and re-wrote your own. Full source code to the Texture2D, or any other file within the D’Jinn Engine can be found HERE.

Hope this was informative! If anyone has any further information they would like to add, feel free!

Happy Coding Everyone!

D’Jinn Engine: Updates

Over the last few days I’ve been re-working a few of the OpenGL calls and a few classes in the D’Jinn Engine. The most notable change is removing the Texture2D class that apple provides, and instead loading up a Texture2D class of my own that uses the TextureController for memory management. In revamping the Textures from OpenGL, I was hopeful to figure out the problem I’ve been having with the Particle Emitter, and I have not been able to figure it out… but I’ll keep working!

The Emitters problem is documented in both the class file as well as issues on the SVN site.

Anyway, feel free to poke around and send me an email if you find anything that I could do better, or that could be re-structured better. I will start working on new extensions and making the “engine” an actual engine over the next few weeks.. especially now that the design for my game is starting to complete and I have a better idea of what I’ll need to add to the engine to make it work. After all, the D’Jinn Engine is a project of mine to help learn the in’s and out’s of C++ development, so send in that feedback!

Also of note, I obtained the 3.0 SDK and fixed the minor errors in the code that didn’t let you compile and run it under 3.0 OS. You should be able to now. Full list of changes can be found: HERE

Happy Coding everyone!
PS: D’Jinn Engine SVN: CLICK HERE

D’Jinn Engine: Open Sourced…

Is it ready for full time production? … eh, no…
Is it a fully function engine? … eh, no…
Will it aid in your thurst for knowledge?.. YEAH!

As you read yesterday, I’ve decided to put what I have of the D’Jinn Engine up on google code, for anyone to poke, pry, and have fun with. I will continue my trek to modify and improve the engine pretty much every day, but it is also free for anyone who also wishes to take what I have to use in their own project.

What is the catch? Simple… If you make any improvements, let us know about it! The iPhone and iPod Touch community is hungry for knowledge on game development, and could really use a few great resources. Will the D’Jinn Engine ever be a general enough resource for anyone to pick up and use? Probably not… but at least its there for the few of us who enjoy C++ enough to torture ourselves into making a game engine on the iPhone :)

I have spent some time working on the description and trying to comment the code as much as I could. As we speak, I am working on a texture controller class that will eliminate the need for the Texture2D from apple (and in the process, hopefully eliminate a nasty bug I introduced with the particle system…)

Remember, I will be working on this thing pretty much every day, if not every other day. Don’t expect to see a commit every day, but know that there are people making improvements to it. Dive in, have fun, learn a thing or two, teach me a thing or three… and feel free to join the discussion group if you have something interesting to share!

D’Jinn Engine: iPhone C++ 2D engine
http://code.google.com/p/djinnengine/

Happy Coding everyone!

C++ on the iPhone: Djinn Engine

EDIT: I would like to point out that below, when mentioning “Mike” … I forgot to plug his website.. whoops! In any rate, he has a few great tutorials (in video form) located: http://www.71squared.co.uk/ … HIGHLY recommend you check them out if you’re using Obj-C on the iPhone.

Hello everyone! I have been reading through your emails and appreciate all the letters. One question I kept asking myself with this project was “Do I want to make the engine open source?” My decision came apparent when I realized that this engine, although it will be used for my iPhone games, was first and foremost a learning experience for me and a tool that I used in order to become a better programmer.

So here I am, with a working copy of the Djinn Engine, and I have decided to make the project ‘open source.’ Before I upload the source to a SVN however, I want to ask the communities opinion on what they want to see?

The engine works, but it is crude. Currently in the engine is the following:

TestGame – I’ve been using this as a static unit testing for the engine

Actor System – Handles any actors in the game. Started by using the Angel Engine as template

Animation System – Animation Manager used for stopping, starting, and updating various animation playlists.

Game Screen Management – A C++ version of the Screen Controller tutorial from below.

Serializable objects – All objects (Characters, particle effects, etc) will be serialized in .dat files for dynamic loading. This way they do not need to be hard coded into the engine.

Input management (single touch only) – A C++ version of the input manager tutorial below.

Particle System – Using Mike’s tutorial as a starting point, dynamic particle system that includes a controller, effect, and various emitters for every particle effect. The one i currently have been using is “fire”

OpenAL Sound Support (have not put in OGG support yet, plan to) – Also using Mike’s tutorials as a staging point, this is an OpenAL sound engine that currently only works with sound effects… I want to add OGG support in the future.

File Management – pass in the asset name of a file, and a pointer to the object you wish to unserialize, and the file manager will take care of the rest.

Random Number Generation – … does just what it says it will do :)

Modified version of Apples Texture2D for C++ (will need to revamp this)

Math Utilities class (IE: Clamp, Min / Max, Abs, Lerp, etc etc)

and a couple of other things. Keep in mind, this is a 2D engine! So… iPhone community… We have a few choices before this thing goes Open Source. I will continue working on it, adding things that will meet my needs (keeping in mind, this will be the engine I am using for my iPhone Game) and I figure if I need a feature, maybe the community could use it as well. Should I just release it “as is” right now and continue working on it while you all can get your hands on it and modify it depending on what you need? Should I clean it up a bit, so its easier to understand when you’re reading through the code? or should I wait til the engine is pretty much done and release it then?

Let me know either via comment or email what you wish, and we’ll make it happen. I’ll have to work on some documentation, especially for the crude object serialization haha.. but that shouldn’t be too hard to do. Let me know what you think, and for the few of us who actually enjoy C++ on the iPhone, lets make it happen!

C++ on the iPhone: Test Driven Development

I have been learning quite a few development strategies as of late, and the newest one that I’ve taken a peek into is Test Driven Development (TDD), or Unit Testing. The idea behind TDD and Unit Testing is to split up your problems into small, easily manageable problems rather than having to design everything from the get go, and living with any or all of your mistakes for the rest of the project. TDD is a very complex topic and usually requires the use of various frameworks for dynamic unit tests, but I’ll be focusing on the ‘beginning’ method of TDD, static unit tests.

How do we start? Well in my current engine, what I did was write a class called “TestGame.cpp” which was a singleton class that housed various methods for testing the game. In that class, I would write functions to test a particular class I would be creating, or an entire game loop to test the logic of a class without having to construct a game world for our object to live in. Inside the TestGame class there is a function called ‘startTesting()’ which will call anything you wish to test. Lets write a sample test to give you an idea on the very basics of what I’m doing.

//This function is public, and able to be called when you obtain the instance
//of the TestGame class. We will start every test from this function, and keep
//it kind of like a list. Whenever an aspect needs to be changed, for example
//with the actor class, we can simply uncomment the 'testActorClass()' line 
//to ensure it still passes all of our tests. 
void TestGame startTesting()
{
	testActorClass();
}

//This function, however... is private and unable to be called by anything
//outside the "TestGame" class, and should only be called by the 'startTesting()'
//function.
void testActorClass()
{
	Actor *act = new Actor();
	string testString;
	float testFloat;
	
	act->setAlpha( .50f );
	testFloat = act->getAlpha();
	
	//	identities are unique and assigned when the object is constructed.. Calling this function
	//	should not change the identity
	act->setIdentity( "newIdentity" ); 
	testString = act->getIdentity(); //should still be "Actor_#"

	act->setName( "Werewolf ");
	testString = act->getName();//should be "Werewolf"

	act->setPosition( Vector2::ZERO() );
	testString = act->getPosition();//should be 0,0

	act->setSize( Vector2(32, 32) );
	testString = act->getSize();//should be 32, 32

	act->update( .003f );
}

Now if I were to compile this code, it would spit out a bunch of errors. “Set Name? .. Get Identity? I don’t know how to do that!” and that’s the point! These functions have not been written yet. The basic idea is to construct what you want your actor class to do, and then write the code to DO it. The next step is to write JUST enough code to get the project to compile, so… to the actor class we go! Quite literally, all we’ll be doing in the next step is to write the skeleton functions like such (NOTE: The various helper classes like Vector2 have been written and added to the engine, they are already created and have already been tested using this approach and do not come ‘standard’ in C++ (or Obj-C as far as I know);

//in the Actor.h file
public:
	bool setIdentity( const string &value );
	string getIdentity() const { return identity; }

	bool setName( const string &value );
	string getName() const { return name; }

	bool setPosition( const Vector2 &value );
	Vector2* getPosition() { return position; }

	bool setSize( const Vector2 &value );
	Vector2* getSize() const { return size; }

	bool setAlpha( const float value );
	float getAlpha() const { return alpha; }

	virtual void update( const float deltaTime );
protected:
	string identity;
	string name;
	Vector2 *position;
	Vector2 *size;
	float alpha;
//in the Actor.cpp file
bool Actor::setIdentity( const string &value )
{
}

bool Actor::setName( const string &value )
{
}

bool Actor::setPosition( const Vector2 &value )
{
}

bool Actor::setSize( const Vector2 &value )
{
}

bool Actor::setAlpha( const float value )
{
}

void Actor::update( const float deltaTime )
{
}

This code should now compile and run, even though it doesn’t do anything. Well we know what we want to do, and we now have a skeleton to do it… so we should get going on writing the code!

For example, we know that we want the identity of the actor to be unique, and that the setIdentity function should only set the string if it currently does not have an identity.. so since this is going to be the most difficult function to write, lets do that one real quick.

bool Actor::setIdentity( const string &value )
{
	//	if the identity has already been set, do not
	//	re-set the identity. Object must be destroyed
	//	and re-created to reset an identity. 
	if ( identity.length() != 0)
	{
		return false;
	}
	
	//	if the identity has not been set, set it
	//	and return true
	identity = value;
	return true;
}

really, thats it. The actor doesn’t know if its identity is unique, nor does it know how to obtain a unique identity. It just says “Okay, I don’t have an identity right now, so I’ll take this one and make it my own!” The idea is the actor class exists on its own, and functions as its own data. To obtain a unique identity and to keep track of all actors in the game world, we will use an ActorController (remember that pesky thing called the Model / View / Controller? ) The Actor class is the data (model) while the Controller will manage that data and when needed, present it to the view for rendering.. but that is a topic for another post.

The last thing we should do is COMMENT COMMENT COMMENT! I am a big fan of commenting my code, and documenting not only what the function does but why its implemented the way it is. If you ever look over your code 3 months down the line, you’ll say to yourself “I didn’t write this… what was I thinking?!” … well if you commented your code, you’d know! its a good habit to get into, and if you look at my Screen Controller from a few posts back, you’ll notice just how much I comment.

So that is all for today. Test Driven Development is a HUGE area, and this is just the very very basics of how it can be done. Once you get into the frameworks, it can be pretty complex, but very much worth the effort.

Happy coding everyone!

iPhone Gaming Framework: ObjC Template

Well, everyone… the time has finally come! Yesterday I got an email in my mailbox about a really interesting website that linked to my two blog posts about iPhone development, the Parsing XML files on the iPhone, and the iPhone Gaming Framework tutorials.

Best Universities: 100 free courses tutorials for aspiring iPhone app developers

While looking through the wealth of information on those articles, I found a really neat one.. how to create a project template! This is something I’ve wanted to do for everyone interested in getting started with iPhone game development, but have not had time to really research it on my own.

So, fast forward a few hours, I made a few changes to the ObjC framework and stored it into a template! I would like to first note, that this framework most likely has a few bugs in it. I tried to track down what I could, but I’m sure I didn’t get them all. My current efforts are more directed towards my C++ Djinn Engine, so this project took a back seat, but I felt a lot of people could really use this to jumpstart their efforts.

Anyway, if you choose to use this template, be sure to mail me with your finished projects or development blogs. I always love to see what people are up to! If you’ve used XNA at all, you’ll recognize the Screen Controller and be comfortable with how it works.

If you have any questions, feel free to comment ( so others can help answer and benefit from the questions as well )

How to install the template!
Step 1) Download the zip file located HERE

Step 2) Navigate to ~library/Application Support/Developer/Shared/Xcode/ and create the following folders: Project Templates/iPhone Templates/ .. Your final directory structure should look like ~library/Application Support/Developer/Shared/Xcode/Project Templates/iPhone Templates/

Step 3) Unzip the OpenGL Screen Controller.zip into your iPhone Templates directory. This will add the OpenGL Screen Controller folder and project template. Your new directory structure will look like:
~library/Application Support/Developer/Shared/Xcode/Project Templates/iPhone Templates/OpenGL Screen Controller/(project files here)

Step 4)Open up XCode, create new project, and you’ll see on the left side “User Templates” with a sub-category “iPhone Templates,” clicking on that will bring up your Screen Controller template.

Look at the code, see how its done. Build and run it, and if you click “Level Play” it should transition to a new screen (the gameplay screen) .. click anywhere else in the frame while on the gameplay screen, and it will remove that screen from the screen controller and go back to the title screen. Trace the code, see how it does it, and start playing around.

C++ on the iPhone

C++ is an interesting language, and so is Objective-C. Since I have chosen to go back to college to get my degree in Computer Science, I thought it would be beneficial to do as much of my projects in C++ and not split up the languages (C#, Objective-C, C++, etc) so I’ve converted my projects to C++ code. What does this mean for iPhone development though? Its actually quite interesting.

Think of it this way, if you were to do EVERYTHING in a C or C++ style syntax, how would you load and bind a texture in OpenGL? What about converting the screen manager (that tutorial posted below) to C++? What about capturing the touches from the screen and filtering them to the InputManager class? It really is quite interesting.

So, the ‘Djinn Engine’ was born and is really just a pet project of mine for now. As we discuss something in class, and I finish the classes project for that section (which usually doesn’t take me long) I will stat working on those features in the engine. Its an interesting setup, and will take me longer to get a “product” on the app store, but I enjoy it more and am learning a great deal more about how things are working under the hood, and that is something I think everyone should take a look at.

I’ll make some posts soon about the progress of the engine and any projects associated with it. I have not announced anything that I am working on, but there are a few projects that are going to be coming in the next year or so. Exciting? You betcha!

iPhone Gaming Framework: Amendment

Its been great to see a lot of you take apart the code and really see what you can do! There have been several people who have been in contacts with me via email, trying to get everything up and running.. but as you may have known, there are a few things missing from the tutorials. This is the amendment, going to patch up the final few things to get you back on track!

First thing is in the GLView.m file. We have a screen manager, but we are not telling the game to update or draw through the screen manager. Lets fix that! Go into your -(void)drawView method, and right below the glBindFrameBufferOES() call, you should have a [controller drawView:self]; … we’re going to change that to the following:

	//
	//	Update the view
	//
	[controller updateView:self WithTime:(float)[animationTimer timeInterval]];	
	//
	//	Draw the view
	//
	[controller drawView:self WithTime:(float)[animationTimer timeInterval]];

You’re going to call the controllers updateView and drawView methods, and pass in a time interval from the animationTimer. Now the controller will update and draw the game screens!

Secondly, There were a few people who never added a blankTexture to their project. I suggest opening an image editor, creating a black image called “blankTexture.png” and drag it into your resources file. You’ll notice, in the loadContent method, the screen manager allocates memory for the input manager, sets landscape mode, and then right after that loads in a blankTexture.png. If it doesn’t have one, it can’t load it.

Next amendment is more of a “clean up” since I didn’t fully understand how the retain / release system worked (Hey! i’m still a new mac developer too! :D ) In your addScreen method, you don’t need a [screen retain] since adding it to the screens NSMutableArray will retain the object. Likewise in the releaseScreen method, you’ll need to take out the [screen release] unless you like having your game crash when releasing a screen that has already been deallocated :)

With everything working, you’ll notice that your textures are being drawn “upside down” … well since we changed the way the coordinate system worked, and Apples “Texture2D” class works with the previous coordinate system, that will need to be changed. There are a few ways to do this; some people who really know their OpenGL suggested to flip the image before binding it.. the approach I took was just to adjust the vertices in the Texture2D draw methods.

This goes into your “drawAtpoint” method, comment out the current array:

	//
	//	Modified by Craig Giles to flip the texture upside down while using my coord system
	//    
	GLfloat		vertices[] = 
	{	
		-width / 2 + point.x,	height / 2 + point.y,	0.0,
		width / 2 + point.x,	height / 2 + point.y,	0.0, 
		-width / 2 + point.x,	-height / 2 + point.y,	0.0,
		width / 2 + point.x,	-height / 2 + point.y,	0.0
		
	};

This goes into your “drawAtRect” method, comment out the current array:

	//
	//	Modified by Craig Giles to flip the texture upside down while using my coord system
	//
	GLfloat	vertices[] = 
	{
		rect.origin.x,							rect.origin.y + rect.size.height,		0.0,
		rect.origin.x + rect.size.width,		rect.origin.y + rect.size.height,		0.0, 
		rect.origin.x,							rect.origin.y,							0.0,
		rect.origin.x + rect.size.width,		rect.origin.y,							0.0
		
	};

I think thats all the changes. Thanks again for everyones feedback on the last few writeups! I am looking over a few documents sent to me about templates, so I can release this as a starting template. Will let everyone know more when I can! As always, feel free to email me or post a comment if you need help with something.

iPhone Gaming Framework: Stage 2 Tutorial

NOTE:: I am still looking for a good way to turn this into a template and release it for anyone wishing to install this for the base of their game. If you know of a good resource for doing so, please let me know, as google has been fairly unhelpful as of this point.

Welcome back everyone! Did you all finish Stage 1 of the tutorial? If not, please do that, as we are going to be building off stage 1 in our next tutorial. Stage 1 can be found HERE

Okay, now that stage 1 is done, you have a working screen management system… except you don’t have an input manager to help you with input management! Remember my note from previous tutorials, there are MANY solutions to a problem, and this is just one of many. Our input class works as follows: If a touch is detected, the GLViewController will send a message to the input manager, and that message will be stored in an input “state” called “queryState.” Before the view controller updates any of the game screens, it will send a message to the input manager to update the input, and this is when the input is changed from the “queryState” to “currentState” and the current state is then set to the previous state.

So lets look at the code, yeah? First the InputManager.h file

//	
//	The input manager is a helper class that houses any input
//	that can be obtained by the game engine. As a touch is detected
//	on screen, it will send a message to the input helper. The input
//	helper will then hold onto that message and filter it into the 
//	current state on the next game loop. The current state is moved
//	to the previous state, and any incoming touches are then put
//	back into the query state, waiting to be updated.
//
//	This method of updating lets the game filter updates to the top-most
//	game screen and not have to worry about un-focused screens handling
//	input that was not intended for them.
//
//  Created by Craig Giles on 1/3/09.
//

#import <Foundation/Foundation.h>
#import "InputState.h"

@interface InputManager : NSObject 
{	
@private
	bool isLandscape;
	InputState *currentState;
	InputState *previousState;
	InputState *queryState;
}

@property (nonatomic, readwrite) bool isLandscape;
@property (nonatomic, readonly) InputState *currentState;
@property (nonatomic, readonly) InputState *previousState;

- (void) update:(float)deltaTime;

//
//	Touch events
//
- (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer;
- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer;
- (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer;
- (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view WithTimer:(NSTimer *)deltaTimer;

//
//	Helper Methods
//
- (void) update:(float)deltaTime;
- (bool) isButtonPressed:(CGRect)rect;
- (bool) isButtonHeld:(CGRect)rect;
- (void) convertCoordinatesToLandscape;

//
//	Class methods
//
+ (bool) doesRectangle:(CGRect)rect ContainPoint:(CGPoint)point;

@end

And the .m file

//	
//	The input manager is a helper class that houses any input
//	that can be obtained by the game engine. As a touch is detected
//	on screen, it will send a message to the input helper. The input
//	helper will then hold onto that message and filter it into the 
//	current state on the next game loop. The current state is moved
//	to the previous state, and any incoming touches are then put
//	back into the query state, waiting to be updated.
//
//	This method of updating lets the game filter updates to the top-most
//	game screen and not have to worry about un-focused screens handling
//	input that was not intended for them.
//
//  Created by Craig Giles on 1/3/09.
//

#import "InputManager.h"


@implementation InputManager

//
//	Getters / Setters
//
@synthesize isLandscape;
@synthesize currentState;
@synthesize previousState;

//
//	Initialization
//
- (id) init
{
	self = [super init];
	if (self != nil) 
	{
		//
		//	Allocate memory for all of the possible states
		//
		currentState = [[InputState alloc] init];
		previousState = [[InputState alloc] init];
		queryState = [[InputState alloc] init];
		
		//
		//	Set the initial coords for the touch locations.
		//
		currentState.touchLocation = CGPointMake(0, 0);
		previousState.touchLocation = CGPointMake(0, 0);
		queryState.touchLocation = CGPointMake(0, 0);
	}
	return self;
}

//
//	Deallocation
//
- (void) dealloc
{
	[currentState release];
	[previousState release];
	[queryState release];
	[super dealloc];
}

//
//	Update the input manager. This method will take the
//	values in updateState and apply them to the current state. 
//	in essence, this method will "query" the current state
//
- (void) update:(float)deltaTime
{
	//	Sets previous state to current state
	previousState.isBeingTouched = currentState.isBeingTouched;
	previousState.touchLocation = currentState.touchLocation;
	
	//	Sets the current state to the query state
	currentState.isBeingTouched = queryState.isBeingTouched;
	currentState.touchLocation = queryState.touchLocation;
	
	//	converts the coordinate system if the game is in landscape mode
	[self convertCoordinatesToLandscape];
}
	
//
//	Touch events
//
//	These events are filtered into the input manager as they occur.
//	Since we want to control how our input, we are going to use a 
//	queryState as the "Live" state, while our current and previous
//	states are updated every loop. For this reason, we are always
//	modifying the queryState when these touch events are detected,
//	and the current state is only modified on [self update:deltaTime];
//
- (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer
{		
	queryState.isBeingTouched = YES;
	queryState.touchLocation = [[touches anyObject] locationInView:view];
}

- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer
{	
	queryState.isBeingTouched = YES;
	queryState.touchLocation = [[touches anyObject] locationInView:view];
}

- (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view  WithTimer:(NSTimer *)deltaTimer
{	
	queryState.isBeingTouched = NO;
	queryState.touchLocation = [[touches anyObject] locationInView:view];
}

- (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event InView:(UIView *)view WithTimer:(NSTimer *)deltaTimer
{
	queryState.isBeingTouched = NO;
}

//
//	When in landscape mode, the touch screen still records input
//	as if it were in portrait mode. To get around this, if we
//	are writing a game in landscape we need to adjust the coordinate
//	system on the touchscreen to match that of our world.
//
- (void) convertCoordinatesToLandscape
{
	//	If we are not in landscape mode, don't convert anything
	if ( !isLandscape )
		return;
	
	//	Otherwise, we will need to take the current touch location
	//	swap the x and y values (since in landscape, the portrait
	//	coordinate system means x will point up / down instead of
	//	left / right) and move the y position to match our origin 
	//	point of (0,0) in the upper left corner. 
	int x = currentState.touchLocation.y;
	int y = (currentState.touchLocation.x - 320);
	
	//	make sure we take the absolute value of y, since if we didn't
	//	y would always be a negative number.
	y = abs(y);
	
	//	Since we were converting the current state, we need to update
	//	the current touch location
	currentState.touchLocation = CGPointMake( x, y );
}

//
//	Looks at the previous state, and the current state to determine
//	weather or not the button (rectangle) was just pressed and released.
//
- (bool) isButtonPressed:(CGRect)rect
{
	//
	//	If the current state is not being touched
	//	and the previous state is being touched, the
	//	user just released their touch. This is 
	//	personal preference really, But i've found with
	//	my XNA programming, that its better to detect if
	//	a button was just released rather than if it was
	//	just pressed in when determining a button press.
	//	
	if ( !currentState.isBeingTouched &&
		 previousState.isBeingTouched )
	{
		
		return 	[InputManager doesRectangle:rect ContainPoint:currentState.touchLocation];
	}
	
	return NO;
}

//
//	Looks at the previous state, and the current state to determine
//	weather or not the button (rectangle) is being held down.
//
- (bool) isButtonHeld:(CGRect)rect
{
	//
	//	If the current state and the previous states
	//	are being touched, the user is holding their 
	//	touch on the screen.
	//	
	if ( currentState.isBeingTouched &&
		 previousState.isBeingTouched )
	{
		return 	[InputManager doesRectangle:rect ContainPoint:currentState.touchLocation];
	}
	
	return NO;
}

//
//	Helper method for determining if a rectangle contains a point.
//	Unsure if this will stay in the input helper or be moved to some
//	sort of "RectangleHelper" class in the future, but for now this
//	is a good spot for it. Remember, this works with our current coord
//	system. If your engine uses a different coord system (IE: (0,0) is at
//	the bottom left of the screen) you'll need to modify this method.
//
+ (bool) doesRectangle:(CGRect)rect ContainPoint:(CGPoint)point
{
	//
	//	If the rectangle contains the given point, return YES
	//	Otherwise, the point is outside the rectangle, return NO
	//	
	if (point.x > rect.origin.x &&
		point.x < rect.origin.x + rect.size.width &&
		point.y > rect.origin.y &&
		point.y < rect.origin.y + rect.size.height)
	{
		return YES;
	}
	
	return NO;
}

@end
&#91;/sourcecode&#93;

InputState just contains 2 values, and I have chosen to set them as the following:

&#91;sourcecode language="cpp"&#93;
#import <Foundation/Foundation.h>

@interface InputState : NSObject 
{
	bool isBeingTouched;
	CGPoint touchLocation;
}

@property (nonatomic, readwrite) bool isBeingTouched;
@property (nonatomic, readwrite) CGPoint touchLocation;

@end

//
//  Implementation of InputState
//
@implementation InputState

@synthesize isBeingTouched;
@synthesize touchLocation;

- (id) init
{
	self = [super init];
	if (self != nil) {
		isBeingTouched = NO;
		touchLocation = CGPointMake(0, 0);
	}
	return self;
}

@end

It should be a good time to point out, that the input manager changes the coordinates of the actual touch, depending on if you’re playing your game in landscape mode or normal mode. One of the problems I was having, before I realized what was really happening, was my coordinates for the touch screen and coordinates for the game world were different. For example, my touch screen coordinates, if held landscape, (0,0) was in the lower left corner, while in the world coordinates, (0,0) was in the upper left corner. This gave me problems, as you can imagine.

In order to change this, I wrote a method that will convert the coordinates system if the screen is detected in landscape mode. It should be pointed out, that if you’re using a different origin point for your world (IE: Lower left corner instead of upper left) you’re conversions will have to be done differently.

Another method that is currently in the input manager class, is the [self doesRectangle:rect ContainPoint:touchLocation]; Inside this method, you’ll see that both current and previous states are being used in order to detect if a touch is being “touched” or “held.” This can be done differently, but the way I’ve chosen to implement it, is as follows;

if the button was just RELEASED (current state is not pressed, but previous state was) than the button was just “pressed.”

This is important to note, because it means if the user touches the screen, and holds their finger down, it won’t register as a “button press” until they release their finger. Some people prefer to do the opposite, meaning if the current state was just pressed and the previous state was un-pressed. Use what you feel comfortable with.

So now all we need to do is add a game screen or two, right? Well, I told you that I would help you get up a paused screen. This will help you learn how to get any sort of game screen up and running. First, lets take a look at the PausedScreen.h file

//
//	The paused screen is just an overlay popup screen that is
//	displayed to the user when the game is paused.
//
//  Created by Craig Giles on 1/5/09.
//

#import <Foundation/Foundation.h>

#import "GameScreen.h"
#import "InputManager.h"
#import "Texture2D.h"

@interface PausedScreen : GameScreen 
{
	Texture2D *pausedText;
	double alphaValue;
}

@property (nonatomic, retain) Texture2D *pausedText;

- (void) loadContent;
- (void) unloadContent;

- (void) handleInput:(InputManager *)input;
- (void) update:(float)deltaTime	OtherScreenHasFocus:(bool)otherFocus	CoveredByOtherScreen:(bool)coveredByOtherScreen;
- (void) draw:(float)deltaTime;

@end

If you notice, several of these methods are in “GameScreen.h” right? You’ll also notice the LACK of touch event classes. All input is handled by the input manager, and will be called from the view controller (the [self handleInput:input] method) Aah now you are getting why I went the touch manager route instead of re-writing every single “touchEvent” method in each game screen!

There are several methods that every game screen needs in order to function properly. It will need a loadContent / unloadContent methods, handleInput method, and the update / draw methods. Also keep in mind, every game screen will need to call the [super update:deltaTime…], and every screen (other than the paused screen, which is a popup screen) will need to call the [super draw:deltaTime]; within its draw method.

So now you have the basics of the game screen, let me show you the .m file.

//
//	The paused screen is just an overlay popup screen that is
//	displayed to the user when the game is paused.
//
//  Created by Craig Giles on 1/5/09.
//

#import "PausedScreen.h"


@implementation PausedScreen

@synthesize pausedText;

//
//	Initialize the pause menu screen
//
- (id) init
{
	self = [super init];
	if (self != nil) 
	{
		//	flag that there is no need for the game to transition
		//	off when the pause menu is on top of it
		self.isPopup = YES;
		
	}
	return self;
}

//
//	Load all content associated with the paused screen
//
- (void) loadContent
{
	//
	//	Since this is a popup screen, we will over-ride the 
	//	view controllers transition time and set this to instantly
	//	transition on and off.
	//
	self.transitionOnTime = 0;
	self.transitionOffTime = 0;
	
	//	set the paused text
	pausedText = [[Texture2D alloc] initWithString:@"Paused\nTap screen to unpause"
										dimensions:CGSizeMake(self.viewport.size.width, self.viewport.size.height)
										 alignment:UITextAlignmentCenter
										  fontName:@"Zapfino"
										  fontSize:32];
	
	//	The alpha value of the background. below 
	//	the paused text.
	alphaValue = 0.75f;
}

- (void) unloadContent
{
	//TODO: all unload content goes here
	[pausedText release];
	[super unloadContent];
}


- (void) handleInput:(InputManager *)input
{
	//	If the 'tap here to resume' button was pressed
	//	resume game
	if ([input isButtonPressed:self.viewport])
	{
		[self exitScreen];
	}
}

- (void) update:(float)deltaTime	OtherScreenHasFocus:(bool)otherFocus	CoveredByOtherScreen:(bool)coveredByOtherScreen
{
	//TODO: Update logic goes here
	
	//	Update the base class
	[super update:deltaTime OtherScreenHasFocus:otherFocus CoveredByOtherScreen:coveredByOtherScreen];
}

- (void) draw:(float)deltaTime
{	
	//	Darken the screen to alert the player that it has been paused
	[self.controller fadeBackBufferToBlack:alphaValue];
	
	[pausedText drawInRect:CGRectMake(self.viewport.size.width / 4, 
									  self.viewport.size.height / 4,
									  self.viewport.size.width / 2,
									  self.viewport.size.height / 2)];
}
@end

One thing to take note, since the PausedScreen is a popup screen, it has overwritten the transition on and transition off values sent to it by the view controller. Any game screen can do the same, for example if you are transitioning to a screen that you’ve made your own custom transition, turn the view controllers transition off and let the screen transition itself. (IE: a battle screen.)

So there you have it! I don’t remember if textures are drawing upside down with this coord system, but if they are, all you have to do is edit the Texture2D.m file to fix that. If you don’t know how, send me an email and I’ll show you how I did it, but there are several ways of doing it.

I hope you enjoyed my heavily commented code for the screen manager, input manager, and game screen classes. This should give you the basic knowledge to get up and running with your own iPhone OpenGL applications. If you found these useful, let me know and I’ll write up some more when I have the time. I’m still learning all of this myself, but sharing my knowledge will lead to more interesting games for everyone! Keep in mind these are very basic systems and can be heavily expanded on by creative programmers. Can’t wait to see what you guys come up with!

Happy coding all!