Shader Pass format - Ladysnake/Satin GitHub Wiki

This description is based on reverse-engineering of MC 1.14.

The Shader Pass JSON is defined as an object.

Types

BlendEquation

A blend equation is a string representing a valid OpenGl Blend Equation. Accepted values are "add", "subtract", "reversesubstract" or "reverse_subtract", "min", and "max". The case does not matter.

BlendComponent

A blend component is a string representing a valid OpenGl Blend Function parameter. Underscores are ignored, "one" is equivalent to "1", "zero" is equivalent to "0", and "minus" is equivalent to "-". Must be resolved to one of "0", "1", "srccolor", "1-srccolor", "dstcolor", "1-dstcolor", "srcalpha", "1-srcalpha", "dstalpha", or "1-dstalpha".

BlendState

A blend state is an object with the following keys:

  • func: an optional BlendEquation. Defaults to "add".
  • srcrgb: an optional BlendComponent. Defaults to "one".
  • dstrgb: an optional BlendComponent. Defaults to "zero".
  • srcalpha: an optional BlendComponent. Defaults to "one".
  • dstalpha: an optional BlendComponent. Defaults to "zero".

Sampler

A sampler is an object with the following keys:

  • name: a string identifying a sampler uniform in the fragment shader.
  • file: an optional string. observation: does not seem to do anything

The sampler name should correspond to either an auxiliary target defined in the post process shader file or DiffuseSampler (the input target of the pass). Otherwise, it must be set externally in the application code.

Uniform

A uniform is an object with the following mandatory keys:

  • name: a string identifying a uniform in the fragment shader.
  • type: a string denoting a GLSL type. Accepted values are "int", "float", "matrix2x2", "matrix3x3", and "matrix4x4".
  • count: an int denoting the number of values in the given uniform. Should be 1 for an atomic value, between 2 and 4 for vectors, and the size of the matrix for matrix types. observation: validation for this number is completely broken - do not put stupid values.
  • values: an array of numbers containing the default values for this uniform. Length must be equal tocount. Alternatively, an array of length one will fill the uniform with that number.

Mandatory fields

  • vertex: a string providing the name of a vertex shader file (with the .vsh extension omitted) located in assets/minecraft/shaders/program/.
  • fragment: a string providing the name of a fragment shader file (with the .fsh extension omitted) located in assets/minecraft/shaders/program/.

Satin adds the possibility of using an Identifier format for both fragment and vertex file locations (domain:shader_source_file).

Optional fields

  • samplers: an array of Sampler objects representing sampler uniforms found in the fragment shader's source.
  • attributes: an array of attributes declared in the shader source. observation: currently not used for anything
  • uniforms: an array of Uniform objects representing scalar uniforms found in the shader's source.
  • blend: a BlendState object indicating how the shader output should blend with the existing texture on the output framebuffer.
  • cull: true if the pass should use face culling, false otherwise.

Default uniforms

There are several uniforms which values will be automatically set each render. You can find all of them in the body of the PostEffectPass#render method.

Example

This is the blit shader definition:

{
    "blend": {
        "func": "add",
        "srcrgb": "srcalpha",
        "dstrgb": "1-srcalpha"
    },
    "vertex": "blit",
    "fragment": "blit",
    "attributes": [ "Position" ],
    "samplers": [
        { "name": "DiffuseSampler" }
    ],
    "uniforms": [
        { "name": "ProjMat",       "type": "matrix4x4", "count": 16, "values": [ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0 ] },
        { "name": "OutSize",       "type": "float",     "count": 2,  "values": [ 1.0, 1.0 ] },
        { "name": "ColorModulate", "type": "float",     "count": 4,  "values": [ 1.0, 1.0, 1.0, 1.0 ] }
    ]
}

It uses the blit vertex and fragment shaders, respectively located in assets/minecraft/shaders/program/blit.vsh and assets/minecraft/shaders/program/blit.fsh. The vertex shader declares the "Position" attribute, and the "ProjMat" and "OutSize" uniforms. The fragment shader declares the "ColorModulate" uniform.

  • ProjMat is a mat4, denoted by a matrix4x4 in the JSON, and defaults to the identity matrix.
  • OutSize is a vec2, denoted by a float with a count of 2 in the JSON, and defaults to [1.0, 1.0].
  • ColorModulate is a vec4, denoted by a float with a count of 4 in the JSON, and defaults to opaque white (which basically means the input texture overwrites the output texture with no alteration).

The output from the shader blends with the existing texture using the standard alpha blending function (you can eg. change dstrgb to "one" for additive blending).