Unigine::Player Class

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 viewport mask should match:

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 viewport 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++)

#include "AppWorldLogic.h"
#include <UnigineGame.h>
#include <UniginePlayers.h>

using namespace Unigine;
using namespace Math;

/* ... */

// calculates a projection matrix for the specified parameters (angles for left, right, top, and bottom are in degrees)
Unigine::Math::mat4 calculateProjection(double left, double right, double bottom, double top, double zNear, double zFar, double zoom)
{
	left = zNear * Unigine::Math::tan(Unigine::Math::Consts::DEG2RAD*(left * zoom));
	right = zNear * Unigine::Math::tan(Unigine::Math::Consts::DEG2RAD*(right * zoom));
	top = zNear * Unigine::Math::tan(Unigine::Math::Consts::DEG2RAD*(top * zoom));
	bottom = zNear * Unigine::Math::tan(Unigine::Math::Consts::DEG2RAD*(bottom * zoom));

	return Unigine::Math::frustum(static_cast<float>(left), static_cast<float>(right), static_cast<float>(bottom), static_cast<float>(top), static_cast<float>(zNear), static_cast<float>(zFar));
}

	/* ... */

	// ortho flag - change this value to switch projection type
	int ortho_proj = 0;

int AppWorldLogic::init()
{
	// disabling default aspect correction for the main window 
	// to ensure that the custom projection is applied properly
	Unigine::WindowManager::getMainWindow()->setAspectCorrection(false);

	// getting the current player
	PlayerPtr player = Game::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;
	
	float fov = 60.0f;
	float ortho_height = 2.0f;
	
	player->setZNear(znear);
	player->setZFar(zfar);
	player->setFov(fov);
	player->setOrthoHeight(ortho_height);
	
	if (ortho_proj)
	{
		// setting up orthographic projection
		player->setProjectionMode(Camera::PROJECTION_MODE_ORTHOGRAPHIC);
		
		// or setting up orthographic projection manually
		player->setProjection(Math::ortho(-ortho_height / 2.0f, ortho_height / 2.0f, -ortho_height / 2.0f, ortho_height / 2.0f, znear, zfar));
	}
	else
	{
		// setting up perspective projection
		player->setProjectionMode(Camera::PROJECTION_MODE_PERSPECTIVE);


		// or setting up a projection matrix manually
		player->setProjection(Math::perspective(fov, aspect, znear, zfar));


		// or calculating a projection matrix for FullfHD/4K resolution
		auto projection = calculateProjection(-22.5f, 22.5f, -13.1f, 13.1f, 1.0f, 200000.0f, 1.0f);
		// and setting up custom calculated projection manually
		player->setProjection(projection);
	}

	return 1;
}

Getting Euler Angles for an Active Camera

Sometimes it might be necessary to get current rotation of the active camera as a set of Euler angles. When we talk about axes in UNIGINE we assume that:


X axis points to the right giving us a pitch angle. Y axis points forward giving us a roll angle. Z axis points up giving us a yaw (heading) angle.	Object Direction Vectors

To get the Euler angles we should use decomposeRotationZXY() also known as Cardan angles (yaw is independent, then we get pitch and in the end, roll). But, there is one thing to be taken into account - cameras have a different system:


X axis points to the right giving us a pitch angle. Y axis points up giving us a yaw (heading) angle. Z axis points backward giving us a -roll angle.	Camera Direction Vectors

To compensate it, we need to rotate our camera -90 degrees around X axis.

Source code (C++)

#include "AppWorldLogic.h"
#include <UnigineGame.h>
#include <UniginePlayers.h>

using namespace Unigine;
using namespace Math;

/* ... */

	// getting the current view matrix of the current camera
	Mat4 currentModelview = Game::getPlayer()->getCamera()->getIModelview();

	// decomposing rotation matrix of the camera (with compensation)
	vec3 euler = decomposeRotationZXY(mat3(currentModelview * Mat4(rotateX(-90.0f))));
	euler.x += 90.0f;

	// perform correction for negative angle values
	if (euler.x < 0) euler.x += 360.0f;
	if (euler.y < 0) euler.y += 360.0f;
	if (euler.z < 0) euler.z += 360.0f;

	// Euler angles for the camera
	float pitch = euler.x;
	float roll = euler.y;
	float yaw = euler.z;

Usage Example#

In this example we create a PlayerSpectator player, specify its parameters and set it as current game player.

In the AppWorldLogic.h header file include the UniginePlayers.h header and declare a PlayerSpectator smart pointer.

Source code (C++)

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UniginePlayers.h>

class AppWorldLogic : public Unigine::WorldLogic
{

public:

	/* public methods */

private:
	Unigine::PlayerSpectatorPtr playerSpectator;

};

In the AppWorldLogic.cpp implementation file do the following:

Include the UnigineGame.h header to set a new player by using setPlayer() method.
Use using namespace Unigine directive: names of the Unigine namespace will be injected into global namespace.
Specify the necessary parameters of the created Player instance.
Set our recently created Player as a current game player.
Clear the pointer to the PlayerSpectator to avoid memory leaks.

Here are the necessary parts of code:

Source code (C++)

#include "AppWorldLogic.h"
#include <UnigineGame.h>
#include <UniginePlayers.h>

using namespace Unigine;
using namespace Math;

/* ... */

int AppWorldLogic::init()
{

	// create a new PlayerSpectator instance
	playerSpectator = PlayerSpectator::create();

	// 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(Math::vec3(0.0f, 1.0f, 0.0f));
	playerSpectator->setWorldPosition(Math::Vec3(-1.6f, -1.7f, 1.7f));

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

	return 1;
}

int AppWorldLogic::shutdown()
{

	// clear the pointer to Player
	playerSpectator.clear();

	return 1;
}

功能列表:

Name	描述 View: Sort by:
setCamera	Sets given Camera instance to the Player.
getCamera	Returns the Camera instance of the Player node.
setControlled	Disables or enables the player controls.
isControlled	Returns a value indicating whether player controls are disabled (player does not respond to them) or enabled.
setControls	Sets a Controls object that will hold settings of input controls relevant to the player.
getControls	Returns a Controls object that holds settings of input controls relevant to the player.
setFov	Sets a vertical field of view of the player.
getFov	Returns the current vertical field of view of the player.
setObliqueFrustum	Enables or disables obliqueness of the viewing frustum.
isObliqueFrustum	Returns a value indicating if the viewing frustum is oblique.
setObliqueFrustumPlane	Sets the oblique near clipping plane of the viewing frustum.
getObliqueFrustumPlane	Returns the oblique near clipping plane of the viewing frustum.
setProjection	Updates the current projection matrix.
getProjection	Returns the current projection matrix with unit (1.0) aspect ratio.
setReflectionViewportMask	Sets a bit mask for rendering reflections into the viewport.
getReflectionViewportMask	Returns the current bit mask for rendering reflections into the viewport.
setReverbMask	Sets a reverb mask that determines reverberation zones, which can be heard.
getReverbMask	Returns the current bit mask that determines what reverberation zones can be heard.
setSourceMask	Sets a source mask that determines sound sources, which can be heard.
getSourceMask	Returns the source mask that determines sound sources, which can be heard.
setUp	Sets an up direction of the player's viewport (i.e. tilt of the player's viewport).
getUp	Returns the current up direction of the player's viewport (i.e. tilt of the player's viewport).
setVelocity	Sets a player's velocity.
getVelocity	Returns the current velocity of the player.
setViewDirection	Sets given view direction vector to the Player instance.
getViewDirection	Returns Player's view direction vector.
setViewportMask	Sets a viewport mask.
getViewportMask	Returns the current viewport mask.
setZFar	Sets a distance to the far clipping plane of the player's viewing frustum.
getZFar	Returns the current distance to the far clipping plane of the player's viewing frustum.
setZNear	Sets a distance to the near clipping plane of the player's viewing frustum.
getZNear	Returns the distance to the near clipping plane of the player's viewing frustum.
setFovMode	Sets the value indicating the type of FOV that is used for the player: For the standard player, the vertical FOV should be set.
getFovMode	Returns the value indicating the type of FOV that is used for the player.
setFilmGate	Sets a film gate for the physically-based camera with horizontal FOV.
getFilmGate	Returns a film gate for the physically-based camera with horizontal FOV.
setFocalLength	Sets a focal length of the physically-based camera lens.
getFocalLength	Returns the focal length of the physically-based camera lens.
getFovFixed	Returns a value indicating which FOV component (horizontal or vertical) is currently fixed.
getNumScriptableMaterials	Returns the total number of scriptable materials attached to the player.
setMainPlayer	Sets a player as a main player.
isMainPlayer	Checks if the player is a main player.
setListener	Sets the player as the listener.
isListener	Checks if the player is a listener.
setProjectionMode	Sets the projection mode: orthographic or perspective.
getProjectionMode	Returns the current projection mode: orthographic or perspective.
setOrthoHeight	Sets the height of the camera with the orthographic projection mode enabled.
getOrthoHeight	Returns the current height of the camera with the orthographic projection mode enabled.
getDirectionFromScreen	Casts the ray to a certain position on the screen and returns coordinates of the start (p0) and end (p1) points of the ray.
getProjectionFromScreen	Creates a projection matrix out of 2 screen positions .
getScreenPosition	Projects the point in world coordinates to the screen.
flushTransform	Forces to immediately set transformations to the player.
updateControls	Gets the current player's parameters (impulse, direction, velocity etc) according to user input.
getAspectCorrectedProjection	Returns projection matrix after correction for the specified aspect ratio (screen width / screen height).
addScriptableMaterial	Attaches a new scriptable material to the player.
insertScriptableMaterial	Inserts a new scriptable material into the list of the ones assigned to the player.
removeScriptableMaterial	Removes the scriptable material with the specified number from the player.
findScriptableMaterial	Returns the number of the specified scriptable material for the player.
setScriptableMaterial	Replaces the scriptable material with the specified number with the new scriptable material specified.
getScriptableMaterial	Returns a scriptable material attached to the player by its number.
setScriptableMaterialEnabled	Enables or disables the scriptable material with the specified number.
getScriptableMaterialEnabled	Returns a value indicating if the scriptable material with the specified number attached to the player is enabled (active).
swapScriptableMaterials	Swaps two scriptable materials with specified numbers.
clearScriptableMaterials	Clears all scriptable materials attached to the player.
getDirectionFromMainWindow	Casts the ray to a certain position on the screen and returns coordinates of the start (p0) and end (p1) points of the ray relative to the current main window.
getDirectionFromWindow	Casts the ray to a certain position on the screen and returns coordinates of the start (p0) and end (p1) points of the ray relative to the specified window viewport.
getProjectionFromMainWindow	Creates a projection matrix out of 2 screen positions relative to the current main window.
getProjectionFromWindow	Creates a projection matrix out of 2 screen positions relative to the specified window viewport.
getMainWindowPosition	Projects the point in world coordinates relative to the main window.
getWindowPosition	Projects the point in world coordinates relative to the specified window viewport.

Player Class

Members

void setCamera ( const Ptr<Camera> & camera ) #

Sets given Camera instance to the Player.

Arguments

const Ptr<Camera> & camera - Smart pointer to a Camera to be set.

Ptr<Camera> getCamera ( ) const#

Returns the Camera instance of the Player node.

Return value

The camera of the player.

void setControlled ( bool controlled ) #

Disables or enables the player controls.

Arguments

bool controlled - true to enable player controls, false to disable (player stops responding to them).

bool isControlled ( ) const#

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

Return value

true if player controls are enabled; otherwise, false.

void setControls ( const Ptr<Controls> & controls ) #

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

Arguments

const Ptr<Controls> & controls - Controls object used to handle input controls.

Ptr<Controls> getControls ( ) const#

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

Return value

Controls object used to handle input controls.

void getDirectionFromScreen ( Math::Vec3 & p0, Math::Vec3 & p1, int mouse_x, int mouse_y, int screen_x, int screen_y, int screen_width, int screen_height ) const#

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++)

Vec3 p0, p1;

// get the current player (camera)
PlayerPtr player = Game::getPlayer();

if (player.get() == NULL)
	return 0;

// get width and height of the current application window
Math::ivec2 winsize = WindowManager::getMainWindow()->getSize();
int width = winsize.x;
int height = winsize.y;

// get the current X and Y coordinates of the mouse pointer
int mouse_x = Gui::getCurrent()->getMouseX();
int mouse_y = Gui::getCurrent()->getMouseY();

// get the mouse direction from the player's position (p0) to the mouse cursor pointer (p1)
player->getDirectionFromScreen(p0, p1, mouse_x, mouse_y, 0, 0, width, height);

Arguments

Math::Vec3 & p0 - Start coordinates of the ray.
Math::Vec3 & p1 - End coordinates of the ray.
int mouse_x - X-coordinate of the mouse position.
int mouse_y - Y-coordinate of the mouse position.
int screen_x - X-coordinate of the screen position.
int screen_y - X-coordinate of the screen position.
int screen_width - Screen width.
int screen_height - Screen height.

Math::vec3 getDirectionFromScreen ( int mouse_x, int mouse_y, int screen_x, int screen_y, int screen_width, int screen_height ) const#

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

Source code (C++)

// get width and height of the current application window
Math::ivec2 winsize = WindowManager::getMainWindow()->getSize();
int width = winsize.x;
int height = winsize.y;

// 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(Gui::getCurrent()->getMouseX(), Gui::getCurrent()->getMouseY(), 0, 0, width, height)) * 100;

Arguments

int mouse_x - X-coordinate of the mouse position.
int mouse_y - Y-coordinate of the mouse position.
int screen_x - X-coordinate of the screen position.
int screen_y - X-coordinate of the screen position.
int screen_width - Screen width.
int screen_height - Screen height.

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. Setting FOV recalculates projection matrix with aspect ratio = 1.

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 ( ) const#

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 ( bool frustum ) #

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

bool frustum - true to enable oblique viewing frustum; false to disable it.

bool isObliqueFrustum ( ) const#

Returns a value indicating if the viewing frustum is oblique.

Return value

true if the viewing frustum is oblique; otherwise, false.

void setObliqueFrustumPlane ( const Math::Vec4 & 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++)

#include "AppWorldLogic.h"
#include <UnigineGame.h>
#include <UniginePlayers.h>

using namespace Unigine;
using namespace Math;

/* ... */

int AppWorldLogic::update()
{

	float time = Game::getTime();

	// initializing a plane to be set as a near clipping plane
	Math::Vec4 plane = Math::Vec4(1.0f, 1.0f, 1.0f, 1.0f + Math::sin(time) * 4.0f);

	// getting a player
	PlayerPtr player = Game::getPlayer();
	if (player != nullptr)
	{
		// enabling oblique frustum
		player->setObliqueFrustum(1);

		// setting our plane as an oblique near clipping plane
		player->setObliqueFrustumPlane(plane);
	}

	return 1;
}

Arguments

const Math::Vec4 & 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.

Math::Vec4 getObliqueFrustumPlane ( ) const#

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 setProjection ( const Math::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

const Math::mat4 & projection - New projection matrix.

Math::mat4 getProjection ( ) const#

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

Return value

Current projection matrix.

Math::mat4 getProjectionFromScreen ( int x0, int y0, int x1, int y1, int screen_width, int screen_height ) const#

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 screen_width - Screen width.
int screen_height - Screen height.

Return value

Projection matrix.

void setReflectionViewportMask ( 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 (one bit at least).

Arguments

int mask - Reflection viewport mask (an integer, each bit of which is a mask).

int getReflectionViewportMask ( ) const#

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

Return value

Reflection viewport mask (an 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 - Reverb mask (integer, each bit of which is a mask for reverberating sound sources and reverberation zones).

int getReverbMask ( ) const#

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 ( int & x, int & y, const Math::Vec3 & point, int screen_width, int screen_height ) const#

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

Arguments

int & x - X-coordinate of the screen position.
int & y - Y-coordinate of the screen position.
const Math::Vec3 & point - Point coordinates.
int screen_width - Screen width.
int screen_height - Screen height.

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 - Source mask (integer, each bit of which specifies a sound channel).

int getSourceMask ( ) const#

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 ( const Math::vec3 & up ) #

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

Notice

In case of PlayerActor, its transformation forces it to recalculate its inner state (position, direction, angles and so on), so the up direction of the player's viewport may become "negative forward". And then transformation will be recalculated by using this direction, causing flip of the basis of the player actor. To avoid such flipping, the theta and phi angles should be recalculated by using the current viewing orientation of the player.

Arguments

const Math::vec3 & up - New upward direction vector. The vector is normalized to 1.

Math::vec3 getUp ( ) const#

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 ( const Math::vec3 & velocity ) #

Sets a player's velocity.

Notice

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

const Math::vec3 & velocity - New velocity in units per second.

Math::vec3 getVelocity ( ) const#

Returns the current velocity of the player.

Return value

Velocity in units per second.

void setViewDirection ( const Math::vec3 & direction ) #

Sets given view direction vector to the Player instance.

Arguments

const Math::vec3 & direction - A view direction vector.

Math::vec3 getViewDirection ( ) const#

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 - Viewport mask (integer, each bit of which is a mask).

int getViewportMask ( ) const#

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 - Distance to the far clipping plane in units. The minimum value is 0.

float getZFar ( ) const#

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 - Distance to the near clipping plane in units. The minimum value is 0.

float getZNear ( ) const#

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 ( ) const#

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 ) const#

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 ( Camera::FOV_MODE 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

Camera::FOV_MODE 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.

Camera::FOV_MODE getFovMode ( ) const#

Returns 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 ( ) const#

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 ( ) const#

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

Return value

Camera lens focal length.

Math::mat4 getAspectCorrectedProjection ( int width = -1, int height = -1 ) const#

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).

Camera::FOV_FIXED getFovFixed ( ) const#

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.

void addScriptableMaterial ( const Ptr<Material> & material ) #

Attaches a new scriptable material to the player. To apply a scriptable material globally, use the addScriptableMaterial() method of the Render class. The order of execution for scripts assigned to scriptable materials is defined by material's number in the list of the player.

Notice

Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

const Ptr<Material> & material - Scriptable material to be attached to the player.

void insertScriptableMaterial ( int num, const Ptr<Material> & material ) #

Inserts a new scriptable material into the list of the ones assigned to the player. To apply a scriptable material globally, use the insertScriptableMaterial() method of the Render class. The order of execution for scripts assigned to scriptable materials is defined by material's number in the player's list.

Notice

Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

int num - Position at which a new scriptable material is to be inserted.
const Ptr<Material> & material - Scriptable material to be inserted.

void removeScriptableMaterial ( int num ) #

Removes the scriptable material with the specified number from the player.

Arguments

int num - Scriptable material number in the range from 0 to the total number of scriptable materials.

int getNumScriptableMaterials ( ) const#

Returns the total number of scriptable materials attached to the player.

Return value

Total number of scriptable materials attached to the player.

int findScriptableMaterial ( const Ptr<Material> & material ) const#

Returns the number of the specified scriptable material for the player. This number is player-specific (valid for this player only) and determines the order in which the assigned expressions are executed.

Notice

Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

const Ptr<Material> & material - Scriptable material for which a number is to be found.

Return value

Scriptable material number in the range from 0 to the total number of scriptable materials, or -1 if the specified material was not found.

void setScriptableMaterial ( int num, const Ptr<Material> & material ) #

Replaces the scriptable material with the specified number with the new scriptable material specified. The number of material determines the order in which the expressions assigned to it are executed. This number is player-specific (valid for this player only).

Notice

Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

int num - Scriptable material number in the range from 0 to the total number of scriptable materials.
const Ptr<Material> & material - New scriptable material to replace the one with the specified number.

Ptr<Material> getScriptableMaterial ( int num ) const#

Returns a scriptable material attached to the player by its number.

Arguments

int num - Scriptable material number in the range from 0 to the total number of scriptable materials.

Return value

Scriptable material attached to the player with the specified number.

void setScriptableMaterialEnabled ( int num, bool enabled ) #

Enables or disables the scriptable material with the specified number. When a material is disabled (inactive), the scripts attached to it are not executed.

Arguments

int num - Scriptable material number in the range from 0 to the total number of scriptable materials.
bool enabled - true to enable the scriptable material with the specified number, false to disable it.

bool getScriptableMaterialEnabled ( int num ) const#

Returns a value indicating if the scriptable material with the specified number attached to the player is enabled (active). When a material is disabled (inactive), the scripts attached to it are not executed.

Arguments

int num - Scriptable material number in the range from 0 to the total number of scriptable materials.

Return value

true if the scriptable material with the specified number is enabled; otherwise, false.

void swapScriptableMaterials ( int num_0, int num_1 ) #

Swaps two scriptable materials with specified numbers. The number of material determines the order in which the expressions assigned to it are executed.

Notice

The number is player-specific (valid for this player only).

Arguments

int num_0 - Number of the first scriptable material in the range from 0 to the total number of scriptable materials.
int num_1 - Number of the second scriptable material in the range from 0 to the total number of scriptable materials.

void clearScriptableMaterials ( ) #

Clears all scriptable materials attached to the player.

void setMainPlayer ( bool player ) #

Sets a player as a main player.

Arguments

bool player - true to set the player as the main player, false to unset it.

bool isMainPlayer ( ) const#

Checks if the player is a main player.

Return value

true if the player is a main player; otherwise, false.

void setListener ( bool listener ) #

Sets the player as the listener.

Arguments

bool listener - true to set the player as the listener, false to unset it.

bool isListener ( ) const#

Checks if the player is a listener.

Return value

true if the player is a listener; otherwise, false.

void getDirectionFromMainWindow ( Math::Vec3 & p0, Math::Vec3 & p1, int mouse_x, int mouse_y ) const#

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

Arguments

Math::Vec3 & p0 - Start coordinates of the ray.
Math::Vec3 & p1 - End coordinates of the ray.
int mouse_x - X-coordinate of the mouse position in world coordinates.
int mouse_y - Y-coordinate of the mouse position in world coordinates.

Math::vec3 getDirectionFromMainWindow ( int mouse_x, int mouse_y ) const#

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

Arguments

int mouse_x - X-coordinate of the mouse position in world coordinates.
int mouse_y - Y-coordinate of the mouse position in world coordinates.

Return value

Vector coordinates.

void getDirectionFromWindow ( Math::Vec3 & p0, Math::Vec3 & p1, int mouse_x, int mouse_y, const Ptr<EngineWindowViewport> & window ) const#

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

Arguments

Math::Vec3 & p0 - Start coordinates of the ray.
Math::Vec3 & p1 - End coordinates of the ray.
int mouse_x - X-coordinate of the mouse position in world coordinates.
int mouse_y - Y-coordinate of the mouse position in world coordinates.
const Ptr<EngineWindowViewport> & window - Window viewport relative to which the directon is returned.

Math::vec3 getDirectionFromWindow ( int mouse_x, int mouse_y, const Ptr<EngineWindowViewport> & window ) const#

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

Arguments

int mouse_x - X-coordinate of the mouse position in world coordinates.
int mouse_y - Y-coordinate of the mouse position in world coordinates.
const Ptr<EngineWindowViewport> & window - Window viewport relative to which the directon is returned.

Return value

Vector coordinates.

Math::mat4 getProjectionFromMainWindow ( int x0, int y0, int x1, int y1 ) const#

Creates a projection matrix out of 2 screen positions relative to the current main window. 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.

Return value

Projection matrix.

Math::mat4 getProjectionFromWindow ( int x0, int y0, int x1, int y1, const Ptr<EngineWindowViewport> & window ) const#

Creates a projection matrix out of 2 screen positions relative to the specified window viewport. 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.
const Ptr<EngineWindowViewport> & window - Window viewport relative to which the projection is returned.

Return value

Projection matrix.

int getMainWindowPosition ( int & x, int & y, const Math::Vec3 & point ) const#

Projects the point in world coordinates relative to the main window. The coordinates are written into the first 2 variables passed to the method.

Arguments

int & x - X-coordinate of the screen position.
int & y - Y-coordinate of the screen position.
const Math::Vec3 & point - Point coordinates.

Return value

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

int getWindowPosition ( int & x, int & y, const Math::Vec3 & point, const Ptr<EngineWindowViewport> & window ) const#

Projects the point in world coordinates relative to the specified window viewport. The coordinates are written into the first 2 variables passed to the method.

Arguments

int & x - X-coordinate of the screen position.
int & y - Y-coordinate of the screen position.
const Math::Vec3 & point - Point coordinates.
const Ptr<EngineWindowViewport> & window - Window viewport relative to which the projection is returned.

Return value

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

void setProjectionMode ( Camera::PROJECTION_MODE mode ) #

Sets the projection mode: orthographic or perspective.

Arguments

Camera::PROJECTION_MODE mode - The projection mode, PROJECTION_MODE_ORTHOGRAPHIC for the orthographic mode; PROJECTION_MODE_PERSPECTIVE for the perspective mode.

Camera::PROJECTION_MODE getProjectionMode ( ) const#

Returns the current projection mode: orthographic or perspective.

Return value

The projection mode, PROJECTION_MODE_ORTHOGRAPHIC for the orthographic mode; PROJECTION_MODE_PERSPECTIVE for the perspective mode.

void setOrthoHeight ( float height ) #

Sets the height of the camera with the orthographic projection mode enabled.

Arguments

float height - The orthographic camera height.

float getOrthoHeight ( ) const#

Returns the current height of the camera with the orthographic projection mode enabled.

Return value

The orthographic camera height.

Last update: 2024-12-13

Help improve this article

Was this article helpful?

Report a problem related to this article

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

Header:	#include <UniginePlayers.h>
Inherits from:	Node

Unigine::Player Class

In This Article:

Player Masks#

Perspective and Orthographic Projection#

Getting Euler Angles for an Active Camera

Usage Example#

功能列表:

Player Class

Members

void setCamera ( const Ptr<Camera> & camera ) #

Arguments

Ptr<Camera> getCamera ( ) const#

Return value

void setControlled ( bool controlled ) #

Arguments

bool isControlled ( ) const#

Return value

void setControls ( const Ptr<Controls> & controls ) #

Arguments

Ptr<Controls> getControls ( ) const#

Return value

void getDirectionFromScreen ( Math::Vec3 & p0, Math::Vec3 & p1, int mouse_x, int mouse_y, int screen_x, int screen_y, int screen_width, int screen_height ) const#

Arguments

Math::vec3 getDirectionFromScreen ( int mouse_x, int mouse_y, int screen_x, int screen_y, int screen_width, int screen_height ) const#

Arguments

Return value

void setFov ( float fov ) #

Arguments

float getFov ( ) const#

Return value

void setObliqueFrustum ( bool frustum ) #

Arguments

bool isObliqueFrustum ( ) const#

Return value

void setObliqueFrustumPlane ( const Math::Vec4 & plane ) #

Arguments

Math::Vec4 getObliqueFrustumPlane ( ) const#

Return value

void setProjection ( const Math::mat4 & projection ) #

Arguments

Math::mat4 getProjection ( ) const#

Return value

Math::mat4 getProjectionFromScreen ( int x0, int y0, int x1, int y1, int screen_width, int screen_height ) const#

Arguments

Return value

void setReflectionViewportMask ( int mask ) #

Arguments

int getReflectionViewportMask ( ) const#

Return value

void setReverbMask ( int mask ) #

Arguments

int getReverbMask ( ) const#

Return value

int getScreenPosition ( int & x, int & y, const Math::Vec3 & point, int screen_width, int screen_height ) const#

Arguments

Return value

void setSourceMask ( int mask ) #

Arguments

int getSourceMask ( ) const#

Return value

void setUp ( const Math::vec3 & up ) #

Arguments

Math::vec3 getUp ( ) const#

Return value

void setVelocity ( const Math::vec3 & velocity ) #

Arguments

Math::vec3 getVelocity ( ) const#

Return value

void setViewDirection ( const Math::vec3 & direction ) #

Arguments

Math::vec3 getViewDirection ( ) const#

Return value

void setViewportMask ( int mask ) #

Arguments

int getViewportMask ( ) const#

Return value

void setZFar ( float zfar ) #

Arguments

float getZFar ( ) const#

Return value