docs.unity3d.com
    Show / Hide Table of Contents

    Class CinemachineVirtualCameraBase

    Base class for a Monobehaviour that represents a Virtual Camera within the Unity scene.

    This is intended to be attached to an empty Transform GameObject. Inherited classes can be either standalone virtual cameras such as CinemachineVirtualCamera, or meta-cameras such as CinemachineClearShot or CinemachineFreeLook.

    A CinemachineVirtualCameraBase exposes a Priority property. When the behaviour is enabled in the game, the Virtual Camera is automatically placed in a queue maintained by the static CinemachineCore singleton. The queue is sorted by priority. When a Unity camera is equipped with a CinemachineBrain behaviour, the brain will choose the camera at the head of the queue. If you have multiple Unity cameras with CinemachineBrain behaviours (say in a split-screen context), then you can filter the queue by setting the culling flags on the virtual cameras. The culling mask of the Unity Camera will then act as a filter for the brain. Apart from this, there is nothing that prevents a virtual camera from controlling multiple Unity cameras simultaneously.

    Inheritance
    Object
    CinemachineVirtualCameraBase
    CinemachineBlendListCamera
    CinemachineClearShot
    CinemachineExternalCamera
    CinemachineFreeLook
    CinemachineMixingCamera
    CinemachineStateDrivenCamera
    CinemachineVirtualCamera
    Namespace: Cinemachine
    Syntax
    public abstract class CinemachineVirtualCameraBase : MonoBehaviour, ICinemachineCamera

    Fields

    m_ExcludedPropertiesInInspector

    Inspector control - Use for hiding sections of the Inspector UI.

    Declaration
    public string[] m_ExcludedPropertiesInInspector
    Field Value
    Type Description
    String[]

    m_LockStageInInspector

    Inspector control - Use for enabling sections of the Inspector UI.

    Declaration
    public CinemachineCore.Stage[] m_LockStageInInspector
    Field Value
    Type Description
    CinemachineCore.Stage[]

    m_Priority

    The priority will determine which camera becomes active based on the state of other cameras and this camera. Higher numbers have greater priority.

    Declaration
    public int m_Priority
    Field Value
    Type Description
    Int32

    m_StandbyUpdate

    When the virtual camera is not live, this is how often the virtual camera will be updated. Set this to tune for performance. Most of the time Never is fine, unless the virtual camera is doing shot evaluation.

    Declaration
    public CinemachineVirtualCameraBase.StandbyUpdateMode m_StandbyUpdate
    Field Value
    Type Description
    CinemachineVirtualCameraBase.StandbyUpdateMode

    Properties

    Description

    Gets a brief debug description of this virtual camera, for use when displayiong debug info

    Declaration
    public virtual string Description { get; }
    Property Value
    Type Description
    String
    Implements
    ICinemachineCamera.Description

    Follow

    Get the Follow target for the Body component in the Cinemachine pipeline.

    Declaration
    public abstract Transform Follow { get; set; }
    Property Value
    Type Description
    Transform
    Implements
    ICinemachineCamera.Follow

    FollowTargetAttachment

    This must be set every frame at the start of the pipeline to relax the virtual camera's attachment to the target. Range is 0...1.
    1 is full attachment, and is the normal state. 0 is no attachment, and virtual camera will behave as if no Follow targets are set.

    Declaration
    public float FollowTargetAttachment { get; set; }
    Property Value
    Type Description
    Single

    IsValid

    Returns false if the object has been deleted

    Declaration
    public bool IsValid { get; }
    Property Value
    Type Description
    Boolean
    Implements
    ICinemachineCamera.IsValid

    LookAt

    Get the LookAt target for the Aim component in the Cinemachine pipeline.

    Declaration
    public abstract Transform LookAt { get; set; }
    Property Value
    Type Description
    Transform
    Implements
    ICinemachineCamera.LookAt

    LookAtTargetAttachment

    This must be set every frame at the start of the pipeline to relax the virtual camera's attachment to the target. Range is 0...1.
    1 is full attachment, and is the normal state. 0 is no attachment, and virtual camera will behave as if no LookAt targets are set.

    Declaration
    public float LookAtTargetAttachment { get; set; }
    Property Value
    Type Description
    Single

    Name

    Get the name of the Virtual Camera. Base implementation returns the owner GameObject's name.

    Declaration
    public string Name { get; }
    Property Value
    Type Description
    String
    Implements
    ICinemachineCamera.Name

    ParentCamera

    Support for meta-virtual-cameras. This is the situation where a virtual camera is in fact the public face of a private army of virtual cameras, which it manages on its own. This method gets the VirtualCamera owner, if any. Private armies are implemented as Transform children of the parent vcam.

    Declaration
    public ICinemachineCamera ParentCamera { get; }
    Property Value
    Type Description
    ICinemachineCamera
    Implements
    ICinemachineCamera.ParentCamera

    PreviousStateIsValid

    Set this to force the next update to ignore deltaTime and reset itself

    Declaration
    public virtual bool PreviousStateIsValid { get; set; }
    Property Value
    Type Description
    Boolean

    Priority

    Get the Priority of the virtual camera. This determines its placement in the CinemachineCore's queue of eligible shots.

    Declaration
    public int Priority { get; set; }
    Property Value
    Type Description
    Int32
    Implements
    ICinemachineCamera.Priority

    State

    The CameraState object holds all of the information necessary to position the Unity camera. It is the output of this class.

    Declaration
    public abstract CameraState State { get; }
    Property Value
    Type Description
    CameraState
    Implements
    ICinemachineCamera.State

    ValidatingStreamVersion

    Version that was last streamed, for upgrading legacy

    Declaration
    public int ValidatingStreamVersion { get; }
    Property Value
    Type Description
    Int32

    VirtualCameraGameObject

    The GameObject owner of the Virtual Camera behaviour.

    Declaration
    public GameObject VirtualCameraGameObject { get; }
    Property Value
    Type Description
    GameObject
    Implements
    ICinemachineCamera.VirtualCameraGameObject

    Methods

    AddExtension(CinemachineExtension)

    A delegate to hook into the state calculation pipeline. This will be called after each pipeline stage, to allow others to hook into the pipeline. See CinemachineCore.Stage.

    Declaration
    public virtual void AddExtension(CinemachineExtension extension)
    Parameters
    Type Name Description
    CinemachineExtension extension

    The extension to add.

    ApplyPositionBlendMethod(ref CameraState, CinemachineVirtualCameraBase.BlendHint)

    Applies a position blend hint to a camera state

    Declaration
    protected void ApplyPositionBlendMethod(ref CameraState state, CinemachineVirtualCameraBase.BlendHint hint)
    Parameters
    Type Name Description
    CameraState state

    The state to apply the hint to

    CinemachineVirtualCameraBase.BlendHint hint

    The hint to apply

    CreateBlend(ICinemachineCamera, ICinemachineCamera, CinemachineBlendDefinition, CinemachineBlend)

    Create a blend between 2 virtual cameras, taking into account any existing active blend, with special case handling if the new blend is effectively an undo of the current blend

    Declaration
    protected CinemachineBlend CreateBlend(ICinemachineCamera camA, ICinemachineCamera camB, CinemachineBlendDefinition blendDef, CinemachineBlend activeBlend)
    Parameters
    Type Name Description
    ICinemachineCamera camA

    Outgoing virtual camera

    ICinemachineCamera camB

    Incoming virtual camera

    CinemachineBlendDefinition blendDef

    Definition of the blend to create

    CinemachineBlend activeBlend

    The current active blend

    Returns
    Type Description
    CinemachineBlend

    The new blend

    DetachedFollowTargetDamp(Single, Single, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public float DetachedFollowTargetDamp(float initial, float dampTime, float deltaTime)
    Parameters
    Type Name Description
    Single initial

    The amount that will be damped

    Single dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Single

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    DetachedFollowTargetDamp(Vector3, Single, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public Vector3 DetachedFollowTargetDamp(Vector3 initial, float dampTime, float deltaTime)
    Parameters
    Type Name Description
    Vector3 initial

    The amount that will be damped

    Single dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Vector3

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    DetachedFollowTargetDamp(Vector3, Vector3, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public Vector3 DetachedFollowTargetDamp(Vector3 initial, Vector3 dampTime, float deltaTime)
    Parameters
    Type Name Description
    Vector3 initial

    The amount that will be damped

    Vector3 dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Vector3

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    DetachedLookAtTargetDamp(Single, Single, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public float DetachedLookAtTargetDamp(float initial, float dampTime, float deltaTime)
    Parameters
    Type Name Description
    Single initial

    The amount that will be damped

    Single dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Single

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    DetachedLookAtTargetDamp(Vector3, Single, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public Vector3 DetachedLookAtTargetDamp(Vector3 initial, float dampTime, float deltaTime)
    Parameters
    Type Name Description
    Vector3 initial

    The amount that will be damped

    Single dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Vector3

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    DetachedLookAtTargetDamp(Vector3, Vector3, Single)

    Get a damped version of a quantity. This is the portion of the quantity that will take effect over the given time. This method takes the target attachment into account. For general damping without consideration of target attachment, use Damper.Damp()

    Declaration
    public Vector3 DetachedLookAtTargetDamp(Vector3 initial, Vector3 dampTime, float deltaTime)
    Parameters
    Type Name Description
    Vector3 initial

    The amount that will be damped

    Vector3 dampTime

    The rate of damping. This is the time it would take to reduce the original amount to a negligible percentage

    Single deltaTime

    The time over which to damp

    Returns
    Type Description
    Vector3

    The damped amount. This will be the original amount scaled by a value between 0 and 1.

    ForceCameraPosition(Vector3, Quaternion)

    Force the virtual camera to assume a given position and orientation

    Declaration
    public virtual void ForceCameraPosition(Vector3 pos, Quaternion rot)
    Parameters
    Type Name Description
    Vector3 pos

    Worldspace pposition to take

    Quaternion rot

    Worldspace orientation to take

    GetInputAxisProvider()

    Locate the first component that implements AxisState.IInputAxisProvider.

    Declaration
    public AxisState.IInputAxisProvider GetInputAxisProvider()
    Returns
    Type Description
    AxisState.IInputAxisProvider

    The first AxisState.IInputAxisProvider or null if none

    GetMaxDampTime()

    Query components and extensions for the maximum damping time. Base class implementation queries extensions. Only used in editor for timeline scrubbing.

    Declaration
    public virtual float GetMaxDampTime()
    Returns
    Type Description
    Single

    Highest damping setting in this vcam

    InternalUpdateCameraState(Vector3, Single)

    Internal use only. Do not call this method. Called by CinemachineCore at designated update time so the vcam can position itself and track its targets. Do not call this method. Let the framework do it at the appropriate time

    Declaration
    public abstract void InternalUpdateCameraState(Vector3 worldUp, float deltaTime)
    Parameters
    Type Name Description
    Vector3 worldUp

    Default world Up, set by the CinemachineBrain

    Single deltaTime

    Delta time for time-based effects (ignore if less than 0)

    Implements
    ICinemachineCamera.InternalUpdateCameraState(Vector3, Single)

    InvokeOnTransitionInExtensions(ICinemachineCamera, Vector3, Single)

    Invokes the OnTransitionFromCamera for all extensions on this camera

    Declaration
    protected bool InvokeOnTransitionInExtensions(ICinemachineCamera fromCam, Vector3 worldUp, float deltaTime)
    Parameters
    Type Name Description
    ICinemachineCamera fromCam

    The camera being deactivated. May be null.

    Vector3 worldUp

    Default world Up, set by the CinemachineBrain

    Single deltaTime

    Delta time for time-based effects (ignore if less than or equal to 0)

    Returns
    Type Description
    Boolean

    True to request a vcam update of internal state

    InvokePostPipelineStageCallback(CinemachineVirtualCameraBase, CinemachineCore.Stage, ref CameraState, Single)

    Invokes the PostPipelineStageDelegate for this camera, and up the hierarchy for all parent cameras (if any). Implementaion must be sure to call this after each pipeline stage, to allow other services to hook into the pipeline. See CinemachineCore.Stage.

    Declaration
    protected void InvokePostPipelineStageCallback(CinemachineVirtualCameraBase vcam, CinemachineCore.Stage stage, ref CameraState newState, float deltaTime)
    Parameters
    Type Name Description
    CinemachineVirtualCameraBase vcam

    The virtual camera being processed

    CinemachineCore.Stage stage

    The current pipeline stage

    CameraState newState

    The current virtual camera state

    Single deltaTime

    The current applicable deltaTime

    InvokePrePipelineMutateCameraStateCallback(CinemachineVirtualCameraBase, ref CameraState, Single)

    Invokes the PrePipelineMutateCameraStateCallback for this camera, and up the hierarchy for all parent cameras (if any). Implementaion must be sure to call this after each pipeline stage, to allow other services to hook into the pipeline. See CinemachineCore.Stage.

    Declaration
    protected void InvokePrePipelineMutateCameraStateCallback(CinemachineVirtualCameraBase vcam, ref CameraState newState, float deltaTime)
    Parameters
    Type Name Description
    CinemachineVirtualCameraBase vcam

    The virtual camera being processed

    CameraState newState

    The current virtual camera state

    Single deltaTime

    The current applicable deltaTime

    IsLiveChild(ICinemachineCamera, Boolean)

    Check whether the vcam a live child of this camera. This base class implementation always returns false.

    Declaration
    public virtual bool IsLiveChild(ICinemachineCamera vcam, bool dominantChildOnly = false)
    Parameters
    Type Name Description
    ICinemachineCamera vcam

    The Virtual Camera to check

    Boolean dominantChildOnly

    If truw, will only return true if this vcam is the dominat live child

    Returns
    Type Description
    Boolean

    True if the vcam is currently actively influencing the state of this vcam

    Implements
    ICinemachineCamera.IsLiveChild(ICinemachineCamera, Boolean)

    MoveToTopOfPrioritySubqueue()

    When multiple virtual cameras have the highest priority, there is sometimes the need to push one to the top, making it the current Live camera if it shares the highest priority in the queue with its peers.

    This happens automatically when a new vcam is enabled: the most recent one goes to the top of the priority subqueue. Use this method to push a vcam to the top of its priority peers. If it and its peers share the highest priority, then this vcam will become Live.

    Declaration
    public void MoveToTopOfPrioritySubqueue()

    OnDestroy()

    Maintains the global vcam registry. Always call the base class implementation.

    Declaration
    protected virtual void OnDestroy()

    OnDisable()

    Base class implementation makes sure the priority queue remains up-to-date.

    Declaration
    protected virtual void OnDisable()

    OnEnable()

    Base class implementation adds the virtual camera from the priority queue.

    Declaration
    protected virtual void OnEnable()

    OnTargetObjectWarped(Transform, Vector3)

    This is called to notify the component that a target got warped, so that the component can update its internal state to make the camera also warp seamlessy.

    Declaration
    public virtual void OnTargetObjectWarped(Transform target, Vector3 positionDelta)
    Parameters
    Type Name Description
    Transform target

    The object that was warped

    Vector3 positionDelta

    The amount the target's position changed

    Implements
    ICinemachineCamera.OnTargetObjectWarped(Transform, Vector3)

    OnTransformParentChanged()

    Base class implementation makes sure the priority queue remains up-to-date.

    Declaration
    protected virtual void OnTransformParentChanged()

    OnTransitionFromCamera(ICinemachineCamera, Vector3, Single)

    Notification that this virtual camera is going live. Base class implementation must be called by any overridden method.

    Declaration
    public virtual void OnTransitionFromCamera(ICinemachineCamera fromCam, Vector3 worldUp, float deltaTime)
    Parameters
    Type Name Description
    ICinemachineCamera fromCam

    The camera being deactivated. May be null.

    Vector3 worldUp

    Default world Up, set by the CinemachineBrain

    Single deltaTime

    Delta time for time-based effects (ignore if less than or equal to 0)

    Implements
    ICinemachineCamera.OnTransitionFromCamera(ICinemachineCamera, Vector3, Single)

    OnValidate()

    Enforce bounds for fields, when changed in inspector. Call base class implementation at the beginning of overridden method. After base method is called, ValidatingStreamVersion will be valid.

    Declaration
    protected virtual void OnValidate()

    PullStateFromVirtualCamera(Vector3, ref LensSettings)

    Create a camera state based on the current transform of this vcam

    Declaration
    protected CameraState PullStateFromVirtualCamera(Vector3 worldUp, ref LensSettings lens)
    Parameters
    Type Name Description
    Vector3 worldUp

    Current World Up direction, as provided by the brain

    LensSettings lens

    Lens settings to serve as base, will be combined with lens from brain, if any

    Returns
    Type Description
    CameraState

    RemoveExtension(CinemachineExtension)

    Remove a Pipeline stage hook callback.

    Declaration
    public virtual void RemoveExtension(CinemachineExtension extension)
    Parameters
    Type Name Description
    CinemachineExtension extension

    The extension to remove.

    ResolveFollow(Transform)

    Returns this vcam's Follow target, or if that is null, will retrun the parent vcam's Follow target.

    Declaration
    protected Transform ResolveFollow(Transform localFollow)
    Parameters
    Type Name Description
    Transform localFollow

    This vcam's Follow value.

    Returns
    Type Description
    Transform

    The same value, or the parent's if null and a parent exists.

    ResolveLookAt(Transform)

    Returns this vcam's LookAt target, or if that is null, will retrun the parent vcam's LookAt target.

    Declaration
    protected Transform ResolveLookAt(Transform localLookAt)
    Parameters
    Type Name Description
    Transform localLookAt

    This vcam's LookAt value.

    Returns
    Type Description
    Transform

    The same value, or the parent's if null and a parent exists.

    Start()

    Derived classes should call base class implementation.

    Declaration
    protected virtual void Start()

    Update()

    Base class implementation makes sure the priority queue remains up-to-date.

    Declaration
    protected virtual void Update()

    UpdateCameraState(Vector3, Single)

    Update the camera's state. The implementation must guarantee against multiple calls per frame, and should use CinemachineCore.UpdateVirtualCamera(ICinemachineCamera, Vector3, float), which has protection against multiple calls per frame.

    Declaration
    public void UpdateCameraState(Vector3 worldUp, float deltaTime)
    Parameters
    Type Name Description
    Vector3 worldUp

    Default world Up, set by the CinemachineBrain

    Single deltaTime

    Delta time for time-based effects (ignore if less than 0)

    Implements
    ICinemachineCamera.UpdateCameraState(Vector3, Single)
    Back to top Copyright © 2020 Unity Technologies
    Generated by DocFX
    on Wednesday, October 20, 2021