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
...

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

Using custom vertex attribute layouts

The attributes field of the material lists the attributes and their types. The order and sizes must match the data fed to the vertex buffer, typically from Halley::SpriteVertexAttrib. To this end, most Halley materials derive from Halley/SpriteBase. However, if you're feeding vertices with a different layout, you should also define your own attributes.

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)
...

Note how it matches Halley::SpriteVertexAttrib:

struct SpriteVertexAttrib
{
	// This structure must match the layout of the shader
	// See shared_assets/material/sprite_base.yaml for reference
	Vector4f vertPos;
	Vector2f pos;
	Vector2f pivot;
	Vector2f size;
	Vector2f scale;
	Colour4f colour;
	Rect4f texRect;
	float rotation = 0;
	float textureRotation = 0;
	char _padding[8];
};