# Shader Syntax Overview
# Preprocessor
Wallpaper Engine uses a custom preprocessor to cull unused code and introspect a shader before compilation. The preprocessor is not a fullfledged C preprocessor and is lacking, for example, string conversion and concatenation. Conditionals should however work with boolean and logic operators, except for #elif, which isn't supported.
# The following define directives are applied based on context
- GLSL: Shader is being compiled as GLSL.
- HLSL: Shader is being compiled as HLSL.
- HLSL_SM40: Shader is being compiled for shader model 4.
- HLSL_GS40: Current renderer supports shader model 4 geometry shaders.
# The following directives make it easier to write a shader that supports GLSL and HLSL
- texSample2D (sampler, vec2 uvs) -> vec4: Sample a simple 2D texture. First parameter is a sampler constant and the second parameter a vec2 texture coordinate.
- texSample2DLod (sampler, vec2 uvs, float lod) -> vec4: Sample a simple 2D texture. First parameter is a sampler constant, the second parameter a vec2 texture coordinate and the third parameter a float to designate which mip maps get sampled.
- mix: Mix is the GLSL name for lerp in HLSL and accepted for both in Wallpaper Engine. So you should use mix to make the shader fully compatible.
- frac: frac is the HLSL name for fract in GLSL. So you should use frac to make the shader fully compatible.
- saturate: saturate is the HLSL name for clamp(x, 0, 1) in GLSL.
- atan2: atan2 is the HLSL name for atan in GLSL. So you should use atan2 to make the shader fully compatible.
- ddx: ddx is the HLSL name for dFdx in GLSL. So you should use ddx to make the shader fully compatible.
- ddy: ddy is the HLSL name for dFdy in GLSL. So you should use ddy to make the shader fully compatible.
# Type Casting
Since shaders are translated into HLSL, it is recommended to use the following casting macros for construction and casting. For example, when you want to cast a 4x4 matrix into 3x3 or when you want to create a vec3 from a single float.
- CAST2(): This will call vec2(x) in GLSL and do (float2)x in HLSL.
- CAST3(): This will call vec3(x) in GLSL and do (float3)x in HLSL.
- CAST4(): This will call vec4(x) in GLSL and do (float4)x in HLSL.
- CAST3X3(): This will call mat3(x) in GLSL and do (float3x3)x in HLSL.
# Shader Inputs and Outputs
Wallpaper Engine currently uses the old GLSL syntax based on attribute, varying, uniform and globals like gl_FragColor.
- An attribute is a hardcoded parameter that is provided by Wallpaper Engine per vertex.
- A varying can be freely defined by you. This is what the vertex shader outputs to the pixel shader and will be linearly interpolated between adjacent vertices of a primitive.
- Final global outputs like gl_FragColor are forwarded to the next stage to be immediately used for displaying the result of your shader.
# Vertex Shader
Vertex shaders for image/text layers currently only support the attributes a_Position and a_TexCoord.
# Input Attributes
- a_Position (
vec3): The position in object space. - a_PositionVec4 (
vec4) - a_Normal (
vec3): The normal in object space. - a_Tangent4 (
vec4): The tangent in object space with bitangent sign in w. - a_TexCoord (
vec2): The basic texture coordinates. - a_TexCoordVec3 (
vec3) - a_TexCoordVec4 (
vec4) - a_TexCoordC1 (
vec2) - a_TexCoordVec3C1 (
vec3) - a_TexCoordVec4C1 (
vec4) - a_TexCoordC2 (
vec2) - a_TexCoordVec3C2 (
vec3) - a_TexCoordVec4C2 (
vec4) - a_TexCoordC3 (
vec2) - a_TexCoordVec3C3 (
vec3) - a_TexCoordVec4C3 (
vec4) - a_TexCoordC4 (
vec2) - a_TexCoordVec3C4 (
vec3) - a_TexCoordVec4C4 (
vec4) - a_TexCoordC5 (
vec2) - a_TexCoordVec3C5 (
vec3) - a_TexCoordVec4C5 (
vec4) - a_Color (
vec4)
# Fragment Shader
# Outputs
- gl_FragColor (
vec4): The final output color for a given pixel.