Player Class
| 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.
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 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
Positive number if player controls are disabled; otherwise, 0.void setControls(Controls controls)
Sets a Controls object 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 object that holds settings of input controls relevant to the player.Return value
Controls object used to handle input controls.void setFov(float fov)
Sets a vertical field of view of the player. (Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.)Arguments
- float fov - New vertical field of view in degrees. The provided value will be saturated in the range [0; 180].
float getFov()
Returns the current vertical field of view of the player. (Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.)Return value
Vertical field of view in 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 (UnigineScript)
/* .. */
int 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 = engine.game.getTime();
// initializing a plane to be set as a near clipping plane
Vec4 plane = Vec4(1.0f, 1.0f, 1.0f, 1.0f + sin(time) * 4.0f);
// getting a player
Player player = engine.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
- 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 post postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.They are used after engine.render.setPostMaterials(), if any.
Arguments
- string materials - List of comma-separated postprocess materials names.
string getPostMaterials()
Returns names of the current post postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.They are used after engine.render.getPostMaterials(), if any.
Return value
Name of the current post postprocess materials.void setProjection(mat4 projection)
Updates the current projection matrix.Notice
It is not recommended to use this method for setting obliqueness of the near clipping plane of the frustum, as in this case a number of features (such as clouds, shadows, TAA, a number of engine optimizations, etc.) will not function properly. Please, use the setObliqueFrustum() method instead.
Arguments
- mat4 projection - New projection matrix.
mat4 getProjection()
Returns the current projection matrix with unit (1.0) aspect ratio.Return value
Current projection matrix.void setReflectionMask(int mask)
Sets a bit mask for rendering reflections into the viewport. Reflections are rendered in the viewport if masks of reflective materials match this one.Arguments
- int mask - Integer, each bit of which is a mask.
int getReflectionMask()
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.Return value
Integer, each bit of which is a mask.void setReverbMask(int mask)
Updates a bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match 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
Integer, each bit of which is a mask for reverberating sound sources and reverberation zones.void setSourceMask(int mask)
Updates a bit mask that determines what sound sources can be heard. For a sound source to be heard, its mask should match 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 a bit mask that determines what sound channels 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
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).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
- 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 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
- vec3 velocity - New velocity in units per second.
vec3 getVelocity()
Returns a player's velocity.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 bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport mask matches the player's one (one matching bit is enough).Arguments
- int mask - Integer, each bit of which is a mask.
int getViewportMask()
Returns the current bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport mask matches the player's one (one matching bit is enough).Return value
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.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.Return value
Distance in units.void setZNear(float znear)
Sets a distance to the near clipping plane of the player's viewing frustum.Arguments
- float znear - New distance in units. If a negative value is provided, 0 will be used instead.
float getZNear()
Returns the current distance to the near clipping plane of the player's viewing frustum.Return value
Distance 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-12-21
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)