Class CinemachineFramingTransposer

This is a Cinemachine Component in the Body section of the component pipeline. Its job is to position the camera in a fixed screen-space relationship to the vcam's Follow target object, with offsets and damping.

The camera will be first moved along the camera Z axis until the Follow target is at the desired distance from the camera's X-Y plane. The camera will then be moved in its XY plane until the Follow target is at the desired point on the camera's screen.

The FramingTansposer will only change the camera's position in space. It will not re-orient or otherwise aim the camera.

For this component to work properly, the vcam's LookAt target must be null. The Follow target will define what the camera is looking at.

If the Follow target is a CinemachineTargetGroup, then additional controls will be available to dynamically adjust the camera's view in order to frame the entire group.

Although this component was designed for orthographic cameras, it works equally
well with persective cameras and can be used in 3D environments.

Inheritance

MonoBehaviour

CinemachineComponentBase

CinemachineFramingTransposer

Inherited Members

CinemachineComponentBase.Epsilon

CinemachineComponentBase.VirtualCamera

CinemachineComponentBase.FollowTarget

CinemachineComponentBase.LookAtTarget

CinemachineComponentBase.FollowTargetPosition

CinemachineComponentBase.FollowTargetRotation

CinemachineComponentBase.LookAtTargetPosition

CinemachineComponentBase.LookAtTargetRotation

CinemachineComponentBase.VcamState

CinemachineComponentBase.PrePipelineMutateCameraState(CameraState)

Namespace: Cinemachine

Syntax

[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
public class CinemachineFramingTransposer : CinemachineComponentBase

Fields

m_AdjustmentMode

How to adjust the camera to get the desired framing

Declaration

public CinemachineFramingTransposer.AdjustmentMode m_AdjustmentMode

Field Value

Type	Description
CinemachineFramingTransposer.AdjustmentMode

m_BiasX

A non-zero bias will move the targt position away from the center of the soft zone

Declaration

public float m_BiasX

Field Value

Type	Description
System.Single

m_BiasY

A non-zero bias will move the targt position away from the center of the soft zone

Declaration

public float m_BiasY

Field Value

Type	Description
System.Single

m_CameraDistance

The distance along the camera axis that will be maintained from the Follow target

Declaration

public float m_CameraDistance

Field Value

Type	Description
System.Single

m_DeadZoneDepth

The camera will not move along its z-axis if the Follow target is within this distance of the specified camera distance

Declaration

public float m_DeadZoneDepth

Field Value

Type	Description
System.Single

m_DeadZoneHeight

Camera will not move vertically if the target is within this range of the position

Declaration

public float m_DeadZoneHeight

Field Value

Type	Description
System.Single

m_DeadZoneWidth

Camera will not move horizontally if the target is within this range of the position

Declaration

public float m_DeadZoneWidth

Field Value

Type	Description
System.Single

m_GroupFramingMode

What screen dimensions to consider when framing

Declaration

public CinemachineFramingTransposer.FramingMode m_GroupFramingMode

Field Value

Type	Description
CinemachineFramingTransposer.FramingMode

m_GroupFramingSize

How much of the screen to fill with the bounding box of the targets.

Declaration

public float m_GroupFramingSize

Field Value

Type	Description
System.Single

m_LookaheadIgnoreY

If checked, movement along the Y axis will be ignored for lookahead calculations

Declaration

public bool m_LookaheadIgnoreY

Field Value

Type	Description
System.Boolean

m_LookaheadSmoothing

Controls the smoothness of the lookahead algorithm. Larger values smooth out jittery predictions and also increase prediction lag

Declaration

public float m_LookaheadSmoothing

Field Value

Type	Description
System.Single

m_LookaheadTime

This setting will instruct the composer to adjust its target offset based on the motion of the target. The composer will look at a point where it estimates the target will be this many seconds into the future. Note that this setting is sensitive to noisy animation, and can amplify the noise, resulting in undesirable camera jitter. If the camera jitters unacceptably when the target is in motion, turn down this setting, or animate the target more smoothly.

Declaration

public float m_LookaheadTime

Field Value

Type	Description
System.Single

m_MaxDollyIn

How much closer to the target can the camera go?

Declaration

public float m_MaxDollyIn

Field Value

Type	Description
System.Single

m_MaxDollyOut

How much farther from the target can the camera go?

Declaration

public float m_MaxDollyOut

Field Value

Type	Description
System.Single

m_MaximumDistance

Set this to limit how far from the taregt the camera can get

Declaration

public float m_MaximumDistance

Field Value

Type	Description
System.Single

m_MaximumFOV

If adjusting FOV, will not set the FOV higher than this

Declaration

public float m_MaximumFOV

Field Value

Type	Description
System.Single

m_MaximumOrthoSize

If adjusting Orthographic Size, will not set it higher than this

Declaration

public float m_MaximumOrthoSize

Field Value

Type	Description
System.Single

m_MinimumDistance

Set this to limit how close to the target the camera can get

Declaration

public float m_MinimumDistance

Field Value

Type	Description
System.Single

m_MinimumFOV

If adjusting FOV, will not set the FOV lower than this

Declaration

public float m_MinimumFOV

Field Value

Type	Description
System.Single

m_MinimumOrthoSize

If adjusting Orthographic Size, will not set it lower than this

Declaration

public float m_MinimumOrthoSize

Field Value

Type	Description
System.Single

m_ScreenX

Horizontal screen position for target. The camera will move to position the tracked object here

Declaration

public float m_ScreenX

Field Value

Type	Description
System.Single

m_ScreenY

Vertical screen position for target, The camera will move to to position the tracked object here

Declaration

public float m_ScreenY

Field Value

Type	Description
System.Single

m_SoftZoneHeight

When target is within this region, camera will gradually move to re-align towards the desired position, depending onm the damping speed

Declaration

public float m_SoftZoneHeight

Field Value

Type	Description
System.Single

m_SoftZoneWidth

When target is within this region, camera will gradually move to re-align towards the desired position, depending onm the damping speed

Declaration

public float m_SoftZoneWidth

Field Value

Type	Description
System.Single

m_UnlimitedSoftZone

If checked, then then soft zone will be unlimited in size

Declaration

public bool m_UnlimitedSoftZone

Field Value

Type	Description
System.Boolean

m_XDamping

How aggressively the camera tries to maintain the offset in the X-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's x-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration

public float m_XDamping

Field Value

Type	Description
System.Single

m_YDamping

How aggressively the camera tries to maintain the offset in the Y-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's y-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration

public float m_YDamping

Field Value

Type	Description
System.Single

m_ZDamping

How aggressively the camera tries to maintain the offset in the Z-axis. Small numbers are more responsive, rapidly translating the camera to keep the target's z-axis offset. Larger numbers give a more heavy slowly responding camera. Using different settings per axis can yield a wide range of camera behaviors

Declaration

public float m_ZDamping

Field Value

Type	Description
System.Single

OnGUICallback

Used by the Inspector Editor to display on-screen guides.

Declaration

public Action OnGUICallback

Field Value

Type	Description
Action

Properties

HardGuideRect

Internal API for the inspector editor

Declaration

public Rect HardGuideRect { get; set; }

Property Value

Type	Description
Rect

IsValid

True if component is enabled and has a valid Follow target

Declaration

public override bool IsValid { get; }

Property Value

Type	Description
System.Boolean

Overrides

CinemachineComponentBase.IsValid

m_LastBounds

For editor visulaization of the calculated bounding box of the group

Declaration

public Bounds m_LastBounds { get; }

Property Value

Type	Description
Bounds

m_lastBoundsMatrix

For editor visualization of the calculated bounding box of the group

Declaration

public Matrix4x4 m_lastBoundsMatrix { get; }

Property Value

Type	Description
Matrix4x4

SoftGuideRect

Internal API for the inspector editor

Declaration

public Rect SoftGuideRect { get; set; }

Property Value

Type	Description
Rect

Stage

Get the Cinemachine Pipeline stage that this component implements. Always returns the Body stage

Declaration

public override CinemachineCore.Stage Stage { get; }

Property Value

Type	Description
CinemachineCore.Stage

Overrides

CinemachineComponentBase.Stage

TargetGroup

Get Follow target as CinemachineTargetGroup, or null if target is not a group

Declaration

public CinemachineTargetGroup TargetGroup { get; }

Property Value

Type	Description
CinemachineTargetGroup

TrackedPoint

Internal API for inspector

Declaration

public Vector3 TrackedPoint { get; }

Property Value

Type	Description
Vector3

Methods

MutateCameraState(ref CameraState, Single)

Positions the virtual camera according to the transposer rules.

Declaration

public override void MutateCameraState(ref CameraState curState, float deltaTime)

Parameters

Type	Name	Description
CameraState	curState	The current camera state
System.Single	deltaTime	Used for damping. If less than 0, no damping is done.

Overrides

CinemachineComponentBase.MutateCameraState(ref CameraState, Single)

OnTargetObjectWarped(Transform, Vector3)

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

Declaration

public override 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

Overrides

CinemachineComponentBase.OnTargetObjectWarped(Transform, Vector3)