Skip to content

Shaderpack Interface documentation (Version 1)

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

Shader Pack Integration Guide

Schema Version: 1

Note for readers and pack authors:

  • SR behaves like a small plugin that your shader pack can call during the composite stage. It does NOT change the game's render resolution or screen resolution by itself. Any decision to render at a different internal resolution ("render scale") is yours to make inside your shader pack. SR only reads the inputs you provide, performs upscaling, and writes the result back at screen resolution.
  • SR's upscaling is only allowed during regular composite passes (not compute-based composite passes). The exact composite pass and timing are chosen by your shader pack configuration.

If you encounter any uncertainty while integrating SR, stop and ask — the guide will pause so we can clarify the exact detail before proceeding.

Part I — Usage Guide (for shader pack authors)

This short, practical guide tells you what you need to do to integrate SR quickly and correctly.

  1. High-level idea

    • You control how and where your shader renders (render resolution, buffers, and the composite pipeline).
    • When you want an upscale step, call SR at a composite pass you control. SR will:
      1. Read color, depth, and motion-vector inputs you expose.
      2. Run its upscaler.
      3. Write the upscaled color back to one or more targets at full screen resolution.
    • SR never changes your render resolution or swaps your pipeline — it only plugs into the composite step you select.

  2. Pick the right pass

    • Choose a regular composite pass (tile/quad/fragment pipeline), not a compute shader pass. SR does not support compute-based composite passes.
    • You can trigger SR either BEFORE or AFTER the named composite pass, as long as that pass is a non-compute composite pass.

  3. Provide the three required inputs

    • color — the color buffer to be upscaled (render resolution).
    • depth — a depth buffer aligned with your render coordinate conventions.
    • motion_vectors — packed RG channels in UV space (see Appendix for details).
    • All three must be available when SR runs; otherwise that frame will skip upscaling.

  4. Define outputs

    • SR writes the upscaled result at full screen resolution.
    • Configure one output key named upscaled_color which lists one or more targets SR will write into (targets must have equal sizes).
    • SR will write the de-jittered, SDR upscaled color into those targets.

  5. Jitter and subpixel AA

    • If you use render jitter/super-sampling, SR can accept jitter input and will de-jitter the result. Enable jitter support in the configuration if you want SR to consider jittered inputs.
    • If the active internal algorithm does not support jitter, enabling jitter in the config is harmless — jitter will simply not be applied.

  6. Fail-safe behavior

    • If the configuration is absent, invalid, or required inputs are missing, SR disables itself gracefully — it will never break the shader pipeline. At worst, that frame or the whole run will skip SR and rendering continues as your shader pack normally does.

  7. Where to place the config file

    • Place superresolution.json next to shader.properties (same folder as your shader pack descriptors).
    • If the file is missing, SR remains inactive.

  8. Simple integration checklist

    • Decide render resolution and whether you render at a scaled resolution (this is your shader pack's responsibility).
    • Pick a composite pass (non-compute) and position (BEFORE/AFTER).
    • Ensure color, depth, and motion_vector textures are exposed at the expected sizes.
    • Add superresolution.json with correct inputs, trigger, and outputs.
    • Test: toggle SR on/off and verify frames where SR is disabled fall back to normal rendering.

Part II — Specification Appendix (precise rules and semantics)

This appendix lists exact rules and constraints so pack authors and implementers can avoid integration mistakes.

General behavior

  • SR is a plugin stage: it reads provided inputs, applies an internal upscaler, and writes outputs at Screen Resolution.
  • SR does NOT:
    • Modify the game's Screen Resolution.
    • Force or change your Render Resolution. Render scaling must be implemented and chosen by your shader pack.
  • SR's internal upscale is only permitted at a regular (non-compute) composite pass. Compute passes used as composite are not supported for SR's composite operation.

Configuration file and schema

  • Filename: superresolution.json
  • Placed beside shader.properties.
  • If missing or JSON malformed → SR disables itself completely.
  • top-level: "schema_version": 1

Profiles and dimension handling

  • The profiles object allows per-dimension overrides.
  • Matching order: exact dimension key (e.g., "0") → "*" fallback → if none → upscaling disabled.
  • Common keys:
    • "0" → Overworld
    • "-1" → Nether
    • "1" → End
    • "*" → Default fallback

Trigger

  • trigger controls when SR runs relative to a named composite pass:
    • "type": "BEFORE" or "AFTER"
    • "pass": the name of a regular composite pass (must not be a compute pass)
  • Examples:
    • "trigger": { "type": "AFTER", "pass": "composite1" }
    • SR will run at the chosen timing; the pack decides which pass is appropriate.

Inputs

  • Required inputs (when upscaling enabled):
    • color — required
    • depth — required
    • motion_vectors — required
  • Each input block:
    • "enabled": true/false
    • "src": name of the texture as exposed by your shader pack (e.g., "colortex0", "depthtex")
    • "region": [X, Y, W, H] — see Region Field below
  • If any required input is missing at runtime, SR will skip upscaling for that frame (no error, no crash).

Region Field

  • "region": [X, Y, W, H]
    • X, Y: must be 0 or positive (pixel offset in the source texture).
    • W, H:
      • positive number → explicit size in pixels
      • -1 → full Render Resolution for that resource
      • -2 → full Screen Resolution
    • Example defaults:
      • If region is omitted for inputs, it defaults to full Render Resolution ([0,0,-1,-1]).
    • Invalid: negative X or Y (e.g., [-1,-1,-1,-1] is invalid).
  • Rule of thumb: inputs are typically defined in Render Resolution space; outputs are defined in Screen Resolution.

Motion Vectors (critical)

  • Format:
    • Stored in RG channels.
    • Values are in UV space (0..1) relative to the Render Resolution.
    • Computation: motion = previous_uv - current_uv
      • Where UV coordinates are normalized based on Render Resolution (not NDC).
  • Important constraints:
    • Do NOT flip Y when producing motion vectors.
    • Do NOT convert motion vectors to NDC before providing them.
    • If your pack computes motion differently, convert it to the required format or ask for clarification.
  • SR will internally map the UV-based motion into whatever its algorithm needs; provide motion in the specified RG UV format.

Outputs

  • The outputs block must contain exactly one key named upscaled_color.
  • Example: "outputs": { "upscaled_color": { "enabled": true, "target": ["colortex0"], "region": [0, 0, -2, -2] } }
  • Rules:
    • Output resolution is always Screen Resolution.
    • The upscaled image that SR writes is de-jittered (any jitter is removed).
    • Color space of output is SDR (SR does not perform HDR conversion).
    • If multiple targets are listed, SR writes them in the order given; all targets must share the same size.
    • All output targets must be capable of holding full Screen Resolution content.

Jitter

  • "jitter": { "enabled": true/false }
    • If enabled, SR will expect and handle sub-pixel jitter offsets (pack must provide jitter uniforms as usual).
    • If the selected SR algorithm doesn't support jitter, enabling jitter in config has no effect (it's safe to enable).

Failure and error handling

  • Malformed JSON → SR disables itself.
  • Missing or invalid required blocks → SR disables itself.
  • Missing inputs at runtime → that frame skips SR processing (rendering continues).
  • SR will never crash or permanently break the shader pipeline; it quietly disables or skips frames as needed.

Shader macros and uniforms

  • When SR is active, shaders may receive the following macros and uniforms (informational; presence depends on integration):
    • Macros:
      • SR_INSTALLED (1 when SR available)
      • SR_USING_ALGO (non-zero when an algorithm is active)
      • SR_ALGO_SUPPORTS_JITTER (non-zero if jitter is supported)
    • Uniforms:
      • SRRenderScale (scale factor between Render and SR internal size)
      • SRRatio (aspect or ratio helpers)
      • SRScaledViewportSize (width,height in internal scaled pixels)
      • SROriginalViewportSize (width,height in original render pixels)
      • SRJitterOffset (current jitter)
      • SRPreviousJitterOffset (previous frame jitter)
  • When SR is disabled:
    • Scale values default to 1.0
    • Jitter offsets default to 0
    • SR_USING_ALGO evaluates to 0

Example configuration (simple, clear)

{
  "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]
          }
        }
      }
    }
  }
}

Integration tips and common pitfalls

  • Confirm the pass you choose is not implemented as compute. If unsure, ask — tell me the pass name and I will advise whether it's acceptable.
  • Verify motion vectors are in RG and UV space. Test with a simple moving quad and check values.
  • If you render at a lower internal resolution, be sure your color/depth inputs reflect that resolution consistently.
  • Start with SR disabled and validate your rendering pipeline. Then enable SR and check differences frame-by-frame.

If you need an alternate example for:

  • a pack that renders directly at screen resolution (no internal scale), or
  • a pack that uses a custom composite pass name, tell me which case you want and I will pause and generate the exact JSON and integration notes.

Clone this wiki locally