Camera Class
Warning
UnigineScript is deprecated and will be removed in future releases. Please consider using C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt is not guaranteed, as the current level of support assumes only fixing critical issues.
The Camera class is used to create a new camera, set it up (set all the required matrices, field of view, masks and so on) and then pass it to an instance of the Viewport class to render an image from this camera.
Notice
An instance of this class is not a node.
A camera instance can have the following masks:
- Sound Source mask
- Sound Reverberation mask
- Viewport mask
- Reflection Viewport mask
Camera settings can be set up in the Camera Settings in UnigineEditor.
Camera Class
Members
static Camera ( ) #
Constructor. Creates a new camera with default settings:- Modelview, inverse modelview and offset matrices are 4×4 identity matrices.
- FOV is 60 degrees.
- Distance to the near clipping plane is 0.1 unit.
- Distance to the far clipping plane is 10000 units.
- Up direction vector is (0,0,1).
- Viewport, reflection, source and reverb masks are set to 00000001.
void setFov ( float fov ) #
Sets a vertical field of view of the camera and updates the projection matrix.
Notice
Horizontal 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].
float getFov ( ) #
Returns the current vertical field of view of the camera.
Notice
Horizontal 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.Mat4 getIModelview ( ) #
Returns the inverted view matrix of the camera.Return value
Inverse view matrix.void setModelview ( Mat4 modelview ) #
Updates a modelview and inverse modelview matrices for the camera.Arguments
- Mat4 modelview - New view matrix.
Mat4 getModelview ( ) #
Returns the current view matrix of the camera.Return value
Current view matrix.void setObliqueFrustum ( int 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
- 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 ( 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 (UnigineScript)
/* .. */
int update() {
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 and a camera
Player player = engine.game.getPlayer();
Camera camera = player.getCamera();
if (camera != NULL)
{
// enabling oblique frustum
camera.setObliqueFrustum(1);
// setting our plane as an oblique near clipping plane
camera.setObliqueFrustumPlane(plane);
}
player.setCamera(camera);
return 1;
}
/* .. */Arguments
- 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.
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 setOffset ( mat4 offset ) #
Sets an additional transformation (an offset matrix) for the camera. This transformation is applied after the modelview transformation. The offset matrix does not affect the view matrix or the position of the camera. For example, the offset matrix can be used to simulate camera shaking from an explosion.Arguments
- mat4 offset - Offset matrix.
mat4 getOffset ( ) #
Returns an additional transformation (an offset matrix) set for the camera. This transformation is applied after modelview transformation. The offset matrix does not affect the view matrix or the position of the camera. For example, it can be used to simulate camera shake from an explosion.Return value
Offset matrix.void setPosition ( Vec3 position ) #
Sets a new position of the camera and updates the modelview and inverse modelview (its 3rd column) matrices.Arguments
- Vec3 position - Camera position in the world space.
Vec3 getPosition ( ) #
Returns the current position of the camera. The position vector is stored in the 3rd column of the inverse view matrix.Return value
Camera position in the world space.void setPostMaterials ( string materials ) #
Sets post postprocess materials that are applied after all other postprocess are rendered. They are used after engine.render.setPostMaterials(), if any.Arguments
- string materials - Comma-separated names of postprocess materials.
string getPostMaterials ( ) #
Returns names of the current post postprocess materials that are applied after all other postprocess 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.
This method allows you to set your camera to use perspective or orthographic projection, depending on your project's requirements.
For example, you can use the following code to set up orthographic projection or perspective projection for your camera depending on a flag value:
Source code (UnigineScript)
// world.usc
Camera camera;
Player player;
/* ... */
// ortho flag - change this value to switch projection type
int ortho_flag = 0;
int init(){
/* ... */
// getting the camera of the current player
camera = engine.game.getPlayer().getCamera();
// 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_flag)
{
// setting up orthographic projection
camera.setProjection(ortho(-1.0f, 1.0f, -1.0f, 1.0f, znear, zfar));
}
else
{
// setting up perspective projection
camera.setProjection(perspective(60.0f, aspect, znear, zfar));
}
// setting player's camera
player = engine.game.getPlayer();
player.setCamera(camera);
return 1;
}Arguments
- mat4 projection - Projection matrix.
mat4 getProjection ( ) #
Returns the current projection matrix with unit (1.0) aspect ratio.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 - Integer, each bit of which is used to set a mask.
int getReflectionViewportMask ( ) #
Returns the current bit mask for rendering reflections into the camera viewport. Reflections are rendered in the camera viewport if masks of reflective materials match this one (one bit at least).Return value
Integer, each bit of which is used to set 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 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 the camera's one in several 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 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 camera's one in several bits, not necessarily one.Return value
Integer, each bit of which is used to set 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 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 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 camera's viewport (i.e. tilt of the camera's viewport).Arguments
- vec3 up - New upward direction vector. The vector is normalized to 1.
vec3 getUp ( ) #
Returns the current up direction of the camera's viewport (i.e. tilt of the camera's viewport).Return value
Upward 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 masks match the camera's one (one matching bit is enough).Arguments
- int mask - Integer, each bit of which is used to set 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 camera's one (one matching bit is enough).Return value
Integer, each bit of which is used to set a mask.void setZFar ( float zfar ) #
Sets a distance to the far clipping plane of the camera's viewing frustum and updates the projection matrix.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 camera's viewing frustum.Return value
Distance in units.void setZNear ( float znear ) #
Sets a distance to the near clipping plane of the camera's viewing frustum and updates the projection matrix.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 camera's viewing frustum.Return value
Distance in units.Camera clone ( ) #
Clones the current camera and saves it to the given camera instance.Return value
Copy of the camera.void setFovMode ( int mode ) #
Sets the value indicating the type of FOV that is used for the camera:- For the classic camera, the vertical FOV should be set. In this case, FOV is directly set in degrees.
- For the physically-based camera, the horizontal FOV should be set. In this case, FOV is calculated depending on the film gate and focal length of the camera.
Arguments
- int mode - FOV_MODE_VERTICAL for the camera with the vertical FOV; FOV_MODE_PHYSICALLY_BASED_CAMERA for the physically-based camera with the horizontal FOV.
int getFovMode ( ) #
Sets the value indicating the type of FOV that is used for the camera.Return value
0 if the camera with the vertical FOV is used; 1 if the physically-based camera 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 ( float aspect ) #
Returns projection matrix after correction for the specified aspect ratio. Currently fixed FOV component is taken into account.Arguments
- float aspect - Aspect ratio.
Return value
Projection matrix after correction for the specified aspect ratio.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 ( Material material ) #
Attaches a new scriptable material to the camera. 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 camera.Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-camera.
Arguments
- Material material - Scriptable material to be attached to the camera.
void removeScriptableMaterial ( int num ) #
Removes the scriptable material with the specified number from the camera.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 camera.Return value
Total number of scriptable materials attached to the camera.int findScriptableMaterial ( Material material ) #
Returns the number of the specified scriptable material for the camera. This number is camera-specific (valid for this camera 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-camera.
Arguments
- 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, 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 camera-specific (valid for this camera only).Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-camera.
Arguments
- int num - Scriptable material number in the range from 0 to the total number of scriptable materials.
- Material material - New scriptable material to replace the one with the specified number.
Material getScriptableMaterial ( int num ) #
Returns a scriptable material attached to the camera 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 camera 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 camera 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.Notice
The number is camera-specific (valid for this camera 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 camera.Last update:
2020-04-10
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)