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 ICinemachineTargetGroup, 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
Object
Object
Component
Behaviour
MonoBehaviour
CinemachineComponentBase
CinemachineFramingTransposer
Inherited Members
Namespace: Cinemachine
Syntax
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[AddComponentMenu("")]
public class CinemachineFramingTransposer : CinemachineComponentBase

Fields

m_AdjustmentMode

How to adjust the camera to get the desired framing

Declaration
[Tooltip("How to adjust the camera to get the desired framing.  You can zoom, dolly in/out, or do both.")]
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
[Range(-0.5F, 0.5F)]
[Tooltip("A non-zero bias will move the target position horizontally away from the center of the soft zone.")]
public float m_BiasX
Field Value
Type Description
Single

m_BiasY

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

Declaration
[Range(-0.5F, 0.5F)]
[Tooltip("A non-zero bias will move the target position vertically away from the center of the soft zone.")]
public float m_BiasY
Field Value
Type Description
Single

m_CameraDistance

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

Declaration
[Tooltip("The distance along the camera axis that will be maintained from the Follow target")]
public float m_CameraDistance
Field Value
Type Description
Single

m_CenterOnActivate

Force target to center of screen when this camera activates. If false, will clamp target to the edges of the dead zone

Declaration
[Tooltip("Force target to center of screen when this camera activates.  If false, will clamp target to the edges of the dead zone")]
public bool m_CenterOnActivate
Field Value
Type Description
Boolean

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
[Tooltip("The camera will not move along its z-axis if the Follow target is within this distance of the specified camera distance")]
[FormerlySerializedAs("m_DistanceDeadZoneSize")]
public float m_DeadZoneDepth
Field Value
Type Description
Single

m_DeadZoneHeight

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

Declaration
[Range(0F, 2F)]
[Tooltip("Camera will not move vertically if the target is within this range of the position.")]
public float m_DeadZoneHeight
Field Value
Type Description
Single

m_DeadZoneWidth

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

Declaration
[Space]
[Range(0F, 2F)]
[Tooltip("Camera will not move horizontally if the target is within this range of the position.")]
public float m_DeadZoneWidth
Field Value
Type Description
Single

m_GroupFramingMode

What screen dimensions to consider when framing

Declaration
[Space]
[Tooltip("What screen dimensions to consider when framing.  Can be Horizontal, Vertical, or both")]
[FormerlySerializedAs("m_FramingMode")]
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
[Tooltip("The bounding box of the targets should occupy this amount of the screen space.  1 means fill the whole screen.  0.5 means fill half the screen, etc.")]
public float m_GroupFramingSize
Field Value
Type Description
Single

m_LookaheadIgnoreY

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

Declaration
[Tooltip("If checked, movement along the Y axis will be ignored for lookahead calculations")]
public bool m_LookaheadIgnoreY
Field Value
Type Description
Boolean

m_LookaheadSmoothing

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

Declaration
[Tooltip("Controls the smoothness of the lookahead algorithm.  Larger values smooth out jittery predictions and also increase prediction lag")]
[Range(0F, 30F)]
public float m_LookaheadSmoothing
Field Value
Type Description
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
[Tooltip("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.")]
[Range(0F, 1F)]
[Space]
public float m_LookaheadTime
Field Value
Type Description
Single

m_MaxDollyIn

How much closer to the target can the camera go?

Declaration
[Tooltip("The maximum distance toward the target that this behaviour is allowed to move the camera.")]
public float m_MaxDollyIn
Field Value
Type Description
Single

m_MaxDollyOut

How much farther from the target can the camera go?

Declaration
[Tooltip("The maximum distance away the target that this behaviour is allowed to move the camera.")]
public float m_MaxDollyOut
Field Value
Type Description
Single

m_MaximumDistance

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

Declaration
[Tooltip("Set this to limit how far from the target the camera can get.")]
public float m_MaximumDistance
Field Value
Type Description
Single

m_MaximumFOV

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

Declaration
[Range(1F, 179F)]
[Tooltip("If adjusting FOV, will not set the FOV higher than this.")]
public float m_MaximumFOV
Field Value
Type Description
Single

m_MaximumOrthoSize

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

Declaration
[Tooltip("If adjusting Orthographic Size, will not set it higher than this.")]
public float m_MaximumOrthoSize
Field Value
Type Description
Single

m_MinimumDistance

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

Declaration
[Tooltip("Set this to limit how close to the target the camera can get.")]
public float m_MinimumDistance
Field Value
Type Description
Single

m_MinimumFOV

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

Declaration
[Range(1F, 179F)]
[Tooltip("If adjusting FOV, will not set the FOV lower than this.")]
public float m_MinimumFOV
Field Value
Type Description
Single

m_MinimumOrthoSize

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

Declaration
[Tooltip("If adjusting Orthographic Size, will not set it lower than this.")]
public float m_MinimumOrthoSize
Field Value
Type Description
Single

m_ScreenX

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

Declaration
[Space]
[Range(-0.5F, 1.5F)]
[Tooltip("Horizontal screen position for target. The camera will move to position the tracked object here.")]
public float m_ScreenX
Field Value
Type Description
Single

m_ScreenY

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

Declaration
[Range(-0.5F, 1.5F)]
[Tooltip("Vertical screen position for target, The camera will move to position the tracked object here.")]
public float m_ScreenY
Field Value
Type Description
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
[Range(0F, 2F)]
[Tooltip("When target is within this region, camera will gradually move vertically to re-align towards the desired position, depending on the damping speed.")]
public float m_SoftZoneHeight
Field Value
Type Description
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
[Range(0F, 2F)]
[Tooltip("When target is within this region, camera will gradually move horizontally to re-align towards the desired position, depending on the damping speed.")]
public float m_SoftZoneWidth
Field Value
Type Description
Single

m_TargetMovementOnly

If set, damping will apply only to target motion, and not when the camera rotation changes. Turn this on to get an instant response when the rotation changes

Declaration
[Tooltip("If set, damping will apply  only to target motion, but not to camera rotation changes.  Turn this on to get an instant response when the rotation changes.  ")]
public bool m_TargetMovementOnly
Field Value
Type Description
Boolean

m_TrackedObjectOffset

Offset from the Follow Target object (in target-local co-ordinates). The camera will attempt to frame the point which is the target's position plus this offset. Use it to correct for cases when the target's origin is not the point of interest for the camera.

Declaration
[Tooltip("Offset from the Follow Target object (in target-local co-ordinates).  The camera will attempt to frame the point which is the target's position plus this offset.  Use it to correct for cases when the target's origin is not the point of interest for the camera.")]
public Vector3 m_TrackedObjectOffset
Field Value
Type Description
Vector3

m_UnlimitedSoftZone

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

Declaration
[Space]
[Tooltip("If checked, then then soft zone will be unlimited in size.")]
public bool m_UnlimitedSoftZone
Field Value
Type Description
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
[Space]
[Range(0F, 20F)]
[Tooltip("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.")]
public float m_XDamping
Field Value
Type Description
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
[Range(0F, 20F)]
[Tooltip("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.")]
public float m_YDamping
Field Value
Type Description
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
[Range(0F, 20F)]
[Tooltip("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.")]
public float m_ZDamping
Field Value
Type Description
Single

Properties

BodyAppliesAfterAim

FramingTransposer's algorithm tahes camera orientation as input, so even though it is a Body component, it must apply after Aim

Declaration
public override bool BodyAppliesAfterAim { get; }
Property Value
Type Description
Boolean
Overrides

IsValid

True if component is enabled and has a valid Follow target

Declaration
public override bool IsValid { get; }
Property Value
Type Description
Boolean
Overrides

LastBounds

For editor visulaization of the calculated bounding box of the group

Declaration
public Bounds LastBounds { get; }
Property Value
Type Description
Bounds

LastBoundsMatrix

For editor visualization of the calculated bounding box of the group

Declaration
public Matrix4x4 LastBoundsMatrix { get; }
Property Value
Type Description
Matrix4x4

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

TrackedPoint

Internal API for inspector

Declaration
public Vector3 TrackedPoint { get; }
Property Value
Type Description
Vector3

Methods

ForceCameraPosition(Vector3, Quaternion)

Force the virtual camera to assume a given position and orientation

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

Worldspace pposition to take
Quaternion rot

Worldspace orientation to take
Overrides

GetMaxDampTime()

Report maximum damping time needed for this component.

Declaration
public override float GetMaxDampTime()
Returns
Type Description
Single

Highest damping setting in this component
Overrides

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
Single deltaTime

Used for damping. If less than 0, no damping is done.
Overrides

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

OnTransitionFromCamera(ICinemachineCamera, Vector3, Single, ref CinemachineVirtualCameraBase.TransitionParams)

Notification that this virtual camera is going live. Base class implementation does nothing.

Declaration
public override bool OnTransitionFromCamera(ICinemachineCamera fromCam, Vector3 worldUp, float deltaTime, ref CinemachineVirtualCameraBase.TransitionParams transitionParams)
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)
CinemachineVirtualCameraBase.TransitionParams transitionParams

Transition settings for this vcam
Returns
Type Description
Boolean

True if the vcam should do an internal update as a result of this call
Overrides