Class CinemachineConfiner2D
An add-on module for Cinemachine Virtual 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.
The cached secondary polygon 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
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.
The cached secondary polygon is not a single polygon, but rather a family of polygons from which a member is chosen depending on the current size of the camera view. The number of polygons in this family will depend on the complexity of the input polygon, and the maximum expected camera view size. The MaxOrthoSize 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: Cinemachine
Assembly: Cinemachine.dll
Syntax
[AddComponentMenu("")]
[ExecuteAlways]
[DisallowMultipleComponent]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@2.9/manual/CinemachineConfiner2D.html")]
public class CinemachineConfiner2D : CinemachineExtensionFields
m_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 a 2D polygon or 2D composite collider.")]
public Collider2D m_BoundingShape2DField Value
| Type | Description |
|---|---|
| Collider2D |
m_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)]
public float m_DampingField Value
| Type | Description |
|---|---|
| float |
m_MaxWindowSize
To optimize computation and memory costs, set this to the largest view size that the camera is expected to have. The confiner will not compute a polygon cache for frustum sizes larger than this. This refers to the size in world units of the frustum at the confiner plane (for orthographic cameras, this is just the orthographic size). If set to 0, then this parameter is ignored and a polygon cache will be calculated for all potential window sizes.
Declaration
[Tooltip("To optimize computation and memory costs, set this to the largest view size that the camera is expected to have. The confiner will not compute a polygon cache for frustum sizes larger than this. This refers to the size in world units of the frustum at the confiner plane (for orthographic cameras, this is just the orthographic size). If set to 0, then this parameter is ignored and a polygon cache will be calculated for all potential window sizes.")]
public float m_MaxWindowSizeField Value
| Type | Description |
|---|---|
| float |
m_Padding
For large window sizes, the confiner will potentially generate polygons with zero area.
The padding may be used to add a small amount of area to these polygons, to prevent them from being
a series of disconnected dots.
Declaration
[Tooltip("For large window sizes, the confiner will potentially generate polygons with zero area. The padding may be used to add a small amount of area to these polygons, to prevent them from being a series of disconnected dots.")]
[Range(0, 100)]
public float m_PaddingField Value
| Type | Description |
|---|---|
| float |
Methods
InvalidateCache()
Invalidates cache and consequently trigger a rebake at next iteration.
Declaration
public void InvalidateCache()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 |
Overrides
ValidateCache(float)
Validates cache
Declaration
public bool ValidateCache(float cameraAspectRatio)Parameters
| Type | Name | Description |
|---|---|---|
| float | cameraAspectRatio | Aspect ratio of camera. |
Returns
| Type | Description |
|---|---|
| bool | Returns true if the cache could be validated. False, otherwise. |