shader
Shader compilation — turning authored WGSL into registered GPU programs, and the reusable modules those programs include.
require("@builtin::modules.api.engine.shader") -- shader (also available as global 'shader')
The shader namespace: 12 functions.
globals/shader/compile
shader.compile(keys: string | { string }, opts: { [string]: any }) -> boolean
Compile a zero-scaffolding SURFACE shader: the author wrote only
vertex() / fragment() and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.
Parameters
keysstring | { string }— The shader key (guid@checksumof the version compiled), alone or as a one-element array.opts{ [string]: any }—{ source, domain?, properties?, replaces? }— the author's WGSL, its@domain, the declared property schema, and the key this shader compiled under before its source changed, whose materials move to the new key.
Returns boolean — True when the compile was queued.
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
globals/shader/forget
shader.forget(keys: string | { string }) -> boolean
Drop what a removed shader registered under its key: its programs and their variants, the composed WGSL, the compile status and the diagnostic. The pipelines built from those programs are evicted and the materials drawing through them re-prepare.
Parameters
keysstring | { string }— The shader key (guid@checksum), alone or in an array.
Returns boolean — True when the removal was queued.
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
globals/shader/registerModule
shader.registerModule(keys: string | { string }, source: string) -> boolean
Register a block of WGSL other shaders include. Every key names the same source, so a shader includes it by whichever name it holds — its guid, its identity, or an alias. Registering again replaces it, and the shaders that include it recompile.
Parameters
keysstring | { string }— One key, or the array of keys this module answers to.sourcestring— The module's WGSL.
Returns boolean — True when the registration was queued.
shader.registerModule({ ref.guid, ref.identity }, wgsl)
globals/shader/status
shader.status(name: string) -> (string, string?)
A shader's latest compile outcome, without reading the engine log:
"compiled", "failed" (with the compiler error second), or "pending".
Compilation is async, so a "pending" straight after a write means ask
again next frame.
Parameters
namestring— The key it compiled under (guid@checksum), or a reference to a shader asset (identity, path, guid), which reaches the key of the version that reference resolves to now.
Returns (string, string?) — Status, and the compiler error when it failed.
local status, err = shader.status("myShader")
modules/shader/compile
compile(keys: string | { string }, opts: { [string]: any }): boolean
Compile a zero-scaffolding SURFACE shader: the author wrote only
vertex() / fragment() and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.
Parameters
keysstring | { string }— The shader key (guid@checksumof the version compiled), alone or as a one-element array.opts{ [string]: any }—{ source, domain?, properties?, replaces? }— the author's WGSL, its@domain, the declared property schema, and the key this shader compiled under before its source changed, whose materials move to the new key.
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
modules/shader/forget
forget(keys: string | { string }): boolean
Drop what a removed shader registered under its key: its programs and their variants, the composed WGSL, the compile status and the diagnostic. The pipelines built from those programs are evicted and the materials drawing through them re-prepare.
Parameters
keysstring | { string }— The shader key (guid@checksum), alone or in an array.
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
modules/shader/registerModule
registerModule(keys: string | { string }, source: string): boolean
Register a block of WGSL other shaders include. Every key names the same source, so a shader includes it by whichever name it holds — its guid, its identity, or an alias. Registering again replaces it, and the shaders that include it recompile.
Parameters
keysstring | { string }— One key, or the array of keys this module answers to.sourcestring— The module's WGSL.
shader.registerModule({ ref.guid, ref.identity }, wgsl)
modules/shader/status
status(name: string): (string, string?)
A shader's latest compile outcome, without reading the engine log:
"compiled", "failed" (with the compiler error second), or "pending".
Compilation is async, so a "pending" straight after a write means ask
again next frame.
Parameters
namestring— The key it compiled under (guid@checksum), or a reference to a shader asset (identity, path, guid), which reaches the key of the version that reference resolves to now.
local status, err = shader.status("myShader")
typed/builtin//modules/api/engine/shader/shader/compile
shader.compile(keys: string | { string }, opts: { [string]: any }) -> boolean
Compile a zero-scaffolding SURFACE shader: the author wrote only
vertex() / fragment() and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.
Parameters
keysstring | { string }— The shader key (guid@checksumof the version compiled), alone or as a one-element array.opts{ [string]: any }—{ source, domain?, properties?, replaces? }— the author's WGSL, its@domain, the declared property schema, and the key this shader compiled under before its source changed, whose materials move to the new key.
Returns boolean — True when the compile was queued.
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
typed/builtin//modules/api/engine/shader/shader/forget
shader.forget(keys: string | { string }) -> boolean
Drop what a removed shader registered under its key: its programs and their variants, the composed WGSL, the compile status and the diagnostic. The pipelines built from those programs are evicted and the materials drawing through them re-prepare.
Parameters
keysstring | { string }— The shader key (guid@checksum), alone or in an array.
Returns boolean — True when the removal was queued.
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
typed/builtin//modules/api/engine/shader/shader/registerModule
shader.registerModule(keys: string | { string }, source: string) -> boolean
Register a block of WGSL other shaders include. Every key names the same source, so a shader includes it by whichever name it holds — its guid, its identity, or an alias. Registering again replaces it, and the shaders that include it recompile.
Parameters
keysstring | { string }— One key, or the array of keys this module answers to.sourcestring— The module's WGSL.
Returns boolean — True when the registration was queued.
shader.registerModule({ ref.guid, ref.identity }, wgsl)
typed/builtin//modules/api/engine/shader/shader/status
shader.status(name: string) -> (string, string?)
A shader's latest compile outcome, without reading the engine log:
"compiled", "failed" (with the compiler error second), or "pending".
Compilation is async, so a "pending" straight after a write means ask
again next frame.
Parameters
namestring— The key it compiled under (guid@checksum), or a reference to a shader asset (identity, path, guid), which reaches the key of the version that reference resolves to now.
Returns (string, string?) — Status, and the compiler error when it failed.
local status, err = shader.status("myShader")