lamina

The onParse event is a callback provided to the Abstract constructor that runs after a layer's shader and uniforms have been parsed. It allows you to inject custom functionality that goes beyond the standard layer extension syntax, such as modifying shader code dynamically or updating the debugger (Leva) schema.

Common use cases include:

• Injecting specific shader chunks based on a non-uniform parameter.
• Adding custom controls to the debugger schema.

Note: Non-uniform parameters (parameters that change the shader structure rather than just being passed as uniforms) must be passed to the layer constructor via the args prop in React.

class CustomLayer extends Abstract {
  // ... shader definitions ...

  mapping: 'uv' | 'world' = 'uv';

  constructor(props) {
    super(
      CustomLayer,
      {
        name: 'CustomLayer',
        ...props,
      },
      (self: CustomLayer) => {
        // 1. Add to Leva (debugger) schema
        self.schema.push({
          value: self.mapping,
          label: 'mapping',
          options: ['uv', 'world'],
        })

        // 2. Inject shader chunk based on selected mapping
        const mapping = CustomLayer.getMapping(self.mapping)
        self.fragmentShader = self.fragmentShader.replace('lamina_mapping_template', mapping)
      }
    )
  }
}

In React, use the args prop to pass these non-uniform values:

<LayerMaterial>
  <customLayer
    ref={ref}
    color="green"
    alpha={0.5}
    args={[mapping]} // Non-uniform params must use `args`
  />
</LayerMaterial>

Custom layers are created by extending the Abstract class. Each layer acts as an isolated shader program that returns a vec4 color.

Key Rules:

1. Uniforms: Must start with the prefix u_. They are automatically exposed as class properties (setters/getters).
2. Varyings: Must start with the prefix v_.
3. Local Variables: Must start with the prefix f_.
4. Vertex Shader: Must return a vec3 position. You do not need to set gl_Position; Lamina handles the projection automatically.
5. Noise Functions: You can use built-in noise functions directly: lamina_noise_perlin(), lamina_noise_simplex(), lamina_noise_worley(), lamina_noise_white(), lamina_noise_swirl().

import { Abstract } from 'lamina/vanilla'

class CustomLayer extends Abstract {
  static u_color = 'red'
  static u_alpha = 1

  static fragmentShader = `   
    uniform vec3 u_color;
    uniform float u_alpha;
    varying vec3 v_Position;

    vec4 main() {
      vec4 f_color = vec4(u_color, u_alpha);
      return f_color;
    }
  `

  static vertexShader = `   
    varying vec3 v_Position;

    void main() {
      v_Position = position;
      return position * 2.;
    }
  `

  constructor(props) {
    super(CustomLayer, {
      name: 'CustomLayer',
      ...props,
    })
  }
}

import { Abstract } from 'lamina/vanilla'

// Extend the Abstract layer
class CustomLayer extends Abstract {
  // Define stuff as static properties!

  // Uniforms: Must begin with prefix "u_".
  // Assign them their default value.
  // Any unifroms here will automatically be set as properties on the class as setters and getters.
  // There setters and getters will update the underlying unifrom.
  static u_color = 'red' // Can be accessed as CustomLayer.color
  static u_alpha = 1 // Can be accessed as CustomLayer.alpha

  // Define your fragment shader just like you already do!
  // Only difference is, you must return the final color of this layer
  static fragmentShader = `   
    uniform vec3 u_color;
    uniform float u_alpha;

    // Varyings must be prefixed with "v_"
    varying vec3 v_Position;

    vec4 main() {
      // Local variables must be prefixed with "f_"
      vec4 f_color = vec4(u_color, u_alpha);
      return f_color;
    }
  `

  // Optionally Define a vertex shader!
  // Same rules as fragment shaders, except no blend modes.
  // Return a non-projected vec3 position.
  static vertexShader = `   
    // Varyings must be prefixed with "v_"
    varying vec3 v_Position;

    void main() {
      v_Position = position;
      return position * 2.;
    }
  `

  constructor(props) {
    // You MUST call `super` with the current constructor as the first argument.
    // Second argument is optional and provides non-uniform parameters like blend mode, name and visibility.
    super(CustomLayer, {
      name: 'CustomLayer',
      ...props,
    })
  }
}