Log inGet started
Package

rasterShader.assetType

Newest version

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 a vs_main reading one is refused at the compile, naming the binding.
  • vertices (a mesh's vertices) and acceleration_structure are compute bindings; a raster shader declaring one is refused.
  • A sampler states how it samples (filter, mipmap, address / addressU / addressV / addressW, anisotropy), and one stating compare is a sampler_comparison for textureSampleCompare on a texture_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"