using System;
using Cinemachine.Utility;
using UnityEngine;
namespace Cinemachine
{
///
/// This is a CinemachineComponent in the Body section of the component pipeline.
/// Its job is to position the camera in a fixed relationship to the vcam's Follow
/// target object, with offsets and damping.
///
/// The Tansposer will only change the camera's position in space. It will not
/// re-orient or otherwise aim the camera. To to that, you need to instruct
/// the vcam in the Aim section of its pipeline.
///
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
[AddComponentMenu("")] // Don't display in add component menu
[SaveDuringPlay]
public class CinemachineTransposer : CinemachineComponentBase
{
///
/// The coordinate space to use when interpreting the offset from the target
///
[DocumentationSorting(DocumentationSortingAttribute.Level.UserRef)]
public enum BindingMode
{
///
/// Camera will be bound to the Follow target using a frame of reference consisting
/// of the target's local frame at the moment when the virtual camera was enabled,
/// or when the target was assigned.
///
LockToTargetOnAssign = 0,
///
/// Camera will be bound to the Follow target using a frame of reference consisting
/// of the target's local frame, with the tilt and roll zeroed out.
///
LockToTargetWithWorldUp = 1,
///
/// Camera will be bound to the Follow target using a frame of reference consisting
/// of the target's local frame, with the roll zeroed out.
///
LockToTargetNoRoll = 2,
///
/// Camera will be bound to the Follow target using the target's local frame.
///
LockToTarget = 3,
/// Camera will be bound to the Follow target using a world space offset.
WorldSpace = 4,
/// Offsets will be calculated relative to the target, using Camera-local axes
SimpleFollowWithWorldUp = 5
}
/// The coordinate space to use when interpreting the offset from the target
[Tooltip("The coordinate space to use when interpreting the offset from the target. This is also "
+ "used to set the camera's Up vector, which will be maintained when aiming the camera.")]
public BindingMode m_BindingMode = BindingMode.LockToTargetWithWorldUp;
/// The distance which the transposer will attempt to maintain from the transposer subject
[Tooltip("The distance vector that the transposer will attempt to maintain from the Follow target")]
public Vector3 m_FollowOffset = Vector3.back * 10f;
/// 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
[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 = 1f;
/// 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
[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 = 1f;
/// 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
[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 = 1f;
/// How to calculate the angular damping for the target orientation
public enum AngularDampingMode
{
/// Use Euler angles to specify damping values.
/// Subject to gimbal-lock fwhen pitch is steep.
Euler,
///
/// Use quaternions to calculate angular damping.
/// No per-channel control, but not susceptible to gimbal-lock
Quaternion
}
/// How to calculate the angular damping for the target orientation.
/// Use Quaternion if you expect the target to take on very steep pitches, which would
/// be subject to gimbal lock if Eulers are used.
public AngularDampingMode m_AngularDampingMode = AngularDampingMode.Euler;
/// How aggressively the camera tries to track the target rotation's X angle.
/// Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.
[Range(0f, 20f)]
[Tooltip("How aggressively the camera tries to track the target rotation's X angle. "
+ "Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.")]
public float m_PitchDamping = 0;
/// How aggressively the camera tries to track the target rotation's Y angle.
/// Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.
[Range(0f, 20f)]
[Tooltip("How aggressively the camera tries to track the target rotation's Y angle. "
+ "Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.")]
public float m_YawDamping = 0;
/// How aggressively the camera tries to track the target rotation's Z angle.
/// Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.
[Range(0f, 20f)]
[Tooltip("How aggressively the camera tries to track the target rotation's Z angle. "
+ "Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.")]
public float m_RollDamping = 0f;
/// How aggressively the camera tries to track the target's orientation.
/// Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.
[Range(0f, 20f)]
[Tooltip("How aggressively the camera tries to track the target's orientation. "
+ "Small numbers are more responsive. Larger numbers give a more heavy slowly responding camera.")]
public float m_AngularDamping = 0f;
/// Derived classes should call this from their OnValidate() implementation
protected virtual void OnValidate()
{
m_FollowOffset = EffectiveOffset;
}
/// Hide the offset in int inspector. Used by FreeLook.
public bool HideOffsetInInspector { get; set; }
/// Get the target offset, with sanitization
public Vector3 EffectiveOffset
{
get
{
Vector3 offset = m_FollowOffset;
if (m_BindingMode == BindingMode.SimpleFollowWithWorldUp)
{
offset.x = 0;
offset.z = -Mathf.Abs(offset.z);
}
return offset;
}
}
/// True if component is enabled and has a valid Follow target
public override bool IsValid { get { return enabled && FollowTarget != null; } }
/// Get the Cinemachine Pipeline stage that this component implements.
/// Always returns the Body stage
public override CinemachineCore.Stage Stage { get { return CinemachineCore.Stage.Body; } }
///
/// Report maximum damping time needed for this component.
///
/// Highest damping setting in this component
public override float GetMaxDampTime()
{
var d = Damping;
var d2 = AngularDamping;
var a = Mathf.Max(d.x, Mathf.Max(d.y, d.z));
var b = Mathf.Max(d2.x, Mathf.Max(d2.y, d2.z));
return Mathf.Max(a, b);
}
/// Positions the virtual camera according to the transposer rules.
/// The current camera state
/// Used for damping. If less than 0, no damping is done.
public override void MutateCameraState(ref CameraState curState, float deltaTime)
{
InitPrevFrameStateInfo(ref curState, deltaTime);
if (IsValid)
{
Vector3 offset = EffectiveOffset;
TrackTarget(deltaTime, curState.ReferenceUp, offset, out Vector3 pos, out Quaternion orient);
offset = orient * offset;
// Respect minimum target distance on XZ plane
var targetPosition = FollowTargetPosition;
pos += GetOffsetForMinimumTargetDistance(
pos, offset, curState.RawOrientation * Vector3.forward,
curState.ReferenceUp, targetPosition);
curState.RawPosition = pos + offset;
curState.ReferenceUp = orient * Vector3.up;
}
}
/// 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.
/// The object that was warped
/// The amount the target's position changed
public override void OnTargetObjectWarped(Transform target, Vector3 positionDelta)
{
base.OnTargetObjectWarped(target, positionDelta);
if (target == FollowTarget)
m_PreviousTargetPosition += positionDelta;
}
///
/// Force the virtual camera to assume a given position and orientation
///
/// Worldspace pposition to take
/// Worldspace orientation to take
public override void ForceCameraPosition(Vector3 pos, Quaternion rot)
{
base.ForceCameraPosition(pos, rot);
// Infer target pos from camera
var targetRot = m_BindingMode == BindingMode.SimpleFollowWithWorldUp
? rot : GetReferenceOrientation(VirtualCamera.State.ReferenceUp);
m_PreviousTargetPosition = pos - targetRot * EffectiveOffset;
}
/// Initializes the state for previous frame if appropriate.
/// The current camera state
/// Current effective deltaTime.
protected void InitPrevFrameStateInfo(
ref CameraState curState, float deltaTime)
{
bool prevStateValid = deltaTime >= 0 && VirtualCamera.PreviousStateIsValid;
if (m_previousTarget != FollowTarget || !prevStateValid)
{
m_previousTarget = FollowTarget;
m_targetOrientationOnAssign = FollowTargetRotation;
}
if (!prevStateValid)
{
m_PreviousTargetPosition = FollowTargetPosition;
m_PreviousReferenceOrientation = GetReferenceOrientation(curState.ReferenceUp);
}
}
/// Positions the virtual camera according to the transposer rules.
/// Used for damping. If less than 0, no damping is done.
/// Current camera up
/// Where we want to put the camera relative to the follow target
/// Resulting camera position
/// Damped target orientation
protected void TrackTarget(
float deltaTime, Vector3 up, Vector3 desiredCameraOffset,
out Vector3 outTargetPosition, out Quaternion outTargetOrient)
{
var targetOrientation = GetReferenceOrientation(up);
var dampedOrientation = targetOrientation;
bool prevStateValid = deltaTime >= 0 && VirtualCamera.PreviousStateIsValid;
if (prevStateValid)
{
if (m_AngularDampingMode == AngularDampingMode.Quaternion
&& m_BindingMode == BindingMode.LockToTarget)
{
float t = VirtualCamera.DetachedFollowTargetDamp(1, m_AngularDamping, deltaTime);
dampedOrientation = Quaternion.Slerp(
m_PreviousReferenceOrientation, targetOrientation, t);
}
else
{
var relative = (Quaternion.Inverse(m_PreviousReferenceOrientation)
* targetOrientation).eulerAngles;
for (int i = 0; i < 3; ++i)
{
if (Mathf.Abs(relative[i]) < 0.01f) // correct for precision drift
relative[i] = 0;
else if (relative[i] > 180)
relative[i] -= 360;
}
relative = VirtualCamera.DetachedFollowTargetDamp(relative, AngularDamping, deltaTime);
dampedOrientation = m_PreviousReferenceOrientation * Quaternion.Euler(relative);
}
}
m_PreviousReferenceOrientation = dampedOrientation;
var targetPosition = FollowTargetPosition;
var currentPosition = m_PreviousTargetPosition;
var previousOffset = prevStateValid ? m_PreviousOffset : desiredCameraOffset;
var offsetDelta = desiredCameraOffset - previousOffset;
if (offsetDelta.sqrMagnitude > 0.01f)
{
var q = UnityVectorExtensions.SafeFromToRotation(
m_PreviousOffset.ProjectOntoPlane(up),
desiredCameraOffset.ProjectOntoPlane(up), up);
currentPosition = targetPosition + q * (m_PreviousTargetPosition - targetPosition);
}
m_PreviousOffset = desiredCameraOffset;
// Adjust for damping, which is done in camera-offset-local coords
var positionDelta = targetPosition - currentPosition;
if (prevStateValid)
{
Quaternion dampingSpace;
if (desiredCameraOffset.AlmostZero())
dampingSpace = VcamState.RawOrientation;
else
dampingSpace = Quaternion.LookRotation(dampedOrientation * desiredCameraOffset, up);
var localDelta = Quaternion.Inverse(dampingSpace) * positionDelta;
localDelta = VirtualCamera.DetachedFollowTargetDamp(localDelta, Damping, deltaTime);
positionDelta = dampingSpace * localDelta;
}
currentPosition += positionDelta;
outTargetPosition = m_PreviousTargetPosition = currentPosition;
outTargetOrient = dampedOrientation;
}
/// Return a new damped target position that respects the minimum
/// distance from the real target
/// The effective position of the target, after damping
/// Desired camera offset from target
/// Current camera local +Z direction
/// Effective world up
/// The real undamped target position
/// New camera offset, potentially adjusted to respect minimum distance from target
protected Vector3 GetOffsetForMinimumTargetDistance(
Vector3 dampedTargetPos, Vector3 cameraOffset,
Vector3 cameraFwd, Vector3 up, Vector3 actualTargetPos)
{
var posOffset = Vector3.zero;
if (VirtualCamera.FollowTargetAttachment > 1 - Epsilon)
{
cameraOffset = cameraOffset.ProjectOntoPlane(up);
var minDistance = cameraOffset.magnitude * 0.2f;
if (minDistance > 0)
{
actualTargetPos = actualTargetPos.ProjectOntoPlane(up);
dampedTargetPos = dampedTargetPos.ProjectOntoPlane(up);
var cameraPos = dampedTargetPos + cameraOffset;
var d = Vector3.Dot(
actualTargetPos - cameraPos,
(dampedTargetPos - cameraPos).normalized);
if (d < minDistance)
{
var dir = actualTargetPos - dampedTargetPos;
var len = dir.magnitude;
if (len < 0.01f)
dir = -cameraFwd.ProjectOntoPlane(up);
else
dir /= len;
posOffset = dir * (minDistance - d);
}
m_PreviousTargetPosition += posOffset;
}
}
return posOffset;
}
///
/// Damping speeds for each of the 3 axes of the offset from target
///
protected Vector3 Damping
{
get
{
switch (m_BindingMode)
{
case BindingMode.SimpleFollowWithWorldUp:
return new Vector3(0, m_YDamping, m_ZDamping);
default:
return new Vector3(m_XDamping, m_YDamping, m_ZDamping);
}
}
}
///
/// Damping speeds for each of the 3 axes of the target's rotation
///
protected Vector3 AngularDamping
{
get
{
switch (m_BindingMode)
{
case BindingMode.LockToTargetNoRoll:
return new Vector3(m_PitchDamping, m_YawDamping, 0);
case BindingMode.LockToTargetWithWorldUp:
return new Vector3(0, m_YawDamping, 0);
case BindingMode.LockToTargetOnAssign:
case BindingMode.WorldSpace:
case BindingMode.SimpleFollowWithWorldUp:
return Vector3.zero;
default:
return new Vector3(m_PitchDamping, m_YawDamping, m_RollDamping);
}
}
}
/// Internal API for the Inspector Editor, so it can draw a marker at the target
/// Current effective world up
/// The position of the Follow target
public virtual Vector3 GetTargetCameraPosition(Vector3 worldUp)
{
if (!IsValid)
return Vector3.zero;
return FollowTargetPosition + GetReferenceOrientation(worldUp) * EffectiveOffset;
}
/// State information for damping
Vector3 m_PreviousTargetPosition = Vector3.zero;
Quaternion m_PreviousReferenceOrientation = Quaternion.identity;
Quaternion m_targetOrientationOnAssign = Quaternion.identity;
Vector3 m_PreviousOffset;
Transform m_previousTarget = null;
/// Internal API for the Inspector Editor, so it can draw a marker at the target
/// Current effective world up
/// The rotation of the Follow target, as understood by the Transposer.
/// This is not necessarily the same thing as the actual target rotation
public Quaternion GetReferenceOrientation(Vector3 worldUp)
{
if (m_BindingMode == BindingMode.WorldSpace)
return Quaternion.identity;
if (FollowTarget != null)
{
Quaternion targetOrientation = FollowTarget.rotation;
switch (m_BindingMode)
{
case BindingMode.LockToTargetOnAssign:
return m_targetOrientationOnAssign;
case BindingMode.LockToTargetWithWorldUp:
{
Vector3 fwd = (targetOrientation * Vector3.forward).ProjectOntoPlane(worldUp);
if (fwd.AlmostZero())
break;
return Quaternion.LookRotation(fwd, worldUp);
}
case BindingMode.LockToTargetNoRoll:
return Quaternion.LookRotation(targetOrientation * Vector3.forward, worldUp);
case BindingMode.LockToTarget:
return targetOrientation;
case BindingMode.SimpleFollowWithWorldUp:
{
Vector3 fwd = (FollowTargetPosition - VcamState.RawPosition).ProjectOntoPlane(worldUp);
if (fwd.AlmostZero())
break;
return Quaternion.LookRotation(fwd, worldUp);
}
}
}
// Gimbal lock situation - use previous orientation if it exists
#if UNITY_2019_1_OR_NEWER
return m_PreviousReferenceOrientation.normalized;
#else
return m_PreviousReferenceOrientation.Normalized();
#endif
}
}
}