FidelityFX FSR3

FidelityFX Super Resolution 3 运行时库。

Defines

FFX_FSR3UPSCALER_VERSION_MAJOR

#define FFX_FSR3UPSCALER_VERSION_MAJOR (3)

FidelityFX Super Resolution 3 主版本号。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 36 行, 第 9 列)

FFX_FSR3UPSCALER_VERSION_MINOR

#define FFX_FSR3UPSCALER_VERSION_MINOR (1)

FidelityFX Super Resolution 3 次版本号。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 41 行, 第 9 列)

FFX_FSR3UPSCALER_VERSION_PATCH

#define FFX_FSR3UPSCALER_VERSION_PATCH (4)

FidelityFX Super Resolution 3 修订版本号。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 46 行, 第 9 列)

FFX_FSR3UPSCALER_CONTEXT_COUNT

#define FFX_FSR3UPSCALER_CONTEXT_COUNT 1

FidelityFX Super Resolution 3 上下文计数。

定义 FSR3 所需的内部效果上下文数量

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 53 行, 第 9 列)

FFX_FSR3UPSCALER_CONTEXT_SIZE

#define FFX_FSR3UPSCALER_CONTEXT_SIZE (FFX_SDK_DEFAULT_CONTEXT_SIZE)

以 32 位值为单位指定的上下文大小。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 58 行, 第 9 列)

函数

ffxFsr3UpscalerContextCreate

FFX_API FfxErrorCode ffxFsr3UpscalerContextCreate(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerContextDescription *pContextDescription)

根据 FfxFsr3UpscalerCreateParams 结构体中设置的参数，创建一个 FidelityFX Super Resolution 3 上下文。

上下文结构体是与 FSR3 API 交互的主要对象，负责管理 FSR3 算法使用的内部资源。调用此 API 时，将通过回调结构体中的指针进行多次调用。这些回调将尝试检索设备功能，并创建 FSR3 帧间功能所需的内部资源和管线。根据创建 FfxFsr3UpscalerContext 时使用的具体配置，可能会通过回调函数请求不同的资源和管线集。

FfxFsr3UpscalerContext 的 flags 字段中的标志与您的应用程序的配置以及 FSR3 的预期用途相匹配。正确设置这些标志（以及正确编程的 FfxFsr3UpscalerDispatchDescription）对于确保 FSR3 的正确运行至关重要。建议查阅概述文档以获取有关如何将 FSR3 集成到应用程序中的更多详细信息。

创建 FfxFsr3UpscalerContext 后，应在需要应用 FSR3 缩放的每一帧使用 ffxFsr3UpscalerContextDispatch 函数。有关详细信息，请参阅 ffxFsr3UpscalerContextDispatch 的文档。

当 FfxFsr3UpscalerContext 的使用完成后，应将其销毁，通常是在应用程序卸载或用户禁用 FSR3 缩放时。要销毁 FSR3 上下文，应调用 ffxFsr3UpscalerContextDestroy。

参数

pContext (FfxFsr3UpscalerContext *) – [输出] 指向要填充的 FfxFsr3UpscalerContext 结构体的指针。
pContextDescription (const FfxFsr3UpscalerContextDescription *) – [输入] 指向 FfxFsr3UpscalerContextDescription 结构体的指针。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 307 行, 第 22 列)

ffxFsr3UpscalerGetSharedResourceDescriptions

FFX_API FfxErrorCode ffxFsr3UpscalerGetSharedResourceDescriptions(FfxFsr3UpscalerContext *context, FfxFsr3UpscalerSharedResourceDescriptions *SharedResources)

提供必须为该效果分配的共享资源的描述。

返回值：FFX_OK 操作成功完成。

返回值：其他任何值操作失败。

参数

context (FfxFsr3UpscalerContext *) – [输入] 指向 FfxFsr3UpscalerContext 结构体的指针。
SharedResources (FfxFsr3UpscalerSharedResourceDescriptions *) – [输出] 指向要填充的 FfxFsr3UpscalerSharedResourceDescriptions 的指针。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 320 行, 第 22 列)

ffxFsr3UpscalerContextGetGpuMemoryUsage

FFX_API FfxErrorCode ffxFsr3UpscalerContextGetGpuMemoryUsage(FfxFsr3UpscalerContext *pContext, FfxEffectMemoryUsage *pVramUsage)

获取 FidelityFX Super Resolution 上下文的 GPU 内存使用情况。

参数

pContext (FfxFsr3UpscalerContext *) – [输入] 指向 FfxFsr3UpscalerContext 结构体的指针。
pVramUsage (FfxEffectMemoryUsage *) – [输出] 指向 `FfxEffectMemoryUsage` 结构的指针。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 333 行, 第 22 列)

ffxFsr3UpscalerContextDispatch

FFX_API FfxErrorCode ffxFsr3UpscalerContextDispatch(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerDispatchDescription *pDispatchDescription)

调度构成 FidelityFX Super Resolution 3 的各种通道。

FSR3 是一种复合效果，意味着它由多个组成通道（实现为一种或多种清除、复制和计算调度）组成。每次调用 FfxFsr3UpscalerScheduleGpuJobFunc 回调函数都将对应 FfxFsr3UpscalerPass 中的一个通道。有关每个通道的更全面描述，请参阅 FSR3 参考文档。

请注意，在某些情况下，例如：FFX_FSR3UPSCALER_PASS_ACCUMULATE 和 FFX_FSR3UPSCALER_PASS_ACCUMULATE_SHARPEN，将使用其中一个通道或另一个通道（它们是互斥的）。选择哪一个将取决于创建 FfxFsr3UpscalerContext 的方式以及每次调用 ffxFsr3UpscalerContextDispatch 时 FfxFsr3UpscalerDispatchParamters 的具体内容。

参数

pContext (FfxFsr3UpscalerContext *) – [输入] 指向 FfxFsr3UpscalerContext 结构体的指针。
pDispatchDescription (const FfxFsr3UpscalerDispatchDescription *) – [输入] 指向 FfxFsr3UpscalerDispatchDescription 结构体的指针。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 374 行, 第 22 列)

ffxFsr3UpscalerContextGenerateReactiveMask

FFX_API FfxErrorCode ffxFsr3UpscalerContextGenerateReactiveMask(FfxFsr3UpscalerContext *pContext, const FfxFsr3UpscalerGenerateReactiveDescription *pParams)

一个辅助函数，用于从不透明纹理和包含半透明对象的纹理生成一个反应掩码。

参数

pContext (FfxFsr3UpscalerContext *) – [输入] 指向 FfxFsr3UpscalerContext 结构体的指针。
pParams (const FfxFsr3UpscalerGenerateReactiveDescription *) – [输入] 指向 FfxFsr3UpscalerGenerateReactiveDescription 结构体的指针

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 385 行, 第 22 列)

ffxFsr3UpscalerContextDestroy

FFX_API FfxErrorCode ffxFsr3UpscalerContextDestroy(FfxFsr3UpscalerContext *pContext)

销毁 FidelityFX Super Resolution 上下文。

参数

pContext (FfxFsr3UpscalerContext *) – [输出] 指向要销毁的 FfxFsr3UpscalerContext 结构体的指针。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 397 行, 第 22 列)

ffxFsr3UpscalerGetUpscaleRatioFromQualityMode

FFX_API float ffxFsr3UpscalerGetUpscaleRatioFromQualityMode(FfxFsr3UpscalerQualityMode qualityMode)

根据质量模式获取缩放比例。

下表列出了质量模式与每维缩放比例的映射。

质量预设
缩放系数

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

传入无效的 `qualityMode` 将返回 0.0f。

返回值：根据上表，`qualityMode` 的每维缩放比例。

参数

qualityMode (FfxFsr3UpscalerQualityMode) – [输入] 质量模式预设。

返回值： FFX_API float

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 420 行, 第 15 列)

ffxFsr3UpscalerGetRenderResolutionFromQualityMode

FFX_API FfxErrorCode ffxFsr3UpscalerGetRenderResolutionFromQualityMode(uint32_t *pRenderWidth, uint32_t *pRenderHeight, uint32_t displayWidth, uint32_t displayHeight, FfxFsr3UpscalerQualityMode qualityMode)

一个辅助函数，用于根据目标分辨率和期望的质量级别计算渲染分辨率。

此函数将 ffxFsr3UpscalerGetUpscaleRatioFromQualityMode 返回的缩放因子应用于每个维度。

参数

pRenderWidth (uint32_t *) – [输出] 指向 `uint32_t` 的指针，其中将保存计算出的渲染分辨率宽度。
pRenderHeight (uint32_t *) – [输出] 指向 `uint32_t` 的指针，其中将保存计算出的渲染分辨率高度。
displayWidth (uint32_t) – [输入] 目标显示分辨率宽度。
displayHeight (uint32_t) – [输入] 目标显示分辨率高度。
qualityMode (FfxFsr3UpscalerQualityMode) – [输入] FSR 2 缩放所需的质量模式。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 442 行, 第 22 列)

ffxFsr3UpscalerGetJitterPhaseCount

FFX_API int32_t ffxFsr3UpscalerGetJitterPhaseCount(int32_t renderWidth, int32_t displayWidth)

一个用于根据显示分辨率计算抖动相位数的辅助函数。

有关将相机抖动应用于应用程序渲染的更详细信息，请参阅 ffxFsr3UpscalerGetJitterOffset 函数。

下表显示了此函数为每个质量预设返回的抖动相位数。

质量预设
缩放系数
相位数

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

自定义
[1..n]x
ceil(8*n^2)

返回值：渲染宽度和显示宽度之间的缩放因子的抖动相位数。

参数

renderWidth (int32_t) – [输入] 渲染分辨率宽度。
displayWidth (int32_t) – [输入] 显示分辨率宽度。

返回值： FFX_API int32_t

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 474 行, 第 17 列)

ffxFsr3UpscalerGetJitterOffset

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

一个用于计算子像素抖动偏移量的辅助函数。

FSR3 依赖应用程序在渲染时应用子像素抖动。这通常包含在相机的投影矩阵中。为了简化相机抖动的应用，FSR3 API 提供了一组小型实用函数，用于计算一个帧在一系列单独抖动偏移量中的子像素抖动偏移量。首先，必须计算抖动相位内的索引。要计算序列的长度，可以调用 ffxFsr3UpscalerGetJitterPhaseCount 函数。索引应为一个值，该值每帧递增，并对 ffxFsr3UpscalerGetJitterPhaseCount 计算出的序列长度取模。抖动相位内的索引通过 index 参数传递给 ffxFsr3UpscalerGetJitterOffset。

此函数使用 Halton(2,3) 序列来计算抖动偏移量。用于序列的最终索引为 index % phaseCount。

重要的是要理解，从 ffxFsr3UpscalerGetJitterOffset 函数返回的值是以像素单位表示的，并且为了将其正确地复合到投影矩阵中，我们必须将其转换为投影偏移量。这按照下面显示的伪代码进行。 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; 抖动应应用于所有渲染。这包括不透明、半透明和光线追踪对象。对于栅格化对象，ffxFsr3UpscalerGetJitterOffset 函数计算的子像素抖动值可以应用于最终用于顶点着色期间执行变换的相机投影矩阵。对于光线追踪渲染，子像素抖动应应用于射线的起点，通常是相机的位置。

无论您选择使用 ffxFsr3UpscalerGetJitterOffset 函数还是自己的序列生成器，都必须对 FfxFsr3UpscalerDispatchParameters 结构体的 jitterOffset 字段进行编程，以便告知 FSR3 已为渲染每一帧而应用的抖动偏移量。

如果未使用推荐的 ffxFsr3UpscalerGetJitterOffset 函数，则应注意确保您的抖动序列永远不会生成空向量；即 X 和 Y 维度都为 0。

参数

pOutX (float *) – [输出] 指向一个 float 的指针，其中将包含 x 维度的子像素抖动偏移量。
pOutY (float *) – [输出] 指向一个 float 的指针，其中将包含 y 维度的子像素抖动偏移量。
index (int32_t) – [输入] 抖动序列内的索引。
phaseCount (int32_t) – [输入] 抖动阶段的长度。请参阅 ffxFsr3UpscalerGetJitterPhaseCount。

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 542 行, 第 22 列)

ffxFsr3UpscalerResourceIsNull

FFX_API bool ffxFsr3UpscalerResourceIsNull(FfxResource resource)

一个辅助函数，用于检查资源是否为 FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL。

返回值：true 资源不是 FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL。

返回值：false 资源是 FFX_FSR3UPSCALER_RESOURCE_IDENTIFIER_NULL。

参数

resource (FfxResource) – [输入] 一个 FfxResource。

返回值: FFX_API bool

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 555 行, 第 14 列)

ffxFsr3UpscalerGetEffectVersion

FFX_API FfxVersionNumber ffxFsr3UpscalerGetEffectVersion()

查询效果版本号。

返回: 构建该效果的 SDK 版本。

返回: FFX_API FfxVersionNumber

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 567 行, 第 26 列)

ffxFsr3UpscalerSetConstant

FFX_API FfxErrorCode ffxFsr3UpscalerSetConstant(FfxFsr3UpscalerContext *context, FfxFsr3UpscalerConfigureKey key, void *valuePtr)

在 upscaler 上下文创建后覆盖 upscaler 常量缓冲区值。

参数

context (FfxFsr3UpscalerContext *) – [输入] 指向 FfxFsr3UpscalerContext 结构体的指针。
key (FfxFsr3UpscalerConfigureKey) – [输入] 来自 FfxFsr3UpscalerConfigureKey 枚举的键
valuePtr (void *) – [输入] 指向要传递给着色器的常量缓冲区值的指针。请参阅 Fsr3UpscalerConstants

返回： FFX_API FfxErrorCode

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 583 行, 第 22 列)

类型定义

FfxFsr3UpscalerMessage

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

传递字符串消息。

用于调试消息。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 154 行, 第 9 列)

枚举

FfxFsr3UpscalerPass

enum FfxFsr3UpscalerPass

构成 FSR3 算法的所有通道的枚举。

FSR3 实现为多个计算通道的复合体，每个通道计算最终结果的关键部分。每次调用 FfxFsr3UpscalerScheduleGpuJobFunc 回调函数都将对应 FfxFsr3UpscalerPass 中的一个通道。有关每个通道的更全面描述，请参阅 FSR3 参考文档。

值

FFX_FSR3UPSCALER_PASS_PREPARE_INPUTS

准备游戏输入以供后续通道使用的通道。

FFX_FSR3UPSCALER_PASS_LUMA_PYRAMID

生成当前帧的亮度 mipmap 链的通道。

FFX_FSR3UPSCALER_PASS_SHADING_CHANGE_PYRAMID

生成当前帧的阴影变化检测 mipmap 链的通道。

FFX_FSR3UPSCALER_PASS_SHADING_CHANGE

估计当前帧阴影变化的通道。

FFX_FSR3UPSCALER_PASS_PREPARE_REACTIVITY

准备累积相关信息的通道。

FFX_FSR3UPSCALER_PASS_LUMA_INSTABILITY

估计亮度变化时间不稳定的通道。

FFX_FSR3UPSCALER_PASS_ACCUMULATE

执行缩放的通道。

FFX_FSR3UPSCALER_PASS_ACCUMULATE_SHARPEN

使用锐化时执行缩放的通道。

FFX_FSR3UPSCALER_PASS_RCAS

执行锐化的通道。

FFX_FSR3UPSCALER_PASS_DEBUG_VIEW

用于调试目的，绘制一些内部资源的通道。

FFX_FSR3UPSCALER_PASS_GENERATE_REACTIVE

一个可选的通道，用于生成反应掩码。

FFX_FSR3UPSCALER_PASS_TCR_AUTOGENERATE

已弃用 - 不再支持。

FFX_FSR3UPSCALER_PASS_COUNT

FSR3 执行的通道数。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 81 行, 第 1 列)

FfxFsr3UpscalerQualityMode

enum FfxFsr3UpscalerQualityMode

FidelityFX Super Resolution 3 缩放支持的所有质量模式的枚举。

为了在多个实现 FSR3 的应用程序中提供一致的用户体验。强烈建议在应用程序的用户界面中提供以下预设缩放因子。

如果您的应用程序不提供缩放算法的预设缩放因子概念（例如，而是实现一个固定的、不可变的比例），或者实现更动态的缩放方案（如动态分辨率缩放），则无需使用这些预设。

请注意，FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE 是一个可选模式，可能会在最终图像中引入严重的质量下降。因此，建议在决定是否应在应用程序中包含此缩放模式之前，先评估其最终结果。

值

FFX_FSR3UPSCALER_QUALITY_MODE_NATIVEAA

FFX_FSR3UPSCALER_QUALITY_MODE_NATIVEAA = 0

以 1.0x 的每维度缩放比例执行缩放。

FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY

FFX_FSR3UPSCALER_QUALITY_MODE_QUALITY = 1

以 1.5 倍的每维缩放比例执行缩放。

FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED

FFX_FSR3UPSCALER_QUALITY_MODE_BALANCED = 2

以 1.7 倍的每维缩放比例执行缩放。

FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE

FFX_FSR3UPSCALER_QUALITY_MODE_PERFORMANCE = 3

以 2.0 倍的每维缩放比例执行缩放。

FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE

FFX_FSR3UPSCALER_QUALITY_MODE_ULTRA_PERFORMANCE = 4

以 3.0x 的每维度缩放比例执行缩放。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 119 行, 第 1 列)

FfxFsr3UpscalerInitializationFlagBits

enum FfxFsr3UpscalerInitializationFlagBits

创建 FfxFsr3UpscalerContext 时使用的位标志枚举。请参阅 FfxFsr3UpscalerContextDescription。

值

FFX_FSR3UPSCALER_ENABLE_HIGH_DYNAMIC_RANGE

FFX_FSR3UPSCALER_ENABLE_HIGH_DYNAMIC_RANGE = (1<<0)

一个位，指示提供的输入颜色数据是否使用高动态范围。

FFX_FSR3UPSCALER_ENABLE_DISPLAY_RESOLUTION_MOTION_VECTORS

FFX_FSR3UPSCALER_ENABLE_DISPLAY_RESOLUTION_MOTION_VECTORS = (1<<1)

一个指示运动矢量是否以显示分辨率渲染的位。

FFX_FSR3UPSCALER_ENABLE_MOTION_VECTORS_JITTER_CANCELLATION

FFX_FSR3UPSCALER_ENABLE_MOTION_VECTORS_JITTER_CANCELLATION = (1<<2)

一个指示运动矢量应用了抖动模式的位。

FFX_FSR3UPSCALER_ENABLE_DEPTH_INVERTED

FFX_FSR3UPSCALER_ENABLE_DEPTH_INVERTED = (1<<3)

一个位，指示提供的输入深度缓冲区数据是反转的 [1..0]。

FFX_FSR3UPSCALER_ENABLE_DEPTH_INFINITE

FFX_FSR3UPSCALER_ENABLE_DEPTH_INFINITE = (1<<4)

一个位，指示提供的输入深度缓冲区数据使用的是无限远平面。

FFX_FSR3UPSCALER_ENABLE_AUTO_EXPOSURE

FFX_FSR3UPSCALER_ENABLE_AUTO_EXPOSURE = (1<<5)

指示是否应将自动曝光应用于输入颜色数据的位。

FFX_FSR3UPSCALER_ENABLE_DYNAMIC_RESOLUTION

FFX_FSR3UPSCALER_ENABLE_DYNAMIC_RESOLUTION = (1<<6)

指示应用程序使用动态分辨率缩放的位。

FFX_FSR3UPSCALER_ENABLE_TEXTURE1D_USAGE

FFX_FSR3UPSCALER_ENABLE_TEXTURE1D_USAGE = (1<<7)

此值已弃用，但保留以帮助从旧版 FSR3 进行升级。

FFX_FSR3UPSCALER_ENABLE_DEBUG_CHECKING

FFX_FSR3UPSCALER_ENABLE_DEBUG_CHECKING = (1<<8)

一个指示运行时应检查某些 API 值并报告问题的位。

FFX_FSR3UPSCALER_ENABLE_RCAS_LOWER_LIMITER_COMPENSATION

FFX_FSR3UPSCALER_ENABLE_RCAS_LOWER_LIMITER_COMPENSATION = (1<<9)

一个位，指示是否应补偿 rcas 期间可能的负输出值。

来源： sdk/include/FidelityFX/host/ffx_fsr3upscaler.h (第 131 行, 第 1 列)

依赖项

此模块依赖于