NGLObject3D Class Reference
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
propertymoveRelativeTo:distance:
ortranslateRelativeToX:toY:toZ:
methods. 
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
propertymoveRelativeTo:distance:
ortranslateRelativeToX:toY:toZ:
methods. 
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
propertymoveRelativeTo:distance:
ortranslateRelativeToX:toY:toZ:
methods. 
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
propertyrotateRelativeToX:toY:toZ:
. 
rotateY
Defines the object’s rotation in Absolute mode along the axis Y. To perform Relative rotations use the method
propertyrotateRelativeToX:toY:toZ:
. 
rotateZ
Defines the object’s rotation in Absolute mode along the axis Z. To perform Relative rotations use the method
propertyrotateRelativeToX:toY:toZ:
. 
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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.
See Also
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 SOHCAHTOA (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.
See Also
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 columnmajor format.
Discussion
Rotates this 3D object with a rotation matrix using the Relative mode.
The matrix must be in columnmajor 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 columnmajor format.
Discussion
Rotates this 3D object with a rotation matrix.
The matrix must be in columnmajor 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
.
See Also
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