Shader Definition and Usage

Ingredients

A shader on a block or item requires three things:

1. Vertex and/or fragment source files containing GLSL code for your shader. The code must follow the conventions and API defined by Canvas.

2. At least one RenderMaterial that contains the shaders.

3. Quads on block or item models that reference the RenderMaterial containing the shaders.

When all of these ingredients are present, Canvas will automatically compile the shader, feed it all necessary vertex data and uniforms, and activate it for any visible quads associated with the material.

Shader Sources

Shaders sources are declared to Canvas via namespaced identifiers. The path is relative to the assets/ folder and contains the full file path and extension. The extension is necessary because they tend to vary between .glsl, .frag and .vert depending on the intended usage. Material shaders are expected to reside in assets/<namespace>/shaders/material but this is not a hard restriction.

The way that Canvas receives the shader names depends on how the material is defined...

Defining Materials

There are two ways to define RenderMaterials with shaders:

1. Use Java code and the extended version of MaterialFinder with ShaderBuilder to create a RenderMaterial compatible with the Fabric Renderer API.

2. Use the FREX JSON material loader as demonstrated in the tutorial. Documentation is currently scarce, but there are examples of usage in the Canvas asset tree.

Registered Materials

Note that materials can be registered and retrieved using namedspaced identifiers. This feature is part of the core Rendering API and is a useful way to share materials created by Java code with other mod authors or pack makers.

Applying Materials to Models

There are several ways to apply a material to a block or item model.

1. Implement FabricBakedModel and directly associate the materials as the quads are built using MeshBuilder or QuadEmitter. This method requires Java code.

2. Transform an existing model using a QuadTransform. However, this typically requires a FabricBakedModel that encapsulates the transformed model. This method also requires Java code.

3. Use FREX material maps as described in the tutorial. These maps are quite flexible and good for handling vanilla models. They can handle per-sprite associations but cannot change the model otherwise. See the Canvas asset tree for examples.

4. Use JMX to create JSON models that reference registered materials.

5. Use Exotic Matter to reference registered materials. (Generally XM models are created with Java code so this is only attractive if you are already planning to use XM.)