Module custom_surface 

Custom GPU surface layers: splice a user’s terrain GLSL into the library template and drive the per-slot surface buffers on the render device.

This is the code-authored terrain extension point for consumers who want procedural terrain that runs entirely on the GPU (no CPU bake pool). The user writes a small .glsl file defining terrain_height / terrain_color (and optionally terrain_normal); assemble_source wraps it in TEMPLATE — which owns the per-texel gnomonic direction mapping, the finite-difference auto-normal, and the writes into the same surface_color/height/normal buffers the built-in realize/bake shaders read when surface_enabled == 1. Godot’s RenderingDevice compiles the assembled GLSL at runtime, so no slangc and nothing new ships — it reuses Godot’s own shader compiler. The compiled pipeline runs as the celestial/chunk-surface-custom node (crate::chunk_nodes::surface_custom), between upload and realize.

Contrast with crate::surface::CpuSurfaceProvider, which bakes the same buffers on CPU worker threads (for data-driven / streaming terrain).

Enums

AssembleError

Errors assembling a custom-surface shader from user GLSL.

Constants

MAX_USER_PARAMS

Max generic user params (@export var name: float) surfaced to a GPU builder’s .glsl. Matches the float cels_user[16] tail in the template’s binding-4 Params block and the pad in pack_params.

TEMPLATE

The library GLSL template. The user’s source replaces the // __CELS_USER_CODE__ marker line.

Functions

assemble_source

Splice user_glsl into TEMPLATE, producing a complete compute shader.

assemble_source_with_params

Like assemble_source, but also splices a #define block — one line per param_names entry — at the defines marker so the user’s .glsl can reference each @export var name: float on the builder as the UPPERCASE NAME (backed by P.cels_user[<index>]). Names past MAX_USER_PARAMS are ignored (they have no backing slot).

pack_params

Pack the custom-surface params buffer (std430) read by the template’s binding-4 Params block: the four fixed fields {chunk_count, tile_res, water_height, height_scale} followed by MAX_USER_PARAMS user floats (cels_user[16]). Extra user values are ignored; missing ones are zero-filled. Total = 16 + 4*MAX_USER_PARAMS bytes.