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. If the camera is looking obliquely at the polygon, confining will still occur but not precisely at the polyon edges. In this situation, you can adjust the polygon until the desired confining occurs.
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 subsequent 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 |
Properties
BoundingShapeIsBaked
Before it can be used, the bounding shape must be baked. Baking happens whenever the bounding shape cache gets invalidated. The expensive baking operation is spread out over a number of frames. The confiner will have no effect until the bounding shape is baked. This property can be polled to determine whether the baking operation is complete.
Declaration
public bool BoundingShapeIsBaked { get; }Property Value
| Type | Description |
|---|---|
| bool | True if the bouding shape cache has been fully baked. |
Methods
BakeBoundingShape(CinemachineVirtualCameraBase, float)
Normally, confiner baking will happen automatically when the camera is activated. This expensive operation will be spread out over a number of frames, up to a maximum total baking time of 5 seconds. If it's not fully baked in 5 seconds, it will give up because the bounding shape is too complex to be baked.
Sometimes it is necessary to force the completion of baking immediately (for instance, if a level begins with a confined camera, it needs to be fully baked on the first frame).
In those cases, this method can be called to advance the baking.
Declaration
public bool BakeBoundingShape(CinemachineVirtualCameraBase vcam, float maxTimeInSeconds)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The virtual camera context. This is needed for the lens information. |
| float | maxTimeInSeconds | Maximum time in seconds to devote to baking during this blocking call. If it's not enough to finish the job, then this method can be called repeatedly over several frames. When the total accumulated time is more than 5 seconds, this method will do nothing. |
Returns
| Type | Description |
|---|---|
| bool | True if baking is complete, false if more baking is needed or if more than 5 baking seconds have elapsed. |
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 |
CameraWasDisplaced(CinemachineVirtualCameraBase)
See whether the virtual camera has been moved by the confiner
Declaration
public bool CameraWasDisplaced(CinemachineVirtualCameraBase vcam)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The virtual camera in question. This might be different from the virtual camera that owns the confiner, in the event that the camera has children |
Returns
| Type | Description |
|---|---|
| bool | True if the virtual camera has been repositioned |
GetCameraDisplacementDistance(CinemachineVirtualCameraBase)
See how far virtual camera has been moved by the confiner
Declaration
public float GetCameraDisplacementDistance(CinemachineVirtualCameraBase vcam)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The virtual camera in question. This might be different from the virtual camera that owns the confiner, in the event that the camera has children |
Returns
| Type | Description |
|---|---|
| float | True if the virtual camera has been repositioned |
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 |