Unigine::Player Class
Header: | #include <UniginePlayers.h> |
Inherits: | Node |
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 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
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:
// AppWorldLogic.cpp
/* ... */
#include <UniginePlayers.h>
#include <UnigineGame.h>
// inject Unigine namespace names to global namespace
using namespace Unigine;
/* ... */
// ortho flag - change this value to switch projection type
int ortho = 0;
int AppWorldLogic::init() {
// 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;
if (ortho)
{
// setting up orthographic projection
player->setProjection(Math::ortho(-1.0f, 1.0f, -1.0f, 1.0f, znear, zfar));
}
else
{
// setting up perspective projection
player->setProjection(Math::perspective(60.0f, aspect, znear, zfar));
}
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:
|
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:
|
Camera Direction Vectors
|
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 * 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.
#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:
#include "AppWorldLogic.h"
#include "UnigineGame.h"
// inject Unigine namespace names to global namespace
using namespace Unigine;
/* ... */
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::dvec3(-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;
}
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 ( ) #
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 to disable the player controls (player stops responding to them), 0 to enable the controls.
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 ( const Ptr<Controls> & controls ) #
Sets a Controls smart pointer that will hold settings of input controls relevant to the player.Arguments
- const Ptr<Controls> & controls - Controls smart pointer used to handle input controls.
Ptr<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 ( Math::Vec3 & p0, Math::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.// get the current player (camera)
PlayerPtr player = Game::getPlayer();
if (player.get() == NULL)
return 0;
// get width and height of the current application window
int width = App::getWidth();
int height = App::getHeight();
// get the current X and Y coordinates of the mouse pointer
int mouse_x = App::getMouseX();
int mouse_y = App::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, width, height);
Arguments
- Math::Vec3 & p0 - Start coordinates of the ray.
- Math::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.
Math::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.// 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::getMouseX(), App::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.
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.
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 frustum ) #
Enables or disables obliqueness of the viewing frustum.Arguments
- int frustum - 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 ( const Math::Vec4 & plane ) #
Sets the oblique near clipping plane of the viewing frustum.// AppWorldLogic.cpp
#include <UnigineGame.h>
using namespace Unigine;
/* .. */
int AppWorldLogic::update() {
// Write here code to be called before updating each render frame: specify all graphics-related functions you want to be called every frame while your application executes.
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 != NULL)
{
// 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 ( ) #
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 setPostMaterials ( const char * materials ) #
Sets postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.Arguments
- const char * materials - Comma-separated list of names of postprocess materials.
const char * 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 ( const Math::mat4 & projection ) #
Updates the current projection matrix.Arguments
- const Math::mat4 & projection - New projection matrix.
Math::mat4 getProjection ( ) #
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 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 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 ( ) #
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 ( ) #
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 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
- int & x - X-coordinate of the screen position.
- int & y - Y-coordinate of the screen position.
- const Math::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 - Source 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 ( const Math::vec3 & up ) #
Sets an up direction of the player's viewport (i.e. tilt of the player's viewport).Arguments
- const Math::vec3 & up - New upward direction vector. The vector is normalized to 1.
Math::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 ( const Math::vec3 & velocity ) #
Sets a player's velocity.Arguments
- const Math::vec3 & velocity - New velocity in units per second.
Math::vec3 getVelocity ( ) #
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 ( ) #
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 ( ) #
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 ( ) #
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 ( ) #
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.Math::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.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.Arguments
- const Ptr<Material> & material - Scriptable material to be attached to the player.
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 ( ) #
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 ) #
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.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).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 ) #
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, int 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.
- int enabled - 1 to enable the scriptable material with the specified number, 0 to disable it.
int getScriptableMaterialEnabled ( int num ) #
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
1 if the scriptable material with the specified number is enabled; otherwise, 0.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.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 ( int player ) #
Sets a player as a main player.Arguments
- int player - Pointer to the player