Inherits from NGLObject3D : NSObject
Declared in NGLCamera.h

Overview

The NinevehGL camera class.

The NGLCamera works exactly like a camera in professional 3D softwares like Maya, 3DS Max, LightWave, Cinema4D, Modo and others. NGLCamera is one of the most important pieces in NinevehGL’s render process.

OpenGL’s shaders works greatly with a type of matrix called ModelViewProjection Matrix. The NGLCamera is responsible for generating the ViewProjection part of that matrix.

Using an user friendly approach, NGLCamera can easily move the camera in the 3D world, rotate it, get focus and follow a target. All that using just few simple methods.

Another important NGLCamera responsability is to deal with the lens. As you know, cameras in the real world have a lot of lenses type to capture different kind of images. The NGLCamera works similarly, producing different kind of images based on lens. You can easily adjust the lens using two methods. By default, every NGLCamera instance is initialized with a Perspective Projection based on the device’s screen.

To make all those things, NGLCamera needs to know what object its lens will see. In NinevehGL all 3D objects, the visible ones, need to be rendered from a camera. Objects outside a camera scope will be ignored in NinevehGL’s render process.

About the camera behavior, the important thing to remember is that OpenGL by default uses the right handed orientation. That means, the axis orientation will be, looking from the front perspective of the device:

  • Axis X positive to the right and negative to the left of the device.
  • Axis Y positive upward and negative to downard of the device.
  • Axis Z axis positive coming toward the screen, in direction to the user and negative outgoing toward the screen, in direction to device’s back.

     ____________________________
    /___________________________/|
   ||___________________________||
   ||                           ||
   ||                           ||
   ||                           ||
   ||                           ||
   ||                           ||
   ||                           ||
   ||            +y   -z        ||
   ||            |   /          ||
   ||            |  /           ||
   ||            | /            ||
   ||  -x _______|/________ +x  ||
   ||            /              ||
   ||           /|              ||
   ||          / |              ||
   ||         /  |              ||
   ||        /   |              ||
   ||       +z   -y             ||
   ||                           ||
   ||                           ||
   ||                           ||
   ||                           ||
   ||           Right Hand Rule ||
   ||___________________________||
   |             ___             |
   |            |   |            |
   |            |___|            |
   |_____________________________|

So when you increase the Z position of a 3D object, it will come near to the screen and when you decrease the Z, the 3D object goes away from the screen. The important thing about the camera is when you decrease Z, it will go away from the screen too, but this will produce the effect of the objects coming toward the screen, because the render always will produce the image by the camera lens point of view.

If you have two or more cameras and render it at the same time, the final image will be composed by the superimposition of the images captured by all cameras. This image composition will happen in the same order as the cameras was rendered.

One camera can hold many meshes, but each mesh can be rendered by only one camera at time. If a mesh was attached to more than one camera, just the last attachment will be valid to the render process and the mesh will be automatically removed from the previously attached duplication.

From a NGLCamera you can get the VIEW MATRIX, PROJECTION MATRIX and the VIEW PROJECTION MATRIX. Also, you can get the normal MODEL MATRIX as the NGLCamera is a subclass of the NGLObject3D.

A category deals with iOS interactions.

This category implements methods to deal with any kind of interaction between NinevehGL structure and Cocoa Touch Framework. It includes things like: device’s orientation, touches, accelerometer and any kind of input specific to iOS devices.

Tasks

Other Methods

  •   angleView

    Defines angle of view to the camera lens.

    property
  •   nearPlane

    Defines near plane for the camera lens. Nearest objects will be clipped.

    property
  •   farPlane

    Defines far plane for the camera lens. Farthest objects will be clipped.

    property
  •   aspectRatio

    Defines size for the camera’s field of view (FOV). This property is valid for both projections: Perspective and Orthographic.

    property
  •   projection

    Defines lens type, also known as camera projection. It can be:

    property
  •   matrixView

    Returns the current VIEW MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

    property
  •   matrixProjection

    Returns the current PROJECTION MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

    property
  •   matrixViewProjection

    Represents the Camera Matrix, also known as VIEW PROJECTION MATRIX.

    property
  • – initWithMeshes:

    Initializes a camera instance with some meshes attached to it. The camera will retain the meshes internally.

  • – lensPerspective:near:far:angle:

    Places new lens on camera.

  • – lensOrthographic:near:far:

    Places new lens on camera.

  • – addMesh:

    Adds a new mesh to this camera. The camera will retain the meshes internally.

  • – addMeshesFromArray:

    Adds a set of new meshes to this camera. The camera will retain the meshes internally.

  • – addMeshesFromGroup3D:

    Adds a set of new meshes to this camera. The camera will retain the meshes internally.

  • – hasMesh:

    Checks if a specific mesh is already attached to this camera.

  • – removeMesh:

    Removes a specific mesh attached to this camera. The meshes are released when removed from camera.

  • – removeAllMeshes

    Removes all meshes attached to this camera. All the meshes will receive a release message.

  • – drawCamera

    Draws the image capture by this camera’s lens.

  • – allMeshes

    (Internal only) You should never use this directly.

NGLCameraInteractive Methods

Properties

angleView

Defines angle of view to the camera lens.

@property (nonatomic) float angleView

Discussion

Defines angle of view to the camera lens.

This property doesn’t affect the Orthographic projection, just the Perspective. Angle of View is the aperture angle that defines the Field of View (FOV) in Perspective projection type.

The default value is 45.0.

Declared In

NGLCamera.h

aspectRatio

Defines size for the camera’s field of view (FOV). This property is valid for both projections: Perspective and Orthographic.

@property (nonatomic) float aspectRatio

Discussion

Defines size for the camera’s field of view (FOV). This property is valid for both projections: Perspective and Orthographic.

This property represents the same object in both projections: the final visible frame. With the Perspective projection, this is what it represents:

           Width
        ___________
       |           |  Aspect Ratio (Width / Height)
       ____________  __
      |           /|   |
     ||          / |   |
     ||         /  |   |
     ||        /   |   |  Height
     ||       /    |   |
    | |      /     |   |
    | |_____/______| __|
    | /    /       /
    |/____/      /
    |     |    /  ----> Field of View (FOV)
    |     |  /
    |_____|/

With the Orthographic projection, this is what it represents:

          Width
        _________
       |         |  Aspect Ratio (Width / Height) - Perspective Porjection only
       __________  __
      /         /|   |
     /|        / |   |
    / |       /  |   |  Height
   /  |      /   |   |
  /   |_____/____| __|
 /    /    /     /
/____/____/     /
|   /     |    /  ----> Field of View (FOV)
|  /      |   /
| /       |  /
|/        | /
|_________|/

The default value is based on device’s screen frame (width / height).

Declared In

NGLCamera.h

farPlane

Defines far plane for the camera lens. Farthest objects will be clipped.

@property (nonatomic) float farPlane

Discussion

Defines far plane for the camera lens. Farthest objects will be clipped.

The default value is 100.0.

Declared In

NGLCamera.h

matrixProjection

Returns the current PROJECTION MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

@property (nonatomic, readonly) NGLmat4 *matrixProjection

Discussion

Returns the current PROJECTION MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

Declared In

NGLCamera.h

matrixView

Returns the current VIEW MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

@property (nonatomic, readonly) NGLmat4 *matrixView

Discussion

Returns the current VIEW MATRIX. NinevehGL doesn’t use this property, it’s just a reference in case you need to get it.

Declared In

NGLCamera.h

matrixViewProjection

Represents the Camera Matrix, also known as VIEW PROJECTION MATRIX.

@property (nonatomic, readonly) NGLmat4 *matrixViewProjection

Discussion

Represents the Camera Matrix, also known as VIEW PROJECTION MATRIX.

Declared In

NGLCamera.h

nearPlane

Defines near plane for the camera lens. Nearest objects will be clipped.

@property (nonatomic) float nearPlane

Discussion

Defines near plane for the camera lens. Nearest objects will be clipped.

The default value is 0.001.

Declared In

NGLCamera.h

projection

Defines lens type, also known as camera projection. It can be:

@property (nonatomic) NGLProjection projection

Discussion

Defines lens type, also known as camera projection. It can be:

  • Perspective;
  • Orthographic.

The default value is NGLProjectionPerspective.

Declared In

NGLCamera.h

Instance Methods

addMesh:

Adds a new mesh to this camera. The camera will retain the meshes internally.

- (void)addMesh:(NGLMesh *)mesh

Parameters

mesh

A NGLMesh to be attached to this camera.

Discussion

Adds a new mesh to this camera. The camera will retain the meshes internally.

If a mesh is already attached to this camera, new attempts to put it in the same camera will be ignored. One single mesh can be attached to multiple cameras.

Declared In

NGLCamera.h

addMeshesFromArray:

Adds a set of new meshes to this camera. The camera will retain the meshes internally.

- (void)addMeshesFromArray:(NSArray *)array

Parameters

array

A NSArray containing the meshes to be attached to this camera.

Discussion

Adds a set of new meshes to this camera. The camera will retain the meshes internally.

This method is similar to addMesh: method, but this one takes meshes from an array.

Declared In

NGLCamera.h

addMeshesFromGroup3D:

Adds a set of new meshes to this camera. The camera will retain the meshes internally.

- (void)addMeshesFromGroup3D:(NGLGroup3D *)group

Parameters

group

A NGLGroup3D containing the meshes to be attached to this camera.

Discussion

Adds a set of new meshes to this camera. The camera will retain the meshes internally.

This method is similar to addMesh: method, but this one takes meshes from a group. Only instances of NGLMesh will be taken from the group, any other object inside the group will be ignored by this method.

See Also

Declared In

NGLCamera.h

adjustToScreenAnimated:

Adjusts the current camera’s settings to fir the current device’s screen.

- (void)adjustToScreenAnimated:(BOOL)value

Parameters

value

A Boolean value indicating if the adjust will be animated or not.

Discussion

Adjusts the current camera’s settings to fir the current device’s screen.

This method will be performed automatically if the auto-adjust is set to YES. The adjust will be performed with or without animation. The animation occurs in the iOS rotation times. This time can vary depending on the device and iOS version.

Declared In

NGLCamera.h

allMeshes

(Internal only) You should never use this directly.

- (NSArray *)allMeshes

Return Value

A NSArray containing all the meshes.

Discussion

(Internal only) You should never use this directly.

Gets all the meshes currently in this camera.

Declared In

NGLCamera.h

autoAdjustToScreen:animated:

Sets the camera auto-adjust.

- (void)autoAdjustToScreen:(BOOL)value animated:(BOOL)animating

Parameters

value

A Boolean value indicating if the camera will start to auto-adjust or not.

animating

A Boolean value indicating if the auto adjust will be animated or not. This parameter has no effect if the first parameter is NO.

Discussion

Sets the camera auto-adjust.

The auto-adjust will fit the camera FOV to the current device’s screen, trying to identify its orientation and adjusting the current camera’s settings. This adjust will change the FOV for every device’s orientation change. If you’re not planning to rotate for every orientation, then make your own implementation using the adjustToScreenAnimated: method when there is a change in orientation.

Declared In

NGLCamera.h

drawCamera

Draws the image capture by this camera’s lens.

- (void)drawCamera

Discussion

Draws the image capture by this camera’s lens.

Call this method at every render cycle or every time you want to draw the image produced by this camera. A single call to this method will make all the meshes attached to this camera be drawn.

This method should be called inside a drawView method from a NGLView or equivalent delegation. The produced image will be attached to the NGLView from where this method was called.

Declared In

NGLCamera.h

hasMesh:

Checks if a specific mesh is already attached to this camera.

- (BOOL)hasMesh:(NGLMesh *)mesh

Parameters

mesh

A NGLMesh to search for.

Return Value

A BOOL data type indicating if the mesh is attached to this camera.

Discussion

Checks if a specific mesh is already attached to this camera.

Return a BOOL indicating if the mesh is or not attached to this camera.

Declared In

NGLCamera.h

initWithMeshes:

Initializes a camera instance with some meshes attached to it. The camera will retain the meshes internally.

- (id)initWithMeshes:(NGLMesh *)firstMesh, ...

Parameters

firstMesh

The first mesh (NGLMesh) to be added, followed by a comma.

...

A list of meshes, all followed by commas. This method requires a nil termination.

Return Value

A new initialized instance.

Discussion

Initializes a camera instance with some meshes attached to it. The camera will retain the meshes internally.

This method requires nil termination.

Declared In

NGLCamera.h

lensOrthographic:near:far:

Places new lens on camera.

- (void)lensOrthographic:(float)aspect near:(float)near far:(float)far

Parameters

aspect

This parameter represents the aspect ratio relative to the device’s screen. OpenGL produces squared image and if the device’s screen is not squared the final image will be stretched to fit into the device’s screen. With this parameter that problem can be avoided. What you need to do is inform the screen’s aspect ratio (or the desired part of screen). To calculate it, just divide the final width by the final height (width / height).

near

Indicates the minimum distance for the camera to capture an objects. This value is associated with a generic unit, the same used in the 3D space. A good value to it could be 0.01, by this way only the objects very close to the camera will be clipped.

far

Indicates the maximum range for the camera capture an objects. This value is associated with a generic unit, the same used in the 3D space. A good value to it could be 100.0, by this way only the objects very far to the camera will be clipped.

Discussion

Places new lens on camera.

This lens has an orthographic projection.

Declared In

NGLCamera.h

lensPerspective:near:far:angle:

Places new lens on camera.

- (void)lensPerspective:(float)aspect near:(float)near far:(float)far angle:(float)angle

Parameters

aspect

This parameter represents the aspect ratio relative to the device’s screen. OpenGL produces squared image and if the device’s screen is not squared the final image will be stretched to fit into the device’s screen. With this parameter that problem can be avoided. What you need to do is inform the screen’s aspect ratio (or the desired part of screen). To calculate it, just divide the final width by the final height (width / height).

near

Indicates the minimum distance for the camera to capture an objects. This value is associated with a generic unit, the same used in the 3D space. A good value to it could be 0.01, by this way only the objects very close to the camera will be clipped.

far

Indicates the maximum range for the camera capture an objects. This value is associated with a generic unit, the same used in the 3D space. A good value to it could be 100.0, by this way only the objects very far to the camera will be clipped.

angle

The Angle of View. It’s also called as Field of View (FOV), but actually they are not the same thing, though they are related. The human eye total perception goes around 130º to 160º, but the focus is around 45º to 60º. So these could be good values to use. Great angles are like Gran Angular lens (as the Fisheye Lens). Here are some acceptable values and their equivalent lenses:

  • 100 = 15mm lens;
  • 83 = 20mm lens;
  • 73 = 24mm lens;
  • 65 = 28mm lens;
  • 54 = 35mm lens;
  • 39 = 50mm lens;
  • 23 = 85mm lens;
  • 15 = 135mm lens;
  • 10 = 200mm lens.

Values higher than 170 and smaller than 10 produce bizarre results and distort a lot of the real 3D world.

Discussion

Places new lens on camera.

This lens has a perspective projection.

Declared In

NGLCamera.h

removeAllMeshes

Removes all meshes attached to this camera. All the meshes will receive a release message.

- (void)removeAllMeshes

Discussion

Removes all meshes attached to this camera. All the meshes will receive a release message.

If no mesh was found in this camera, this method does nothing.

Declared In

NGLCamera.h

removeMesh:

Removes a specific mesh attached to this camera. The meshes are released when removed from camera.

- (void)removeMesh:(NGLMesh *)mesh

Parameters

mesh

A NGLMesh to remove.

Discussion

Removes a specific mesh attached to this camera. The meshes are released when removed from camera.

If the mesh is not found in this camera, this method does nothing.

Declared In

NGLCamera.h