Shader

A handle to a compiled graphics pipeline (a vertex + fragment program plus its pipeline state).
Shaders are looked up by name and assigned to a Material (material:SetShader(...));
the geometry (3D) variant can also be created at runtime from named SPIR-V stages via CreateGeo.

Static calls use the type table (Shader.Get(...)); instance methods use colon syntax on a handle
(shader:RenderQueue()). The Lua surface is read-only — there are no property setters and no
Destroy.

Types

Shader — an opaque handle (userdata) to a compiled pipeline. A handle may be null or
stale. The instance queries on a dead handle log a warning (NotFound) and return nil; they
never raise on a live-but-empty result. Passing a non-Shader userdata (or wrong argument types)
to a method raises a Lua type error. tostring(shader) yields Shader{name}, or Shader{NULL} if
the handle is dead.

Creation & Destruction

Shader.CreateGeo( string name, string vertName, string fragName, integer renderQueue, integer textureCount ) : Shader
Creates a geometry (3D) shader named name from the named vertex and fragment SPIR-V stages, with
the given render-queue order and texture-binding count. Allocates a GPU pipeline through the render
backend, so it is only meaningful with a live backend. Returns the new handle, or nil (logs
InvalidArgument) on failure. renderQueue and textureCount are truncated to u16 (values
≥ 65536 wrap silently).

Shader.Get( string name ) : Shader
Looks up a shader by its unique name. Returns nil if none exists (no warning — a miss is a valid result).

Shader.Exists( Shader shader ) : boolean
Returns true if the handle refers to a live shader. Safe on null/stale/foreign handles (returns
false) — the one call here that never warns or raises.

Shaders have no instance Destroy from Lua.

Functions

Read-only queries. Each logs NotFound and returns nil on a null/stale handle.

shader:ID( ) : string
The shader’s unique name.

shader:RenderQueue( ) : integer
The render-queue order value (a u16; controls draw sorting relative to other shaders).

shader:DepthWrite( ) : boolean
Whether the pipeline writes to the depth buffer.

shader:AlphaToCoverage( ) : boolean
Whether alpha-to-coverage is enabled on the pipeline.

Example

-- Assign a looked-up shader to a material, and inspect its pipeline state.
-- (Adapted from data/scripts/session_setup.lua.)
local mat = Material.Create("lit_material")
local geo = Shader.Get("geo_lit")
mat:SetShader(geo)
mat:SetColorLinear(0, Vector4.new(1, 1, 1, 1))

if Shader.Exists(geo) then
    -- geo:ID(), geo:RenderQueue(), geo:DepthWrite(), geo:AlphaToCoverage()
    print(geo:ID(), "queue=" .. geo:RenderQueue(), "depthWrite=" .. tostring(geo:DepthWrite()))
end