In this article I’ll show how to calculate per-vertex Normals and the Tangent Space. Here you’ll see the most accurate technique, generating real Normals and breaking the vertex when necessary. This article is an intermediate part of the “All about Shaders” series. Would be nice if you’ve read the first part All about Shaders – (part 1/3)

At a glance

First off, the calculations and routines that we’ll create here is not an easy task, there are complexes concepts and calculations involved here. So, be sure you have this macro view:

• Usually the 3D softwares will export an Optimized Per-Vertex Normal, for those cases we can save our time, avoiding re-create the Normals. So we’ll create the Normal Vector ONLY when the Normals from 3D file was not optimized or don’t exist.
• Non optimized Normals means that the same Normal vector was written many times by the 3D software. It happens in some 3D file formats, like COLLADA, that the same Normal vector can appear hundred times, making the parse processing very expensive.
• It’s a good idea to calculate the Tangent Space always as possible (all that we need is Vertex Position and Vertex Texcoord).
• The best way to deal with meshes using OpenGL is to use what we call “Array of Structures”, however I’ll show you a generice algorithym that can be used with “Structure of Arrays” as well.

If these four bullets sounds like “Greek*” for you, I highly recommend you read some other articles before proceed:

• All about OpenGL ES 2.x – (part 1/3)
• All about OpenGL ES 2.x – (part 2/3)
• All about OpenGL ES 2.x – (part 3/3)

(* well, if you are a greek guy, sorry for that and please, take this word as equivalent to “chinese” or something like that).

As I explained before, to calculate the Normals we just need the vertex position, but to calculate the Tangent Space we’ll need the texcoord already calculated. If the mesh we are working on doesn’t have texcoord we’ll skip the Tangent Space phase, because is not possible to create an arbitrary UV Map in the code, UV Maps are design dependents and change the way as the texture is made.

Hands at work!

Calculating Normals – Step 1

In theory, the technique to calculate the face normals is simple: We’ll find the perpendicular vector for each face (triangle). However as you saw in the first tutorial of “All About Shaders“, the face normals are not so good. So, we need to calculate the vertex normals.

The things become a little bit more complex when we try to calculate the vertex normals. Every Face Normal will affect the vertex that compose the face. One single vertex can be shared by multiple faces, so, the final Vertex Normal will be the averaged vector of each Face that share this Vertex. As each face has its own size, the averaged Vertex Normal vector should consider those differences.

Vertices shared by multiple faces will have the resulting Normal as an average of all adjacent faces' Normals.

Just with this concept, you can create the Normals, but they will seem strange in some meshes. Like this teapot at the left side. When I created my first Normals, I spent weeks trying to find what was wrong with my calculus or with this concept… “Everything is OK, but only that fucking vertex is not. Why?”, I thought. Many others said that was a problem with my code, a problem with my memory allocation, and all other kinds of shits. But only after look closely to a great 3D software I found the problem. I’ll show you the same image that I spent hours looking to until I find the solution.

Vertex Normals

Did you notice something strange? This is a basic teapot mesh, many 3D softwares give you this to make tests with materials and lights. But this mesh has ONE single strange vertex: a vertex with 2 Normal Vectors. Is it possible? Actually, NO. The mesh structure must follow a pattern, so you can’t have all vertices with 1 Normal and only one vertex with 2 Normals. This is a very important point that no one talk about it, actually, I never seen anyone talking about this.

It’s time to understand what happens. Your mesh structure is not complete until you calculate the Normals. Why? Because some vertices will be “break/split” into two or more vertices by the Normals. This is what happens in that image. The 3D softwares will not show you this, but there are two vertices, with the same position and texcoords, but with different Normals. Obviously the 3D softwares prefer to omit this for performance reasons, but we can’t omit this fact to OpenGL. We must inform to the Shaders that there are two vertices instead of a single one.

And how will we know where to break a vertex? By the angle between faces. WOW, this thing of Normals is becoming very complex! Yeah, I told you that this is a very important and complex part. Let’s think by steps. Usually the light looks continuous on a surface until an angle of ~80º (like a sphere), however two faces with an angle > ~80º will form a hard edge, like the table’s corners. OK, now translating to English, this is what we’ll do:

1. Calculate each face’s Normal.
2. Calculate the angle between face’s Normals.
3. At each group of ~80º we’ll create a new set of Normals.
4. Finally we’ll find the averaged Normal for each group, respecting the face’s size.

Well, now it looks more simple, with just 4 simple steps. Nice! OK, let’s put our hands on code. First off, let’s create our Vector/Math functions.

// Early in definitions...
typedef struct
{
	float x;
	float y;
} vec2;

// Vector's distance.
static inline vec2 vec2Subtract(vec2 vecA, vec2 vecB)
{
	return (vec2){vecA.x - vecB.x, vecA.y - vecB.y};
}

typedef struct
{
	float x;
	float y;
	float z;
} vec3;

static const vec3 kvec3Zero = {0.0f, 0.0f, 0.0f};

// Vector's length.
static inline float vec3Length(vec3 vec)
{
	// Square root.
	return sqrtf(vec.x * vec.x + vec.y * vec.y + vec.z * vec.z);
}

// Vector's normalization.
static inline vec3 vec3Normalize(vec3 vec)
{
	// Find the magnitude/length. This variable is called inverse magnitude (iMag)
	// because instead divide each element by this magnitude, let's do multiplication, it's faster.
	float iMag = vec3Length(vec);

	// Avoid divisions by 0.
	if (iMag != 0.0f)
	{
		iMag = 1.0f / iMag;

		vec.x *= iMag;
		vec.y *= iMag;
		vec.z *= iMag;
	}

	return vec;
}

// Vector's sum.
static inline vec3 vec3Add(vec3 vecA, vec3 vecB)
{
	return (vec3){vecA.x + vecB.x, vecA.y + vecB.y, vecA.z + vecB.z};
}

// Vector's distance.
static inline vec3 vec3Subtract(vec3 vecA, vec3 vecB)
{
	return (vec3){vecA.x - vecB.x, vecA.y - vecB.y, vecA.z - vecB.z};
}

// Checks for zero values.
vec3IsZero(vec3 vec)
{
	return (vec.x == 0.0f && vec.y == 0.0f && vec.z == 0.0f);
}

// The dot product returns the cosine of the angle formed by two vectors.
static float vec3Dot(vec3 vecA, vec3 vecB)
{
	return vecA.x * vecB.x + vecA.y * vecB.y + vecA.z * vecB.z;
}

// The cross product returns an orthogonal vector with the other two,
// that means, the new vector is mutually perpendicular to the other two.
static vec3 vec3Cross(vec3 vecA, vec3 vecB)
{
	vec3 vec;

	vec.x = vecA.y * vecB.z - vecA.z * vecB.y;
	vec.y = vecA.z * vecB.x - vecA.x * vecB.z;
	vec.z = vecA.x * vecB.y - vecA.y * vecB.x;

	return vec;
}

// Checks if there is a NaN value inside the informed vector.
// If a NaN value is found, it's changed to 0.0f (zero).
static vec3 vec3Cleared(vec3 vec)
{
	vec3 cleared;
	cleared.x = (vec.x != vec.x) ? 0.0f : vec.x;
	cleared.y = (vec.y != vec.y) ? 0.0f : vec.y;
	cleared.z = (vec.z != vec.z) ? 0.0f : vec.z;

	return cleared;
}

Now we’re ready to go further:

// Private variables...
// Assumes that all the variables that start with "_" is a private one
// and you must implement it by your self and some of those values must
// be present before you start:

// vec3 *_vertices    "array of vertices positions"   (required)
// vec3 *_texcoords   "array of texture coordinates"  (optional)
// vec3 *_normals     "array of normals"              (optional/to calculate)
// vec3 *_tangents    "array of tangents"             (to calculate)
// vec3 *_bitangents  "array of bitangents"           (to calculate)

// int  _vCount       "vertices count"                (required)
// int  _tCount       "texture coordinates count"     (optional)
// int  _nCount       "normals count"                 (optional/to calculate)
// int  _taCount      "tangents count"                (to calculate)
// int  _biCount      "bitangents count"              (to calculate)

// int *_faces        "array of face indices"         (required)
// int  _facesCount   "faces indices count"           (required)
// int  _facesStride  "stride of faces indices"       (required)

// Checks the crease angle for the normal calculations.
// This function creates and divides the normals for a vertex, recursively.
static unsigned int creaseAngle(unsigned int index, vec3 vector, vec3 **buffer, unsigned int *count, NSMutableDictionary *list)
{
	// Let's talk about this function later on.
}

// Calculating the Tangent Space.
void calculateTangentSpace()
{
	unsigned int i, length;
	unsigned int j, lengthJ;

	unsigned int *newFaces, *outFaces;
	unsigned int oldFaceStride = _facesStride;

	int i1, i2, i3;
	int vi1, vi2, vi3;
	int ti1, ti2, ti3;

	vec3 vA, vB, vC;
	vec2 tA, tB, tC;
	vec3 distBA, distCA;
	vec2 tdistBA, tdistCA;

	vec3 normal;
	vec3 tangent;
	vec3 bitangent;

	vec3 *normalBuffer;
	vec3 *tangentBuffer;
	vec3 *bitangentBuffer;

	NSMutableDictionary *multiples;

	Element *element;
	int vLength, vOffset;
	int nLength, nOffset;
	int tLength, tOffset;

	float area, delta;
	float *outValue;

	// Checks if the parsed mesh has Normals and Texture Coordinates.
	BOOL hasNormals = NO;// CUSTOM: Check if your mesh structure already has normals.
	BOOL hasTextures = YES;// CUSTOM: Check if your mesh structure already has texcoords.

	// Gets the vertex element.
	vLength = 4;// CUSTOM: Take the length of your vertex position component.
	vOffset = 0;// CUSTOM: Take the offset  of your vertex position component in the Array of Structures.

	// If the normal element doesn't exist yet, creates a new one.
	if (!hasNormals)
	{
		// CUSTOM: Create the Normal elements if it doesn't exist yet.
		// The element should be just as the vertex one, having a length and an offset.
		// IMPORTANT: Increate the stride of your Array of Structures (_facesStride).
	}

	// Gets the normal element.
	nLength = 3;// CUSTOM: Take the normal length.
	nOffset = 7;// CUSTOM: Take the normal offset. In this case (7) we consider it's after the texcoord.

	// If the texture coordinate element exist, gets it and create tangent and bitangent element.
	if (hasTextures)
	{
		tLength = 3;// CUSTOM: Take the texcoord length.
		tOffset = 4;// CUSTOM: Take the texcoord offset. In this case it's after the vertices positions.

		// CUSTOM: Here you should create the Tangent and Bitangent elements. Just as any
		// other element until here, they must have length and offset.
		// IMPORTANT: Increate the stride of your Array of Structures (_facesStride).
	}

	// Allocates memory to the new faces.
	newFaces = malloc(sizeof(int) * (_facesCount * _facesStride));

	// A priori, assumes that for each vertex exists only one normal.
	_nCount = _taCount = _biCount = _vCount;

	// Initializes the buffers for the tangent space elements.
	// This memory allocation must use calloc because they must be 0 (zero) value,
	// otherwise NaN values can be generated.
	normalBuffer = calloc(_nCount, sizeof(vec3));
	tangentBuffer = calloc(_taCount, sizeof(vec3));
	bitangentBuffer = calloc(_biCount, sizeof(vec3));

	// Initializes the dictionaries to deal with vertices with multiple normals in it.
	multiples = [[NSMutableDictionary alloc] init];

	// Loop through each triangle.
	length = _facesCount;
	for (i = 0; i < length; i += 3)
	{
		// Triangle Vertices. At this moment _faces is an ordered list of elements' indices:
		// iv1, it1, in1, iv2, in2, it2, iv3, it3, in3...
		//  |			   |			  |
		//  V			   V			  V
		// iv1,			  iv2,			 iv3
		// So the following lines will extract the indices of vertices that form a triangle.
		i1 = _faces[i * oldFaceStride + vOffset];
		i2 = _faces[(i + 1) * oldFaceStride + vOffset];
		i3 = _faces[(i + 2) * oldFaceStride + vOffset];

		// Calculates the vertex indices in the array of vertices.
		vi1 = i1 * vLength;
		vi2 = i2 * vLength;
		vi3 = i3 * vLength;

		// Retrieves 3 vertices from the array of vertices.
		vA = (vec3){_vertices[vi1], _vertices[vi1 + 1], _vertices[vi1 + 2]};
		vB = (vec3){_vertices[vi2], _vertices[vi2 + 1], _vertices[vi2 + 2]};
		vC = (vec3){_vertices[vi3], _vertices[vi3 + 1], _vertices[vi3 + 2]};

		// Calculates the vector of the edges, the distance between the vertices.
		distBA = vec3Subtract(vB, vA);
		distCA = vec3Subtract(vC, vA);

		//*************************
		//	Normals
		//*************************
		if (!hasNormals)
		{
			// Calculates the face normal to the current triangle.
			normal = vec3Cross(distBA, distCA);

			// Searches for crease angles considering the adjacent triangles.
			// This function also initialize new blocks of memory to the buffer, setting them to 0 (zero).
			i1 = creaseAngle(i1, normal, &normalBuffer, &_nCount, multiples);
			i2 = creaseAngle(i2, normal, &normalBuffer, &_nCount, multiples);
			i3 = creaseAngle(i3, normal, &normalBuffer, &_nCount, multiples);

			// Averages the new normal vector with the oldest buffered.
			normalBuffer[i1] = vec3Add(normal, normalBuffer[i1]);
			normalBuffer[i2] = vec3Add(normal, normalBuffer[i2]);
			normalBuffer[i3] = vec3Add(normal, normalBuffer[i3]);
		}
		else
		{
			// If the parsed file has normals in it, retrieves their indices in the array of normals.
			vi1 = _faces[i * oldFaceStride + nOffset] * nLength;
			vi2 = _faces[(i + 1) * oldFaceStride + nOffset] * nLength;
			vi3 = _faces[(i + 2) * oldFaceStride + nOffset] * nLength;

			// Retrieves the normals.
			vA = (vec3){_normals[vi1], _normals[vi1 + 1], _normals[vi1 + 2]};
			vB = (vec3){_normals[vi2], _normals[vi2 + 1], _normals[vi2 + 2]};
			vC = (vec3){_normals[vi3], _normals[vi3 + 1], _normals[vi3 + 2]};

			// Calculates the face normal to the current triangle.
			normal = vec3Add(vec3Add(vA, vB), vC);
		}

// CONTINUE...

Let's understand all those lines:

• Lines 1-16: Definition of the output variables.
• Lines 20-23: A very important function to calculate the crease angle between faces. We'll discuss more about it later on.
• Lines 28-59: Defining the variables we'll use to calculate the Normals and the Tangent Space.
• Lines 62-63: CUSTOM CODE. Checks if there are Normals and Texture Coordinates already calculated in your mesh structure.
• Lines 66-67: CUSTOM CODE. Gets the length of each Vertex set (usually 3 or 4) and its offset in the Array of Faces.
• Lines 70-75: CUSTOM CODE. If there is no previous calculated Normals, create a new element and define its length (usually 3) and its offset in the Array of Faces.
• Lines 78-79: CUSTOM CODE. Gets the length of each Normal set (usually 3) and its offset in the Array of Faces.
• Lines 82-90: CUSTOM CODE. If there is a calculated Texture Coordinates, then create the Tangent and Bitangent elements. As both Tangent and Bitangent will follow the same elements rule, so you just need to define the length and offset in face for one of them.
• Lines 93-106: Allocating the necessary memory for the calculations.
• Lines 109-110: Starting the loop through all triangles of your mesh.
• Lines 118-120: Getting the indices form the current working triangle.
• Lines 123-130: Getting the vertices related to the current triangle.
• Lines 133-134: Calculating the distance between triangle's vertices. Depending on the order which you calculate this distance, the resulting normal vector direction can change. So, be careful about changing this order.
• Lines 142-153: If there are no previous normals. The cross product between the calculated distances will generate a perpendicular vector, it's the face normal to the current triangle (Cross Product info). Then the crease angles are calculated, so we add the current normal vector to the normalBuffer. When we sum two vectors we are automatically calculating the middle vector. (Add Vector info).
  IMPORTANT: We're not normalizing the vector in this step, by doing so we make sure each triangle area (size) will be considered, because they have different lengths.
• Lines 158-168: If there are previous calculated normals. We calculate the current face normal, because the final format for normals are always vertex normal, not face normal. For the next steps we'll need the face normal.

The Crease Angle - Step 2

As I said before, the crease angle is a crucial part to create perfect normals, otherwise your normals will look correct for some meshes but very strange in other ones. My crease angle is recursive, that means, it will automatically break the vertex index and count as many times as necessary. So if one single vertex has 3 different normals, this function will break it 3 times.

This function must be called once per vertex. In the above code it's called at:
i1 = creaseAngle(i1, normal, &normalBuffer, &_nCount, multiples);
i2 = creaseAngle(i2, normal, &normalBuffer, &_nCount, multiples);
i3 = creaseAngle(i3, normal, &normalBuffer, &_nCount, multiples);

So the original vertex index can become a new index and this new one will be used in new normal vector and in tangent space (tangent and bitanget).

// Defines the maximum crease angle ~80.
#define kCreaseAngle		0.2

// Checks the crease angle for the normal calculations.
// This function creates and divides the normals to a vertex.
static unsigned int creaseAngle(unsigned int index,
								vec3 vector,
								vec3 **buffer,
								unsigned int *count,
								NSMutableDictionary *list)
{
	NSNumber *newIndex, *oldIndex;

	// Eliminates the NaN points.
	(*buffer)[index] = vec3Cleared((*buffer)[index]);

	// Checks if the informed normal vector is not zero.
	if (!vec3IsZero((*buffer)[index]))
	{
		// Calculates the cosine of the angle between the current normal vector and the
		// averaged normal in the buffer.
		float cos = vec3Dot(vec3Normalize(vector), vec3Normalize((*buffer)[index]));

		// If the cosine is greater than the crease angle, that means the current normal vector
		// forms an acceptable angle witht the averaged normal in the buffer. Otherwise, proceeds and
		// creates a new normal vector to the current triangle face.
		if (cos <= kCreaseAngle)
		{
			// Tries to retrieve an already buffered normal with the same bend.
			oldIndex = [NSNumber numberWithInt:index];
			newIndex = [list objectForKey:oldIndex];

			// If no buffer was found, create a new register to the current normal vector.
			if (newIndex == nil)
			{
				// Retrieves the new index and stores its value as a linked list to the old one.
				newIndex = [NSNumber numberWithInt:*count];
				[list setObject:newIndex forKey:oldIndex];
				index = [newIndex intValue];

				// Reallocates the buffer and set the new buffer value to zero, avoiding NaN.
				*buffer = realloc(*buffer, NGL_SIZE_VEC3 * ++*count);
				(*buffer)[index] = kvec3Zero;
			}
			// Otherwise, repeat the process with the buffered value to check for new crease angles.
			else
			{
				index = creaseAngle([newIndex intValue], vector, buffer, count, list);
			}
		}
	}

	return index;
}

Understanding line by line:

• Line 12: Clearing any possible NaN value. If a NaN value is found, it'll be set to 0.0f (zero).
• Line 15: Making sure that an empty buffer index will be skipped, because there is no reason to calculate the crease angle between a face and no other.
• Line 19: Calculating the "dot" product (Dot Product info) we get the cosine of the angle formed between two faces. These faces are: The new normal vector and the value that is already in the normal buffer. Both of them must be normalized at this point, otherwise their lengths will affect the resulting dot product.
• Line 24: Check if the calculated cosine is bellow the crease angle. So, if a cosine value is lower than the crease angle it means the calculated angle is higher than the maximum angle. Then the process of breaking the buffer index will start.
• Lines 27-31: Creating NSNumbers. The old value is, actually, the current index parameter. The line 28 tries to retrieve if there is an already calculated broken index referenced by the current index. If there is a previous calculated reference, that means, if the current index was broken before, then the crease angle function will be called again. Otherwise, the process of breaking the buffer index will continue.
• Lines 34-36: The new buffer index will be created in the end of the current buffer array. This new index will be stored and linked with the current index. So, if the current index appear again we already know where is it broken index.
• Lines 39-40: Reallocating the memory of the buffer array and setting the new index to zero, avoiding NaN values.
• Line 50: The returned index will always be one of these two situations:
  1. An empty buffer index (zero vector).
  2. A buffer index in which its stored normal forms an acceptable angle with the new normal.

Nice! Now we have the correct calculated Normals, respecting the crease angle. Besides if there is a previous calculated normals, this routine respects that and calculates only the face normal again.

Now it's time to enter in the Tanget Space.

Calculating the Tanget Space - Step 3

As you know the Tangent Space is formed by the Tangent Vector and the Bitangent Vector. Just to make this point clear, the word "Binormal" is wrong in the 3D context. Because a 2D circle can have a Binormal, however there is only one Normal Vector in the 3D space. So the perpendicular angle between the Normal and the Tangent is the Bitangent. Some guys still calling as Binormal, we can understand what they want to say, but we know this term is a misspelling, there is no Binormal in the 3D space.

OK, now let's understand the concept of the Tangent Space.

The Tangent Space is a local stuff related at how the light interacts on each face of the surface. But the tangent space doesn't exist in the reality, right? Right, it doesn't. The tangent space is something created as a workaround to use the "Bump Technique". Now a day, there are many bump techniques, like bump map, parallax map , displacement map and many others. Independent of the technique the tangent space vector must be calculated.

The tangent and bitangent are orthogonal vector with the Normal and instruct us about the direction of the face's texture coordinate (U and V map directions). This direction will be used to calculate the light based on the RGB colors of the bump image file.

So in short, the Tangent Space is just a convention that we create as a workaround the bump technique. Here is how we'll calculate the Tangent Space.

// CONTINUING...

		//*************************
		//  Tangent Space
		//*************************
		if (hasTextures)
		{
			// The crease angle process produces splits on the per-vertex normals, as the tangent space
			// must be orthogonalized, the tangent and bitanget follow those splits.
			if (_nCount > _taCount)
			{
				// Normals, Tangents and Bitangents buffers will always have the same number of elements.
				tangentBuffer = realloc(tangentBuffer, sizeof(vec3) * _nCount);
				bitangentBuffer = realloc(bitangentBuffer, sizeof(vec3) * _nCount);

				// Setting the brand new buffers to 0 (zero).
				lengthJ = _nCount;
				for (j = _taCount - 1; j < lengthJ; ++j)
				{
					tangentBuffer[j] = kvec3Zero;
					bitangentBuffer[j] = kvec3Zero;
				}

				_taCount = _biCount = _nCount;
			}

			// Retrieves texture coordinate indices.
			ti1 = _faces[i * oldFaceStride + tOffset] * tLength;
			ti2 = _faces[(i + 1) * oldFaceStride + tOffset] * tLength;
			ti3 = _faces[(i + 2) * oldFaceStride + tOffset] * tLength;

			// Retrieves the texture coordinates.
			tA = (vec2){_texcoords[ti1], _texcoords[ti1 + 1]};
			tB = (vec2){_texcoords[ti2], _texcoords[ti2 + 1]};
			tC = (vec2){_texcoords[ti3], _texcoords[ti3 + 1]};

			// Calculates the vector of the texture coordinates edges, the distance between them.
			tdistBA = vec2Subtract(tB, tA);
			tdistCA = vec2Subtract(tC, tA);

			// Calculates the triangle's area.
			area = tdistBA.x * tdistCA.y - tdistBA.y * tdistCA.x;

			//*************************
			//  Tangent
			//*************************
			if (area == 0.0f)
			{
				tangent = kvec3Zero;
			}
			else
			{
				delta = 1.0f / area;

				// Calculates the face tangent to the current triangle.
				tangent.x = delta * ((distBA.x * tdistCA.y) + (distCA.x * -tdistBA.y));
				tangent.y = delta * ((distBA.y * tdistCA.y) + (distCA.y * -tdistBA.y));
				tangent.z = delta * ((distBA.z * tdistCA.y) + (distCA.z * -tdistBA.y));
			}

			// Averages the new tagent vector with the oldest buffered.
			tangentBuffer[i1] = vec3Add(tangent, tangentBuffer[i1]);
			tangentBuffer[i2] = vec3Add(tangent, tangentBuffer[i2]);
			tangentBuffer[i3] = vec3Add(tangent, tangentBuffer[i3]);

			//*************************
			//  Bitangent
			//*************************
			// Calculates the face bitangent to the current triangle,
			// completing the orthogonalized tangent space.
			bitangent = vec3Cross(normal, tangent);

			// Averages the new bitangent vector with the oldest buffered.
			bitangentBuffer[i1] = vec3Add(bitangent, bitangentBuffer[i1]);
			bitangentBuffer[i2] = vec3Add(bitangent, bitangentBuffer[i2]);
			bitangentBuffer[i3] = vec3Add(bitangent, bitangentBuffer[i3]);
		}

// CONTINUE...

Understanding line by line:

• Line 6: Just create tangent space if there is texture coordinates on the mesh.
• Lines 10 - 25: Checking if the "Crease Angle" routine changed the normals. If so, adjust the tangents and bitangents buffers to have the same size as the normals buffer.
• Lines 27 - 42: Calculates the direction of the UV coordinates and the area of the current face (triangle).
• Lines 47 - 64: Calculates the tangent vector for the current triangle and add this value into the tangents buffer.
• Lines 71 - 76: As the Tangent Space is formed by three orthogonal vectors, we can calculate the last one (bitangent) very easy just by calculating the cross product between the Normal and Tangent.

OK, that's all, it's done!
Now we have all that we need: Normals, Tangents and Bitangents. They all are pretty perfect now and we just need to bring their values back into the arrays format. You can make this last step as you wish, I'll show you here a way that I'm used to.

Updating the Original Arrays - Step 4

OK, as I told you at the start, we'll use the "Array of Structures" in our final format. So we need to create/update that array and its indices based on the new elements, which may include Normals, Tangents and Bitangents.

I'll rewrite the "calculateTangentSpace()" function just to you take a look at it without breaks/continues.

// CONTINUING...		

		// Copies the oldest face indices and inserts the new tangent space indices.
		outFaces = newFaces + (i * _faceStride);
		lengthJ = _faceStride;
		for (j = 0; j < lengthJ; ++j)
		{
			*outFaces++ = (j < oldFaceStride) ? _faces[i * oldFaceStride + j] : i1;
		}

		outFaces = newFaces + ((i + 1) * _faceStride);
		for (j = 0; j < lengthJ; ++j)
		{
			*outFaces++ = (j < oldFaceStride) ? _faces[(i + 1) * oldFaceStride + j] : i2;
		}

		outFaces = newFaces + ((i + 2) * _faceStride);
		for (j = 0; j < lengthJ; ++j)
		{
			*outFaces++ = (j < oldFaceStride) ? _faces[(i + 2) * oldFaceStride + j] : i3;
		}
	}

	// Commits the changes for the original array of faces. At this time, it could looks like:
	// iv1, it1, in1, ita1, ibt1, iv2, it2, in2, ita2, ibt2,...
	_faces = realloc(_faces, sizeof(int) * (_faceNumber * _faceStride));
	memcpy(_faces, newFaces, sizeof(int) * (_faceNumber * _faceStride));

	// Reallocates the memory for the array of normals, if needed.
	if (!hasNormals)
	{
		_normals = realloc(_normals, sizeof(vec3) * _nCount);
	}

	// Reallocates the memory for the array of tangents and array of bitangents, if needed.
	if (hasTextures)
	{
		_tangents = realloc(_tangents, sizeof(vec3) * _taCount);
		_bitangents = realloc(_bitangents, sizeof(vec3) * _biCount);
	}

	// Loops through all new values of the tangent space, normalizing all the averaged vectors.
	length = _nCount;
	for (i = 0; i < length; i++)
	{
		// Puts the new normals, if needed.
		if (!hasNormals)
		{
			normal = vec3Normalize(normalBuffer[i]);
			outValue = _normals + (i * 3);
			*outValue++ = normal.x;
			*outValue++ = normal.y;
			*outValue = normal.z;
		}

		// Puts the new tangent and bitangent, if needed.
		// Isn't necessary here the Gram–Schmidt Orthogonalization process, because all the vectors
		// of the tangent space are already orthogonalized in reason of the crease angle approach.
		if (hasTextures)
		{
			tangent = vec3Normalize(tangentBuffer[i]);
			bitangent = vec3Normalize(bitangentBuffer[i]);

			outValue = _tangents + (i * 3);
			*outValue++ = tangent.x;
			*outValue++ = tangent.y;
			*outValue = tangent.z;

			outValue = _bitangents + (i * 3);
			*outValue++ = bitangent.x;
			*outValue++ = bitangent.y;
			*outValue = bitangent.z;
		}
	}

	// Frees the memories.
	free(newFaces);
	free(normalBuffer);
	free(tangentBuffer);
	free(bitangentBuffer);

	[multiples release];
}

Let's understand more about those last lines:

• Lines 4 - 21: Using a pointer to insert the new face indices in the "newFaces" array, pointers is much faster than accessing the array by indices. These lines also respect the old face indices to place the new ones in the last positions.
• Lines 26 - 27: Updating the original "array of faces". As you can see in the comments, at this point the new "array of faces" will be as "index of vertex 1, index of texcoord 1, index of normal 1, index of tangent 1, index of bitangent 1, index of vertex 2, ...". Remember that in this article I'll not include the job of converting those array into one single "array of structures", however with this "array of faces" you can do it very easy.
• Lines 30 - 40: Preparing the Normals, Tangents and Bitangents to receive the calculated values.
• Lines 43 - 74: Updating the Normals, Tangents and Bitangents values using pointers.
• Lines 77 - 82: Clearing the allocated memory.

Conclusion

WOW, a lot of code in this article, don't you think? I'll try to simplify the steps, as you may notice was only 4 steps until here. So, here is all that you need:

1. Calculate the Normals or use the Face Normals you already has.
2. When you need to calculate the Normals you must calculate the crease angle and split the Normals according to this calculation.
3. Calculate the Tangent Space, which includes Tangent and Bitangent.
4. Update the original arrays, including the Normals, Tangents and Bitangents.

OK, my friends, now you have all that you need to construct your preferable array for OpenGL ("array of structures" or "structure of arrays").

In my next article will continue the series about shaders. Let's talk about shader some techniques advanced skills in OpenGL ES Shaders.

If you have any doubts, just Tweet me:

Tweet

See you soon!

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!

I’m feeling that I must to pay more than a single tribute to Steve Jobs, I want to disseminate this tribute to more than a single post. So this is the deal, I want to talk a little bit about my idea with this tribute and start doing this.

The Image

This image, created by a student (Jonathan Mak Long) early this week became a symbol, an epic symbol and at the same time a tribute to Steve Jobs.

Tribute created by Jonathan Mak Long

This image is so amazing, it have hundreds of implicit significations and many subliminal values. But I don’t want to start a philosophical discuss about this. Just one thing I want to talk about is the first thing that this image make me remember.

I started to search how this image could be created and I found these two images:

They are good as well, but still far from the Long’s image. So, I found this another one:

Good, this image is more closest to what the Long’s image brings to my mind: Steve Jobs on the stage. It’s the strongest memory in my mind. Everyone knows how advanced was his rhetoric skills, how many implicit values and messages Jobs could put in one single sentence. His words reflect his way to think and his way changed everything. So, the great visionary that Steve Jobs was were reflected in their presentations and the Long’s image makes me remember that.

Finally, I found another image, a real photo, this one:

So, the Long’s image is the next step in this chain. I don’t know if the Jonathan Mak Long had this idea in his mind, of also represent the Jobs’ life on the stage. The point is that it comes to my mind when I saw the Long’s image. So, the new “Apple Logo” from Jonathan Mak is absolutely amazing under all points of view, I want to use it!

The Text

I heard this week: “We lost our john Lennon, we lost our hero”. This is true. Today all my life is around what the Steve Jobs did. I have macs on my work and at home, my phone is Apple, I play games on iPads, the last gift I gave to my wife was an iPod, we watch movies on an AppleTV, I teach Apple technology, everyday in my life I work/think in iOS APPs.

The changes that Steve Jobs made goes much beyond the technology. The Jobs’ legacy opened some whole new markets, with thousands companies working on it around the globe everyday, by the way, my daily job is on one of those companies. Steve Jobs really made millions of jobs around the world.

One of my first advertisements. (Click to enlarge)

5 years ago I was an ActionScript developer (Flash), but I hated that, because we can’t create great 3D on Flash (even today with Stage3D/Molehill, Flash developers can’t do the same as iOS can). With iOS I found myself! I found a place to put everything I know, to make great animations, great graphics, to think psychologically in the content and produce amazing user experiences. And the truth is, without Jobs, I could never find my place in this world.

We felt ourselves comfortable knowing we could focus on what we love, because there was one person on the backstage, that was thinking in “one more thing” that will change the day of tomorrow again. But now, this guy is dead…

But he showed to us the path, now we all know that everyone can change the world if they are “crazy enough to think they can change the world”. I want “to stay hungry, to stay foolish”. The Jobs death is not the end, it’s just the beginning of a new era, as he was used to say: a dot that we’ll connect only in some years when we look back, it’s impossible to understand the magnitude of this dot right now. The Jobs’ death is a dot in the history of the mankind.

The Tribute

So I want to do something, more than a simple tribute to Steve Jobs, I want to change something in my life now that will reflect my gratitude to the Jobs’ legacy. So, here is the symbol of this change, here is the deal:

From now and forever in my life, every post, every topic, every article, every single tutorial I make, I’ll finish with the following signature.

Due to some bugs and questions with the old tutorial, I’m creating this new one, much more simpler and less bugs than the another one. I’ll not post the old link here because everything you need to know you can find right here.

Nowadays, exist few alternatives to create a Framework to iOS, changing the default Xcode Script, which could not be a good choice if you want to publish the APPs constructed with your custom Framework. I’ll treat here about how to construct an Universal Framework to iOS, using the default tools from Xcode.

Let’s start!

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

FAQ

top
First off, I want to make sure you understand what this Framework to iOS can do, this can safe your time reading this article:

1. Can I use this Framework as a Bundle to store my files, XIBs, images?
   A: Yes, you can and now it’s very very easy to retrieve your files.
2. Can I use this Framework to import other Frameworks, like import UIKit, CoreGraphics, OpenGL?
   A: No. There is no way to do that. Your code in this custom Framework can import classes from other frameworks normally, but it is just a reference, classes from another framework will not be compiled at this time. So you must import the referenced Framework on the new project as well.
3. Will be my code visible to others?
   A: No. This Framework will export a compiled binary, so anyone can see inside it. You can make the same for some other files, like XIBs.
4. Why I need this?
   A: This is for developers/teams that want to share their codes without shows the entire code (.m/.c/.cpp files). Besides this is for who want to organize compiled code + resources (images, videos, sounds, XIBs, plist, etc) into one single place. And this is also for that teams that want to work together above the same base (framework).

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 this 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 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 simpler 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.

Remember that organization is 90% of a good framework, so try follow all the Apple advices to create your classes names, methods, properties, functions, etc.

Creating the 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 how. 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. Different than the old tutorial. You don’t need to clean up anything. Just know that everything else will be ignored (linked frameworks .plist files, .pch etc…).

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:

• Base SDK: Latest iOS (iOS X.X) (in the X.X will appear the number of the lastest iOS SDK installed on your machine).
• Architectures: $(ARCHS_STANDARD_32_BIT) armv6 (it’s very important to be exactly this value including the space before “armv6″) This setting is valid to Xcode 4.2, if you are using an old version, use the “Standard (armv6 armv7)” option. (the values for this property depend on the value of the item bellow, so set that first).
• Build Active Architecture Only: NO (otherwise we can’t compile to armv6 and armv7 at the same time).
• Valid Architecture: $(ARCHS_STANDARD_32_BIT) (it’s very important to be exactly this value). If your Xcode is showing two lines with armv6 and armv7, delete then and insert this value in one single line.
• 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: This setting is not mandatory, but if you are planning to use any kind of C++ code (.cpp or .mm) on this framework, Chris Moore (on the comments) advises to use the “-lstdc++” option. In this case could be a good idea to use “-ObjC” too, to avoid conflicts in old compilers.
• 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.
• Generate Debug Symbols: NO (this is a very important setting, otherwise the framework will not work on other computers/profiles).
• Precompile Prefix Header: NO.
• Prefix Header: “”. (Leave it blank).

IMPORTANT: Since the Xcode 4.x the architectures armv6 has no longer support. So, to create a real Universal Framework we must make a small “hack”:

1. After change the settings above close the Xcode, find the .xcodeproj (the project file) in Finder and then “Show Package Contents”.
2. Open the file “project.pbxproj” into a text editor.
3. Delete all the lines with VALID_ARCHS = “$(ARCHS_STANDARD_32_BIT)”.

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. Later, when we generate the final framework, all your resources will be placed in a folder called “Resources”, but you can change it. That folder is very important, because it will be part of the path to retrieve your resources from the framework product.

Tip: To add many files at once, click on the “+” button and write the files’ extension on the search field. For example “.m”, “.c”, “.cpp”, “.h”, etc. This can save a lot of time.

This is how your “Build Phase” will looks like:

Define your compilable source and the headers.

Building the Universal Framework

top

6. 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.

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/or run some scripts, exactly what we want! To use the Lipo Tool we’ll need to create a “Run Script” at the “Build Phase“.

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

7. Lipo Tool Script:

top
This will be our greatest trick. The following script will make everything we need. It will compile the Framework Target to iOS Device and Simulator at once, will merge them with Lipo tool and will organize a good Framework Bundle structure.

Copy and paste this on your “Run Script” phase:

# Sets the target folders and the final framework product.
FMK_NAME=FI
FMK_VERSION=A

# Install dir will be the final output to the framework.
# The following line create it in the root folder of the current project.
INSTALL_DIR=${SRCROOT}/Products/${FMK_NAME}.framework

# Working dir will be deleted after the framework creation.
WRK_DIR=build
DEVICE_DIR=${WRK_DIR}/Release-iphoneos/${FMK_NAME}.framework
SIMULATOR_DIR=${WRK_DIR}/Release-iphonesimulator/${FMK_NAME}.framework

# Building both architectures.
xcodebuild -configuration "Release" -target "${FMK_NAME}" -sdk iphoneos
xcodebuild -configuration "Release" -target "${FMK_NAME}" -sdk iphonesimulator

# Cleaning the oldest.
if [ -d "${INSTALL_DIR}" ]
then
rm -rf "${INSTALL_DIR}"
fi

# Creates and renews the final product folder.
mkdir -p "${INSTALL_DIR}"
mkdir -p "${INSTALL_DIR}/Versions"
mkdir -p "${INSTALL_DIR}/Versions/${FMK_VERSION}"
mkdir -p "${INSTALL_DIR}/Versions/${FMK_VERSION}/Resources"
mkdir -p "${INSTALL_DIR}/Versions/${FMK_VERSION}/Headers"

# Creates the internal links.
# It MUST uses relative path, otherwise will not work when the folder is copied/moved.
ln -s "${FMK_VERSION}" "${INSTALL_DIR}/Versions/Current"
ln -s "Versions/Current/Headers" "${INSTALL_DIR}/Headers"
ln -s "Versions/Current/Resources" "${INSTALL_DIR}/Resources"
ln -s "Versions/Current/${FMK_NAME}" "${INSTALL_DIR}/${FMK_NAME}"

# Copies the headers and resources files to the final product folder.
cp -R "${DEVICE_DIR}/Headers/" "${INSTALL_DIR}/Versions/${FMK_VERSION}/Headers/"
cp -R "${DEVICE_DIR}/" "${INSTALL_DIR}/Versions/${FMK_VERSION}/Resources/"

# Removes the binary and header from the resources folder.
rm -r "${INSTALL_DIR}/Versions/${FMK_VERSION}/Resources/Headers" "${INSTALL_DIR}/Versions/${FMK_VERSION}/Resources/${FMK_NAME}"

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

rm -r "${WRK_DIR}"

Now build the Aggregate target. Doesn’t matter you build for iOS Device or Simulator, this script will create a working folder, compile the framework target twice in there (device + simulator) and will output a folder called “Products” located in the project root folder. There is your Universal Framework to iOS!

Congratulations!

Importing your Universal Framework

top

8. Importing:

top
To test your Universal Framework, 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. Remember to import your Framework Principal Header as a framework notation. Xcode will use your public headers in the Code Completion.

Let’s understand what happens until here:
When we set the “Mach-O Type” to “Relocatable Object File” the Xcode understand that everything related to that package will be like a “Binary Archive” like a ZIP. But that archive must be compiled again in new projects.

Then, when we create a Framework Bundle structure, Xcode understand that everything inside it is organized in folders like “Headers” and . But, as any other external bundle, to retrieve the resources you must load the external bundle. To iOS this could be an annoying step, however our Framework structure can help. Just Click and Drag on your Framework icon from “Project Navigator” to the “Copy Bundle Resources“. By doing this all the resources in your Framework will be copied to your Application Main Bundle.

Now, to retrieve the resources, make use of the main bundle, just as you are used to:

[[NSBundle mainBundle] pathForResource:@"FI.framework/Resources/FileName"
                                ofType:@"fileExtension"];

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.
• Create an Aggreate target and place a Run Script in it.

One last advice: 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.

And one last tip: Notice in the sample project I removed the scheme for the “Bundle Target”. We don’t need that scheme any more, because the new script will manage the compilation to us.

That’s all, buddies.
Enjoy your Framework to iOS!

Thanks for reading,
See you soon!

After long months, just waiting for a single day, was a long wait, I know, but today the things will change a little bit. Today is THAT day.

After working through the nights, polishing every piece of code, thinking and rethinking routines… finally IT is here!

I’m very very happy to announce that NinevehGL is HERE!

Ladies and Gentlemen

With a great pleasure, let me introduce you the NinevehGL!

Keep it Simple

You know me, I’m so bored with many web sites, softwares, 3D engines and technologies that make our life a hell with their docs (or the absence of docs), poor tutorials, complex setups, complex API or even worst… they are paid! God Dammit!!!

• So, let’s try something different, something simple! Starting with the web site: nineveh.gl, just it, simple and easy.
• What about tutorials or docs? Very simple: http://nineveh.gl/docs/tutorials/, video tutorials!
• Long time to learn? Maybe… what do you think about just 30 min? 10 videos, 3 min each one. Sounds good?

Awesome features

There are many cool features in NinevehGL. But I think 3 are the “Killer Features”:

• OpenGL ES 2.0 (Programmable Pipeline): It uses the newest OpenGL ES version. More power, faster, lighter, better and shaders! With NinevehGL you can use all the power of the shaders and programmable pipeline.
• Import directly from 3D softwares! NinevehGL doesn’t need plugins or special 3D formats to import your files! Make use of Wavefront OBJ files or COLLADA files (all 3D softwares export one of them). NinevehGL is ready to import them.
• Made with pure Objective-C (Obj-C)! Yes, as an iOS developer, when I use OpenGL I expect to see Obj-C code, not C++ or C. NinevehGL is purely made with the native iOS language. Classes and routines follow all the Apple/Cocoa Touch guidelines.

Well, another great thing about NinevehGL is that it’s FREE! A 3D engine for iOS totally FREE!

This is a short post just to tell you about this great news. I hope you like it.

See you, guys!

In this article, I’ll talk about the binaries. I’ll cover the most important concepts and operations, let’s see some examples of where and how to use binaries and also how you can use it in your daily work. If you are looking for a tutorial about binaries or a “binary tutorial”, you are in the right place.

Let’s delve into the binary world.

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

At a Glance

The binaries are the most basic and fastest approach in any programming language. Why? Our computers, and I mean, any kind of processing machine, is composed by a board with electric circuits on it, a lot of them. Through these circuits, electrical impulses passes every time, by one single circuit can pass thousands impulses per second.

Representation of electrical impulses on a computer board.

The receptors of the impulses are prepared to receive only one kind of information: “has impulse or not”, it’s a single “YES or NO”. This kind of information is exactly what a bit is. A bit can has the values 1 or 0 (“YES or NO”). Very simple, right?

This is why the binaries are the fastest approach ever. Because it’s the most singular representation of an electrical impulse, which is the basic communication of the components of our hardwares. Everything what comes next in this article is just a little of organization above this kind of information. We’ll see how organize the bits to form a byte, data types, files and everything else in our virtual world!

After we understand the binary world, we’ll apply some mathematics on it and make simple operations using the BITWISE operators. Finally we go up to high level programming language and see how the binaries can be used in our daily work to improve our applications.

Bit and Byte

top
Some people get confused with these names, so let’s make everything absolutely clear: “A Bit IS NOT a Byte!”. To our high level programming language, a single bit is “invisible”, we can’t set a bit individually, all our work is done on the byte level. To us, the byte is the most basic unit, not a bit. But what the hell is the diference between bit and byte?

Well, one byte is composed by 8 bits, this is a constant, it’s a rule, this never will change. 1 Byte = 8 Bits.

So, if we think in a sequence of 8 bits, remembering from combinatorial analysis, we can say that a set of 8 bits (with 2 possible values: 0 or 1) results in 256 possibilities (2^8 = 256). To make full use of these 256 possibilites, we can think in that sequence as Power of Two.

Every sequence of 8 bits forms 1 byte, which has 256 combinations.

Confused? Well, look at the next list, it could help you to understand this concept:

To compute the value, you look at every bit and check if it is valid or not (0 or 1), if it’s valid you sum the value it represents. Then you have the final value to a specific byte. The following image shows an example:

Each bit represents a single "YES" or "NO".

The calculation in the image above was: 128 + 64 + 32 + 4 + 1 = 229. Very simple, right?

Try it Yourself

top
You could try to discover the following values by yourself:

If you miss some value, don’t worry, because in reality we’ll never need to make this kind of calculation by our selves. As I told you before, what happens with bits inside a byte is invisible to our high level programming languages. We’ll never (or almost never) need to write “myVariable = 10101100;“, instead we’ll use: “value = 172;”

Now let’s go up one level and understand how a byte can be combined with another one to form more complex structures.

Combining Bytes

top
As we’ve saw a Byte can has 256 different values, 0 – 255. But we are used to use data types with a large range, like int, wich can be -2,147,483,648 to 2,147,483,647 or even the floating numbers, how it can be?

It’s simple, by placing more than 1 byte to describe a data. If you are 20 years or old, you probably remember from devices of 8 bits, right? Like the game console Nintendo 8 bits. Well, now you know, that console was capable to process data types only with 1 byte at time. After comes platforms of 16 bits, 32 bits and today we are used to work with 64 bits platforms. What that means?

In case of 16 bits, that means 1 byte can be processed together with another byte (2 x 8 bits), for a 32 bits platforms, that means 4 bytes can be processed together (4 x 8 bits), for a 64 bits platforms that means 8 bytes processed together (8 x 8 bits) and so on. The following picture illustrate 32 bits data types int and float:

Modern processors can work with multiple bytes at same time. This is a representation of 32 bits data types.

Thinking about it: a simple change of processing, from reading only 1 byte to more than one, can changes everything in our devices. For example, with 8 bits at once we have a range of 256 values for colors, do you remember from computers with that configuration? Yes, it was sucks! Now, with 4 bytes at the same time we can have systems running with 4,294,967,296 different colors. Imagine the performance and processing gain to our hardwares with that simple change: from reading 1 byte to reading many of them.

Just as a divagation, in these days, some people say about new kind of processors: Quantum Processors! The idea is change from electrical impulses on a board to electrons state in an atom. Basically an electron have 3 states in the energy level: Up (positive), Middle (neutral) or Down (negative), so instead only a single “YES or NO”, we could identify three states: “UP, MIDDLE and DOWN”. This single fact can drive us to a new perspective and a new kind of “bit”. Besides, unlike the impulses on a board, the electrons in an atom space don’t need to follow a physical path, its is just atomic vibration, imagine how fast it can be. Now imagine how many electrons can exist in a single atom, how many “bytes” (or something similar) we could process at the same time! Today some super computers are running on great platforms like 128 bits, 256 bits, 512 bits and more, but nothing could be compared to a Quantum Processor! Well, to say the truth, I’ve read that a team led by Yale University researchers has created the first quantum processor. This still far from the market, but not so far from our world.

Well, this is enough divagation. Back to the earth!

Great, now we know how our high level programming languages deal with binaries and more, we know how the binaries work. So every time you create an int data type, for example, in reality, you are creating a set of 32 bits, or in simple words, 32 slots of 0 or 1: 00000000 00000000 00000000 00000000.

It’s time to learn some operation we can make in the bit level.

Bitwise Operators

top
There are just few bitwise operators, actually 4. The actions they make are completely different than traditional mathematical operations.

   01001101
&  00101011
   --------
   00001001

   01001101
|  00101011
   --------
   01101111

   01001101
^  00101011
   --------
   01100110

~  01001101
   --------
   10110010

All the bitwise operators with use two sequences, just work for two sequences of the same length. But if one sequences has less bits, it will be filled with 0 at the left until reach the same length of the bigger sequence. For example: 01010100 & 111 is in reality the operation: 01010100 & 00000111. Remember that 0 bits on the left doesn't change anything, just as the real numbers.

Using these simple operations we can really make incredible routines. The best thing is that binaries are stupidly fast with any language, but we already talked about that. Soon we'll see some real examples of binaries in our day work. Before it, we need to see the Bit Shift operations, they are like a complementation to Bitwise operators.

Bit Shifts Operators

top
Exist two kind of shifts: left and right. Simple as that. Using this bit shift you'll push the bits in a byte set, that means, if your data type has 1 byte, bits will be shifted inside only 1 byte, if your data type has 4 bytes, bits will be shifted inside these 4 bytes.

   01001101 <<
   --------
   10011010

   01001101 >>
   --------
   00100110

The Bit Shift operator should be always in the right side. You also can specify multiple bits to shift by placing the number to shift at the right of the operator. For example:

.
   01001101 << 4
   --------
   11010000

   01001101 >> 3
   --------
   00001001
.

Oh right, my friends, these are all the binary operators. Now with these very simple operations we'll make really great things, including in our daily work.

Real Applications to the Binaries

top
I want to show you examples that we are used to use in our daily-work, some examples that can boost your application's performance without hard re-coding, just simple changes. So my deal with you is: only real examples. Let's go.

Even/Odd Routine

top
Let's start with a very simple example. Imagine a routine that you need to fill lines in a table, you want to fill those lines in pairs, one colored line and the one with blank. A simple way would be to count the rows and on each odd number row you fill in with color and on each even number row you leave it blank. Then we could create a routine to check the result of a division by 2, but the fastest way is using binaries. A binary routine could be something like this:

.
// Assume the numberOfRows variable was set.
for (i = 0; i < numberOfRows; ++i)
{
    if (i&1)
    {
        // The "i" is an odd number.
    }
    else
    {
        // The "i" is an even number.
    }
}
.

I love this routine. It makes me think about all the implicit rules that are within binary numbers. In the example above, what we are actually doing is:

00000001 & XXXXXXXX

As only the first bit has a value equals to 1, the only way to create an odd number is by using that bit. So, by using the AND operator, we check if the current "i" number makes use of that bit or not. In affirmative case, the number is odd, otherwise, it will be an even number. Very simple!

Working With Colors

top
Binary + Colors is one of the most popular topics. Almost all Image Softwares make use of binary routines to transform the images. For example, Photoshop makes all its image effects with binary changes in the pixel level.

The first thing about the binary + colors is to understand what is an hexadecimal number. An hexadecimal value is represented by 0xN (always need "0x" before the number), where N has 16 different values: 0-9 + A-F. So the real values to an hexadecimal number is:

0x0 = 0
0x1 = 1
0x2 = 2
0x3 = 3
0x4 = 4
0x5 = 5
0x6 = 6
0x7 = 7
0x8 = 8
0x9 = 9
0xA = 10
0xB = 11
0xC = 12
0xD = 13
0xE = 14
0xF = 15

Now we can place two hexadecimal numbers side by side, one will work like our "unit place" and the other as our "decimal place". So the first has 16 possible values and the second one has other 16 values, totalizing 256 possible values. Wait, wait, wait... 256? It's a Byte, right? So we can use every combination of two hexadecimal numbers (0xNN) to represent a byte!

Pair of hexadecimal numbers.

Just to make this step clear, here is some values using double hexadecimal numbers.

0x00 = 0      (0 x 16 + 0)
0x10 = 16     (1 x 16 + 0)
0x20 = 32     (2 x 16 + 0)
0x21 = 33     (2 x 16 + 1)
0x22 = 34     (2 x 16 + 2)
0xA0 = 160    (10 x 16 + 0)
0xA9 = 169    (10 x 16 + 9)
0xAA = 170    (10 x 16 + 10)
0xAB = 171    (10 x 16 + 11)
0xF0 = 240    (15 x 16 + 0)
0xFF = 255    (15 x 16 + 15)

Well, by using 32 bits platforms, we can use 4 bytes to describe a color, if we think in a RGB spectrum + Alpha we can reserve 1 byte to each color channel (R,G,B,A). At this way, each color channel has 256 possible values, right? We can represent a byte with a double hexadecimal number in the form 0xNN. So we could represent a full pixel with RGBA informations with an hexadecimal combination like this 0xNNNNNNNN, or using a "channel representation" 0xRRGGBBAA.

As a legacy from old times, the alpha processing doesn't has a pattern, so each software made its own implementation, some make 0xRRGGBBAA, others make 0xAARRGGBB and others even use 0xRRGGBB + 0xAA. Until today we don't have an universal format to alpha, so let's focus only in 0xRRGGBB to our study purposes.

Now, to isolate each color channel is very simple:

.
unsigned int color = 0x99AA44

unsigned char redChannel = color >> 16;
unsigned char greenChannel = ( color >> 8 ) & 0xFF;
unsigned char blueChannel = color & 0xFF;
.

It's very simple understand what happened. If we think in a binary representation (bits), the "color" variable above could be something like: RRRRRRRRGGGGGGGGBBBBBBBB. Then, when we move sixteen bits to the right, the resulting binary is:

RRRRRRRRGGGGGGGGBBBBBBBB >> 16 = RRRRRRRR

Similar we move eight bits to get the green channel, but at this time the green channel is not isolated yet, the red channel remains in the result. Then, to isolate the green channel we use the AND bitwise with 0xFF, which is a byte representing the real value 255, by doing so, we discard all the red channel information, remaining only with the green channel:

RRRRRRRRGGGGGGGGBBBBBBBB >> 8 = RRRRRRRRGGGGGGGG & 11111111 = GGGGGGGG

And finally we make almost the same to the blue channel:

RRRRRRRRGGGGGGGGBBBBBBBB & 11111111 = BBBBBBBB

If you get the pixel data from an image file, it could also has the alpha information pre-multiplied (ARGB). So to correctly extract the color channels you could make the & 0xFF step even to the red channel. If the alpha is post-multiplied (RGBA), we must to push 8 bits more:

.
unsigned int color = "one pixel data"

// To pixel data in format ARGB
unsigned char redChannel = ( color >> 16 ) & 0xFF;
unsigned char greenChannel = ( color >> 8 ) & 0xFF;
unsigned char blueChannel = ( color >> 0 ) & 0xFF;

// To pixel data informat RGBA
unsigned char redChannel = ( color >> 24 ) & 0xFF;
unsigned char greenChannel = ( color >> 16 ) & 0xFF;
unsigned char blueChannel = ( color >> 8 ) & 0xFF;
.

Once you have access to the color channel of each pixel you can make almost everything with the image color. You can exclude or replace a color channel, transform it into a grey scale image, change the colors individually, well... look at the Photoshop, all that effects was made with this principle. Obviously to produce more complex effects, like a blur or motion blur you need make many passes through every pixel and depending on the image size (width and height), this could be a very expensive task.

I've wrote about how to reduce the color range of an image using the binary approach. It was on my last OpenGL tutorial, you can check it by clicking here.

All the informations on this topic, binary + color, are about the most popular image formats, which make use of 8 bits per channel. But, there are some image format that support more, like 16 bits/channel or even 32 bits/channel. Those high formats support an incredible range of colors, they are often used to print formats, which uses CMYK instead RGBA color formats. But if you need to work with one of that "high images", the code is almost the same, just changing some numbers of bit shifts. To our virtual world, assume all images will always use 8 bits/channel. The following image shows the supported bits per channel for each of the popular image formats. Files that support 32 bits/channel also support 16 and 8, files that support 16 bits/channel also support 8:

Supported bits/channel on the most popular image formats.

Files are Bits

top
Everything was made with binaries. All the files that we use are in a low-level, only bits. So we can parse and extract information from any file. But to do that, you must know the bits organization in that file. This is the principle of file security and encryption. If you make a "coder" and a "decoder" to reorganize the bits inside a file, that file will be now encrypted. More sophisticated techniques also include fake bits or even create a "key" inside the file to recreate the file with a completely new structure. But in depth, everything are bits and can be read.

Usually the popular file formats have their bits organizations largely exposed on documents and specifications. So we can learn to read and write those formats.

Here is a list with the greatest website with file format specifications:

• http://www.fileformat.info
• http://www.wotsit.org
• http://www.martinreddy.net/ - for 2D image files
• http://www.martinreddy.net/ - for 3D format files

You also have 2 other choices: search in wikipedia for the file format you are looking for or even go to the page of the company/creator which made the file you are looking for. If you don't know who is the creator, you can go to this page: http://whatis.techtarget.com and search for the file extension, when you click you'll see a link to the official page of that format, if exist.

Talking about the file formats, in general, the great majority of the file creators try to organize the informations in 4 bytes, even those informations that need less than 4. This is a good practice to make the file more organized and more readable. But it's not a rule, some files could fill many informations into 4 byte.

Our high level programming languages often offer a class, or some classes, to work with binary files. So you can easily use any data type and that class will create a binary stream for you, forming a great array of bits. After put all informations on the files, you just save it, or send via internet, anyway. I'll show you a little piece of code using Objective-C (Cocoa):

.
// Creates some generic data to save into a file.
// As in C language the strings are made with an array of chars
// we must to know the length of the string to calculate
// the number of bits necessary to write it.
float floatNumber = 15.2;
char *charString = "this is a string";
int strLength = strlen(charString) + 1;

// Initializes the Cocoa class that deals with binaries.
NSMutableData *data = [[NSMutableData alloc] init];

// Inserts the data to save. This order is very important.
[data appendBytes:&floatNumber length:sizeof(float)];
[data appendBytes:&strLength length:sizeof(int)];
[data appendBytes:&charString length:sizeof(char) * stringLength];

// Saves the file.
[data writeToFile:@"/path/to/save/file.test" atomically:YES];

// Frees the memory allocated.
[data release];
.

Even if you are not familiar to Objective-C, you can understand the steps involved here. Using a standard C libraries, we also can use fopen function with the parameter "b" to open or write a file in the binary format.

The most important thing to understand is the order and length of each information in a binary file. In the example above, if we change the order of the calls to "appendBytes:length:" the resulting file will be absolutely different. The following image shows the resulting file from the code above and another file resulting from one little change in the code:

Every file is a stream of bits.

As you can see, changing the order of one little information drives us into a whole new file. The image above shows the binary file opened in an "Hexadecimal Editor". This kind of application show to us the binary format of any file, separating the data in 4 bytes. You remember how to represent a byte using hexadecimal numbers, right? 0xNNNNNNNN represents 4 bytes.

To read the binary file, you need follow the inverse path: selecting a set of bits by time and parsing it appropriately. For example, if you know the next 4 bytes represents a float data, parse it in a float data type, if you know the next byte represents a single char, parse it into a char and so on. Here is an important thing, to parse an information with mutable size, like a string, you need to know the length of the data in first place. So every time we need save a data with mutable size, we reserve some bits (usually 32 bits) to hold the length of the data that comes next.

Using the same example above, we could write to open the saved file:

.
// Creates the variables to receive the data from binary file.
float floatNumber;
char *charString;
int strLength;

// Creates a location/pointer to guide the position of the bytes inside the binary file.
int lastLocation = 0;

// Initializes the Cocoa class that deals with binaries.
NSData *data = [[NSData alloc] initWithContentsOfFile:@"/path/to/save/file.test"];

// Retrieves the floating number from the file and updates the location/pointer.
[data getBytes:&floatNumber range:NSMakeRange(lastLocation, sizeof(float))];
lastLocation += sizeof(float);

// Retrieves the string length from the file and updates the location/pointer.
[data getBytes:&strLength range:NSMakeRange(lastLocation, sizeof(int))];
lastLocation += sizeof(int);

// Allocates the necessary memory to receive the string and retrieves the data.
charString = malloc(sizeof(char) * strLength);
[data getBytes:&charString range:NSMakeRange(lastLocation, sizeof(char) * strLength)];

// Frees the memory allocated.
[data release];
.

Working with binary files we can make great thing on our application. We can improve the security, we can create binary files to hold informations or even open the binary files of other softwares. The performance and size is really amazing! Few kilobytes can hold a bunch of informations.

Conclusion

top
Well, as you can imagine now, we can use binaries to many things: to improve our application's performance, for security improvements, for read and write files, the binaries are useful for many things. My last advice is: don't be shy, use and abuse of binaries! After I learned about the binaries I waited many months until I really started to explore them. Don't do the same, explore the binary power right now, as in The Matrix (movie), you'll start to see the bits behind the world!

So, let's remember from everything:

• Bits are the most basic representation of the electrical impulses on our computer boards.
• A Bit can be 0 or 1.
• One Byte has 8 Bits. Totalizing 256 different possibilities.
• Bytes can be combined to form powerful platforms: 16 bits, 32 bits, 64 bits and so on.
• Bitwise operators (&, |, ^ and ~) generate new bits with some changes on the original bit(s).
• Bit Shifts operators (>> and <<) generate new bits changing the position of the original bit(s).
• One pair of hexadecimal values can represent one byte.
• Every file on any computer is a binary file and can be read if you know the bit sequence.

Very well my friends, this is all about the binaries. As you saw, they are really simple, very simple and in reason of this simplicity the binaries are so powerful. If you have any doubt, just ask.

Thanks for reading,

See you soon.

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!

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!