Skip to content

Shaderpack Interface documentation (Version 1)

Jump to bottom
187J3X1-114514 edited this page Feb 21, 2026 · 14 revisions

  1. Create superresolution.json in the same directory as shader.properties

  2. Declare the upscaling trigger point and input/output resources for each dimension in this file. See below for details.

Note

SR does not plan to support OptiFine. If your shader pack targets OptiFine, the SR configuration file will have no unintended side effects.

Note

When SR detects a valid compatibility configuration file in the shader pack, it will not resize the game's framebuffers. The shader pack is then responsible for handling resolution scaling manually.

Important

The SR config parser has limited error tolerance. Some fields have defaults (for example, missing region falls back to [0, 0, -1, -1], and unsupported internal_format falls back to r11g11b10f). However, malformed JSON, missing schema_version, or other runtime-invalid structures can still fail loading and fall back to standard rendering mode. Check the game log for error details.

Configuration Structure

Top-Level Structure

{
    "schema_version": 1,
    "profiles": {
        "<dimension key>": {
            "jitter": {
                "enabled": true
            },
            "upscale": {
                "enabled": true,
                "internal_format": "r11g11b10f",
                "trigger": {
                    "type": "AFTER",
                    "pass": "<composite pass name>"
                },
                "inputs": {
                    "<texture name>": {
                        "enabled": true,
                        "src": "<texture source>",
                        "region": [X, Y, W, H]
                    }
                },
                "outputs": {
                    "upscaled_color": {
                        "enabled": true,
                        "target": [
                            "<target texture source>"
                        ],
                        "region": [X, Y, W, H]
                    }
                }
            }
        }
    }
}

Dimension Key

  • Dimension profiles are identified by string keys. SR resolves the current dimension ID to a key via Iris's internal dimensionMap to look up the matching profile.
  • The wildcard "*" can be used as a default/fallback profile when no matching dimension key is found.
  • The meaning of specific key values depends on the dimension mapping defined by the shader pack itself. Typically, "0" is the Overworld, "-1" is the Nether, and "1" is the End.

Texture Name Reference (inputs keys)

Name Description
color Input color texture
depth Input depth texture
motion_vectors Input motion vector texture (RG channels; R = X direction, G = Y direction. The input motion vector should be in UV space, with the R/G channel range of each pixel being [-1,-1] to [1,1]. The calculation formula is similar to (previousScreenPosition - currentScreenPosition) / RenderSize. For some algorithms running on Vulkan, the Mod will automatically flip the Y-axis (by multiplying the value on the G channel by -1).)

Output Texture Key Reference (outputs keys)

Name Description
upscaled_color Upscaled result output texture. This key name is fixed and must not be changed.

Parameter Reference

Global

Key Description Example
schema_version Schema version of the configuration file. Current version is 1. 1

Dimension Profile (profiles)

Each profile entry contains the following fields:

Jitter Configuration (jitter)

Key Description Example
enabled Whether to enable jitter for this dimension true

Upscale Configuration (upscale)

Key Description Example
enabled Whether to enable super-resolution upscaling for this dimension true
internal_format Specifies the internal texture format used by the upscaler. Affects intermediate and temporary I/O textures. Default: r11g11b10f. Supported values: rgb8, rgba8, rgba16f, rgba16, rgb16f, r11g11b10f r11g11b10f

Trigger Configuration (trigger)

Key Description Example
type When to trigger upscaling. BEFORE triggers before the specified pass; AFTER triggers after it. Case-insensitive. Values other than BEFORE are treated as AFTER by the current parser. AFTER
pass The non-compute composite pass name at which to trigger upscaling, e.g. composite1, composite2 composite1

Input Texture Configuration (inputs)

The inputs field is an object whose keys are texture types (e.g. color, depth, motion_vectors) and values are texture configuration objects:

Important

In the current implementation, color, depth, and motion_vectors should all be present in inputs. Missing entries may cause dispatch-time errors instead of being gracefully ignored.

Key Description Example
enabled Whether to enable this input texture true
src Texture source name. Recommended values: colortexX, alttexX, depthtex, noHandDepthtex, noTranslucentDepthtex colortex0
region Input region array [X, Y, W, H]. Special negative values:
-1 = scaled render resolution (full frame)
-2 = original screen resolution (full frame)		 [0, 0, -1, -1]

Output Texture Configuration (outputs)

The outputs field is an object whose key is fixed as upscaled_color. The value is a texture configuration object:

Key Description Example
enabled Whether to enable this output texture true
target Array of output target texture names. Recommended: colortexX, alttexX ["colortex0", "alttex0"]
region Output region array [X, Y, W, H]. Same negative value semantics as input region. [0, 0, -2, -2]

Note

SR supports writing the upscaled result to multiple textures simultaneously. See the GlTextureCopier class for implementation details.

Important

The key name inside outputs must be upscaled_color. SR internally looks up this exact key to read the output configuration. Using any other key can trigger runtime errors during dispatch (rather than a guaranteed silent skip).

Example Configuration (JSON)

{
    "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",
                            "alttex0"
                        ],
                        "region": [0, 0, -2, -2]
                    }
                }
            }
        },
        "0": {
            "jitter": {
                "enabled": true
            },
            "upscale": {
                "enabled": true,
                "internal_format": "rgba16f",
                "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]
                    }
                }
            }
        }
    }
}

SR Support Inside Shaders

SR automatically injects the following macros and uniforms into shaders:

Defines

Name Description
SR_INSTALLED Always 1. Indicates that the SR mod is installed.
SR_ENABLE 1 when upscaling is enabled, otherwise 0.
SR_DISABLE 1 when upscaling is disabled, otherwise 0.
SR_ALGO_<CODENAME> Unique integer identifier for each algorithm, e.g. SR_ALGO_FSR2, SR_ALGO_DLSS.
SR_ALGO_SUPPORTS_JITTER 1 if the current algorithm supports jittered color input, otherwise 0.
SR_USING_ALGO The ID of the currently active upscale algorithm (matches a SR_ALGO_* value). 0 when upscaling is disabled.
SR_SHOULD_APPLY_SCALE 1 when upscaling is enabled, otherwise 0. Indicates whether scaling should be applied. (Currently always 1.)
SR_SHOULD_APPLY_JITTER 1 when upscaling is enabled, otherwise 0. Currently this follows upscale enable state directly; use SR_ALGO_SUPPORTS_JITTER to determine whether jitter is actually supported by the active algorithm.
SR_SCALED_WIDTH Scaled render width in pixels. Equals screen width when upscaling is disabled.
SR_SCALED_HEIGHT Scaled render height in pixels. Equals screen height when upscaling is disabled.
SR_SCREEN_WIDTH Original screen width in pixels.
SR_SCREEN_HEIGHT Original screen height in pixels.

Tip

The specific algorithm identifier macros available depend on which SR extension mods are installed. Common algorithms include:
SR_ALGO_FSR2 - AMD FidelityFX Super Resolution 2
SR_ALGO_FSR1 - AMD FidelityFX Super Resolution 1
SR_ALGO_SGSR1 - Snapdragon™ Game Super Resolution 1
SR_ALGO_SGSR2 - Snapdragon™ Game Super Resolution 2
SR_ALGO_DLSS - NVIDIA Deep Learning Super Sampling (experimental)
SR_ALGO_XESS - Intel Xe Super Sampling (experimental)
SR_ALGO_FSR - AMD FidelityFX Super Resolution (experimental; actual algorithm depends on user settings, may be FSR2 or FSR3)
SR_ALGO_NONE - No upscaling algorithm

Note

When both SR_ALGO_SUPPORTS_JITTER and SR_SHOULD_APPLY_JITTER are 1, shaders may use the jitter offset provided by SR directly. Regardless of these macro values, the upscaled output is always de-jittered.

Uniforms

Name Type Description
SRRenderScale float Render scale factor. 1.0 when upscaling is disabled.
SRRatio float Upscale ratio. Equal to 1 / SRRenderScale. 1.0 when upscaling is disabled.
SRRenderScaleLog2 float Log₂ of the render scale: log2(renderWidth / screenWidth). 0.0 when upscaling is disabled. Should be used as a Mipmap LOD bias when sampling textures to improve texture detail.
SRScaledViewportSize vec2 Scaled viewport size (render resolution) in pixels.
SROriginalViewportSize vec2 Original viewport size (screen resolution) in pixels.
SRScaledViewportSizeI ivec2 Scaled viewport size as integers.
SROriginalViewportSizeI ivec2 Original viewport size as integers.
SRJitterOffset vec2 Current frame jitter offset in pixel space. Always vec2(0.0) when the algorithm does not support jitter.
SRPreviousJitterOffset vec2 Previous frame jitter offset in pixel space. Always vec2(0.0) when the algorithm does not support jitter. Useful for TAA and other algorithms that require the previous frame's jitter.

Example Code

#ifdef SR_INSTALLED
    #ifdef SR_UTILS_SHOULD_ADD_UNIFORMS
        uniform float SRRatio;
        uniform float SRRenderScale;
        uniform float SRRenderScaleLog2;
        uniform vec2 SRScaledViewportSize;
        uniform vec2 SROriginalViewportSize;
        uniform ivec2 SRScaledViewportSizeI;
        uniform ivec2 SROriginalViewportSizeI;
        uniform vec2 SRJitterOffset;
    #endif // SR_UTILS_SHOULD_ADD_UNIFORMS
    #define MC_RENDER_SCALE (SRRenderScale)
    #define MC_RENDER_RATIO (SRRatio)
    #define MC_RENDER_SCALE_LOG2 (SRRenderScaleLog2)
    #define MC_SCALED_VIEWPORT_SIZE (SRScaledViewportSize)
    #define MC_ORIGINAL_VIEWPORT_SIZE (SROriginalViewportSize)
    #define MC_SCALED_VIEWPORT_SIZEI (SRScaledViewportSizeI)
    #define MC_ORIGINAL_VIEWPORT_SIZEI (SROriginalViewportSizeI)
    #if (SR_ALGO_SUPPORTS_JITTER == 1) && (SR_SHOULD_APPLY_JITTER == 1)
        #define MC_JITTER_OFFSET (SRJitterOffset)
    #else
        #define MC_JITTER_OFFSET (vec2(0.0))
    #endif //(SR_ALGO_SUPPORTS_JITTER == 1) && (SR_SHOULD_APPLY_JITTER == 1)
#else
    #define MC_RENDER_SCALE (1.0)
    #define MC_RENDER_RATIO (1.0)
    #define MC_RENDER_SCALE_LOG2 (0.0)
    #define MC_SCALED_VIEWPORT_SIZE (vec2(viewWidth, viewHeight))
    #define MC_ORIGINAL_VIEWPORT_SIZE (vec2(viewWidth, viewHeight))
    #define MC_SCALED_VIEWPORT_SIZEI (ivec2(viewWidth, viewHeight))
    #define MC_ORIGINAL_VIEWPORT_SIZEI (ivec2(viewWidth, viewHeight))
    #define MC_JITTER_OFFSET (vec2(0.0))
#endif // SR_INSTALLED

Clone this wiki locally