We allow loading rendering shaders to be used on sprites and, in the future, even more things. The system closely matches Godot's system because, well, it's easy to implement. Full-screen shaders can also be drawn using Overlays.
Shaders are defined through the prototype system. The arch-type you want is shader.
Shaders can be defined to load Godot shader source code, or use the preset shader options (aking to Godot's CanvasItemMaterial). This can be configured through the kind property of the prototype.
Every shader needs an ID for it to be referenced by. This can be set through the id property of the prototype.
canvas kind:canvas matches Godot's CanvasItemMaterial. There are a whopping two properties:
blend_mode: The way the object is drawn over the scene. These are the same as the equivalent for Godot. Barring the naming being slightly different. Possible values are mix, add, subtract, multiply and premultiplied_alphalight_mode: The way the object interacts with light. Again equivalent to Godot's, with the values being normal, unshaded and light_only.For example, the unshaded prototype used for computer displays:
- type: shader
id: unshaded
kind: canvas
light_mode: unshaded
source kind:source allows you to load shaders from source code. The source code used here is Godot's shading language, which you can read about here.
source has one property, path, the path to a file containing the actual source code. Right now I settled on .swsl for the file extension of these shaders.
Many of the compatibility differences are handled automatically. One notable one you must do manually is to ensure that every relevant variable has highp or lowp. For example, highp vec3 rather than just vec3.
| Name | Type | Description |
|---|---|---|
FRAGCOORD |
highp vec4 |
The coordinates within the fragment. |
COLOR |
lowp vec4 |
The resulting pixel color. (Think of it as the return value of the fragment shader.) |
lightMap |
sampler2D |
The lighting map of the current fragment (applied automatically by base-default.frag) |
modulate |
highp vec4 |
The draw color (applied automatically by base-default.frag) |
SCREEN_PIXEL_SIZE |
highp vec2 |
The size of one pixel, in local units. |
TIME |
highp float |
The number of seconds since game startup. |
Shader support stencil operations. This is an advanced rendering feature that can be useful for some things if you know what you're doing. The feature closely mimics the stencil parameters as exposed by OpenGL (and as far as I can tell, Vulkan too). See The OpenGL wiki if you need a reference.
Stencil parameters are defined in a separate stencil object. As an example:
- type: shader
id: stencilDraw
kind: canvas
stencil:
ref: 1
op: Keep
func: NotEqual
Indeed, stencil parameters are independent from the shader kind.
The options are:
ref: The reference to compare / write as passed to the second parameter of glStencilFunc.
op: The operation to apply to the stencil buffer if the stencil test passes. You can only set the op on pass (glStencilOp's third parameter).
Keep, Zero, Replace, IncrementClamp, IncrementWrap, DecrementClamp, DecrementWrap, InvertKeep.func: The comparison function to use to see if the test passes. (glStencilFunc's first parameter).
Always, Never, Less, LessOrEqual, Greater, GreaterOrEqual, NotEqual, Equal.Always.readMask: Mask to use when reading from the stencil buffer (glStencilFunc's third parameter).
writeMask: Mask to use when writing to the stencil buffer (glStencilMask's parameter).
Shaders that apply to screens/viewports as opposed to individual sprites use overlays. An overlay, at minimum, needs to retrieve the appropriate shader and implement the Draw function. For an overlay draw function, you need the following: