API reference

Every public class, method, and event in @codexo/exojs. Generated from source.

classShader

@codexo/exojs / rendering / stable

Immutable shader source pair shared by Material instances. `Shader` owns only the GLSL/WGSL text and its stable identity; it carries no uniform/texture state (that lives on the Material). One `Shader` can back many materials, and renderers key their compiled program/pipeline caches on the source identity exposed via id. # Vertex layout The vertex layout for the mesh path is fixed and shared with the default mesh material, so custom vertex shaders MUST pin the standard attribute locations: ## GLSL (location-qualified) ```glsl layout(location = 0) in vec2 a_position; layout(location = 1) in vec2 a_texcoord; layout(location = 2) in vec4 a_color; ``` ## WGSL (location-qualified) ```wgsl struct VertexInput { @location(0) position: vec2<f32>, @location(1) texcoord: vec2<f32>, @location(2) color: vec4<f32>, }; ``` # Auto-bound uniforms Renderers auto-bind these when the source declares them. Declared but unused is fine; absent is fine too. Both backends carry the same logical uniforms, only the binding scheme differs. ## GLSL ```glsl uniform mat3 u_projection; // active view's projection uniform mat3 u_translation; // drawable's global transform uniform vec4 u_tint; // tint as RGBA in 0..1 uniform sampler2D u_texture; // bound to texture slot 0 ``` ## WGSL ```wgsl struct MeshUniforms { projection: mat3x3<f32>, translation: mat3x3<f32>, tint: vec4<f32>, }; @group(0) @binding(0) var<uniform> u_mesh: MeshUniforms; @group(1) @binding(0) var u_texture: texture_2d<f32>; @group(1) @binding(1) var u_sampler: sampler; ``` # Declared user uniforms Supplying `uniforms` (one block) or `uniformBlocks` (several named ones) makes this source the single source of truth for their names, types, layout and defaults. The engine computes one canonical `std140` layout and prepends the matching GLSL block and WGSL struct to the stages, so neither body declares them; both read through the instance name - `uniforms` for the implicit block, the record key for a named one. ```ts const shader = new Shader({ uniforms: { u_time: UniformType.Float, u_tint: UniformType.Vec4 }, glsl: { vertex, fragment }, wgsl, }); ``` Materials and filters built on such a source expose typed accessors instead of the value record, and textures are declared in `textures` rather than among the uniforms. Blocks take bindings `0..n-1` of the consumer's user bind group in declaration order, with texture bindings following after them. # Raw user uniforms Without a declaration the source keeps full control and correspondingly weaker guarantees. Anything in Material.uniforms is set after the auto-binds, and `Texture`/`RenderTexture` values claim slots 1..N (slot 0 belongs to the drawable's own texture). ## WGSL user-uniform contract User uniforms live in `@group(2)`: - `@group(2) @binding(0) var<uniform> u_user: <UserUniformsStruct>;` for the packed scalar/vector/matrix uniforms, each in its own 16-byte slot in declaration order. - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform, in declaration order, alongside its sampler at `@binding(N+1)`.

props

methods

events

Import

import { Shader } from '@codexo/exojs'

Immutable shader source pair shared by Material instances.

`Shader` owns only the GLSL/WGSL text and its stable identity; it carries no uniform/texture state (that lives on the Material). One `Shader` can back many materials, and renderers key their compiled program/pipeline caches on the source identity exposed via id.

# Vertex layout

The vertex layout for the mesh path is fixed and shared with the default mesh material, so custom vertex shaders MUST pin the standard attribute locations:

## GLSL (location-qualified)

```glsl layout(location = 0) in vec2 a_position; layout(location = 1) in vec2 a_texcoord; layout(location = 2) in vec4 a_color; ```

## WGSL (location-qualified)

```wgsl struct VertexInput { @location(0) position: vec2<f32>, @location(1) texcoord: vec2<f32>, @location(2) color: vec4<f32>, }; ```

# Auto-bound uniforms

Renderers auto-bind these when the source declares them. Declared but unused is fine; absent is fine too. Both backends carry the same logical uniforms, only the binding scheme differs.

## GLSL

```glsl uniform mat3 u_projection; // active view's projection uniform mat3 u_translation; // drawable's global transform uniform vec4 u_tint; // tint as RGBA in 0..1 uniform sampler2D u_texture; // bound to texture slot 0 ```

## WGSL

```wgsl struct MeshUniforms { projection: mat3x3<f32>, translation: mat3x3<f32>, tint: vec4<f32>, };

@group(0) @binding(0) var<uniform> u_mesh: MeshUniforms;

@group(1) @binding(0) var u_texture: texture_2d<f32>; @group(1) @binding(1) var u_sampler: sampler; ```

# Declared user uniforms

Supplying `uniforms` (one block) or `uniformBlocks` (several named ones) makes this source the single source of truth for their names, types, layout and defaults. The engine computes one canonical `std140` layout and prepends the matching GLSL block and WGSL struct to the stages, so neither body declares them; both read through the instance name - `uniforms` for the implicit block, the record key for a named one.

```ts const shader = new Shader({ uniforms: { u_time: UniformType.Float, u_tint: UniformType.Vec4 }, glsl: { vertex, fragment }, wgsl, }); ```

Materials and filters built on such a source expose typed accessors instead of the value record, and textures are declared in `textures` rather than among the uniforms. Blocks take bindings `0..n-1` of the consumer's user bind group in declaration order, with texture bindings following after them.

# Raw user uniforms

Without a declaration the source keeps full control and correspondingly weaker guarantees. Anything in Material.uniforms is set after the auto-binds, and `Texture`/`RenderTexture` values claim slots 1..N (slot 0 belongs to the drawable's own texture).

## WGSL user-uniform contract

User uniforms live in `@group(2)`:

- `@group(2) @binding(0) var<uniform> u_user: <UserUniformsStruct>;` for the packed scalar/vector/matrix uniforms, each in its own 16-byte slot in declaration order. - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform, in declaration order, alongside its sampler at `@binding(N+1)`.

Constructors1

new(options: ShaderOptionsConstruction options for Shader. At least one language must be supplied. Provide `glsl` for WebGL2, `wgsl` for WebGPU, or both for backend-portable materials.…<F, B>): Shader<F, B>

Methods2

detectUniformDrift(): { onlyInGlsl: readonly string[]; onlyInWgsl: readonly string[] }

Compare declared uniform names between the GLSL and WGSL sources. Returns lists of names declared in only one language. Use in CI to catch drift when both languages should expose the same logical uniforms. When only one language is provided, returns empty arrays. Auto-bound uniforms (u_projection, u_translation, u_tint, u_texture) are excluded from the comparison since the GLSL source declares them at the top-level uniform scope while the WGSL source receives them via the @group(0) mesh-uniforms struct and the @group(1) texture binding.

getDeclaredUniforms(): { glsl: Record<string, string>; wgsl: Record<string, string> }

Reflect declared uniforms from each language's source. Returns a per- language map of uniform-name → declared type, parsed from the shader sources via lightweight regex (not a full GLSL/WGSL grammar). Texture uniforms (sampler2D/texture_2d) are included; sampler bindings are not (they pair with textures by binding index). Reflection is best-effort and intended for CI drift-checks and editor tooling, not for runtime uniform binding decisions. The renderers do NOT consult this map; they bind uniforms by name from Material.uniforms and let the underlying API resolve declared- but-unused entries.

Properties7

glsl: null | { fragment: string; vertex: null | string }

GLSL sources for the WebGL2 backend, or null if not provided. vertex is null when the author left the vertex stage to the consumer.

uniformBlocks: B

The named block declarations, as supplied.

uniforms: F

The implicit block's field declaration, as supplied.

uniformSchema: UniformSchemaLayoutA shader source's whole uniform declaration. `implicit` distinguishes the single engine-named block declared through `uniforms` from explicitly named `uniformB… | null

The canonical layout of the declared uniform blocks, or null for a source that manages its own uniform declarations.

wgsl: null | string

WGSL source for the WebGPU backend, or null if not provided.

fragmentOutputs: FragmentOutputCountsPer-language count of the color attachments a fragment stage declares an output for, as reflected from the shader source. `null` means the count could not be e…

How many color attachments each language's fragment stage declares an output for, reflected from the source on first read and cached for the shader's lifetime. Drawing into a multi-attachment render target needs one declared output per attachment, and the engine refuses a draw whose count is known to fall short. Reflection uses the same lightweight regex approach as getDeclaredUniforms rather than a full grammar, so a source it cannot resolve reports null and is let through rather than refused.

id: number

Stable per-instance identity. Identical id ⇒ same compiled program/ pipeline can be reused. Monotonic across the session; never reused.

Source

src/rendering/shader/Shader.ts