FidelityFX CACAO

Include the interface for the backend of the API.

Enumerations

Name

Description

FfxCacaoDispatchFlagsBits

An enumeration of bit flags used when dispatching FidelityFX CACAO.
FFX_CACAO_SRV_SSAO_REMAP_TO_PONG = (1<<0) – A bit indicating the SRV maps to pong texture.
FFX_CACAO_UAV_SSAO_REMAP_TO_PONG = (1<<1) – A bit indicating the UAV maps to pong texture.

FfxCacaoInitializationFlagBits

An enumeration of bit flags used when creating a “FfxCacaoContext“. See “FfxCacaoContextDescription“.
FFX_CACAO_ENABLE_APPLY_SMART = (1<<0) – A bit indicating to use smart application.

FfxCacaoPass

An enumeration of the passes which constitutes the CACAO algorithm.
FFX_CACAO_PASS_CLEAR_LOAD_COUNTER = 0
FFX_CACAO_PASS_PREPARE_DOWNSAMPLED_DEPTHS = 1
FFX_CACAO_PASS_PREPARE_NATIVE_DEPTHS = 2
FFX_CACAO_PASS_PREPARE_DOWNSAMPLED_DEPTHS_AND_MIPS = 3
FFX_CACAO_PASS_PREPARE_NATIVE_DEPTHS_AND_MIPS = 4
FFX_CACAO_PASS_PREPARE_DOWNSAMPLED_NORMALS = 5
FFX_CACAO_PASS_PREPARE_NATIVE_NORMALS = 6
FFX_CACAO_PASS_PREPARE_DOWNSAMPLED_NORMALS_FROM_INPUT_NORMALS = 7
FFX_CACAO_PASS_PREPARE_NATIVE_NORMALS_FROM_INPUT_NORMALS = 8
FFX_CACAO_PASS_PREPARE_DOWNSAMPLED_DEPTHS_HALF = 9
FFX_CACAO_PASS_PREPARE_NATIVE_DEPTHS_HALF = 10
FFX_CACAO_PASS_GENERATE_Q0 = 11
FFX_CACAO_PASS_GENERATE_Q1 = 12
FFX_CACAO_PASS_GENERATE_Q2 = 13
FFX_CACAO_PASS_GENERATE_Q3 = 14
FFX_CACAO_PASS_GENERATE_Q3_BASE = 15
FFX_CACAO_PASS_GENERATE_IMPORTANCE_MAP = 16
FFX_CACAO_PASS_POST_PROCESS_IMPORTANCE_MAP_A = 17
FFX_CACAO_PASS_POST_PROCESS_IMPORTANCE_MAP_B = 18
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_1 = 19
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_2 = 20
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_3 = 21
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_4 = 22
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_5 = 23
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_6 = 24
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_7 = 25
FFX_CACAO_PASS_EDGE_SENSITIVE_BLUR_8 = 26
FFX_CACAO_PASS_APPLY_NON_SMART_HALF = 27
FFX_CACAO_PASS_APPLY_NON_SMART = 28
FFX_CACAO_PASS_APPLY = 29
FFX_CACAO_PASS_UPSCALE_BILATERAL_5X5 = 30
FFX_CACAO_PASS_COUNT – The number of passes in CACAO.

FfxCacaoQuality

The quality levels that FidelityFX CACAO can generate SSAO at. This affects the number of samples taken for generating SSAO.
FFX_CACAO_QUALITY_LOWEST = 0
FFX_CACAO_QUALITY_LOW = 1
FFX_CACAO_QUALITY_MEDIUM = 2
FFX_CACAO_QUALITY_HIGH = 3
FFX_CACAO_QUALITY_HIGHEST = 4

Structs

Name

Description

FfxCacaoBufferSizeInfo

A structure containing sizes of each of the buffers used by FidelityFX CACAO.

FfxCacaoConstants

A structure for the constant buffer used by FidelityFX CACAO.

FfxCacaoContext

A structure encapsulating the FidelityFX CACAO context.

FfxCacaoContextDescription

A structure encapsulating the parameters required to initialize FidelityFX CACAO.

FfxCacaoDispatchDescription

A structure encapsulating the parameters and resources required to dispatch FidelityFX CACAO.

FfxCacaoSettings

A structure for the settings used by FidelityFX CACAO. These settings may be updated with each draw call.

Functions

Return type

Description

FFX_API FfxErrorCode

ffxCacaoContextCreate ( FfxCacaoContext * context, const FfxCacaoContextDescription * contextDescription )
Create a FidelityFX CACAO context from the parameters programmed to the “FfxCacaoContextDescription“ structure.

FFX_API FfxErrorCode

ffxCacaoContextDispatch ( FfxCacaoContext * context, const FfxCacaoDispatchDescription * dispatchDescription )
Dispatches work to the FidelityFX CACAO context.

FFX_API FfxErrorCode

Destroy the FidelityFX CACAO context.

FFX_API FfxErrorCode

ffxCacaoUpdateSettings ( FfxCacaoContext * context, const FfxCacaoSettings * settings, const bool useDownsampledSsao )
Updates the settings used by CACAO.

FFX_API FfxVersionNumber

Queries the effect version number.

Macros

Name

Description

FFX_CACAO_APPLY_HEIGHT 8

Height of the APPLY pass tile size.

FFX_CACAO_APPLY_WIDTH 8

Width of the APPLY pass tile size.

FFX_CACAO_BILATERAL_UPSCALE_HEIGHT 8

Height of the BILATERAL_UPSCALE pass tile size.

FFX_CACAO_BILATERAL_UPSCALE_WIDTH 8

Width of the BILATERAL_UPSCALE pass tile size.

FFX_CACAO_BLUR_HEIGHT 16

Height of the BLUR pass tile size.

FFX_CACAO_BLUR_WIDTH 16

Width of the BLUR pass tile size.

FFX_CACAO_CONTEXT_COUNT 1

FidelityFX CACAO context count.

FFX_CACAO_CONTEXT_SIZE (301054)

The size of the context specified in 32bit values.

FFX_CACAO_GENERATE_HEIGHT 8

Height of the GENERATE pass tile size.

FFX_CACAO_GENERATE_SPARSE_HEIGHT 16

Height of the GENERATE_SPARSE pass tile size.

FFX_CACAO_GENERATE_SPARSE_WIDTH 4

Width of the GENERATE_SPARSE pass tile size.

FFX_CACAO_GENERATE_WIDTH 8

Width of the GENERATE pass tile size.

FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_HEIGHT 8

Height of the PREPARE_DEPTHS_AND_MIPS pass tile size.

FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_WIDTH 8

Width of the PREPARE_DEPTHS_AND_MIPS pass tile size.

FFX_CACAO_PREPARE_DEPTHS_HALF_HEIGHT 8

Height of the PREPARE_DEPTHS_HALF pass tile size.

FFX_CACAO_PREPARE_DEPTHS_HALF_WIDTH 8

Width of the PREPARE_DEPTHS_HALF pass tile size.

FFX_CACAO_PREPARE_DEPTHS_HEIGHT 8

Height of the PREPARE_DEPTHS pass tile size.

FFX_CACAO_PREPARE_DEPTHS_WIDTH 8

Width of the PREPARE_DEPTHS pass tile size.

FFX_CACAO_PREPARE_NORMALS_HEIGHT 8

Height of the PREPARE_NORMALS pass tile size.

FFX_CACAO_PREPARE_NORMALS_WIDTH 8

Width of the PREPARE_NORMALS pass tile size.

FFX_CACAO_VERSION_MAJOR (1)

FidelityFX CACAO major version.

FFX_CACAO_VERSION_MINOR (4)

FidelityFX CACAO minor version.

FFX_CACAO_VERSION_PATCH (0)

FidelityFX CACAO patch version.

IMPORTANCE_MAP_A_HEIGHT 8

Height of the IMPORTANCE_MAP_A pass tile size.

IMPORTANCE_MAP_A_WIDTH 8

Width of the IMPORTANCE_MAP_A pass tile size.

IMPORTANCE_MAP_B_HEIGHT 8

Height of the IMPORTANCE_MAP_B pass tile size.

IMPORTANCE_MAP_B_WIDTH 8

Width of the IMPORTANCE_MAP_B pass tile size.

IMPORTANCE_MAP_HEIGHT 8

Height of the IMPORTANCE_MAP pass tile size.

IMPORTANCE_MAP_WIDTH 8

Width of the IMPORTANCE_MAP pass tile size.

PREPARE_NORMALS_FROM_INPUT_NORMALS_HEIGHT 8

Height of the PREPARE_NORMALS_FROM_INPUT_NORMALS pass tile size.

PREPARE_NORMALS_FROM_INPUT_NORMALS_WIDTH 8

Width of the PREPARE_NORMALS_FROM_INPUT_NORMALS pass tile size.

Detailed description

Include the interface for the backend of the API.

FidelityFX Combined Adaptive Compute Ambient Occlusion runtime library.

Global variables

Copied!

static const FfxCacaoSettings  FFX_CACAO_DEFAULT_SETTINGS = {    1.2f,   1.0f,   1.50f,      0.98f,      0.06f,      50.0f,      300.0f,     FFX_CACAO_QUALITY_HIGHEST ,    0.45f,      2,      0.98f,      0.0f,   0.0f,   0.5f,   false,      5.0f,   0.01f, }

Global functions

ffxCacaoContextCreate

Copied!

FFX_API  FfxErrorCode  ffxCacaoContextCreate (
    FfxCacaoContext * context,
    const FfxCacaoContextDescription * contextDescription
)

Create a FidelityFX CACAO context from the parameters programmed to the FfxCacaoContextDescription structure.

The context structure is the main object used to interact with the CACAO API, and is responsible for the management of the internal resources used by the CACAO 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 CACAO to function. Depending on the precise configuration used when creating the FfxCacaoContext a different set of resources and pipelines might be requested via the callback functions.

The FfxCacaoContext should be destroyed when use of it is completed, typically when an application is unloaded or CACAO upscaling is disabled by a user. To destroy the CACAO context you should call ffxCacaoContextDestroy.

Parameters:

pContext

A pointer to a FfxCacaoContext structure to populate.

pContextDescription

A pointer to a FfxCacaoContextDescription 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 FfxCacaoContextDescription.callbacks was not fully specified.

FFX_ERROR_BACKEND_API_ERROR

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


ffxCacaoContextDispatch

Copied!

FFX_API  FfxErrorCode  ffxCacaoContextDispatch (
    FfxCacaoContext * context,
    const FfxCacaoDispatchDescription * dispatchDescription
)

Dispatches work to the FidelityFX CACAO context.

Parameters:

pContext

A pointer to a FfxCacaoContext structure to populate.

pDispatchDescription

A pointer to a FfxCacaoDispatchDescription 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.


ffxCacaoContextDestroy

Copied!

FFX_API  FfxErrorCode  ffxCacaoContextDestroy (FfxCacaoContext * context)

Destroy the FidelityFX CACAO context.

Parameters:

pContext

A pointer to a FfxCacaoContext structure to destroy.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_CODE_NULL_POINTER

The operation failed because context was NULL.


ffxCacaoUpdateSettings

Copied!

FFX_API  FfxErrorCode  ffxCacaoUpdateSettings (
    FfxCacaoContext * context,
    const FfxCacaoSettings * settings,
    const bool useDownsampledSsao
)

Updates the settings used by CACAO.

Parameters:

context

A pointer to a FfxCacaoContext structure to change settings for.

settings

A pointer to a FfxCacaoSettings structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_CODE_NULL_POINTER

The operation failed because either context or settings was NULL.


ffxCacaoGetEffectVersion

Copied!

FFX_API  FfxVersionNumber  ffxCacaoGetEffectVersion ()

Queries the effect version number.

Returns:

The SDK version the effect was built with.


Macros

FFX_CACAO_APPLY_HEIGHT

Copied!

#define FFX_CACAO_APPLY_HEIGHT 8

Height of the APPLY pass tile size.


FFX_CACAO_APPLY_WIDTH

Copied!

#define FFX_CACAO_APPLY_WIDTH 8

Width of the APPLY pass tile size.


FFX_CACAO_BILATERAL_UPSCALE_HEIGHT

Copied!

#define FFX_CACAO_BILATERAL_UPSCALE_HEIGHT 8

Height of the BILATERAL_UPSCALE pass tile size.


FFX_CACAO_BILATERAL_UPSCALE_WIDTH

Copied!

#define FFX_CACAO_BILATERAL_UPSCALE_WIDTH 8

Width of the BILATERAL_UPSCALE pass tile size.


FFX_CACAO_BLUR_HEIGHT

Copied!

#define FFX_CACAO_BLUR_HEIGHT 16

Height of the BLUR pass tile size.


FFX_CACAO_BLUR_WIDTH

Copied!

#define FFX_CACAO_BLUR_WIDTH 16

Width of the BLUR pass tile size.


FFX_CACAO_CONTEXT_COUNT

Copied!

#define FFX_CACAO_CONTEXT_COUNT 1

FidelityFX CACAO context count.

Defines the number of internal effect contexts required by CACAO.


FFX_CACAO_CONTEXT_SIZE

Copied!

#define FFX_CACAO_CONTEXT_SIZE (301054)

The size of the context specified in 32bit values.


FFX_CACAO_GENERATE_HEIGHT

Copied!

#define FFX_CACAO_GENERATE_HEIGHT 8

Height of the GENERATE pass tile size.


FFX_CACAO_GENERATE_SPARSE_HEIGHT

Copied!

#define FFX_CACAO_GENERATE_SPARSE_HEIGHT 16

Height of the GENERATE_SPARSE pass tile size.


FFX_CACAO_GENERATE_SPARSE_WIDTH

Copied!

#define FFX_CACAO_GENERATE_SPARSE_WIDTH 4

Width of the GENERATE_SPARSE pass tile size.


FFX_CACAO_GENERATE_WIDTH

Copied!

#define FFX_CACAO_GENERATE_WIDTH 8

Width of the GENERATE pass tile size.


FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_HEIGHT

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_HEIGHT 8

Height of the PREPARE_DEPTHS_AND_MIPS pass tile size.


FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_WIDTH

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_AND_MIPS_WIDTH 8

Width of the PREPARE_DEPTHS_AND_MIPS pass tile size.


FFX_CACAO_PREPARE_DEPTHS_HALF_HEIGHT

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_HALF_HEIGHT 8

Height of the PREPARE_DEPTHS_HALF pass tile size.


FFX_CACAO_PREPARE_DEPTHS_HALF_WIDTH

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_HALF_WIDTH 8

Width of the PREPARE_DEPTHS_HALF pass tile size.


FFX_CACAO_PREPARE_DEPTHS_HEIGHT

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_HEIGHT 8

Height of the PREPARE_DEPTHS pass tile size.


FFX_CACAO_PREPARE_DEPTHS_WIDTH

Copied!

#define FFX_CACAO_PREPARE_DEPTHS_WIDTH 8

Width of the PREPARE_DEPTHS pass tile size.


FFX_CACAO_PREPARE_NORMALS_HEIGHT

Copied!

#define FFX_CACAO_PREPARE_NORMALS_HEIGHT 8

Height of the PREPARE_NORMALS pass tile size.


FFX_CACAO_PREPARE_NORMALS_WIDTH

Copied!

#define FFX_CACAO_PREPARE_NORMALS_WIDTH 8

Width of the PREPARE_NORMALS pass tile size.


FFX_CACAO_VERSION_MAJOR

Copied!

#define FFX_CACAO_VERSION_MAJOR (1)

FidelityFX CACAO major version.


FFX_CACAO_VERSION_MINOR

Copied!

#define FFX_CACAO_VERSION_MINOR (4)

FidelityFX CACAO minor version.


FFX_CACAO_VERSION_PATCH

Copied!

#define FFX_CACAO_VERSION_PATCH (0)

FidelityFX CACAO patch version.


IMPORTANCE_MAP_A_HEIGHT

Copied!

#define IMPORTANCE_MAP_A_HEIGHT 8

Height of the IMPORTANCE_MAP_A pass tile size.


IMPORTANCE_MAP_A_WIDTH

Copied!

#define IMPORTANCE_MAP_A_WIDTH 8

Width of the IMPORTANCE_MAP_A pass tile size.


IMPORTANCE_MAP_B_HEIGHT

Copied!

#define IMPORTANCE_MAP_B_HEIGHT 8

Height of the IMPORTANCE_MAP_B pass tile size.


IMPORTANCE_MAP_B_WIDTH

Copied!

#define IMPORTANCE_MAP_B_WIDTH 8

Width of the IMPORTANCE_MAP_B pass tile size.


IMPORTANCE_MAP_HEIGHT

Copied!

#define IMPORTANCE_MAP_HEIGHT 8

Height of the IMPORTANCE_MAP pass tile size.


IMPORTANCE_MAP_WIDTH

Copied!

#define IMPORTANCE_MAP_WIDTH 8

Width of the IMPORTANCE_MAP pass tile size.


PREPARE_NORMALS_FROM_INPUT_NORMALS_HEIGHT

Copied!

#define PREPARE_NORMALS_FROM_INPUT_NORMALS_HEIGHT 8

Height of the PREPARE_NORMALS_FROM_INPUT_NORMALS pass tile size.


PREPARE_NORMALS_FROM_INPUT_NORMALS_WIDTH

Copied!

#define PREPARE_NORMALS_FROM_INPUT_NORMALS_WIDTH 8

Width of the PREPARE_NORMALS_FROM_INPUT_NORMALS pass tile size.