FidelityFX FSR2

FfxFsr2Message

typedef void (*FfxFsr2Message )(
    FfxMsgType type,
    const wchar_t *message
    )

Pass a string message.

Used for debug messages.

Parameters:

ffxFsr2ContextCreate

FFX_API  FfxErrorCode  ffxFsr2ContextCreate (
    FfxFsr2Context * pContext,
    const FfxFsr2ContextDescription * pContextDescription
)

Create a FidelityFX Super Resolution 2 context from the parameters programmed to the FfxFsr2CreateParams structure.

The context structure is the main object used to interact with the FSR2 API, and is responsible for the management of the internal resources used by the FSR2 algorithm. When this API is called, multiple calls will be made via the pointers contained in the callbacks structure. These callbacks will attempt to retreive the device capabilities, and create the internal resources, and pipelines required by FSR2’s frame-to-frame function. Depending on the precise configuration used when creating the FfxFsr2Context a different set of resources and pipelines might be requested via the callback functions.

The flags included in the flags field of FfxFsr2Context how match the configuration of your application as well as the intended use of FSR2. It is important that these flags are set correctly (as well as a correct programmed FfxFsr2DispatchDescription) to ensure correct operation. It is recommended to consult the overview documentation for further details on how FSR2 should be integerated into an application.

When the FfxFsr2Context is created, you should use the ffxFsr2ContextDispatch function each frame where FSR2 upscaling should be applied. See the documentation of ffxFsr2ContextDispatch for more details.

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

Parameters:

Return values:

ffxFsr2ContextGetGpuMemoryUsage

FFX_API  FfxErrorCode  ffxFsr2ContextGetGpuMemoryUsage (
    FfxFsr2Context * pContext,
    FfxEffectMemoryUsage * pVramUsage
)

Get GPU memory usage of the FidelityFX Super Resolution context.

Parameters:

Return values:

ffxFsr2ContextDispatch

FFX_API  FfxErrorCode  ffxFsr2ContextDispatch (
    FfxFsr2Context * pContext,
    const FfxFsr2DispatchDescription * pDispatchDescription
)

Dispatch the various passes that constitute FidelityFX Super Resolution 2.

FSR2 is a composite effect, meaning that it is compromised of multiple constituent passes (implemented as one or more clears, copies and compute dispatches). The ffxFsr2ContextDispatch function is the function which (via the use of the functions contained in the callbacks field of the FfxFsr2Context structure) utlimately generates the sequence of graphics API calls required each frame.

As with the creation of the FfxFsr2Context correctly programming the FfxFsr2DispatchDescription is key to ensuring the correct operation of FSR2. It is particularly important to ensure that camera jitter is correctly applied to your application’s projection matrix (or camera origin for raytraced applications). FSR2 provides the ffxFsr2GetJitterPhaseCount and ffxFsr2GetJitterOffset entry points to help applications correctly compute the camera jitter. Whatever jitter pattern is used by the application it should be correctly programmed to the jitterOffset field of the dispatchDescription structure. For more guidance on camera jitter please consult the documentation for ffxFsr2GetJitterOffset as well as the accompanying overview documentation for FSR2.

Parameters:

Return values:

ffxFsr2ContextGenerateReactiveMask

FFX_API  FfxErrorCode  ffxFsr2ContextGenerateReactiveMask (
    FfxFsr2Context * pContext,
    const FfxFsr2GenerateReactiveDescription * pParams
)

A helper function generate a Reactive mask from an opaque only texure and one containing translucent objects.

Parameters:

Return values:

ffxFsr2ContextDestroy

FFX_API  FfxErrorCode  ffxFsr2ContextDestroy (FfxFsr2Context * pContext)

Destroy the FidelityFX Super Resolution context.

Parameters:

Return values:

ffxFsr2GetUpscaleRatioFromQualityMode

FFX_API  float ffxFsr2GetUpscaleRatioFromQualityMode (FfxFsr2QualityMode  qualityMode)

Get the upscale ratio from the quality mode.

The following table enumerates the mapping of the quality modes to per-dimension scaling ratios.

Passing an invalid qualityMode will return 0.0f.

Parameters:

Returns:

The upscaling the per-dimension upscaling ratio for qualityMode according to the table above.

ffxFsr2GetRenderResolutionFromQualityMode

FFX_API  FfxErrorCode  ffxFsr2GetRenderResolutionFromQualityMode (
    uint32_t* pRenderWidth,
    uint32_t* pRenderHeight,
    uint32_t displayWidth,
    uint32_t displayHeight,
    FfxFsr2QualityMode  qualityMode
)

A helper function to calculate the rendering resolution from a target resolution and desired quality level.

This function applies the scaling factor returned by ffxFsr2GetUpscaleRatioFromQualityMode to each dimension.

Parameters:

Return values:

ffxFsr2GetJitterPhaseCount

FFX_API  int32_t ffxFsr2GetJitterPhaseCount (
    int32_t renderWidth,
    int32_t displayWidth
)

A helper function to calculate the jitter phase count from display resolution.

For more detailed information about the application of camera jitter to your application’s rendering please refer to the ffxFsr2GetJitterOffset function.

The table below shows the jitter phase count which this function would return for each of the quality presets.

Parameters:

Returns:

The jitter phase count for the scaling factor between renderWidth and displayWidth.

ffxFsr2GetJitterOffset

FFX_API  FfxErrorCode  ffxFsr2GetJitterOffset (
    float* pOutX,
    float* pOutY,
    int32_t index,
    int32_t phaseCount
)

A helper function to calculate the subpixel jitter offset.

FSR2 relies on the application to apply sub-pixel jittering while rendering. This is typically included in the projection matrix of the camera. To make the application of camera jitter simple, the FSR2 API provides a small set of utility function which computes the sub-pixel jitter offset for a particular frame within a sequence of separate jitter offsets. To begin, the index within the jitter phase must be computed. To calculate the sequence’s length, you can call the ffxFsr2GetJitterPhaseCount function. The index should be a value which is incremented each frame modulo the length of the sequence computed by ffxFsr2GetJitterPhaseCount. The index within the jitter phase is passed to ffxFsr2GetJitterOffset via the index parameter.

This function uses a Halton(2,3) sequence to compute the jitter offset. The ultimate index used for the sequence is index % phaseCount.

It is important to understand that the values returned from the ffxFsr2GetJitterOffset function are in unit pixel space, and in order to composite this correctly into a projection matrix we must convert them into projection offsets. This is done as per the pseudo code listing which is shown below.

const int32_t jitterPhaseCount = ffxFsr2GetJitterPhaseCount(renderWidth, displayWidth);

float jitterX = 0;
float jitterY = 0;
ffxFsr2GetJitterOffset(&jitterX, &jitterY, index, jitterPhaseCount);

const float jitterX = 2.0f * jitterX / (float)renderWidth;
const float jitterY = -2.0f * jitterY / (float)renderHeight;
const Matrix4 jitterTranslationMatrix = translateMatrix(Matrix3::identity, Vector3(jitterX, jitterY, 0));
const Matrix4 jitteredProjectionMatrix = jitterTranslationMatrix * projectionMatrix;

Jitter should be applied to all rendering. This includes opaque, alpha transparent, and raytraced objects. For rasterized objects, the sub-pixel jittering values calculated by the iffxFsr2GetJitterOffset function can be applied to the camera projection matrix which is ultimately used to perform transformations during vertex shading. For raytraced rendering, the sub-pixel jitter should be applied to the ray’s origin, often the camera’s position.

Whether you elect to use the ffxFsr2GetJitterOffset function or your own sequence generator, you must program the jitterOffset field of the FfxFsr2DispatchParameters structure in order to inform FSR2 of the jitter offset that has been applied in order to render each frame.

If not using the recommended ffxFsr2GetJitterOffset function, care should be taken that your jitter sequence never generates a null vector; that is value of 0 in both the X and Y dimensions.

Parameters:

Return values:

ffxFsr2ResourceIsNull

FFX_API  bool ffxFsr2ResourceIsNull (FfxResource  resource)

A helper function to check if a resource is FFX_FSR2_RESOURCE_IDENTIFIER_NULL.

Parameters:

Returns:

true The resource was not FFX_FSR2_RESOURCE_IDENTIFIER_NULL.

false The resource was FFX_FSR2_RESOURCE_IDENTIFIER_NULL.

ffxFsr2GetEffectVersion

FFX_API  FfxVersionNumber  ffxFsr2GetEffectVersion ()

Queries the effect version number.

Returns:

The SDK version the effect was built with.

FFX_FSR2_CONTEXT_COUNT

#define FFX_FSR2_CONTEXT_COUNT 1

FidelityFX Super Resolution 2 context count.

Defines the number of internal effect contexts required by FSR2

FFX_FSR2_CONTEXT_SIZE

#define FFX_FSR2_CONTEXT_SIZE (FFX_SDK_DEFAULT_CONTEXT_SIZE)

The size of the context specified in 32bit values.

FFX_FSR2_VERSION_MAJOR

#define FFX_FSR2_VERSION_MAJOR (2)

FidelityFX Super Resolution 2 major version.

FFX_FSR2_VERSION_MINOR

#define FFX_FSR2_VERSION_MINOR (3)

FidelityFX Super Resolution 2 minor version.

FFX_FSR2_VERSION_PATCH

#define FFX_FSR2_VERSION_PATCH (2)

FidelityFX Super Resolution 2 patch version.