Shade

Cross-platform shaders using the Haxe programming language.

Shade is a vertex and fragment shader transpiler that converts Haxe shader code to GLSL (OpenGL/WebGL) and Unity (HLSL/Cg) formats. It uses the reflaxe library for macro-based transpilation. Additional target shader languages can be added by providing custom backends.

This project is primarily intended to be used with Ceramic, but could work with other game engines too. It is very close to the GLSL spec, although it doesn't try to cover the entirety of it.

Table of Contents

• Quick Start
• Command Line Interface
• Shader Structure
• Field Annotations
• Types
• Built-in Functions
• Operators
• Control Flow
• Helper Functions
• Multi-Texture Support
• Output Examples

Quick Start

Here's a basic textured shader:

package shaders;

class Textured extends Shader<Textured_Vert, Textured_Frag> {}

class Textured_Vert extends Vert {
    @param var projectionMatrix:Mat4;
    @param var modelViewMatrix:Mat4;

    @in var vertexPosition:Vec3;
    @in var vertexTCoord:Vec2;
    @in var vertexColor:Vec4;

    @out var tcoord:Vec2;
    @out var color:Vec4;

    function main():Vec4 {
        tcoord = vertexTCoord;
        color = vertexColor;
        return projectionMatrix * modelViewMatrix * vec4(vertexPosition, 1.0);
    }
}

class Textured_Frag extends Frag {
    @param var mainTex:Sampler2D;

    @in var tcoord:Vec2;
    @in var color:Vec4;

    function main():Vec4 {
        var texColor = texture(mainTex, tcoord);
        return color * texColor;
    }
}

Setup

1. Install Haxe: https://haxe.org/download/

2. Install shade library:

# Install shade
haxelib install shade

3. Transpile your shader:

# Transpile to GLSL
haxelib run shade --in shaders/Textured.hx --target glsl --out output/

# Transpile to Unity (ShaderLab)
haxelib run shade --in shaders/Textured.hx --target unity --out output/

Command Line Interface

Shade provides a CLI for transpiling shaders.

Usage

haxelib run shade --in <shader.hx> --target <glsl|unity> [--out <dir>] [--hxml <extra>]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | --in <path> | Yes | Input Haxe shader file (can be repeated for multiple files) | | --target <backend> | Yes | Target backend: glsl, unity, or custom | | --out <dir> | No | Output directory (default: current directory) | | --hxml <content> | No | Additional hxml compiler options |

Examples

# Single shader to GLSL
haxelib run shade --in src/Blur.hx --target glsl --out shaders/

# Multiple shaders to Unity
haxelib run shade --in src/Blur.hx --in src/Bloom.hx --target unity --out unity-shaders/

# With custom defines
haxelib run shade --in src/Custom.hx --target glsl --hxml "-D my_define"

Shader Structure

Shaders are defined as Haxe classes:

• Shader<V, F> - Main shader class that pairs a vertex shader with a fragment shader
• Vert - Base class for vertex shaders (class name must end with _Vert)
• Frag - Base class for fragment shaders (class name must end with _Frag)

class MyShader extends Shader<MyShader_Vert, MyShader_Frag> {}

class MyShader_Vert extends Vert {
    function main():Vec4 {
        // Return vertex position (becomes gl_Position)
        return vec4(0.0, 0.0, 0.0, 1.0);
    }
}

class MyShader_Frag extends Frag {
    function main():Vec4 {
        // Return fragment color (becomes fragColor)
        return vec4(1.0, 0.0, 0.0, 1.0);
    }
}

The main() function is required:

• In vertex shaders, it returns the vertex position (Vec4)
• In fragment shaders, it returns the fragment color (Vec4)

Field Annotations

@param - Uniform Parameters

Values passed from CPU to shader, constant for all vertices/fragments in a draw call:

@param var projectionMatrix:Mat4;
@param var modelViewMatrix:Mat4;
@param var mainTex:Sampler2D;
@param var time:Float;
@param var resolution:Vec2;

@in - Input Varyings

In vertex shaders: per-vertex attributes from vertex buffers:

@in var vertexPosition:Vec3;
@in var vertexTCoord:Vec2;
@in var vertexColor:Vec4;

In fragment shaders: interpolated values from vertex shader outputs:

@in var tcoord:Vec2;
@in var color:Vec4;

@out - Output Varyings

Values computed in vertex shader, interpolated across the triangle, and read in the fragment shader:

// In vertex shader
@out var tcoord:Vec2;
@out var color:Vec4;

The corresponding @in in the fragment shader must have the same name.

Types

Scalar Types

| Type | Description | |------|-------------| | Float | Single-precision floating point | | Int | Integer | | Bool | Boolean |

Vector Types

| Type | Description | |------|-------------| | Vec2 | 2-component float vector | | Vec3 | 3-component float vector | | Vec4 | 4-component float vector |

Matrix Types

| Type | Description | |------|-------------| | Mat2 | 2x2 float matrix (column-major) | | Mat3 | 3x3 float matrix (column-major) | | Mat4 | 4x4 float matrix (column-major) |

Sampler Types

| Type | Description | |------|-------------| | Sampler2D | 2D texture sampler |

Component Access

Vectors support multiple naming conventions for component access:

var v:Vec4 = vec4(1.0, 2.0, 3.0, 4.0);

// Position components
v.x; v.y; v.z; v.w;

// Color components
v.r; v.g; v.b; v.a;

// Texture components
v.s; v.t; v.p; v.q;

Swizzling

Read and write swizzles are supported:

var pos:Vec3 = vec3(1.0, 2.0, 3.0);
var xy:Vec2 = pos.xy;               // Read swizzle: vec2(1.0, 2.0)
var rgb:Vec3 = vec4(1,2,3,4).rgb;   // Extract first 3 components

var color:Vec4 = vec4(0.0);
color.xyz = vec3(1.0, 0.0, 0.0);    // Write swizzle

Built-in Functions

Texture Sampling

| Function | Description | |----------|-------------| | texture(sampler:Sampler2D, coord:Vec2):Vec4 | Sample texture at coordinate |

Angle and Trigonometric Functions

| Function | Description | |----------|-------------| | radians(degrees) | Convert degrees to radians | | degrees(radians) | Convert radians to degrees | | sin(angle) | Sine (angle in radians) | | cos(angle) | Cosine (angle in radians) | | tan(angle) | Tangent (angle in radians) | | asin(x) | Arc sine, returns [-π/2, π/2] | | acos(x) | Arc cosine, returns [0, π] | | atan(y_over_x) | Arc tangent, returns [-π/2, π/2] | | atan(y, x) | Arc tangent of y/x using signs to determine quadrant, returns [-π, π] |

All trigonometric functions work on Float, Vec2, Vec3, and Vec4.

Exponential Functions

| Function | Description | |----------|-------------| | pow(x, y) | x raised to power y | | exp(x) | e^x | | exp2(x) | 2^x | | log(x) | Natural logarithm ln(x) | | log2(x) | Base-2 logarithm | | sqrt(x) | Square root | | inversesqrt(x) | Inverse square root (1/√x) |

All exponential functions work on Float, Vec2, Vec3, and Vec4.

Common Functions

| Function | Description | |----------|-------------| | abs(x) | Absolute value | | sign(x) | Returns -1.0, 0.0, or 1.0 | | floor(x) | Largest integer ≤ x | | ceil(x) | Smallest integer ≥ x | | fract(x) | Fractional part: x - floor(x) | | mod(x, y) | Modulo: x - y * floor(x/y) | | min(x, y) | Minimum value | | max(x, y) | Maximum value | | clamp(x, min, max) | Constrain x to [min, max] | | mix(x, y, a) | Linear interpolation: x*(1-a) + y*a | | step(edge, x) | 0.0 if x < edge, else 1.0 | | smoothstep(edge0, edge1, x) | Smooth Hermite interpolation |

All common functions work on Float, Vec2, Vec3, and Vec4. Functions like min, max, clamp, and mix support both scalar and per-component operations.

Geometric Functions

| Function | Description | |----------|-------------| | length(x) | Vector magnitude | | distance(p0, p1) | Distance between points | | dot(x, y) | Dot product | | cross(x, y) | Cross product (Vec3 only) | | normalize(x) | Unit vector in same direction | | faceforward(N, I, Nref) | Orient normal toward viewer | | reflect(I, N) | Reflection direction | | refract(I, N, eta) | Refraction direction |

Matrix Functions

| Function | Description | |----------|-------------| | matrixCompMult(x, y) | Component-wise multiplication (not matrix multiply) | | transpose(m) | Matrix transpose | | determinant(m) | Matrix determinant | | inverse(m) | Matrix inverse (Mat2 only) |

Fragment-Only Functions

These functions are only available in fragment shaders:

| Function | Description | |----------|-------------| | dFdx(p) | Partial derivative with respect to window x | | dFdy(p) | Partial derivative with respect to window y | | fwidth(p) | abs(dFdx(p)) + abs(dFdy(p)) | | discard() | Discard current fragment |

Constructor Functions

Vector Constructors

// Vec2
vec2(x, y)          // From components
vec2(v)             // Broadcast scalar to all components
vec2(v)             // Take first 2 components

// Vec3
vec3(x, y, z)       // From components
vec3(v)             // Broadcast scalar
vec3(xy, z)         // From Vec2 + scalar
vec3(x, yz)         // From scalar + Vec2
vec3(v)             // Take first 3 components

// Vec4
vec4(x, y, z, w)    // From components
vec4(v)             // Broadcast scalar
vec4(xy, z, w)      // From Vec2 + scalars
vec4(xy, zw)        // From two Vec2
vec4(xyz, w)        // From Vec3 + scalar
vec4(x, yzw)        // From scalar + Vec3

Matrix Constructors

// Mat2
mat2(v)                         // Diagonal matrix
mat2(col0, col1)