Welcome to the NinevehGL's world!
NinevehGL is a 3D engine forged with pure Obj-C.
Just 30min
to learn everything about!

The NinevehGL's golden rule is:"Keep it simple!"

The video lessons are now divided in 3 categories: Basics, Features and Effects. Each video tutorial has up to 10 min and can teach you many aspects about NinevehGL. Besides, there are some other advanced topics you can learn in the full documentation guide.

For any video, just click on the thumbnail to play the video right here, or choose one of the video servers. Inside any of the video servers you will find the same list of content.

If you read the tutorials and you are still having doubts, just ask us via Twitter or send us an email via Contact section.

Lessons: Basics

This set of lessons teach you about the basic concepts and code to work with NinevehGL.

Here you will see how to import the framework into your project, import 3D files, create cameras, groups and make transformations on your meshes.

Watch on Vimeo | Watch on YouTube | Continue reading


Creating a NinevehGL APP is easy, just start a new project using the NinevehGL templates.

Or if you preffer, you can import the NinevehGL.framework into any other project. In this last case, you also needs to import the frameworks OpenGLES and QuartzCore

Open the Xcode with a new project Import the frameworks:OpenGLES, QuartzCore and NinevehGL
Replace an UIView by a NGLView


Using the Interface Builder (IB) tool, change the desired UIView by a NGLView.

The NGLView is a subclass of UIView. Each NGLView represents a 3D view instance with its own render cycle, that means, for each 3D view there are separated Frame Buffer, Render Buffers, frame rate, render filters and render cycle.


Import your 3D file(s) into the Xcode project. Also import all related textures and image files.

Import your 3D file(s) into the Xcode.
Use #import <NinevehGL/NinevehGL.h> to start coding with NinevehGL.


The NinevehGL offer the delegate routine, just as the Cocoa framework does. You can set the delegate target directly in the Interface Builder or set it manually in your code.

Instead of using the delegate routine and IB tool, you can create your own subclass of NGLView.

There are two important classes that you will use a lot: NGLMesh and NGLCamera.


You can import the 3D files with the NGLMesh by using the loadFile:settings:type: or at the initialization time by using the initWithFile:settings:delegate: methods.

The meshes must be rendered by a camera, you can "add" the meshes manually or at the initialization time by using initWithMeshes: method.

Initialize your NGLMesh and NGLCamera instances.
Use #import <NinevehGL/NinevehGL.h> to start coding with NinevehGL.


There are many dictionary of settings in NinevehGL, all of them use a well defined pattern for the values and keys:

k + <Class Name> + <Value Explanation>
k + <Class Name> + Key + <Value Explanation>

Notice that both constants are very similar, the difference is just a "Key" word right after the Class Name.

Those settings use only two kind of values: Strings and Numbers (float or int). In any case, the Strings is always acceptable, you can write float or int values with strings.


Absolute rotation is made always from the origin. Absolute rotations will always produce the same effect at a specific angle. For example, a rotation in XYZ of 0.0, 0.0, 0.0 will take the object to its default state, without any rotation on it.

On the other hand, the relative rotation is made from the actual state, so a rotation in XYZ of 0.0, 0.0, 0.0 will not reset the object rotation, just will make no changes in the actual state.

Absolute VS Relative concept.


World rotation, also know as Global rotation, relates to the rotation happening in relation to the world space. It doesn't matter the actual object state, a World rotation on axis X always will turn the object toward the screen (assuming no changes camera), for example.

On the other side, the Local rotation happens in the local space. For example, a Local rotation on axis X will turn the object around its own axis X, not the world axis. The Local rotations suffer influences of the previous rotations. At this point make sure you don't get confused with Relative rotation. A rotation can be Absolute and Local at the same time, for example.


There are 6 Rotation Orders. These orders represent how the consecutive rotations will happen during an animation. The rotations can achieve different results depending on the order in which they've happened.

The six orders are: XYZ, XZY, YXZ, YZX, ZXY, ZYX

Rotation Order concet.


Create two or more meshes and implement one touch routine to get the pinch and pan gestures. The Cocoa framework offers many ways to get the touch inputs, choose the one you want.


The lookAt routine can be used frame by frame, calling the respective method, or can be set once by setting the target property. Notice that lookAt routine doesn't change the translations which means that it is not a follow routine.

Make many tests to understand the rotation behaviors and play with the lookAt routine.


Using the relative methods you can add little increments to the camera transformations. The relative methods are:

  • moveRelativeTo:distance: - Move the camera based on a NGLMove.
  • translateRelativeToX:toY:toZ: - Move the camera based on increments in three axis.
  • rotateRelativeToX:toY:toZ: - Rotate the camera based on increments in three axis.


Besides, you can use the absolute transformation methods as well.

Remember that the absolute methods will place the object in a specific position over the 3D world. To navigate just add (or subtract) small increments.


Create groups in NinevehGL is very simple, you'll use the NGLGroup3D. It's a subclass of NGLObject3D, so you can transform it as any other object. Each object can be member of only one group at a time, if you try to add the same object to more than one group it will be detached from the old one and will become a member of the new group.

As a NGLGroup3D is also an object, you can create a chain/hierarchy of groups and objects. Besides, notice that any object can act as a "group", that means, the transformation chain can be made with any kind of NGLObject3D, although only the NGLGroup3D has the properties necessary to be a collection and aggregate many objects in it.


There are two copy methods in NinevehGL: copy and copyInstance. You can use these methods to clone objects and save the memory and loading time, in the case of NGLMesh.

The copy method will duplicate all the memory of an object, but if you want to save memory and keep the core of an object intact, you can use the copyInstance. Consult the NGLCopying documentation to see the full list of classes and features of the copying routine in NinevehGL.


As with the NinevehGL you never need to touch directly in the OpenGL API, you can make use of Global API to make some changes. The global API is formed by basic C functions with no return data (void).

Each function changes a variable called Global Property. Often, there is a local property with the same behavior of the Global Property, in these cases, the Global Property overrides the local one. To invalidate the Global Property, just set its value to NGL_NULL.

The global functions are:

  1. nglGlobalFlush(void) - Every global change works asynchronously, so after make one or more changes to the global function you must call this function to your changes take effect.
  2. nglGlobalFilePath(NSString *filePath) - For every external file you should specify the full path in the file system, but the NinevehGL makes it easy for you. If you just inform the file name, without any path, the NinevehGL will search the file using the Global Path. You can set any Global Path you want, by default it is the application main bundle.
  3. nglGlobalFPS(unsigned short fps) - This function changes the global frame rate.
  4. nglGlobalEngine(NGLEngineVersion engine) - The NinevehGL is OpenGL version free, that means, your code doesn't need to change when new versions of OpenGL comes out. To take advantage of a specific OpenGL version, just set this Global Property. By default it's set to OpenGL ES 2.0 version.
  5. nglGlobalColorFormat(NGLColorFormat colorFormat) - The supported color formats are: NGLColorFormatRGB and NGLColorFormatRGBA. This Global Property changes the EAGL context and allows your application to work with the alpha channel. The default format is RGB.
  6. nglGlobalColor(NGLvec4 color) - This Global Property represents the default color. It affects the NinevehGL's background color and the default color for new Fog effects.
  7. nglGlobalFrontAndCullFace(NGLFrontFace front, NGLCullFace cull) - This function changes a double Global Property. Both are used to define the face formats of your application.
  8. nglGlobalAntialias(NGLAntialias antialias) - This function changes the antialias filter. Remember that this filter is very expensive, use it only in special situations.
  9. nglGlobalTextureQuality(NGLQuality quality) - This function changes the default quality for any new texture.
  10. nglGlobalTextureRepeat(NGLRepeat repeat) - This function changes the default repeat property for any new texture.
  11. nglGlobalTextureOptimize(NGLOptimize optimize) - This function changes the default optimization behavior for any new texture.
  12. nglGlobalRotationSpace(NGLRotationSpace space) - This function changes the default rotation space for any mesh, even the existing meshes.
  13. nglGlobalRotationOrder(NGLRotationOrder order) - This function changes the default rotation order for any mesh, even the existing meshes.
  14. nglGlobalImportSettings(NSDictionary *settings) - This function sets a global import settings to future imports with NGLMesh.
  15. nglGlobalLightEffects(NGLLightEffects effect) - This function turns ON or OFF the global light effect.
  16. nglGlobalMultithreading(NGLMultithreading option) - This function changes the multithreading option.
Lessons: Features

This set of lessons teach you about some exclusive features of NinevehGL.

Here you will learn about the NGL Binary file, Multithreading and Tween API. These three features will boost your application automatically for free.

Watch on Vimeo | Watch on YouTube | Continue reading


The NGL Binary file is generated at the first time you import a new 3D file, the NinevehGL's core will create a correlated binary file, which stores the data with an OpenGL friendly format. This file will be stored locally on the device.

At the second time that your application tries to import the same 3D file, the NinevehGL's core will compare the original with the binary copy and will choose the most recent file. So you can update the original 3D files with a new version of your APP (by iTunes) or even downloading the 3D file directly to the device via internet. At the next run of your APP, the NinevehGL's core will respect your update by using the original file again and updating the correlated binary file.

The NGL Binary file is generated automatically.
This process happens every time a new 3D file is imported.


There is no limit on how many NGL Binary files your application can deal with.
The binary files are stored in the folder <Application_Home>/Library/NinevehGL/.

Besides you can import a NGL Binary file directly rather than the traditionals OBJ and COLLADA format. To get a NGL Binary from your files outside the application, you can convert them on-line! No plugins to install on your machine. Just access: http://nineveh.gl/binary/ (not online during the Beta phase).


The result is evident to your final users. At the first run, your application take some time to load and parse the 3D files. But from the second run and the next ones, your application loads around 85X faster, some times 100X faster.

Up to 100X fasters!
This process happens every time a new 3D file is imported.


The NinevehGL has full and real multithreading. There are some kinds of threads:

  1. Render Thread: A background thread that take care of all the drawing commands. It's a long-lived thread.
  2. Helper Thread: A background thread that is responsible for uploading the meshes into the OpenGL core. It's a short-lived thread.
  3. Parser Threads: A collection of background threads that are responsible for the loading process, which includes the parsing. They all are short-lived threads.

You can turn on/off these types of threads. When a thread type is turned off, all its work return to the main thread. So if you choose to use only the render thread (NGLMultithreadingRender), all the Loading Process will be made in the main thread and the render will still on a background thread.
By default, NinevehGL will use all its 7 threads if necessary (1 render + 1 helper + 5 loadings).


The Loading Process (in NinevehGL the expression "Loading Process" is used to describe the loading, parsing and uploading of the meshes) is the most expensive task in the 3D applications, so to optimize this process and let you make your best to boost the user experience, NinevehGL offers the multithreading feature. It work with 5 background threads for loading, 1 thread for render and 1 helper thread.

All those threads can loading and parse your mesh like a streaming, that means, the mesh can appear on the screen progressively. As the surfaces is being constructeds it will appear on the screen.

Besides, with the render into a background thread the render cycle never stops, that means you can place a NGLView inside a UIScrollView and the render will still happening even when scrolling. The NinevehGL multithreading is a huge feature to let you create amazing user experiences in your applications.

Up to 100X fasters!
This process happens every time a new 3D file is imported.


The NinevehGL Tween API was made to deal with any kind of animations you want, specially in case of the loop animations. You just set it once and the Tween API will update the properties at every render cycle. It uses the same frame rate as the global property.

The Tween API has some predefineds ease functions, like Smooth, Elastic, Bounce, etc. All those functions has In, Out and InOut modifiers. You can also create your own ease function and use it with the Tween API. Consult the documentation for full instructions about this API.

Lessons: Effects

This set of lessons teach you about advanced features of NinevehGL.

Here you will learn about the NGL Binary file, Multithreading and Tween API. These three features will boost your application automatically for free.

Watch on Vimeo | Watch on YouTube | Continue reading


You can create your own material by using the NGLMaterial class and set it to the mesh's property. Any change to the mesh's structure must be followed by a call to compileCoreMesh method, which will reconstruct the OpenGL shaders.

You can create a single custom material.
You can create multiple materials to a single mesh.


The NinevehGL gives you the possibility to set multiple materials to a single mesh. To use any kind of multi element into a mesh, you must define the surface areas. To do that, use the NGLSurfaceMulti class. Add NGLSurface instances into the multi library.

You must know the mesh to define the surface areas. Once you set the surface areas, you must create a NGLMaterialMulti instance and insert your desired materials.

Then, you add the multi libraries to the correspondent mesh's properties and call the compileMesh method.


To create texture object in NinevehGL, make use of the NGLTexture class. To define textures to your meshes, just create a new NGLMaterial, as shown in the Lesson 8, and set the NGLTexture to the texture property you want.

The texture properties are:

  1. alphaMap - Defines the alpha region. It should preferably be in grey scale, which the black color represents total transparency. Your application must run with RGBA color format to support alpha channel.
  2. ambientMap - Defines the material's ambient color absorption. Often, it's used to simulate ambient light.
  3. diffuseMap - Defines the diffuse map. It's the base color for the material.
  4. emissiveMap - Defines the emissive map. The emission color of a material doesn't affect other objects in the scene, just itself.
  5. specularMap - Defines the material's specular color by a texture map.
  6. shininessMap - Defines the material's shininess, also know as glossiness. To achieve more precision, the map should be in grey scale, where the full white represents the value of 1000 and full black represents the 0.
  7. bumpMap - Defines the material's bump effect. This map should be constructed as a normal map using the tangent space colors.
  8. reflectiveMap - Defines the reflection map. This map is the only one that doesn't use the UV coordinates (the mesh's texture coordinates). Instead, it will use a spherical enviroment.
NinevehGL offers many kind of textures maps.
NinevehGL can merge many shaders into a single one.


The NinevehGL is capable of parsing your custom shaders, analize them and merge them within the NinevehGL's shaders. You can write the shader in an external file, just as you are used to do using OpenGL programmable pipeline or even write the shaders source directly in your code.

If you have old shaders files you can test it with NinevehGL. You can write the entire shader program, managing even the vertex position in the vertex shader, but this is not useful. The NinevehGL comes to make the hard work for you, like taking care about the mesh's structure and matrices. So, often, when you want to customize the shaders, you will create just a custom fragment shader. With NinevehGL you don't need to set the pair of shaders, because the engine is already taking care of them for you.

The new thing is that you can use any of the NinevehGL previous processing, that means, the NinevehGL's shaders are processed before, so you can take advantage of any variable processed by NinevehGL. You have to take care to don't use or override any of the NinevehGL's variable.

Check the documentation for more informations about the NinevehGL's variables.


NinevehGL offers light and fog effects. To access both of them use the singleton instances of NGLLight and NGLFog, respectively.

The light is a subclass of NGLObject3D, so you can move and transform it as any other 3D object. The global light is an Omni Light (also known as Point Light) and in the current version can't be of another type.

The fog effect can gradually change the meshes' colors and make the meshes disapear in the horizon (camera clipping plane). The fog color can be set using the color property. By default, when you call the NGLFog singleton, it will assume the global color as its color.

NinevehGL offers many kind of textures maps.
NinevehGL can merge many shaders into a single one.


NinevehGL has methods to render to off-screen surfaces. You can render to an UIImage, to NGLTexture or to NSData. The NGLView is the responsible for the renders, so there are methods to draw to off-screen surfaces:

  1. - (UIImage *) drawToImage: Draws to an image the current render.
  2. - (NGLTexture *) drawToTexture: Draws to a texture the current render.
  3. - (NSData *) drawToData:(NGLImageFileType)type: Draws to a data with a specific image format (can be JPG or PNG).

Drawing to off-screen surfaces in NinevehGL doesn't produce any new render call, they just retrieve the last render image. So if you want to use one of those methods inside the render cycle, call them after the drawing commands.


NinevehGL is a 3D engine built right on top of OpenGL ES and it uses all the programmable pipeline power, making it easy for you to create great application with shaders.

Share on

Follow NinevehGL
Fastest way to contact us:

Copyright © 2011 db-in. All rights reserved.