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 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
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.
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 recently create Player.
- Clear the pointer to the PlayerSpectator to avoid memory leaks.
Here the necessary parts of code:
Source code (C++)
#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->setNodeWorldPosition(Math::dvec3(-1.6f, -1.7f, 1.7f));
// cast PlayerSpectator to Player
PlayerPtr player = playerSpectator->getPlayer();
// set the Player to the Game singleton instance
Game::get()->setPlayer(player);
return 1;
}
/* ... */
int AppWorldLogic::shutdown() {
// clear the pointer to Player
playerSpectator.clear();
return 1;
}Player Class
Members
Ptr<Player> cast(const Ptr<Node> & node)
Casts a Player out of the Node instance.Arguments
- const Ptr<Node> & node - Pointer to Node.
Return value
Pointer to Player.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)
Arguments
- Math::Vec3 & p0
- Math::Vec3 & p1
- int x
- int y
- int width
- int height
Math::vec3 getDirectionFromScreen(int x = -1, int y = -1, int width = -1, int height = -1)
Arguments
- int x
- int y
- int width
- int height
void setFov(float fov)
Sets a field of view of the player. The default is 60 degrees.Arguments
- float fov - Field of view in degrees. The provided value will be saturated in the range [0; 180].
float getFov()
Returns the current field of view of the player. The default is 60 degrees.Return value
Current field of view in degrees.Ptr<Player> getPlayer()
Returns a player pointer.Return value
The player pointer.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)
Sets a projection matrix.Arguments
- const Math::mat4 & projection - New projection matrix.
Math::mat4 getProjection()
Returns the current projection matrix.Return value
Current projection matrix.Math::mat4 getProjectionFromScreen(int x0, int y0, int x1, int y1, int width = -1, int height = -1)
Arguments
- int x0
- int y0
- int x1
- int y1
- int width
- int height
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 - Reflection 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 - 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)
Arguments
- int & x
- int & y
- const Math::Vec3 & point
- int width
- int height
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 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
- 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.
const 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.
Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)