Due to many emails I have been received on the last months, I decide to create a single article to explain a little bit about the Singleton classes (also known as Singleton Pattern). I’ll focus here on Objective-C and Cocoa approach, however I’ll talk a little bit generally, so you can take the concept to other languages as well.

Let’s start!

Just Give me the Code!

Ok, ok. For who of you that just want the final code without protraction, here is it, you can choose a Xcode template or the pure code:

Xcode template (Xcode 4)

A cool template for Xcode 4 that I created to use over my working machines.

1. Download the zipped file bellow.
2. Unzip and copy the “db-in” folder to “/Library/Developer/Xcode/Templates/File Templates”
3. Open an Xcode project and try to add a new file. You will see a category called “db-in” on the left side, under the iOS platform.

Download now
Xcode Singleton Class template
40kb

Pure code

Here is the code for your header and source files:

@interface MySingleton : NSObject

+ (MySingleton *) instance;

@end

@interface MySingleton()

// Make any initialization of your class.
- (id) initSingleton;

@end

@implementation MySingleton

- (id) initSingleton
{
	if ((self = [super init]))
	{
		// Initialization code here.
	}

	return self;
}

+ (MySingleton *) instance
{
	// Persistent instance.
	static MySingleton *_default = nil;

	// Small optimization to avoid wasting time after the
	// singleton being initialized.
	if (_default != nil)
	{
		return _default;
	}

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_4_0
	// Allocates once with Grand Central Dispatch (GCD) routine.
	// It's thread safe.
	static dispatch_once_t safer;
	dispatch_once(&safer, ^(void)
				  {
					  _default = [[MySingleton alloc] initSingleton];
				  });
#else
	// Allocates once using the old approach, it's slower.
	// It's thread safe.
	@synchronized([MySingleton class])
	{
		// The synchronized instruction will make sure,
		// that only one thread will access this point at a time.
		if (_default == nil)
		{
			_default = [[MySingleton alloc] initSingleton];
		}
	}
#endif
	return _default;
}

- (id) retain
{
	return self;
}

- (oneway void) release
{
	// Does nothing here.
}

- (id) autorelease
{
	return self;
}

- (NSUInteger) retainCount
{
    return INT32_MAX;
}

@end

At a glance

First off, Singleton is a Design Patterns, I know you know some patterns and also use some of them every day in your works. Like MVC (Model View Controller) which all of us use to create our App in Xcode, or also the Delegate Pattern, which Cocoa framework uses largely. So the Singleton is one of those patterns. There are hundreds of patterns, if you want to learn more about Design Patterns I suggest you this book:
http://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612

OK, now about Singleton Pattern. It’s simple the concept of instantiate (allocate the necessary memory) for a class once and share this instance with all other classes/functions that need it, making at this form, a single point of access.

There are many discussion about the Singleton, many criticisms and many enthusiasm. In my humble opinion, the Singleton Pattern is very useful to control/manage some global data. Like the user account, for example, specially when some data need a special treatment, like user imagem data.

Anyway, my objective here is just to show you how to create a real Singleton class, using the minimum code as possible and make it thread-safe. Remember that in Objective-C multithreading is always something that we must be aware and think about.

Coding the concept

In theory the code is very simple, instead of allocate and initialize the class, we just call a class method that returns the singleton instance. We can use this approach through all our application:

// Inside a ClassA, for example.
MySingleton *foo = [MySingleton instance];
[foo setSomeValue:1];

// Inside a ClassB, for example.
MySingleton *foo = [MySingleton instance];
[foo someValue]; // gets the value that was set on ClassA.

It’s important to remember that a singleton class SHOULDN’T BE RELEASED! Using the Cocoa logic, when you call “instance” you are not allocating nor copying any memory, so you shouldn’t release it.

Well, but the memory must be allocated for someone, right? Yes, the memory will be allocated and controlled by the “instance” method. Let’s talk about the singleton lock.

Singleton Lock

We create a kind of lock to make sure our instance will be initialized only once. Like this:

+ (MySingleton *) instance
{
	// Persistent instance.
	static MySingleton *_default = nil;

	if (_default == nil)
	{
		_default = [[MySingleton alloc] init];
	}

	return _default;
}

This code will work for 99,9% of the time for ALL kind of languages. However, there is a rare kind of situation which this code will fail. We’re talking about the multithreading behavior where two threads try to access the singleton instance AND the singleton is not initialized yet.

In a very rare situation, two threads can try to initialize a singleton at the same time.

Notice that initializing a class is something very fast, could be done in one or two microseconds, however for a multithreading application, this could be time enough to cause a redundant instantiation. As the singleton, usually, is never deallocated, the double memory allocation will represent a leak.

To solve this problem, all that we need is to make sure our singleton lock be thread-safe, that means, only one thread can make the initialization process. At this point, with Objective-C we have many options, let’s see the best one.

Thread Safe

The best and faster approach is using the GCD (Grand Central Dispatch). However the GCD is not available for all iOS versions, just for iOS 4 or later. So we must think in a solution that fits good for all. The “@synchronized” instruction is something that works for all iOS versions, it creates a kind of funnel/queue in which only one thread can run at a time.

The problem with “@synchronized” is that it’s very slow and could make threads run at a synchronized way. So, to avoid unnecessarily wasting time with the @synchronized, let’s create a way to make the things run faster after the singleton being initialized:

+ (MySingleton *) instance
{
	// Persistent instance.
	static MySingleton *_default = nil;

	// Small optimization to avoid wasting time after the
	// singleton being initialized.
	if (_default != nil)
	{
		return _default;
	}

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_4_0
	// Allocates once with Grand Central Dispatch (GCD) routine.
	// It's thread safe.
	static dispatch_once_t safer;
	dispatch_once(&safer, ^(void)
				  {
					  _default = [[MySingleton alloc] init];
					  // private initialization goes here.
				  });
#else
	// Allocates once using the old approach, it's slower.
	// It's thread safe.
	@synchronized([MySingleton class])
	{
		// The synchronized instruction will make sure,
		// that only one thread will access this point at a time.
		if (_default == nil)
		{
			_default = [[MySingleton alloc] init];
			// private initialization goes here.
		}
	}
#endif
	return _default;
}
@end

Notice that the “if (_default != nil)” is a single check, that runs very very fast and can avoid our code of spending time with unnecessary checks. About the GCD and blocks, it’s a simple piece of code that makes the same thing as the code without GCD. The only difference is that the GCD approach uses the special data type “dispatch_once_t” (a kind of BOOL) to check if the code have been executed before.

If you want more information about GCD and the blocks, here is it:
http://developer.apple.com/library/ios/#documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html
http://developer.apple.com/library/ios/#documentation/Performance/Reference/GCD_libdispatch_Ref/Reference/reference.html
http://developer.apple.com/library/ios/#featuredarticles/Short_Practical_Guide_Blocks/_index.html

Final adjustments

OK, we’re almost done. Now, just to make sure that any other class (including classes from Cocoa framework) will not change the retain count of our singleton class, we can override some methods:

- (id) retain
{
	return self;
}

- (oneway void) release
{
	// Does nothing here.
}

- (id) autorelease
{
	return self;
}

- (NSUInteger) retainCount
{
    return INT32_MAX;
}

The dealloc method is not necessary, because the singleton will never be deallocated. But remember to release and retain the memory for internal variables, by the way this is why @property and @synthesize exist.

Conclusion

Very well, my friends, that is all about Singleton Pattern for Obj-C. I hope you liked. Enjoy your singletons and feel free to ask anything you want.

Cya!

Is time to dive in advanced knowledges about OpenGL and 3D world. In this tutorial we’ll see many things about the 2D graphics, multisampling, textures, render to off-screen surfaces and let’s try to optimize at maximum our applications’ performance.

Is very important to you already know about all the concepts covered in the other 2 parts of this serie, if you miss something, here is a list:

This serie is composed by 3 parts:

• Part 1 – Basic concepts of 3D world and OpenGL (Beginners)
• Part 2 – OpenGL ES 2.0 in-depth (Intermediate)
• Part 3 – Jedi skills in OpenGL ES 2.0 and 2D graphics (Advanced)

At this time I imagine you know a lot of things about OpenGL and 3D world. You probably already created some applications using OpenGL, discovered many cool things, found some problems, even maybe your own engine/framework is under construction and I’m very glad in see you coming back.

As I’ve read once in a book: “One day you didn’t know to walk. Then you learned how to stand up and walk. Now is time to run, jump and swim!”… and why not “to fly”. With OpenGL our imagination has no limits, we can fly.

Let’s start.

Here is a little list of contents to orient your reading:

At a glance

Remembering everything until here:

1. OpenGL’s logic is composed by just 3 simple concepts: Primitives, Buffers and Rasterize.
2. OpenGL ES 2.x works with programmable pipeline, which is synonymous of Shaders.
3. OpenGL isn’t aware of the output device, platform or output surface. To make the bridge between OpenGL’s core and our devices, we must use EGL (or EAGL in iOS).
4. The textures are crucial and should have a specific pixel format and order to fit within OpenGL.
5. We start the render process by calling glDraw*. The first steps will pass through the Vertex Shader, several checks will conclude if the processed vertex could enter in the Fragment Shader.
6. The original structure of our meshes should never change. We just create transformations matrices to produce the desired results.

First I’ll talk about 2D graphics, then let’s see what is the multisampling/antialias filter, personally I don’t like the cost x benefit of this kind of technique. Many times an application could run nicely without multisampling, but a simple multisampling filter can completely destroy the performance of that application. Anyway, sometimes, it’s really necessary to make temporary multisampling to produce smooth images.

Later I’ll talk about textures in deep and its optimization 2 bytes per pixel data format. Also let’s see PVRTC and how to place it in an OpenGL’s texture, besides render to an off-screen surface.

And finally I’ll talk a briefly about some performances gains that I discovered by my self. Some tips and tricks which really help me a lot today and I want to share this with you.

Let’s go!

2D graphics with OpenGL

top
Using 2D graphics with OpenGL is not necessary limited to the use of lines or points primitives. The three primitives (triangles, lines and points) are good to use with 3D and 2D. The first thing about 2D graphics is the Z depth. All our work becomes two dimensions, excluding the Z axis to translations and scales and also excluding X and Y to rotations. It implies that we don’t need to use the Depth Render Buffer anymore, because everything we draw will be made on the same Z position (usually the 0.0).

A question comes up: “So how the OpenGL will know which object should be drawn on the front (or top) of the other ones?” It’s very simple, by drawing the objects in the order that we want (objects at the background should be drawn first). OpenGL also offers a feature called Polygon Offset, but it’s more like an adjustment than a real ordering.

OK, now we can think in 2D graphics at three ways:

1. Many squares on the same Z position.
2. Many points on the same Z position.
3. All above.

This is how a 2D graphics looks like for OpenGL.

How a 2D scene will appear on the screen.

You could imagine how easy it’s to OpenGL, a state machine prepared to work with millions of triangles, to deal with those few triangles. In extreme situations, 2D graphics works with hundreds of triangles.

With simple words, everything will be textures. So most of our work with 2D will be on the textures. Many people feel compelled to create an API to work with texture Non-POT, that means, work with texture of dimensions like 36 x 18, 51 x 39, etc. My advice here is: “Don’t do that!”. It’s not a good idea to work with 2D graphics using Non-POT textures. As you’ve seen in the last image above, it’s always a good idea work with a imaginary grid, which should be POT, a good choice could be 16×16 or 32×32.

If you are planing to use PVRTC compressed image files, could be good to use a grid of 8×8, because PVRTC minimum size is 8. I don’t advice make grids less than 8×8, because it’s unnecessary precise and could increase your work developing, also it compromise your application’s performance. Grids with 8×8 size are very precise, we’ll see soon the diferences between the grids and when and how to use them. Let’s talk a little bit more about the grid.

The Grid Concept

top
I think this is the most important part in the planing of a 2D application. In a 3D game, for example, to determine where a character can walk we must create a collision detector. This detector could be a box (bounding box) or a mesh (bounding mesh, a simple copy from the original). In both cases, the calculations are very important and expensive. But in a 2D application it’s very very easy to find the collisions areas if you are using a grid, because you have only a square area using X and Y coordinates!

This is just one reason because the grid is so important. I know you can come up with many other advantages of the grid, like the organization, the precision on the calculations, the precision of the objects on the screen, etc. About 10 year ago (or maybe more) I worked with a tiny program to produce RPG games with 2D graphics. The idea of grid was very well stablished there. The following images show how everything can be fitted into the grid:

Grid in the RPG Maker. (click to enlarge)

I know, I know… it’s the “Fuckwindons” system, sorry for that… as I told you, it was a decade ago… OK, let’s understand the important features about the grid. You can click on the side image to enlarge it. The first thing I want you notice is the about the overlap of the images. Notice that the left side of the window is reserved to a kind of library. At the top of this library you can see little square images (32×32 in this case). Those squares are reserved to the floor of the scenario (in our OpenGL language, it would be the background). The other images in that library are transparent images (PNG) wich can be placed on top of the floor squares. You can see this difference looking at the big trees placed on the grid.

Now find the “hero” on the grid. He’s at the right side near a tree, it shows a little face with redhead inside a box. This is the second important point about the grid. That hero doesn’t occupies only one little square on the grid, he could be bigger, but to the grid, the action delimitator represents only one square. Confused? Well, it’s always a good idea to use only one grid’s square to deal with the actions, because it let your code much more organized than other approaches. To create areas of actions you can duplicate the action square, just like the exit of the the village on the right top area of the grid in this side image.

I’m sure you can imagine how easy is to create a control class to deal with the actions in your 2D application and then create view classes referencing the control classes, so you can prepare the view classes to get the collision detection on many squares on the grid. So you have 1 action – N grid squares detectors. At this way you can take all advantages of the grid and also an incredible boost in your application’s performance.

By using the grid you can easy define the collision areas which are impossible to the character pass through, like the walls. Another great advantage of using the grid is define “top areas”, that means, areas which always will be drawn on top, like the up side of the trees. So if the character pass through these areas, he will be displayed behind.

The following image shows a final scene which uses all these concepts of the grid. Notice how many images can be overlapped by others, pay attention of how the character deals with the action square and its own top areas. And notice the most top effects overlapping everything, like the clouds shadows or the yellow light coming from the sun.

RPG Maker final scene.

Summarizing the points taken, the grid is really the most important part of planning a 2D application. The grid is not a real thing in OpenGL, so you have to be careful about using this concept, because everything will be imaginary. Well, just to let you know, an extra information: the grid concept is so important that the OpenGL internally works with a grid concept to construct the Fragments.

Great, this is everything about the grid. Now you would say: “OK, but this is not what I wanted, I want a game with a projection like Diablo, Sin City or even the We Rule does!”. Oh right, so let’s make things more complex and bring back the Depth Render Buffer and Cameras to our 2D application.

The Depth Render Buffer in 2D

top
Knowing how the 2D graphics goes with OpenGL, we can think in more refined approach, like use the Depth Buffer even in 2D applications.

"2D game" using OpenGL with Depth Render Buffer. (click to enlarge)

"2D game" using OpenGL without Depth Render Buffer. (click to enlarge)

By clicking on the images above, you can notice the difference between them. Both screenshot are from famous games from iOS, both use OpenGL and both are known as 2D games. Although they use OpenGL ES 1.1, we can understand the concept of Grid + Depth Render Buffer. The game on the left (Gun Bros) makes use of a very small grid, exactly 8×8 pixels, this kind of grid gives to the game a incredible precision to place the objects on the grid, but to improve the user experience you need to make a set of grid squares to deal with the actions, in this case a good choice could be arranging 4 ou 8 grid squares to each action detector. Now the game on the right, it’s called Inotia, by the way, Inotia is today in its 3th edition. Since the first edition, Inotia always used a big grid, 32×32 pixels. As Gun Bros, Inotia uses OpenGL ES 1.1.

There are many differences between those two grid types (8×8 and 32×32). The first one (8×8) is much more precisely and could seem to be the best choice, but remember that this choice will increase too much your processing. The Inotia game has a light processing demand, something absolutely unimpressive to the iOS’ hardwares. You need to make the best choice to fit within the application you are planning to use.

Now, talking about the Depth Render Buffer, the great thing about it is that you can use 3D models in your application. Look, without Depth Render Buffer you must use only squares, or another primitive geometric form, with textures. By doing this you must create one different texture to each position of your animation, specially to characters animation, obviously a great idea is make use of texture atlas:

Character texture atlas from Ragnarok.

The image of Inotia game above has a similar texture altas to each character that appear in the game. Looking at that image you can see that the three character on the screen can turn just to four directions. Now, take another look to the Gun Bros image above.

Notice that the characters can turn to all directions. Why? Well, by using a Depth Render Buffer you are free to use 3D models in your 2D application. So you can rotate, scale and translate the 3D models respecting the grid and the 2D concepts (no Z translate). The result is much much better, but as any improvements, it has a great cost for performance compared to 2D squares, of couse.

But there is another important thing about mixing 3D and 2D concepts: the use of cameras. Instead of creating a single plane right in front of the screen, locking the Z translations, you can create a great plane along the Z axis, place your objects just as in a 3D application and create a camera with orthographic projection. You remember what it is and how to do it, right? (click here to check the article about cameras).

Before going further into the cameras and Depth Render Buffer with 2D graphics, it’s important to know that at this point it has no real difference, at the code level, between 2D and 3D graphics since everything comes from your own planning and organization. So the code to use the Depth buffer is the same we saw in the last part (click here to see the last tutorial).

Now let’s talk about the cameras with 2D graphics.

The Cameras with 2D

top
OK, I’m sure you know how to create a camera and an orthographic projection now, as you’ve seen it at the tutorial about cameras, right? (click here to check the cameras tutorial). Now a question comes up: “Where is the best place and approach to use cameras and depth render buffer in the 2D graphics?”. The following image could help more than 1.000 words:

Same camera in both projections. (click to enlarge)

This image shows a scene like Diablo Game style, with a camera in the similar position. You can notice clearly the difference between both projections. Notice the red lines across the picture, with the Orthographic projection those lines are parallels, but with the Perspective projection those lines are not really parallels and can touch at the infinity.

Now focus on the grey scale picture at the bottom right. That is the scene with the objects. As you can see, they are really 3D objects, but with an orthographic projection you can create scenes like Diablo, Sim City, Starcraft and other best sellers, giving a 2D look to your 3D application.

If you take another look at that image of Gun Bros game, you can see that it’s exactly what they do, there is a camera with orthographic projection and real 3D objects placed on the scene.

So the best approach is to create a camera in your desired position, construct all your scene in a 3D world, set the camera to use orthographic projection and guide your space changes by using the grid concept.

The grid concept is very important even with cameras and Depth Render Buffer.

I have one last advice about this subject, well… it’s not really an advice, it’s more like a warning. Perspective and Orthographic projections are completely different. So the same configuration of focal point, angle of view, near and far produces completely different results. So you need to find a configuration to the Orthographic projection different of that you were using with Perspective projection. Probably if you have a perspective projection which is working, when you change to orthographic projection you won’t see anything. This is not a bug, it’s just the differences between perspective and orthographic calculations.

OK, these are the most important concepts about 2D graphics with OpenGL. Let’s make a little review of them.

• There are two ways of using 2D graphics with OpenGL: by using or not the Depth Render Buffer.
• Without Depth Render Buffer you can construct everything like a rectangle on the screen, forget the Z axis position at this way. Your job here will be laborious on textures. Although, by this way, you can have the best performance with OpenGL.
• By using the Depth Render Buffer you can use real 3D objects and probably you will want to use a camera with orthographic projection.
• Independent of the way you choose, always use the Grid concept when working on 2D graphics. It’s the best way to organize your world and optimize your application performance.

Now is time to go back into the 3D world and talk a little about the multisampling and antialias filter.

The Multisampling

top
I’m sure you already noticed that every 3D application, which have a real time render, have their objects’ edges aliased. I’m talking about 3D world in general, like 3D softwares or games, whatever… the edges always (I mean, in majority of the cases) looks like it’s kind aliased. That doesn’t happen due a lack of well developed techniques to fit that but rather it’s because our hardwares are not so powerful yet to deal with pixel blend in real time too fast.

So, the first thing I want to say about the Anti-Alias filter is: “it’s expensive!”. In the majority of cases this little problem (aliased edges) doesn’t matter. But there are some situations that your 3D application needs to looks better. The most simple and common example is the render in 3D softwares. When we hit the render button on our 3D software we expect to see gorgeous images, not jagged edges.

With simple words, the OpenGL primitives get rasterized onto a grid (yes, like our grid concept), and their edges may become deformed. OpenGL ES 2.0 supports something called multisampling. It’s a technique of Anti-Alias filter which each pixel is divided into few samples, each of these samples are treated like a mini-pixel in the rasterization process. Each sample has its own information about color, depth and stencil. When you ask the OpenGL for the final image on the Frame Buffer, it will resolve and mix all the samples. This process produces more smooth edges. OpenGL ES 2.0 is always configured to multisampling technique, even if the number of samples is equal 1, that means 1 pixel = 1 sample. Looks very simple in theory, but remember that OpenGL doesn’t know anything about the device’s surface, consequently, anything about device’s pixel and color.

The bridge between OpenGL and the device is made by the EGL. So the device color informations, pixel informations and surface informations are responsibility of EGL and consequentially the multisampling could not be implemented only by the OpenGL, it needs a plugin, which is responsibility of the vendors. Each vendors must create a plugin to EGL instructing about the necessary information, by doing this the OpenGL can really resolve the multi samples. The default EGL API offers a multisampling configuration, but commonly the vendors make some changes on it.

In the case of Apple, this plugin is called “Multisample APPLE” and it’s located at the OpenGL Extensions Header (glext.h). To correctly implement the Apple Multisample you need 2 Frame Buffer and 4 Render Buffer! 1 Frame Buffer is the normal provided by OpenGL, the another one is the Multisample Framebuffer. The Render Buffers are Color and Depth.

There are three new functions in the glext.h to deal with Multisample APPLE:

Before checking the code, let’s understand a little bit more about these new functions. The first function (glRenderbufferStorageMultisampleAPPLE) is intended to replace that function that set the properties to the Render Buffer, the glRenderbufferStorage. The big new in this function is the number of samples, it will define how many samples each pixel will has.

The second one (glResolveMultisampleFramebufferAPPLE) is used to take the informations from the original frame buffer, place it in the Multisample Frame Buffer, resolve the samples of each pixel and then draw the resulting image to our original Frame Buffer again. In simple words, this is the core of Multisample APPLE, this is the function which makes all the job.

The last one (glDiscardFramebufferEXT) is another clearing function. As you imagine, after the glResolveMultisampleFramebufferAPPLE makes all the processing, the Multisample Frame Buffer will be with many informations in it, so it’s time to clear all that memory. To do that, we call the glDiscardFramebufferEXT informing what we want to clear from where.

Now, here is the full code to use Multisample APPLE:

.
// EAGL
// Assume that _eaglLayer is a CAEAGLLayer data type and was already defined.
// Assume that _context is an EAGLContext data type and was already defined.

// Dimensions
int _width, _height;

// Normal Buffers
GLuint _frameBuffer, _colorBuffer, _depthBuffer;

// Multisample Buffers
GLuint _msaaFrameBuffer, _msaaColorBuffer, _msaaDepthBuffer;
int _sample = 4; // This represents the number of samples.

// Normal Frame Buffer
glGenFramebuffers(1, &_frameBuffer);
glBindFramebuffer(GL_FRAMEBUFFER, _frameBuffer);

// Normal Color Render Buffer
glGenRenderbuffers(1, &_colorBuffer);
glBindRenderbuffer(GL_RENDERBUFFER, _colorBuffer);
[_context renderbufferStorage:GL_RENDERBUFFER fromDrawable:_eaglLayer];
glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_RENDERBUFFER, _colorBuffer);

// Retrieves the width and height to the EAGL Layer, just necessary if the width and height was not informed.
glGetRenderbufferParameteriv(GL_RENDERBUFFER, GL_RENDERBUFFER_WIDTH, & _width);
glGetRenderbufferParameteriv(GL_RENDERBUFFER, GL_RENDERBUFFER_HEIGHT, & _height);

// Normal Depth Render Buffer
glGenRenderbuffers(1, &_depthBuffer);
glBindRenderbuffer(GL_RENDERBUFFER, _depthBuffer);
glRenderbufferStorage(GL_RENDERBUFFER, GL_DEPTH_COMPONENT16, _width, _height);
glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, GL_RENDERBUFFER, _depthBuffer);
glEnable(GL_DEPTH_TEST);

// Multisample Frame Buffer
glGenFramebuffers(1, &_msaaFrameBuffer);
glBindFramebuffer(GL_FRAMEBUFFER, _msaaFrameBuffer);

// Multisample  Color Render Buffer
glGenRenderbuffers(1, &_msaaColorBuffer);
glBindRenderbuffer(GL_RENDERBUFFER, _msaaColorBuffer);
glRenderbufferStorageMultisampleAPPLE(GL_RENDERBUFFER, _samples, GL_RGBA8_OES, _width, _height);
glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_RENDERBUFFER, _msaaColorBuffer);

// Multisample Depth Render Buffer
glGenRenderbuffers(1, &_msaaDepthBuffer);
glBindRenderbuffer(GL_RENDERBUFFER, _msaaDepthBuffer);
glRenderbufferStorageMultisampleAPPLE(GL_RENDERBUFFER, _samples, GL_DEPTH_COMPONENT16, _width, _height);
glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, GL_RENDERBUFFER, _msaaDepthBuffer);
.

Yes, many lines to a basic configuration. Once all those 6 buffers have been defined, we also need to make the render by a different approach. Here is the necessary code:

.
//-------------------------
//	Pre-Render
//-------------------------
// Clears normal Frame Buffer
glBindFramebuffer(GL_FRAMEBUFFER, _frameBuffer);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

// Clears multisample Frame Buffer
glBindFramebuffer(GL_FRAMEBUFFER, _msaaFrameBuffer);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

//-------------------------
//	Drawing
//-------------------------
//...
// Draw all your content.
//...

//-------------------------
//	Render
//-------------------------
// Resolving Multisample Frame Buffer.
glBindFramebuffer(GL_DRAW_FRAMEBUFFER_APPLE, _frameBuffer);
glBindFramebuffer(GL_READ_FRAMEBUFFER_APPLE, _msaaFrameBuffer);
glResolveMultisampleFramebufferAPPLE();

// Apple (and the khronos group) encourages you to discard
// render buffer contents whenever is possible.
GLenum attachments[] = {GL_COLOR_ATTACHMENT0, GL_DEPTH_ATTACHMENT};
glDiscardFramebufferEXT(GL_READ_FRAMEBUFFER_APPLE, 2, attachments);

// Presents the final result at the screen.
glBindRenderbuffer(GL_RENDERBUFFER, _colorBuffer);
[_context presentRenderbuffer:GL_RENDERBUFFER];
.

If you want to remember something about the EAGL (the EGL implementation by Apple), check it here: article about EGL and EAGL. OpenGL also offers some configurations to multisampling, glSampleCoverage and few configurations with glEnable. I’ll not talk in deep about these configurations here, because I don’t believe multisampling is a good thing to spend our time on. As I told you, the result is not a big deal, it’s just a little bit more refined. In my opinion, the performance cost is too much compared to the final result:

Same 3D model rendered without and with Anti-Alias filter.

OK, now it’s time to talk more about the textures in OpenGL.

More About Textures

top
We already know many things about textures from the second part of this serie (All About OpenGL ES 2.x – Textures). First, let’s talk about the optimized types. It’s a great boost on our application’s performance and is very easy to implement. I’m talking about the bytes per pixel of our images.

Bytes per Pixel

top
Usually the images has 4 bytes per pixel, one byte for each channel, RGBA. Some images without alpha, like JPG file format, has only 3 bytes per pixel (RGB). Each byte could be represented by an hexadecimal color in the format 0xFF, it’s called hexadecimal because each decimal house has the range 0 – F (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F), so when you make a combination of two hexadecimal numbers you get one byte (16 x 16 = 256). As a convention, we describe a hexadecimal color as 0xFFFFFF, where each set of two number represent one color channel (RGB). For images with alpha channel, like PNG format, we are used to say 0xFFFFFF + 0xFF, that means (RGB + A).

My next article will be about binary programming, so I’ll not talk in deep about binaries here. All that we need for now is to know that 1 byte = 1 color channel. The OpenGL can also work with more compressed format, which uses only 2 bytes per pixel. What that means? It means that each byte will store two color channels, including alpha. In very simple words, let’s reduce the color’s range of the image.

The OpenGL offers to us 3 compressed data types: GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_5_6_5. The first two should be used when you have alpha channel and the last one it’s only for situations without alpha. These 3 names tell us something about the pixel data. The numbers at the right instruct us about the number of bits (not bytes) that must be used in each channel (RGBA). Oh, and just to make it clear, each byte is composed by 8 bits. So in the first case 4 bits per channel with a total of 2 bytes per pixel. The second one, 5 bits to RGB channels and 1 bit to alpha with a total of 2 bytes per pixel. And the last one, 5 bits to R, 6 bits to G and 5 bits to B with a total of 2 bytes per pixel.

Here I want to make a warning: The type GL_UNSIGNED_SHORT_5_5_5_1 is not really useful, because only 1 bit to alpha is the same as give it a Boolean data type, I mean, 1 bit to alpha means visible YES or NOT, just it. So this type is not really useful, it has less bits on Green channel than GL_UNSIGNED_SHORT_5_6_5 and even can’t produce real transparent effects like GL_UNSIGNED_SHORT_4_4_4_4. So if you need the alpha channel, make use of GL_UNSIGNED_SHORT_4_4_4_4, if not, make use of GL_UNSIGNED_SHORT_5_6_5.

A little thing to know about the GL_UNSIGNED_SHORT_5_6_5. As the human eye has more sensibility to the green colors, the channel with more bits is exactly the Green channel. At this way, even with a less color range, the resulting image to the final user will not seem to be that different.

Now let’s take a look at the difference between both compressions.

OpenGL optimized 2 bytes per pixel (bpp) data types.

As you saw, by using GL_UNSIGNED_SHORT_4_4_4_4 could really be ugly in some situations. But the GL_UNSIGNED_SHORT_5_6_5 looks very nice. Why? I’ll explain in details at the next article about binaries, but in very simple words, by using GL_UNSIGNED_SHORT_4_4_4_4 we have only 16 tonalities for each channel, including 16 tonalities to alpha. But with GL_UNSIGNED_SHORT_5_6_5 we have 32 tonalities to Red and Blue and 96 tonalities of Green spectrum. It still far from the human eye’s capacity, but remember that by using these optimizations we reduce 2 bytes per pixel in all our images, this represents much more performance to our renders.

Now it’s time to learn how to convert our traditional images to these formats. Normally, when you extract the binary informations from an image you get it pixel by pixel, so probably each pixel will be composed by an “unsigned int” data type, which has 4 bytes. Each programming language provides a method(s) to extract the binary information from the pixels. Once you have your array of pixel data (array of unsigned int) you can use the following code to convert that data to the GL_UNSIGNED_SHORT_4_4_4_4 or GL_UNSIGNED_SHORT_5_6_5.

.
typedef enum
{
	ColorFormatRGB565,
	ColorFormatRGBA4444,
} ColorFormat;

static void optimizePixelData(ColorFormat color, int pixelDataLength, void *pixelData)
{
	int i;
	int length = pixelDataLength;

	void *newData;

	// Pointer to pixel information of 32 bits (R8 + G8 + B8 + A8).
	// 4 bytes per pixel.
	unsigned int *inPixel32;

	// Pointer to new pixel information of 16 bits (R5 + G6 + B5)
	// or (R4 + G4 + B4 + A4).
	// 2 bytes per pixel.
	unsigned short *outPixel16;

	newData = malloc(length * sizeof(unsigned short));
	inPixel32 = (unsigned int *)pixelData;
	outPixel16 = (unsigned short *)newData;

	if(color == ColorFormatRGB565)
	{
		// Using pointer arithmetic, move the pointer over the original data.
		for(i = 0; i < length; ++i, ++inPixel32)
		{
			// Makes the convertion, ignoring the alpha channel, as following:
			// 1 -	Isolates the Red channel, discards 3 bits (8 - 3), then pushes to the final position.
			// 2 -	Isolates the Green channel, discards 2 bits (8 - 2), then pushes to the final position.
			// 3 -	Isolates the Blue channel, discards 3 bits (8 - 3), then pushes to the final position.
			*outPixel16++ = (((( *inPixel32 >> 0 ) & 0xFF ) >> 3 ) << 11 ) |
							(((( *inPixel32 >> 8 ) & 0xFF ) >> 2 ) << 5 ) |
							(((( *inPixel32 >> 16 ) & 0xFF ) >> 3 ) << 0 );
		}
	}
	else if(color == ColorFormatRGBA4444)
	{
		// Using pointer arithmetic, move the pointer over the original data.
		for(i = 0; i < length; ++i, ++inPixel32)
		{
			// Makes the convertion, as following:
			// 1 -	Isolates the Red channel, discards 4 bits (8 - 4), then pushes to the final position.
			// 2 -	Isolates the Green channel, discards 4 bits (8 - 4), then pushes to the final position.
			// 3 -	Isolates the Blue channel, discards 4 bits (8 - 4), then pushes to the final position.
			// 4 -	Isolates the Alpha channel, discards 4 bits (8 - 4), then pushes to the final position.
			*outPixel16++ = (((( *inPixel32 >> 0 ) & 0xFF ) >> 4 ) << 12 ) |
							(((( *inPixel32 >> 8 ) & 0xFF ) >> 4 ) << 8 ) |
							(((( *inPixel32 >> 16 ) & 0xFF ) >> 4 ) << 4 ) |
							(((( *inPixel32 >> 24 ) & 0xFF ) >> 4 ) << 0 );
		}
	}

	free(pixelData);

	pixelData = newData;
}
.

The routine above assumes the channel order as RGBA. Although is not common, your image could have the pixels composed by another channel order, like ARGB or BGR. In these cases you must change the routine above or change the channel order at when extracting binary informations from each pixel. Another important thing is about the binary order. I don't want to confuse your mind if you don't know too much about binaries, but just as an advice: you probably will get the pixel data in little endian format, the traditional, but if your programming language get the binary informations as a big endian, the above routine will not work properly, so make sure your pixel data is in little endian format.

PVRTC

top
I sure you've heard about the texture compression format PVRTC, if you already feel confortable about this topic, just skip to the next one. PVRTC is a binary format created by "Imagination Technology", also called "Imgtec". This format uses the channel order as ARGB instead the traditional RGBA. To say the truth, its optimization is not about the file's size, if we look only to the size, any JPG is more compressed or even a PNG can be lighter. The PVRTC is optimized about its processing, its pixels can be already in the format 2 bytes per pixel (2bpp) or 4 bytes per pixel (4bpp). The data inside PVRTC is OpenGL friendly and also can store Mipmap levels. So, could it be a good idea to always make use of PVRTC? Well, not exactly... let's see why.

The PVRTC format is not supported by default in OpenGL ES 2.0, there are informations that OpenGL ES 2.1 will come with native support to PVRTC textures, but what we have for now is just the OpenGL ES 2.0. To use PVRTC on it, just as the Multisampling, you need a vendors plug-in. In the case of Apple, this plugin has four new constant values. OpenGL provides a function to upload pixel data from the compressed formats, like PVRTC:

As you can imagine, the data format GL_UNSIGNED_SHORT_4_4_4_4 or GL_UNSIGNED_SHORT_5_6_5 is chosen based on the file format, RGB or RGBA with 2bpp or 4bpp, depends on.

To generate the PVRTC you have many options. The two most common is the Imgtec Tools or the Apple's Texture Tool. Here you can find the Imgtec Tools. The Apple tool comes with iPhone SDK, it's located at the path "/iPhoneOS.platform/Developer/usr/bin" the name is "texturetool", you can find all informations about it at Apple Texture Tool.

I'll explain how to use the Apple tool here. Follow these steps:

• Open the Terminal.app (usually it is in /Applications/Utilities/Terminal.app)
• Click on texturetool in Finder and drag & drop it on Terminal window. Well, you also can write the full path "/iPhoneOS.platform/Developer/usr/bin/texturetool", I preffer drag & drop.
• Write in front of texture tool path: " -e PVRTC --channel-weighting-linear --bits-per-pixel-2 -o "
• Now you should write the output path, again, I prefer drag & drop the file from the Finder to the Terminal window and rename its extension. The extension really doesn't matter, but my advice is to write something that let you identify the file format, like pvrl2 for Channel Weighting Linear with 2bpp.
• Finally, add an space and write the input file. Guess... I prefer to drag & drop from the Finder. The input files must be PNG or JPG files only.
• Hit "Enter"

.
/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/texturetool
 -e PVRTC --channel-weighting-linear --bits-per-pixel-2 -o
/Texture/Output/Path/Texture.pvrl2 /Texture/Intput/Path/Texture.jpg
.

Good, now you have a PVRTC file. The problem with the Apple tool is that it doesn't generate the traditional PVRTC binary header. It's composed by 52 bytes at the beginning of the file and gives instructions about the height and width of the image, number of Mipmaps on it, bpp, channels order, alpha, etc. In the traditional PVRTC files, this is the header format:

• unsigned int (4 bytes): Header Length in Bytes. Old PVRTC has a header of 44 bytes instead 52.
• unsigned int (4 bytes): Height of the image. PVRTC only accepts squared images (width = height) and POT sizes (Power of Two)
• unsigned int (4 bytes): Width of the image. PVRTC only accepts squared images (width = height) and POT sizes (Power of Two).
• unsigned int (4 bytes): Number of Mipmaps.
• unsigned int (4 bytes): Flags.
• unsigned int (4 bytes): Data Length of the image.
• unsigned int (4 bytes): The bpp.
• unsigned int (4 bytes): Bitmask Red.
• unsigned int (4 bytes): Bitmask Green.
• unsigned int (4 bytes): Bitmask Blue.
• unsigned int (4 bytes): Bitmask Alpha.
• unsigned int (4 bytes): The PVR Tag.
• unsigned int (4 bytes): Number of Surfaces.

But, using the Apple Texture Tool we don't have the file header and without that header we can't find neither the width nor height of the file from our code. So to use PVRTC from Apple tool you should know about bpp, width, height and alpha. Kind of annoying, no?

Well... I have good news for you. I found a way, a trick, to extract informations from the PVRTC generated by Apple tool. This trick works fine, but it can't identify informations about the Mipmap, but this is not a problem, because Apple tool doesn't generate Mipmaps anyway.

.
// Supposing the bpp of the image is 4, calculates its squared size.
float size = sqrtf([data length] * 8 / 4);

// Checks if the bpp is really 4 by comparing the rest of division by 8,
// the minimum size of PVRTC, if the rest is zero then this image really
// has 4 bpp, otherwise, it has 2 bpp.
bpp = ((int)size % 8 == 0) ? 4 : 2;

// Knowing the bpp, calculates the width and height
// based on the data size.
width = sqrtf([data length] * 8 / bpp);
height = sqrtf([data length] * 8 / bpp);
length = [data length];
.

The PVRTC files made from Texturetool doesn't have any header, so its image data starts in the first byte of the file. And what about the alpha? Could you ask. Well, the alpha will be more dependent of your EAGL context configuration. If you are using RGBA8, assume the alpha exist and use the GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG or GL_COMPRESSED_RGBA_PVRTC_2BPPV1_IMG, based on the informations that you extract from the code above. If your EAGL context uses RGB565, so assume GL_COMPRESSED_RGB_PVRTC_4BPPV1_IMG or GL_COMPRESSED_RGB_PVRTC_2BPPV1_IMG.

Now to use your PVRTC on OpenGL ES 2.0, it's very simple, you don't need to change almost anything, you will create your texture normally, just replace the call to glTexImage2D by glCompressedTexImage2D function.

.
// format = one of the GL_COMPRESSED_RGB* constants.
// width = width extract from the code above.
// height = height extract from the code above.
// length = length extract from the code above.
// data = the array of pixel data loaded via NSData or any other binary class.

// You probably will use NSData to load the PVRTC file.
// By using "dataWithContentsOfFile" or similar NSData methods.

glCompressedTexImage2D(GL_TEXTURE_2D, 0, format, width, height, 0, length, data);
.

Well done, this is all about PVRTC. But my last advice about this topic is, always avoid to use PVRTC. The cost X benefit is not so good. Remember you just need to parse an image file once to OpenGL, so PVRTC doesn't offers a great optimization.

The Off-Screen Render

Until now we've just talked about render to the screen, "on the screen", "on the device", but we also have another surface to render, the off-screen surfaces. You remember it from the EGL article, right? (EGL and EAGL article).

What is the utility of an off-screen render? We can take a snapshot from the current frame and save it as an image file, but the most important thing about off-screen renders is to create an OpenGL texture with the current frame and then use this new internal texture to make a reflection map, a real-time reflection. I'll not talk about the reflections here, this subject is more appropriated to a tutorial specific about the shaders and lights, let's focus only about how to render to an off-screen surface. We'll need to know a new function:

To use this function we need to first create the target texture. We can do it just as before (check out the texture functions here). Then we call glFramebufferTexture2D and proceed normally with our render routine. After drawing something (glDraw* callings) that texture object will be filled and you can use it for anything you want. Here is an example:

.
// Create and bind the Frame Buffer.
// Create and attach the Render Buffers, except the render buffer which will
// receive the texture as attachment.

GLuint _texture;
glGenTextures(1, &_texture);
glBindTexture(GL_TEXTURE_2D, _texture);
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA,  textureWidth, textureHeight, 0, GL_RGBA, GL_UNSIGNED_BYTE, NULL);
glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, _texture, 0);
.

Differently than creating a texture for a pixel data, at this time you set the texture data to NULL. Because they will be filled up dynamically later on. If you intend to use the output image as a texture for another draw, remember first to draw the objects that will fill the output texture.

Well, as any Frame Buffer operation, it's a good idea to check glCheckFramebufferStatus to see if everything was attached OK. A new question comes up: "If I want to save the resulting texture to a file, how could I retrieve the pixel data from the texture?", OpenGL is a good mother, she gives us this function:

As you've saw, the function is very easy, you can call it any time you want. Just remember a very important thing: "OpenGL Pixel Order!", it starts in the lower left corner and goes to the up right corner. To a traditional image file, that means the image is flipped vertically, so if you want to save to a file, take care with it.

Now you must to do the invert path you are used to when import a texture. Now you have the pixel data and want to construct a file. Fortunately many languages offers a simple way to construct an imagem from pixel data. For example, with Cocoa Touch (Objective-C), we can use NSData + UIImage, at this way:

.
// The pixelData variable is a "void *" initialized with memory allocated.

glReadPixels (0, 0, 256, 256, GL_RGB, GL_UNSIGNED_BYTE, pixelData);
UIImage *image = [UIImage imageWithData:[NSData dataWithBytes:pixelData length:256 * 256]];

// Now you can save the image as JPG or PNG.
[UIImageJPEGRepresentation(image, 100) writeToFile:@"A path to save the file" atomically:YES];
.

Just a little question, glReadPixels will read from where? OpenGL State Machine, do you remember? glReadPixels will read the pixels from the "last Frame Buffer bound".

Now it's time to talk more about optimization.

Tips and Tricks

top
I want to talk now about some tips and tricks to boost your application. I don't want to talk about little optimizations which make you gain 0.001 secs, no. I want to talk about real optimizations. That ones which can boost 0.5 secs or even increase your render frame rate.

The Cache

top
This is very important, I really love it, I'm used to use it on everything, it's great! Imagine this situation, the user touch the objects on the screen to make a rotation. Now the user touch another object, but the first doesn't change anything. So it would be great to make the first object's transformation matrix a cached matrix, instead to recalculating the first object's matrix at each frame.

The cached concept extends even to other areas, like cameras, lights and quaternions. Instead to recalculate something at each frame, use a little BOOL data type to check if a matrix or even a value is cached or not. The following pseudo-code shows how is simple to work with cache concept.

.
bool _matrixCached;
float _changeValue;
float *_matrix;

float *matrix(void)
{
    if (!_matrixCached)
    {
        // Do changes into _matrix.

        _matrixCached = TRUE;
    }

    return _matrix;
}

void setChange(float value)
{
    // Change the _changeValue which will affect the matrix.

    _matrixCached = FALSE;
}
.

Store the Values

top
We are used to change the matrix (or the quaternion) every time that occurs transformation. For example, if our code make the changes: translate X - we change the resulting matrix, translate Y - we change the matrix, rotate Z - change the matrix and scale Y - change the matrix. Some 3D engines and people do not even hold on a value to those transformations, so if the code need to retrieve those values, they extract the values directly from the resulting matrix. But this is not the best approach. A great optimization could be reached if we store the values independently, like translations X,Y and Z, rotations X,Y and Z and scales X,Y and Z.

By storing the values you can make a single change into the resulting matrix, making the calculations once per frame instead of making the calculus at every transformation. The following pseudo-code can help you to understand the Store concept better:

.
float _x;
float _y;
float _z;

float x(void) { return _x; }
float setX(float value)
{
    _x = value;
}

float y(void) { return _y; }
float setY(float value)
{
    _y = value;
}

float z(void) { return _z; }
float setZ(float value)
{
    _z = value;
}

float *matrix(void)
{
    // This function will be called once per frame.
    // Make the changes to the matrix based on _x, _y and _z.
}
.

C is always the fast language

top
This tip is just something to remember. You probably know that, but it's very important to reinforce. C is always the fastest language. No other language can be faster than C. It's the most basic language and it's the great father of almost all computer languages. So always try to use C in the most critical parts of the code. Specially for render routines.

String comparisons with C is around 4x faster than Objective-C comparisons. So if you need to check some string value at the render time, prefer to convert it from NSString to C string (char *) and make the comparison, even if you need re-convert from C string to NSString again, even in these cases C string is faster. To compare C strings you know, just use if (strcmp(string1, string2) == 0).

Specially for numbers, always use basic C data types (float, int, short, char and their unsigned versions). Besides, avoid at maximum value that use 64 bits, like long or double data type. Remember that OpenGL ES doesn't support, by default, 64 bits data types.

Conclusion

top
OK dudes, we're at the end of our objective with this serie. I'm sure now you know a lot of things about OpenGL and 3D world. I have covered almost all about the OpenGL in those 3 tutorials of this serie. I hope you learned all the concepts about the subjects covered in these tutorials.

Now, as we are used, let's remember everything:

• 2D graphics with OpenGL can be done by two ways: with or without Depth Render Buffer.
• When using Depth Render Buffer, it could also be good to make use of a camera with Orthographic projection.
• Independent of the way you choose, always use the Grid concept with 2D graphics.
• The Multisampling filter is a plug-in that depends the vendors implementation. Multisampling always has a big cost on performance, use it only in special situations.
• Always try to optimize your textures to a 2bpp data format.
• You can use PVRTC in your application to save some time when creating an OpenGL texture from a file.
• Always try to use the Cache concept when working with matrices.
• Make use of the Store Values concept to save CPU processing.
• Prefer basic C language on the critical render routines.

Well, you know, if you have some doubt, just ask me, let a comment bellow and if I can help I'll be glad.

From here and beyond

Well, and now? Is this all? No. It will never be enough! The points and lines deserve a special article. With points in can make particles and some cool effects. As I told at the beginning of this tutorial, you can use points with 2D graphics instead squares, in case of no Depth Render Buffer.

And about the shaders? In deep? The Programmable Pipeline gives us a whole new world of programming. We should talk about the Surface Normals VS Vertex Normals, about the tangent space, the normal bump effect, the reflection and refraction effect. To say the truth... I think we need a new serie of tutorial called "All About OpenGL Shaders". Well, this could be my next serie.

But I want to hear from you, tell me here or on Twitter what you want to know more about.
Just Tweet me:
Tweet

Thanks again for reading.
See you in the next tutorial!

I felt a good impulse to write a little article about this theme, because there are few poor informations about it around the web. In many cases, are wrong or incomplete informations. So if you want to write a framework to iPhone and distribute it, you are in the right place!

I’ll treat here about how to construct an Universal Framework to iOS, what are the necessary configurations and everything else related to. We’ll focus on Xcode 4, but this is also valid to Xcode 3.x.

Let’s start!

–WARNING–

This content is outdated! There is a new version of this article (2.0) teaching how to create an Universal Framework to iOS, much simpler and reliable:
http://db-in.com/blog/2011/07/universal-framework-iphone-ios-2-0/

Here is a little list of contents to orient your reading:

You can download the project I used in this article:

Download now
Xcode project files to Framework-iOS
403kb

Framework on iOS? Really?

top
Ok buddies, let’s make something clear, many people had said:”iOS doesn’t support custom Frameworks!”, “Custom Framework is not allowed at iOS!”, “Doesn’t exist custom Framework on iOS!” and many other discouraging things like these. Look, I’ve made many frameworks and worked with many others, I don’t believe that is really impossible to use a Framework on iOS. According to my experience and knowledge about Frameworks, it’s absolutely feasible a custom Framework on iOS Devices. If we think more about the issue we can find an elegant solution, right? First, let’s understand what a Framework really is, here is the definition of framework by Apple’s eyes:

A framework is a hierarchical directory that encapsulates shared resources, such as a dynamic shared library, nib files, image files, localized strings, header files, and reference documentation in a single package.

Doesn’t make many sense something with this description not be allowed in iOS, thinking in architecture and structure. Apple also says:

A framework is also a bundle and its contents can be accessed using Core Foundation Bundle Services or the Cocoa NSBundle class. However, unlike most bundles, a framework bundle does not appear in the Finder as an opaque file. A framework bundle is a standard directory that the user can navigate.

Good, now thinking about iOS security, performance and size, the only thing in a Framework definition which doesn’t fit in iOS technology is the “dynamic shared library”. The words “dynamic” and “shared” are not welcome in the iOS architecture. So the Apple allows us to work and distribute something called “Static Library“. I don’t like it! It’s not so easy as a Cocoa Framework, if a developer got your Static Library, he needs to set a header path too, or import the header files… it’s not useful, that’s a shit!

Well, so a Framework concept is absolutely compatible with iOS, except by the “dynamic shared library”, on the other hand Apple says that a “static library” is OK for iOS. So if we replace the “dynamic shared libraries” by a “static library” we could construct a Custom Framework to iOS, right?

Right!!!!

This is exactly what we’ll make in this article, let’s construct a Framework with Static Library, by the way, an Universal Framework.

Understanding Universal, Dynamic and Static concepts

top
Simple answer:

• Universal: Which works perfect on all architectures. iOS devices uses armv6 and armv7, iOS simulator on MacOS X uses i386.
• Dynamic: The compiler doesn’t include the target files directly. The classes/libraries are already pre-compiled (binary format) and lies on the system path. Besides, the dynamic libraries can be shared by many applications. This is exactly what Cocoa Framework is.
• Static: It represents that classes/libraries which is compiled by the compiler at the build phase. These files can’t be shared by other applications and relies on application path.

Simple as that. If you need more informations about Dynamic VS Static libraries, try this Apple’s Documentation.

No more concepts, hands at work!

Constructing a Framework Project

top

1. Create the Project:

top
I want to show you step by step of the entire process, so let’s start with the most basic, create an iOS project. You can choose one application template in Xcode, this is not really so important, but remember to choose one template which could test your Framework code before export it.

Create an application project.

2. Framework Classes:

top

Create your framework classes.

Remember to create an import header to make everything more simple and organized to the user of your framework. Remember to write this header file with a framework notation, just as shown in the image bellow. Also remember to create your classes taking care to hide the classes which should not be visible to the other developers (users of your framework). We will set the public and private headers soon, but it’s very important to you protect the “core” classes, I mean, that classes which you don’t want to make visible to other developers.

For those private classes, you could import their header inside the “.m” (or .mm, .cpp, etc) file of a public class, by doing this you protect the header of private classes. Well, I know you probably already know that, I’m saying just to reinforce.

After you have all the classes (and also other files, like images, sounds, etc.), you are ready to compile a custom framework. In the next step, we’ll create a target to compile our framework, this will be our first big trick!

Create your framework header with framework notation.

Compiling a Framework

top

3. Create a Framework Target:

top
OK, let’s create a target to compile our framework. Click on the icon of your project in the project navigator at the left and hit the button “Add Target”. A new window will come up. Now is our first trick. Instead to create a “Cocoa Touch Static Library” or a “Cocoa Framework” we will create a “Bundle” target.

A Bundle? Really? Yes! I can explain. A “Cocoa Framework” target can’t be compiled to armv6/armv7 and Xcode doesn’t allow us to use “Static Libraries” in a “Cocoa Framework”, so we can’t use this target. On the other hand, we can’t use “Cocoa Touch Static Library” either, because it doesn’t use the framework structure that we want.

Now, the Bundle target could be the best choice. It can hold any file we want, we can compile source code inside it and… we can turn it into a framework. To say the truth, almost all “Framework & Library” targets could be turned into a framework too, even the “Cocoa Touch Static Library”, throughout this article you probably will figure out why. For now, let’s create a Bundle target.

Create a Bundle target rather than Cocoa Touch Static Library.

4. Bundle Setup:

top
It’s time to make all the necessary changes to the Bundle target. First of all, make sure you have cleaned up all the default files from the Bundle target. Remove the linked frameworks (you can find it clicking in the “Build Phase” tab and then they are in the section “Link Binary With Libraries“) and delete the Preference List file (.plist), the pre-compiled headers (.pch) and the language files.

I’m sure you already know this, but just to reinforce, here is the Build Setting screen, you can find it by clicking on the project icon in the left project navigator and then clicking in the “Build Setting” tab.

You must make a special Build Setting to turn a Bundle into a framework.

Here is our second great trick, or should be better to say “tricks”. Let’s change the “Build Setting” following this list:

• Architectures: Standard (armv6 armv7) (the values for this property depend on the value of the item bellow).
• Base SDK: Latest iOS (iOS X.X) (in the X.X will appear the number of the lastest iOS SDK installed on your machine).
• Build Active Architecture Only: NO (this is a very important set, if it’s YES then we can’t compile to armv6 and armv7 at the same time).
• Supported Platforms: iphonesimulator iphoneos.
• Valid Architecture: $(ARCHS_STANDARD_32_BIT) (it’s very important to be exactly this value, seems there is a bug in Xcode 4, once you set i386 as supported platforms to iOS, it can’t be removed anymore and it could generate errors in your project. So, to avoid any architectures error, use this value).
• Installation Directory: [optional change] I like to set this to $(BUILT_PRODUCTS_DIR), but this is not really relevant to our purposes here. You can set it to a path of your choice.
• Mac OS X Deployment Target: Compiler Default.
• Dead Code Stripping: NO.
• Link With Standard Libraries: NO.
• Mach-O Type: Relocatable Object File. This is the most important change. Here, we instruct the compiler to treat the Bundle as a relocatable file, by doing this, we can turn it into a framework with the wrapper setting.
• Other Linker Flags: [optional change] -ObjC, could be good make sure the compiler understands what’s the language it is compiling for, this can reduce the warnings at the compilation.
• Info.plist File: empty, remove any value from this field.
• Wrapper Extension: framework. Here we change the Bundle to a Framework. To Xcode, frameworks is just a folder with the extension .framework, which has inside one or more compiled binary sources, resources and some folders, a folder, usually called Headers, contains all the public headers.
• Precompile Prefix Header: NO.
• Prefix Header: empty, remove any value from this field.
• Generate Debug Symbols: NO (this is a very important setting, otherwise your framework will not work on another computer/profile).

5. Adding code and resources to the Bundle (Framework)

top
It’s time to place the content in our framework and define the public headers. To do that, with the Bundle target selected, click on the “Build Phase” tab. At bottom, hit the button “Add Phase” and then “Add Copy Headers“.

Open the recently created “Copy Headers” section and separate your public headers from the private or project headers. The difference here is:

• Public: Headers that other developers must know in order to work with your framework. In the final framework product, these headers will be visible even to Xcode.
• Private: Headers that is not necessary to other developers, but is good for consult or for reference. These headers will not be visible to Xcode, but will be in the framework folder.
• Project: Headers that the other developers nor Xcode have access. In reality these headers will not be placed in the final product, this is just to instruct the compiler to create your custom framework.

Now, open the “Compile Source” section and put there all your .m, .c, .mm, .cpp or any other compilable source file. If your framework include not compilable files, like images, sounds and other resources, you can place them in the “Copy Bundle Resources” section, in the example of this article, I used no resources. This is how your “Build Phase” will looks like:

Define your compilable source and the headers.

6. Schemes Setup

top
This is an important change to compile our framework. You don’t need to compile it in the Debug modes, we just need the Release mode, because if you have any Macro in your code which works only in Debug mode, like DEBUG macro, it will assume the configuration of the product that the other developers will make. So to us now, only the Release is important.

You can change it accessing the menu Product > Manage Schemes… or by the schemes short cut: the drop list in front at the Build/Run bottom in the top left corner of the Xcode window.

At this point could be a good idea to delete all the current schemes and then press the button “AutoCreate Schemes Now“. The important is select your framework target and hit the button “Edit” at the bottom. In the next window, change the “Build Configuration” from Debug to Release. Change to Release in all the situations: Run, Test, Profile, Analyze and Archive. By doing this, we ensure that our framework target will always compile the Release version.

Build the custom framework only to Release.

7. Building the Framework

top
OK, here is the annoying step of this process. Until now, I don’t figure out a more easy an elegant way to do this. You must to compile this target twice: one to iOS Device (this will compile for the architectures armv6/arvm7) and to iOS Simulator (can be iPhone or iPad with any SDK, doesn’t matter, the simulator always will compile for the architecture i386).

I’ve tried another way, like create an “integrator” and I placed two targets to its “Target Dependencies”, but trust me, it’s worst, because you need to change 2 targets instead 1 in cases when you change the framework content. Besides, the dependencies will assume the architectures of the “integrator”, so you need to compile twice too. Anyway… the best solution I found until now is use only 1 target and build it twice. If you find a better one, please tell me.

Compile the framework target twice: iOS Device and Simulator.

After the compile complete, you can see in the “Products” folder in the Project Navigator at the left, that your framework product now is active. Right click on it and hit “Show in Finder“. Take a look at this product, its is your iOS Framework! Great!

But we’re not done yet. You can test this product in other applications if you want, but it will only work to one architecture. We must to create an Universal version of this product. If you look around your framework product in the Finder, you’ll see that it is in a folder called “Release-iphoneos” (if you didn’t change the destination folder in the Build Settings). And if you have compiled to Simulator too, you’ll see another folder called “Release-iphonesimulator” which contains the same framework product, but this version is for architecture i386.

So, let’s join both products into one.

Building the Universal Framework

top

8. Creating Universal Target:

top
To join both architectures products into one, we must to use the Lipo Tool. It’s a tool which comes with iOS SDK, just to know, it is in “/Platforms/iPhoneOS.platform/Developer/usr/bin”, its file name is “lipo”. But we don’t need to know this path, Xcode can deal with it to us.

To use the Lipo Tool we’ll need to create a “Run Script” at the “Build Phase“, you can create it in your previously Bundle Target, but my advice is to create another target. I say to create another target to avoid compiling errors. This script will need to use “Release-iphoneos” and “Release-iphonesimulator” folders, so if the folders or products inside them not exist yet, the compiler will generate errors.

Let’s add a new target, hit the “Add Target” button, just as you did with Bundle Target. At this time a good choice is the “Aggregate” target. It doesn’t create any product directly, its purposes is just to aggregate another targets and run some scripts, exactly what we want!

Use the "Aggregate" target to construct a run script.

9. Lipo Tool Script:

top
We are almost there, now it’s time to create the Run Script to use the Lipo Tool. Well, you probably will need to make some changes in the code bellow to fit it to your framework name or folders (if you set different folders to build for). Here is the script to use:

.
if [ "${ACTION}" = "build" ]
then
# Set the target folders and the final framework product.
    INSTALL_DIR=${SYMROOT}/FI.framework
    DEVICE_DIR=${SYMROOT}/Release-iphoneos
    SIMULATOR_DIR=${SYMROOT}/Release-iphonesimulator

# Create and renews the final product folder.
    mkdir -p "${INSTALL_DIR}"
    rm -rf "${INSTALL_DIR}"
    rm -rf "${INSTALL_DIR}/FI"

# Copy the header files to the final product folder.
    ditto "${DEVICE_DIR}/FI.framework/Headers" "${INSTALL_DIR}/Headers"

# Use the Lipo Tool to merge both binary files (i386 + armv6/armv7) into one Universal final product.
    lipo -create "${DEVICE_DIR}/FI.framework/FI" "${SIMULATOR_DIR}/FI.framework/FI" -output "${INSTALL_DIR}/FI"
fi
.

Lipo script to join products for architectures i386 and armv6/armv7.

Now build the Aggregate target. At this time doesn’t matter if you build for iOS Device or Simulator, because all that it will make is run the script, nothing more. The above script creates the final Universal Framework at the ${SYMROOT} path, this is the same path of your Bundle target. So you can right click on the Framework product in the “Products” again and hit “Show in Finder”. Move to the level with “Release-iphoneos” and “Release-iphonesimulator” folders. Now, there is a new folder with the “.framework” extension, it’s your Universal Framework to iOS!

Congratulations!

Testing your Universal Framework

top

10. Testing:

top
To test your Universal Framework could be a good idea take it from that folder and place it in another one more easy to find, like the Desktop or ~/Library/Frameworks. Well, to avoid take it from that folder every time, you can change the Run Script above. Just change the “INSTALL_DIR” variable and set a path of your choice, make sure you choose a path with the write permissions. A good choice could be use the Xcode variable ${SRCROOT} which represents your project folder root, so you can set ${SRCROOT}/Products or something like that.

Anyway, with your Universal Framework in an “user friendly path”, create a new Xcode project, select the Application target and go to “Build Phase” tab. Open the section “Link Binary With Libraries” and hit the “+” to add a new Framework. Click the “Add Other…” button and select your Universal Framework. Remember, you must to select the “.framework” folder.

After the importing, Xcode will know everything about your custom framework. So try to write some code using your framework classes. Remember to import your Framework Principal Header as a framework notation. Xcode will use your public headers in the Code Completion.

Xcode knows your public headers and can use them in the Code Completion.

I like to use the Xcode Midnight Color Theme, so the classes of the project are green and the framework classes are blue. I love blue classes!

Conclusion

top
Well done, my friends! As we are used, let’s make a final review and take care with some possible problems.

• In a common Xcode project, create a Bundle target.
• Make the necessary setup, place your sources, headers and resources in it and finally change the its Schemes configuration.
• Compile to iOS Device (armv6/armv7) and to Simulator (i386).
• Create an Aggreate target and place a Run Script in it.
• Enjoy your real Universal Framework to iOS!

To finish I want to talk about some issues that I had:

• Take special care with the architectures. Don’t write the i386 directly in the Valid Architectures setting, always use the $(ARCHS_STANDARD_32_BIT). Plus, always set the Build Active Architecture Only to NO.
• Take care with your classes structure. If you set, for example, the ClassB.h as a Project or Private header, but in your code you import it into a Public header, this will cause conflicts.
• Take care with the Install Directory and Skip Install settings. They can generate warning if the folders permissions or paths are not right set.
• Finally, take a special care with the Lipo Tool script. It could generate warnings and/or errors if the paths was not found or the folder permissions was not right set.

This is all, buddy.
As I told you, the annoying thing is that you need build 3 times to generate a new Universal Framework: 2 x Bundle target (one to iOS Device and other to the Simulator) and 1x to the Aggregate target (which will run a script). But by my experience, this is not to much, you will create the final product only few times. At the great majority, you will test your Framework classes directly with the Application target in your Framework Xcode Project.

Enjoy your real Framework to iOS!

Thanks for reading,
See you soon!

Today I want to talk about the NinevehGL. Talk more about the features and about what it can offer to us. NinevehGL is almost done, I want to be as fast as possible, but I don’t want to launch it without everything seems great: the documentation, the tutorials, the official website and obviously, the NinevehGL itself.

Soon I’ll start posting videos and many divulgations about it, but right now in this article let’s see some images taken directly from the NinevehGL running.

Let’s start!

At a glance

The NinevehGL is a 3D engine fully made with the most pure Objective-C, right on top of Cocoa Touch Framework. So at the first moment, the NinevehGL is a 3D engine only for iOS. I intend to port NinevehGL to MacOSX (desktops with Obj-C) and also for ActionScript 3.0, using the new great API code named Molehill. ActionScript is my old programming language, today I don’t hold much lover for it, but I know that there are many people that still loving Flash. Another important step is to port NinevehGL to JavaScript to work with WebGL. But at the beginning, NinevehGL will work only with OpenGL ES 2.x for iOS.

Now the most important question: “Why NinevehGL instead of PowerVR, Oolong, SIO2, Torque, Ogre, UDK, Unity, Wolfenstein, Shiva, Galaxy, or any other? Why should I choose NinevehGL instead any other 3D engine?”.

I always tried to convince everyone to buy what I was selling, trying to convince everybody from my point of view. But not this time, I don’t want to sell anything, I don’t want to convince you. If you are using some other engine and glad with that, just continue with it, you don’t have to change. Also, if you are a great OpenGL programmer and have your very own model and structure, continue with it, don’t change anything. Because, again, I don’t want to convince anyone at this time. Just as OpenGL, I’ll focus on the most important thing to me: development!

I took everything that I’ve seen of worst in other engines and I’ve tried to make it better in NinevehGL. I took all my frustations with the actual engines, all my luggage as developer, all my knowledge about 3D world and put all of them in the NinevehGL. So, if you are like me and you have some insatisfaction with the other engines, for you, NinevehGL could really nice for you! I know I’m telling this every time, but I love this concept:”Keep it simple!” This is the NinevehGL’s main principle, everything was made to be simple. There are no commands that need more than one single line of code. If you want to make one thing, you need one line, nothing else.

Now I’ll describe in details the most important features of NinevehGL. Remember, I don’t want to convince you of anything. I’m sure you are an advanced programmer and can form your own opinion about what’s coming next. If you like it, great! If don’t, it’s great as well! Just tell me why and I’ll try to make better.

Here is a features’ list.

Importing 3D files

This is the most problematic topic to me considering other engines. As OpenGL doesn’t import 3D files directly, you must use an engine that imports a file good for you or use one of the files accepted by that engine, like POD to PowerVR engine.

This is the first problem that NinevehGL works to solve, it can import the two most popular 3D file formats: COLLADA and WaveFront OBJ. You know what a mess the 3D imports with 3D softwares are. Each software has its own file format and implements its importing routines at its own way. So it’s not hard to export an OBJ from 3DS Max and when you try to import in Maya, BOOM, error! To tell the truth, the incompatibility with the files when exporting from a 3D software to another is common.

The NinevehGL has a full importing routine. What that means? If your OBJ file has informations about the specular, the bump map, the reflection map or anything supported by OBJ file, NinevehGL will import and parse everything for you with no losses. The same is true for COLLADA files.

NinevehGL supports OBJ and DAE files.

Caching 3D files

This is the greatest feature in my opinion. NinevehGL works with a third kind of file, the NGL binary file. It’s a binary file containing a full 3D model with all informations necessary to NinevehGL and also OpenGL. This file is loaded through streaming, so it’s extremely fast. There are no 3D softwares that can export it, it’s exclusive from NinevehGL. So how you can use it? There are two ways: First, you can convert your OBJ or COLLADA file on-line! Yes, you read it right, on-line convertion! No plugins, no installations, no complex things, you can generate NGL file on-line! Just access the NinevehGL website, choose the files on your machine and hit the button!

The other way, is the most fascinating one. NGL file is generated automatically by NinevehGL at the first time you load a new file from OBJ or COLLADA. This file will be stored locally in the device under the folder /Library/NinevehGL. What is great here, is that this folder is fully backed up by iTunes. So imagine this:

1. You make an APP, which loads OBJ and COLLADA files.
2. An user make the download of your APP from the APP Store.
3. The user runs your APP at the first time, the NinevehGL loads around 20 3D file in 12 secs, let’s suppose.
4. The next times that this user runs your APP, the loading time will be 0.12 secs, for example.

What happened???
It’s great! At the second run, the NinevehGL automatically identified that those 20 3D files were already parsed before, so it will use the cached NGL binary files instead the original ones!

But this feature doesn’t stop here! Remember, NinevehGL was made to make everything be simple! So, let’s suppose your application loads the 3D files through the internet connection instead loading it locally. No problems! NinevehGL compares the modification date of the files and choose the most recent. Imagine this:

1. Your APP loads the 3D files from the internet, because you want to make updates without submeting a new APP to APP Store.
2. An User downloads your APP. First run, 20 3D files in 12 secs.
3. In the next times, NinevehGL will use NGL binary files, loading them in 0.12 secs.
4. You make an update and upload some new 3D files.
5. All the users that have your APP will receive the update, with 10 new 3D files replacing the old ones, so NinevehGL will parse the new downloaded files in 10 secs and it’ll generate new NGL binary files.
6. In the next runs of your application, NinevehGL will use the new generated NGL files and the loads will happen in 0.08 secs.

I cry of happiness every time I explain this routine. It’s amazing, wonderful, outstanding, great, it’s… it’s… “magical”! Well, this is just my opinion about it. But I’m sure you can imagine how great would be to the final user: “At the first run, a loading of few seconds, next times, no loading? Where is the loading of this APP?”. The loading happens in a snap.

NinevehGL automatically saves NGL binary files locally.

The last thing I want to say about this feature is the optimization. Again, the NinevehGL was made to be EXTREMELY FAST! So, if you load a NGL binary file directly, it will not create a cache file to it, because it is already optimized, it’ll just create cache from non optimized files (OBJ and COLLADA). Now you know how to convert your 3D models to NGL binary file, you can convert them on-line, at the official NinevehGL website, or can just run your application in the simulator and take the binary file generated at the first run and find the file at /Library/NinevehGL!

In order to avoid confusion, it’s important to say that NinevehGL will not be responsible to manage the internet connection for the file downloading. So you can’t inform an URL to load a 3D file. What the NinevehGL will make is manage the files locally.

Custom Shaders

The NinevehGL was made to work with OpenGL programmable pipeline. So obviously it’ll create its own shaders, based on the materials (loaded from 3D files or materials created directly in the code). Well, the most fun part of the programmable pipeline is exactly the shaders, so will NinevehGL block us of using our own shaders? Of course NOT! NinevehGL is absolutely user friendly, it’s flexible!

The other engines working with programmable pipeline are used to give to us only two choices. Working only with your very own shaders or working only with their shaders! Well, this is not a choice, but rather it’s a dilema! But, the NinevehGL offers another way, a third way: “all of above”! Yes, your read it right, NinevehGL has an API Shader capable to integrate two or more shaders into only one program. WOW, what that means?

That means you can create your own shaders, just as you are used to, implementing your own lights effects, materials or anything else you want. Then you pass your shaders to the NinevehGL and it’ll integrate your custom shaders with the shaders generated by the NinevehGL materials. No conflicts, everything works fine together!

This works for Vertex Shader and/or Fragment Shader. An important thing to say is that there are no special constraints, you can even use a shader that you already have, with many variables inside, many functions and the main function. The NinevehGL Shader API will interpretate the code inside the shaders and will fuse all together.

NinevehGL can merge your custom shader with its own shaders.

Calculating Normals and Tangent Space

This is the robust side of NinevehGL. It’s very fast even in the hard processing scopes, like calculations of normals and tangent space for imported models. Normals and tangent space are very important to generate real time lights, reflections, bump effects and many other things. NinevehGL automatically calculates the normals and generates the tangent space for each mesh that needs it.

NinevehGL automatically generates normals and tangent space, if needed.

NinevehGL can automatically generate some effects, like specular lights, ambient light, emissive light, bump map, reflections and other ones specified by NinevehGL materials. NinevehGL doesn’t impose any limitations to you, it just works around the limits of the OpenGL. So, in the iOS, for example, you can work with very high mesh models. Obviously this is not a common situation, but sometimes it could be better to see high mesh models on the screen. Even to these high meshes, NinevehGL will continue to produce the normals, tangent space, specular lights, bump maps, reflections and everything else you need.

NinevehGL also works with very high mesh models.

Now I want to show you some other features that are also great, but I’ll not talk in deep here.

Optimizing Textures

Just to keep it fresh on our minds, NinevehGL was made to operate in the maximum performance. So even the loaded textures will be optimized. If you choose to work with an opaque OpenGL Layer (the default), the textures could be optimized to the format RGB_5_6_5, which is the best choice without alpha channel. If you choose to work with transparent layer, the textures could be optimized to the format RGBA_4_4_4_4.

The optimization process will happens automatically and you don’t need to worry about it. Even to PVRTC compressed texture format, these optimization could happen, if needed to. The textures, as any other external file, can be loaded from any path locally and the NinevehGL is ready to manage the local paths to you.

Plus, just as the 3D files, textures has a kind of “cache”, that means if you load an image more than one time, the NinevehGL will manage the load locally and will not spend more memory with the same cached image. This is a very important optimization, mostly in cases when a 3D file use the same image for many things, like to the ambient, diffuse and specular maps.

Many other things

There are in NinevehGL many other important features, but I’ll just point it because other engines also have these features, so it’s not that exclusive. Like:

• Cameras with projections (perspective and orthographic).
• Customizations of OpenGL behaviors, like the render buffers.
• Simple API to make 3D transformations (like obj.rotateX += 1.0).
• Always use OpenGL optimization features, as Buffer Objects, array of structures, optimized texture formats, etc.

One great thing to talk a little bit more is about the auto-corrections. It’s very common that the 3D modelers create their models with different scales, I mean, a 3D file which contains a spoon could has the range of vertices going through -1000.0 to 1000.0 and other file which contains a house with the range of -0.5 to 0.7, for example. By placing both files in a 3D softwares you probably will see a house at the side of the empire state in format of a spoon.

For a 3D softwares this is not a big deal, because there are an infinity work space and you can simply reorganize your objects visually. But for a programming language, this is a problem and gets even bigger if the object is so big or so far that you can’t even see it on the screen.

The NinevehGL auto-correction can solve this problem for you, because it can normalize the vertices positions to fit on the screen (or in a specific range you want). By doing so you can control the size of your models without having to export it again from the 3D software. So in the case of the house and the spoon you could set the auto-correction to fit the house at the range -10.0 to 10.0 and the spoon to -0.1 and 0.1, simple as that (one line of code).

Outside the Scope

What you should not expect from NinevehGL? Here is a list:

• The NinevehGL is not a game engine, it’s a 3D engine.
• So you shouldn’t expect physics controllers or sound controllers. You should construct this kind of stuff by yourself.
• No animation, YET! Animations is very important in the 3D world, but the first version of NinevehGL will not come with this feature. (Animations = Character Rigging + Bones)
• No collisions, YET! There are two techniques to deal with collision, bounding box and bounding mesh. In this version, NinevehGL will not implement any of those.

Obviously any item in this list can change, because the NinevehGL is flexible. Consider the above list as an “out of scope” list only for the first version of the NinevehGL.

Conclusion

I’m sure you have now a solid opinion about NinevehGL, good or not, so let me know what you think, post a comment bellow, send me an email, tweet me… anything.

Again, I don’t want to make promisses, but I really want to see this engine released soon. So I’m sure it will come in the first half of this year (2011). I’m just finishing some details now and organizing everything for the first release.

Thanks for reading,

And see you very soon!

NinevehGL will come in the first half of 2011.

This will be a little article to give support to my full tutorial about OpenGL. In this article I’ll talk about the EGL API and the EAGL (the EGL API implemented by Apple). We’ll see how to set up an OpenGL’s application to comunicate with the device’s windowing system.

I’ll focus on Objective-C and iOS, but I’ll talk about the setup in others devices and languages too. So let’s start!

At a glance

As I said in the first part of my full tutorial about OpenGL (click here to see), OpenGL is not responsible by manage the windowing system of each device that support it. OpenGL relinquished this responsability. So, to make the bridge between OpenGL’s render output and the device’s screen, Khronos group created the EGL API.

Remember that EGL can be modified by the vendors to fit exactly what they need to their devices and windowing systems. So my big advice in this article is: ALWAYS CONSULT THE EGL INSTRUCTIONS FROM YOUR VENDORS.

Setup EGL API

OK, now we’ll enter in a EGL’s comum area, independently to the vendors’s implementation, the EGL’s logics is always needed.

The first thing that EGL needs to know is where we want to display our content, normally it is done with the function eglGetDisplay, which returns a EGLDisplay data type. A constant EGL_DEFAULT_DISPLAY is always implemented by the vendors to return their default display. Right after this you call eglInitialize to initialize the EGL API, this function will return a boolean data type to inform the status. So normally you start with the code:

EGLDisplay display;

display = eglGetDisplay(EGL_DEFAULT_DISPLAY);

if (eglInitialize(display, NULL, NULL))
{
    // Proceed with your code.
}

The NULL, NULL parameters are pointers, which you can get the major and minor version of the current EGL’s implementation. I don’t want to go deeply here, the important thing is understand this step. The EGL API need to know where is the display to initialize, just it!

OK, the next step is the configuration. Once EGL know the display, it can prepare the bridge between OpenGL’s output and the device’s screen. To start constructing this bridge, the EGL needs some configurations, which involve the color format, colors individually, the sizes, the transparency, the samples per pixel, pixel format and many others. By default EGL provide a lot of functions to this step, like eglGetConfigs or eglChooseConfigs. Here the interference of the vendors is more intense, because they need to provide a bunch of configurations about their systems and devices. I’ll not describe it here, there are so many systems and languages. So again, always consult your vendors.

The last step is more simple. After all configurations, you instruct EGL API to create a render surface, this means, the surface on which your OpenGL’s render output will be placed. You can choose between a On-Screen or a Off-Screen surface. The first means your render output will go directly to the device’s screen, the Off-Screen means that your render output will go to a buffer or to a image file, a snapshot, or anything like that. You can define the surface by using eglCreateWindowSurface or eglCreatePbufferSurface, both will return an EGLSurface.

But here a little advice, if you want to place your render’s output onto a Off-Screen surface, is better you use a frame buffer directly with OpenGL’s API instead to create a EGL’s PBuffer. Is faster and cost less for your application.

Are we ready now?

Not yet. This is just the platform’s side of the bridge, EGL has the other side of the bridge, the OpenGL’s side.

EGL Context

Until now, EGL knows all that it need about the windowing system, but now EGL needs to know all about our OpenGL usage. Deeply, EGL works with 2 frame buffers. Do you remember what is frame buffer from the first part of OpenGL’s tutorial, right? (click here if not). The EGL API use these 2 frame buffer to place the OpenGL’s render output into your desired surface.

To make it properly, EGL needs to know where are the OpenGL’s buffers which you want to render. This step is very simple. All that we need is create a EGL context and make it the current context (yes, we can create many contexts). Once we made a context the current context, the subsequent Frame Buffer we use in OpenGL will be used by EGL context. Only one Frame Buffer can be used at time (the next part of OpenGL’s tutorial will talk deeply about this). Usually, the EGL functions to context are:

Seems a little confused? Don’t worry. I’m talking superficially about this. The point here is to you understand which an EGL’s Context represent the OpenGL’s side of the bridge. The most important advice I can give you is: Look for the vendors documentation of EGL API.

Rendering with EGL Context

Once the EGL knows about the windowing system and has a context to know about our OpenGL application, we can make our render’s output be presented onto the desired surface.

The render step is very very simple. Do you remember I said EGL works with 2 internal frame buffers? Now is time to use that. All that we need is instruct the EGL to swap the buffers. Swap? Why?

While EGL present one frame buffer to your desired surface, the other one stay on back waiting for a new render output. The buffer on the back will be filled with all renders you did until the next call to EGL swap the buffers and when you do this, EGL brings the back buffer to the front and present the final render’s output onto the desired surface, while the old front buffer goes to the back to reinitiate the process.

This technique is a great boost on our application’s performance, because the our final surface will not be notified every time we execute a render command. The final surface will be notified only when we finish all the renders commands. Another improvement is because the buffer on the back will receive the render’s outputs faster than a device’s screen, for example.

EGL API swap the buffers to present the render onto the desired surface.

This is the function to swap the buffers and present the render output onto the desired surface.

OK, this is all about the EGL making the bridge between the OpenGL’s core and the windowing systems. I know that seems many steps to just output a simple render. But look from far, is just a little setup:

1. Initialize the EGL API with the display and surface given by your vendor.
2. Make the configurations to your desired surface.
3. Create a context and make it your current context.
4. Ask for your EGL context to swap its internal buffers.

Now I’ll talk about EGL implementation by Apple, which has a lot of changes from the original, many changes!

EAGL – The Apple’s EGL API

The EAGL (which we are used to pronounce Eagle) is the implementation by Apple of EGL API. The most important thing to know about EAGL is which the Apple doesn’t allow us to render directly to the screen. We must to work with frame and render buffers.

But why the Apple changed EGL so much? Well, you know the Apple’s approach, Cocoa Framework is almost like another language, it has infinities rules, hard rules! If you change the place of one little screw, all the framework will down! So the Apple made that changes to fit the EGL API into the Cocoa’s rules.

Using EAGL, we must to create a color render buffer and draw our render’s output into it. Plus, we must to bind that color render buffer to a special Apple’s layer called CAEAGLLayer. And finally to make a render, we need to ask the context to present that color render buffer. In deeply, this command will swap the buffer just like original EGL context, but our code changes a lot. Let’s see.

Setup EAGL API

The first thing we need to do is create a sub-class from UIVIew. Inside this new class, we need to change its Core Animation layer. Doing this is equivalent in the original EGL API to initialize the API, take the display from the windowing system and define our surface. So, in this equivalence we’ll have EGLDisplay = the UIWindow which has our custom view and EGLSurface = our sub-class from UIView.

Our code will be like this:

#import <UIKit/UIKit.h>

@interface CustomView : UIView

@end

@implementation CustomView

// Overrides the layerClass from UIView.
+ (Class) layerClass
{
    // Instead to return a normal CALayer, we return the special CAEAGLLayer.
    // Inside this CAEAGLLayer the Apple did the most important part
    // of their custom EGL's implementation.
    return [CAEAGLLayer class];
}

@end

Now we need to make the step of configure the EGL API defining the color format, the sizes and others. In EAGL we do this step by setting the properties of our CAEAGLLayer. So let’s code:

@implementation CustomView

...

- (id) initWithFrame:(CGRect)frame
{
    if ((self = [super initWithFrame:frame]))
	{
		// Assign a variable to be our CAEAGLLayer temporary.
		CAEAGLLayer *eaglLayer = (CAEAGLLayer *)[self layer];

		// Construct a dictionary with our configurations.
		NSDictionary *dict = [NSDictionary dictionaryWithObjectsAndKeys:
							 [NSNumber numberWithBool:NO], kEAGLDrawablePropertyRetainedBacking,
							 kEAGLColorFormatRGB565, kEAGLDrawablePropertyColorFormat,
							 nil];

		// Set the properties to CAEALLayer.
		[eaglLayer setOpaque:YES];
		[eaglLayer setDrawableProperties:dict];

		// Other initializations...
	}

    return self;
}

...

@end

EAGL Context

Following the EGL API steps, the next one is about the context. Here again the Apple changes almost all to fit the EGL API into their Cocoa Framework. The EAGL API gives to us only two Objective-C classes, one of then is EAGLContext. The EAGLContext is equivalent to EGLContext.

Here I have to admit, even changing everything the Apple made this step easer than EGL API. All that you need is allocate a new instance of EAGLContext initializing it with your desired OpenGL ES’s version (1.x or 2.x) and call a method to make that context the current one. Here you don’t have to inform again the EGLDisplay, the EGLSurface, the EGLContext and the others annoying parameters as in the origial EGL API.

@interface CustomView : UIView
{
	EAGLContext *_context;
}

@end

@implementation CustomView

...

- (id) initWithFrame:(CGRect)frame
{
    if ((self = [super initWithFrame:frame]))
	{
		// Other initializations...

		// Create a EAGLContext using the OpenGL ES 2.x.
		_context = [[EAGLContext alloc] initWithAPI:kEAGLRenderingAPIOpenGLES2];

		// Make our new context, the current context.
		[EAGLContext setCurrentContext:_context];
	}

    return self;
}

...

@end

Rendering with EAGL Context

Next step!
By following the above EGL’s steps the next one is the swap the buffers (rendering). But here the Apple changed the thing a lot. As I said before, to use EAGL we must to create at least a color render buffer, this necessarily needs a frame buffer too. So in the reality the next step should be the buffers creations. I could describe this step here, but as this article is just a middle point between the first and the second part of my full tutorial, describe it is not my intention here. I’ll let this discussion to the next part of that tutorial.

So let’s go to the final EAGL’s step, the rendering.
I told you Apple uses a color render buffer instead to directly swap the context’s buffers. By doing this, Apple simplified the last step, the swap of the buffers. Instead to swap the buffers informing the desired display and surface, we just ask our EAGLContext to present its render buffer.

@interface CustomView : UIView
{
	EAGLContext *_context;
}

- (void) makeRender;

@end

@implementation CustomView

...

- (void) makeRender
{
	[_context presentRenderbuffer:GL_RENDERBUFFER];
}

...

@end

The param GL_RENDERBUFFER to presentRenderbuffer is a constant and is just for internal usage. This call should occurs just after we perform all our changes to our 3D objects, like translates or rotations.

Well, this is all the basic instructions about EGL and EAGL APIs. Obviously using EAGL, you could take a more OOP approach, by separating your custom UIView of the other class which hold the EAGLContext instance and makes the final presentation.

Now, as we are used to, let’s remember the steps using the EAGL.

1. Make a sub-class from UIView and override the layerClass method to return an instance of CAEAGLLayer;
2. Set up the properties to the CAEAGLLayer;
3. Create an instance from EAGLContext;
4. Present a color render buffer onto the screen by using the EAGLContext.

Conclusion

Well done, my friends.
Think in this article like an abstract class! Is a little step, but is also so much annoying to cover this in the second part of my OpenGL’s tutorial.

If you were to save only a single sentence of this entire article, the phrase would be: “Consult the EGL instruction from your vendors!”. The vendors don’t interfere inside OpenGL, so I can talk about it independently from the system or language. But the EGL API is the bridge between a unified OpenGL API and all the systems which support OpenGL. So the interference from the vendors on the EGL is bigger! Just like the Apple did!

Thanks for reading!

See you in the next part of OpenGL’s tutorial!