On this article, let's talk about the Protocol Extensions and Protocol Oriented Programming (POP). There are lots of discussions on this subject, many comparisons between Swift Protocol Extensions and Multiple Inheritance. So let's discuss the difference between both and why POP sounds much more reliable.

The Chicken Problem

I like to use this example to illustrate how complex a small problem can become into a large scale development and a real world application. Let's first see the problem and then discuss it.

Imagine an application that we need to construct "objects/entities" of birds. At first glance, we'll have Perrots, Sparrows and Falcons. Let's now create a beautiful and smart code for that.

OOP & Multiple Inheritance

All those birds share many things, like a "beak", "feathers" and all of them can "fly". So let's think in the following architecture for our Birds App.

Looks Great! At this point, we as developers are super proud of our creation. It's clean, reliable, we made the code once, only one implementation of the "fly" method, which is a very complex algorithm.

Now, we made the Release 1 of the product. At this point the client (owner of the Bird Application) says: "Hey, you know what, I noticed that my customers would like to have a Chicken as well, so please add Chickens to this app, it should be very easy once you told me you have a very flexible architecture working with OOP"

Ok, that's easy... Chickens are birds, so it'll become one subclass of Birds... But wait... Chickens can't fly! So at this point do I need to override this "fly()" method and just negate all my beautiful algorithm from "Bird"?

Wait, by doing this I'm not just rewriting code, however if my beloved client decides that tomorrow he'll invent a new kind of super Chicken that can fly, what am I going to do? A new sub-class of "Chicken" negating my Chicken negation to "fly()"?

And if my client decides to move the app to the South pole and create Penguins? Penguins have no feather!

OMG... I just realized that my whole Architecture is not flexible enough for my client! Should I change it? Should I rewrite my whole application? Propose a V2? Should I change my client? Should I change to another planet where Birds are perfect and they all share the same characteristics?

Ok, ok... let's calm down. Let's try to think about possible solutions, after all, OOP is great and really can reflect the complexity of the real world.

Well, not exactly. We can try to struggle ourselves with the OOP solutions. I'll not get into deep on how many fail solutions we could try:

• Create two base classes: Bird and Flying Bird (FAIL: What if client decides to have Airplanes?)
• Use Protocols/Interfaces to define the Flying Method (FAIL: Re-writing a lot of code)
• Define "fly()" as a static method that receives an object that can fly (FAIL: What if I have millions of flying objects? Concurrency, multi-threading)

I've made this exercise with hundreds of different developers, letting them try many solutions. In short, the only possible solution to get out this problem in OOP is using Multiple Inheritance, however as we all know, it's hell dangerous. Only a few programming languages allow such feature and with many caveats in its own implementation. Pearl and Python use an ordered list for Multiple Inheritance, Java 8 tries to use the compiler to avoid errors, C++ is actually one of the only languages that really implements Multiple Inheritance in its full extension.

So, if you don't want to create a C++ module in your application just to solve that problem, let's try now using the Swift features solve that Chicken Problem.

Swift - Protocol Extensions

In short, The Chicken Problem is just a metaphor to a very common issue on software projects when two or more "objects/entities" share some common characteristics but completely differ in others. Especially in the current scenario for mobile projects, working with Agile, getting a constant feedback from the users, clients change its applications every day, which means that it can happen a lot during the maintenance of a product. So as developers, we need to construct architectures flexible enough to handle such changes.

At this point, using a good platform or programming language can help a lot to get out of those traps. At that point, Swift comes to the table with its Protocol Extensions feature. In many ways, it is compared to Multiple Inheritance, however without all the dangerous of Multiple Inheritance. Due to a single detail in this Swift feature, called Default Implementation. It means we can provide a default implementation for protocol properties and methods.

protocol MyProtocol {
    func methodOnProtocol()
}
extension MyProtocol {
    func methodOnProtocol() {
        print("Default Implementation of \(#function)")
    }
    func newMethodOnExtension() {
        print("Default Implementation of \(#function)")
    }
}

Knowing that, we can get back to the "Chicken Problem" and rewrite it, into a way that we code ONLY ONCE and still satisfying all the specific needs of Birds.

Look how flexible this can be. The Bird can still be a super class, no worries. But "fly()" and "feathers" become a Protocol with Default Implementations. Which means we CODE ONCE and we can make all kind of birds without rewriting any code.

Notice that even if our client goes crazy and says: "You know what, my Birds application know needs Airplanes, Kites and all kind of flying objects!". No worries, we built our architecture flexible enough to deal with that, because now instead of working with a single hierarchy chain in the polymorphism approach (more specifically Subtyping Polymorphism) we are now free to think as a child using Lego blocks (technically called Composition).

Protocol Oriented Programming (POP)

The Protocol Extension is something new, very powerful, we don't know to fully use it yet and yes, it has some caveats involved. We must practice it a lot in order to dominate this technique. It looks like Multiple Inheritance in some aspects but more sophisticated.

One of the best WWDC's video ever is the Crusty video, where Apple explain what are Protocol Extensions and Protocol Oriented Programming. I highly recommend watching this video:
https://developer.apple.com/videos/play/wwdc2015/408/

Chaing our mindset from OOP to POP requires a "leap of faith", we probably will find ourselves trying to solve problems using the OOP yet, take a deep breath, try to think as POP since the very beginning, try creating the architecture using POP before start coding.

Conclusion

Chickens can't fly, so the "Chicken Problem" stands for a common problem in software development, where objects/entities start sharing common features, however at some point they start diverging, becoming a completely different entity.

At this point, the traditional Polymorphism and it's single inheritance chain can't help. So at this point we need to be smart and using features such as Protocol Extensions and changing our mindset to Protocol Oriented Programming can help a lot to create a more flexible architecture and avoid refactoring whole applications just because the Client has been adding unexpected features.

That's the way the Agile world is today, we must adapt and change fast, especially in the Mobile Software Development.

Thanks for reading guys,
Please post your thoughts and comments bellow.

I'll start with a polemic phrase: "Swift is the future". I'm saying this phrase too. In this article I'll tell a little about why I take my hat off to Swift now. I'll cover few key points on Swift 2.0, like LLVM optimization, Generics Specialization, Value Syntax and Protocol Oriented Programming.

It's all up to the compiler

Yeah, It's truth that nothing on this old binary world can be faster than C. This statement remains, however... Swift is now running faster on runtime, why?

Not exactly faster than C, but faster than any application that we could create with pure C on our daily works. With tons of pure C code, hyper-optimized routines, we could create an application running so fast as Swift now, but it can become a monster, with a code impossible to manage across a large team of developers, with Seniors and Juniors in the same space.

This is the point when we all think the same:"well, to let every ordinary developer make the same rich code, we could have a compiler or framework good enough to create a hyper-optimized low level code and give an abstract high level that let all developers interact and create the state of art in terms of software performance while keeping the code readable to a large developer team". Well, this is the base idea behind Swift compiler.

It's all about the compiler... really. As we all know, the LLVM compiles the C and Objective-C code into a low-level Assembly that is then assembled to a machine code. LLVM do the same with Swift code, it compiles an assembly code in the last human readable phase of the whole compilation. At this point, the things become really interesting.

All the hard work necessary to create a super optimized code with C is now done by the compiler, without pain. The LLVM can infer so many things based on Swift code that would be insane to recreate the same performance in an ordinary project. But remember, this is a reality in Swift 2.0 with the implementation of all its new great features. Let's see more the new features that give Swift 2.0 such power.

LLVM and Chris Lattner

Chris Lattner was a promising compiler engineer since his early days at the college. Apple hired him at 2005 to work at LLVM compiler and at 2011 gave him a great opportunity: creating a new high-level language that could just work greatly with all his genius ideas on LLVM. With other few developers at Apple, Lattner started the Swift language that year.

Lattner arrived at Apple with high moral and a great responsibility. He corresponded really fast, taking LLVM and Clang to a higher level and he created language features like the C Blocks, a super optimized piece of code that can run extremely fast at runtime due to its treats with Stack memory. If you remember from iOS 4, the Blocks is which makes the GCD possible.

Lattner also contributed creating the ARC feature for Objective-C. As you can see, he is the responsible for the last 5 years of the most advanced features in the Apple development. About Swift, it is the biggest dream of Lattner. A curious thing: he started working on Swift at nights, at his home. For one and a half year he worked on Swift in secret, without telling anything at Apple, not even to his closest friends. Only on 2011 Chris revealed his secret to the top executives at Apple. They loved!

Apple designated few other developers to work on the Swift project and after another one and a half year, the Swift project became the greatest focus of Apple. Can you imagine what was that Lattner's dream? "Create a language that would soon change the world of computing", in the words of Wired magazine.

Just as the creators of C (Dennis Ritchie and Kenneth Thompson) changed the world of computing once, Chris Lattner is doing it again, at this time using the compiler's power!

Now the Apple part in this... I'm suspect to say this because I really love Apple, but let's just take a look how the Apple Marketing is great. The Google language GO appeared for the first time in 2009 and 6 years later and it doesn't even appear in the Top 50 at Tiobe Index nor in the communities. Swift is 1-year-old and it's reaching Top 10 at Tiobe (while Objective-C is in free fall from Top 5).
Tiobe Link

Well, of course there is a big difference between Go and Swift, Go also reach higher ranks at Tiobe during its launch, but come on... The Go was made by one of the creators of C and the Google is behind it, a successful combination that doesn't looks to be working that good. I dare to say that Swift is much more likely to change the "world of computing" that any other language today.

And now, Swift is Open Source, just as Mike Ash wished last year. ;)

Generics

One of the things I love most in Swift is Generics! How powerful this is for the developers. However for the Runtime the Generics was a time bomb.

In order to run reliable codes, the compiler should add a lot of checks and double checks to work with a Generic instruction. But no more in Swift 2.0. Again, "power to the compiler!" The LLVM can now infer much more things on our codes, not just looking at one file but looking at the whole project. By doing this, the compiler can create specific versions of our Generics, this is called Generic Specialization.

// Consider a Generic function
func maxFunc(x: T, _ y: T) -> T {
    if x < y {
        return y
    }
    return x
}

...

// In another file
var a = 4
var b:Int = 2 + 3
var c = maxFunc(a, b)

Now with Swift 2.0 the compiler can infer that the above code can be replaced by:

// Version generated by Generic Specialization
func maxFunc(x: Int, _ y: Int) -> Int {
    if x < y {
        return y
    }
    return x
}

With this optimized version, the compiler can guarantee a much higher performance during the RunTime.

This is the same concept applied many years ago to the duality of isEqual: and isEqualToString:. Both do the same job, you can use both on a NSString instance, but the second one can run faster, because it's specialized it can avoid uncessary checks.

Value Syntax

This one already exists in Swift 1.x, but now it's much better. The Value Syntax is the opposition to the Reference Syntax that is the one used for C pointers and consequently to Objective-C classes. The C struct and C basic data types use the Value Syntax, so nothing new here.

Just to remember, here is an example of both syntax:
(Objective-C code)

// Value Syntax, memory is copied.
CGRect rect = {0.0, 0.0, 100.0, 100.0};
CGRect rectVS = rect;

rect.size.width = 50;
rectVS.origin.x = 10;

NSLog(@"%@", NSStringFromCGRect(rect)); // Prints {{0, 0}, {50, 100}}
NSLog(@"%@", NSStringFromCGRect(rectVS)); // Prints {{10, 0}, {100, 100}}

// Reference syntax, memory is shared.
CGRect *rectRS = ▭

rect.size.width = 25;
(*rectRS).origin.x = 10;

NSLog(@"%@", NSStringFromCGRect(rect)); // Prints {{10, 0}, {25, 100}}
NSLog(@"%@", NSStringFromCGRect(*rectRS)); // Prints {{10, 0}, {25, 100}}

As you can see, the both have its usage and value. The thing is that on Objective-C you must know about C pointers and C data types in deep in order to correctly work with Value and Reference syntax. The new in Swift 2.0 is again the ability to infer things, so... "power to the compiler!"

The LLVM can infer much more based on your code and project files. It's able to determine if a variable/constant must use the value syntax or the reference syntax. By default Swift is Value Syntax-based, but you can use both styles if you want by changing the architecture of your code (like creating class wrappers) or by forcing a reference (using the inout instruction). For inout, guess what... the syntax for doing it is the same as in C, with "&". Great!

func fooSum(inout varA:Int, varB:Int)
{
    varA += varB
}

var a = 5
let b = 3
fooSum(&a, varB: b)
print(a)

Protocol Oriented

This is the last part I want to talk about, but I think this is the most exciting thing on Swift 2.0. Guess what, again it's a compiler thing: "power to the compiler!", but this time, it's so huge, it's a completely change of paradigm and can really change our way to code things.

The Swift 2.0 is now being called as a Protocol Oriented Programming, in counter-part to Object Oriented Programming. Why is that? Introduced in Swift 2.0, the Protocol Extension is what changes everything. With the power of the Where Clauses, this new protocol feature enable us to think about a whole new world without classes and polymorphism.

First off, as a side effect the Protocol Extension eliminates the Mocks on our tests, which I consider an ugly and unnecessary BTW. Mocks sucks, Protocol Extensions are great and can do the same thing. This is enough subject to other article, for now let's focus on how this new feature can change our world.

You already know that Value Types in Swift is great and powerful. Because the compiler can treat Enums, Structs and Classes at the same way at a lower-level, we can create functions, properties and extensions to all these types and get the same performance at runtime.

Just to illustrate how powerful this feature is, consider this: In Swift standard library, Arrays, Sets and Dictionaries are struct types (actually almost all in Swift standard library are Structs with many Extensions). All these 3 types share the same protocol CollectionType, well this protocol is also shared by many others, like String.

Let's say you want to create an extension to the Arrays and Sets. In Swift 1.x or even in Objective-C you could create a category (called extension in Swift) to the Array and another one to the Set, well you could start duplicating code in this scenario. Now, with Protocol Extensions you can create a single extension to the CollectionType and all the classes that implement this protocol gains the new function for free.

But wait, you may not want to give this function to all the CollectionType, because Dictionaries and Strings will have it too. No problems, with the Where Clause (aka Constraints) you can do it in one single line of code, defining that your protocol extension will act only on collections with a single element type.

Notice that Protocol Extension is completely different than creating Protocol Inheritance (or Hierarchy). The Hierarchy is like subclassing a class, which is nothing new and already exist on Obj-C. Swift calls Extension what we were used to call Category, so Swift 2.0 can create concrete and abstract categories to the protocols, which is completely different than Protocol Inheritance.

Take a moment to think how great this new feature is, it can break paradigms and open our world of possibilities. Some may say is isn't too much and they may think about how to achieve a similar behavior, coding once, in other languages. This is not the point here. Discussing a language is free of how much glue code you could use to achieve the same behavior. Discussing a language is how its syntax and paradigms can change our way to think and code.

This protocol feature in Swift 2.0 is enough to drive us outside the box of polymorphism and classes. Remember, classes try to illustrate the real world, but they have many problems, like the single chain and this is not how the real world works. Languages like C++ try to give classes a little bit more power with the Multiple Inheritance, but... OMG... you know that this attempt is probably one of the worst features ever.

In short, OOP was an attempt to recreate the real world structure and of course create new programming paradigms, but this is not how the real world works. Now with POP we have a new way to think, a new way to deal with the reality and transcribe real world things into our small programming world.

Conclusion

From this article, would be nice to remember few things:

• Swift performance comes from the compiler
• Swift 2.0 is about to change our paradigms
• Swift is the future

I'll start writing a series about Swift, talking about its new features, its secrets, sharing Playgrounds and algorithms. See you there.

There are a lot of talk out there about the Swift. As always, Apple reach the trend topics with its biggest announce: "a new programming language, I introduce you Swift".

I've seen people getting scared, screaming, jumping the window. Calm down people, my sincerely word for you is: Swift is GOOD! I'll explain here why Swift is a good thing and why you should not worry if you don't want to change.

As Swift still under the Apple's NDA, this IS NOT a tutorial about Swift, it's just a clarify and word of relief for the afflicted ones. But as soon as it goes live, I'll immediately post LOTS of tutorials about Swift.

The first important thing is: Do not get confused between Apple Swift, OpenStack Swift storage (http://swift.openstack.org), another scientific project called Swift Language (http://swift-lang.org) or any other references to the name "Swift", yeah, this name is too generic.

Well, there are 3 myths that Apple are trying to introduce to scare people that I'll demystify here:

1. Swift is faster than C and Objective-C (MYTH)
2. You can learn Swift faster than Obj-C (MYTH)
3. You can make everything with Swift (MYTH)

1st MYTH - Swift is Faster than C and Objctive-C

Apple shown this image in the WWDC 2014 keynote:

Despite the countless test I've made and saw others doing in performance field with Swift, I'll focus on something below the surface, something that really prove this image is a lie. (But just to let you know, in the performance tests, Obj-C still the winner).

Since the very begining of the computer science and technology, our human knowledge is limited by the physical materials. I mean, every single computer in this world operates on a plastic board, with circuits made with copper and other metals. The magic happens when very small eletrical impulses start running through the board. To these impulses there are only two possible values: or they exist (1) or they don't (0). This is the binary world, the Processor tracks those impulses countless times per second (well, of course it's not real countless, but you get the meaning).

The Quantum computer is a reality, but I'll not go deep in this subject, which is really the only way to take our current computer science to a new level. By changing the binary logic to another logic with -1, 0, 1 and everything between those values. Anyway...

So we know that working with bits is the fastest way to work with the traditional computers, because bits are the real processor's language. Now, you probably know that Obj-C as a superset of standard C and works with "pointers". I'll not go further in this subject too, but we all know that working with pointers is the way to direct slide through the bits in the memory, which means, working directly with bits. Back to the processor, nothing can be faster than working with bits in a traditional computer. So, the BEST a new language could achieve in performance is EQUAL to C, but never FASTER than C.

This is the first point: Nothing is faster than C in a traditional computer, just EQUAL in the best case.

But why Apple shown this graphic? It's a lie? Not exactly. As everything that Apple does, this image is a marketing piece intended to be used in their marketing WAR.

It's true that the greatest part of the developers doesn't know C and Obj-C structure in deep, which lead them to make mistakes, which lead the final app to have a poor performance. So to 90% of the apps, which are made by beginners, using Swift will avoid to make mistakes, avoiding bad performance and bad algorithims. So if you compare the app performance of an ordinary developer using Obj-C and Swift, yes, Swift will be faster. But if you compare the code of an experienced developer using Swift and Obj-C, nothing will really change, absolutely no performance gain. In fact, as many test have proved, the performance could even be worst, because Swift translation will never be smarter than a good C developer.

So, saying Swift is faster than Obj-C is a big LIE, but for Apple it's a marketing Weapon and will be used as that.

2nd MYTH - The learning curve is better in Swift

In a far future from now, maybe this phrase becomes true, but not now. Not even closer. You can't do everything with Swift. The Next Step legancy still until today and it's HUGE. There are so many frameworks in Apple that is using the NS base that is insane try to refactor everything. So Apple will just let it as it is.

Again, this means that for beginners and ordinary developers, Swift will do many things, but when you try to make something a little more sophisticated, like using the new Metal API (a 3D graphical lib, the new Apple competitor for OpenGL), you'll notice that Swift is not enough, because Metal is not even compatible with Swift. You must know and learn about Obj-C, C, MRC and everything else that Apple is trying to hide from us.

So, in a marketing perspective, Apple just make the first step in his development world a little bit easier, but as soon a new developer try to make a small feature similar to a great app, BAM... he will notice that there is no way to achieve that without go deep in the Obj-C world.

As soon as you start mixing Obj-C and Swift, you will find how exponential this learning curve can be. You'll need to learn two languages at once and learn how to mix them. As a marketing strategy for Apple, this can be dangerous.

3rd MYTH - You can make everything with Swift

As a consequence of what we discussed above, Swift is far from ready to do everything that Obj-C and C does. It does not have all the frameworks and its integration with Obj-C is not really a FULL integration.

Let me explain: the communication between Obj-C and Swift is made using a pre-compiled code that is taken by Xcode as Swift code. Apple called this feature of "Objective-C Bridiging", which is nothing else than a header for pre-compiling your Objective-C code. This means the Old C and the new Swift can live within the same project, but not within the same file as Obj-C and C could. (BTW, Swift has a new file extension ".swift", Apple always like to use long extension files, instead 2 or 3 letters). The backward already exist, Xcode automatically put a suffix in all your Swift classes and objects calling them as "-Swift".

Do you know why this "Objective-C Bridiging" can exist? Because the Apple compiler LLVM 6.0 converts all the Swift code to basic Obj-C/C code during the compilation. Yeah! So your app on iPhone still running the same kind of runtime, the same compiled code, Apple didn't change anything down there. This is another clue about the first MYTH (about Swift not being faster than Obj-C in real).

Just one more word about this subject, we can totally understand why Apple didn't change and probably will not change anything on runtime. I've been through few runtime changes in my life and I can say, it's very painful. AS2 to AS3 (Action Script), changing the runtime means completely give up of the current applications, means refactoring the entire project, which can kill thousands of business and companies. The old ASP.NET to .NET C#, these change was much more painfull than Flash.

Conclusion

• Is Swift cool? YES
• Will Swift grow fast? Probably
• Learning Swift will be fast? YES
• So can we give up Obj-C? NO

This is the bad news for beginners, they will must learn two languages instead of one. Doing ordinary apps anyone can do, PhoneGap and Titanium can do ordinary apps. But I'm not talking about this level, I'm talking about the real development, the one that can bring you awards, the one that can change things, the special ones, TOP apps. For this level, you can totally give up of Swift for now.

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.

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

You can download the template instead of doing it manually:

Download now
Xcode Template

Unzip it and place it at /Library/Developer/Xcode/Templates/Project Templates/
(create the path it needed)

FAQ

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?

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

• 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

1. Create the Project:

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

3. Create a Framework 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.

4. Bundle Setup:

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.

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)

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:

Building the Universal Framework

6. Creating Universal Target:

  
# 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}"  

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

Let's start a new series of tutorials, at this time let's go deep in shaders universe, the most exciting part of OpenGL programmable pipeline. We'll treat about textures, lights, shadows, per-pixel effects, bump, reflections and more.

This series is composed by 3 parts:

• Part 1 - Basic concepts about GLSL ES (Beginners)
• Part 2 - Shaders Effects (Intermediate)
• Part 3 - Mastering effects with OpenGL Shader Language (Advanced)

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

At a glance

We'll study in-depth the shaders language (more specifically the GLSL ES, the shader language for Embedded Systems) and let's make great effects using the shaders like specular lights and reflections, bump maps, refractions, reflections and more.

In this first part I'll cover the basic concepts sobre shaders and GLSL ES. We'll need to drill deep in something called Tangent Space, which is an intermediate level, so I'll create an article between the part 1 and 2 specific to treat Tangent Space concepts and its creation.

In the second part let's start creating some interesting effects like specular lights, reflections and refractions. Besides, on the second one let's create the environment mappings by using the cube texture.

Finally in the last part let's make the most advanced effect, the bump mapping and see what is the difference between Normal Mapping, Bump Mapping and Parallax Mapping.

Hands to work!

Shading Types

Once upon a time, there was a single shading technique, called Flat Shading. It defines that light is computed with the normal vector and each FACE of the mesh has a normal vector. The term "FACE" here means a polygon (usually a triangle).

With the evolution of the hardwares we start to process values for each vertex, this improvement took us into a new level, making more light effects. This shading technique was called Goraud Shading.

Then we discovered something that produces really nice results, the interpolation. It's a process which we calculate all the intermediate points between two other points. We use it all the time. For example, if a point A has a texture coordinate U:1 V:2 and a point B has U:2 V:5, the interpolation will calculate all the middle points from 1,2 to 2,5. This is know as Phong Shading.

But for many reasons, to simulate the real world, we need more than a linear interpolation. Surfaces have many details that change the way the light and shadow reacts. So we discovered a way to produce infinities values over a surface using less processing time. This technique was called Bump Shading.

Today we have some advanced Bump's techniques, but all of them have the same basic concept: store each value surface deformation value as a set of RGB color. So, basically, the Bump Shading takes advantage of a texture map that store coordinates within a RGB format. The coordinates in there can be used for many things: Normals, Tangents, Bitangents, Vertices positions or anything else we want. Usually the textures for Bump Shading is called Normal Maps, because we store the Normal Vector value in it.

By default, OpenGL uses the Phong Shading, making the interpolations between the Vertex Shader's outputs and Fragment Shader's inputs. This information is very important, so I'll repeat: "Vertex Shader's outputs are interpolated to Fragment Shader's inputs". Technically, this is what happens:

OpenGL Shaders

• Shader is the way to calculate everything related to our 3D objects by our own (from the vertices positions to the most complex light equations).
• Vertex Shaders (VSH) are processed one time for each object's vertex. Fragment Shader (FSH) are processed one time for each fragment (not necessarely a pixel) of the visible object (http://blog.db-in.com/all-about-opengl-es-2-x-part-1).
• You can set constant values for Uniforms to work throughout the VSH and FSH processing (http://blog.db-in.com/all-about-opengl-es-2-x-part-2).
• Dynamic variables can be assigned only to the Attribute kind, which is exclusive of VSH. You can send a variable from VSH to FSH via Varyings, but remember that those values will be interpolated!

The shaders are small pieces of code that will be processed directly in the GPU. Unfortunately, even in these days (2011) our hardwares are very poor and slow if compared with the real amount of calculations that exist in the real world. The most advanced hardware trying to calculate a real phenomenon of the sun light passing through the water in a pool could take days to calculate a single frame. In the other hand, the real nature calculates all physical phenomenon instantly (OK, the mother nature makes a kind of "calculation", not exactly an equation).

While we stay on the "Era of Bits" we can't try to calculate the real phenomenons (I wrote an article about the "Binary World" where I talked about the new Era of Quantum computers, maybe there, in the "Era of Quantums", we'll be able to reproduce our 3D world closest from the reality).

Anyway, what I meant is that the shaders are something trying to reproduce the real world with a very very abstractly code, making a bunch of simplifications of the real world. So if you want to mastering the shader, you must learn to extract some abstract pieces of code from the real world phenomenons. But don't worry too much about it now, in the right time you'll see that it's an easy task and can be cool as well.

It's important to start thinking in the concept of "Shader Program". It's a set of 2 (and only 2) shaders: a vertex shader and a fragment shader. So, we must think in the render as 2 different steps (vertex and fragment). Usually the Fragment shader is processed a lot of times more than the Vertex one. If a mesh has 10.000 vertices that means its Vertex Shader will generate 10.000 outputs to the Fragment Shader. Remember that those outputs will always be interpolated to the Fragment processing. So, to increase the performance we always try to place hard calculus in the Vertex Shader. Obviously there are calculus that we can't accept interpolation to their values, like the bump effect, just in these cases we make the calculus inside the Fragment Shader.

However, make sure you got the correct distinction between the concept of making the calculus inside the Vertex Shader and another thing called Per-Vertex/Per-Fragment Light. We'll see those concept in-depth later on, but just to clarify:

• Per-Vertex Light means you have all the light calculus inside the Vertex Shader and them you interpolate the result to Fragment Shader.
• Per-Fragment Light means you have all last light calculus (the output value) inside the Fragment Shader, independent if the first steps was made in the Vertex or in the Fragment Shader.

The interpolation happens on all Vertex Attributes, like the Texture Coordinates. As shown above in the Interpolation Table, the interpolated values from a texture coordinate can retrieve all the pixels from a texture. The Texture Coordinates usually is defined by a technique called "UV Map" or "UV Unwrap Map", which is an artistic job, actually is almost impossible to create detailed UV Maps only with the code. Often a professional 3D software export the Texture Coordinates values within the model coordinates, based on definitions from an user friendly UV editor.

But there is another per-vertex Attribute very important to 3D world. With the shaders we calculate lights, shadows, reflections, refractions and any other effects we want. All of them need something in common, a Normal vector.

Normal Vector

In simple words, the normal vector is an unit vector (magnitude equals to 1.0 and all axis range vary between [0.0, 1.0]) which represents the surface's angle. Nice, now, how we can calculate it?

Well, that's not an easy task, my friend. I had to read/watch/try a bunch of tutorials until I found the right formula. There are many people trying to teach how to calculate the normals. Some say that you must calculate per-face normals and store them into a buffer, others say to calculate the averaged normals between adjacent faces, some even say that you need to calculate each surface area to include in your final calculation. But no one gave me the right formula! I had to find it by my self, with the help of a great 3D software called MODO (by the way, I love it!).

Unfortunately, I'll not explain how to calculate the normals in this first tutorial. I'll create a separated article to show you how to get the right formula to calculate the normals. The normals deserve more attention than a simple subject inside one tutorial.

The most valuable point here is you understand that the Normal is an unit vector and visualize how the normals work together and how they fit into our shaders' context.

Normal's Smooth Angle

Try to imagine the smallest face/triangle that composes that bowling ball. Even if we try to use a microscope, we never will see a faceted area. Now take a look at our virtual spheres, even if we create a 3D mesh using a stupidly high resolution of 8 millions polygons, we'll stay very very far from the perfection of the real world. By the way, for our 3D applications and games, we must work around thousands polygons, not millions. Does that means our 3D lights will seem ugly on low meshes? Fortunately we have a solution.

This problem can be solved with the Normal's Smooth Angle. With simple words, it represents the maximum angle on which the light will looks continuous when reflected by a surface. The following picture helps us to understand this point better:

Remember that smooth angle should be calculated when we calculate the Normals, so any post-change to the smooth angle will affect the entire Normals. I'll talk more about the smooth angle in the article of the Normals calculations.

Tangent Space

The Tangent and Bitangent are unit vectors, just as the Normal, the combination of these three components must form an Orthogonal and Orthonormal set. Before we go ahead, let me explain in simple words these two concepts:

• Orthogonal: Two vectors that are perpendicular (form an angle of 90 degrees).
• Orthonormal: A set of vectors that are all Orthogonals and unit vectors.

OK, these set of three vectors called Tangent Space is defined per-vertex. It's purpose is define a local space for each face/vertex, which will be used to interpret the surface's imperfection (bump map). The bump map (also known as normal map) is a RGB map that defines each relief of the surface.

It could sound confused to a text explanation. Just try to imagine this, as we always optimize everything in 3D world, the bump map is a technique that stores the surface's deformations into a single image file. The Tangent Space is a set of vectors that allow us to parse the bump informations for each fragment, independent of the mesh's rotation, position or scale. The following image illustrate the Tangent Space and its connection with the Texture Coordinates.

Basically the Tangent Vector points to where the "S" coordinate increases (S Tangent) and the Bitangent points to where the "T" coordinate increases (T Tangent).

It's possible to exist more than a Tangent Space for a single vertex, in this case the vertex will break into two or more vertices with the same value for position, actually there are other important concepts in Tanget Space, but I'll not bother you with the details in here. Just as the Normal's calculations, I'll let this complex part to another article dedicated to that subject. The important thing here is to you understand what is the bump maps and how the Tangent Space is important to make bump effects.

Texture Coordinates

The texcoord have more to do with the artistic work than with our code, usually the 3D softwares are responsible for generating it. The texcoord will directly affects how the texture image file should be created, I mean, the image of the texture must be created based on the texcoord positions. There are some 3D softwares that accept multiple texcoord channels. It could be good for some situations which multiple designers are working together, but it's not good to the performance and optimization. There is nothing that multiple texcoord channels can make that a single channel can't. So, keep it simple, always try to work with a single texcoord channel.

The texcoord is very important to create the Tangent Space. Multiple texcoord channels will need multiple Tangent Spaces as well. So, multiple channels is never a good idea.

Conclusion

In this tutorial you saw:

• The Shaders are responsible for all the visual results of our 3D world, including lights, shadows, reflections, refractions, etc.
• There are four shading techniques most used: Flat Shading, Goraud Shading, Phong Shading and Bump Shading. OpenGL by default will use the Phong Shading.
• The values from Vertex Shader to Fragment Shader will always be interpolated.
• We have 3 very important per-vertex vectors: Position, Normal and Texture Coordinate.
• The Normal Vector + 2 others form the Tangent Space, fundamental concept to produce the Bump Shading and any other displacement technique (like the Parallax Mapping).
• Always try to use only one texcoord channel.

Well done!
My next article will not be the second part of this series, instead, it'll be a short article covering how to calculate the Normal Vector and the Tangent Space. We'll need to have those vectors very correct before enter in the real calculus inside the shaders' world.

If you have any doubts, just Tweet me:

Tweet

See you soon!

It's a great pleasure to present a new part of my work. This one is a piece of a framework intended to be used in the daily job. To make many things, make your life easier and programming faster. Today I wanna show you the NPPTransition, an API to make custom animations and transitions between UIView and/or UIViewController using pure native Objective-C (aka Obj-C).

Just by importing it you can change all the transitions (push and modal) of your application, even without writing a single line of code. Let's talk about it.

At a glance

First of all, it's an Open Source, here are the links to download it:

Download now
Source + Sample
1.4Mb

Bitbucket
Git Project

And this is the official web page: http://db-in.com/nippur/transition

What it does?

Well, I prefer to show you:

This video is from the sample code. These transitions are happening between UIViewController and UINavigationController. Every transition can be customized, there is also a global setting. Besides, any UIView can be animated to other UIView.

How it works?

The first important thing to understand is that it's completely "iOS version free". What exactly that means. It means it does not lie on the UIKit framework, that changes a lot from version to version (which is sucks, BTW). It completely lies on the QuartzCore and CoreGraphics frameworks, besides those frameworks are also used for desktop development (Cocoa for Mac OS). So it can easily be used for Mac OS development as well.

First, it creates a solid base that deals with the sizes and positions of the views. Then a "snapshot" of the views is taken as images, these images are used to make the animation/transition. At this point all the responsibility by the animation/transition is up to the subclasses. After the animation, the task returns to the main base that deals again of how to place, remove, show or hide the final views in its places.

By default, the NPPTransition uses a category trick to replace the normal iOS behavior, it swizzles the UINavigationController and UIViewController methods to make its magic.

There is just two steps to get it working on your project:

1. Import the source folder "Nippur" or the "Nippur.framework" on your project (drag and drop). Also make sure the QuartzCore and CoreGraphics frameworks are within your project.
2. In project's prefix file (.pch) write accordingly to your importing:

It's done!
Now just build and run your project to see what happens. If you try this into an existing of your projects you'll how different the things will goes on.

Using the NPPTransition

Despite by default it's using a category trick to replace the transitions, you can turn this feature ON or OFF as you wish and you can do it individually just for Push or for Modal transitions. Here is how it goes:

  
// To turn ON/OFF the category feature for push transitions.
[NPPTransition definePushTransitionCategoryUsage:NO];

// To turn ON/OFF the category feature for modal transitions.
[NPPTransition defineModalTransitionCategoryUsage:YES];

As it happens automatically, you can also define some other default settings:

  
// To define the push transition class.
[NPPTransition definePushTransitionClass:[NPPTransitionFold class] direction:NPPDirectionDown];

// To define the modal transition class.
[NPPTransition defineModalTransitionClass:[NPPTransitionTurn class] direction:NPPDirectionUp];

// To define the default duration for all transitions.
[NPPTransition defineTransitionDuration:1.0f];

As you noticed, the transition happens inside a subclass. It's the one responsible for custom animations and all the basic parameters still the same because the NPPTransition abstract class has defined them.

Now you may ask: "Ok, but if I turn OFF the category feature, the animations will happen automatically?". No, in this case you should manually replace the push, pop, present or dismiss methods for the correlated ones of NPPTransition. But don't worry, it's very easy to find them, they start with the letters "npp"

  
// Instead of:
[myViewController pushViewController:otherController animated:YES];
// Use now:
[myViewController nppPushViewController:otherController animated:YES transition:nil];

// ---

// Instead of:
[myViewController presentViewController:otherController animated:YES completion:nil];
// Use now:
[myViewController nppPresentViewController:otherController animated:YES transition:nil];

// ---

// And so on...

If you set the transition as "nil" the default class for that kind of transition (push or modal) will be used in place. For example, following the two parts of codes above, our push transition will NPPTransitionFold and the modal transition will be NPPTransitionTurn.

Now, if you set a specific transition, it will be respected, regarding the specific parameters for the transition you're asking, that means, the NPPTransition properties "fromView", "toView" and "backward" will be ignored. Because those parameters are specific to each ViewController and its current state.

  
NPPTransitionFold *fold = [NPPTransitionFold transitionWithcompletion:nil];  
[[self presentingViewController] nppDismissViewControllerAnimated:YES transition:fold];

As you noticed, all the NPPTransition has a completion block, that means you can get a completion notification for any kind of transition (push or modal).

And what about minor animations, like animating two objects inside a view?
It's very easy to do as well.

  
// Creating a custom transition.
NPPTransitionCube *cube = [NPPTransitionCube transitionFromView:aViewInStage toView:aNewView completion:nil];  
cube.direction = NPPDirectionDown;  
cube.mode = NPPTransitionModeOverride;  
[cube perform];

// Preparing it to goes back after 2 seconds.
[cube performBackwardAfterDelay:2.0f];

Conclusion

Very well my friends, that's it. There are a lot more in the sample project. Get it by downloading the zip or copying the Git project.

If you have any doubts, just Tweet me:

Tweet to @dineybomfim

See you soon!

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

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

Let's start!

At a glance

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

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

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

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

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

Here is a features' list.

Importing 3D files

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

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

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

Caching 3D files

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

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

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

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

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

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

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

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

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

Custom Shaders

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

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

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

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

Calculating Normals and Tangent Space

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

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

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

Optimizing Textures

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

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

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

Many other things

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

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

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

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

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

Outside the Scope

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

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

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

Conclusion

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

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

Thanks for reading,

And see you very soon!

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!

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

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.

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!

In this article I'll talk about a very very important part of the 3D world. As you already know, this world behind of our devices' screen is just an attempt to recreate the beauty and complexity of the human eye. To do that we use cameras, which is in the real world the simulation of the human eye. To construct cameras we use mathematical equations.

Here is a little list of contents to help you to find something you want in this tutorial.

At a glance

First let's see the basic about cameras, how it works in real world, the lens differences, how a zoom works, translations, rotations and some similar concepts. Right after consolidate these concepts let's enter deeply in the OpenGL and understand how all of that can fit in our application. So we finally go to the code, I'll give you the equations and explain how they work.

Do you remember from my OpenGL serie of tutorials when I said that Khronos has delegated many responsibilities and got focus on the most import part of the 3D world? (more precisely from the part 1, if not, you can check it here) Well, from OpenGL ES 1.x to 2.x the cameras was one of those responsibilities that Khronos delegated. So now we must to create the cameras by ourselves. And wanna know? I Love it! With the shaders behavior we can have an amazing control on our applications, more than this, we are free to construct awesome 3D engines.

With the OpenGL controlling the cameras, we had only two or three kinds of cameras. But when we started programming the cameras by ourselves, we are able to create any kind of cameras. In this article I'll talk about the basic cameras: Orthogonal Camera and Perspective Camera.

OK, let's start!

Cameras in the real world

The final image depend on many factors, not just the type of the lens, but in general words, the image bellow shows how a picture looks like behind each kind of lens.

Both kinds could produce an image equal to the original one, I mean, with a tiny angle of distortion, depending on the distance of the object from the lens and the angle of view. The next image will show the most important attributes of a camera.

The red areas in the image above are not visible to the camera, so any fragment in those areas will be clipped. The "Depth of Field" is the visible area, all fragments inside it will be visible. Commonly the word "Depth of Field" is also used to describe an special effect, the effect of Lens Blur. As the human's eyes have focus which make the object outside the focus seems blurred, the Lens Blur effect simulate that focus, making objects outside the focus seems blurred. So why I didn't put the attribute "Focus" on the image above? Because the focus is a special feature in just some cameras, the basic cameras in 3D doesn't implements focus behavior. The other important attribute is the "Angle of View", which represents the horizontal angle visible to the camera. Any fragment outside this angle will not be visible to the camera. Some times this "Angle of View" is also used to represent the vertical area, but usually we prefer to define the aspect ratio of the final image using the width and height.

The modern cameras are very accurate and can produce awesome effects using that attributes and combining the lenses types. Now let's back to our virtual world and see how we can transpose those attributes and behaviors mathematically. But before moving to the 3D cameras, we need to understand a little bit more about the maths in 3D world.

Short history about 3D world

Advancing many years ahead in our Time Machine, we out in the beginning of 17th century, where a great man called René Descartes created something called cartesian coordinate system. That was amazing! It has created the bridge between the Euclid's theory and the linear algebra, introducing the matrices into Euclidean Transformations (translate, scale and rotation). Euclidean Transformations was made with traditional Pythagoras approaches, so you can imagine how many calculations was there, but thanks to Descartes we are able to make Euclidean Transformations using matrices. Is simple, is fast, is pure beauty! Matrices in the 3D world are awesome!

But the matrices with Euclidean Transformations were not perfect. They produce some problems, the biggest one is related to rotations and is called Gimbal Lock. It happens when you try to rotate a plane and unintentionally the other two planes touche themselves, so the next rotation of one of those two planes will produce the Gimbal Lock, that means, it will involuntary rotate both locked axis. Many years later another great man called Sir William Rowan Hamilton, in 1843, created a method to deal with Euclidean Rotations and avoiding the Gimbal Lock, Hamilton created something called Quaternions! Quaternion is faster, better and the most elegant way to deal with 3D rotations. A Quaternion is composed by an imaginary part (complex number) and a real part. As in the 3D world we always use calculations with unity vectors (vectors with their magnitude/length equals to 1) we can discard the imaginary part of Quaternions and work only with the real numbers. Precisely, Quaternions was a Hamilton's thesis which include much more than just 3D rotations, but to us and to 3D world, the principal application is to deal with rotations.

OK, what does all of that have to do with cameras? It's simple, based on all this we start using 4x4 matrices to deal with Euclidean Transformations and use a vector with 4 elements to describe a point the space (X,Y,Z,W). The W is an Homogeneous Coordinate element. I'll not talk about it here, but just to let you know Homogeneous Coordinates was created by August Ferdinand Möbius in 1827 to deal with the concept of infinity in the Cartesian System. We'll talk about Möbius contribuition later on, but shortly, the concept of infinity is very complex to fit into the cartesian system, we could use an complex imaginary number for it, but this is not so good to real calculations. So to solve this problem, Möbius just added one variable W, which is a real number, and took us back to the world of real numbers. Anyway. The point is that a matrix 4x4 fits perfectly with vector 4 and as we use a single matrix to make the Euclidean Transformations into our 3D world, we think that it could be a good idea to use the same 4x4 matrix to deal with a camera in the 3D world.

The image above shows how a Matrix 4x4 and a Quaternions looks like visually. As you saw, the matrix has 3 independent slots for translation (position X,Y,Z), but the other instructions are mixed in its red area. Each rotation (X,Y and Z) affects 4 slots and each scale (X,Y and Z) affects 1 slot. A quaternion have 4 real numbers, 3 of then represent vertex (X,Y and Z) and this vertex forms a direction. The fourth value represents the rotation around its own pivot. We'll talk about quaternion later, but one of its coolest features is that we can extract a rotation matrix from it. We can do so by constructing a Matrix 4x4 with only the yellow elements filled up.

You could think now: "WTF!". Calm down, the practice is not so hard as the theory! Before put hands on code, we need to take just one more concept: the projections.

Projections

Did you see? It's very simple, the Orthographic projection is commonly used in 2D games, like Sim City or The Sims (old versions) or even the best seller Diablo (except the new Diablo III, which is really using the Perspective projection) . The Orthographic projection doesn't exist in real world, it's impossible to the human's eyes receive the images at this way, because there is always has a vanish point on the images formed by our eyes. So the real cameras always capture the image with a Perpective projection.

Many people ask me about 2D graphics with OpenGL, well, here is my first tip about how to do it, you will need an Orthographic projection to create games like Sim City or The Sims. Games like Starcraft use a Perpective projection simulating an Orthographic projection. Is it possible? Yes! As everything related to a lens behavior, the final image lies on many factors, for example, a Perpective projection with a great Angle of View could seems more like an Orthographic projection, I mean, it's like to look to the ground from an airplane on air. From that distance, the cities look like a mockup and the vanish point seems no effect.

Before continuing we need to make a little digression to understand in deep the difference between those two projections. You remember from René Descartes and its cartesian system, right? In the linear algebra two parallel lines never touch, even at the inifity. How we could deal with the infinity idea in the linear algebra? Using calculations with ∞(infinity denotation)? It's not useful. To create a Perspective projection we really need a vanish point and with it two parallel lines must touch at the infinity. So, how we can solve that? We can't! At least not using the linear algebra knowledge. We'll need something else.

Thanks to a man called August Ferdinand Möbius we can deal with this little problem. This man created something called "Homogeneous Coordinates". The idea is incredibly simple, is unbelievable (just as I like). Möbius just add 1 last coordinate number to any dimensional system the coordinate w. The 2D becomes 2D + 1 (x,y -> x,y,w), the 3D becomes 3D + 1 (x,y,z -> x,y,z,w). In the space calculations we just divide our original value by w, just it! Look at this pseudo code:

The w will be 1.0 in the majority of cases. It will change just to represent the ∞ (infinity), in this case w will be 0.0! "WTF!!! Divisions by 0?" Not exactly. The w is often used to solve systems of two equations, so if we got a 0, the projection will be sent to the infinity. I know, seems confused in theory, but a simple practical example is the generation of shadows. When we have a light in a 3D scene, a light at the infinity or without attenuation, like a sun light in 3D world, we can simple create the shadows generated by that light using the w equals to 0. At this way the shadow will be projected on a wall or a floor exactly as the original model is. Obviously the lights and shadows in the real world in stupidly more complex than this, but remember that in the our virtual 3D world we are just kidding of copy the real behavior. With some few more steps we can simulate a shadow behavior more realistic, this is very good to a professional 3D software implements in its render, but to a game is not a good solution, more realistic shadow takes a lot of processing on the CPU and GPU. To a game, casts the shadows using the Möbius is pretty simple and looks very nice to the player!

OK, this is all about Projections, now let's move to the OpenGL and see how we can implement all these concepts with our code. Matrices and Quaternions will be our allies.

Cameras in the 3D world

Thereby, when we rotate an object on the screen, in deeply, what we are doing is creating a matrix which contains information to make that rotation factor happen. Then in our shaders, when we multiply that matrix by the vertices of our object, on the screen, the object seems to be rotating. The same is true for any other 3D elements, like lights or cameras. But the camera object has a special behavior, all the transformations on it must be inverted. The examples below can help to understand this issue:

Notice in the pictures above that the resulting image on the device's screen is the same in both cases. This behavior drives us to an idea: every camera movement is inverted compared to the object space. For example, if the camera goes into +Z axis, this will produce the same effect as sending the 3D object to -Z axis. Rotate the camera in +Y will have the same effect as rotating the 3D object in its local -Y axis. So hold this idea, every transformation at the camera will be inverted, we'll use this soon.

Now the next concept about camera is how to interact the local space with the world space. In the examples above, if we think in rotating the object to -Y in local, this will produce the same results as rotating the camera at +Y and moving it in X and Y axis around the object, assuming the camera as the pivot. To deal with it, again the operations with matrices will save our day. To change from local space rotations to global space rotation all that we need is to change the order of the matrices in a multiplication (A x B = local, B x A = global, remember the matrices multiplication is not commutative). So we must multiply the camera's matrix by the object's matrix, in this order.

OK, I know, techniques seem very confusing, but trust me, the code is much simpler than you imagine. Let's review those concepts and dive into code.

• We never change the object structure, what changes is just some matrices, which will be multiplied by the original object's structure to achieve the desired result.
• On the camera, all transformations should be inverted before to construct the matrix.
• As the camera will be our eyes in the 3D world, we assume the camera is always the local space, so the final matrix will be the resulting of CameraMatrix X ObjectMatrix, in this exactly order.

The code behind the 3D world

• Recommended book: Mathematics for 3D Game Programming and Computer Graphics.
• WebSite:http://www.euclideanspace.com

The EuclideanSpace website has not a good layout, I know, it seems a little amateur, but trust me, all formulas in there are very reliable, ALL the formulas. Navigation is made by the top menu, it could seems confused at a glance, but it's very organized, thinking mathematically.

OK, so let's start with the matrices.

Matrices

Using a linear unidimensional array we could represent a matrix by two ways, row-major or column-major. This is just a convention, because in reality pre-multiply a row-major matrix or post-multiply a column-major matrix produces the same result. Well, as OpenGL prefers a column-major notation, let's follow this notation.
That is like the array indices are organized with a column-major notation:

  
.
    |    0        4        8        12   |
    |                                    |
    |    1        5        9        13   |
    |                                    |
    |    2        6        10       14   |
    |                                    |
    |    3        7        11       15   |
.

Now I'll show separately 5 kinds of matrices: Translation Matrix, Scale Matrix, Rotation X Matrix, Rotation Y Matrix and Rotation Z Matrix. Later we'll see how to join all these into one single matrix.

The most simple operation with 4x4 matrices is the translation, changing the X, Y and Z position. It's very very simple, you don't even need a formula. Here is what you need to do:

  
.
    |    1        0        0        X    |
    |                                    |
    |    0        1        0        Y    |
    |                                    |
    |    0        0        1        Z    |
    |                                    |
    |    0        0        0        1    |
.

The second stupidly simple operation is the scale. As you may have seen in 3D professional softwares, you can change the scale individually to each axis. This operation doesn't need a formula. Here is what you need to do:

  
.
    |    SX       0        0        0    |
    |                                    |
    |    0        SY       0        0    |
    |                                    |
    |    0        0        SZ       0    |
    |                                    |
    |    0        0        0        1    |
.

Now let's complicate it a little bit. Is time to make rotation with a matrix around one specific axis. We can think about rotations in the 3D world using the Right Hand Rule. The right hand rule defines the positive directions of all the 3 axis, besides it defines the rotations order as well. Align your thumb along a positive direction on an axis, now close the other fingers then the direction that your fingers are pointing to is the positive rotation of that axis:

We can create a rotation matrix using only one angle in one axis. To do that, we'll use sines and cosines. As you know, the angles should be in radians, not in degrees. To convert degrees to radians we use: Angle * PI / 180 and to convert from radians to degrees we could use: Angle * 180 / PI. Well, my advice here, to gain performance, is: "let the PI / 180 and 180 / PI pre-calculated". Using C macros, I like to use something like this:

  
// Pre-calculated value of PI / 180.
#define kPI180     0.017453

// Pre-calculated value of 180 / PI.
#define k180PI    57.295780

// Converts degrees to radians.
#define degreesToRadians(x) (x * kPI180)

// Converts radians to degrees.
#define radiansToDegrees(x) (x * k180PI)

OK, so with the values of our rotations in radians, is time to use the following formulas:

  
.
    |    1        0        0        0    |
    |                                    |
    |    0      cos(θ)   sin(θ)     0    |
    |                                    |
    |    0     -sin(θ)   cos(θ)     0    |
    |                                    |
    |    0        0        0        1    |
.

  
.
    |  cos(θ)     0    -sin(θ)      0    |
    |                                    |
    |    0        1        0        0    |
    |                                    |
    |  sin(θ)     0     cos(θ)      0    |
    |                                    |
    |    0        0        0        1    |
.

  
.
    |  cos(θ)  -sin(θ)     0        0    |
    |                                    |
    |  sin(θ)   cos(θ)     0        0    |
    |                                    |
    |    0        0        1        0    |
    |                                    |
    |    0        0        0        1    |
.

Maybe you have seen the same formulas in other places with different minus signal in the elements, but remember, often they teach the traditional mathematical way, which uses the row-major notation, so remember here we are using the column-major notation, which fits right within OpenGL process.

Now it's time to join all of those matrices together. Just as a literal number, we need to multiply each one to get the final result. But the matrix multiplication has some special behaviors. You probably remember some of them from your high school or college.

• Matrix multiplication is not commutative. A x B is different than B x A.
• Multiplying A x B is a calculation of the multiplication from each value of A rows by each value from B columns.
• To multiply A x B, A matrix MUST have the number of columns EQUAL to the number of rows in B. Otherwise, multiplication can't be made.

Well, in the 3D world we always have square matrices, 4x4 or in some cases 3x3, so we can multiply a 4x4 only for other 4x4. Now, let's dive into the code using an array of 16 elements to compute all the above formulas:

  
typedef float mat4[16];

void matrixIdentity(mat4 m)  
{
    m[0] = m[5] = m[10] = m[15] = 1.0;
    m[1] = m[2] = m[3] = m[4] = 0.0;
    m[6] = m[7] = m[8] = m[9] = 0.0;
    m[11] = m[12] = m[13] = m[14] = 0.0;
}

void matrixTranslate(float x, float y, float z, mat4 matrix)  
{
    matrixIdentity(matrix);

    // Translate slots.
    matrix[12] = x;
    matrix[13] = y;
    matrix[14] = z;   
}

void matrixScale(float sx, float sy, float sz, mat4 matrix)  
{
    matrixIdentity(matrix);

    // Scale slots.
    matrix[0] = sx;
    matrix[5] = sy;
    matrix[10] = sz;
}

void matrixRotateX(float degrees, mat4 matrix)  
{
    float radians = degreesToRadians(degrees);

    matrixIdentity(matrix);

    // Rotate X formula.
    matrix[5] = cosf(radians);
    matrix[6] = -sinf(radians);
    matrix[9] = -matrix[6];
    matrix[10] = matrix[5];
}

void matrixRotateY(float degrees, mat4 matrix)  
{
    float radians = degreesToRadians(degrees);

    matrixIdentity(matrix);

    // Rotate Y formula.
    matrix[0] = cosf(radians);
    matrix[2] = sinf(radians);
    matrix[8] = -matrix[2];
    matrix[10] = matrix[0];
}

void matrixRotateZ(float degrees, mat4 matrix)  
{
    float radians = degreesToRadians(degrees);

    matrixIdentity(matrix);

    // Rotate Z formula.
    matrix[0] = cosf(radians);
    matrix[1] = sinf(radians);
    matrix[4] = -matrix[1];
    matrix[5] = matrix[0];
}

And here is the code for a multiplication of two 16 arrays representing 4x4 matrices.

  
void matrixMultiply(mat4 m1, mat4 m2, mat4 result)  
{
    // Fisrt Column
    result[0] = m1[0]*m2[0] + m1[4]*m2[1] + m1[8]*m2[2] + m1[12]*m2[3];
    result[1] = m1[1]*m2[0] + m1[5]*m2[1] + m1[9]*m2[2] + m1[13]*m2[3];
    result[2] = m1[2]*m2[0] + m1[6]*m2[1] + m1[10]*m2[2] + m1[14]*m2[3];
    result[3] = m1[3]*m2[0] + m1[7]*m2[1] + m1[11]*m2[2] + m1[15]*m2[3];

    // Second Column
    result[4] = m1[0]*m2[4] + m1[4]*m2[5] + m1[8]*m2[6] + m1[12]*m2[7];
    result[5] = m1[1]*m2[4] + m1[5]*m2[5] + m1[9]*m2[6] + m1[13]*m2[7];
    result[6] = m1[2]*m2[4] + m1[6]*m2[5] + m1[10]*m2[6] + m1[14]*m2[7];
    result[7] = m1[3]*m2[4] + m1[7]*m2[5] + m1[11]*m2[6] + m1[15]*m2[7];

    // Third Column
    result[8] = m1[0]*m2[8] + m1[4]*m2[9] + m1[8]*m2[10] + m1[12]*m2[11];
    result[9] = m1[1]*m2[8] + m1[5]*m2[9] + m1[9]*m2[10] + m1[13]*m2[11];
    result[10] = m1[2]*m2[8] + m1[6]*m2[9] + m1[10]*m2[10] + m1[14]*m2[11];
    result[11] = m1[3]*m2[8] + m1[7]*m2[9] + m1[11]*m2[10] + m1[15]*m2[11];

    // Fourth Column
    result[12] = m1[0]*m2[12] + m1[4]*m2[13] + m1[8]*m2[14] + m1[12]*m2[15];
    result[13] = m1[1]*m2[12] + m1[5]*m2[13] + m1[9]*m2[14] + m1[13]*m2[15];
    result[14] = m1[2]*m2[12] + m1[6]*m2[13] + m1[10]*m2[14] + m1[14]*m2[15];
    result[15] = m1[3]*m2[12] + m1[7]*m2[13] + m1[11]*m2[14] + m1[15]*m2[15];
}

As you know, standard C doesn't allow us to return arrays from a function, because we need to pass a pointer to our result array. If you are using a language which allows you to return an array, like JavaScript or ActionScript, you could prefer to return a literal array instead of working with a pointer.

Now one very important thing: "You CAN'T combine matrices directly, like using a rotationX formula above a matrix with another rotationZ, for example. YOU MUST TO CREATE EACH OF THEM SEPARATELY AND THEN MULTIPLY TWO BY TWO UNTIL YOU GET THE FINAL RESULT!".

For example, to translate, rotate and scale an object you must create each matrix separately and then perform the multiplication ((Scale * Rotation) * Translation) to get the final transformation matrix.

Now let's talk about some tips and tricks with matrix.

Matrices in Deep

1. What means pre or post-multiply matrices? This is the order of what the things happens. The second matrix in the multiplication WILL MAKE THE CHANGES FIRST! (lol). If we multiply A x B this means that B will happen first and then A. So if we multiply Rotation x Translation this means that object first will translate and then will rotate. The same is true for scales too.

2. Using the logic above, we can understand why the diference between local rotations and global rotations is just pre or post-multiply one rotation matrix by another. If you always post-multiply the new rotation matrices this means the object will first make the new rotation and then will rotate the old values, this is a local rotation. If you always pre-multiply the new rotations this means the object will first rotate to the old values and then rotate the new, this is a global rotation.
3. Any 3D object always has 3 local vectors: Right Vector, Up Vector and Look Vector. These vector are very important to make the Euclidean Transformation on it (Scales, Rotations and Translations). Specially when you are making local transformations. The good news is: do you remember the rotations formulas? What that formulas make is transcribe the rotations angles to the vectors and place them in the matrix. So you can extract these vectors directly from a rotation matrix and the best thing is that these vectors are already normalized in the matrix.

4. The next cool thing is about orthogonal matrices (don't get confused with orthonormal, which is said about two orthogonal vectors). In theory the orthogonal matrix is that one with real entries whose columns and rows are orthogonal unit vectors, in very simple words, orthogonal matrix is that one we call rotation matrix, without scales! I'll repeat this, it's very important: "Orthogonal is the ROTATION MATRIX, pure rotation matrix, without any scale!". Using the rotations formulas we get only unit vector and they are always orthogonal! What the hell are unit and orthogonal vectors? Is very simple to understand, unit vectors are that vector which the length/magnitude is equal 1, so the name "unit" vector. The orthogonal vector are said about two or more vector which has an angle of 90º between them. Look at the picture above again, notice that Right, Up and Look vectors are always orthogonal in 3D world.
5. Still in orthogonal matrices, if a matrix is orthogonal this means its inverse is equal its transpose. WOW! This is great! Because to calculate the inverse we need over than 100 multiplications and more than 40 sums, but to calculate the transpose we don't need any calculations, just change the order of some values. This is a big boost on our performance. But why we want the inverse of rotation matrix? To calculate the lights in the shaders! Remember that the real object never changes, we just change the computation of its vertices by multiplying they by a matrix. So to calculate a light, which is in the global space, we need the inverse of rotation matrix. Well, obviously we will need the inverse for other things, like cameras, so use the transpose instead of inverse could be great! And just to don't let any doubts, inverse matrix technacally represents a matrix which if we multiply it by the original (pre or post, doesn't matter here) will produce the matrix identity. In simple words, the inverse matrix is that which will revert all transformations from the original matrix.

You can extract the values of rotation, scale and transition from a matrix. Unfortunately don't exist a precise way to extract negative scales from a matrix. You could find the formulas to extract the values from a matrix in that book, 3D Game Programming, or in EuclideanSpace website. I'll not talk about those formulas here because I have a better advice: "Instead to try retrieve values from a matrix, is much much better you store user friendly values. Like store the global rotations (X,Y and Z), local scales (X,Y and Z) and global positions (X,Y and Z)."

Now is time to know about the great Hamilton contribution, the Quaternions!

Quaternions

If you make a little research by, you'll find many discussions about it. Quaternions is very polemic! Some guys love it, others hate it. Some say it is just a fad, others say it is amazing. Why all this around Quaternions? Well, is because using the rotations formulas we found a formula to produce rotations about an arbitrary axis, directly, avoiding the Gimbal Lock, or in other words, that formula produces the same effect as a quaternion (in fact is very similar). I'll not show this formula here, because I don't believe it is a good solution.

About the war of Quaternions X Rotation about an arbitrary axis you'll find people saying which this takes 27 multiplications, plus some sums, sine, cosine, vector magnitude against 21 or 24 multiplications in Quaternions and all this kind of annoying discussion! Whatever!!! With the actual hardwares, you can cut 10.000.000 multiplications in your application and all the gain that you'll have is 0.04 secs (directly on the iPhone 4 the mark was 0.12 with 10.000.000 multiplications)! This is not remarkable. There are several thing much more important than multiplications to boost your application's performance. In reallity the difference between those number will be less than 1.000 per frame.

So what is the crucial point about the Quaternions X Rotations Formulas? My love about Quaternions comes from the fact that it is SIMPLE! Very organized, very clear and incredibly precisely when you make consecutive rotations. I'll show how to work with Quarternions, and you take your own decision.

Let's start with simple concept. Quaternions, as the name sugest, is a vector of order 4 (x,y,z,w). Just for convention we are used to take notation of Quaternions as w,x,y,z using the "w" first. But this really doesn't matter, because all operations with quaternions always will bring the letter x,y,z or w. An alert! Don't confuse the "w" of Quaternions with "w" from Homegeneous Coordinates, those are two things completely different.

As quaternion is a vector 4, many vector operations are applied to it. But just few formulas are really important: multiplication, identity and inverse. Before start with those three formulas, I want to introduce you the formula to extract a matrix from a quaternion. This is the most important one:

  
.
    // This is the arithmetical formula optimized to work with unit quaternions.
    // |1-2y²-2z²        2xy-2zw         2xz+2yw       0|
    // | 2xy+2zw        1-2x²-2z²        2yz-2xw       0|
    // | 2xz-2yw         2yz+2xw        1-2x²-2y²      0|
    // |    0               0               0          1|

    // And this is the code.
    // First Column
    matrix[0] = 1 - 2 * (q.y * q.y + q.z * q.z);
    matrix[1] = 2 * (q.x * q.y + q.z * q.w);
    matrix[2] = 2 * (q.x * q.z - q.y * q.w);
    matrix[3] = 0;

    // Second Column
    matrix[4] = 2 * (q.x * q.y - q.z * q.w);
    matrix[5] = 1 - 2 * (q.x * q.x + q.z * q.z);
    matrix[6] = 2 * (q.z * q.y + q.x * q.w);
    matrix[7] = 0;

    // Third Column
    matrix[8] = 2 * (q.x * q.z + q.y * q.w);
    matrix[9] = 2 * (q.y * q.z - q.x * q.w);
    matrix[10] = 1 - 2 * (q.x * q.x + q.y * q.y);
    matrix[11] = 0;

    // Fourth Column
    matrix[12] = 0;
    matrix[13] = 0;
    matrix[14] = 0;
    matrix[15] = 1;
.

Just like the matrices formulas, this conversion always produces an orthogonal matrix with unit vectors. In some places you may find an arithmetical formula which uses "w²+x²-y²-z²" instead "1-2y²-2z²". Don't worry, this is because the original quaternions from Hamilton was much more complex. They have an imaginary part (i, j and k) and could be more than just unit quaternions. But as in 3D world we always work with unit vectors, we can discard the imaginary part of quaternions and assume which they will always be unit quaternions. Because this optimization, we can use the formula with "1-2y²-2z²".

Now, let's talk about other formulas. First, the multiplication formula:

  
.
     // Assume that this multiplies q1 x q2, in this order, resulting in "newQ".
    newQ.w = q1.w * q2.w - q1.x * q2.x - q1.y * q2.y - q1.z * q2.z;
    newQ.x = q1.w * q2.x + q1.x * q2.w + q1.y * q2.z - q1.z * q2.y;
    newQ.y = q1.w * q2.y - q1.x * q2.z + q1.y * q2.w + q1.z * q2.x;
    newQ.z = q1.w * q2.z + q1.x * q2.y - q1.y * q2.x + q1.z * q2.w;
.

That multiplication formula has exact the same effect as multiply a rotation matrix by another, for example. Just as matrix multiplication, multiplying quaternions is not a commutative operation. so q1 x q2 is not equals to q2 x q1. Note that I'll not show here the arithmetical formula to multiplication. This is because the original multiplication with two vector 4 are much more complex than a cross multiplication by a vector 3 and it needs a matrix multiplication, this could confuse our minds (in fact the arithmetical formula will result in the code above). Let's focus on what is important. But if you have intrest in know more about multiplications with vector 4, try this: http://www.mathpages.com/home/kmath069.htm

The identity. The identity quaternion produces the identity matrix, here is the formula:

  
.
    q.x = 0;
    q.y = 0;
    q.z = 0;
    q.w = 1;
.

OK, now this is the formula to invert a quaternion, aka "conjugate quaternion":

  
.
    q.x *= -1;
    q.y *= -1;
    q.z *= -1;

    // At this point is a good idea normalize the quaternion again.
.

I love this inverse formula. Because its simplicity! It's so simple! And these three lines of code has the exactly the same effect as take the inverse of a matrix! (Ô.o)
Yes dude, if you are working with quaternions to rotations, instead to invert the matrix, making more than 100 multiplications and sums, you can simple make these three lines above. As I said before, is not because the reduction of processing, but is more in reason of the simplicity! Quaternions are stupidly simple!

Is everything OK until here? Remember to ask, if you have doubts. Let's proceed now to those two formula which are reason of the "Quaternions WAR". Let's put some rotations angles into it. To do that, we have two ways: using the quaternion's concept and informing a vector as direction and an angle to rotate around this direction or we can use the Euler angles (X, Y and Z) informing the three angles as they are. This last one takes more multiplications, but is more user friendly because is just like set the angles to the matrices rotations formulas.

First setting the quaternion by a direction vector and an angle:

  
.
    // The new quaternion variable.
    vec4 q;

    // Converts the angle in degrees to radians.
    float radians = degreesToRadians(degrees);

    // Finds the Sin and Cosin for the half angle.
    float sin = sinf(radians * 0.5);
    float cos = cosf(radians * 0.5);

    // Formula to construct a new Quaternion based on direction and angle.
    q.w = cos;
    q.x = vec.x * sin;
    q.y = vec.y * sin;
    q.z = vec.z * sin;
.

To produce consecutive rotations you can make multiply quaternions. Just as the matrix approach, to produce a local or a global rotation just change the order of the multiplication (q1 x q2 or q2 x q1), and remember, just as the matrix, when you multiply q1 x q2 this means: "do q2 first and then q1".

Now, here is the formula to convert Euler Angles to Quaternions:

  
.
    // The new quaternion variable.
    vec4 q;

    // Converts all degrees angles to radians.
    float radiansY = degreesToRadians(degreesY);
    float radiansZ = degreesToRadians(degreesZ);
    float radiansX = degreesToRadians(degreesX);

    // Finds the Sin and Cosin for each half angles.
    float sY = sinf(radiansY * 0.5);
    float cY = cosf(radiansY * 0.5);
    float sZ = sinf(radiansZ * 0.5);
    float cZ = cosf(radiansZ * 0.5);
    float sX = sinf(radiansX * 0.5);
    float cX = cosf(radiansX * 0.5);

    // Formula to construct a new Quaternion based on Euler Angles.
    q.w = cY * cZ * cX - sY * sZ * sX;
    q.x = sY * sZ * cX + cY * cZ * sX;
    q.y = sY * cZ * cX + cY * sZ * sX;
    q.z = cY * sZ * cX - sY * cZ * sX;
.

As you saw, I organized the order of code to make the angles in order Y, Z and X. Why? Because this is the order in which the rotation will be produced by the quaternion. Using this formula, can we change this order? NO, we can't. This formula is to produce this kind of rotation (Y,Z,X). By the way, this is what we call "Euler Rotation Order". If you want to know more about rotation order, or what that means, watch this video, is really great http://www.youtube.com/watch?v=zc8b2Jo7mno

Great! This is the basic about quaternions. Obviously we have formulas to retrieve the values from a Quaternion, extract the Euler angles, extract the vector direction, etc. This kind of thing is good just to you check what is happening inside the quaternions. My advice here is the same as the matrix: "Always store an user friendly variable to control your rotations".

Now let's back to the matrices and finally understand how we can create camera lenses.

The code behind the 3D cameras

As explained early, we can create two kind of projections: Perpective and Orthographic. About the both kinds, I'll not explain here the mathematical formula in deep, if you are intrest in the concepts behind the projection matrices, you can find a real good explanation here: http://www.songho.ca/opengl/gl_projectionmatrix.html. Oh right, so now let's focus on the code. Starting with the most basic kind, the Orthographic projection:

  
.
    // These paramaters are lens properties.
    // The "near" and "far" create the Depth of Field.
    // The "left", "right", "bottom" and "top" represent the rectangle formed
    // by the near area, this rectangle will also be the size of the visible area.
    float near = 0.001, far = 100.0;
    float left = 0.0, right = 320.0, bottom = 480.0, top = 0.0;

    // First Column
    matrix[0] = 2.0 / (right - left);
    matrix[1] = 0.0;
    matrix[2] = 0.0;
    matrix[3] = 0.0;

    // Second Column
    matrix[4] = 0.0;
    matrix[5] = 2.0 / (top - bottom);
    matrix[6] = 0.0;
    matrix[7] = 0.0;

    // Third Column
    matrix[8] = 0.0;
    matrix[9] = 0.0;
    matrix[10] = -2.0 / (far - near);
    matrix[11] = 0.0;

    // Fourth Column
    matrix[12] = -(right + left) / (right - left);
    matrix[13] = -(top + bottom) / (top - bottom);
    matrix[14] = -(far + near) / (far - near);
    matrix[15] = 1;
.

As you noticed, the Orthographic projection doesn't have any "Angle of View", this is because it doesn't need. As you remember from the orthographic project, it make everything seems equal, the units are always squared, in other words, orthographic projection is a linear projection.

The code above show to us what we imagine before. The projection matrix will affect slightly the rotations (X, Y and Z), affect directly the scales (the major diagonal) and more incisive on the vertex positions.

Now, let's see the perspective projection, a little more elaborated case:

  
.
    // These paramaters are about lens properties.
    // The "near" and "far" create the Depth of Field.
    // The "angleOfView", as the name suggests, is the angle of view.
    // The "aspectRatio" is the cool thing about this matrix. OpenGL doesn't
    // has any information about the screen you are rendering for. So the
    // results could seem stretched. But this variable puts the thing into the
    // right path. The aspect ratio is your device screen (or desired area) width divided
    // by its height. This will give you a number < 1.0 the the area has more vertical
    // space and a number > 1.0 is the area has more horizontal space.
    // Aspect Ratio of 1.0 represents a square area.
    float near = 0.001, far = 100.0;
    float angleOfView = 45.0;
    float aspectRatio = 0.75;

    // Some calculus before the formula.
    float size = near * tanf(degreesToRadians(angleOfView) / 2.0); 
    float left = -size, right = size, bottom = -size / aspectRatio, top = size / aspectRatio;

    // First Column
    matrix[0] = 2 * near / (right - left);
    matrix[1] = 0.0;
    matrix[2] = 0.0;
    matrix[3] = 0.0;

    // Second Column
    matrix[4] = 0.0;
    matrix[5] = 2 * near / (top - bottom);
    matrix[6] = 0.0;
    matrix[7] = 0.0;

    // Third Column
    matrix[8] = (right + left) / (right - left);
    matrix[9] = (top + bottom) / (top - bottom);
    matrix[10] = -(far + near) / (far - near);
    matrix[11] = -1;

    // Fourth Column
    matrix[12] = 0.0;
    matrix[13] = 0.0;
    matrix[14] = -(2 * far * near) / (far - near);
    matrix[15] = 0.0;
.

Understanding: Wow, the formula changes slightly, but now there are no effect on X and Y position, it just changes the Z position (depth). It continues affecting the rotation X, Y and Z, but there are a great interference on the Third Column, what is that? That is exactly the calculus about the modifications to produce the perspective and the factors to adjust the aspect ratio. Note that the last element of the third column is negative. This will inverse the stretches of the aspect ratio when the final matrix was generated (multiplied).

Now talking about the final matrix. This is a very important step. Unlike the other matrices multiplication, at this time you can't change the order, otherwise you'll get unexpected results. This is what you need to do:

Take the camera View Matrix (an inverted matrix containing the rotations and translations of the camera) and POST-Multiply it by the Projection Matrix:
PROJECTION MATRIX x VIEW MATRIX.
Remember, this will produce the effect as: "Do the VIEW MATRIX first and then do PROJECTION MATRIX".

Now you have what we are used to call VIEWPROJECTION MATRIX. Using this new matrix you will POST-Multiply the MODEL MATRIX (matrix containing all the rotations, scales and translations of an object) by the VIEWPROJECTION MATRIX:
VIEWPROJECTION MATRIX x MODEL MATRIX.
Again, just to reinforce, that means: "Do the MODEL MATRIX first and then do VIEWPROJECTION MATRIX". Finally! Now you have what is called MODELVIEWPROJECTION MATRIX!

CONGRATULATIONS!
Gasp! Oof!

OK, I know what you are thinking... "WTF! All this just to produces a simple stupid matrix!" Yeh, I thought the same. Doesn't has a more simple or fast way to do that?

Well, I think the answer to that questions is on the conclusion of this article. Let's go!

Conclusion

1. You could construct a Framework/Engine by yourself.
2. You could take an existing Framework/Engine and learn how to use it.

Just as any "choice", both have positives and negatives points. You need to think and decide what is better for your purposes. I think a third choice, construct a little "template" to use in your projects could not be a good one, so personally I discard this option as a choice. There are so many things to be done in the 3D world that probably we would be crazy or very lost trying to fit everything into one or few templates. So my last advice is: "Take a choice".

Anyway, the next tutorial I'll make will be more advanced. For now, let's revise everything of this tutorial:

• Cameras could has a Convex or Concave Lens. Cameras also has some properties like Depth of Field, Angle of View, Near and Far.
• In 3D world we can work with a real projection called Perspective and an unreal projection called Orthographic.
• The Camera should work as the inverse of a normal 3D object.
• We never change the original structure of a 3D object, we just take the result of a temporary change.
• Those changes can be made using matrices. We have formulas to rotate, scale and translate a matrix. We also has the Quaternions to work with the rotations.
• We also use a matrix to create the camera's lens using a Perspective or Orthographic projection.

This is all for now.
Thanks for reading, see you in the next tutorial!

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.

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

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!

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

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

This serie is composed by 3 parts:

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

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

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

Let's start.

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

At a glance

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

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

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

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

Let's go!

2D graphics with OpenGL

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

The Grid Concept

The Depth Render Buffer in 2D

The Cameras with 2D

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

The Multisampling

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

// Dimensions
int _width, _height;

// Normal Buffers
GLuint _frameBuffer, _colorBuffer, _depthBuffer;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

More About Textures

Bytes per Pixel

.  
typedef enum  
{
    ColorFormatRGB565,
    ColorFormatRGBA4444,
} ColorFormat;

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

    void *newData;

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

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

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

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

    free(pixelData);

    pixelData = newData;
}
.

PVRTC

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

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

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

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

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

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

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

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

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

The Off-Screen Render

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

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

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

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

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

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

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

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

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

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

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

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

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

Now it's time to talk more about optimization.

Tips and Tricks

The Cache

.  
bool _matrixCached;  
float _changeValue;  
float *_matrix;

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

        _matrixCached = TRUE;
    }

    return _matrix;
}

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

    _matrixCached = FALSE;
}
.

Store the Values

.  
float _x;  
float _y;  
float _z;

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

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

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

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

C is always the fast language

Conclusion

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

From here and beyond

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

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

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

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

Now we are aware about the basic concepts of 3D world and OpenGL. Now it's time to start the fun! Let's go deep into code and see some result on our screens. Here I'll show you how to construct an OpenGL application, using the best practices.

If you lost the first one, you can check the parts of this serie below.

This serie is composed by 3 parts:

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

Before start, I want to say something: is Thank You!
The first tutorial of this serie became much much bigger than I could imagine. When I saw the news at the home of http://www.opengl.org website, I was speechless, stunned, that was really amazing!!!
So I want to say again, Thank you so much!

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

At a glance

As asked in comments below, here is a PDF file for those of you who prefer to read this tutorial on a file instead of here in the blog.

Download now
PDF file with navigation links
1.3Mb

Remembering the first part of this serie, we've seen:

1. OpenGL’s logic is composed by just 3 simple concepts: Primitives, Buffers and Rasterize.
2. OpenGL works with fixed or programmable pipeline.
3. Programmable pipeline is synonymous of Shaders: Vertex Shader and Fragment Shader.

Here I'll show code more based in C and Objective-C. In some parts I'll talk specifically about iPhone and iOS. But in general the code will be generic to any language or platform. As OpenGL ES is the most concise API of OpenGL, I'll focus on it. If you're using OpenGL or WebGL you could use all the codes and concepts here.

The code in this tutorial is just to illustrate the functions and concepts, not real code. In the link bellow you can get a Xcode project which uses all the concepts and code of this tutorial. I made the principal class (CubeExample.mm) using Objective-C++ just to make clearly to everybody how the OpenGL ES 2.0 works, even those which don't use Objective-C. This training project was made for iOS, more specifically targeted for iPhone.

Download now
Xcode project files to iOS 4.2 or later
172kb

Here I'll use OpenGL functions following the syntax: gl + FunctionName. Almost all implementation of OpenGL use the prefix "gl" or "gl.". But if your programming language don't use this, just ignore this prefix in the following lines.

Another important thing to say before we start is about OpenGL data types. As OpenGL is multiplatform and depends of the vendors implementation, many data type could change from one programming language to another. For example, a float in C++ could represent 32 bits exactly, but in JavaScript a float could be only 16 bits. To avoid these kind of conflict, OpenGL always works with it's own data types. The OpenGL's data type has the prefix "GL", like GLfloat or GLint. Here is a full list of OpenGL's data type:

A very important information about Data Types is that OpenGL ES does NOT support 64 bits data types, because embedded systems usually need performance and several devices don't support 64 bits processors. By using the OpenGL data types, you can easily and safely move your OpenGL application from C++ to JavaScript with less changes, for example.

One last thing to introduce is the graphics pipeline. We'll use and talk about the Programmable Pipeline a lot, here is a visual illustration:

We'll talk deeply about each step in that diagram. The only thing I want to say now is about the "Frame Buffer" in the image above. The Frame Buffer is marked as optional because you have the choice of don't use it directly, but internally the OpenGL's core always will work with a Frame Buffer and a Color Render Buffer at least.

Did you notice the EGL API in the image above?
This is a very very important step to our OpenGL's application. Before start this tutorial we need to know at least the basic concept and setup about EGL API. But EGL is a dense subject and I can't place it here. So I've created an article to explain that. You can check it here: EGL and EAGL APIs. I really recommend you read that before to continue with this tutorial.

If you've read or already know about EGL, let's move following the order of the first part and start talking about the Primitives.

Primitives

  
GLfloat point3D = {1.0,0.0,0.5};  
GLfloat line3D = {0.5,0.5,0.5,1.0,1.0,1.0};  
GLfloat triangle3D = {0.0,0.0,0.0,0.5,1.0,0.0,1.0,0.0,0.0};  

Meshes and Lines Optimization

  
// Array of vertices to a cube.
GLfloat cube3D[] =  
{
    0.50,-0.50,-0.50,    // vertex 1
    0.50,-0.50,0.50,    // vertex 2
    -0.50,-0.50,0.50,    // vertex 3
    -0.50,-0.50,-0.50,    // vertex 4
    0.50,0.50,-0.50,    // vertex 5
    -0.50,0.50,-0.50,    // vertex 6
    0.50,0.50,0.50,        // vertex 7
    -0.50,0.50,0.50        // vertex 8
}

  
// Array of vertices to a cube.
GLfloat cube3D[] =  
{
    0.50,-0.50,-0.50,    // vertex 1
    0.00,0.33,            // texture coordinate 1
    1.00,0.00,0.00        // normal 1
    0.50,-0.50,0.50,    // vertex 2
    0.33,0.66,            // texture coordinate 2
    0.00,1.00,0.00        // normal 2
    ...
}

Buffers

Frame Buffers

  
GLuint frameBuffer;

// Creates a name/id to our frameBuffer.
glGenFramebuffers(1, &frameBuffer);

// The real Frame Buffer Object will be created here,
// at the first time we bind an unused name/id.
glBindFramebuffer(GL_FRAMEBUFFER, frameBuffer);

// We can suppress the glGenFrambuffers.
// But in this case we'll need to manage the names/ids by ourselves.
// In this case, instead the above code, we could write something like:
//
// GLint frameBuffer = 1;
// glBindFramebuffer(GL_FRAMEBUFFER, frameBuffer);

Render Buffers

  
GLuint colorRenderbuffer, depthRenderbuffer, stencilRenderbuffer;  
GLint sw = 320, sh = 480; // Screen width and height, respectively.

// Generates the name/id, creates and configures the Color Render Buffer.
glGenRenderbuffers(1, &colorRenderbuffer);  
glBindRenderbuffer(GL_RENDERBUFFER, colorRenderbuffer);  
glRenderbufferStorage(GL_RENDERBUFFER, GL_RGBA4, sw, sh);

// Generates the name/id, creates and configures the Depth Render Buffer.
glGenRenderbuffers(1, &depthRenderbuffer);  
glBindRenderbuffer(GL_RENDERBUFFER, depthRenderbuffer);  
glRenderbufferStorage(GL_RENDERBUFFER, GL_DEPTH_COMPONENT16, sw, sh);

// Generates the name/id, creates and configures the Stencil Render Buffer.
glGenRenderbuffers(1, &stencilRenderbuffer);  
glBindRenderbuffer(GL_RENDERBUFFER, stencilRenderbuffer);  
glRenderbufferStorage(GL_RENDERBUFFER, GL_STENCIL_INDEX8, sw, sh);  

  
GLuint *renderbuffers;  
GLint sw = 320, sh = 480; // Screen width and height, respectively.

// Let's create multiple names/ids at once.
// To do this we declared our variable as a pointer *renderbuffers.
glGenRenderbuffers(2, renderbuffers);

// The index 0 will be our color render buffer.
glBindRenderbuffer(GL_RENDERBUFFER, renderbuffers[0]);  
glRenderbufferStorage(GL_RENDERBUFFER, GL_RGBA4, sw, sh);

// The index 1 will be our depth render buffer.
glBindRenderbuffer(GL_RENDERBUFFER, renderbuffers[1]);  
glRenderbufferStorage(GL_RENDERBUFFER, GL_DEPTH_COMPONENT16, sw, sh);  

  
// Suppose you previously set EAGLContext *_context
// as I showed in my EAGL article.

GLuint colorBuffer;

glGenRenderbuffers(1, & colorBuffer);  
glBindRenderbuffer(GL_RENDERBUFFER, colorBuffer);  
[_context renderbufferStorage:GL_RENDERBUFFER fromDrawable:myCAEAGLLayer];

  
// Doesn't matter if this is before or after
// we create the depth render buffer.
// The important thing is enable it before try
// to render something which needs to use it.
glEnable(GL_DEPTH_TEST);  

Buffer Objects

Textures

Rasterize

Face Culling

Per-Fragment Operations

• Scissor Test: GL_SCISSOR_TEST - This can crop the image, so every fragment outside the scissor area will be ignored.
• Stencil Test: GL_STENCIL_TEST - Works like a mask, the mask is defined by a black-white image where the white pixels represent the visible area. So every fragment placed on the black area will be ignored. This requires a stencil render buffer to works.
• Depth Test: GL_DEPTH_TEST - This test compares the Z depth of the current 3D object against the others Z depths previously rendered. The fragment with a depth higher than another will be ignored (that means, more distant from the viewer). This will be done using a grey scale image. This requires a depth render buffer to works.
• Blend: GL_BLEND - This step can blend the new fragment with the existing fragment into the color buffer.
• Dither: GL_DITHER - This is a little OpenGL's trick. In the systems wich color available to the frame buffer is limited, this step can optimize the color usage to appears to have more colors than has in real. The Dither has no configuration, you just choose to use it or not.

Shaders

• Shaders use the GLSL or GLSL ES, a compact version of the first one.
• Shaders always work in pairs, a Vertex Shader (VSH) and a Fragment Shader (FSH).
• That pair of shader will be processed every time you submit a render command, like glDrawArrays or glDrawElements.
• VSH will be processed per-vertex, if your 3D object has 8 vertices, so the vertex shader will be processed 8 times. The VSH is responsible by determine the final position of a vertex.
• FSH will be processed in each visible fragment of your objects, remember that FSH is processed before the "Fragment Operations" in the graphics pipeline, so the OpenGL doesn't knows yet what object is in front of others, I mean, even the fragments behind the others will be processed. The FSH is responsible by define the final color of a fragment.
• VSH and FSH must be compiled separately and linked together within a Program Object. You can reuse a compiled shader into multiple Program Objects, but can link only one kind of shader (VSH and FSH) at each Program Object.

Shader and Program Creation

GLuint _program;

GLuint createShader(GLenum type, const char **source)  
{
    GLuint name;

    // Creates a Shader Object and returns its name/id.
    name = glCreateShader(type);

    // Uploads the source to the Shader Object.
    glShaderSource(name, 1, &source, NULL);

    // Compiles the Shader Object.
    glCompileShader(name);

    // If you are running in debug mode, query for info log.
    // DEBUG is a pre-processing Macro defined to the compiler.
    // Some languages could not has a similar to it.
#if defined(DEBUG)

    GLint logLength;

    // Instead use GL_INFO_LOG_LENGTH we could use COMPILE_STATUS.
    // I prefer to take the info log length, because it'll be 0 if the
    // shader was successful compiled. If we use COMPILE_STATUS
    // we will need to take info log length in case of a fail anyway.
    glGetShaderiv(name, GL_INFO_LOG_LENGTH, &logLength);

    if (logLength > 0)
    {
        // Allocates the necessary memory to retrieve the message.
        GLchar *log = (GLchar *)malloc(logLength);

        // Get the info log message.
        glGetShaderInfoLog(name, logLength, &logLength, log);

        // Shows the message in console.
        printf("%s",log);

        // Frees the allocated memory.
        free(log);
    }
#endif

    return name;
}

GLuint createProgram(GLuint vertexShader, GLuint fragmentShader)  
{
    GLuint name;

    // Creates the program name/index.
    name = glCreateProgram();

    // Will attach the fragment and vertex shaders to the program object.
    glAttachShader(name, vertexShader);
    glAttachShader(name, fragmentShader);

    // Will link the program into OpenGL's core.
    glLinkProgram(_name);

#if defined(DEBUG)

    GLint logLength;

    // This function is different than the shaders one.
    glGetProgramiv(name, GL_INFO_LOG_LENGTH, &logLength);

    if (logLength > 0)
    {
        GLchar *log = (GLchar *)malloc(logLength);

        // This function is different than the shaders one.
        glGetProgramInfoLog(name, logLength, &logLength, log);

        printf("%s",log);

        free(log);
    }
#endif

    return name;
}

void initProgramAndShaders()  
{
    const char *vshSource = "... Vertex Shader source using SL ...";
    const char *fshSource = "... Fragment Shader source using SL ...";

    GLuint vsh, fsh;

    vsh = createShader(GL_VERTEX_SHADER, &vshSource);
    fsh = createShader(GL_FRAGMENT_SHADER, &fshSource);

    _program = createProgram(vsh, fsh);

    // Clears the shaders objects.
    // In this case we can delete the shader because we
    // will not use they anymore and once compiled,
    // the OpenGL stores a copy of they into the program object.
    glDeleteShader(vsh);
    glDeleteShader(fsh);

    // Later you can use the _program variable to use this program.
    // If you are using an Object Oriented Programming is better make
    // the program variable an instance variable, otherwise is better make
    // it a static variable to reuse it in another functions.
    // glUseProgram(_program);
}

Shader Language

  
vec4 myVec4 = vec4(0.0, 1.0, 2.0, 3.0);  
vec3 myVec3;  
vec2 myVec2;

myVec3 = myVec4.xyz;        // myVec3 = {0.0, 1.0, 2.0};  
myVec3 = myVec4.zzx;        // myVec3 = {2.0, 2.0, 0.0};  
myVec2 = myVec4.bg;            // myVec2 = {2.0, 1.0};  
myVec4.xw = myVec2;            // myVec4 = {2.0, 1.0, 2.0, 1.0};  
myVec4[1] = 5.0;            // myVec4 = {2.0, 5.0, 2.0, 1.0};  

  
precision mediump float;  
precision lowp int;

vec4 myVec4 = vec4(0.0, 1.0, 2.0, 3.0);  
ivec3 myIvec3;  
mediump ivec2 myIvec2;

// This will fail. Because the data types are not compatible.
//myIvec3 = myVec4.zyx;

myIvec3 = ivec3(myVec4.zyx);    // This is OK.  
myIvec2.x = myIvec3.y;            // This is OK.

myIvec2.y = 1024;

// This is OK too, but the myIvec3.x will assume its maximum value.
// Instead 1024, it will be 256, because the precisions are not
// equivalent here.
myIvec3.x = myIvec2.y;  

  
mat4 myMat4;  
mat3 myMat3;  
vec4 myVec4 = vec4(0.0, 1.0, 2.0, 3.0);  
vec3 myVec3 = vec3(-1.0, -2.0, -3.0);  
float myFloat = 2.0;

// A mat4 has 16 elements, could be constructed by 4 vec4.
myMat4 = mat4(myVec4,myVec4,myVec4,myVec4);

// A float will multiply each vector value.
myVec4 = myFloat * myVec4;

// A mat4 multiplying a vec4 will result in a vec4.
myVec4 = myMat4 * myVec4;

// Using the accessor, we can multiply two vector of different orders.
myVec4.xyz = myVec3 * myVec4.xyz;

// A mat3 produced by a mat4 will take the first 9 elements.
myMat3 = mat3(myMat4);

// A mat3 multiplying a vec3 will result in a vec3.
myVec3 = myMat3 * myVec3;  

Vertex and Fragment Structures

  
precision mediump float;  
precision lowp int;

uniform mat4        u_mvpMatrix;

attribute vec4        a_vertex;  
attribute vec2        a_texture;

varying vec2        v_texture;

void main()  
{
    // Pass the texture coordinate attribute to a varying.
    v_texture = a_texture;

    // Here we set the final position to this vertex.
    gl_Position = u_mvpMatrix * a_vertex;
}

  
precision mediump float;  
precision lowp int;

uniform sampler2D    u_maps[2];

varying vec2        v_texture;

void main()  
{
    // Here we set the diffuse color to the fragment.
    gl_FragColor = texture2D(u_maps[0], v_texture);

    // Now we use the second texture to create an ambient color.
    // Ambient color doesn't affect the alpha channel and changes
    // less than half the natural color of the fragment.
    gl_FragColor.rgb += texture2D(u_maps[1], v_texture).rgb * .4;
}

Setting the Attributes and Uniforms

• glUniform1i(GLint location, GLint x)
• glUniform1f(GLint location, GLfloat x)
• glUniform2i(GLint location, GLint x, GLint y)
• glUniform2f(GLint location, GLfloat x, GLfloat y)
• glUniform3i(GLint location, GLint x, GLint y, GLint z)
• glUniform3f(GLint location, GLfloat x, GLfloat y, GLfloat z)
• glUniform4i(GLint location, GLint x, GLint y, GLint z, GLint w)
• glUniform4f(GLint location, GLfloat x, GLfloat y, GLfloat z, GLfloat w)
• glUniform1iv(GLint location, GLsizei count, const GLint* v)
• glUniform1fv(GLint location, GLsizei count, const GLfloat* v)
• glUniform2iv(GLint location, GLsizei count, const GLint* v)
• glUniform2fv(GLint location, GLsizei count, const GLfloat* v)
• glUniform3iv(GLint location, GLsizei count, const GLint* v)
• glUniform3fv(GLint location, GLsizei count, const GLfloat* v)
• glUniform4iv(GLint location, GLsizei count, const GLint* v)
• glUniform4fv(GLint location, GLsizei count, const GLfloat* v)
• glUniformMatrix2fv(GLint location, GLsizei count, GLboolean transpose, const GLfloat* value)
• glUniformMatrix3fv(GLint location, GLsizei count, GLboolean transpose, const GLfloat* value)
• glUniformMatrix4fv(GLint location, GLsizei count, GLboolean transpose, const GLfloat* value)

• glVertexAttrib1f(GLuint index, GLfloat x)
• glVertexAttrib2f(GLuint index, GLfloat x, GLfloat y)
• glVertexAttrib3f(GLuint index, GLfloat x, GLfloat y, GLfloat z)
• glVertexAttrib4f(GLuint index, GLfloat x, GLfloat y, GLfloat z, GLfloat w)
• glVertexAttrib1fv(GLuint index, const GLfloat* values)
• glVertexAttrib2fv(GLuint index, const GLfloat* values)
• glVertexAttrib3fv(GLuint index, const GLfloat* values)
• glVertexAttrib4fv(GLuint index, const GLfloat* values)
• glVertexAttribPointer(GLuint index, GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid* ptr)

  
// Assume which _program defined early in another code example.

GLuint mvpLoc, mapsLoc, vertexLoc, textureLoc;

// Gets the locations to uniforms.
mvpLoc = glGetUniformLocation(_program, "u_mvpMatrix");  
mapsLoc = glGetUniformLocation(_program, "u_maps");

// Gets the locations to attributes.
vertexLoc = glGetAttribLocation(_program, "a_vertex");  
textureLoc = glGetAttribLocation(_program, "a_texture");

// ...
// Later, in the render time...
// ...

// Sets the ModelViewProjection Matrix.
// Assume which "matrix" variable is an array with
// 16 elements defined, matrix[16].
glUniformMatrix4fv(mvpLoc, 1, GL_FALSE, matrix);

// Assume which _texture1 and _texture2 are two texture names/ids.
// The order is very important, first you activate
// the texture unit and then you bind the texture name/id.
glActiveTexture(GL_TEXTURE0);  
glBindTexture(GL_TEXTURE_2D, _texture1);  
glActiveTexture(GL_TEXTURE1);  
glBindTexture(GL_TEXTURE_2D, _texture2);

// The {0,1} correspond to the activated textures units.
int textureUnits[2] = {0,1};

// Sets the texture units to an uniform.
glUniform1iv(mapsLoc, 2, &textureUnits);

// Enables the following attributes to use dynamic values.
glEnableVertexAttribArray(vertexLoc);  
glEnableVertexAttribArray(textureLoc);

// Assume which "vertexArray" variable is an array of vertices
// composed by several sequences of 3 elements (X,Y,Z)
// Something like {0.0,0.0,0.0, 1.0,2.0,1.0, -1.0,-2.0,-1.0, ...}
glVertexAttribPointer(vertexLoc, 3, GL_FLOAT, GL_FALSE, 0, vertexArray);

// Assume which "textureArray" is an array of texture coordinates
// composed by several sequences of 2 elements (S,T)
// Something like {0.0,0.0, 0.3,0.2,  0.6, 0.3,  0.3,0.7, ...}
glVertexAttribPointer(textureLoc, 2, GL_FLOAT, GL_FALSE, 0, textureArray);

// Assume which "indexArray" is an array of indices
// Something like {1,2,3,  1,3,4,  3,4,5,  3,5,6,  ...}
glDrawElements(GL_TRIANGLES, 64, GL_UNSIGNED_SHORT, indexArray);

// Disables the vertices attributes.
glDisableVertexAttribArray(vertexLoc);  
glDisableVertexAttribArray(textureLoc);  

Using the Buffer Objects

  
GLuint arrayBuffer, indicesBuffer;

// Generates the name/ids to the buffers
glGenBuffers(1, &arrayBuffer);  
glGenBuffers(1, &indicesBuffer);

// Assume we are using the best practice to store all informations about
// the object into a single array: vertices and texture coordinates.
// So we would have an array of {x,y,z,s,t,  x,y,z,s,t,  ...}
// This will be our "arrayBuffer" variable.
// To the "indicesBuffer" variable we use a
// simple array {1,2,3,  1,3,4,  ...}

// ...
// Proceed with the retrieving attributes and uniforms locations.
// ...

// ...
// Later, in the render time...
// ...

// ...
// Uniforms definitions
// ...

glBindBuffer(GL_ARRAY_BUFFER, arrayBuffer);  
glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, indicesBuffer);

int fsize = sizeof(float);  
GLsizei str = 5 * fsize;  
void * void0 = (void *) 0;  
void * void3 = (void *) 3 * fsize;

glVertexAttribPointer(vertexLoc, 3, GL_FLOAT, GL_FALSE, str, void0);  
glVertexAttribPointer(textureLoc, 2, GL_FLOAT, GL_FALSE, str, void3);

glDrawElements(GL_TRIANGLES, 64, GL_UNSIGNED_SHORT, void0);  

Rendering

Pre-Render

  
glBindFramebuffer(GL_FRAMEBUFFER, _frameBuffer);  
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);  

Drawing

Render

  
- (void) makeRender
{
    glBindFramebuffer(_framebuffer);
    glBindRenderbuffer(_colorRenderbuffer);
    [_context presentRenderbuffer:GL_RENDERBUFFER];
}

Conclusion

• First we saw the OpenGL's data types and the programmable pipeline.
• Your meshes (primitives) data must be an array of informations. It should be optimized to form an Array of Structures.
• The OpenGL works as a Port Crane which has multiple arms with hooks. Four great hooks: Frame Buffer Hook, Render Buffer Hook, Buffer Object Hook and Texture Hook.
• The Frame Buffers holds 3 Render Buffers: Color, Depth and Stencil. They form an image coming from the OpenGL's render.
• Textures must to have specific formats before be uploaded to OpenGL (a specific pixel order and color bytes per pixel). Once an OpenGL's texture was created, you need to activate a Texture Unit which will be processed in the shaders.
• The Rasterize is a big process which includes several tests and per-fragment operations.
• Shaders are used in pairs and must be inside a Program Object. Shaders use their own language called GLSL or GLSL ES.
• You can define dynamic values only in Attributes into VSH (per-vertex values). The Uniforms are always constant and can be used in both shaders kind.
• You need to clean the buffers before start to draw new things to it.
• You will call a glDraw* function to each 3D object you want to render.
• The final render step is made using EGL API (or EAGL API, in iOS cases).

On the Next

All I showed here is an intermediate level about OpenGL. Using these knowledge you can create great 3D applications. I think this is around the half of the OpenGL study. In the next part, an advanced tutorial, I'll talk about everything I skipped here: the 3D textures, multisampling, render to off-screen surfaces, per-fragment operations in deeply and some best practices I've learned developing my 3D engine.

Probably I'll make another two articles before the third part of this serie. One about the textures, the complexity of binary images and compressed formats like PVR textures. And another one about the ModelViewProjection Matrix, Quaternions and matrices operations, it's more a mathematical article, for who likes, will appreciate.

Thanks again for reading and see you in the next part!

NEXT PART: Part 3 - Jedi skills in OpenGL ES 2.0 and 2D graphics (Advanced)

Welcome again to a new serie of tutorial. This time let's talk about the magic of 3D world. Let's talk about OpenGL. I dedicated the last five months of my life entirely to go deep inside 3D world, I'm finishing my new 3D engine (seems one of the greatest work that I've done) and now is time to share with you what I know, all references, all books, tutorials, everything and, of course, learn more with your feedback.

This serie is composed by 3 parts:

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

So if you are interested in some code, just jump to part 2/3, because in this first one I'll just talk about the concepts, nothing more.

OK, let's start.

At a glance

Who of you never hear about OpenGL? OpenGL means Open Graphics Library and it is used a lot today in computer languages. OpenGL is the closest point between the CPU (which we, developers, run our applications based on a language) and the GPU (the graphic's processor that exist in every Graphics Cards). So OpenGL need to be supported by the vendors of Graphics Cards (like NVidia) and be implemented by the OS's vendors (like Apple in his MacOS and iOS) and finally the OpenGL give to us, developers, an unified API to work with. This API is "Language Free" (or almost free). This is amazing, because if you use C, or C++, or Objective-C, or Perl, or C#, or JavaScript, wherever you use, the API always will be equivalent, will present the same behavior, the same functions, the same commands and is at this point that comes this tutorial serie! To deal with OpenGL's API to the developers.

Before start talking about OpenGL API we need to have a good knowledge in 3D world. The history of 3D
world in computer language is bound to OpenGL history. So let's take a little look at a bit of history.

A short story

About 20 years ago has a guy called Silicon Graphics (SGI) made a little kind of device. That device was able to show an illusion of reality. In a world of 2D images, that device dared to show 3D images, that simulate the perpective and depth of the human eye. That device was called IrisGL (probaly because it tries to simulate the eye's iris).

Well, serious, that device was the first great Graphics Library. But it died fast, because to do what he did, he needed to control many things in computers like the graphical card, the windowing system, the basic language and even the front end. It's too much to just one company manages. So the SGI started to delegate some things like "create graphics cards", "manage the windowing", "make the front end" to other companies and get focus on the most important part of their Graphical Library. In 1992 was launch the first OpenGL.

In 1995 Microsoft released the Direct3D, the main competitor of OpenGL.
And only in 1997 OpenGL 1.1 was released. But OpenGL becomes really interesting to me only in 2004, which the OpenGL 2.0 was released with a great change. The Shaders, the programmable pipeline. I love it!
And finally in 2007 we meet the OpenGL ES 2.0 wich bring to us the power of Shader and programmable pipeline to the Embedded Systems.

Today you can the see the OpenGL's logo (or OpenGL ES) in many games, 3D applications, 2D applications and a lot of graphical softwares (specially in 3D softwares). OpenGL ES is used by PlayStation, Android, Nintendo 3DS, Nokia, Samsung, Symbian and of course by Apple with MacOS and iOS.

OpenGL's Greatest Rival

Talking about Microsoft Windows OS (Brugh!!)
OK, do you remember I said that the first launch of OpenGL was in 1992? So at that time, Microsoft has their shiny Windows 3.1. Well, as Microsoft always believe that "Nothing is created, everything is copied", Microsoft tries to copy OpenGL in what they called DirectX and introduced it in 1995 on Windows 95.

One year later, in 1996, Microsoft introduced Direct3D which is a literal copy of OpenGL. The point is that Microsoft dominate the info market for years, and DirectX or (Direct3D) penetrated and grabbed like a plague in many computers (PCs) and when Microsoft started to deliver their OS to the mobiles and video games, DirectX goes together.

Today DirectX is very similar in structure to OpenGL: has a Shader Language, has a programmable pipeline, has fixed pipeline too, even the names of the function in the API are similar. The difference is that OpenGL is OPEN, but DirectX is closed. OpenGL is for iOS, MacOS and Linux Systems while the DirectX is just for Microsoft OS.

Great, now let's start our journey into 3D world!

3D world

First Point - The Eye

Since I can remember, I was passionate by 3D world and 3D games. All that we, humans, know about simulate the real world in a 3D illusion comes from just one single place: our eye.

The eye is the base of everything in 3D world. All that we do is to simulate the power, the beauty and the magic of the human's eye. I'm not a doctor (despite being the son of two) and don't want to talk about the eye in this tutorial, but will be good if you're used to some concepts like: field of view, binocular and monocular vision, eye's lens, concave and convex lens, and this kind of things, this can help you to understand some concepts.

Everything we do in 3D world is to recreate the sensations from the human eye: the perpectives, the vanish points, the distortions, the depth of field, the focus, the field of view, in resume, everything is to simulate that sensations.

Second Point - The Third Dimension

This can seems stupid, but it's necessary to say: 3D world is 3D because has 3 dimensions. "WTF! This is so obviously!", calm down, dude, I'm speaking this because is important to say that an addition of one single dimension (compared to 2D world) led us into serious troubles. That does not create 1 or 3 little problems, but drive us into a pool of troubles.

Look, in 2D world when we need to rotate a square is very simple, 45º degrees always will led our square to a specific rotation, but in 3D world, to rotate a simple square requires X, Y and Z rotation. Depending on which order we rotate first, the final result can be completely different. The things becomes worse when we make consecutive rotations, for example, rotate x = 25 and Y = 20 is one thing, but rotate x = 10, y = 20 and then x = 10 again is a completely new result.

Well, the point here is to say that an addition of one another dimension makes our work be stupidly multiplied.

Third Point - It's not 3D... it's often 4D.

WTF! Another dimension?
Yes dude, the last point that I need to say is it. Often we don't work just in a 3D world, we have a fourth dimension: the time. The things in 3D world need to interact, need to move, need to accelerate, need to collide itself, need to change their inertias. And as I told before, make consecutive changes in 3D world can drive us into multiple results.

OK, until now we have a phrase to define the 3D world: "Is the simulation of the human eye and everything moves.".

OpenGL into the 3D world

Now this tutorial starts to be a little more fun. Let's talk about the great engine OpenGL. First we need to thank to great mathematicians like Leonhard Euler, William Rowan Hamilton, Pythagoras and so many others. Thanks to them, today we have so many formulas and techniques to work with 3D space. OpenGL used all this knowledge to construct a 3D world right on our face. Are thousands, maybe millions of operations per second using a lot of formulas to simulate the beauty of the human eyes.

OpenGL is a great STATE MACHINE (this means that entire OpenGL works with the State Design Pattern). To illustrate what OpenGL is, let's imagine a great Port Crane in some port. There are so many containers with a lot of crates inside. OpenGL is like the whole port, which:

• The containers are the OpenGL's objects. (Textures, Shaders, Meshes and this kind of stuff)
• The crates inside each containers is what we created in our applications using the OpenGL. Are our instances.
• The port crane is the OpenGL API, which we have access.

How OpenGL works

OpenGL's Logic

• Primitives
• Buffers
• Rasterize

Just it? 3 little things?
Believe, OpenGL works around these 3 concepts. Let's see each concept independently and how the three can join to create the most advanced 3D Graphics Library (also you can use OpenGL to 2D graphics. 2D images to OpenGL is just a 3D working all in the Z depth 0, we'll talk about later on).

Primitives

OpenGL's primitives is limited to 3 little kind of objects:

• About a 3D Point in space (x,y,z)
• About a 3D Line in space (composed by two 3D Points)
• About a 3D Triangle in space (composed by three 3D Points)

A 3D Point can be used as a particle in the space.
A 3D Line is always a single line and can be used as a 3D vector.
A 3D Triangle could be one face of a mesh which has thousands, maybe millions faces.
Some OpenGL's versions also support quads (quadrangles), which is merely an offshoot of triangles. But as OpenGL ES was made to achieve the maximum performance, quads are not supported.

Buffers

Now let's talk about the buffers. In simple words, buffer is a temporary optimized storage. Storage for what? For a lot of stuffs.
OpenGL works with 3 kind of buffers:

• Frame Buffers
• Render Buffers
• Buffer Objects

Frame Buffers is the most abstract of the three. When you make an OpenGL's render you can send the final image directly to the device's screen or to a Frame Buffer. So Frame Buffer is a temporary image data, right?
Not exactly. You can image it as an output from an OpenGL's render and this can means a set of images, not just one. What kind of images? Images about the 3D objects, about the depth of objects in space, the intersection of objects and about the visible part of objects. So the Frame Buffer is like a collection of images. All of these stored as a binary array of pixel's information.

Render Buffer is a temporary storage of one single image. Now you can see more clearly that a Frame Buffer is a collection of Render Buffers. Exist few kinds of Render Buffer: Color, Depth and Stencil.

• Color Render Buffer stores the final colored image generated by OpenGL's render. Color Render Buffer is a colored (RGB) image.
• Depth Render Buffer stores the final Z depth information of the objects. If you are familiar to the 3D softwares, you know what is a Z depth image. It's a grey scale image about the Z position of the objects in 3D space, in which the full white represent most near visible object and black represent the most far object (the full black is invisible)
• Stencil Render Buffer is aware about the visible part of the object. Like a mask of the visible parts. Stencil Render Buffer is a black and white image.

Buffer Objects is a storage which OpenGL calls "server-side" (or server’s address space). The Buffer Objects is also a temporary storage, but not so temporary like the others. A Buffer Object can persist throughout the application execution. Buffer Objects can hold informations about your 3D objects in an optimized format. These information can be of two type: Structures or Indices.

Structures is the array which describe your 3D object, like an array of vertices, an array of texture coordinates or an array of whatever you want. The Indices are more specifics. The array of indices is to be used to indicate how the faces of your mesh will be constructed based on an array of structures.

Seems confused?

OK, let's see an example.
Think about a 3D cube. This cube has 6 faces composed by 8 vertices, right?

Each of these 6 faces are quads, but do you remember that OpenGL just knows about triangles? So we need to transform that quads into triangles to work with OpenGL. When we do this, the 6 faces become 12 faces!
The above image was made with Modo, look at the down right corner. That are informations given by Modo about this mesh. As you can see, 8 vertices and 12 faces (GL: 12).
Now, let's think.

Triangles in OpenGL is a combination of three 3D vertices. So to construct the cube's front face we need to instruct OpenGL at this way: {vertex 1, vertex2, vertex 3}, {vertex 1, vertex 3, vertex 4}. Right?

In other words, we need to repeat the 2 vertices at each cube's face. This could be worst if our mesh has pentangle we need to repeat 4 vertices informations, if was an hexangle we need to repeat 6 vertices informations, a septangle, 8 vertices informations and so on.
This is much much expansive.

So OpenGL give us a way to do that more easily. Called Array of Indices!
In the above cube's example, we could has an array of the 8 vertices: {vertex 1, vertex 2, vertex 3, vertex 4, ...} and instead to rewrite these informations at each cube's faces, we construct an array of indices: {0,1,2,0,2,3,2,6,3,2,5,6...}. Each combination of 3 elements in this array of indices (0,1,2 - 0,2,3 - 6,3,2) represent a triangle face. With this feature we can write vertex's information once and reuse it many times in the array of indices.

Now, returning to the Buffer Objects, the first kind is an array of structures, as {vertex 1, vertex 2, vertex 3, vertex 4, ...} and the second kind is an array of indices, as {0,1,2,0,2,3,2,6,3,2,5,6...}.

The great advantages of Buffer Objects is they are optimized to work directly in the GPU processing and you don't need hold the array in your application any more after create a Buffer Object.

Rasterize

The rasterize is the process by which OpenGL takes all informations about 3D objects (all that coordinates, vertices, maths, etc) to create a 2D image. This image will suffer some changes and then it will be presented on the device's screen (commonly).

But this last step, the bridge between pixel informations and the device's screen, it's a vendor's responsibility. The Khronos group provide another API called EGL, but here the vendors can interfere. We, developers, don't work directly with Khronos EGL, but with the vendor's modified version.

So, when you make an OpenGL render you can choose to render directly to the screen, using the vendor's EGL implementation, or render to a Frame Buffer. Rendering to a Frame Buffer, you still in the OpenGL API, but the content will not be showed onto device's screen yet. Rendering directly to the device's screen, you go out the OpenGL API and enter in the EGL API. So at the render time, you can choose one of both outputs.

But don't worry about this now, as I said, each vendor make their own implementation of EGL API. The Apple, for example, doesn't let you render directly to the device's screen, you always need to render to a Frame Buffer and then use EGL's implementation by Apple to present the content on the device's screen.

OpenGL's pipelines

I said before about "programmable pipeline" and "fixed pipeline". But what the hell is a programmable pipeline? In simple words?

The programmable pipeline is the Graphics Libraries delegating to us, developers, the responsibility by everything related to Cameras, Lights, Materials and Effects. And we can do this working with the famous Shaders. So every time you hear about "programmable pipeline" think in Shaders!

But now, what the hell is Shaders?

Shaders is like little pieces of codes, just like little programs, working directly in the GPU to make complex calculations. Complex like: the final color of a surface's point which has a T texture, modified by a TB bump texture, using a specular color SC with specular level SL, under a light L with light's power LP with a incidence angle LA from distance Z with falloff F and all this seeing by the eyes of the camera C located on P position with the projections lens T.

Whatever this means, it's much complex to be processed by the CPU and is so much complex to Graphics Libraries continue to care about. So the programmable pipeline is just us managing that kind of thing.

And the fixed pipeline?

It's the inverse! The fixed pipeline is the Graphics Library caring about all that kind of things and giving to us an API to set the Cameras, Materials, Lights and Effects.

To create shaders we use a language similar to C, we use the OpenGL Shader Language (GLSL). OpenGL ES use a little more strict version called OpenGL ES Shader Language (also known as GLSL ES or ESSL). The difference is that you have more fixed functions and could write more variables in GLSL than in GLSL ES, but the syntax is the same.

Well, but how did works these shaders?

You create them in a separated files or write directly in your code, whatever, the important thing is that the final string containing the SL will be sent to the OpenGL's core and the core will compile the Shaders to you (you even can use a pre-compiled binary shaders, but this is for another part of this serie).

The shaders works in pairs: Vertex Shader and Fragment Shader. This topic needs more attention, so let's look closely to the Vertex and Fragment shaders. To understand what each shader does, let's back to the cube example.

Vertex Shader

Vertex Shader, also known as VS or VSH is a little program which will be executed at each Vertex of a mesh.
Look at the cube above, as I said early, this cube needs 8 vertices (now in this image the vertex 5 is invisible, you will understand why shortly).
So this cube's VSH will be processed 8 times by the GPU.

What Vertex Shader will do is define the final position of a Vertex. Do you remember that programmable pipeline has left us the responsible by the camera? So now is it's time!

The position and the lens of a camera can interfere in the final position of a vertex. Vertex Shader is also responsible to prepare and output some variables to the Fragment Shader. In OpenGL we can define variable to the Vertex Shader, but not to the Fragment Shader directly. Because that, our Fragment's variables must pass through the Vertex Shader.

But why we don't have access to the Fragment Shader directly?
Well, let's see the FSH and you will understand.

Fragment Shader

Look at the cube image again.
Did you notice vertex 5 is invisible? This is because at this specific position and specific rotation, we just can see 3 faces and these 3 faces are composed by 7 vertices.

This is what Fragment Shader does! FSH will be processed at each VISIBLE fragment of the final image. Here you can understand a fragment as a pixel. But normally is not exactly a pixel, because between the OpenGL's render and the presentation of the final image on the device's screen has stretches. So a fragment can result in less than a real pixel or more than a real pixel, depending on the device and the render's configurations. In the cube above, the Fragment Shader will be processed at each pixel of that three visible faces formed by 7 vertices.

Inside the Fragment Shader we will work with everything related to the mesh' surface, like materials, bump effects, shadow and light effects, reflections, refractions, textures and any other kind of effects we want. The final output to the Fragment Shader is a pixel color in the format RGBA.

Now, the last thing you need to know is about how the VSH and FSH works together. It's mandatory ONE Vertex Shader to ONE Fragment Shader, no more or less, must be exactly one to one. To ensure we'll not make mistakes, OpenGL has something called Program. A Program in OpenGL is just the compiled pair of VSH and FSH. Just it, nothing more.

Conclusion

Very well!

This is all about the OpenGL's concepts. Let's remember of everything.

1. OpenGL's logic is composed by just 3 simple concepts: Primitives, Buffers and Rasterize.
   • Primitives are points, lines and triangles.
   • Buffers can be Frame Buffer, Render Buffer or Buffer Objects.
   • Rasterize is the process which transform OpenGL mathematics in the pixels data.
2. OpenGL works with fixed or programmable pipeline.
   • The fixed pipeline is old, slow and large. Has a lot of fixed functions to deal with Cameras, Lights, Materials and Effects.
   • The programmable pipeline is more easy, fast and clean than fixed pipeline, because in the programmable way OpenGL let to us, developers, the task to deal with Cameras, Lights, Materials and Effects.
3. Programmable pipeline is synonymous of Shaders: Vertex Shader, at each vertex of a mesh, and Fragment Shader, at each VISIBLE fragment of a mesh. Each pair of Vertex Shader and Fragment Shader are compiled inside one object called Program.

Looking at these 3 topics, OpenGL seems very simple to understand and learn. Yes! It is very simple to understand... but to learn... hmmm...
The 3 little topics has numerous ramifications and to learn all about can take months or more.

What I'll try to do in the next two parts of this serie is give to you all what I've learned in 6 immersive months of deeply hard OpenGL's study. In the next one, I'll will show you the basic functions and structures of a 3D application using the OpenGL, independently of which programming language you are using or which is your final device.

But before it, I want to introduce you one more OpenGL's concept.

OpenGL's Error API

OpenGL is a great State Machine working as a Port Crane and you don't have access to what happen inside it. So if an error occurs inside it, nothing will happens with your application, because OpenGL is a completely extern core.

But, how to know if just one of your shaders has a little error? How to know if one of your render buffers is not properly configured?

To deal with all the errors, OpenGL gives to us an Error API. This API is very very simple, it has few fixed function in pairs. One is a simple check, Yes or Not, just to know if something was done with successful or not. The other pair is to retrieve the error message. So is very simple. First you check, very fast, and if has an error then you get the message.

Generally we place some checks in critical points, like the compilations of the shaders or buffers configurations, to stay aware about the most communs errors.

On the Next

OK, dude, now we are ready to go.
At next tutorial let's see some real code, prepare your self to write a lot.

Thanks for reading and see you in the next part!

NEXT PART: Part 2 - OpenGL ES 2.0 in deeply (Intermediate)

This article will treat article the myth and truths behind iOS ARC (Automatic Referece Counting) and MRR (Manual Retain Release). Let's understand how it works, what the compiler does with it, why some people love it and other hate it. Also, my favorite part, let's see how to create a cross ARC/MRR application! When working on team, usually in agencies and companies we have a Senior developer (which usually prefers MRR) and a Junior developer (which prefers ARC) working on the same project. Using this technique both can work happy together.

At a glance

It's important to say that this is not an ARC tutorial. I'll not teach you how to use ARC at all. To continue reading you must already know what ARC is. This article is to show you how to integrate ARC and MRR in the same application, or is better to say, how to make a code that compiles in ARC and in MRR environment without changing one single line of code.

First off, we must understand how the ARC goes on, what it really means to the final compiled code. Of course, if you're a Senior dev, you can just skip this introduction and go to the funny part here.

Here is the sample Xcode project for this tutorial:

Download now
Xcode project files to iOS 5.1 or later
4.0Mb


Github: https://github.com/dineybomfim/arc-mrr/

OK. Let's get started.

The ARC concept

The first thing you must to understand about ARC is: it's sucks! The ARC concept to save your time coding is not really a big deal for who really knows to manage the memory of the application. In fact, there is no real time save using ARC, the point about it is: for developers that came from other languages that support Gargabe Collection, the memory management concept is really a very hard part to understand.

So here is the real point of Apple creating ARC: learning Obj-C for those ones that never saw any kind of memory management is really painful!

I can say that because I walked through this path. I started my developer life with very high ending languages, Server Side languages, Java Script and this kind of shit. So when I meed C the concept of memory management was something really new with no relation with my background. Thinking like Apple, increase the group of Obj-C developer is very important and then ARC concept comes in to solve a big hole in the issue about engaging new developers, increasing the community.

Some may ask about Garbage Collection. Well, Mac OS has Garbage Collection and MRR as well. But for iOS, running on very tiny and limited devices the life battery matter is the biggest problem. Garbage Collection on iOS could really kill the battery life so this is completely out of the question. Running something on background all the time just to make sure the memory management is on the track is not possible on mobiles.

The ARC concept is very simple: developers don't need to think about the memory management because we (Apple) will review his code, looking for all the places where the memory should be allocated and released. Then we (Apple) will place the instructions about retaining, releasing or even autoreleasing in the right spots. All this job will be made during the compilation of the code. So every time the developer hit "compile" we'll review his code first. No costs for the application on runtime. It's a very great idea, doesn't it?

Yeah, the theory is perfect, but not the practice. Memory management is something extremely complex and has a lot of collateral effects in the entire code. So to make sure the Apple ARC is not doing shit, they ask to the developer to give some instructions, like saying this variable is "strong", that means, I'll need it over a very long time and this variable is "weak", that means, I just need it for a short period of time.

There are much more. The developers also need to say when a basic C variable is cast to an Obj-C variable what kind of conversion is involved, because the ARC is just for Obj-C, not for pure C.
O.o
Oh God...

The high Obj-C framework is far for controlling everything. If you need anything more specific you'll face the low level Apple frameworks, that is pure C. Actually I love C. I'm used to say that here is no real iOS or Mac application made with pure Obj-C. You'll always mix Obj-C and pure C, because in fact Obj-C is a C (a superset of C).

So, I think you already got my point. In very simple questions: Apple had a good intention creating ARC. However this is just for beginners. If you want to make a little bit better application you'll need to learn a lot of concepts of memory management. You'll need to learn about C pointers and MRR any way. Even if you choose for keep using ARC, you'll need to learn how it really works.

ARC - Behind the scenes

OK, no more shit talking, let's go to the action. Let's understand what goes behind the ARC.

@interface ClassA : NSObject
{
@private
    NSDictionary *_myDict;
}

- (void) myMethod;
@end

@implementation ClassA

- (void) myMethod
{
    NSMutableArray *array = [[NSMutableArray alloc] init];

    unsigned int i, length = 10;
    for (i = 0; i < length; ++i)
    {
        [array addObject:[[NSString alloc] initWithFormat:@"%i",i]];
    }

    _myDict = [[NSDictionary alloc] initWithObjectsAndKeys:array, @"keyArray", nil];
}

@end

The above is what you code, but this is what really goes on to the compiler:

@interface ClassA : NSObject
{
@private
    __strong NSDictionary *_myDict;
}

- (void) myMethod;
@end

@implementation ClassA

- (void) myMethod
{
    NSMutableArray *array = [[NSMutableArray alloc] init];

    unsigned int i, length = 10;
    for (i = 0; i < length; ++i)
    {
        NSString *__scopeVar1 = [[NSString alloc] initWithFormat:@"%i",i];
        [array addObject:__scopeVar1];
        [__scopeVar1 release];
        __scopeVar1 = nil;
    }

    if (_myDict != nil)
    {
        [_myDict release];
        _myDict = nil;
    }
    _myDict = [[NSDictionary alloc] initWithObjectsAndKeys:array, @"keyArray", nil];

    if (array != nil)
    {
        [array release];
        array = nil;
    }
}

- (void) dealloc
{
    if (_myDict != nil)
    {
        [_myDict release];
        _myDict = nil;
    }

    [super dealloc];
}

@end

WOW, much more code, it's true! However it's much more understandable to see what is going on with the application memory.

Notice that variables inside a scope will always die, I mean, be released inside the same scope. The "array" for example will die in the end of its scope and the "__scopeVar1" will die in the end of its own scope. It's important to say that the ARC will always prefer the direct "release" instead of "autorelease", because it's better, fasters and saves more memory. In fact, the "autorelease" is used in very few situations by ARC, like the returning of a function/method, in this case there is no other way than autoreleasing the instance. Let's see more about "autorelease" soon.

Other thing I want to call the attention is how ARC will release the variables. ARC is prepared to use what we call "safe release", that means, the variable will always be set to "nil" after being released. This is a safety way to avoid Zombies. Don't know what is it? Zombies is where an instance receives a double "release" command. So if an instance was already released and receives another "release" message the application will crash. I'll explain it better right next, now just keep in mind that by checking if the variable is not "nil" and then setting it to "nil" right after releasing it is a safe way to avoid Zombies. Of course there are many other ways to get a Zombie, however by using this method you can avoid a lot of them.

More about ARC in my Obj-C Memory article.

ARC + MRR = S2

OK fellows, here is what you're looking for. The problem today is, like I said, the team work, when a senior developer wants to use MRR and a Junior just know about the ARC. I like to create a global file called Runtime.h, it will hold all the runtime related things, in majority, C macros.

Here is what you need.

/*
 *    ARC+MRR.h
 *    ARC+MRR
 *    
 *    Created by Diney Bomfim on 4/28/13.
 *    Copyright 2013 db-in. All rights reserved.
 */

// Defines the ARC instructions.
#if __has_feature(objc_arc)

    // ARC definition.
    #define IS_ARC

    // Convertion instructions.
    #define ARC_UNSAFE          __unsafe_unretained
    #define ARC_BRIDGE          __bridge
    #define ARC_ASSIGN          __weak
    #define ARC_RETAIN          __strong

    // Property definitions
    #define RETAIN              strong
    #define ASSIGN              weak
    #define COPY                copy

#else

    // Convertion instructions.
    #define ARC_UNSAFE
    #define ARC_BRIDGE
    #define ARC_ASSIGN
    #define ARC_RETAIN

    // Property definitions
    #define RETAIN              retain
    #define ASSIGN              assign
    #define COPY                copy

#endif

// The retain routine.
#ifdef IS_ARC
    #define arcRetain(x)        (x)
#else
    #define arcRetain(x)        ([x retain])
#endif

// The release routine.
#ifdef IS_ARC
    #define arcRelease(x)       ({ (x) = nil; })
#else
    #define arcRelease(x)       ({ if(x) { [x release]; (x) = nil; } })
#endif

// The autorelease routine.
#ifdef IS_ARC
    #define arcAutorelease(x)   (x)
#else
    #define arcAutorelease(x)   ([x autorelease])
#endif

// The free routine, not really necessary for ARC, but let's do it to make a safe free as well.
#define nppFree(x)              ({ if(x) { free(x); (x) = NULL; } })

That's it!
I prefer to use the terms "RETAIN" and "ASSIGN", because they sounds more correctly to me. Of course you can change it to "STRONG" and "WEAK" respectively if you want. Anyway, the point it how to use it? Here:

@interface ClassA : NSObject
{
@private
    NSDictionary *_myDict;
    ARC_ASSIGN NSString *_tempVar;
}

@property (nonatomic, RETAIN) NSString *strongProperty;
@property (nonatomic, ASSIGN) NSString *weakProperty;
@property (nonatomic, COPY) NSString *copyProperty;

- (void) myMethod;
@end

@implementation ClassA

- (void) myMethod
{
    NSMutableArray *array = arcAutorelease([[NSMutableArray alloc] init]);

    unsigned int i, length = 10;
    for (i = 0; i < length; ++i)
    {
        NSString *__scopeVar1 = [[NSString alloc] initWithFormat:@"%i",i];
        [array addObject:__scopeVar1];
        arcRelease(__scopeVar1);
    }

    arcRelease(_myDict);
    _myDict = [[NSDictionary alloc] initWithObjectsAndKeys:array, @"keyArray", nil];
}

@end

There are other usages of these definitions. I'll not show all here to don't take too much of your time. In this tutorial there is a sample project, you can get it and see all the other usages. Check how it's simple to use it. You can turn OFF or ON the Objective-C ARC compiler's feature without changing even one single line of code!

Conclusion

Very well my friends, that's it. Let's make a fast concept review:

1. ARC is not a savior! It's just a way that Apple founds to avoid loosing near devs.
2. ARC just make a very simple work during the compilation, not a big deal.
3. Using macros we can easily "undo" what ARC "does". This is good for large team works and specially when making frameworks.

Remember, ARC will not save your ass all the time. You must understand what goes under the code to avoid leaks and zombies. I've seen junior developers getting zombies even with ARC! Trust me, it's much more easy than you can image.

If you have any doubts, just Tweet me:

Tweet

See you soon!

Download now
Xcode project files to iOS 5.1 or later
4.0Mb


Github: https://github.com/dineybomfim/arc-mrr/