CameraComponent
Extends: Component
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).
// Add a pc.CameraComponent to an entity
var entity = new pc.Entity();
entity.addComponent('camera', {
nearClip: 1,
farClip: 100,
fov: 55
});
// Get the pc.CameraComponent on an entity
var cameraComponent = entity.camera;
// Update a property on a camera component
entity.camera.nearClip = 2;
Summary
Properties
aspectRatio | The aspect ratio (width divided by height) of the camera. |
aspectRatioMode | The aspect ratio mode of the camera. |
calculateProjection | Custom function you can provide to calculate the camera projection matrix manually. |
calculateTransform | Custom function you can provide to calculate the camera transformation matrix manually. |
clearColor | The color used to clear the canvas to before the camera starts to render. |
clearColorBuffer | If true the camera will clear the color buffer to the color set in clearColor. |
clearDepthBuffer | If true the camera will clear the depth buffer. |
clearStencilBuffer | If true the camera will clear the stencil buffer. |
cullFaces | If true the camera will take material. |
disablePostEffectsLayer | Layer ID of a layer on which the postprocessing of the camera stops being applied to. |
farClip | The distance from the camera after which no rendering will take place. |
flipFaces | If true the camera will invert front and back faces. |
fov | The field of view of the camera in degrees. |
frustum | Queries the camera's frustum shape.[read only] |
frustumCulling | Controls the culling of mesh instances against the camera frustum, i. |
horizontalFov | Set which axis to use for the Field of View calculation. |
layers | An array of layer IDs (Layer#id) to which this camera should belong. |
nearClip | The distance from the camera before which no rendering will take place. |
orthoHeight | The half-height of the orthographic view window (in the Y-axis). |
postEffects | The post effects queue for this camera. |
priority | Controls the order in which cameras are rendered. |
projection | The type of projection used to render the camera. |
projectionMatrix | Queries the camera's projection matrix.[read only] |
rect | Controls where on the screen the camera will be rendered in normalized screen coordinates. |
renderTarget | Render target to which rendering of the cameras is performed. |
scissorRect | Clips all pixels which are not in the rectangle. |
viewMatrix | Queries the camera's view matrix.[read only] |
Methods
calculateAspectRatio | Calculates aspect ratio value for a given render target. |
endXr | Attempt to end XR session of this camera |
screenToWorld | Convert a point from 2D screen space to 3D world space. |
startXr | Attempt to start XR session with this camera |
worldToScreen | Convert a point from 3D world space to 2D screen space. |
Inherited
Properties
system | The ComponentSystem used to create this Component. |
entity | The Entity that this Component is attached to. |
enabled | Enables or disables the component. |
Details
Constructor
CameraComponent(system, entity)
Create a new Camera Component.
// Add a pc.CameraComponent to an entity
var entity = new pc.Entity();
entity.addComponent('camera', {
nearClip: 1,
farClip: 100,
fov: 55
});
// Get the pc.CameraComponent on an entity
var cameraComponent = entity.camera;
// Update a property on a camera component
entity.camera.nearClip = 2;
Parameters
system | CameraComponentSystem | The ComponentSystem that created this Component. |
entity | Entity | The Entity that this Component is attached to. |
Properties
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:
- ASPECT_AUTO: aspect ratio will be calculated from the current render target's width divided by height.
- ASPECT_MANUAL: use the aspectRatio value.
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:
- {Mat4} transformMatrix: output of the function
- {number} view: Type of view. Can be VIEW_CENTER, VIEW_LEFT or VIEW_RIGHT. 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:
- Mat4 transformMatrix: output of the function.
- {number} view: Type of view. Can be VIEW_CENTER, VIEW_LEFT or VIEW_RIGHT. Left and right are only used in stereo rendering.
The color used to clear the canvas to before the camera starts to render. Defaults to [0.75, 0.75, 0.75, 1].
If true the camera will clear the color buffer to the color set in clearColor. 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.
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.
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:
- PROJECTION_PERSPECTIVE: A perspective projection. The camera frustum resembles a truncated pyramid.
- PROJECTION_ORTHOGRAPHIC: An orthographic projection. The camera frustum is a cuboid.
Defaults to PROJECTION_PERSPECTIVE.
Controls where on the screen the camera will be rendered in normalized screen coordinates. Defaults to [0, 0, 1, 1].
Render target to which rendering of the cameras is performed. If not set, it will render simply to the screen.
Clips all pixels which are not in the rectangle. The order of the values is [x, y, width, height]. Defaults to [0, 0, 1, 1].
Methods
calculateAspectRatio([rt])
Calculates aspect ratio value for a given render target.
Parameters
rt | RenderTarget | Optional render target. If unspecified, the backbuffer is assumed. |
Returns
numberThe aspect ratio of the render target (or backbuffer).
endXr([callback])
Attempt to end XR session of this camera
// On an entity with a camera component
this.entity.camera.endXr(function (err) {
// not anymore in XR
});
Parameters
callback | callbacks.XrError | Optional callback function called once session is ended. The callback has one argument Error - it is null if successfully ended XR session. |
screenToWorld(screenx, screeny, cameraz, [worldCoord])
Convert a point from 2D screen space to 3D world space.
// Get the start and end points of a 3D ray fired from a screen click position
var start = entity.camera.screenToWorld(clickX, clickY, entity.camera.nearClip);
var 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");
});
Parameters
screenx | number | X coordinate on PlayCanvas' canvas element. |
screeny | number | Y coordinate on PlayCanvas' canvas element. |
cameraz | number | The distance from the camera in world space to create the new point. |
worldCoord | Vec3 | 3D vector to receive world coordinate result. |
Returns
Vec3The world space coordinate.
startXr(type, spaceType, [options])
Attempt to start XR session with this camera
// 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
}
}
});
Parameters
type | string | The type of session. Can be one of the following:
|
spaceType | string | reference space type. Can be one of the following:
|
options | object | object with options for XR session initialization. |
options.optionalFeatures | string[] | Optional features for XRSession start. It is used for getting access to additional WebXR spec extensions. |
options.callback | callbacks.XrError | Optional callback function called once the session is started. The callback has one argument Error - it is null if the XR session started successfully. |
worldToScreen(worldCoord, [screenCoord])
Convert a point from 3D world space to 2D screen space.
Parameters
worldCoord | Vec3 | The world space coordinate. |
screenCoord | Vec3 | 3D vector to receive screen coordinate result. |
Returns
Vec3The screen space coordinate.