This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine.Camera Class

The Camera class is used to create a new camera, set it up (set all the required matrices, field of view, masks and so on) and then pass it to an instance of the Viewport class to render an image from this camera.

Notice
An instance of this class is not a node.

A camera instance can have the following masks:

  • Sound Source mask
  • Sound Reverberation mask
  • Viewport mask
  • Reflection mask

Camera settings can be set up in the Camera Settings in UnigineEditor.

Usage Example

In this example Camera and PlayerSpectator (which inherited from Player class) instances created and added to the current scene. Here is a code from the AppWorldLogic.cs file.

Source code (C#)
namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		PlayerSpectator playerSpectator;
		Camera camera;

		/* ... */

		public override int init()
		{
			/* ... */
			// initialize PlayerSpectator and Camera instances
			playerSpectator = new PlayerSpectator();
			camera = new Camera();

			// specify the necessary camera parameters: FOV, ZNear, ZFar.
			// add the post_sensor_red post-effect to camera
			camera.setFov(110.0f);
			camera.setZNear(0.1f);
			camera.setZFar(10000.0f);
			camera.setPostMaterials("post_sensor_red");

			// set camera to the player
			playerSpectator.setCamera(camera);

			// specify the position and view direction of playerSpectator
			playerSpectator.setViewDirection(new vec3(0.0f, 1.0f, 0.0f));
			playerSpectator.setWorldPosition(new dvec3(-1.6f, -1.7f, 1.7f));

			Game.get().setPlayer(playerSpectator);

			return 1;
		}
	}
}

Camera Class

Members


static Camera()

Constructor. Creates a new camera with default settings:

void getDirectionFromScreen(out Vec3 p0, out Vec3 p1, float screen_x, float screen_y, float aspect)

Casts the ray from a certain position on the screen.

Arguments

  • out Vec3 p0 - Start coordinate of the ray.
  • out Vec3 p1 - End coordinate of the ray.
  • float screen_x - X-coordinate of screen, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float screen_y - Y-coordinate of screen, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float aspect - Screen's aspect ratio (height to width).

vec3 getDirectionFromScreen(float screen_x, float screen_y, float aspect)

Casts the ray from a certain position on the screen.

Arguments

  • float screen_x - X-coordinate of screen, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float screen_y - Y-coordinate of screen, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float aspect - Screen's aspect ratio (height to width).

Return value

Point coordinate.

void setFov(float fov)

Sets a vertical field of view of the camera and updates the projection matrix.

Notice
Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.

You can use the following formula to calculate horizontal FOV from the vertical one for the given aspect ratio (width/height): FOV_h = 2 × atan ( (width / height) × tan(FOV_v / 2)).

Arguments

  • float fov - New vertical field of view in degrees. The provided value will be saturated in the range [0;180].

float getFov()

Returns the current vertical field of view of the camera.

Notice
Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.

You can use the following formula to calculate horizontal FOV from the vertical one for the given aspect ratio (width/height): FOV_h = 2 × atan ( (width / height) × tan(FOV_v / 2)).

Return value

Vertical field of view in degrees.

Mat4 getIModelview()

Returns the inverted view matrix of the camera.

Return value

Inverse view matrix.

void setModelview(Mat4 modelview)

Updates a modelview and inverse modelview matrices for the camera.

Arguments

  • Mat4 modelview - New view matrix.

Mat4 getModelview()

Returns the current view matrix of the camera.

Return value

Current view matrix.

void setObliqueFrustum(int enabled)

Enables or disables obliqueness of the viewing frustum.
Notice
It is recommended to set oblique viewing frustum using this method, as it doesn't affect the projection matrix. To specify the near clipping plane use the setObliqueFrustumPlane() method.

Arguments

  • int enabled - 1 to enable oblique viewing frustum; 0 to disable it.

int isObliqueFrustum()

Returns a value indicating if the viewing frustum is oblique.

Return value

1 if the viewing frustum is oblique; otherwise, 0.

void setObliqueFrustumPlane(Vec4 clipping_plane)

Sets the oblique near clipping plane of the viewing frustum.
Notice
This method does not affect the projection matrix. To enable the oblique frustum use the setObliqueFrustum() method.
Source code (C#)
// AppWorldLogic.cs
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Unigine;

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		/* .. */
		
		public override int update()
		{

            float time = Game.get().getTime();
			
				// initializing a plane to be set as a near clipping plane
                dvec4 plane = new dvec4(1.0f, 1.0f, 1.0f, 1.0f + MathLib.sin(time) * 4.0f);
				
				// getting a camera
                Camera camera = Game.get().getPlayer().getCamera();
                if (camera != null)
                {
					// enabling oblique frustum
                    camera.setObliqueFrustum(1);

					// setting our plane as an oblique near clipping plane
                    camera.setObliqueFrustumPlane(plane);
                }

            return 1;
		}
		
		/* .. */
	}
}

Arguments

  • Vec4 clipping_plane - World coordinates of the oblique near clipping plane to set (Nx, Ny, Nz, D), where Nx, Ny, Nz - coordinates of the plane normal, D - distance from the origin to the plane.

Vec4 getObliqueFrustumPlane()

Returns the oblique near clipping plane of the viewing frustum.

Return value

World coordinates of the oblique near clipping plane to set (Nx, Ny, Nz, D), where Nx, Ny, Nz - coordinates of the plane normal, D - distance from the origin to the plane.

void setOffset(mat4 offset)

Sets an additional transformation (an offset matrix) for the camera. This transformation is applied after the modelview transformation. The offset matrix does not affect the view matrix or the position of the camera. For example, the offset matrix can be used to simulate camera shaking from an explosion.

Arguments

  • mat4 offset - Offset matrix.

mat4 getOffset()

Returns an additional transformation (an offset matrix) set for the camera. This transformation is applied after modelview transformation. The offset matrix does not affect the view matrix or the position of the camera. For example, it can be used to simulate camera shake from an explosion.

Return value

Offset matrix.

void setPosition(Vec3 position)

Sets a new position of the camera and updates the modelview and inverse modelview (its 3rd column) matrices.

Arguments

  • Vec3 position - Camera position in the world space.

Vec3 getPosition()

Returns the current position of the camera. The position vector is stored in the 3rd column of the inverse view matrix.

Return value

Camera position in the world space.

void setPostMaterials(string materials)

Sets post postprocess materials that are applied after all other postprocess are rendered. They are used after engine.render.setPostMaterials(), if any.

Arguments

  • string materials - Comma-separated names of postprocess materials.

string getPostMaterials()

Returns names of the current post postprocess materials that are applied after all other postprocess are rendered. They are used after engine.render.getPostMaterials(), if any.

Return value

Name of the current post postprocess materials.

void setProjection(mat4 projection)

Updates the current projection matrix.
Notice
It is not recommended to use this method for setting obliqueness of the near clipping plane of the frustum, as in this case a number of features (such as clouds, shadows, TAA, a number of engine optimizations, etc.) will not function properly. Please, use the setObliqueFrustum() method instead.

Arguments

  • mat4 projection - Projection matrix.

mat4 getProjection()

Returns the current projection matrix with unit (1.0) aspect ratio.

Return value

Projection matrix.

mat4 getProjectionFromScreen(float screen_x0, float screen_y0, float screen_x1, float screen_y1, float aspect)

Creates a projection matrix out of 2 screen positions. This is required for the frame selection.

Arguments

  • float screen_x0 - X-coordinate of the first screen position, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float screen_y0 - Y-coordinate of the first screen position, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float screen_x1 - X-coordinate of the second screen position, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float screen_y1 - Y-coordinate of the second screen position, in the [0;1] range, where 0 is the left upper point, 1 is the right lower point.
  • float aspect - Screen's aspect ratio (height to width).

Return value

Projection matrix.

void setReflectionMask(int mask)

Sets a bit mask for rendering reflections into the viewport. Reflections are rendered in the viewport if masks of reflective materials match this one.

Arguments

  • int mask - Integer, each bit of which is used to set a mask.

int getReflectionMask()

Returns the current bit mask for rendering reflections into the camera viewport. Reflections are rendered in the camera viewport if masks of reflective materials match this one.

Return value

Integer, each bit of which is used to set a mask.

void setReverbMask(int mask)

Updates a bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match a reverb mask of the sound source and a reverb mask of the reverberation zone. Masks of a sound source and reverberation zone can match the camera's one in several bits, not necessarily one.

Arguments

  • int mask - Integer, each bit of which is a mask for reverberating sound sources and reverberation zones.

int getReverbMask()

Returns the current bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match a reverb mask of the sound source and a reverb mask of the reverberation zone. Masks of a sound source and reverberation zone can match with the camera's one in several bits, not necessarily one.

Return value

Integer, each bit of which is used to set a mask for reverberating sound sources and reverberation zones.

int getScreenPosition(out float screen_x, out float screen_y, ref Vec3 point, float aspect)

Projects the point in world coordinates to the screen. Screen coordinates are written into the first 2 variables passed to the method.

Arguments

  • out float screen_x - X-coordinate of the screen position.
  • out float screen_y - Y-coordinate of the screen position.
  • ref Vec3 point - Point coordinates.
  • float aspect - Aspect ratio (screen height to width).

Return value

1 if the point has been projected successfully; otherwise, 0.

void setSourceMask(int mask)

Updates a bit mask that determines what sound sources can be heard. For a sound source to be heard, its mask should match this one in at least one bit. Plus, the volume of sound channel in which the sound plays (its number also depends on this mask) should not be equal to 0.

Arguments

  • int mask - Integer, each bit of which specifies a sound channel.

int getSourceMask()

Returns a bit mask that determines what sound channels can be heard. For a sound source to be heard, its mask should match this one in at least one bit. Plus, the volume of sound channel in which the sound plays (its number also depends on this mask) should not be equal to 0.

Return value

Integer, each bit of which specifies a sound channel.

void setUp(vec3 up)

Sets an up direction of the camera's viewport (i.e. tilt of the camera's viewport).

Arguments

  • vec3 up - New upward direction vector. The vector is normalized to 1.

vec3 getUp()

Returns the current up direction of the camera's viewport (i.e. tilt of the camera's viewport).

Return value

Upward direction vector.

void setViewportMask(int mask)

Sets a bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport masks match the camera's one (one matching bit is enough).

Arguments

  • int mask - Integer, each bit of which is used to set a mask.

int getViewportMask()

Returns the current bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport mask matches the camera's one (one matching bit is enough).

Return value

Integer, each bit of which is used to set a mask.

void setZFar(float zfar)

Sets a distance to the far clipping plane of the camera's viewing frustum and updates the projection matrix.

Arguments

  • float zfar - New distance in units. If a negative value is provided, 0 will be used instead.

float getZFar()

Returns the current distance to the far clipping plane of the camera's viewing frustum.

Return value

Distance in units.

void setZNear(float znear)

Sets a distance to the near clipping plane of the camera's viewing frustum and updates the projection matrix.

Arguments

  • float znear - New distance in units. If a negative value is provided, 0 will be used instead.

float getZNear()

Returns the current distance to the near clipping plane of the camera's viewing frustum.

Return value

Distance in units.

Camera clone()

Clones the current camera and saves it to the given camera instance.

Return value

Copy of the camera.
Last update: 2018-06-04
Build: ()