Inherits from NGLObject3D : NSObject
Conforms to NGLCoreTimer
Declared in NGLMesh.h

Overview

The base class to every mesh in NinevehGL.

This is the mesh class. It’s your point of access and probably will be the class you will have more contact with. It can be called at every frame to produce object transformations. It holds the materials, shaders and surfaces instances to work with a specific mesh. It manages the parsing process and controls all the meshes of the view and application. In fact, this is the most important NinevehGL class to your work.

Delving technically inside its structure:

This is an abstract class, which means that alone it does nothing. Here is the basic structure to work with any OpenGL programmable pipeline. This class set some rules to work with programmable pipeline, it:

  • Always work with “array of structures” and “array of indices”;
  • Prepares the elements which will be dynamicaly set, like vertex position, vertex normal, vertex texture coordinate, vertex tangent and vertex bitangent.
  • Constructs the necessary matrices at the render time.
  • Updates the meshes when a global change happens in the OpenGL’s core.

Besides, this class extends the base NGLObject3D, so it’s the bridge to make any 3D transformations. Another important NGLMesh’s responsability is to store the materials, custom shaders and surfaces. These three APIs let you do almost anything to customize the shaders behaviors, using all the power of the OpenGL programmable pipeline.

NGLMesh offers a simple way to instruct the NinevehGL if this mesh could be rendered or not. With the visible property you can skip the entire rendering process to this mesh, even avoiding the vertex shader processing.

One of the most important NGLMesh’s features is that this class is the point of access to the NinevehGL’s Parse API. The Parse API can easily load and parse 3D files and all its related shader behaviors. All that you need to do is to export your 3D scene from a 3D software, place the file (or files) in your project and pass the file’s name/path to one of the NGLMesh’s constructor methods.

This actual Parse API is prepared to work with:

  • WaveFront Object Files (.obj);
  • COLLADA Object Files (.dae);
  • NinevehGL Binary Files (.ngl).

Any copy (simple copy or copyInstance) of NGLMesh will be made asynchronous (when using multithreading) and after the loading process finishes. So, you can make a copy of a NGLMesh even if it’s loading a 3D file. The structure will be copied into the new NGLMesh after the loading, respecting the copy type.

The loading process is one of the most expensive tasks in NinevehGL. If you are using NinevehGL with multithreading mode turned ON, the loading process task will use two distincts background threads:

  • A thread to load and parse the 3D file;
  • A thread to upload the parsed data to the OpenGL core (CoreMesh).

Working on file represents 80% of the loading process and the upload represents 20% of the entire process. So if you are monitoring the process, you will see that the mesh can’t be rendered until 80%. However, after the 80% the mesh can be rendered but it’s not completed yet.

If running on multithreading mode, NinevehGL can generate statuses callbacks for the process, in order to receive the messages a class must conforms to the NGLMeshDelegate protocol.

IMPORTANT: You should not change the multithreading mode while loading.

Tasks

  •   matrixMVP

    The final MODEL_VIEW_PROJECTION matrix.

    property
  •   matrixMInverse

    The final orthogonal MODEL_INVERSE matrix (doesn’t include the scale).

    property
  •   matrixMVInverse

    The final orthogonal MODEL_VIEW_INVERSE matrix (doesn’t include the scale).

    property
  •   delegate

    The delegate must conform to NGLMeshDelegate protocol. If there is a loading process in progress this call will do nothing.

    property
  •   parsing

    The parsing information. This property will return NULL if there is no parsing under processing at this time.

    property
  •   indicesCount

    The array of indices’s length.

    property
  •   structuresCount

    The array of structures’s length.

    property
  •   stride

    The array of structures’s stride in computer basic units (bits).

    property
  •   indices

    Pointer to the array of indices containing the instructions to work with OpenGL programmable pipeline.

    property
  •   structures

    Pointer to the array of structures containing all the information about this mesh' structure.

    property
  •   meshElements

    Pointer to the elements of this mesh.

    property
  •   material

    This property can be set to any NGLMaterial. This includes the basic material NGLMaterial and the multi/sub material NGLMaterialMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, the default clay material will be used in place.

    property
  •   shaders

    This property can be set to any NGLShaders. This include the basic shaders NGLShaders and the multi/sub shaders NGLShadersMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, no custom shaders will be used in place.

    property
  •   surface

    This property can be set to any NGLSurface. This include the basic surface NGLSurface and the multi/sub surface NGLSurfaceMulti.

    property
  •   visible

    Indicates whether this mesh will be visible or not to the render process. If this is set to NO, all the render steps will be skipped to this mesh.

    property
  •   fileNamed

    (Internal only) You should not call this one manually.

    property
  •   fileSettings

    (Internal only) You should not call this one manually.

    property
  • – initWithFile:settings:delegate:

    Initiates the mesh from any supported 3D files with some properties.

  • – loadFile:settings:type:

    Loads a new mesh based on a file type with properties.

  • – cancelLoading

    Stops the loading process. Cancelling the process is not immediately, it can take few more cycles to release all the allocated memory.

  • – compileCoreMesh

    Compiles the final mesh and constructs the OpenGL’s shaders. This method starts an asynchronous task and it may take a while to complete.

  • – drawMeshWithCamera:

    (Internal only) You should not set this property manually.

  • – setIndices:count:

    Sets the array of indices.

  • – setStructures:count:stride:

    Sets the array of structures.

  • + updateAllMeshes

    (Internal only) You should not call this one manually.

  • + emptyAllMeshes

    (Internal only) You should not call this one manually.

  • + allMeshes

    (Internal only) You should not call this one manually.

Properties

delegate

The delegate must conform to NGLMeshDelegate protocol. If there is a loading process in progress this call will do nothing.

@property (nonatomic, assign) id<> delegate

Discussion

The delegate must conform to NGLMeshDelegate protocol. If there is a loading process in progress this call will do nothing.

See Also

Declared In

NGLMesh.h

fileNamed

(Internal only) You should not call this one manually.

@property (nonatomic, copy) NSString *fileNamed

Discussion

(Internal only) You should not call this one manually.

Defines the internal file’s name or path. If there is a loading process in progress this call will do nothing.

Declared In

NGLMesh.h

fileSettings

(Internal only) You should not call this one manually.

@property (nonatomic, copy) NSDictionary *fileSettings

Discussion

(Internal only) You should not call this one manually.

Defines the internal file settings for the loading process. If there is a loading process in progress this call will do nothing.

Declared In

NGLMesh.h

indices

Pointer to the array of indices containing the instructions to work with OpenGL programmable pipeline.

@property (nonatomic, readonly) unsigned int *indices

Discussion

Pointer to the array of indices containing the instructions to work with OpenGL programmable pipeline.

Declared In

NGLMesh.h

indicesCount

The array of indices’s length.

@property (nonatomic, readonly) unsigned int indicesCount

Discussion

The array of indices’s length.

Declared In

NGLMesh.h

material

This property can be set to any NGLMaterial. This includes the basic material NGLMaterial and the multi/sub material NGLMaterialMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, the default clay material will be used in place.

@property (nonatomic, retain) id<> material

Discussion

This property can be set to any NGLMaterial. This includes the basic material NGLMaterial and the multi/sub material NGLMaterialMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, the default clay material will be used in place.

Besides, if no material was set (or set to nil) the default clay material will be used.

Declared In

NGLMesh.h

matrixMInverse

The final orthogonal MODEL_INVERSE matrix (doesn’t include the scale).

@property (nonatomic, readonly) NGLmat4 *matrixMInverse

Discussion

The final orthogonal MODEL_INVERSE matrix (doesn’t include the scale).

Declared In

NGLMesh.h

matrixMVInverse

The final orthogonal MODEL_VIEW_INVERSE matrix (doesn’t include the scale).

@property (nonatomic, readonly) NGLmat4 *matrixMVInverse

Discussion

The final orthogonal MODEL_VIEW_INVERSE matrix (doesn’t include the scale).

Declared In

NGLMesh.h

matrixMVP

The final MODEL_VIEW_PROJECTION matrix.

@property (nonatomic, readonly) NGLmat4 *matrixMVP

Discussion

The final MODEL_VIEW_PROJECTION matrix.

Declared In

NGLMesh.h

meshElements

Pointer to the elements of this mesh.

@property (nonatomic, readonly) NGLMeshElements *meshElements

Discussion

Pointer to the elements of this mesh.

See Also

Declared In

NGLMesh.h

parsing

The parsing information. This property will return NULL if there is no parsing under processing at this time.

@property (nonatomic, readonly) NGLParsing parsing

Discussion

The parsing information. This property will return NULL if there is no parsing under processing at this time.

Declared In

NGLMesh.h

shaders

This property can be set to any NGLShaders. This include the basic shaders NGLShaders and the multi/sub shaders NGLShadersMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, no custom shaders will be used in place.

@property (nonatomic, retain) id<> shaders

Discussion

This property can be set to any NGLShaders. This include the basic shaders NGLShaders and the multi/sub shaders NGLShadersMulti. To use Multi/Sub materials you should set at least one surface. Otherwise, no custom shaders will be used in place.

Besides, if no custom shaders was set (or set to nil) this mesh will work only with the NinevehGL Shaders.

Declared In

NGLMesh.h

stride

The array of structures’s stride in computer basic units (bits).

@property (nonatomic, readonly) unsigned int stride

Discussion

The array of structures’s stride in computer basic units (bits).

Declared In

NGLMesh.h

structures

Pointer to the array of structures containing all the information about this mesh' structure.

@property (nonatomic, readonly) float *structures

Discussion

Pointer to the array of structures containing all the information about this mesh' structure.

Declared In

NGLMesh.h

structuresCount

The array of structures’s length.

@property (nonatomic, readonly) unsigned int structuresCount

Discussion

The array of structures’s length.

Declared In

NGLMesh.h

surface

This property can be set to any NGLSurface. This include the basic surface NGLSurface and the multi/sub surface NGLSurfaceMulti.

@property (nonatomic, retain) id<> surface

Discussion

This property can be set to any NGLSurface. This include the basic surface NGLSurface and the multi/sub surface NGLSurfaceMulti.

Besides, if no surface was set (or set to nil) no surface information will be used in place.

Declared In

NGLMesh.h

visible

Indicates whether this mesh will be visible or not to the render process. If this is set to NO, all the render steps will be skipped to this mesh.

@property (nonatomic) BOOL visible

Discussion

Indicates whether this mesh will be visible or not to the render process. If this is set to NO, all the render steps will be skipped to this mesh.

The default value is YES.

Declared In

NGLMesh.h

Class Methods

allMeshes

(Internal only) You should not call this one manually.

+ (NSArray *)allMeshes

Return Value

A NSArray containing all the meshes.

Discussion

(Internal only) You should not call this one manually.

Gets all the meshes currently in the application’s memory.

Declared In

NGLMesh.h

emptyAllMeshes

(Internal only) You should not call this one manually.

+ (void)emptyAllMeshes

Discussion

(Internal only) You should not call this one manually.

This method affects all NGLMesh in the memory. It’ll clean up all core meshes.

Declared In

NGLMesh.h

updateAllMeshes

(Internal only) You should not call this one manually.

+ (void)updateAllMeshes

Discussion

(Internal only) You should not call this one manually.

This method affects all NGLMesh in the memory. It’ll update all core meshes.

Declared In

NGLMesh.h

Instance Methods

cancelLoading

Stops the loading process. Cancelling the process is not immediately, it can take few more cycles to release all the allocated memory.

- (void)cancelLoading

Discussion

Stops the loading process. Cancelling the process is not immediately, it can take few more cycles to release all the allocated memory.

If you are using NinevehGL with multithreading, remember that the load will retain this mesh to work on a background thread. So, if you want to release and dealloc this mesh before the load finish you should call this method.

Declared In

NGLMesh.h

compileCoreMesh

Compiles the final mesh and constructs the OpenGL’s shaders. This method starts an asynchronous task and it may take a while to complete.

- (void)compileCoreMesh

Discussion

Compiles the final mesh and constructs the OpenGL’s shaders. This method starts an asynchronous task and it may take a while to complete.

The mesh data (array of structure and array of indices) will be reloaded from the local binary cache. The loading will run as any other mesh loading: using two other threads (if the application is in multithreading mode).

This method should be called after a change in materials, shaders or surfaces. Calls to this method while a loding is happening will be ignored.

Declared In

NGLMesh.h

drawMeshWithCamera:

(Internal only) You should not set this property manually.

- (void)drawMeshWithCamera:(NGLCamera *)camera

Parameters

camera

The camera that is capturing this mesh.

Discussion

(Internal only) You should not set this property manually.

Starts the render process with a specific camera.

Declared In

NGLMesh.h

initWithFile:settings:delegate:

Initiates the mesh from any supported 3D files with some properties.

- (id)initWithFile:(NSString *)named settings:(NSDictionary *)dict delegate:(id<NGLMeshDelegate>)target

Parameters

named

In NinevehGL the “named” parameter is always related to the NinevehGL Path API, so you can inform the only the file’s name or full path. The full path is related to the file system. If only the file’s name is informed, NinevehGL will search for the file at the global path.

dict

A NSDictionary containing the keys and values to the preset.

target

The delegate target, it must conforms to NGLMeshDelegate protocol.

Return Value

A new initialized instance.

Discussion

Initiates the mesh from any supported 3D files with some properties.

This method automatically tries to recognize the 3D file based on its extension and choose the appropriated parsing process. The current version can work with: – WaveFront OBJ file (.obj); – COLLADA file (.dae); – NinevehGL Binary file (.ngl).

See Also

Declared In

NGLMesh.h

loadFile:settings:type:

Loads a new mesh based on a file type with properties.

- (void)loadFile:(NSString *)named settings:(NSDictionary *)dict type:(NGL3DFileType)type

Parameters

named

In NinevehGL the “named” parameter is always related to the NinevehGL Path API, so you can inform the only the file’s name or full path. The full path is related to the file system. If only the file’s name is informed, NinevehGL will search for the file at the global path.

dict

A NSDictionary containing the keys and values to the preset.

type

The file type. It can be any of the NGL3DFileType values.

Discussion

Loads a new mesh based on a file type with properties.

This method loads a new mesh with all properties and structures from a 3D file. Any older mesh’s information will be replaced by the new mesh. The file will be searched using the NinevehGL Path API.

If your application is running NinevehGL on multithreading mode, this method will ignore new calls while the last loading is happening.

Declared In

NGLMesh.h

setIndices:count:

Sets the array of indices.

- (void)setIndices:(unsigned int *)newIndices count:(unsigned int)newCount

Parameters

newIndices

Pointer to the array of indices. All the memory pointed by this parameter will be copied internally to avoid inconsistences and weak references.

newCount

The array of indice’s length. As the array of indices is a C array, you need to specify its length.

Discussion

Sets the array of indices.

Use this method to create the array of indices and set its length.

Declared In

NGLMesh.h

setStructures:count:stride:

Sets the array of structures.

- (void)setStructures:(float *)newStructures count:(unsigned int)newCount stride:(unsigned int)newStride

Parameters

newStructures

Pointer to the array of structures. All the memory pointed by this parameter will be copied internally to avoid inconsistences and weak references.

newCount

The array of structures’s length. As array of indices is a C array, you need to specify its length.

newStride

The array of structures’s stride. This stride must be in elements, not basic machine units.

Discussion

Sets the array of structures.

Use this method to create the array of structures, set its length and its stride.

Declared In

NGLMesh.h