FidelityFX FSR3
Navigation: SDK → Effect Components
FidelityFX FSR3
FidelityFX Super Resolution 3 runtime library.
Defines
FFX_FSR3UPSCALER_VERSION_MAJOR
#define FFX_FSR3UPSCALER_VERSION_MAJOR (3)FidelityFX Super Resolution 3 major version.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 36, column 9)
FFX_FSR3UPSCALER_VERSION_MINOR
#define FFX_FSR3UPSCALER_VERSION_MINOR (1)FidelityFX Super Resolution 3 minor version.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 41, column 9)
FFX_FSR3UPSCALER_VERSION_PATCH
#define FFX_FSR3UPSCALER_VERSION_PATCH (4)FidelityFX Super Resolution 3 patch version.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 46, column 9)
FFX_FSR3UPSCALER_CONTEXT_COUNT
#define FFX_FSR3UPSCALER_CONTEXT_COUNT 1FidelityFX Super Resolution 3 context count.
Defines the number of internal effect contexts required by FSR3
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 53, column 9)
FFX_FSR3UPSCALER_CONTEXT_SIZE
#define FFX_FSR3UPSCALER_CONTEXT_SIZE (FFX_SDK_DEFAULT_CONTEXT_SIZE)The size of the context specified in 32bit values.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 58, column 9)
Functions
ffxFsr3UpscalerContextCreate
FFX_API FfxErrorCode ffxFsr3UpscalerContextCreate(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerContextDescription *pContextDescription)Create a FidelityFX Super Resolution 3 context from the parameters programmed to the FfxFsr3UpscalerCreateParams structure.
The context structure is the main object used to interact with the FSR3 API, and is responsible for the management of the internal resources used by the FSR3 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 FSR3’s frame-to-frame function. Depending on the precise configuration used when creating the FfxFsr3UpscalerContext a different set of resources and pipelines might be requested via the callback functions.
The flags included in the flags field of FfxFsr3UpscalerContext how match the configuration of your application as well as the intended use of FSR3. It is important that these flags are set correctly (as well as a correct programmed FfxFsr3UpscalerDispatchDescription) to ensure correct operation. It is recommended to consult the overview documentation for further details on how FSR3 should be integerated into an application.
When the FfxFsr3UpscalerContext is created, you should use the ffxFsr3UpscalerContextDispatch function each frame where FSR3 upscaling should be applied. See the documentation of ffxFsr3UpscalerContextDispatch for more details.
The FfxFsr3UpscalerContext should be destroyed when use of it is completed, typically when an application is unloaded or FSR3 upscaling is disabled by a user. To destroy the FSR3 context you should call ffxFsr3UpscalerContextDestroy.
Parameters:
pContext(FfxFsr3UpscalerContext *) – [out] A pointer to a FfxFsr3UpscalerContext structure to populate.pContextDescription(const FfxFsr3UpscalerContextDescription *) – [in] A pointer to a FfxFsr3UpscalerContextDescription structure.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 307, column 22)
ffxFsr3UpscalerGetSharedResourceDescriptions
FFX_API FfxErrorCode ffxFsr3UpscalerGetSharedResourceDescriptions(FfxFsr3UpscalerContext *context, FfxFsr3UpscalerSharedResourceDescriptions *SharedResources)Provides the descriptions for shared resources that must be allocated for this effect.
Returns: FFX_OK The operation completed successfully.
Returns: Anything else The operation failed.
Parameters:
context(FfxFsr3UpscalerContext *) – [in] A pointer to a FfxFsr3UpscalerContext structure.SharedResources(FfxFsr3UpscalerSharedResourceDescriptions *) – [out] A pointer to a FfxFsr3UpscalerSharedResourceDescriptions to populate.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 320, column 22)
ffxFsr3UpscalerContextGetGpuMemoryUsage
FFX_API FfxErrorCode ffxFsr3UpscalerContextGetGpuMemoryUsage(FfxFsr3UpscalerContext *pContext, FfxEffectMemoryUsage *pVramUsage)Get GPU memory usage of the FidelityFX Super Resolution context.
Parameters:
pContext(FfxFsr3UpscalerContext *) – [in] A pointer to a FfxFsr3UpscalerContext structure.pVramUsage(FfxEffectMemoryUsage *) – [out] A pointer to a FfxEffectMemoryUsage structure.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 333, column 22)
ffxFsr3UpscalerContextDispatch
FFX_API FfxErrorCode ffxFsr3UpscalerContextDispatch(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerDispatchDescription *pDispatchDescription)Dispatch the various passes that constitute FidelityFX Super Resolution 3.
FSR3 is a composite effect, meaning that it is compromised of multiple constituent passes (implemented as one or more clears, copies and compute dispatches). The ffxFsr3UpscalerContextDispatch function is the function which (via the use of the functions contained in the callbacks field of the FfxFsr3UpscalerContext structure) utlimately generates the sequence of graphics API calls required each frame.
As with the creation of the FfxFsr3UpscalerContext correctly programming the FfxFsr3UpscalerDispatchDescription is key to ensuring the correct operation of FSR3. It is particularly important to ensure that camera jitter is correctly applied to your application’s projection matrix (or camera origin for raytraced applications). FSR3 provides the ffxFsr3UpscalerGetJitterPhaseCount and ffxFsr3UpscalerGetJitterOffset 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 ffxFsr3UpscalerGetJitterOffset as well as the accompanying overview documentation for FSR3.
Parameters:
pContext(FfxFsr3UpscalerContext *) – [in] A pointer to a FfxFsr3UpscalerContext structure.pDispatchDescription(const FfxFsr3UpscalerDispatchDescription *) – [in] A pointer to a FfxFsr3UpscalerDispatchDescription structure.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 374, column 22)
ffxFsr3UpscalerContextGenerateReactiveMask
FFX_API FfxErrorCode ffxFsr3UpscalerContextGenerateReactiveMask(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerGenerateReactiveDescription *pParams)A helper function generate a Reactive mask from an opaque only texure and one containing translucent objects.
Parameters:
pContext(FfxFsr3UpscalerContext *) – [in] A pointer to a FfxFsr3UpscalerContext structure.pParams(const FfxFsr3UpscalerGenerateReactiveDescription *) – [in] A pointer to a FfxFsr3UpscalerGenerateReactiveDescription structure
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 385, column 22)
ffxFsr3UpscalerContextDestroy
FFX_API FfxErrorCode ffxFsr3UpscalerContextDestroy(FfxFsr3UpscalerContext *pContext)Destroy the FidelityFX Super Resolution context.
Parameters:
pContext(FfxFsr3UpscalerContext *) – [out] A pointer to a FfxFsr3UpscalerContext structure to destroy.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 397, column 22)
ffxFsr3UpscalerGetUpscaleRatioFromQualityMode
FFX_API float ffxFsr3UpscalerGetUpscaleRatioFromQualityMode(FfxFsr3UpscalerQualityMode qualityMode)Get the upscale ratio from the quality mode.
The following table enumerates the mapping of the quality modes to per-dimension scaling ratios.
Quality preset
Scale factor
FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY
1.5x
FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED
1.7x
FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE
2.0x
FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE
3.0x
Passing an invalid qualityMode will return 0.0f.
Returns: The upscaling the per-dimension upscaling ratio for qualityMode according to the table above.
Parameters:
qualityMode(FfxFsr3UpscalerQualityMode) – [in] The quality mode preset.
Returns: FFX_API float
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 420, column 15)
ffxFsr3UpscalerGetRenderResolutionFromQualityMode
FFX_API FfxErrorCode ffxFsr3UpscalerGetRenderResolutionFromQualityMode(uint32_t *pRenderWidth, uint32_t *pRenderHeight, uint32_t displayWidth, uint32_t displayHeight, FfxFsr3UpscalerQualityMode 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 ffxFsr3UpscalerGetUpscaleRatioFromQualityMode to each dimension.
Parameters:
pRenderWidth(uint32_t *) – [out] A pointer to a uint32_t which will hold the calculated render resolution width.pRenderHeight(uint32_t *) – [out] A pointer to a uint32_t which will hold the calculated render resolution height.displayWidth(uint32_t) – [in] The target display resolution width.displayHeight(uint32_t) – [in] The target display resolution height.qualityMode(FfxFsr3UpscalerQualityMode) – [in] The desired quality mode for FSR 2 upscaling.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 442, column 22)
ffxFsr3UpscalerGetJitterPhaseCount
FFX_API int32_t ffxFsr3UpscalerGetJitterPhaseCount(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 ffxFsr3UpscalerGetJitterOffset function.
The table below shows the jitter phase count which this function would return for each of the quality presets.
Quality preset
Scale factor
Phase count
FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY
1.5x
18
FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED
1.7x
23
FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE
2.0x
32
FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE
3.0x
72
Custom
[1..n]x
ceil(8*n^2)
Returns: The jitter phase count for the scaling factor between renderWidth and displayWidth.
Parameters:
renderWidth(int32_t) – [in] The render resolution width.displayWidth(int32_t) – [in] The display resolution width.
Returns: FFX_API int32_t
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 474, column 17)
ffxFsr3UpscalerGetJitterOffset
FFX_API FfxErrorCode ffxFsr3UpscalerGetJitterOffset(float *pOutX, float *pOutY, int32_t index, int32_t phaseCount)A helper function to calculate the subpixel jitter offset.
FSR3 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 FSR3 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 ffxFsr3UpscalerGetJitterPhaseCount function. The index should be a value which is incremented each frame modulo the length of the sequence computed by ffxFsr3UpscalerGetJitterPhaseCount. The index within the jitter phase is passed to ffxFsr3UpscalerGetJitterOffset 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 ffxFsr3UpscalerGetJitterOffset 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 = ffxFsr3UpscalerGetJitterPhaseCount(renderWidth, displayWidth);
float jitterX = 0; float jitterY = 0; ffxFsr3UpscalerGetJitterOffset(&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 iffxFsr3UpscalerGetJitterOffset 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 ffxFsr3UpscalerGetJitterOffset function or your own sequence generator, you must program the jitterOffset field of the FfxFsr3UpscalerDispatchParameters structure in order to inform FSR3 of the jitter offset that has been applied in order to render each frame.
If not using the recommended ffxFsr3UpscalerGetJitterOffset 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:
pOutX(float *) – [out] A pointer to a float which will contain the subpixel jitter offset for the x dimension.pOutY(float *) – [out] A pointer to a float which will contain the subpixel jitter offset for the y dimension.index(int32_t) – [in] The index within the jitter sequence.phaseCount(int32_t) – [in] The length of jitter phase. See ffxFsr3UpscalerGetJitterPhaseCount.
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 542, column 22)
ffxFsr3UpscalerResourceIsNull
FFX_API bool ffxFsr3UpscalerResourceIsNull(FfxResource resource)A helper function to check if a resource is FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL.
Returns: true The resource was not FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL.
Returns: false The resource was FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL.
Parameters:
resource(FfxResource) – [in] A FfxResource.
Returns: FFX_API bool
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 555, column 14)
ffxFsr3UpscalerGetEffectVersion
FFX_API FfxVersionNumber ffxFsr3UpscalerGetEffectVersion()Queries the effect version number.
Returns: The SDK version the effect was built with.
Returns: FFX_API FfxVersionNumber
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 567, column 26)
ffxFsr3UpscalerSetConstant
FFX_API FfxErrorCode ffxFsr3UpscalerSetConstant(FfxFsr3UpscalerContext *context, FfxFsr3UpscalerConfigureKey key, void *valuePtr)Override upscaler constant buffer value after upscaler context creation.
Parameters:
context(FfxFsr3UpscalerContext *) – [in] A pointer to a FfxFsr3UpscalerContext structure.key(FfxFsr3UpscalerConfigureKey) – [in] A key from FfxFsr3UpscalerConfigureKey enumvaluePtr(void *) – [in] A pointer to value to pass to shader in Constant Buffer. See Fsr3UpscalerConstants
Returns: FFX_API FfxErrorCode
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 583, column 22)
Typedefs
FfxFsr3UpscalerMessage
typedef void(* FfxFsr3UpscalerMessage) (FfxMsgType type, const wchar_t *message)Pass a string message.
Used for debug messages.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 154, column 9)
Enumerations
FfxFsr3UpscalerPass
enum FfxFsr3UpscalerPassAn enumeration of all the passes which constitute the FSR3 algorithm.
FSR3 is implemented as a composite of several compute passes each computing a key part of the final result. Each call to the FfxFsr3UpscalerScheduleGpuJobFunc callback function will correspond to a single pass included in FfxFsr3UpscalerPass. For a more comprehensive description of each pass, please refer to the FSR3 reference documentation.
Please note in some cases e.g.: FFX_FSR3UPSCALER_PASS_ACCUMULATE and FFX_FSR3UPSCALER_PASS_ACCUMULATE_SHARPEN either one pass or the other will be used (they are mutually exclusive). The choice of which will depend on the way the FfxFsr3UpscalerContext is created and the precise contents of FfxFsr3UpscalerDispatchParamters each time a call is made to ffxFsr3UpscalerContextDispatch.
Values:
FFX_FSR3UPSCALER_PASS_PREPARE_INPUTS
A pass which prepares game inputs for later passes.
FFX_FSR3UPSCALER_PASS_LUMA_PYRAMID
A pass which generates the luminance mipmap chain for the current frame.
FFX_FSR3UPSCALER_PASS_SHADING_CHANGE_PYRAMID
A pass which generates the shading change detection mipmap chain for the current frame.
FFX_FSR3UPSCALER_PASS_SHADING_CHANGE
A pass which estimates shading changes for the current frame.
FFX_FSR3UPSCALER_PASS_PREPARE_REACTIVITY
A pass which prepares accumulation relevant information.
FFX_FSR3UPSCALER_PASS_LUMA_INSTABILITY
A pass which estimates temporal instability of the luminance changes.
FFX_FSR3UPSCALER_PASS_ACCUMULATE
A pass which performs upscaling.
FFX_FSR3UPSCALER_PASS_ACCUMULATE_SHARPEN
A pass which performs upscaling when sharpening is used.
FFX_FSR3UPSCALER_PASS_RCAS
A pass which performs sharpening.
FFX_FSR3UPSCALER_PASS_DEBUG_VIEW
A pass which draws some internal resources, for debugging purposes.
FFX_FSR3UPSCALER_PASS_GENERATE_REACTIVE
An optional pass to generate a reactive mask.
FFX_FSR3UPSCALER_PASS_TCR_AUTOGENERATE
DEPRECATED - NO LONGER SUPPORTED.
FFX_FSR3UPSCALER_PASS_COUNT
The number of passes performed by FSR3.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 81, column 1)
FfxFsr3UpscalerQualityMode
enum FfxFsr3UpscalerQualityModeAn enumeration of all the quality modes supported by FidelityFX Super Resolution 3 upscaling.
In order to provide a consistent user experience across multiple applications which implement FSR3. It is strongly recommended that the following preset scaling factors are made available through your application’s user interface.
If your application does not expose the notion of preset scaling factors for upscaling algorithms (perhaps instead implementing a fixed ratio which is immutable) or implementing a more dynamic scaling scheme (such as dynamic resolution scaling), then there is no need to use these presets.
Please note that FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE is an optional mode which may introduce significant quality degradation in the final image. As such it is recommended that you evaluate the final results of using this scaling mode before deciding if you should include it in your application.
Values:
FFX_FSR3UPSCALER_QUALITY_MODE_NATIVEAA
FFX_FSR3UPSCALER_QUALITY_MODE_NATIVEAA = 0Perform upscaling with a per-dimension upscaling ratio of 1.0x.
FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY
FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY = 1Perform upscaling with a per-dimension upscaling ratio of 1.5x.
FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED
FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED = 2Perform upscaling with a per-dimension upscaling ratio of 1.7x.
FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE
FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE = 3Perform upscaling with a per-dimension upscaling ratio of 2.0x.
FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE
FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE = 4Perform upscaling with a per-dimension upscaling ratio of 3.0x.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 119, column 1)
FfxFsr3UpscalerInitializationFlagBits
enum FfxFsr3UpscalerInitializationFlagBitsAn enumeration of bit flags used when creating a FfxFsr3UpscalerContext. See FfxFsr3UpscalerContextDescription.
Values:
FFX_FSR3UPSCALER_ENABLE_HIGH_DYNAMIC_RANGE
FFX_FSR3UPSCALER_ENABLE_HIGH_DYNAMIC_RANGE = (1<<0)A bit indicating if the input color data provided is using a high-dynamic range.
FFX_FSR3UPSCALER_ENABLE_DISPLAY_RESOLUTION_MOTION_VECTORS
FFX_FSR3UPSCALER_ENABLE_DISPLAY_RESOLUTION_MOTION_VECTORS = (1<<1)A bit indicating if the motion vectors are rendered at display resolution.
FFX_FSR3UPSCALER_ENABLE_MOTION_VECTORS_JITTER_CANCELLATION
FFX_FSR3UPSCALER_ENABLE_MOTION_VECTORS_JITTER_CANCELLATION = (1<<2)A bit indicating that the motion vectors have the jittering pattern applied to them.
FFX_FSR3UPSCALER_ENABLE_DEPTH_INVERTED
FFX_FSR3UPSCALER_ENABLE_DEPTH_INVERTED = (1<<3)A bit indicating that the input depth buffer data provided is inverted [1..0].
FFX_FSR3UPSCALER_ENABLE_DEPTH_INFINITE
FFX_FSR3UPSCALER_ENABLE_DEPTH_INFINITE = (1<<4)A bit indicating that the input depth buffer data provided is using an infinite far plane.
FFX_FSR3UPSCALER_ENABLE_AUTO_EXPOSURE
FFX_FSR3UPSCALER_ENABLE_AUTO_EXPOSURE = (1<<5)A bit indicating if automatic exposure should be applied to input color data.
FFX_FSR3UPSCALER_ENABLE_DYNAMIC_RESOLUTION
FFX_FSR3UPSCALER_ENABLE_DYNAMIC_RESOLUTION = (1<<6)A bit indicating that the application uses dynamic resolution scaling.
FFX_FSR3UPSCALER_ENABLE_TEXTURE1D_USAGE
FFX_FSR3UPSCALER_ENABLE_TEXTURE1D_USAGE = (1<<7)This value is deprecated, but remains in order to aid upgrading from older versions of FSR3.
FFX_FSR3UPSCALER_ENABLE_DEBUG_CHECKING
FFX_FSR3UPSCALER_ENABLE_DEBUG_CHECKING = (1<<8)A bit indicating that the runtime should check some API values and report issues.
FFX_FSR3UPSCALER_ENABLE_RCAS_LOWER_LIMITER_COMPENSATION
FFX_FSR3UPSCALER_ENABLE_RCAS_LOWER_LIMITER_COMPENSATION = (1<<9)A bit indicating if we should compensate for possible negative output values during rcas.
Source: sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (line 131, column 1)
Dependencies
This module depends on: