Materials

Overview

Materials describe how a particular draw call (including Sprites and Text Rendering) should look like. They store the following information:

• The vertex attribute layout
• The textures/samplers used
• The uniforms/constants used
• The drawing passes, and, for each of them:
  • The blend mode used
  • The vertex, geometry and pixel shaders used, for each language supported

Materials may inherit from other materials, copying their original properties and overriding them. Most materials inherit from Halley/SpriteBase, since that defines the standard vertex attribute layout.

A few default materials are provided by Halley, such as:

• Halley/SpriteBase: Base material that describes the standard vertex attribute layout used by Halley Sprites
• Halley/Sprite: Standard alpha blended sprite
• Halley/SpriteAdd: Standard add blended sprite
• Halley/SpriteOpaque: Standard opaque blended sprite
• Halley/SolidColour: Draws a solid colour, without textures
• Halley/DistanceFieldSprite: Renders images encoded with distance fields
• Halley/Text: Renders distance field encoded text, with outlines

Declaration

Here's an example material, Halley/Sprite, which ships with Halley:

---
name: Halley/Sprite
base: sprite_base.yaml
textures:
  - tex0: sampler2D
passes:
  - blend: AlphaPremultiplied
    shader:
      - language: glsl
        vertex: sprite.vertex.glsl
        pixel: sprite.pixel.glsl
      - language: hlsl
        vertex: sprite.vertex.hlsl
        pixel: sprite.pixel.hlsl
...

The base sprite material:

---
name: Halley/SpriteBase
attributes:
  - a_vertPos: vec4          # xy = relative position of vertex [0..1], zw = relative position of texture [0..1]
  - a_position: vec2         # position (world space)
  - a_pivot: vec2            # relative pivot [0..1]
  - a_size: vec2             # size (px), should be the size of the texture
  - a_scale: vec2            # scale (relative)
  - a_colour: vec4           # rgba
  - a_texCoord0: vec4        # xy = top-left, zw = bottom-right
  - a_rotation: float        # rotation (radians)
  - a_textureRotation: float # is the sprite rotated? (1 if 90 degrees rotated)
...

Here's an example that uses multi-texturing and uniforms:

---
name: Wargroove/PaletteSwap
base: sprite_base.yaml
textures:
  - tex0: sampler2D
  - tex1: sampler2D
uniforms:
  - MaterialBlock:
    - playerColour: float
    - skinColour: float
passes:
  - blend: AlphaPremultiplied
    shader:
      - language: glsl
        vertex: sprite.vertex.glsl
        pixel: palette_swap.pixel.glsl
      - language: hlsl
        vertex: sprite.vertex.hlsl
        pixel: palette_swap.pixel.hlsl
...

Using MaterialDefinitions and Materials

todo