Shaders
EditShaders are small GPU programs that can be used to customize rendering or perform arbitrary computation. This guide explains how shaders work in LÖVR.
Contents
GLSL
Shaders are written in GLSL. GLSL is a lower-level language than Lua, so shaders are a bit harder to learn at first. Explaining GLSL is outside the scope of these docs, but some good ways to learn it are:
- The OpenGL wiki is a good reference.
- Copying random shaders from the internet and changing them until they do interesting things is another recommended approach.
LÖVR uses GLSL version 4.60
.
Basics
There are 2 types of shaders, given by ShaderType
:
graphics
shaders are used for rendering. They compute vertex positions and pixel colors.compute
shaders run in compute passes. They can perform arbitrary GPU computation.
Shaders have one or more "stages", which are basically functions, given by ShaderStage
:
graphics
shaders have 2 stages:- The
vertex
stage computes vertex positions. It loads vertex data from meshes and applies transformations to get the final "on-screen" position for triangles. - The
fragment
stage computes pixel colors. It uses material data to compute lighting and other effects, returning the final color of the pixel.
- The
compute
shaders have a singlecompute
stage. It doesn't have any semantic meaning, instead performing arbitrary computation by writing toBuffer
andTexture
objects.
Each Pass
has an active shader it uses to process draws. Pass:setShader
changes the active
shader. The active shader will affect all draws until the shader is changed again. When the active
shader is nil
, LÖVR will use a built-in shader based on the type of draw (unlit
for meshes,
font
for text, etc.).
The set of shaders built in to LÖVR are given by DefaultShader
.
Writing Shaders
LÖVR uses the lovrmain
function as the GLSL entrypoint. For vertex stages, lovrmain
should
return the final transformed vertex position. Here's the default vertex shader:
vec4 lovrmain() {
return Projection * View * Transform * VertexPosition;
}
It can also be written using the DefaultPosition
shorthand:
vec4 lovrmain() {
return DefaultPosition;
}
The vertex position is multiplied by several matrices to get it into "normalized device coordinates", which is the coordinate space the GPU uses internally to process vertices.
For fragment shaders, lovrmain
should return the final color of the pixel. Here's the default
fragment shader:
vec4 lovrmain() {
return Color * getPixel(ColorTexture, UV);
}
It can also be written using the DefaultColor
shorthand:
vec4 lovrmain() {
return DefaultColor;
}
The default pixel color is calculated by multiplying the Color
from the vertex stage (which
includes the vertex color, material color, and pass color) with a pixel sampled from the color
texture.
Compute shaders implement the void lovrmain()
function, and don't return anything.
Shaders are created with lovr.graphics.newShader
, with the code for each stage:
shader = lovr.graphics.newShader([[
vec4 lovrmain() {
return DefaultPosition;
}
]], [[
vec4 lovrmain() {
return DefaultColor;
}
]])
The code can also be loaded from a filename or a Blob
. Also, a DefaultShader
can be used for
the code of one or both of the stages:
shader = lovr.graphics.newShader('vertex.glsl', 'unlit')
Shader Builtins
The following built-in variables and macros are available in vertex and fragment shaders:
Name | Type | Notes |
PI |
float | |
TAU |
float | (PI * 2) |
PI_2 |
float | (PI / 2) |
Resolution |
vec2 | The size of the render pass texture, in pixels. |
Time |
float | Current time in seconds (lovr.headset.getTime ). |
CameraPositionWorld |
vec3 | The position of the current view (Pass:setViewPose ). |
Sampler |
sampler | The default sampler (Pass:setSampler ). |
The following built-in variables are available only in vertex shaders:
Name | Type | Notes |
VertexPosition |
vec4 | The local position of the current vertex. |
VertexNormal |
vec3 | The normal vector of the current vertex. |
VertexUV |
vec2 | The texture coordinate of the current vertex. |
VertexColor |
vec4 | The color of the current vertex. |
VertexTangent |
vec3 | The tangent vector of the current vertex. |
Projection |
mat4 | The projection matrix of the current view (Pass:setProjection ). |
View |
mat4 | The view matrix of the current view (Pass:setViewPose ). |
ViewProjection |
mat4 | The projection matrix multiplied with the view matrix. |
InverseProjection |
mat4 | The inverse of the projection matrix. |
Transform |
mat4 | The model matrix (includes transform stack and draw transform). |
NormalMatrix |
mat3 | Transforms normal vectors from local space to world space. |
ClipFromLocal |
mat4 | Transforms from local space to clip space (Projection * View * Transform ). |
ClipFromWorld |
mat4 | Transforms from world space to clip space (Projection * View ). |
ClipFromView |
mat4 | Transforms from view space to clip space (Projection ). |
ViewFromLocal |
mat4 | Transforms from local space to view space (View * Transform ). |
ViewFromWorld |
mat4 | Transforms from world space to view space (View ). |
ViewFromClip |
mat4 | Transforms from clip space to view space (InverseProjection ). |
WorldFromLocal |
mat4 | Transforms from local space to world space (Transform ). |
WorldFromView |
mat4 | Transforms from view space to world space (inverse(View) ). |
WorldFromClip |
mat4 | Transforms from clip space to world space (inverse(ViewProjection) ). |
PassColor |
vec4 | The color set with Pass:setColor . |
The following built-in variables and macros are available only in fragment shaders:
Name | Type | Notes |
PositionWorld |
vec3 | The position of the pixel, in world space. |
Normal |
vec3 | The normal vector of the pixel, in world space. |
Color |
vec4 | The vertex, material, and pass colors multiplied together. |
UV |
vec2 | The texture coordinate of the current pixel. |
Tangent |
vec3 | The tangent vector of the current pixel, in world space. |
TangentMatrix |
mat3 | The tangent matrix, used for normal mapping. |
The properties of the active material, set using Pass:setMaterial
, can be accessed in vertex and
fragment shaders. Textures can be sampled using the getPixel
helper function. The Material
and
lovr.graphics.newMaterial
pages have more info on these properties.
Name | Type | Notes |
Material.color |
vec4 | The material color. |
Material.glow |
vec4 | The material glow color (alpha is glow strength). |
Material.uvShift |
vec2 | The material UV shift. |
Material.uvScale |
vec2 | The material UV shift. |
Material.metalness |
float | The material metalness. |
Material.roughness |
float | The material roughness. |
Material.clearcoat |
float | The material clearcoat factor. |
Material.clearcoatRoughness |
float | The roughness of the clearcoat layer. |
Material.occlusionStrength |
float | The strength of the occlusion texture. |
Material.normalScale |
float | The strength of the normal map texture. |
Material.alphaCutoff |
float | The alpha cutoff. |
ColorTexture |
texture2D | The color texture. |
GlowTexture |
texture2D | The glow texture. |
OcclusionTexture |
texture2D | The ambient occlusion texture. |
MetalnessTexture |
texture2D | The metalness texture. |
RoughnessTexture |
texture2D | The roughness texture. |
ClearcoatTexture |
texture2D | The clearcoat texture. |
NormalTexture |
texture2D | The normal map. |
Shader Inputs
It's also possible to send values or objects from Lua to a Shader. There are a few different ways to do this, each with their own tradeoffs (speed, size, ease of use, etc.).
Constants
Shaders can declare constants, which can be booleans, numbers, vectors, or matrices. There is a very limited amount of space for constants (usually 128 or 256 bytes, depends on the GPU), but they are very easy and inexpensive to update.
Constants are declared in shader code in a Constants
block, then individual constants are modified
from Lua using Pass:send
:
function lovr.load()
shader = lovr.graphics.newShader('unlit', [[
Constants {
vec4 color1;
vec4 color2;
};
// Apply a vertical gradient using the 2 colors from the constants:
vec4 lovrmain() {
return mix(color1, color2, dot(Normal, vec3(0, 1, 0)) * .5 + .5);
}
]])
end
function lovr.draw(pass)
pass:setShader(shader)
pass:send('color1', { 1, 0, 1, 1 })
pass:send('color2', { 0, 1, 1, 1 })
pass:sphere(0, 1.7, -2)
end
The vertex and fragment stages share the constants block, so they should match or one should be a subset of the other.
When the active shader is changed, constants will be preserved.
Vertex Attributes
Vertex attributes are the data for each vertex of a mesh. They should be used for data that varies on a per-vertex basis. Attributes have a name, a type, and a location (an integer ID). LÖVR uses the following default vertex attributes for shapes and meshes:
Name | Type | Location |
VertexPosition | vec4 | 10 |
VertexNormal | vec3 | 11 |
VertexUV | vec2 | 12 |
VertexColor | vec4 | 13 |
VertexTangent | vec3 | 14 |
Custom vertex attributes can be declared for locations 0 through 9:
layout(location = 3) in vec3 customAttribute;
The data in a buffer can then be associated with the attribute, either by name:
vertices = lovr.graphics.newBuffer(vertexCount, {
{ type = 'vec3', name = 'customAttribute' }
})
Or by location:
vertices = lovr.graphics.newBuffer(vertexCount, {
{ type = 'vec3', location = 3 }
})
Buffers
Shaders can access data in Buffer
objects. Buffers can store large arrays of data from Lua tables
or Blobs. The GPU can also write to buffers using compute shaders.
Data in buffers can be accessed in 2 ways:
- Uniform buffers have a smaller size limit, may be faster, and are read-only in shaders.
- Storage buffers have a large size limit, may be slower, and compute shaders can write to them.
First, the buffer should be declared in the shader. Here's an example declaring a uniform buffer:
layout(set = 2, binding = 0) uniform Colors {
vec4 colors[100];
};
And an example storage buffer:
layout(set = 2, binding = 0) buffer Colors {
vec4 colors[100];
};
The first part declares the set and binding of the variable. Right now the set should always be 2
(LÖVR uses set 0 and 1 internally). The binding is a number that can be used to identify the
variable. After that, uniform
or buffer
is used to declare which type of buffer it is, followed
by the name of the variable. Finally, there is a block declaring the format of the data in the
buffer, which should match the format used to create the Buffer in Lua (structs can be used if the
buffer has multiple fields per element).
A Buffer can be sent to one of the above variables like this:
-- palette is a table with 100 colors in it
buffer = lovr.graphics.getBuffer(palette, 'vec4')
pass:send('Colors', buffer)
-- or, using the binding number
pass:send(0, buffer)
The shader can then use the colors
array to access the data from the palette
table.
It's possible to bind a subset of a buffer to the shader by passing the range as extra arguments to
Pass:send
.
Textures
Shaders can also access data from Texture
objects. Similar to buffers, textures can be accessed
in 2 ways:
- Sampled textures are read-only, and can use
Sampler
objects. - Storage textures can be written to using compute shaders.
Sampled textures are declared like this:
layout(set = 2, binding = 0) uniform texture2D myTexture;
The texture type can be texture2D
, textureCube
, texture2DArray
, or texture3D
(see
TextureType
).
Storage textures are declared like this:
layout(set = 2, binding = 0) uniform image2D myImage;
A texture can be sent to the shader variable using Pass:send
.
The getPixel
helper function can be used to sample from a texture:
getPixel(myTexture, UV)
This will sample from the texture using the UV coordinates and the default sampler set using
Pass:setSampler
. It's the same as writing this for 2D textures:
texture(sampler2D(myTexture, Sampler), UV)
It's also possible to declare a custom sampler variable and use it to sample textures:
layout(set = 2, binding = 0) uniform sampler mySampler;
// texture(sampler2D(myTexture, mySampler), UV)
A Sampler
object can be sent to the shader using Pass:send
, similar to buffers and textures.