AutoDepthOfField component

Access the active AutoDepthOfField component at runtime, read focus diagnostics, update diagnostics, refresh volumes, and set the global focal length through the C# API.

AutoDepthOfField API

HIBIKI entertainment's AutoDepthOfField component exposes the runtime API for accessing autofocus state, reading diagnostics, refreshing override volumes, and configuring the global focal length.

Accessing the active component

PBADOF enforces single active output ownership. Only one enabled AutoDepthOfField component owns the depth-of-field output at a time. Additional enabled components become passive and report that state through readiness diagnostics.

Use the static TryGetCurrent method when you need to safely retrieve the active component.

if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    // The active output-owning component
    float distance = dof.CurrentFocusedDistance;
}

Only the active output-owning component writes the depth-of-field result. Check CurrentReadiness when diagnosing a component that has become passive.

Static members

Member	Type	Description
`TryGetCurrent(out AutoDepthOfField)`	Method (static)	Safely gets the active output-owning component. Returns `true` if one is available.
`Current`	Property (static)	The active output-owning component. `null` if no component owns the output.

Instance properties

Property	Type	Description
`Data`	`AutoDepthOfFieldData`	Serialized focus, lens, filtering, glass, Smart Subject, and Ground Assist configuration for this component.
`Preset`	`DepthOfFieldPreset`	The preset currently assigned to this component.
`CurrentFocusedDistance`	`float`	The focus distance selected by the solver in the latest solve.
`AppliedFocusDistance`	`float`	The focus distance actually applied to the render pipeline after smoothing and clamping.
`CurrentFocusSnapshot`	`FocusDebugSnapshot`	Detailed diagnostic information about the latest focus solve, including accepted and rejected rays, confidence data, Smart Subject tracking state, and Ground Assist surface.
`CurrentReadiness`	Readiness info	The current readiness state, reporting pipeline, camera, and output status.

Instance methods

Method	Parameters	Description
`UpdateDiagnosticsNow()`	None	Forces an immediate diagnostic update. Use when you need fresh readiness or focus snapshot data outside the normal update cycle.
`RefreshOverrideVolumes()`	None	Rebuilds and refreshes the override volume database. Call this after adding or removing volumes at runtime to ensure the resolver sees the changes.
`SetGlobalFocalLength(float value)`	`value`: focal length in millimetres	Sets the global focal length on the active component.
`SetFocusHint(target, strength)`	`target`: AutoDepthOfFieldFocusTarget, `strength`: float (default 4f)	Sets a soft focus preference for Smart Subject mode. The hinted target must still be hit by a valid ray and pass all filters.
`ClearFocusHint()`	None	Removes the current focus hint and resets its strength to zero.
`ResetFocusTracking(preserveLens)`	`preserveLens`: bool (default true)	Clears locked subject, challenger, and grace timers. Call after camera cuts or scene transitions to avoid holding a stale subject.

Usage examples

The following examples show common runtime operations: reading the current focus state, refreshing volumes after runtime changes, and setting the focal length.

if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    // Read the solver's selected distance
    float selected = dof.CurrentFocusedDistance;

    // Read the distance actually applied after smoothing
    float applied = dof.AppliedFocusDistance;

    // Read diagnostics
    var snapshot = dof.CurrentFocusSnapshot;
    var readiness = dof.CurrentReadiness;
}

Smart Subject mode

The following examples show common Smart Subject operations: setting a focus hint, reading tracking diagnostics, and resetting tracking after a camera cut.

if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    // Bias the solver towards a specific subject
    var target = myCharacter.GetComponent<AutoDepthOfFieldFocusTarget>();
    dof.SetFocusHint(target, strength: 4f);
}

if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    var snapshot = dof.CurrentFocusSnapshot;

    // Read Smart Subject tracking state
    var locked = snapshot.LockedSubject;
    var challenger = snapshot.ChallengerSubject;
    var switchReason = snapshot.SwitchReason;

    Debug.Log($"Locked: {locked}, Challenger: {challenger}, Reason: {switchReason}");
}

if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    // Clear the focus hint
    dof.ClearFocusHint();

    // Reset tracking after a camera cut to avoid holding a stale subject
    dof.ResetFocusTracking(preserveLensPosition: true);
}

CurrentFocusedDistance reflects the solver's raw selection. AppliedFocusDistance reflects the final value after transition smoothing and distance clamping. If the effect appears to lag, check the transition response settings in the component's Data.

AutoDepthOfFieldData: Serialized configuration for focus, lens, filtering, glass, Smart Subject, and Ground Assist behaviour. See Smart Subject and Ground Assist properties below.
AutoDepthOfFieldFocusTarget: MonoBehaviour that marks a GameObject and its children as one stable semantic subject for Smart Subject mode. See Override volume and focus proxy API.
AutoDepthOfFieldEffectiveSettings: Resolved settings used by the solver.
FocusDebugSnapshot: Diagnostic snapshot of the latest solve, including Smart Subject tracking state and Ground Assist surface.
DepthOfFieldPreset: Reusable preset asset.

Smart Subject and Ground Assist properties

The following AutoDepthOfFieldData properties control Smart Subject mode and Ground Assist behaviour. Access them through the Data property on the active AutoDepthOfField component.

Smart Subject properties

Property	Type	Default	Description
`FocusSelectionMode`	`FocusSelectionMode`	Legacy	Selects the focus-selection strategy. `Legacy` (0) uses depth-cluster sorting; `SmartSubject` (1) groups ray hits by semantic target.
`ChallengerAdvantage`	`float`	1.25	Minimum score ratio (challenger divided by locked) required to initiate a subject switch. Clamped to 1.0 minimum.
`SwitchConfirmationTime`	`float`	0.20 s	Duration the challenger must remain stronger before the solver switches subjects.
`LostSubjectGraceTime`	`float`	0.30 s	Grace period holding focus after the locked subject disappears.
`FocusTagBehavior`	`FocusTagBehavior`	Disabled	How configured tags are interpreted: `Disabled` (0), `Prefer` (1), or `Require` (2).
`FocusExclusionRoot`	`Transform`	none	Optional hierarchy excluded from autofocus and ground-assist checks.

Ground Assist properties

Property	Type	Default	Description
`GroundAssistEnabled`	`bool`	true	Enables Ground Assist. Backed by `m_cameraPitchLimit.overrideState`.
`GroundLayers`	`LayerMask`	layer 1	Physics layers that count as valid ground.
`MaximumGroundSlope`	`float` (0–89 degrees)	60 degrees	Rejects surfaces steeper than this angle.
`CameraPitchLimit`	`ClampedFloatParameter`	35 degrees	Inspector label "Downward Activation Angle". Range 1–90 degrees.

On startup with legacy data, MigrateLegacyGroundFallback() copies interaction layers to Ground Layers and sets MaximumGroundSlope to 60 degrees. This happens automatically.

Next steps

See the AutoDepthOfFieldAPI static API for convenience and compatibility methods, or the Override volume and focus proxy API for volume and proxy component interfaces.

Was this page helpful?