Pipeline Specification

#Pipeline Specification

General

JSON5 Support

FREX ensures that pipeline configuration files support JSON5 extensions This means you can do some useful things you can't normally do:

• comments (prefix with //)
• unquoted keys
• hexadecimal values
• leading and trailing decimal points
• positive sign

Localization

When a descriptive attribute ends with ...Key that means the config UI will attempt to use the value as a localization key. For that to work, you'll need to include the key and it's translation in accompanying lang file(s). If you don't want to deal with localization, use literal strings - those will fail localization lookup and be used directly.

Top-Level Settings

• nameKey: Localization string that will be used to label this pipeline in the renderer's pipeline configuration UI. The text associated with the string should be defined in .lang files that are part of the resource pack containing the pipeline.

• descriptionKey: Localization string that will be used to provide a tooltip for this pipeline in the renderer's pipeline configuration UI. The text associated with the string should be defined in .lang files that are part of the resource pack containing the pipeline.

• enablePBR: If present and true, the renderer should load PBR textures and make them available in shaders. If not present, not true, or if the renderer does not support PBR textures, then PBR textures will not be available in shaders. PBR status can be inspected in shaders using #ifdef PBR_ENABLED.

• glslVersion: Version of GLSL expected by pipeline code. Default is 330 and values < 330 will be ignored. Values > 330 will not work on all hardware that Mojang supports (especially Macs) and pipelines that require higher versions should clearly state they are incompatibile with Macs and possibly some older drivers.

• brightnessSmoothingFrames: The smoothing factor for frx_smoothedEyeBrightness as a number of frames. Changes in world brightness at the camera are eased using simple exponential smoothing and exposed in shaders as frx_smoothedEyeBrightness. Larger values in brightnessSmoothingFrames will cause the smoothed value to converge to actual value more gradually. Default value is 20.

• smoothBrightnessBidirectionaly: When true, the exponential smoothing in frx_smoothedEyeBrightness is active for all changes in brightness - all light level transitions will be eased. When false, only reductions in light level are smoothed and increases in light level are immediately effective. Default value is false.

• rainSmoothingFrames: The smoothing factor for frx_smoothedRainGradient as a number of frames. Changes in world rain intensity are eased using simple exponential smoothing and exposed in shaders as frx_smoothedRainGradient. Larger values in rainSmoothingFrames will cause the smoothed value to converge to actual value more gradually. Default value is 500.

• thunderSmoothingFrames: The smoothing factor for frx_smoothedThunderGradient as a number of frames. Changes in world thunder intensity are eased using simple exponential smoothing and exposed in shaders as frx_smoothedThunderGradient. Larger values in thunderSmoothingFrames will cause the smoothed value to converge to actual value more gradually. Default value is 500.

• runVanillaClear: When true, the renderer will call GL.clear() on the default framebuffer using the vanilla clear color when Minecraft would normally do so. When false, this call is disabled. A false value is useful when a pipeline implements a custom sky color or if the clear call interferes with a pipeline in some other way. When false, there is a small risk of incompatibility with mods that somehow depend on the vanilla GL call.

Material Program

The materialProgram block specifies the pipeline shaders used to render game objects that use the FREX materials system: blocks, items, block entities, entities and particles. Pipeline shaders use the API defined here.

Material Program Attributes

• vertexSource: Resource name of pipeline vertex shader source, including file extension. The .vert extension is conventional but not required. Must be in the form <mod_name>:<path within assets folder>.

• fragmentSource: Resource name of pipeline fragment shader source, including file extension. The .frag extension is conventional but not required. Must be in the form <mod_name>:<path within assets folder>.

• samplers: Optional array of GLSL names for custom samplers. These will be available in the pipeline material shaders in addition to the samplers defined by the FREX API.

• samplerImages: Array of resource names for the images to be loaded for each value of samplers. Array must have the same number of elements as samplers and elements must be in the same order.

• compileByTarget: When true, the renderer will compile a separate version of pipeline shaders for each target framebuffer and #define one of the tokens listed below to support conditional compilation. This has a small potential performance cost due to more frequent program changes and is false by default.

Preprocessor Declarations for compileByTarget

• #define MATERIAL_TARGET_UNKNOWN: Present when compileByTarget is false or if (somehow) the draw target is not one of those listed below.

• #define MATERIAL_TARGET_SOLID: Present when compileByTarget is true and the draw target is the solid framebuffer.

• #define MATERIAL_TARGET_TRANSLUCENT: Present when compileByTarget is true and the draw target is the translucent terrain framebuffer.

• #define MATERIAL_TARGET_ENTITIES: Present when compileByTarget is true and the draw target is the translucent terrain framebuffer.

• #define MATERIAL_TARGET_PARTICLES: Present when compileByTarget is true and the draw target is the translucent terrain framebuffer.

Example

materialProgram: {
    vertexSource: "canvas:shaders/pipeline/standard.vert",
    fragmentSource: "canvas:shaders/pipeline/standard.frag",
    samplers: ["cvu_glint"],
    samplerImages: ["minecraft:textures/misc/enchanted_item_glint.png"],
    compileByTarget: true
}