Skip to content

Shaderpack Interface documentation (Version 1)

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

Super Resolution (SR) Configuration Specification

Version: 1
Schema Version: 1

This document defines the formal configuration contract for SR shader integration.

1. Terminology

To avoid ambiguity, the following terms are used consistently:

Term Definition
Screen Resolution Final display resolution in pixels (post-upscale output resolution).
Render Resolution Internal rendering resolution before upscaling.
Scaled Resolution Same as Render Resolution.
Viewport Size Active framebuffer size in pixels.
NDC Normalized Device Coordinates in range [-1, 1].
UV Space Normalized texture coordinate space in range [0, 1].

Unless explicitly stated otherwise, all sizes are in pixel units.

2. OptiFine Compatibility

SR does not support OptiFine.

If running under OptiFine:

  • SR configuration files are ignored.
  • No framebuffers are resized.
  • No shader macros or uniforms are injected.
  • Behavior outside this specification is undefined.

3. File Location

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

4. Error Handling Model

The configuration parser operates under the following rules:

4.1 Fatal Errors (Configuration Load Fails)

The following conditions cause configuration load failure and fallback to standard rendering:

  • Malformed JSON
  • Missing schema_version
  • Unsupported schema_version
  • Invalid structural types (e.g., object where array required)
  • Missing required fields explicitly marked as required

4.2 Non-Fatal Errors (Field-Level Fallback)

The following fall back to defaults:

  • Missing optional fields
  • Unsupported internal_format
  • Missing region field

4.3 Runtime Dispatch Errors

The following conditions cause dispatch failure:

  • Missing required input entries (color, depth, motion_vectors)
  • Missing required output key upscaled_color

Dispatch failures are logged and skip upscaling for that frame.

5. Configuration Structure

5.1 Top-Level Structure

{
    "schema_version": 1,
    "profiles": {
        "<dimension key>": { ... }
    }
}

Required Fields

  • schema_version (integer, required)
  • profiles (object, required)

6. Dimension Profiles

Profiles are keyed by string identifiers.

Resolution behavior:

  • The active dimension ID is mapped via Iris's internal dimension mapping.
  • If no matching key is found, "*" is used as fallback.
  • If neither a direct match nor "*" exists, upscaling is disabled.

Typical dimension IDs:

  • "0": Overworld
  • "-1": Nether
  • "1": End

7. Profile Structure

{
    "jitter": { ... },
    "upscale": { ... }
}

Both sections are optional. If upscale.enabled is false or missing, upscaling is disabled for that dimension.

8. Jitter Configuration

"jitter": {
    "enabled": true
}
Field Type Required Description
enabled boolean yes Enables jitter offset generation for this dimension.

9. Upscale Configuration

"upscale": {
    "enabled": true,
    "internal_format": "r11g11b10f",
    "trigger": { ... },
    "inputs": { ... },
    "outputs": { ... }
}
Field Required Description
enabled yes Enables super-resolution upscaling.
internal_format no Intermediate texture format. Defaults to r11g11b10f.
trigger yes Defines execution stage.
inputs yes Required input textures.
outputs yes Required output definition.

10. Internal Format

Supported values:

  • rgb8
  • rgba8
  • rgba16
  • rgba16f
  • rgb16f
  • r11g11b10f

Unsupported values fall back to r11g11b10f.

11. Trigger Configuration

"trigger": {
    "type": "AFTER",
    "pass": "composite1"
}
Field Required Description
type yes Must be BEFORE or AFTER (case-insensitive).
pass yes Name of non-compute composite pass.

Invalid type values cause configuration load failure.

12. Input Configuration

Required keys inside inputs:

  • color
  • depth
  • motion_vectors

All three must be present.

12.1 Input Structure

"color": {
    "enabled": true,
    "src": "colortex0",
    "region": [0, 0, -1, -1]
}
Field Required Description
enabled yes Enables use of this input.
src yes Texture source name.
region no Region rectangle [X, Y, W, H].

Region Semantics

Special values:

  • -1 → Render Resolution (full frame)
  • -2 → Screen Resolution (full frame)

If omitted, defaults to [0, 0, -1, -1].

13. Motion Vector Specification

Motion vectors must satisfy:

  • Stored in RG channels

  • R = X direction

  • G = Y direction

  • Each component in range [-1, 1]

  • Expressed in UV space

  • Computed as:

    (previous_position_uv - current_position_uv)

where positions are in normalized UV coordinates relative to Render Resolution.

Backend Adjustment

For Vulkan-based algorithms requiring inverted Y conventions, SR applies Y-axis inversion internally.

Shader authors must not pre-flip motion vectors.

14. Output Configuration

The outputs object MUST contain exactly one key:

"upscaled_color"

Any other key causes dispatch failure.

Output Structure

"upscaled_color": {
    "enabled": true,
    "target": ["colortex0"],
    "region": [0, 0, -2, -2]
}
Field Required Description
enabled yes Enables writing result.
target yes Array of output textures.
region no Output region.

Multiple targets are supported.

If region is omitted, defaults to [0, 0, -2, -2].

15. Shader Injection Contract

When SR is active, the following macros are injected:

  • SR_INSTALLED
  • SR_ALGO_
  • SR_ALGO_SUPPORTS_JITTER
  • SR_USING_ALGO
  • SR_SHOULD_APPLY_SCALE
  • SR_SHOULD_APPLY_JITTER
  • SR_SCALED_WIDTH
  • SR_SCALED_HEIGHT
  • SR_SCREEN_WIDTH
  • SR_SCREEN_HEIGHT

When upscaling is disabled:

  • SR_USING_ALGO = 0
  • SR_SHOULD_APPLY_SCALE = 0
  • SR_SHOULD_APPLY_JITTER = 0

16. Uniforms

Name Type Description
SRRenderScale float Render Resolution / Screen Resolution
SRRatio float 1 / SRRenderScale
SRRenderScaleLog2 float log2(Render Resolution / Screen Resolution)
SRScaledViewportSize vec2 Render Resolution
SROriginalViewportSize vec2 Screen Resolution
SRScaledViewportSizeI ivec2 Render Resolution
SROriginalViewportSizeI ivec2 Screen Resolution
SRJitterOffset vec2 Current frame jitter in pixel space
SRPreviousJitterOffset vec2 Previous frame jitter

If jitter unsupported, jitter uniforms are vec2(0.0).

17. Stability Notes

Algorithms marked experimental:

  • May change behavior
  • May change identifier values
  • No backward compatibility guarantee

Stable algorithms guarantee backward-compatible identifier values within the same major schema version.

Clone this wiki locally