Documentation

PNGine is declarative WebGPU in S-expressions. You describe buffers, textures, pipelines and passes as data, with the shaders themselves in plain WGSL (WebGPU’s shading language); the compiler checks that description against a WebGPU schema and turns it into compact bytecode, which a small runtime plays anywhere WebGPU runs. The bytecode is only data, so it travels well: on its own, inside a standalone HTML file, or, for fun, tucked into a PNG that carries the image, the program and the runtime that plays it in one file.

The S-expression language is SJON, and PNGine is a SJON host: SJON supplies the syntax, the reader and the validator; PNGine supplies the WebGPU schema and the compiler behind it.

Quick Start

# Install via npm (3.0.0 or later: these pages are written for it)
npm install pngine@^3

# Compile shader to PNG
npx pngine shader.sjon -o shader.png

import { pngine, play } from 'pngine';

const p = await pngine('shader.png', {
  canvas: document.getElementById('canvas')
});
play(p);

Guides

Getting Started - Installation, first program, browser setup
SJON Syntax - Quick language overview
Shipping a Player - Runtime tiers and payload formats
Limits & Roadmap - Hard caps and deferred features
SJON language docs - The host language PNGine builds on

SJON Reference

Complete reference for every form (validated against schema/pngine.sjon):

Shaders

(shader-module …) - Named WGSL module

Resources

(buffer …) - GPU buffer (vertex, uniform, storage, index)
(texture …) - GPU texture
(texture-view …) - Explicit view (1d/3d/array/cube sampling)
(sampler …) - Texture sampler
(image-bitmap …) - Decoded image → texture
(data …) - Embedded data arrays and shape generators
(query-set …) - Occlusion and timestamp queries

Pipelines

(render-pipeline …) - Render pipeline
(compute-pipeline …) - Compute pipeline
(bind-group …) - Resource bindings
(bind-group-layout …) - Explicit bind group layout
(pipeline-layout …) - Explicit pipeline layout

Execution

(render-pass …) - Render pass with draw commands
(compute-pass …) - Compute pass with dispatch
(render-bundle …) - Pre-recorded, replayable draws
(queue …) - Buffer writes, copies, query resolves
(frame …) - Frame execution order

Sugar & advanced

(init …) - One-shot compute init
(pass-graph …) - Fullscreen shader-art sugar
(wasm-call …) - Nested WASM module calls
(define …) - Compile-time constants

Device configuration

(limits …) - Raise WebGPU device limits
(canvas …) - Canvas alpha mode

Concepts

References - Bare identifier resolution
Expressions - Compile-time arithmetic

API Reference

CLI Reference - Command-line interface
JavaScript API - Browser runtime API
WASM API - The embedded runtime’s ABI and the in-browser compiler
Bytecode Format - Specification of PNGB, the compiled bytecode

Writing SJON with an AI agent

Models have seen little or no SJON, so an agent writing it cold tends to invent forms. Give it llms.txt instead: a compact reference with complete programs the engine’s test suite validates, and the loop to run (npx pngine validate file.sjon --json, fix, repeat). The same file is served from the engine repository at https://raw.githubusercontent.com/HugoDaniel/pngine/main/docs/llms.txt.

Examples

Worked programs live in the engine repo’s examples/ directory: from simple_triangle.sjon through indexed meshes (teapot.sjon, dragon.sjon), compute simulation with ping-pong buffers (boids.sjon), multi-pass feedback (pass_bloom.sjon) and WASM data buffers (test_data_pass.sjon). Each doubles as a compiler test fixture, so they stay current by construction.

Architecture

Source (.sjon)
    |
    v
+------------------+
|   SJON Host      |  parse -> validate (schema) -> lower -> emit
+--------+---------+
         |
         v
+------------------+
|  PNGB Bytecode   |  Header + Opcodes + Strings + Data
+--------+---------+
         |
    +----+----+
    v         v
+-------+  +--------+
|  PNG  |  |  WASM  |
| Embed |  | Runtime|
+-------+  +----+---+
               v
         +----------+
         |  WebGPU  |
         +----------+

File Formats

Extension	Description
`.sjon`	SJON source file
`.pngb`	Compiled bytecode
`.png`	PNG with the bytecode embedded in a `pNGb` chunk (an ancillary chunk that image tools carry along untouched)

Measured Sizes

From the engine’s example corpus (2026-08-18):

Example	Bytecode	Self-contained PNG
`simple_triangle`	631 B	4.6 KB
`rotating_cube`	3.8 KB	5.9 KB
`boids` (compute)	4.8 KB	6.2 KB