@carbonenginejs/format-webgl

CarbonEngineJS-facing reader/builder for .cewg WebGL shader packages, plus a pure-JavaScript DXBC (Direct3D compiled shader bytecode) to GLSL ES 3.00 emitter for the WebGL2 vertex/pixel/map-style-compute stages ccpwgl targets.

No native tooling, no build step; it runs in Node and the browser. This package has two independent capabilities:

1. CEWG package read/write. CEWG is a CarbonEngineJS-invented container format — a flat sequence of four-byte-tagged chunks (INFO/META/GLSL/ ...), not a Microsoft or CCP one. CEWG is also the four-byte binary package magic.
2. DXBC -> GLSL ES 3.00 emission, translating one DXBC vertex, pixel, or "map-style" compute stage (thread-per-fragment; real compute features — shared memory, barriers, atomics, raw/structured/typed UAV reads — are rejected, see docs/) into GLSL ES 3.00 source. Depends on @carbonenginejs/format-dxbc for DXBC container/program/instruction decoding; this package adds no DXBC-parsing code of its own.

CarbonEngine and Fenris Creations (CCP Games) are named in this package because the WebGL profile targets Carbon/Trinity shader conventions and ccpwgl runtime needs. CEWG itself is a CarbonEngineJS package format. This package contains no CarbonEngine or Fenris Creations (CCP Games) source code unless NOTICE explicitly says otherwise, and it is not affiliated with or endorsed by CCP Games.

Public API

The package root exports one public class: CjsFormatWebgl.

import CjsFormatWebgl from "@carbonenginejs/format-webgl";

// One-shot statics (camelCase by convention)
CjsFormatWebgl.isCewg(bytes);                          // cheap magic sniff
CjsFormatWebgl.inspect(bytes);                      // version + chunk + shader/stage-count summary
CjsFormatWebgl.read(bytes);                         // documented plain JSON package shape
CjsFormatWebgl.read(bytes, { emit: "raw" });        // internal CewgPackage instance (unstable)
CjsFormatWebgl.build([                              // assemble package bytes from chunk payloads
    [ "INFO", { format: "CEWG", formatVersion: 1 } ],
    [ "META", { effectName: "quadv5" } ],
    [ "GLSL", { format: "CEWG_GLSL_SET", formatVersion: 1, shaders: [ /* ... */ ] } ]
]);
CjsFormatWebgl.emitGlsl(dxbcBytes, { source: "Main.pass0.vertex" });

// Reusable profile
const reader = new CjsFormatWebgl({ emit: "json", source: "myeffect.cewg" });
const result = reader.Read(bytes);

Named import is also available:

import { CjsFormatWebgl } from "@carbonenginejs/format-webgl";

The JSON graph (emit: "json", the default, for Read/read)

The JSON format value and the binary package magic are both CEWG.

Root
├─ format ("CEWG"), version, sourcePath
├─ chunks: { tag, size, offset }[]     // every chunk in the package, in file order
├─ info: object | null                 // parsed INFO chunk (translator/package summary)
├─ metadata: object | null             // parsed META chunk (caller-provided Carbon metadata)
├─ glsl: object | string | null        // parsed GLSL chunk JSON (whole-effect stage sets),
│                                      // or raw GLSL text for single-stage packages, or null
└─ shaders: object[]                   // glsl.shaders when present, else []

emit: "raw"

Returns the internal CewgPackage instance directly — unstable, not schema-guaranteed. Exposes pkg.GetChunk(tag), pkg.GetText(tag), pkg.GetJson(tag), and the info/metadata/glsl/glslJson/dxbc getters. Prefer the JSON shape above for anything persisted or handed to another package.

Inspect(bytes) / inspect(bytes)

A cheaper alternative to a full Read: package version, every chunk's tag/size/offset, and the GLSL chunk's shader/stage counts, without building the full JSON shape.

Build(chunks) / build(chunks)

Wraps the CEWG builder: assembles package bytes from an ordered [tag, payload] list. Each payload may be a string (encoded as UTF-8), a plain object (JSON-encoded), or raw bytes (Uint8Array/ArrayBuffer/typed array view) — passed straight through to the same builder used by this project's packaging tooling.

EmitGlsl(dxbcBytes, options) / emitGlsl(dxbcBytes, options)

Translates one DXBC stage. options is a flat bag combining the emitter's ccpwgl-profile constructor bits with its per-call emit options — every key is optional and defaults are preserved exactly:

| Option | Default | Meaning | |---|---|---| | constantBufferStyle | "array" | "array" emits uniform vec4 cbN[] (ccpwgl's uniform4fv path); "std140" emits layout(std140) uniform blocks. | | pixelConstantBufferRemap | { 0: 7 } | Pixel-stage constant-buffer slot renames (ccpwgl keeps PS effect constants at cb7). | | samplerName(register, stageName) | vs${register} (vertex) / s${register} (pixel) | Texture uniform naming per register and stage. | | vertexStructuredCapacity | 69 | Element capacity for vertex-stage structured-buffer UBOs (bones; Carbon's max is 69 joints). | | dataTextureWidth | 2048 | Row width for buffer/structured-resource data textures. | | pairVaryings | undefined | Register list the paired pixel stage reads; any vertex output missing from this shader is declared and zero-filled. | | source | "memory" | Name used in thrown error details. |

Rejects non-vertex/pixel/compute DXBC stages with "Only vertex, pixel, and compute stages target WebGL2", and compute stages that need real compute-pipeline features (shared memory, barriers, atomics, raw/structured/typed UAV reads) with a message containing "not supported" (see docs/decl-io.md, docs/texture-sample.md, docs/memory-structured.md for the full per-opcode lowering rules — mixed GLSL-side choices only; DXBC-side semantics live in @carbonenginejs/format-dxbc's own docs).

Reader Rules

• Instance methods are PascalCase to avoid collisions with CarbonClass data.
• Static one-shot methods are camelCase and live on CjsFormatWebgl.

Ported files

src/core/cewg/CewgPackage.js, CewgPackageBuilder.js, and src/core/glsl/DxbcGlslEmitter.js, DxbcGlslOperandFormatter.js, DxbcGlslHelpers.js are ported from this project's own prior-work repository, hlslreader (src/carbon/webgl/*.js, src/dxbc/glsl/*.js), with import paths and the emitter's DXBC-parsing prelude rewired onto @carbonenginejs/format-dxbc's public format (CjsFormatDxbc.read(bytes, { emit: "raw" })) instead of this package's own container/program/decoder classes, and error class renamed to this package's own CjsWebglReadError. Thrown messages are unchanged. See NOTICE for provenance.

Tests

npm test

Baseline tests are fully self-contained (synthetic DXBC bytes and synthetic CEWG chunk payloads assembled in-test) — no game assets, network access, or fixtures required. An optional corpus sweep emits GLSL for every vertex/pixel DXBC payload found under the directory supplied by WEBGL_CORPUS_DIR (raw magic scan, same approach as @carbonenginejs/format-dxbc's corpus test), and counts map-style compute successes/kill-list rejections without failing on them:

WEBGL_CORPUS_DIR=path/to/effect.dx11 npm test

License

MIT (see LICENSE and NOTICE).