Inherits from NSObject
Conforms to NGLCopying
Declared in NGLObject3D.h

Overview

The base class to every single 3D object in NinevehGL.

This is an abstract class, that means, by itself it does nothing. When it is extended by other classes, this becomes a powerfull part of 3D objects. NGLObject3D is responsible for controling, managing and setting the space coordinates for the 3D objects.

It’s important to remember some rules:

  • All the transformation properties are given with absolute values.
  • Translations can be made in world or local space;
  • Scales are always given in local space in which 1.0 means the original scale;
  • Rotations can be done in 3D world space or local space.

In the NinevehGL’s Render Chain, this is the second class to use cached matrix. Cached matrix is a very powerfull optimization concept of NinevehGL. It means that a matrix will be constructed by parts, so the unchaged parts will be cached and this will reduce the redundant calculations.

There are three important concepts about 3D rotations:

  • Absolute VS Relative (Mode);
  • World VS Local (Space);
  • Rotation Order (Order).

Absolute VS Relative (Mode) 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, with no rotation.

On the other hand, the Relative rotations are always in relation to the object’s current state. So a Relative rotation of 45.0 in Y axis can produce infinities results depending on the object state. The “object state” is said from the result of all its previous transformations until here.

World VS Local (Space) World rotation, also known as Global rotation, it’s said from that 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 cameras), for example. It’s like the rotations are always happening in relation to the origin of the world.

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.

Rotation Order (Order) There are 6 Rotation Orders. These orders represent how the consecutive rotations will happen during an animation. To an Absolute or Relative increment and to a World or Local reference, 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.

We could be inclined to believe that XYZ was the default behavior, but instead the default behavior and most used order is XZY. However the Rotation Order exists to help each object to achieve their objectives. For example, to a camera object the best choice could be YXZ.

All those three concepts work together inside NinevehGL. The Rotation Order is rarely used, exist only in few situations where you need to change it to achieve the desired result, you can set it using a NGLObject3D’s property. The World VS Local are used a little bit more frequently, it’s very useful to define an object behavior, objects which always made Local rotation and objects which always made World rotations. To set the rotation mode you use another NGLObject3D’s property. Now, the Absolute VS Relative is used too often, because it’s normally an object made consecutives Relative rotations and then make a new Absolute rotation. For this reason, there are no properties to change every time you need to use one of them, instead NGLObject3D offers different methods to work with Absolute and Relative rotations.

Another important NGLObject3D’s responsibility is to deal with the Pivot concept. Every 3D object is rotated around its own center, but sometimes it could be important to make the rotations around another point that isn’t its own center, like rotating a “sling” object, for example. This is what the Pivot concept is for. When you set a new pivot, all the rotations will be made around that new center. By default, every has its pivot set to its own center (0.0, 0.0, 0.0).

Every 3D object could be inscribed into a box. This feature is called bounding box. NGLObject3D gives a method to set the pivot related to the bounding box. By this way you can easily construct complex structures, like bones.

Besides, NGLObject3D implements the LookAt concept. It'is a very important behavior in 3D world. It gives you a simple way to rotate the X and Y axis of an object to face a specific location in the 3D world, like face front to other object or face to a point. This behavior is specially useful for 3D cameras. With LookAt the cameras can easily follow a target wherever it goes.

Tasks

  •   tag

    This is a free property, can act as an identifier to this object.

    property
  •   name

    This is a free property, can act as an identifier to this object.

    property
  •   pivot

    The pivot vector to this object.

    property
  •   rotationSpace

    This property defines the rotations’s mode, which can be World or Local.

    property
  •   rotationOrder

    This property defines the rotations’s order. This can be one of the 6 different NGLRotationOrder’s possibilities.

    property
  •   x

    Defines the object’s position along the axis X. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

    property
  •   y

    Defines the object’s position along the axis Y. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

    property
  •   z

    Defines the object’s position along the axis Z. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

    property
  •   scaleX

    Defines the object’s scale on the axis X. This scales always happens in the object’s local space.

    property
  •   scaleY

    Defines the object’s scale on the axis Y. This scales always happens in the object’s local space.

    property
  •   scaleZ

    Defines the object’s scale on the axis Z. This scales always happens in the object’s local space.

    property
  •   rotateX

    Defines the object’s rotation in Absolute mode along the axis X. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

    property
  •   rotateY

    Defines the object’s rotation in Absolute mode along the axis Y. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

    property
  •   rotateZ

    Defines the object’s rotation in Absolute mode along the axis Z. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

    property
  •   position

    A pointer to the position vector.

    property
  •   scale

    A pointer to the scale vector.

    property
  •   rotation

    A pointer to the rotation vector (euler rotation) in degrees.

    property
  •   matrix

    This is the final matrix containing translations, scales and rotations of this 3D object. Also known as MODEL MATRIX.

    property
  •   matrixOrtho

    This is the orthogonal part of the final matrix. It contains information about the object’s rotation and translation, but not the scale. This is the orthogonal portion of the MODEL MATRIX.

    property
  •   target

    Defines a target to look at. At every render cycle, this object will perform a lookAt routine with the specified target. The lookAt affects rotations in X and Y axis. Any other rotation commands will be ignored to the final result. The lookAt routine doesn’t affect the absolute rotation values.

    property
  •   group

    Identifies the group in wich this object is attached to.

    property
  • – moveRelativeTo:distance:

    Translates this 3D object using the Relative mode.

  • – translateRelativeToX:toY:toZ:

    Translates this 3D object using the Relative mode.

  • – rotateRelativeToX:toY:toZ:

    Rotates this 3D object using the Relative mode.

  • – rotateRelativeWithMatrix:

    Rotates this 3D object with a rotation matrix using the Relative mode.

  • – rotateRelativeWithQuaternion:

    Rotates this 3D object with a quaternion using the Relative mode.

  • – scaleRelativeToX:toY:toZ:

    Scales this 3D object using the Relative mode.

  • – translateToX:toY:toZ:

    Translates this 3D object to a specific point using Absolute mode.

  • – scaleToX:toY:toZ:

    Scales this 3D object to a specific scale using Absolute mode.

  • – rotateToX:toY:toZ:

    Rotates this 3D object to a specific rotation using Absolute mode.

  • – rotateWithMatrix:

    Rotates this 3D object with a rotation matrix.

  • – rotateWithQuaternion:

    Rotates this 3D object with a quaternion.

  • – lookAtTarget:

    Makes this 3D object face front to other 3D object.

  • – lookAtPointX:toY:toZ:

    Makes this 3D object turn its face to a 3D point.

  • – lookAtVector:

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

  • – rebaseWithMatrix:scale:compatibility:

    Rebases this object based on another matrix. This process remains the transformation properties unchaged (x, y, z, rotateX, rotateY, rotateZ, scaleX, scaleY, scaleZ).

  • – rebaseReset

    Deactivates/Resets the rebase feature. Call this method when you no longer need rebase this object.

Properties

group

Identifies the group in wich this object is attached to.

@property (nonatomic, assign) NGLObject3D *group

Discussion

Identifies the group in wich this object is attached to.

Each 3D object can have only one group at a time. If you try to attach an object to a group and that object is already attached to another group, it will be automatically detached from the old one and will be attached to the new group.

To attach or detach objects from groups use the NGLGroup3D class.

See Also

Declared In

NGLObject3D.h

matrix

This is the final matrix containing translations, scales and rotations of this 3D object. Also known as MODEL MATRIX.

@property (nonatomic, readonly) NGLmat4 *matrix

Discussion

This is the final matrix containing translations, scales and rotations of this 3D object. Also known as MODEL MATRIX.

The transformations happen in the order: scales –> rotations –> translations. This matrix is of order 4 (4 lines x 4 columns) and is used by OpenGL’s core.

Declared In

NGLObject3D.h

matrixOrtho

This is the orthogonal part of the final matrix. It contains information about the object’s rotation and translation, but not the scale. This is the orthogonal portion of the MODEL MATRIX.

@property (nonatomic, readonly) NGLmat4 *matrixOrtho

Discussion

This is the orthogonal part of the final matrix. It contains information about the object’s rotation and translation, but not the scale. This is the orthogonal portion of the MODEL MATRIX.

Declared In

NGLObject3D.h

name

This is a free property, can act as an identifier to this object.

@property (nonatomic, copy) NSString *name

Discussion

This is a free property, can act as an identifier to this object.

This property has no specific behavior, it’s an identifier to help you to manage your 3D resources in NinevehGL.

Declared In

NGLObject3D.h

pivot

The pivot vector to this object.

@property (nonatomic) NGLvec3 pivot

Discussion

The pivot vector to this object.

Declared In

NGLObject3D.h

position

A pointer to the position vector.

@property (nonatomic, readonly) NGLvec3 *position

Discussion

A pointer to the position vector.

Declared In

NGLObject3D.h

rotateX

Defines the object’s rotation in Absolute mode along the axis X. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

@property (nonatomic) float rotateX

Discussion

Defines the object’s rotation in Absolute mode along the axis X. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

Declared In

NGLObject3D.h

rotateY

Defines the object’s rotation in Absolute mode along the axis Y. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

@property (nonatomic) float rotateY

Discussion

Defines the object’s rotation in Absolute mode along the axis Y. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

Declared In

NGLObject3D.h

rotateZ

Defines the object’s rotation in Absolute mode along the axis Z. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

@property (nonatomic) float rotateZ

Discussion

Defines the object’s rotation in Absolute mode along the axis Z. To perform Relative rotations use the method rotateRelativeToX:toY:toZ:.

Declared In

NGLObject3D.h

rotation

A pointer to the rotation vector (euler rotation) in degrees.

@property (nonatomic, readonly) NGLvec3 *rotation

Discussion

A pointer to the rotation vector (euler rotation) in degrees.

Declared In

NGLObject3D.h

rotationOrder

This property defines the rotations’s order. This can be one of the 6 different NGLRotationOrder’s possibilities.

@property (nonatomic) NGLRotationOrder rotationOrder

Discussion

This property defines the rotations’s order. This can be one of the 6 different NGLRotationOrder’s possibilities.

This property has a correlated global property. As any other NinevehGL Global Property, the final value will be taken from here only if the global property is NGL_NULL, otherwise the global value will be used.

Declared In

NGLObject3D.h

rotationSpace

This property defines the rotations’s mode, which can be World or Local.

@property (nonatomic) NGLRotationSpace rotationSpace

Discussion

This property defines the rotations’s mode, which can be World or Local.

This property has a correlated global property. As any other NinevehGL Global Property, the final value will be taken from here only if the global property is NGL_NULL, otherwise the global value will be used.

Declared In

NGLObject3D.h

scale

A pointer to the scale vector.

@property (nonatomic, readonly) NGLvec3 *scale

Discussion

A pointer to the scale vector.

Declared In

NGLObject3D.h

scaleX

Defines the object’s scale on the axis X. This scales always happens in the object’s local space.

@property (nonatomic) float scaleX

Discussion

Defines the object’s scale on the axis X. This scales always happens in the object’s local space.

Declared In

NGLObject3D.h

scaleY

Defines the object’s scale on the axis Y. This scales always happens in the object’s local space.

@property (nonatomic) float scaleY

Discussion

Defines the object’s scale on the axis Y. This scales always happens in the object’s local space.

Declared In

NGLObject3D.h

scaleZ

Defines the object’s scale on the axis Z. This scales always happens in the object’s local space.

@property (nonatomic) float scaleZ

Discussion

Defines the object’s scale on the axis Z. This scales always happens in the object’s local space.

Declared In

NGLObject3D.h

tag

This is a free property, can act as an identifier to this object.

@property (nonatomic) int tag

Discussion

This is a free property, can act as an identifier to this object.

This property has no specific behavior, it’s an identifier to help you to manage your 3D resources in NinevehGL.

Declared In

NGLObject3D.h

target

Defines a target to look at. At every render cycle, this object will perform a lookAt routine with the specified target. The lookAt affects rotations in X and Y axis. Any other rotation commands will be ignored to the final result. The lookAt routine doesn’t affect the absolute rotation values.

@property (nonatomic, assign) NGLObject3D *target

Discussion

Defines a target to look at. At every render cycle, this object will perform a lookAt routine with the specified target. The lookAt affects rotations in X and Y axis. Any other rotation commands will be ignored to the final result. The lookAt routine doesn’t affect the absolute rotation values.

Declared In

NGLObject3D.h

x

Defines the object’s position along the axis X. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

@property (nonatomic) float x

Discussion

Defines the object’s position along the axis X. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

Declared In

NGLObject3D.h

y

Defines the object’s position along the axis Y. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

@property (nonatomic) float y

Discussion

Defines the object’s position along the axis Y. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

Declared In

NGLObject3D.h

z

Defines the object’s position along the axis Z. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

@property (nonatomic) float z

Discussion

Defines the object’s position along the axis Z. This property always represents the Absolute position mode. To translate the object using the relative mode, use moveRelativeTo:distance: or translateRelativeToX:toY:toZ: methods.

Declared In

NGLObject3D.h

Instance Methods

lookAtPointX:toY:toZ:

Makes this 3D object turn its face to a 3D point.

- (void)lookAtPointX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The point’s X coordinate.

yNum

The point’s Y coordinate.

zNum

The point’s Z coordinate.

Discussion

Makes this 3D object turn its face to a 3D point.

This method has the same bahavior as lookAtTarget: method, but instead a NGLObject3D will be a 3D point in world space.

Declared In

NGLObject3D.h

lookAtTarget:

Makes this 3D object face front to other 3D object.

- (void)lookAtTarget:(NGLObject3D *)target

Parameters

target

The other NGLObject3D which this 3D object will look at.

Discussion

Makes this 3D object face front to other 3D object.

The 3D object “face” is given by it’s Z line positive value. This means that the cube’s “face”, for example, will be the face which is facing to the Z positive line. Or in other words, the cube’s “face” will be the plane (or point) which has a positive value to the Z normal.

     _____________
    /            /|
   /            / |               +y
  /            /  |               |  -z
 /            /   |               |  /
/____________/    |               | /
|            |    |        -x ____|/_____ +x
|            |    /               |
|   FRONT    |   /               /|
|    FACE    |  /               / |
|            | /               /  |
|____________|/               +z  -y

This method changes the X and Y rotations values, it doesn’t change position, scale or Z rotation.

Declared In

NGLObject3D.h

lookAtVector:

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

- (void)lookAtVector:(NGLvec3)vector

Parameters

vector

The vector that represents the distances between this 3D object and the target of LookAt routine.

Discussion

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

You never call this method directly! Just custom LookAt routines could call this method directly to process the triangle equations.

This method is responsible for LookAt routine. First, it finds the distance between this NGLObject3D and the target 3D point. With these distances it’s possible to trace imaginary triangles between these two 3D points (this NGLObject3D pivot and the target point).

                 |\
                 |∂\ --- ∂ angle to find
                 |  \
    Adjacent --- |   \
        Side     |    \ --- Hypotenuse
                 |_    \
                 |_|____\
                     |
                     |___ Opposite
                          Side

It’s simple to deal with it using SOH-CAH-TOA (formulas based on Pythagoras Theorem to find the angles of the triangle using two sides):

  • Sin(∂) = Opposite / Hypotenuse;
  • Cos(∂) = Adjacent / Hypotenuse;
  • Tan(∂) = Opposite / Adjacent.

Declared In

NGLObject3D.h

moveRelativeTo:distance:

Translates this 3D object using the Relative mode.

- (void)moveRelativeTo:(NGLMove)axis distance:(float)distance

Parameters

axis

The #NGLMove# parameter.

distance

A float data type representing the distance which the object will be moved.

Discussion

Translates this 3D object using the Relative mode.

This method produces local translation, that means, the object will be moved along its own axis. So the final result depends on the object current state.

This method makes use of the NGLMove directions. Those directions points at one of the six object’s side.

Declared In

NGLObject3D.h

rebaseReset

Deactivates/Resets the rebase feature. Call this method when you no longer need rebase this object.

- (void)rebaseReset

Discussion

Deactivates/Resets the rebase feature. Call this method when you no longer need rebase this object.

Declared In

NGLObject3D.h

rebaseWithMatrix:scale:compatibility:

Rebases this object based on another matrix. This process remains the transformation properties unchaged (x, y, z, rotateX, rotateY, rotateZ, scaleX, scaleY, scaleZ).

- (void)rebaseWithMatrix:(NGLmat4)matrix scale:(float)scale compatibility:(NGLRebase)rebase

Parameters

matrix

A matrix to act as rebase.

scale

The scale of the matrix metric system. The NinevehGL/OpenGL uses 1.0.

rebase

The rebase compatibility preset.

Discussion

Rebases this object based on another matrix. This process remains the transformation properties unchaged (x, y, z, rotateX, rotateY, rotateZ, scaleX, scaleY, scaleZ).

This is a convient method that helps you to change the base plane of your mesh and still making simple changes on it. Often this method is used with AR engines. The AR engines are used to output a matrix, but each engine has its own matrix system, orientation (Right or Left Hand) and work with different scales. So, this method can deal with all those differences between the engines and translate their matrices to NinevehGL/OpenGL matrix.

The rebase is a feature that when activated it will remains active until you explicit deactivate it (or reset). To do that, make a call to rebaseReset.

See Also

Declared In

NGLObject3D.h

rotateRelativeToX:toY:toZ:

Rotates this 3D object using the Relative mode.

- (void)rotateRelativeToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The rotation increment along the axis X.

yNum

The rotation increment along the axis Y.

zNum

The rotation increment along the axis Z.

Discussion

Rotates this 3D object using the Relative mode.

This method will make an increment in the object actual state. The rotations will follow the previously defined Space and Order.

It’s important to note that the Relative mode only produces increments. That means a value of 3.0 will produces a result of: <current value> + 3.0.

Declared In

NGLObject3D.h

rotateRelativeWithMatrix:

Rotates this 3D object with a rotation matrix using the Relative mode.

- (void)rotateRelativeWithMatrix:(NGLmat4)matrix

Parameters

matrix

The matrix in column-major format.

Discussion

Rotates this 3D object with a rotation matrix using the Relative mode.

The matrix must be in column-major format, that means:


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

Actually, doesn’t matter if the matrix has other transformations, like scale or translate, only the rotation information will be used.

Declared In

NGLObject3D.h

rotateRelativeWithQuaternion:

Rotates this 3D object with a quaternion using the Relative mode.

- (void)rotateRelativeWithQuaternion:(NGLQuaternion *)quaternion

Parameters

quaternion

A NGLQuaternion containing the rotation.

Discussion

Rotates this 3D object with a quaternion using the Relative mode.

The quaternion must be an instance of NGLQuaternion class.

Declared In

NGLObject3D.h

rotateToX:toY:toZ:

Rotates this 3D object to a specific rotation using Absolute mode.

- (void)rotateToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The X rotation to set.

yNum

The Y rotation to set.

zNum

The Z rotation to set.

Discussion

Rotates this 3D object to a specific rotation using Absolute mode.

This method will directly set the rotation values based on the values passed through parameters.

Declared In

NGLObject3D.h

rotateWithMatrix:

Rotates this 3D object with a rotation matrix.

- (void)rotateWithMatrix:(NGLmat4)matrix

Parameters

matrix

The matrix in column-major format.

Discussion

Rotates this 3D object with a rotation matrix.

The matrix must be in column-major format, that means:


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

Actually, doesn’t matter if the matrix has other transformations, like scale or translate, only the rotation information will be used.

Declared In

NGLObject3D.h

rotateWithQuaternion:

Rotates this 3D object with a quaternion.

- (void)rotateWithQuaternion:(NGLQuaternion *)quaternion

Parameters

quaternion

A NGLQuaternion containing the rotation.

Discussion

Rotates this 3D object with a quaternion.

The quaternion must be an instance of NGLQuaternion class.

Declared In

NGLObject3D.h

scaleRelativeToX:toY:toZ:

Scales this 3D object using the Relative mode.

- (void)scaleRelativeToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The scale increment along the axis X.

yNum

The scale increment along the axis Y.

zNum

The scale increment along the axis Z.

Discussion

Scales this 3D object using the Relative mode.

This method will make an increment in the object actual state.

It’s important to note that the Relative mode only produces increments. That means a value of 3.0 will produces a result of: <current value> + 3.0.

Declared In

NGLObject3D.h

scaleToX:toY:toZ:

Scales this 3D object to a specific scale using Absolute mode.

- (void)scaleToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The new X scale value to set.

yNum

The new Y scale value to set.

zNum

The new Z scale value to set.

Discussion

Scales this 3D object to a specific scale using Absolute mode.

This method will directly set the scale based on the values passed through parameters.

Declared In

NGLObject3D.h

translateRelativeToX:toY:toZ:

Translates this 3D object using the Relative mode.

- (void)translateRelativeToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The distance along the axis X.

yNum

The distance along the axis Y.

zNum

The distance along the axis Z.

Discussion

Translates this 3D object using the Relative mode.

This method produces local translation, that means, the object will be moved along its own axis. So the final result depends on the object current state.

It’s important to note that the Relative mode only produces increments. That means a value of 3.0 will produces a result of: <current value> + 3.0.

Declared In

NGLObject3D.h

translateToX:toY:toZ:

Translates this 3D object to a specific point using Absolute mode.

- (void)translateToX:(float)xNum toY:(float)yNum toZ:(float)zNum

Parameters

xNum

The X coordinate to set.

yNum

The Y coordinate to set.

zNum

The Z coordinate to set.

Discussion

Translates this 3D object to a specific point using Absolute mode.

This method will directly set the position based on the values passed through parameters.

Declared In

NGLObject3D.h