Porting GLSL: stages, coordinates and effect inputs
Complete fragment example, explicit uniforms and coordinate checks without blind replacements.
Port the shader's inputs, coordinate spaces and outputs, not only its entry-point name. A regular Reckfell Shader uses the engine shading language; raw GLSL compute through RenderingDevice is a different workflow.
Decide what is being rendered
Use canvas_item for a 2D CanvasItem material, spatial for a 3D surface, and the appropriate specialized type for particles, sky or fog. The example below is a 2D ColorRect effect. It does not turn an arbitrary vertex/fragment pair into a 3D material or replace a multi-pass render pipeline.
A regular engine shader has no GLSL #version, layout(location=...) stage interface or main entry point. Define shader_type and use vertex(), fragment() and other functions supported by that shader type. Shared helper functions can stay ordinary shader functions with supported parameter types.
Complete fragment-port example
Save this source as PortedUv.reckfellshader:
shader_type canvas_item;
render_mode unshaded;
uniform vec2 effect_resolution = vec2(128.0, 128.0);
uniform float effect_time = 0.0;
void mainImage(out vec4 frag_color, vec2 frag_coord) {
vec2 size = max(effect_resolution, vec2(1.0));
vec2 position = frag_coord / size;
frag_color = vec4(position, 0.25 + 0.25 * sin(effect_time), 1.0);
}
void fragment() {
vec4 result;
vec2 size = max(effect_resolution, vec2(1.0));
mainImage(result, UV * size);
COLOR = result;
}Load it with ResourceLoader.Load<Shader>("asset://PortedUv.reckfellshader"), assign it to a ShaderMaterial.Shader, and assign that material to a visible ColorRect. The checked card is 128×128. The red channel increases left-to-right and green top-to-bottom; blue is approximately 0.25 at effect_time=0.
To change time, call material.SetShaderParameter("effect_time", Mathf.Pi / 2). Blue rises to approximately 0.5 without replacing the Shader resource. This is an explicit time input: the caller decides whether pausing, time scaling or replay should affect it. The mainImage helper keeps its out-color/coordinate interface; fragment supplies coordinates and writes COLOR.
The custom effect_resolution uniform describes the effect's chosen coordinate domain. It is not automatically the viewport size, item size or texture size. This normalized-gradient example multiplies UV by that domain before the helper divides by it, so resizing the domain preserves the gradient. Aspect-sensitive effects must define their own normalization instead of relying on a replacement table.
Map each interface deliberately
| Source concept | Engine-side decision |
|---|---|
| main / mainImage | Move stage work into fragment/vertex or call a helper from the stage function. Match parameter directions and output assignment. |
| gl_FragColor | COLOR for a canvas_item fragment. A spatial surface normally writes ALBEDO and other material outputs instead. |
| gl_Position | Clip-space output in GLSL; not a direct rename to VERTEX. Ordinary vertex VERTEX is stage/type-dependent and transformed by the engine. |
| Vertex attributes / varyings | Use supported built-ins and declared varying values; do not copy layout locations blindly. |
| gl_FragCoord | FRAGCOORD for viewport-oriented pixel work in the relevant stage. It is not the same domain as an individual item's UV. |
| Texture dimensions | TEXTURE_PIXEL_SIZE for the built-in canvas texture, or textureSize on the specific sampler. |
| Viewport dimensions | SCREEN_PIXEL_SIZE in canvas fragments gives reciprocal viewport dimensions; it is not a sprite's local size. |
| External texture channels | Declare sampler uniforms and assign the intended textures. A built-in TEXTURE is not an automatic replacement for every channel. |
| External time, mouse, frame, date | Provide explicit uniforms when their original semantics matter. Do not assume TIME reproduces another program's pause/reset policy. |
| Macros and includes | Follow the engine preprocessor; regular shaders and raw GLSL compute have different source pipelines. |
Verify coordinates and color before the full effect
Start with a coordinate gradient or four distinct corner colors. For the tested ColorRect, UV increases rightward and downward. Do not introduce a universal Y flip: source coordinate conventions, textures, target surfaces and rendering paths can differ. If an effect is mirrored, identify which input changed orientation and adjust that boundary once.
Keep texture sampling, CanvasItem modulation, alpha blending and color-space conversion separate. A canvas fragment's incoming COLOR can already include its texture/modulation path; sampling and multiplying the same texture again can darken it. Source-color sampler/uniform hints describe color data; normals, masks and numerical buffers require their actual data interpretation. The gradient above uses no texture, so it does not validate every sampling or transparency case.
Port in stages
- Compile a constant-color shader of the correct type.
- Confirm the coordinate gradient and effect dimensions.
- Add one texture/input at a time and set its uniforms explicitly.
- Restore the algorithm, then test alpha, color and motion independently.
- Rebuild multi-pass behavior with appropriate viewports or rendering integration; copying one fragment function does not recreate previous-frame buffers or feedback.
If the shader compiles but looks wrong, check input dimensions and orientation before changing the algorithm. If it fails to compile, inspect the first stage/type/syntax error before later dependent messages. Function renaming alone is not a validated port.
Actual checks render the complete shader, verify both UV axes and out-color output, and update time/resolution uniforms while preserving the Shader identity. They do not validate arbitrary GLSL features, 3D clip-space rewrites, texture-channel combinations, multi-pass feedback or all renderer/platform targets.