Astra Engine

Appearance

Getting Started ​

Installation ​

Build AXSLC from source:

bash
# Clone the repository
git clone https://github.com/LuizPedroSousa/astra
cd axslc

# Build with CMake
mkdir build && cd build
cmake ..
make

# Install (optional)
sudo make install

Your First Shader ​

Create a file shader.axsl:

axsl
@version 450;

@stage vertex {
    @location(0) in vec3 a_pos;

    @binding(0) uniform mat4 u_mvp;

    void main() {
        gl_Position = u_mvp * vec4(a_pos, 1.0);
    }
}

@stage fragment {
    out vec4 o_color;

    void main() {
        o_color = vec4(1.0, 0.0, 0.0, 1.0);
    }
}

Compile the Shader ​

bash
axslc shader.axsl

This generates GLSL output files with the default prefix out:

  • out.vert.glsl - vertex shader (GLSL 4.5 core)
  • out.frag.glsl - fragment shader (GLSL 4.5 core)

Custom Output Prefix ​

bash
axslc -o build/shaders/basic shader.axsl

or

bash
axslc --output build/shaders/basic shader.axsl

Generates:

  • build/shaders/basic.vert.glsl
  • build/shaders/basic.frag.glsl

Additional CLI Options ​

bash
axslc [options] <input.axsl>

Options:

  • -o, --output <prefix> - Output file prefix (default: out)
  • -I, --include-path <path> - Override base directory for includes
  • -v, --verbose - Print compilation status
  • -h, --help - Print usage
  • --version - Print version

Output naming convention:

  • .vert.glsl - vertex stage
  • .frag.glsl - fragment stage
  • .geom.glsl - geometry stage
  • .comp.glsl - compute stage

File Structure ​

An .axsl file has the following structure:

axsl
@version <number>;
@include "path/to/file.axsl";   // zero or more

// Global declarations (structs, consts, uniforms, interfaces, functions)

@stage vertex   { ... }
@stage fragment { ... }
@stage geometry { ... }
@stage compute  { ... }

Understanding the Output ​

AXSLC generates standard GLSL 4.5 core shaders from your unified .axsl source:

Generated GLSL structure:

  1. Version header: #version 450 core
  2. Global declarations (structs, functions, constants)
  3. Global uniforms/buffers (only if used in the stage)
  4. Stage-specific items (interface blocks, stage-local uniforms, functions)

Dead code elimination: Uniforms are only included in stages that actually reference them, reducing unnecessary uniform declarations.

Compilation Pipeline ​

AXSLC processes shaders through four phases:

  1. Tokenizer - Lexical analysis, converts source text to token stream
  2. Parser - Syntax analysis, builds Abstract Syntax Tree using Pratt parsing
  3. Linker - Resolves symbols, handles @include files, tracks uniform usage per stage
  4. Emitter - Generates final GLSL code with proper layout qualifiers

Error Handling ​

If compilation fails, AXSLC provides detailed error messages with source context:

file:line:col: message
N-2 | source line
N-1 | source line
  N | source line where error occurred
    |       ^
N+1 | source line
N+2 | source line

Common errors:

  • Parse errors - syntax issues, unexpected tokens, missing braces
  • Linker errors - unresolved symbols, undefined identifiers, missing include files

The parser attempts error recovery to report multiple issues in a single compilation.

Next Steps ​