Class: CameraComponent

pc.CameraComponent

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).

Constructor

new CameraComponent(system, entity)

Create a new Camera Component.
Parameters:
Name Type Description
system pc.CameraComponentSystem The ComponentSystem that created this Component.
entity pc.Entity The Entity that this Component is attached to.
Properties:
Name Type Description
projection Number The type of projection used to render the camera. Can be: Defaults to pc.PROJECTION_PERSPECTIVE.
nearClip Number The distance from the camera before which no rendering will take place.
farClip Number The distance from the camera after which no rendering will take place.
aspectRatioMode Number The aspect ratio mode of the camera. Can be pc.ASPECT_AUTO (default) or pc.ASPECT_MANUAL. ASPECT_AUTO will always be current render target's width divided by height. ASPECT_MANUAL will use the aspectRatio value instead.
aspectRatio Number 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.
horizontalFov Boolean Set which axis to use for the Field of View calculation. Defaults to false (use Y-axis).
fov Number The field of view of the camera in degrees. Usually this is the Y-axis field of view, see pc.CameraComponent#horizontalFov. Used for pc.PROJECTION_PERSPECTIVE cameras only. Defaults to 45.
orthoHeight Number The half-height of the orthographic view window (in the Y-axis). Used for pc.PROJECTION_ORTHOGRAPHIC cameras only. Defaults to 10.
priority Number Controls the order in which cameras are rendered. Cameras with smaller values for priority are rendered first.
clearColor pc.Color The color used to clear the canvas to before the camera starts to render.
clearColorBuffer Boolean If true the camera will clear the color buffer to the color set in clearColor.
clearDepthBuffer Boolean If true the camera will clear the depth buffer.
clearStencilBuffer Boolean If true the camera will clear the stencil buffer.
rect pc.Vec4 Controls where on the screen the camera will be rendered in normalized screen coordinates.
scissorRect pc.Vec4 Clips all pixels which are not in the rectangle. The order of the values is [x, y, width, height].
postEffects pc.PostEffectQueue The post effects queue for this camera. Use this to add or remove post effects from the camera.
frustumCulling Boolean Controls the culling of mesh instances against the camera frustum, i.e. if objects outside of camera should be omitted from rendering. If true, culling is enabled. If false, all mesh instances in the scene are rendered by the camera, regardless of visibility. Defaults to false.
calculateTransform function 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:
  • {pc.Mat4} transformMatrix: output of the function
  • {Number} view: Type of view. Can be pc.VIEW_CENTER, pc.VIEW_LEFT or pc.VIEW_RIGHT. Left and right are only used in stereo rendering.
  • calculateProjection function 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:
  • {pc.Mat4} transformMatrix: output of the function
  • {Number} view: Type of view. Can be pc.VIEW_CENTER, pc.VIEW_LEFT or pc.VIEW_RIGHT. Left and right are only used in stereo rendering.
  • cullFaces Boolean If true the camera will take material.cull into account. Otherwise both front and back faces will be rendered.
    flipFaces Boolean If true the camera will invert front and back faces. Can be useful for reflection rendering.
    layers Array An array of layer IDs (pc.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.
    Source:
    Examples
    // 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;

    Extends

    Members

    (readonly) frustum :pc.Frustum

    Queries the camera's frustum shape.
    Type:
    Source:

    (readonly) node :pc.GraphNode

    Queries the camera's GraphNode. Can be used to get position and rotation.
    Type:
    Source:

    (readonly) projectionMatrix :pc.Mat4

    Queries the camera's projection matrix.
    Type:
    Source:

    (readonly) viewMatrix :pc.Mat4

    Queries the camera's view matrix.
    Type:
    Source:

    vrDisplay :pc.VrDisplay

    The pc.VrDisplay that the camera is current displaying to. This is set automatically by calls to pc.CameraComponent#enterVr or pc.CameraComponent#exitVr. Setting this property to a display directly enables the camera to use the transformation information from a display without rendering stereo to it, e.g. for "magic window" style experiences.
    Type:
    Source:
    Example
    // enable magic window style interface
    var display = this.app.vr.display;
    if (display) {
        this.entity.camera.vrDisplay = display;
    }
    
    var camera = this.entity.camera;
    camera.enterVr(function (err) {
    if (err) { return; }
        var display = camera.vrDisplay; // access presenting pc.VrDisplay
    });

    Methods

    calculateAspectRatio(rtopt) → {Number}

    Calculates aspect ratio value for a given render target.
    Parameters:
    Name Type Attributes Description
    rt pc.RenderTarget <optional>
    Optional render target. If unspecified, the backbuffer is assumed.
    Source:
    Returns:
    The aspect ratio of the render target (or backbuffer).
    Type
    Number

    enterVr(displayopt, callback)

    Attempt to start presenting this camera to a pc.VrDisplay.
    Parameters:
    Name Type Attributes Description
    display pc.VrDisplay <optional>
    The VrDisplay to present. If not supplied this uses pc.VrManager#display as the default
    callback function Function called once to indicate success of failure. The callback takes one argument (err). On success it returns null on failure it returns the error message.
    Source:
    Example
    // On an entity with a camera component
    this.entity.camera.enterVr(function (err) {
        if (err) {
            console.error(err);
            return;
        } else {
            // in VR!
        }
    });

    exitVr(callback)

    Attempt to stop presenting this camera.
    Parameters:
    Name Type Description
    callback function Function called once to indicate success of failure. The callback takes one argument (err). On success it returns null on failure it returns the error message.
    Source:
    Example
    this.entity.camera.exitVr(function (err) {
        if (err) {
            console.error(err);
        } else {
    
        }
    });

    (private) frameBegin(rt)

    Start rendering the frame for this camera.
    Parameters:
    Name Type Description
    rt pc.RenderTarget Render target to which rendering will be performed. Will affect camera's aspect ratio, if aspectRatioMode is pc.ASPECT_AUTO.
    Source:

    (private) frameEnd()

    End rendering the frame for this camera
    Source:

    screenToWorld(screenx, screeny, cameraz, worldCoordopt) → {pc.Vec3}

    Convert a point from 2D screen space to 3D world space.
    Parameters:
    Name Type Attributes Description
    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 pc.Vec3 <optional>
    3D vector to receive world coordinate result.
    Source:
    Returns:
    The world space coordinate.
    Type
    pc.Vec3
    Example
    // 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");
    });

    worldToScreen(worldCoord, screenCoordopt) → {pc.Vec3}

    Convert a point from 3D world space to 2D screen space.
    Parameters:
    Name Type Attributes Description
    worldCoord pc.Vec3 The world space coordinate.
    screenCoord pc.Vec3 <optional>
    3D vector to receive screen coordinate result.
    Source:
    Returns:
    The screen space coordinate.
    Type
    pc.Vec3