FidelityFX DoF

FidelityFX Depth of Field runtime library.

Enumerations

Name

Description

FfxDofInitializationFlagBits
An enumeration of bit flags used when creating a “FfxDofContext“. See “FfxDofContextDescription“. Curently, no flags exist.
FFX_DOF_REVERSE_DEPTH = (1 << 0) – A bit indicating whether input depth is reversed (1 is closest)
FFX_DOF_OUTPUT_PRE_INIT = (1 << 1) – A bit indicating whether the output is pre-initialized with the input color (e.g. it is the same texture)
FFX_DOF_DISABLE_RING_MERGE = (1 << 2) – A bit indicating whether to disable merging kernel rings.

FfxDofPass
An enumeration of the passes which constitute the DoF algorithm.
FFX_DOF_PASS_DOWNSAMPLE_DEPTH = 0 – A pass which downsamples the depth buffer.
FFX_DOF_PASS_DOWNSAMPLE_COLOR = 1 – A pass which downsamples the color buffer.
FFX_DOF_PASS_DILATE = 2 – A pass which dilates the depth tile buffer.
FFX_DOF_PASS_BLUR = 3 – A pass which performs the depth of field blur.
FFX_DOF_PASS_COMPOSITE = 4 – A pass which combines the blurred images with the sharp input.
FFX_DOF_PASS_COUNT – The number of passes in DOF.

Structs

Name

Description

FfxDofContext
A structure encapsulating the FidelityFX Depth of Field context.

FfxDofContextDescription
A structure encapsulating the parameters required to initialize FidelityFX Depth of Field.

FfxDofDispatchDescription
A structure encapsulating the parameters for dispatching of FidelityFX Depth of Field.

Functions

Return type

Description

static float
ffxDofCalculateCocScale ( float aperture, float focus, float focalLength, float conversion, float proj33, float proj34, float proj43 )
Calculates the scale parameter in the thin lens model according to lens and projection parameters.

static float
ffxDofCalculateCocBias ( float aperture, float focus, float focalLength, float conversion, float proj33, float proj34, float proj43 )
Calculates the bias parameter in the thin lens model according to lens and projection parameters.

FFX_API FfxErrorCode
ffxDofContextCreate ( FfxDofContext * pContext, const FfxDofContextDescription * pContextDescription )
Create a FidelityFX Depth of Field context from the parameters programmed to the “FfxDofContextDescription“ structure.

FFX_API FfxErrorCode
ffxDofContextDispatch ( FfxDofContext * pContext, const FfxDofDispatchDescription * pDispatchDescription )
Dispatches work to the FidelityFX DoF context.

FFX_API FfxErrorCode
ffxDofContextDestroy (FfxDofContext * pContext)
Destroy the FidelityFX DoF context.

FFX_API FfxVersionNumber
ffxDofGetEffectVersion ()
Queries the effect version number.

Macros

Name

Description

FFX_DOF_CONTEXT_COUNT 1
FidelityFX DOF context count.

FFX_DOF_CONTEXT_SIZE (45664)
The size of the context specified in 32bit values.

FFX_DOF_VERSION_MAJOR (1)
FidelityFX DOF major version.

FFX_DOF_VERSION_MINOR (1)
FidelityFX DOF minor version.

FFX_DOF_VERSION_PATCH (0)
FidelityFX DOF patch version.

Detailed description

FidelityFX Depth of Field runtime library.

Global functions

ffxDofCalculateCocScale

Copied!

static float ffxDofCalculateCocScale (
    float aperture,
    float focus,
    float focalLength,
    float conversion,
    float proj33,
    float proj34,
    float proj43
)

Calculates the scale parameter in the thin lens model according to lens and projection parameters.

Parameters:

aperture

Aperture radius in view space units

focus

Distance to focus plane in view space units

focalLength

Lens focal length in view space units

conversion

Conversion factor for view units to pixels (i.e. image width in pixels / sensor size)

proj33

Element (3,3) of the projection matrix (z range scale)

proj34

Element (3,4) of the projection matrix (z range offset)

proj43

Element (4,3) of the projection matrix (typically 1 or -1)

ffxDofCalculateCocBias

Copied!

static float ffxDofCalculateCocBias (
    float aperture,
    float focus,
    float focalLength,
    float conversion,
    float proj33,
    float proj34,
    float proj43
)

Calculates the bias parameter in the thin lens model according to lens and projection parameters.

Parameters:

aperture

Aperture radius in view space units

focus

Distance to focus plane in view space units

focalLength

Lens focal length in view space units

conversion

Conversion factor for view units to pixels (i.e. image width in pixels / sensor size)

proj33

Element (3,3) of the projection matrix (a.k.a. z range scale)

proj34

Element (3,4) of the projection matrix (a.k.a. z range offset)

proj43

Element (4,3) of the projection matrix (typically 1 or -1)

ffxDofContextCreate

Copied!

FFX_API  FfxErrorCode  ffxDofContextCreate (
    FfxDofContext * pContext,
    const FfxDofContextDescription * pContextDescription
)

Create a FidelityFX Depth of Field context from the parameters programmed to the FfxDofContextDescription structure.

The context structure is the main object used to interact with the Depth of Field API, and is responsible for the management of the internal resources used by the DoF algorithm. When this API is called, multiple calls will be made via the pointers contained in the backendInterface structure. This backend will attempt to retrieve the device capabilities, and create the internal resources, and pipelines required by DoF to function. Depending on the precise configuration used when creating the FfxDofContext a different set of resources and pipelines might be requested via the callback functions.

The FfxDofContext should be destroyed when use of it is completed, typically when an application is unloaded or DoF is disabled by a user. To destroy the DoF context you should call ffxDofContextDestroy.

Parameters:

pContext

A pointer to a FfxDofContext structure to populate.

pContextDescription

A pointer to a FfxDofContextDescription structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_CODE_NULL_POINTER

The operation failed because either context or contextDescription was NULL.

FFX_ERROR_INCOMPLETE_INTERFACE

The operation failed because the FfxDofContextDescription.callbacks was not fully specified.

FFX_ERROR_BACKEND_API_ERROR

The operation failed because of an error returned from the backend.

ffxDofContextDispatch

Copied!

FFX_API  FfxErrorCode  ffxDofContextDispatch (
    FfxDofContext * pContext,
    const FfxDofDispatchDescription * pDispatchDescription
)

Dispatches work to the FidelityFX DoF context.

Parameters:

pContext

A pointer to a FfxDofContext structure.

pDispatchDescription

A pointer to a FfxDofDispatchDescription structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_CODE_NULL_POINTER

The operation failed because either context or dispatchDescription was NULL.

FFX_ERROR_BACKEND_API_ERROR

The operation failed because of an error returned from the backend.

ffxDofContextDestroy

Copied!

FFX_API  FfxErrorCode  ffxDofContextDestroy (FfxDofContext * pContext)

Destroy the FidelityFX DoF context.

Parameters:

pContext

A pointer to a FfxDofContext structure to destroy.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_CODE_NULL_POINTER

The operation failed because context was NULL.

ffxDofGetEffectVersion

Copied!

FFX_API  FfxVersionNumber  ffxDofGetEffectVersion ()

Queries the effect version number.

Returns:

The SDK version the effect was built with.

Macros

FFX_DOF_CONTEXT_COUNT

Copied!

#define FFX_DOF_CONTEXT_COUNT 1

FidelityFX DOF context count.

Defines the number of internal effect contexts required by DOF

FFX_DOF_CONTEXT_SIZE

Copied!

#define FFX_DOF_CONTEXT_SIZE (45664)

The size of the context specified in 32bit values.

FFX_DOF_VERSION_MAJOR

Copied!

#define FFX_DOF_VERSION_MAJOR (1)

FidelityFX DOF major version.

FFX_DOF_VERSION_MINOR

Copied!

#define FFX_DOF_VERSION_MINOR (1)

FidelityFX DOF minor version.

FFX_DOF_VERSION_PATCH

Copied!

#define FFX_DOF_VERSION_PATCH (0)

FidelityFX DOF patch version.