Create a new CameraComponent instance.
The ComponentSystem that created this Component.
The Entity that this Component is attached to.
Private
_cameraPrivate
_disableLayer id at which the postprocessing stops for the camera.
Private
_priorityPrivate
_renderA counter of requests of color map rendering.
Private
_renderA counter of requests of depth map rendering.
Private
_scenePrivate
_sceneThe Entity that this Component is attached to.
Custom function that is called after the camera renders the scene.
Custom function that is called before the camera renders the scene.
The ComponentSystem used to create this Component.
Set camera aperture in f-stops, the default value is 16.0. Higher value means less exposure.
The aspect ratio (width divided by height) of the camera. If aspectRatioMode is ASPECT_AUTO, then this value will be automatically calculated every frame, and you can only read it. If it's ASPECT_MANUAL, you can set the value.
The aspect ratio mode of the camera. Can be:
Defaults to ASPECT_AUTO.
Custom function you can provide to calculate the camera projection matrix manually. Can be used for complex effects like doing oblique projection. Function is called using component's scope. Arguments:
Left and right are only used in stereo rendering.
Custom function you can provide to calculate the camera transformation matrix manually. Can be used for complex effects like reflections. Function is called using component's scope. Arguments:
Left and right are only used in stereo rendering.
If true the camera will clear the color buffer to the color set in clearColor. Defaults to true.
If true the camera will clear the depth buffer. Defaults to true.
If true the camera will clear the stencil buffer. Defaults to true.
If true the camera will take material.cull into account. Otherwise both front and back faces will be rendered. Defaults to true.
Layer ID of a layer on which the postprocessing of the camera stops being applied to. Defaults to LAYERID_UI, which causes post processing to not be applied to UI layer and any following layers for the camera. Set to undefined for post-processing to be applied to all layers of the camera.
Enables or disables the component.
The distance from the camera after which no rendering will take place. Defaults to 1000.
If true the camera will invert front and back faces. Can be useful for reflection rendering. Defaults to false.
The field of view of the camera in degrees. Usually this is the Y-axis field of view, see CameraComponent#horizontalFov. Used for PROJECTION_PERSPECTIVE cameras only. Defaults to 45.
Controls the culling of mesh instances against the camera frustum, i.e. if objects outside of camera should be omitted from rendering. If false, all mesh instances in the scene are rendered by the camera, regardless of visibility. Defaults to false.
Set which axis to use for the Field of View calculation. Defaults to false.
A jitter intensity applied in the projection matrix. Used for jittered sampling by TAA. A value of 1 represents a jitter in the range of [-1 to 1] of a pixel. Smaller values result in a crisper yet more aliased outcome, whereas increased values produce smoother but blurred result. Defaults to 0, representing no jitter.
An array of layer IDs (Layer#id) to which this camera should belong. Don't push, pop, splice or modify this array, if you want to change it, set a new one instead. Defaults to [LAYERID_WORLD, LAYERID_DEPTH, LAYERID_SKYBOX, LAYERID_UI, LAYERID_IMMEDIATE].
The distance from the camera before which no rendering will take place. Defaults to 0.1.
The half-height of the orthographic view window (in the Y-axis). Used for PROJECTION_ORTHOGRAPHIC cameras only. Defaults to 10.
The post effects queue for this camera. Use this to add or remove post effects from the camera.
Controls the order in which cameras are rendered. Cameras with smaller values for priority are rendered first. Defaults to 0.
The type of projection used to render the camera. Can be:
Defaults to PROJECTION_PERSPECTIVE.
Render target to which rendering of the cameras is performed. If not set, it will render simply to the screen.
Set camera sensitivity in ISO, the default value is 1000. Higher value means more exposure.
Set camera shutter speed in seconds, the default value is 1/1000s. Longer shutter means more exposure.
Private
_enablePrivate
Based on the value, the depth layer's enable counter is incremented or decremented.
True to increment the counter, false to decrement it.
True if the counter was incremented or decremented, false if the depth layer is not present.
Private
addCalculates aspect ratio value for a given render target.
Optional
rt: RenderTargetOptional render target. If unspecified, the backbuffer is used.
The aspect ratio of the render target (or backbuffer).
Attempt to end XR session of this camera.
Optional
callback: XrErrorCallbackOptional callback function called once session is ended. The callback has one argument Error - it is null if successfully ended XR session.
// On an entity with a camera component
this.entity.camera.endXr(function (err) {
// not anymore in XR
});
Fire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optional
arg1: anyFirst argument that is passed to the event handler.
Optional
arg2: anySecond argument that is passed to the event handler.
Optional
arg3: anyThird argument that is passed to the event handler.
Optional
arg4: anyFourth argument that is passed to the event handler.
Optional
arg5: anyFifth argument that is passed to the event handler.
Optional
arg6: anySixth argument that is passed to the event handler.
Optional
arg7: anySeventh argument that is passed to the event handler.
Optional
arg8: anyEighth argument that is passed to the event handler.
Self for chaining.
obj.fire('test', 'This is the message');
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Optional
name: stringName of the event to unbind.
Optional
callback: HandleEventCallbackFunction to be unbound.
Optional
scope: objectScope that was used as the this when the event is fired.
Self for chaining.
const handler = function () {
};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional
scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
Can be used for removing event in the future.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
const evt = obj.on('test', function (a, b) {
console.log(a + b);
});
// some time later
evt.off();
Private
onPrivate
The layer to add the camera to.
Private
onPrivate
The layer to remove the camera from.
Private
onPrivate
Old layer composition.
New layer composition.
Attach an event handler to an event. This handler will be removed after being fired once.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional
scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
obj.once('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled
Private
removeRequest the scene to generate a texture containing the scene color map. Note that this call is accumulative, and for each enable request, a disable request need to be called.
True to request the generation, false to disable it.
Request the scene to generate a texture containing the scene depth map. Note that this call is accumulative, and for each enable request, a disable request need to be called.
True to request the generation, false to disable it.
Convert a point from 2D screen space to 3D world space.
X coordinate on PlayCanvas' canvas element. Should be in the range
0 to canvas.offsetWidth
of the application's canvas element.
Y coordinate on PlayCanvas' canvas element. Should be in the range
0 to canvas.offsetHeight
of the application's canvas element.
The distance from the camera in world space to create the new point.
Optional
worldCoord: Vec33D vector to receive world coordinate result.
The world space coordinate.
// Get the start and end points of a 3D ray fired from a screen click position
const start = entity.camera.screenToWorld(clickX, clickY, entity.camera.nearClip);
const end = entity.camera.screenToWorld(clickX, clickY, entity.camera.farClip);
// Use the ray coordinates to perform a raycast
app.systems.rigidbody.raycastFirst(start, end, function (result) {
console.log("Entity " + result.entity.name + " was selected");
});
Sets the name of the shader pass the camera will use when rendering.
In addition to existing names (see the parameter description), a new name can be specified, which creates a new shader pass with the given name. The name provided can only use alphanumeric characters and underscores. When a shader is compiled for the new pass, a define is added to the shader. For example, if the name is 'custom_rendering', the define 'CUSTOM_RENDERING_PASS' is added to the shader, allowing the shader code to conditionally execute code only when that shader pass is active.
Another instance where this approach may prove useful is when a camera needs to render a more cost-effective version of shaders, such as when creating a reflection texture. To accomplish this, a callback on the material that triggers during shader compilation can be used. This callback can modify the shader generation options specifically for this shader pass.
const shaderPassId = camera.setShaderPass('custom_rendering');
material.onUpdateShader = function (options) {
if (options.pass === shaderPassId) {
options.litOptions.normalMapEnabled = false;
options.litOptions.useSpecular = false;
}
return options;
};
The name of the shader pass. Defaults to undefined, which is equivalent to SHADERPASS_FORWARD. Can be:
The id of the shader pass.
Attempt to start XR session with this camera.
The type of session. Can be one of the following:
Reference space type. Can be one of the following:
Optional
options: { Object with options for XR session initialization.
Optional boolean to attempt to enable XrAnchors.
Optional callback function called once the session is started. The callback has one argument Error - it is null if the XR session started successfully.
Optional object with depth sensing parameters to attempt to enable XrDepthSensing.
Set to true to attempt to enable XrImageTracking.
Optional features for XRSession start. It is used for getting access to additional WebXR spec extensions.
Set to true to attempt to enable XrPlaneDetection.
// On an entity with a camera component
this.entity.camera.startXr(pc.XRTYPE_VR, pc.XRSPACE_LOCAL, {
callback: function (err) {
if (err) {
// failed to start XR session
} else {
// in XR
}
}
});
The Camera Component enables an Entity to render the scene. A scene requires at least one enabled camera component to be rendered. Note that multiple camera components can be enabled simultaneously (for split-screen or offscreen rendering, for example).