R3D Documentation

Surface shaders are a simplified shader interface for materials and decals. They abstract away the complexity of multiple render passes (opaque, transparent, shadows, etc.) by allowing you to define behavior in a single shader definition. R3D automatically handles the underlying render pipeline based on your shader code.

A surface shader requires at least one of two optional entry points:

• vertex(): Runs once per vertex. Used to modify vertex positions, colors, or pass data to the fragment stage.
• fragment(): Runs once per pixel. Used to modify surface properties like albedo, roughness, or emission.

// Example of both stages
varying float v_height;

void vertex() {
    v_height = POSITION.y;
}

void fragment() {
    ALBEDO = mix(vec3(0.0, 0.5, 0.0), vec3(1.0, 1.0, 1.0), v_height);
}

Sky shaders are used to procedurally generate skybox cubemaps. Unlike screen shaders that process a rendered frame, sky shaders render each of the six faces of a cubemap from scratch. They run once per texel of a cubemap to compute the sky color for that specific direction. They are not used during normal frame rendering but are invoked explicitly to generate or update an R3D_Cubemap.

void fragment() {
    // Simple gradient sky: blue at horizon, dark at zenith
    float t = max(EYEDIR.y, 0.0);
    COLOR = mix(vec3(0.5, 0.7, 1.0), vec3(0.1, 0.2, 0.5), t);
}

Varyings allow you to pass data from the vertex() stage to the fragment() stage. They are automatically interpolated across the triangle. You can control interpolation using qualifiers:

• smooth: Perspective-correct interpolation (default).
• flat: No interpolation (uses value from provoking vertex).
• noperspective: Linear interpolation in screen space.

flat varying int v_material_id;
noperspective varying vec2 v_screen_uv;

void vertex() {
    v_material_id = 1;
    v_screen_uv = TEXCOORD;
}

void fragment() {
    if (v_material_id == 1) {
        ALBEDO = texture(u_texture, v_screen_uv).rgb;
    }
}

r3d uses the Allman indentation style. Braces should be placed on their own line, aligned with the enclosing statement for scopes that do not require a trailing semicolon (e.g., function bodies, if, for, while, switch blocks).

When a semicolon follows the closing brace (such as in type declarations or initializers), the opening brace stays on the same line.

// Allman: function body, closing brace needs no semicolon
void DoSomething(void)
{
    DoStuff();
}

// Same-line brace: closing brace is followed by ';'
typedef struct {
    int x;
    int y;
} Vector2;

// Same-line brace: initializer, closing brace is followed by ';'
int values[] = {1, 2, 3, 4};

Vector2 origin = {
    .x = 0,
    .y = 0
};

R3D screen shaders follow a specific GLSL structure. You define optional uniform variables and must implement a void fragment() entry point. Inside the fragment stage, you can read screen data using built-in variables and helper functions, and you must write the final pixel color to the COLOR variable.

uniform float uTime;

void fragment() {
    // Use built-in variables or helper functions
    vec3 color = SampleColor(TEXCOORD);
    
    // Write to the output
    COLOR = color * sin(uTime);
}

To avoid common pitfalls and ensure readability:

• Attach the * to the type, not the variable (e.g., Type* v).
• Never declare multiple variables on a single line.
• Use 4 spaces for indentation; do not use tabs.
• Surround operators with spaces (except when omitting them for mathematical formula readability).

Type* v;    // OK
Type* a, b; // FORBIDDEN: split into separate declarations

// Spacing around operators
int result = a + b * c;

// Vertical alignment is allowed for small, related groups
int   width  = 800;
int   height = 600;
float scale  = 1.0f;

In switch statements, case and default labels must not be indented relative to the switch keyword. The statements inside each case should be indented one level from the label.

switch (value)
{
case 1:
    DoA();
    break;

case 2:
    DoB();
    break;

default:
    DoC();
    break;
}

TinyCThread is a minimalist, portable threading library for C modeled after the C11 standard. You can integrate it into your project using one of two methods:

Method 1: Manual Integration

Add tinycthread.c and tinycthread.h directly to your project source files and include the header in your code:

#include <tinycthread.h>

Method 2: CMake Integration

If your project uses CMake, you can add TinyCThread as a subdirectory. This automatically handles include directories and CTest integration. Use target_link_libraries to link the tinycthread target to your executable.

add_subdirectory(tinycthread)
target_link_libraries(your_executable_name tinycthread)