Crate glitcher_api 

Glitcher API

WebAssembly Interface Types for Glitcher Engine render node plugins.

Overview

This crate provides the WIT-generated Rust types that define the contract between the Glitcher Engine host and WASM plugins. Plugins act as “Definition Providers” - they supply node metadata and WGSL shader source code.

Architecture

WASM Plugin (Guest)          Glitcher Engine (Host)
┌─────────────────┐          ┌─────────────────────┐
│ get-manifest()  │────WIT──>│ Load metadata       │
│ get-shader()    │────WIT──>│ Compile WGSL        │
└─────────────────┘          │ Execute on GPU      │
                             └─────────────────────┘

Usage

For Plugin Authors (Guest)

use glitcher_api::*;

wit_bindgen::generate!({
    world: "plugin",
    exports: {
        "glitcher:engine/render-node": MyNode,
    }
});

struct MyNode;

impl Guest for MyNode {
    fn get_manifest() -> NodeManifest {
        NodeManifest {
            api_version: 1,
            display_name: "My Effect".into(),
            model: ExecutionModel::FragmentShader,
            parameters: vec![
                ShaderParam {
                    name: "strength".into(),
                    data_type: ParamType::F32,
                    widget: WidgetConfig::Slider(SliderConfig {
                        min: 0.0,
                        max: 1.0,
                        step: 0.01,
                    }),
                }
            ],
            textures: vec![
                TexturePort {
                    name: "input".into(),
                    binding_slot: 0,
                    writable: false,
                }
            ],
            output_resolution_scale: 1.0,
        }
    }

    fn get_shader_source() -> String {
        r#"
        struct Params {
            strength: f32,
        }

        @group(1) @binding(0) var<uniform> params: Params;
        @group(2) @binding(0) var input_texture: texture_2d<f32>;

        @fragment
        fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
            // Your shader code here
            return textureSample(input_texture, sampler, uv);
        }
        "#.into()
    }
}

For Host Implementation

use glitcher_api::*;
use wasmtime::*;

// Load and instantiate WASM plugin
let module = Module::from_file(&engine, "plugin.wasm")?;
let instance = linker.instantiate(&mut store, &module)?;

// Call WIT functions
let get_manifest = instance
    .get_typed_func::<(), NodeManifest>(&mut store, "get-manifest")?;
let manifest = get_manifest.call(&mut store, ())?;

// Validate and use manifest
assert_eq!(manifest.api_version, 1);

Type System

All types are strongly typed through WIT, eliminating string-based parsing:

• ParamType: WGSL-compatible parameter types (f32, vec3, mat4, etc.)
• WidgetConfig: UI widget configurations (slider, color-picker, etc.)
• ExecutionModel: Fragment shader or compute shader
• NodeManifest: Complete node definition

Memory Layout

The host calculates GPU buffer layouts using std140 rules based on ParamType. Plugins don’t need to worry about alignment or padding.

Binding Conventions

Shaders must follow these binding group conventions:

• Group 0: System globals (time, resolution, mouse) - Host-managed
• Group 1: Node parameters - Single uniform buffer at binding 0
• Group 2: Textures - Bindings match [TexturePort::binding_slot]

API Versioning

The NodeManifest::api_version field ensures compatibility:

• Current version: 1
• Host rejects plugins with mismatched versions
• Breaking changes increment the version number

Re-exports

pub use exports::glitcher::engine::actions::ActionConfig;

pub use exports::glitcher::engine::actions::ActionDef;

pub use exports::glitcher::engine::actions::ActionError;

pub use exports::glitcher::engine::actions::BeatInfo;

pub use exports::glitcher::engine::actions::ParamComputeConfig;

pub use exports::glitcher::engine::actions::ParamRangeError;

pub use exports::glitcher::engine::actions::ParamRef;

pub use exports::glitcher::engine::actions::ParamUpdate;

pub use exports::glitcher::engine::ports::ControlOutput;

pub use exports::glitcher::engine::ports::NodePort;

pub use exports::glitcher::engine::ports::PortConfig;

pub use exports::glitcher::engine::ports::TextureStorageConfig;

pub use exports::glitcher::engine::render_node::CustomCategory;

pub use exports::glitcher::engine::render_node::CustomOutputHint;

pub use exports::glitcher::engine::render_node::EmbeddedTexture;

pub use exports::glitcher::engine::render_node::Guest;

pub use exports::glitcher::engine::render_node::NodeCategory;

pub use exports::glitcher::engine::render_node::NodeManifest;

pub use exports::glitcher::engine::render_node::OutputHint;

pub use exports::glitcher::engine::types::ExecutionModel;

pub use exports::glitcher::engine::types::ParamType;

pub use exports::glitcher::engine::types::ParamValue;

pub use exports::glitcher::engine::types::StorageTextureFormat;

pub use exports::glitcher::engine::types::WorkgroupSize;

pub use exports::glitcher::engine::widgets::ButtonGroupConfig;

pub use exports::glitcher::engine::widgets::ControlPreviewConfig;

pub use exports::glitcher::engine::widgets::CustomWidget;

pub use exports::glitcher::engine::widgets::DropdownConfig;

pub use exports::glitcher::engine::widgets::ShaderParam;

pub use exports::glitcher::engine::widgets::SliderConfig;

pub use exports::glitcher::engine::widgets::WidgetConfig;

Modules

actions

Standard action implementations Standard Action Implementations

builtin

Builtin plugin provider interface Builtin Plugin Provider Interface

exports

hooks

Hook system for action execution events Action System Hook Interface

registry

Action registry for name→ID mapping and dispatch Action Registry - Maps action IDs to handlers

Structs

AudioReactConfig

Audio-reactive modulation configuration

AudioReactiveParams

Audio-reactive parameters from audio analysis

DecodedTexture

Decoded embedded texture data (ready for GPU upload)

ExternalTriggerState

Per-node external trigger state

LoadedPlugin

A loaded WASM plugin with extracted metadata

ParamModulation

Modulation settings for a single parameter

SystemGlobals

System globals shared across all nodes

Enums

AudioBand

Audio frequency band for audio-reactive modulation

BeatDivision

Beat division for modulation timing

ModWaveform

Modulation waveform types for LFO

Constants

CURRENT_API_VERSION

Current API version

Traits

PortConfigExt

Extension trait for PortConfig helpers

Functions

button_group

Helper to create a button group widget config

compute_shader

Helper to create a compute shader execution model

control_output_port

Helper to create a control output port

dropdown

Helper to create a dropdown widget config

fragment_shader

Helper to create a fragment shader execution model

slider

Helper to create a slider widget config

texture_input

Helper to create a texture input port

texture_output

Helper to create a texture output port

texture_storage

Helper to create a texture storage port (read/write for compute shaders)

texture_storage_input

Helper to create a texture storage input port (read/write for compute shaders, accepts connections)