Class CinemachineConfiner2D
An add-on module for Cinemachine Camera that post-processes the final position of the virtual camera. It will confine the camera's position such that the screen edges stay within a shape defined by a 2D polygon. This will work for orthographic or perspective cameras, provided that the camera's forward vector remains parallel to the bounding shape's normal, i.e. that the camera is looking straight at the polygon, and not obliquely at it.
When confining the camera, the camera's view size at the polygon plane is considered, and also its aspect ratio. Based on this information and the input polygon, a second (smaller) polygon is computed to which the camera's transform is constrained. Computation of this secondary polygon is nontrivial and expensive, so it should be done only when absolutely necessary.
When the Orthographic Size or Field of View of the Cinemachine Camera's lens changes, Cinemachine will not automatically adjust the Confiner for efficiency reasons. To adjust the Confiner, call InvalidateLensCache().
Confiner2D pre-calculates a cache to speed up calculation. The cache needs to be recomputed in the following circumstances:
- when the input polygon's points change
- when the input polygon is non-uniformly scaled
- when the input polygon is rotated
For efficiency reasons, Cinemachine will not automatically regenerate the cache. It is the responsibility of the client to call the InvalidateBoundingShapeCache() method to trigger a recalculation. An inspector button is also provided for this purpose.
If the input polygon scales uniformly or translates, the cache remains valid. If the polygon rotates, then the cache degrades in quality (more or less depending on the aspect ratio - it's better if the ratio is close to 1:1) but can still be used. Regenerating it will eliminate the imperfections.
When the Oversize Window is enabled an additional pre-calculation step is added to the caching process. This cache is not a single polygon, but rather a family of polygons. The number of polygons in this family will depend on the complexity of the input polygon, and the maximum expected camera view size. The MaxWindowSize property is provided to give a hint to the algorithm to stop generating polygons for camera view sizes larger than the one specified. This can represent a substantial cost saving when regenerating the cache, so it is a good idea to set it carefully. Leaving it at 0 will cause the maximum number of polygons to be generated.
Inheritance
Inherited Members
Namespace: Unity.Cinemachine
Assembly: Unity.Cinemachine.dll
Syntax
[AddComponentMenu("Cinemachine/Procedural/Extensions/Cinemachine Confiner 2D")]
[ExecuteAlways]
[DisallowMultipleComponent]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@3.1/manual/CinemachineConfiner2D.html")]
public class CinemachineConfiner2D : CinemachineExtensionFields
BoundingShape2D
The 2D shape within which the camera is to be contained.
Declaration
[Tooltip("The 2D shape within which the camera is to be contained. Can be polygon-, box-, or composite collider 2D.\n\nRemark: When assigning a GameObject here in the editor, this will be set to the first Collider2D found on the assigned GameObject!")]
[FormerlySerializedAs("m_BoundingShape2D")]
public Collider2D BoundingShape2DField Value
| Type | Description |
|---|---|
| Collider2D |
Damping
Damping applied automatically around corners to avoid jumps.
Declaration
[Tooltip("Damping applied around corners to avoid jumps. Higher numbers are more gradual.")]
[Range(0, 5)]
[FormerlySerializedAs("m_Damping")]
public float DampingField Value
| Type | Description |
|---|---|
| float |
OversizeWindow
Settings to optimize computation and memory costs in the event that the window size is expected to be larger than will fit inside the confining shape.
Declaration
[FoldoutWithEnabledButton("Enabled")]
public CinemachineConfiner2D.OversizeWindowSettings OversizeWindowField Value
| Type | Description |
|---|---|
| CinemachineConfiner2D.OversizeWindowSettings |
SlowingDistance
Size of the slow-down zone at the edge of the bounding shape.
Declaration
[Tooltip("Size of the slow-down zone at the edge of the bounding shape.")]
public float SlowingDistanceField Value
| Type | Description |
|---|---|
| float |
Methods
CalculateHalfFrustumHeight(in LensSettings, in float)
Calculates half frustum height for orthographic or perspective camera. For more info on frustum height, see docs.unity3d.com/Manual/FrustumSizeAtDistance.html.
Declaration
public static float CalculateHalfFrustumHeight(in LensSettings lens, in float cameraPosLocalZ)Parameters
| Type | Name | Description |
|---|---|---|
| LensSettings | lens | Camera Lens for checking if Orthographic or Perspective |
| float | cameraPosLocalZ | camera's z pos in local space |
Returns
| Type | Description |
|---|---|
| float | Frustum height of the camera |
GetMaxDampTime()
Report maximum damping time needed for this component.
Declaration
public override float GetMaxDampTime()Returns
| Type | Description |
|---|---|
| float | Highest damping setting in this component |
Overrides
InvalidateBoundingShapeCache()
Invalidates Bounding Shape Cache, so a new one is computed next frame. The re-computation is costly. This recomputes the bounding shape cache, and the computed confiner cache. Call this when the input bounding shape changes (non-uniform scale, rotation, or points are moved, added or deleted).
Declaration
public void InvalidateBoundingShapeCache()Remarks
It is much more efficient to have more Cinemachine Cameras with different input bounding shapes and blend between them instead of changing one Confiner2D's input bounding shape and calling this over and over.
InvalidateCache()
Declaration
[Obsolete("Call InvalidateBoundingShapeCache() instead.", false)]
public void InvalidateCache()InvalidateLensCache()
Invalidates the lens cache for the Cinemachine Camera that ownes this Confiner. Call this when when the Field of View or Orthographic Size changes. Calculating the lens cache is fast, but causes allocations.
Declaration
public void InvalidateLensCache()OnTargetObjectWarped(CinemachineVirtualCameraBase, Transform, Vector3)
This is called to notify the extension that a target got warped, so that the extension can update its internal state to make the camera also warp seamlessly. Base class implementation does nothing.
Declaration
public override void OnTargetObjectWarped(CinemachineVirtualCameraBase vcam, Transform target, Vector3 positionDelta)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The camera to warp |
| Transform | target | The object that was warped |
| Vector3 | positionDelta | The amount the target's position changed |
Overrides
PostPipelineStageCallback(CinemachineVirtualCameraBase, Stage, ref CameraState, float)
Callback to do the camera confining
Declaration
protected override void PostPipelineStageCallback(CinemachineVirtualCameraBase vcam, CinemachineCore.Stage stage, ref CameraState state, float deltaTime)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The virtual camera being processed |
| CinemachineCore.Stage | stage | The current pipeline stage |
| CameraState | state | The current virtual camera state |
| float | deltaTime | The current applicable deltaTime |