CanvasItem: 2D color, coordinates and lighting

A CanvasItem shader controls 2D drawing: sprites, UI and other CanvasItem objects. Assign a Shader to a ShaderMaterial, then assign the material to the object. The Entity hierarchy and a VisualShader graph are separate mechanisms.

First working material

1. Create a Sprite2D with a visible texture. Keep Modulate and SelfModulate white.
2. Assign a new ShaderMaterial to Material.
3. Create a Shader in the material's Shader property and paste the complete code below.
4. Edit the material's tint: white preserves the source, green keeps its green channel, and Alpha=0 hides the object.

shader_type canvas_item;
render_mode unshaded;
uniform vec4 tint : source_color = vec4(1.0);
void fragment() {
    COLOR *= tint;
}

In C#, call material.SetShaderParameter("tint", new Color(0, 1, 0, 1)). The name must match the uniform. Two different ShaderMaterials can share one Shader with independent values; a shared material shares parameter values. Passing default(Variant) removes the material value and restores the uniform initializer.

The example uses unshaded so lighting does not interfere with color inspection. Remove it to respond to Light2D. Use source_color for a color parameter; an ordinary numeric vector is not automatically a color.

COLOR already contains the texture

Consequently, COLOR *= texture(TEXTURE, UV) normally multiplies the texture twice, a common cause of darkening. To use only the texture and bypass vertex modulation, assign COLOR directly:

shader_type canvas_item;
render_mode unshaded;
void fragment() {
    COLOR = texture(TEXTURE, UV);
}

To use vertex color without the main texture, pass it through a varying:

shader_type canvas_item;
render_mode unshaded;
varying vec4 vertex_color;
void vertex() {
    vertex_color = COLOR;
}
void fragment() {
    COLOR = vertex_color;
}

The test uses texture RGB (0.8, 0.4, 0.2), Modulate (0.5, 1, 1) and SelfModulate (0.5, 1, 1), producing (0.2, 0.4, 0.2). Sampling and multiplying again produces (0.16, 0.16, 0.04). This checks ordinary 2D arithmetic, not every HDR/color pipeline.

Keep coordinate spaces distinct

In vertex(), VERTEX contains local geometry coordinates in pixels. The default path applies MODEL_MATRIX, then CANVAS_MATRIX and SCREEN_MATRIX. The latter stages account for the canvas/camera and projection. Fragment VERTEX already contains the position after the canvas transform; it is not the original local VERTEX.

UV addresses the texture; SCREEN_UV addresses the current viewport. FRAGCOORD.xy contains viewport pixel-center coordinates, not values from 0 to 1. The tested Vulkan path uses a top-left origin: FRAGCOORD.xy * SCREEN_PIXEL_SIZE matches SCREEN_UV. OS window size and Sprite2D size are not substitutes for viewport resolution.

TEXTURE_PIXEL_SIZE is the reciprocal source texture size: an 8×4 texture gives (0.125, 0.25) even when the sprite is enlarged. For a separate custom sampler, use that sampler's own dimensions rather than the main TEXTURE size.

For a region-enabled Sprite2D, UV already addresses a subrectangle of the full texture. In the tested rectangle path, REGION_RECT contains normalized offset and size: region (2,1,4,2) in an 8×4 texture gives (0.25,0.25,0.5,0.5). To obtain coordinates within that region, subtract REGION_RECT.xy and divide by nonzero REGION_RECT.zw. Do not apply the region offset again to the existing UV. Inspect actual coordinates when using flips, atlases, animation frames or other primitive paths.

skip_vertex_transform disables only the automatic local-to-world step. This complete example performs that step manually; canvas transformation and projection remain automatic:

shader_type canvas_item;
render_mode unshaded, skip_vertex_transform;
void vertex() {
    VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}
void fragment() {
    COLOR = vec4(UV, 0.0, 1.0);
}

With world_vertex_coords, MODEL_MATRIX is instead applied before the user vertex() function. Do not apply it a second time.

Render modes

Choose one blend mode. For premultiplied alpha, calculate final alpha first and multiply RGB by it exactly once. discard removes the selected fragment; merely setting alpha to zero depends on the blend mode.

Built-ins by stage

in is read-only; out is a result without a guaranteed meaningful initial value; inout has an initial value and can be changed. A sampler is used for texture reads. Names are stage-specific: a varying transfers selected data between stages, but does not make every built-in available everywhere.

TIME is global renderer time in seconds and follows Engine.TimeScale. Pausing the scene tree alone does not stop it. rendering/limits/time/time_rollover_secs sets rollover, defaulting to 3600 seconds. Supply your own time uniform for controlled gameplay animation. Global PI, TAU and E are float mathematical constants.

vertex()

fragment()

light()

Lighting and normal maps

Without light(), standard lighting applies. Declaring a custom light() replaces it even when the body is empty: the tested empty function contributes zero. unshaded bypasses custom lighting. Check the light texture, energy, visibility and matching item/light masks; CanvasModulate affects base lighting.

A complete normal-aware light shader:

shader_type canvas_item;
void light() {
    float ndotl = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
    LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * ndotl, LIGHT_COLOR.a);
}

This is a simple diffuse calculation without a separate specular model. CanvasTexture can supply a normal map. For an explicit RGB-encoded sample, write NORMAL_MAP, for example assign texture(NORMAL_TEXTURE, UV).rgb to it inside fragment(); NORMAL is already the lighting normal vector. Do not replace it with unprocessed RGB. Verify map orientation under an actual light.

SDF uses a separate coordinate space

A LightOccluder2D with an OccluderPolygon2D and SDF Collision enabled participates in the viewport distance field. A new LightOccluder2D enables this flag in its constructor. Visibility and viewport SDF coverage/scale affect the result.

These functions are available from fragment()/light() and functions called from them, not vertex(). Do not pass ordinary texture UV to texture_sdf without converting spaces. For screen reads, declare your own sampler with hint_screen_texture; the current registry has no SCREEN_TEXTURE built-in. See screen-reading shaders.

Troubleshooting

Windows Forward+/Vulkan checks execute the five complete examples above and inspect actual color, alpha, coordinate, region, transform and custom-light pixels. The complete built-in table, SDF, TIME/pause, remaining blend modes and world_vertex_coords are source-reviewed; this does not claim separate acceptance for every platform, renderer or export.