API Reference

Class List

pc.CameraComponent

Extends: pc.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

aspectRatioThe aspect ratio (width divided by height) of the camera.
aspectRatioModeThe aspect ratio mode of the camera.
calculateProjectionCustom function you can provide to calculate the camera projection matrix manually.
calculateTransformCustom function you can provide to calculate the camera transformation matrix manually.
clearColorThe color used to clear the canvas to before the camera starts to render.
clearColorBufferIf true the camera will clear the color buffer to the color set in clearColor.
clearDepthBufferIf true the camera will clear the depth buffer.
clearStencilBufferIf true the camera will clear the stencil buffer.
cullFacesIf true the camera will take material.
farClipThe distance from the camera after which no rendering will take place.
flipFacesIf true the camera will invert front and back faces.
fovThe field of view of the camera in degrees.
frustumQueries the camera's frustum shape.[read only]
frustumCullingControls the culling of mesh instances against the camera frustum, i.
horizontalFovSet which axis to use for the Field of View calculation.
layersAn array of layer IDs (pc.Layer#id) to which this camera should belong.
nearClipThe distance from the camera before which no rendering will take place.
nodeQueries the camera's GraphNode.[read only]
orthoHeightThe half-height of the orthographic view window (in the Y-axis).
postEffectsThe post effects queue for this camera.
priorityControls the order in which cameras are rendered.
projectionThe type of projection used to render the camera.
projectionMatrixQueries the camera's projection matrix.[read only]
rectControls where on the screen the camera will be rendered in normalized screen coordinates.
scissorRectClips all pixels which are not in the rectangle.
viewMatrixQueries the camera's view matrix.[read only]
vrDisplayThe pc.VrDisplay that the camera is current displaying to.

Methods

calculateAspectRatioCalculates aspect ratio value for a given render target.
enterVrAttempt to start presenting this camera to a pc.VrDisplay.
enterVrAttempt to start presenting this camera to a pc.VrDisplay.
exitVrAttempt to stop presenting this camera.
screenToWorldConvert a point from 2D screen space to 3D world space.
worldToScreenConvert a point from 3D world space to 2D screen space.

Inherited

Properties

systemThe ComponentSystem used to create this Component
entityThe Entity that this Component is attached to
enabledEnables or disables the component.

Methods

fireFire an event, all additional arguments are passed on to the event listener
hasEventTest if there are any handlers bound to an event name
offDetach an event handler from an event.
onAttach an event handler to an event
onceAttach an event handler to an event.

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

systempc.CameraComponentSystemThe ComponentSystem that created this Component.
entitypc.EntityThe Entity that this Component is attached to.

Properties

NumberaspectRatio

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.

NumberaspectRatioMode

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.

pc.callbacks.CalculateMatrixcalculateProjection

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.
  • pc.callbacks.CalculateMatrixcalculateTransform

    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.
  • pc.ColorclearColor

    The color used to clear the canvas to before the camera starts to render.

    BooleanclearColorBuffer

    If true the camera will clear the color buffer to the color set in clearColor.

    BooleanclearDepthBuffer

    If true the camera will clear the depth buffer.

    BooleanclearStencilBuffer

    If true the camera will clear the stencil buffer.

    BooleancullFaces

    If true the camera will take material.cull into account. Otherwise both front and back faces will be rendered.

    NumberfarClip

    The distance from the camera after which no rendering will take place.

    BooleanflipFaces

    If true the camera will invert front and back faces. Can be useful for reflection rendering.

    Numberfov

    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.

    pc.Frustumfrustum

    Queries the camera's frustum shape.[read only]

    BooleanfrustumCulling

    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.

    BooleanhorizontalFov

    Set which axis to use for the Field of View calculation. Defaults to false (use Y-axis).

    Number[]layers

    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.

    NumbernearClip

    The distance from the camera before which no rendering will take place.

    pc.GraphNodenode

    Queries the camera's GraphNode. Can be used to get position and rotation.[read only]

    NumberorthoHeight

    The half-height of the orthographic view window (in the Y-axis). Used for pc.PROJECTION_ORTHOGRAPHIC cameras only. Defaults to 10.

    pc.PostEffectQueuepostEffects

    The post effects queue for this camera. Use this to add or remove post effects from the camera.

    Numberpriority

    Controls the order in which cameras are rendered. Cameras with smaller values for priority are rendered first.

    Numberprojection

    The type of projection used to render the camera. Can be:

    Defaults to pc.PROJECTION_PERSPECTIVE.

    pc.Mat4projectionMatrix

    Queries the camera's projection matrix.[read only]

    pc.Vec4rect

    Controls where on the screen the camera will be rendered in normalized screen coordinates.

    pc.Vec4scissorRect

    Clips all pixels which are not in the rectangle. The order of the values is [x, y, width, height].

    pc.Mat4viewMatrix

    Queries the camera's view matrix.[read only]

    pc.VrDisplayvrDisplay

    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.

    // 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([rt])

    Calculates aspect ratio value for a given render target.

    Parameters

    rtpc.RenderTargetOptional render target. If unspecified, the backbuffer is assumed.

    Returns

    Number The aspect ratio of the render target (or backbuffer).

    enterVr(callback)

    Attempt to start presenting this camera to a pc.VrDisplay.

    // On an entity with a camera component
    this.entity.camera.enterVr(function (err) {
        if (err) {
            console.error(err);
            return;
        } else {
            // in VR!
        }
    });
             

    Parameters

    callbackpc.callbacks.VrCameraFunction 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.

    enterVr(display, callback)

    Attempt to start presenting this camera to a pc.VrDisplay.

    // On an entity with a camera component
    this.entity.camera.enterVr(function (err) {
        if (err) {
            console.error(err);
            return;
        } else {
            // in VR!
        }
    });

    Parameters

    displaypc.VrDisplayThe VrDisplay to present. If not supplied this uses pc.VrManager#display as the default
    callbackpc.callbacks.VrCameraFunction 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.

    exitVr(callback)

    Attempt to stop presenting this camera.

    this.entity.camera.exitVr(function (err) {
        if (err) {
            console.error(err);
        } else {
    
        }
    });

    Parameters

    callbackpc.callbacks.VrCameraFunction 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.

    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

    screenxNumberx coordinate on PlayCanvas' canvas element.
    screenyNumbery coordinate on PlayCanvas' canvas element.
    camerazNumberThe distance from the camera in world space to create the new point.
    worldCoordpc.Vec33D vector to receive world coordinate result.

    Returns

    pc.Vec3 The world space coordinate.

    worldToScreen(worldCoord, [screenCoord])

    Convert a point from 3D world space to 2D screen space.

    Parameters

    worldCoordpc.Vec3The world space coordinate.
    screenCoordpc.Vec33D vector to receive screen coordinate result.

    Returns

    pc.Vec3 The screen space coordinate.

    Inherited

    Properties

    pc.ComponentSystemsystem

    The ComponentSystem used to create this Component

    pc.Entityentity

    The Entity that this Component is attached to

    Booleanenabled

    Enables or disables the component.

    Methods

    fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

    Fire an event, all additional arguments are passed on to the event listener

    obj.fire('test', 'This is the message');

    Parameters

    nameObjectName of event to fire
    arg1*First argument that is passed to the event handler
    arg2*Second argument that is passed to the event handler
    arg3*Third argument that is passed to the event handler
    arg4*Fourth argument that is passed to the event handler
    arg5*Fifth argument that is passed to the event handler
    arg6*Sixth argument that is passed to the event handler
    arg7*Seventh argument that is passed to the event handler
    arg8*Eighth argument that is passed to the event handler

    Returns

    pc.EventHandler Self for chaining.

    hasEvent(name)

    Test if there are any handlers bound to an event name

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

    Parameters

    nameStringThe name of the event to test

    Returns

    Boolean true if the object has handlers bound to the specified event name.

    off([name], [callback], [scope])

    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.

    var 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 hander functions, called 'test' with scope this

    Parameters

    nameStringName of the event to unbind
    callbackpc.callbacks.HandleEventFunction to be unbound.
    scopeObjectScope that was used as the this when the event is fired

    Returns

    pc.EventHandler Self for chaining.

    on(name, callback, [scope])

    Attach an event handler to an event

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Parameters

    nameStringName of the event to bind the callback to
    callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
    scopeObjectObject to use as 'this' when the event is fired, defaults to current this

    Returns

    pc.EventHandler Self for chaining.

    once(name, callback, [scope])

    Attach an event handler to an event. This handler will be removed after being fired once.

    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

    Parameters

    nameStringName of the event to bind the callback to
    callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
    scopeObjectObject to use as 'this' when the event is fired, defaults to current this

    Returns

    pc.EventHandler Self for chaining.