Unigine.Player Class

Inherits:

Sort by:

List of functions:

This class is used to create cameras that view the world. When you create a new player, it creates a camera and specifies controls, masks, postprocess materials for this camera.

Players' viewing frustum is defined by a near clipping plane, far clipping plane and the field of view. Note that if you set up a custom projection matrix and after that call any of these functions:

your custom matrices will be overwritten.

Players cannot have a parent node; they always use the world coordinates for their transformations. The only exception is PlayerDummy.

Player Masks

Objects, decals and lights can be selectively displayed in the player viewport. To be displayed, their viewport mask should be matching with the player's viewport mask (one matching bit is enough):

Object surface viewport mask or decal viewport mask
Light viewport mask to light the object/decal
Material viewport mask to render the object/decal material

Reflections can also be selectively rendered into the viewport: an object can be rendered without reflection or reflection without an object. For that, the player's reflection mask should match with:

Reflection mask of the reflecting material
Viewport mask of the reflecting material
Object surface viewport mask
Material viewport mask of the reflected material
Light viewport mask

That is enough to render reflection from the object without an object itself. If an object needs to be present as well, all these conditions should simply go together with above mentioned ones.

To render an object without reflection, simply either its material viewport mask or object surface viewport mask should not match the player's reflection mask.

Players also can have sound source and sound reverberation masks. As well as for viewports, corresponding masks of the Player object should match with SoundReverb and SoundSource masks.

Perspective and Orthographic Projection

Depending on your project's requirements you can set your player to use perspective or orthographic projection. This can be done via the setProjection() method.

For example, you can use the following code to set up orthographic projection or perspective projection for your current game player depending on a flag value:

Source code (C#)

// AppWorldLogic.cs

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		Player player;

		/* ... */
		
		// ortho flag - change this value to switch projection type
		int ortho = 0;
		public override int init()
		{
			/* ... */
			
			// getting the current player
			player = Game.get().getPlayer();
	
			// setting up near and far clipping planes and aspect ratio
			float znear = 0.001f;
			float zfar = 10000.0f;
			float aspect = 16.0f / 9.0f;

			if (ortho)
			{
				// setting up orthographic projection
				player.setProjection(MathLib.ortho(-1.0f, 1.0f, -1.0f, 1.0f, znear, zfar));
			}
			else
			{
				// setting up perspective projection
				player.setProjection(MathLib.perspective(60.0f, aspect, znear, zfar));
			}

			return 1;
		}
	}
}

Usage Example

In this example a PlayerSpectator class instance (which inherited from Player class) 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;

		/* ... */

		public override int init()
		{
			/* ... */
			playerSpectator = new PlayerSpectator();

			// specify the necessary parameters: FOV, ZNear, ZFar, view direction vector and PlayerSpectator position.
			playerSpectator.setFov(90.0f);
			playerSpectator.setZNear(0.1f);
			playerSpectator.setZFar(10000.0f);
			playerSpectator.setViewDirection(new vec3(0.0f, 1.0f, 0.0f));
			playerSpectator.setWorldPosition(new dvec3(-1.6f, -1.7f, 1.7f));

			// set the Player to the Game singleton instance
			Game.get().setPlayer(playerSpectator);

			return 1;
		}
	}
}

Player Class

Members

Player cast(Node node)

Casts a Player out of the Node instance.

Arguments

Node node - Node instance.

Return value

Player instance.

void setCamera(Camera camera)

Sets given Camera instance to the Player.

Arguments

Camera camera - Camera instance to be set.

Camera getCamera()

Returns the Camera instance of the Player node.

Return value

The camera of the player.

void setControlled(int controlled)

Disables or enables the player controls.

Arguments

int controlled - 1 — enable player controls, 0 — disable (player stops responding to them).

int isControlled()

Returns a value indicating whether player controls are disabled (player does not respond to them) or enabled.

Return value

1 if player controls are disabled; otherwise, 0.

void setControls(Controls controls)

Sets a Controls smart pointer that will hold settings of input controls relevant to the player.

Arguments

Controls controls - Controls object used to handle input controls.

Controls getControls()

Returns a Controls smart pointer that holds settings of input controls relevant to the player.

Return value

Controls smart pointer used to handle input controls.

void getDirectionFromScreen(out Vec3 p0, out Vec3 p1, int x = -1, int y = -1, int width = -1, int height = -1)

Casts the ray to a certain position on the screen and returns coordinates of the start (p0) and end (p1) points of the ray.

Source code (C#)

// get the current player (camera)
Player player = Game.get().getPlayer();
if (player == null)
	return 0;
// get width and height of the current application window
int width = App.get().getWidth();
int height = App.get().getHeight();
// get the current X and Y coordinates of the mouse pointer
int mouse_x = App.get().getMouseX();
int mouse_y = App.get().getMouseY();
// get the mouse direction from the player's position (p0) to the mouse cursor pointer (p1)
player.getDirectionFromScreen(out p0, out p1, mouse_x, mouse_y, width, height);

Arguments

out Vec3 p0 - Start coordinates of the ray.
out Vec3 p1 - End coordinates of the ray.
int x - X-coordinate of the screen position. If the value is less than 0, the getMouseX() value will be used.
int y - Y-coordinate of the screen position. If the value is less than 0, the getMouseY() value will be used.
int width - Screen width. If the width is less than 0, the getWidth() value will be used.
int height - Screen height. If the height is less than 0, the getHeight() value will be used.

vec3 getDirectionFromScreen(int x = -1, int y = -1, int width = -1, int height = -1)

Casts the ray to a certain position on the screen and returns a vector in the direction of this position.

Source code (C#)

// initializing points of the ray from player's position in the direction pointed by the mouse cursor 
Vec3 p0 = player.getWorldPosition();
Vec3 p1 = p0 + Vec3(player.getDirectionFromScreen(App.get().getMouseX(), App.get().getMouseY())) * 100;

Arguments

int x - X-coordinate of the screen position. If the value is less than 0, the getMouseX() value will be used.
int y - Y-coordinate of the screen position. If the value is less than 0, the getMouseY() value will be used.
int width - Screen width. If the width is less than 0, the getWidth() value will be used.
int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

Vector coordinates.

void setFov(float fov)

Sets a vertical field of view of the player.

NoticeHorizontal 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]. The default is 60 degrees.

float getFov()

Returns the current vertical field of view of the player.

NoticeHorizontal 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. The default is 60 degrees.

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 player
                Player player = Game.get().getPlayer();
                if (player != null)
                {
					// enabling oblique frustum
                    player.setObliqueFrustum(1);

					// setting our plane as an oblique near clipping plane
                    player.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.

Player getPlayer()

Returns a player pointer.

Return value

The player pointer.

void setPostMaterials(string materials)

Sets postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.

Arguments

string materials - List of comma-separated postprocess materials names.

string getPostMaterials()

Returns names of postprocess materials applied after all other postprocess (such as HDR, DOF, etc.) are rendered.

Return value

Comma-separated list of names of 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 - New projection matrix.

mat4 getProjection()

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

Return value

Current projection matrix.

mat4 getProjectionFromScreen(int x0, int y0, int x1, int y1, int width = -1, int height = -1)

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

Arguments

int x0 - X-coordinate of the first screen position.
int y0 - Y-coordinate of the first screen position.
int x1 - X-coordinate of the second screen position.
int y1 - Y-coordinate of the second screen position.
int width - Screen width. If the width is less than 0, the getWidth() value will be used.
int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

Projection matrix.

void setReflectionMask(int mask)

Sets a reflection 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 a mask.

int getReflectionMask()

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

Return value

Reflection mask (integer, each bit of which is a mask).

void setReverbMask(int mask)

Sets a reverb mask that determines reverberation zones, which can be heard. For sound to reverberate, at least one bit of this mask should match with 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 player's one in different 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 with 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 player's one in different bits, not necessarily one).

Return value

Reverb mask (integer, each bit of which is a mask for reverberating sound sources and reverberation zones).

int getScreenPosition(out int x, out int y, ref Vec3 point, int width = -1, int height = -1)

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

Arguments

out int x - X-coordinate of the screen position.
out int y - Y-coordinate of the screen position.
ref Vec3 point - Point coordinates.
int width - Screen width. If the width is less than 0, the getWidth() value will be used.
int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

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

void setSourceMask(int mask)

Sets a source mask that determines sound sources, which can be heard. For a sound source to be heard, its mask should match with 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 the source mask that determines sound sources, which can be heard. For a sound source to be heard, its mask should match with 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

Source mask (integer, each bit of which specifies a sound channel).

void setUp(vec3 up)

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

Arguments

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

vec3 getUp()

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

Return value

Upward direction vector.

void setVelocity(vec3 velocity)

Sets a new velocity for the player. In case of PlayerActor, this function is valid only when the player is not simulated physically (setPhysical() is set to 0). If it is, moving PlayerActor is done via accessing its body.

Arguments

vec3 velocity - New velocity in units per second.

vec3 getVelocity()

Returns the current velocity of the player.

Return value

Velocity in units per second.

void setViewDirection(vec3 direction)

Sets given view direction vector to the Player instance.

Arguments

vec3 direction - A view direction vector.

vec3 getViewDirection()

Returns Player's view direction vector.

Return value

A view direction vector.

void setViewportMask(int mask)

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

Arguments

int mask - Integer, each bit of which is a mask.

int getViewportMask()

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

Return value

Viewport mask (integer, each bit of which is a mask).

void setZFar(float zfar)

Sets a distance to the far clipping plane of the player's viewing frustum. The default is 10000 units.

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 player's viewing frustum. The default is 10000 units.

Return value

Distance to the far clipping plane in units.

void setZNear(float znear)

Sets a distance to the near clipping plane of the player's viewing frustum. The default is 0.1 units.

Arguments

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

float getZNear()

Returns the distance to the near clipping plane of the player's viewing frustum. The default is 0.1 units.

Return value

Distance to the near clipping plane in units.

void flushTransform()

Forces to immediately set transformations to the player. This function should be called manually after user input has been updated via updateControls().

void updateControls(float ifps)

Gets the current player's parameters (impulse, direction, velocity etc) according to user input. After the input has been updated, flushTransform() should be called manually to apply it to the player.

Arguments

float ifps - Frame duration in seconds.

void setFovMode(int mode)

Sets the value indicating the type of FOV that is used for the player:

For the standard player, the vertical FOV should be set. In this case, FOV is directly set in degrees.
For the physically-based player, the horizontal FOV should be set. In this case, FOV is calculated depending on the film gate and focal length of the player.

Arguments

int mode - FOV_MODE_VERTICAL for the player with the vertical FOV; FOV_MODE_PHYSICALLY_BASED_CAMERA for the physically-based player with the horizontal FOV.

int getFovMode()

Sets the value indicating the type of FOV that is used for the player.

Return value

0 if the player with the vertical FOV is used; 1 if the physically-based player with the horizontal FOV is used.

void setFilmGate(float gate)

Sets a film gate for the physically-based camera with horizontal FOV.

Arguments

float gate - Film gate.

float getFilmGate()

Returns a film gate for the physically-based camera with horizontal FOV.

Return value

Film gate.

void setFocalLength(float length)

Sets a focal length of the physically-based camera lens.

Arguments

float length - Camera lens focal length.

float getFocalLength()

Returns the focal length of the physically-based camera lens.

Return value

Camera lens focal length.

mat4 getAspectCorrectedProjection(int width = -1, int height = -1)

Returns projection matrix after correction for the specified aspect ratio (screen width / screen height). Currently fixed FOV component is taken into account.

Arguments

int width - Screen width.
int height - Screen height.

Return value

Projection matrix after correction for the specified aspect ratio (screen width / screen height).

int getFovFixed()

Returns a value indicating which FOV component (horizontal or vertical) is currently fixed.

Return value

Current fixed FOV component, one of the Camera.FOV_FIXED_* values.

Last update: 2018-08-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)