Shaderpack Interface documentation (Version 1) (ZH)

Schema Version: 1

本指南主要介绍如何在你的光影包中集成 SR（Super Resolution，超分辨率）。 SR 作为一个插件——它不会接管或修改游戏的渲染方式，只是为Iris的渲染管线添加了超分辨率功能。你只需要了解 SR 读取哪些数据、把结果写到哪里。

SR 的工作原理

SR 不会改变游戏的渲染分辨率。游戏始终以屏幕分辨率进行渲染。

分辨率缩放完全由你的光影包自己控制（例如通过 buffer scale）。 SR 只是在你指定的 composite pass 处介入，读取你提供的输入，执行超分辨率，然后把结果写回你指定的缓冲区。

具体流程如下：

你的光影正常渲染场景。分辨率缩放由光影自行管理。
在你指定的 composite pass 处，SR 被触发。
SR 从你的缓冲区读取颜色、深度和运动矢量。
SR 执行超分辨率放大。
SR 把放大后的结果写回你指定的缓冲区。
你的光影继续执行后续 pass。

如果配置文件缺失、格式错误，或者光影接口被禁用，SR 什么都不做——你的光影会像 SR 不存在一样正常运行。

注意： SR 是一个插件。它为你现有的管线添加超分辨率能力。它不控制渲染分辨率，也不替换你的任何 pass。

第一部分 — 快速上手

步骤 1：创建配置文件

在光影包根目录下（与 shaders.properties 同级）创建名为 superresolution.json 的文件。

步骤 2：编写最简配置

{
  "schema_version": 1,
  "profiles": {
    "*": {
      "jitter": {
        "enabled": true
      },
      "upscale": {
        "enabled": true,
        "internal_format": "r11g11b10f",
        "trigger": {
          "type": "AFTER",
          "pass": "composite1"
        },
        "inputs": {
          "color": {
            "enabled": true,
            "src": "colortex0",
            "region": [0, 0, -1, -1]
          },
          "depth": {
            "enabled": true,
            "src": "depthtex",
            "region": [0, 0, -1, -1]
          },
          "motion_vectors": {
            "enabled": true,
            "src": "colortex16",
            "region": [0, 0, -1, -1]
          }
        },
        "outputs": {
          "upscaled_color": {
            "enabled": true,
            "target": ["colortex0"],
            "region": [0, 0, -2, -2]
          }
        }
      }
    }
  }
}

步骤 3：在光影中提供所需数据

在触发点之前的 composite pass 中，确保：

颜色缓冲区已写入渲染好的场景（以你的缩放分辨率）。
深度缓冲区可用。
运动矢量缓冲区已写入 UV 空间的逐像素运动矢量。

就这些。剩下的交给 SR。

第二部分 — 配置参考

维度配置（Profiles）

你可以为不同维度配置不同的 SR 参数。"profiles" 中的每个键对应一个维度。

当加载某个维度时，SR 按以下顺序查找配置：

先查找精确匹配的键（例如 "0" 对应主世界）。
如果找不到，使用 "*" 作为默认配置。
如果两者都不存在，该维度的超分辨率功能被禁用��

键	维度
`"0"`	主世界
`"-1"`	下界
`"1"`	末地
`"*"`	默认回退

维度键由光影包自身的维度映射决定（即 Iris 中 dimension.world0 等配置使用的映射）。

触发点（Trigger）

"trigger": {
  "type": "AFTER",
  "pass": "composite1"
}

"type" — "BEFORE" 或 "AFTER"。决定 SR 在指定 pass 之前还是之后运行。
"pass" — composite pass 的名称（如 "composite"、"composite1"、"composite2" 等）。

仅支持 composite pass。 计算着色器（compute shader）的 composite pass 技术上可以使用，但目前不稳定——请自行承担风险。

选择触发点的原则：

触发点之前的 pass 应该已经完成颜色、深度和运动矢量的写入。
触发点之后的 pass 可以读取全屏分辨率的超分结果。

输入（Inputs）

SR 需要三个输入。三个都必须提供且启用。如果任何一个缺失或禁用，该帧将跳过超分。

"inputs": {
  "color": {
    "enabled": true,
    "src": "colortex0",
    "region": [0, 0, -1, -1]
  },
  "depth": {
    "enabled": true,
    "src": "depthtex",
    "region": [0, 0, -1, -1]
  },
  "motion_vectors": {
    "enabled": true,
    "src": "colortex16",
    "region": [0, 0, -1, -1]
  }
}

输入	说明
`color`	以缩放分辨率渲染的场景颜色。
`depth`	深度缓冲区。
`motion_vectors`	UV 空间的逐像素运动矢量（RG 通道）。

src 可以是以下纹理名称：

名称	说明
`colortex0` – `colortex31`	颜色缓冲区附件
`alttex0` – `alttex31`	交替（翻转）纹理变体
`depthtex`	主深度纹理
`noHandDepthtex`	不含手部的深度纹理
`noTranslucentDepthtex`	不含半透明物体的深度纹理

区域（Region）

"region" 字段指定从纹理的哪个区域读取或写入：

"region": [X, Y, W, H]

值	含义
`≥ 0`	显式像素坐标 / 尺寸
`-1`	完整的渲染分辨率（光影使用的缩放分辨率）
`-2`	完整的屏幕分辨率（实际显示分辨率）

规则：

X 和 Y 必须 ≥ 0。位置不允许使用负值。
W 和 H 可以是正数、-1 或 -2。

如果省略 "region"，默认为 [0, 0, -1, -1]（完整渲染分辨率）。

典型用法：

输入区域使用 -1（渲染分辨率），因为光影以缩放分辨率渲染。
输出区域使用 -2（屏幕分辨率），因为超分结果是全分辨率的。

输出（Output）

"outputs" 中必须且只能包含一个键："upscaled_color"。

"outputs": {
  "upscaled_color": {
    "enabled": true,
    "target": ["colortex0"],
    "region": [0, 0, -2, -2]
  }
}

"target" — 写入超分结果的缓冲区名称列表。如果指定多个目标，结果会按顺序写入每一个。所有目标必须具有相同的尺寸。
输出始终为屏幕分辨率。
输出始终已去抖动（jitter 会被自动移除）。
色彩空间保持为 SDR。

内部纹理格式（Internal Format）

"internal_format": "r11g11b10f"

指定 SR 内部处理使用的纹理格式。

支持的值：

值	格式
`r11g11b10f`	R11G11B10F（默认）
`rgba8`	RGBA8
`rgba16f`	RGBA16F

如果省略或无法识别，默认为 R11G11B10F。

抖动（Jitter）

"jitter": {
  "enabled": true
}

启用后，SR 会在每帧生成亚像素抖动偏移。你的光影可以通过提供的 uniform（见下文）读取抖动值，并将其应用到投影矩阵中。

如果当前激活的超分算法不支持抖动，抖动不会被应用——不会产生错误，光影正常运行。

第三部分 — 运动矢量

你的光影必须提供运动矢量。SR 不会为你生成它们。

运动矢量的要求：

存储在源纹理的 RG 通道中。
使用 UV 空间（归一化 0–1 坐标）。
计算方式：

motion = previous_uv - current_uv

其中 UV 坐标基于渲染分辨率（你的缩放分辨率）。

注意：

不要翻转 Y 轴。
不要转换为 NDC。
SR 会在内部自动处理当前算法所需的坐标空间转换。

第四部分 — 着色器宏和 Uniform

当 SR 已安装且光影包包含有效的 superresolution.json 时，SR 会向你的着色器注入以下宏和 uniform。你可以利用它们在 SR 激活时调整渲染行为。

宏（Macros）

宏	说明
`SR_INSTALLED`	SR 已安装时始终为 `1`。
`SR_ENABLE`	超分启用时为 `1`，否则为 `0`。
`SR_DISABLE`	`SR_ENABLE` 的反义。
`SR_USING_ALGO`	当前激活算法的整数 ID。超分禁用时为 `0`。
`SR_ALGO_<NAME>`	每个已注册算法的整数 ID（如 `SR_ALGO_FSR2`）。可与 `SR_USING_ALGO` 比较使用。
`SR_ALGO_SUPPORTS_JITTER`	当前算法支持抖动时为 `1`，否则为 `0`。
`SR_SHOULD_APPLY_SCALE`	超分启用时为 `1`，否则为 `0`。
`SR_SHOULD_APPLY_JITTER`	超分启用时为 `1`，否则为 `0`。
`SR_SCALED_WIDTH`	渲染宽度（缩放分辨率宽度）。超分禁用时等于屏幕宽度。
`SR_SCALED_HEIGHT`	渲染高度（缩放分辨率高度）。超分禁用时等于屏幕高度。
`SR_SCREEN_WIDTH`	屏幕宽度（显示分辨率宽度）。
`SR_SCREEN_HEIGHT`	屏幕高度（显示分辨率高度）。

Uniform

Uniform	类型	说明
`SRRenderScale`	`float`	渲染缩放因子（如 50% 缩放时为 `0.5`）。超分禁用时为 `1.0`。
`SRRatio`	`float`	放大比率（屏幕 / 渲染）。超分禁用时为 `1.0`。
`SRRenderScaleLog2`	`float`	`log2(渲染宽度 / 屏幕宽度)`。超分禁用时为 `0.0`。
`SRScaledViewportSize`	`vec2`	渲染分辨率，`vec2(宽, 高)`。
`SROriginalViewportSize`	`vec2`	屏幕分辨率，`vec2(宽, 高)`。
`SRScaledViewportSizeI`	`ivec2`	渲染分辨率，`ivec2(宽, 高)`。
`SROriginalViewportSizeI`	`ivec2`	屏幕分辨率，`ivec2(宽, 高)`。
`SRJitterOffset`	`vec2`	当前帧的抖动偏移（像素空间）。不支持或未启用抖动时为 `vec2(0)`。
`SRPreviousJitterOffset`	`vec2`	上一帧的抖动偏移（像素空间）。不支持或未启用抖动时为 `vec2(0)`。

超分禁用时：

缩放值为 1.0。
抖动偏移为 vec2(0)。
SR_USING_ALGO 为 0。
SR_SCALED_WIDTH / SR_SCALED_HEIGHT 等于屏幕尺寸。

第五部分 — 错误处理

SR 的设计原则是永远不破坏你的光影管线。

情况	行为
`superresolution.json` 不存在	SR 什么都不做。光影正常运行。
JSON 格式错误	SR 完全禁用。
缺少 `schema_version`	SR 完全禁用。
`schema_version` 不受支持	SR 完全禁用。
当前维度没有匹配的配置	该维度的超分功能被禁用。
某个必需输入缺失或禁用	该帧跳过超分。
算法不支持抖动	抖动不生效，不报错。

SR 在检测到配置问题时会输出警告日志，但不会崩溃或破坏渲染管线。

完整示例

以下是一个包含多维度配置的完整 superresolution.json：

{
  "schema_version": 1,
  "profiles": {
    "*": {
      "jitter": {
        "enabled": true
      },
      "upscale": {
        "enabled": true,
        "internal_format": "r11g11b10f",
        "trigger": {
          "type": "AFTER",
          "pass": "composite2"
        },
        "inputs": {
          "color": {
            "enabled": true,
            "src": "colortex0",
            "region": [0, 0, -1, -1]
          },
          "depth": {
            "enabled": true,
            "src": "depthtex",
            "region": [0, 0, -1, -1]
          },
          "motion_vectors": {
            "enabled": true,
            "src": "colortex16",
            "region": [0, 0, -1, -1]
          }
        },
        "outputs": {
          "upscaled_color": {
            "enabled": true,
            "target": ["colortex0"],
            "region": [0, 0, -2, -2]
          }
        }
      }
    },
    "-1": {
      "jitter": {
        "enabled": true
      },
      "upscale": {
        "enabled": true,
        "internal_format": "rgba16f",
        "trigger": {
          "type": "AFTER",
          "pass": "composite1"
        },
        "inputs": {
          "color": {
            "enabled": true,
            "src": "colortex0",
            "region": [0, 0, -1, -1]
          },
          "depth": {
            "enabled": true,
            "src": "depthtex",
            "region": [0, 0, -1, -1]
          },
          "motion_vectors": {
            "enabled": true,
            "src": "colortex16",
            "region": [0, 0, -1, -1]
          }
        },
        "outputs": {
          "upscaled_color": {
            "enabled": true,
            "target": ["colortex0"],
            "region": [0, 0, -2, -2]
          }
        }
      }
    }
  }
}

在这个示例中：

默认配置（"*"）在 composite2 之后触发。
下界（"-1"）使用不同的触发 pass 和内部纹理格式。
主世界和末地没有单独的配置项，因此使用默认配置。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Shaderpack Interface documentation (Version 1) (ZH)

SR 的工作原理

第一部分 — 快速上手

步骤 1：创建配置文件

步骤 2：编写最简配置

步骤 3：在光影中提供所需数据

第二部分 — 配置参考

维度配置（Profiles）

触发点（Trigger）

输入（Inputs）

区域（Region）

输出（Output）

内部纹理格式（Internal Format）

抖动（Jitter）

第三部分 — 运动矢量

第四部分 — 着色器宏和 Uniform

宏（Macros）

Uniform

第五部分 — 错误处理

完整示例

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally