rasterShader.assetType
- README.md4.7 KB
- about.yaml652 B
- behavior.luau8.8 KB
- inspector.luau2.5 KB
- template
- type.yaml1.5 KB
This package holds more than this page lists. See all of its files in its world.
README.md
Raster shader (asset type)
A .rasterShader is a GPU program a render feature draws with: a vertex stage
that makes every vertex itself, from its @builtin(vertex_index) and
@builtin(instance_index) and whatever it pulls from the buffers it binds, and
a fragment stage that colours what those vertices cover. No mesh and no vertex
buffer stand behind it, which is what an instanced field of grass, kelp,
leaves, debris or sprites wants: one buffer of per-instance records, one draw.
It is drawn by a render feature's kind = "raster" pass (renderFeature
assetType README, "Raster passes"), with its own pipeline, depth and blend —
the shape a hand-written renderer ports into. An instanced field can also be
drawn through an engine material: the guide topics/rendering-instance-data,
section "Instanced foliage built in the vertex shader — grass, kelp, hair
cards, debris", builds it in a surface shader's vertex() from
zero_object_data(v.instance_id, lane) and v.vertex_index on a mesh drawn
with renderer.mesh.drawInstanced, and that field is lit, casts and receives
shadows, writes motion vectors and takes fog and post-processing as every
material does.
Folder shape
<name>.rasterShader/
shader.wgsl # `@vertex fn vs_main` + `@fragment fn fs_main` + helpers (required)
bindings.yaml # the binding + params schema (required)
README.md # what this shader draws (required)
.metadata # asset metadata
bindings.yaml is the schema a .computeShader declares — the same kinds,
access, element, array, format, sample and params: — and the engine
generates every @group(0) @binding(i) line from it, so shader.wgsl holds no
binding declaration of its own. The computeShader assetType README carries the
full table.
- A binding the vertex stage reads is
access: read. A writable storage buffer or storage texture is laid out for the fragment stage alone, and avs_mainreading one is refused at the compile, naming the binding. vertices(a mesh's vertices) andacceleration_structureare compute bindings; a raster shader declaring one is refused.- A
samplerstates how it samples (filter,mipmap,address/addressU/addressV/addressW,anisotropy), and one statingcompareis asampler_comparisonfortextureSampleCompareon atexture_depth— a shadow map a pass drew, bound as@depth.<guid>. - Each stage holds the device's per-stage counts: 8 storage buffers, 4 storage textures, 16 sampled textures and 16 samplers. A read binding counts in both stages.
The two entries
struct VOut { @builtin(position) clip: vec4<f32>, @location(0) uv: vec2<f32> };
@vertex fn vs_main(@builtin(vertex_index) v: u32, @builtin(instance_index) i: u32) -> VOut { ... }
@fragment fn fs_main(in: VOut) -> @location(0) vec4<f32> { ... }
fs_main returns one @location(i) colour per target the pass draws into (a
struct of them for several). A pass whose target count differs from what
fs_main writes is skipped, and the log says both numbers.
The camera
Bind @frame.camera to a read buffer and the vertex stage places its vertices
with the camera of the view being drawn — the live viewport, a capture, a
render-to-texture camera — each through its own matrix:
- { name: cam, kind: buffer, access: read, element: vec4<f32> }
let view_proj = mat4x4<f32>(cam[9], cam[10], cam[11], cam[12]);
out.clip = view_proj * vec4<f32>(world_position, 1.0);
let camera_position = cam[4].xyz;
cam[9..13) is the view-projection the scene rasterized with this render, so
a clip position it produces lands on the scene's own depth. cam[5..9) is
the previous render's view-projection and cam[13].xy the sub-pixel offset this
render's matrix carries, which a pass writing @scene.motion reads. The rest
of the buffer is in the renderFeature README (@frame.camera).
Compile errors
A compile that fails logs [rasterShader] Compile of raster shader '<folder>' (<key>) failed: <reason> with the WGSL error or what the entries
lack, and a pass drawing the shader states the same reason once, when it is
first skipped.
Compiling
A raster shader compiles when it is written and when its world loads; there is
no setup step. ref:compile() compiles it now and answers false, reason with
the WGSL error or what the entries lack; ref:state() answers "pending",
"ready" or "failed", reason. ref:getBindings() lists the declared schema
and ref:setParam(name, value) sets a params: uniform.
local leaves = asset.resolve("leaves", "rasterShader")
print(leaves:state()) -- "ready"