Class CinemachineDeoccluder
An add-on module for CinemachineCamera that post-processes the final position of the camera. Based on the supplied settings, the Deoccluder will attempt to preserve the line of sight with the LookAt target of the camera by moving away from objects that will obstruct the view.
Additionally, the Deoccluder can be used to assess the shot quality and report this as a field in the camera State.
Inheritance
Implements
Inherited Members
Namespace: Unity.Cinemachine
Assembly: Unity.Cinemachine.dll
Syntax
[AddComponentMenu("Cinemachine/Procedural/Extensions/Cinemachine Deoccluder")]
[ExecuteAlways]
[DisallowMultipleComponent]
[RequiredTarget(RequiredTargetAttribute.RequiredTargets.Tracking)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.cinemachine@3.1/manual/CinemachineDeoccluder.html")]
public class CinemachineDeoccluder : CinemachineExtension, IShotQualityEvaluatorFields
AvoidObstacles
Settings for deoccluding the camera when obstacles are present
Declaration
[FoldoutWithEnabledButton("Enabled")]
public CinemachineDeoccluder.ObstacleAvoidance AvoidObstaclesField Value
| Type | Description |
|---|---|
| CinemachineDeoccluder.ObstacleAvoidance |
CollideAgainst
Objects on these layers will be detected.
Declaration
[Tooltip("Objects on these layers will be detected")]
public LayerMask CollideAgainstField Value
| Type | Description |
|---|---|
| LayerMask |
IgnoreTag
Obstacles with this tag will be ignored. It is a good idea to set this field to the target's tag
Declaration
[Tooltip("Obstacles with this tag will be ignored. It is a good idea to set this field to the target's tag")]
public string IgnoreTagField Value
| Type | Description |
|---|---|
| string |
MinimumDistanceFromTarget
Obstacles closer to the target than this will be ignored
Declaration
[Tooltip("Obstacles closer to the target than this will be ignored")]
public float MinimumDistanceFromTargetField Value
| Type | Description |
|---|---|
| float |
ShotQualityEvaluation
If enabled, will evaluate shot quality based on target distance and occlusion
Declaration
[FoldoutWithEnabledButton("Enabled")]
public CinemachineDeoccluder.QualityEvaluation ShotQualityEvaluationField Value
| Type | Description |
|---|---|
| CinemachineDeoccluder.QualityEvaluation |
TransparentLayers
Objects on these layers will never obstruct view of the target.
Declaration
[Tooltip("Objects on these layers will never obstruct view of the target")]
public LayerMask TransparentLayersField Value
| Type | Description |
|---|---|
| LayerMask |
Methods
CameraWasDisplaced(CinemachineVirtualCameraBase)
See whether the virtual camera has been moved nby the collider
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 deoccluder, in the event that the camera has children |
Returns
| Type | Description |
|---|---|
| bool | True if the virtual camera has been displaced due to collision or target obstruction |
DebugCollisionPaths(List<List<Vector3>>, List<List<Collider>>)
Debug API for discovering which objects are occluding the camera, and the path taken by the camera to ist deoccluded position. Note that this information is only collected while running in the editor. In the build, the return values will always be empty. This is for performance reasons.
Declaration
public void DebugCollisionPaths(List<List<Vector3>> paths, List<List<Collider>> obstacles)Parameters
| Type | Name | Description |
|---|---|---|
| List<List<Vector3>> | paths | A container to hold lists of points representing the camera path. |
| List<List<Collider>> | obstacles | A container to hold lists of Colliders representing the obstacles encountered. |
GetCameraDisplacementDistance(CinemachineVirtualCameraBase)
See how far the virtual camera wa moved nby the collider
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 deoccluder, in the event that the camera has children |
Returns
| Type | Description |
|---|---|
| float | True if the virtual camera has been displaced due to collision or target obstruction |
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
IsTargetObscured(CinemachineVirtualCameraBase)
See whether an object is blocking the camera's view of the target
Declaration
public bool IsTargetObscured(CinemachineVirtualCameraBase vcam)Parameters
| Type | Name | Description |
|---|---|---|
| CinemachineVirtualCameraBase | vcam | The virtual camera in question. This might be different from the virtual camera that owns the deoccluder, in the event that the camera has children |
Returns
| Type | Description |
|---|---|
| bool | True if something is blocking the view |
OnDestroy()
Cleanup
Declaration
protected override void OnDestroy()Overrides
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 | Virtual 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 collision resolution and shot evaluation
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 |