Shader

As of 1.12.0, Ebitengine has APIs to render custom shaders. This document explains how to use custom shaders.

What's a shader?

A shader is a program executed on GPU. A custom shader is a shader an Ebitengine user can write. With shaders, you can execute a complex rendering on GPU efficiently.

In Ebitengine, you can write a 'fragment shader'. A fragment shader is a shader executed on each pixel. Roughly speaking, this is a function to calculate a color for each pixel. This color calculation is executed on GPU in parallel.

With shaders, you can execute various effects like lighting or blur. For an example, see examples/shader.

go run -tags=example github.com/hajimehoshi/ebiten/v2/examples/shader@latest

Ebitengine adopts an original shading language 'Kage'. This has a compatible syntax with Go, but the details are different. Kage has high portability. Ebitengine uses graphics libraries like OpenGL or Metal and this depends on environments, but Kage is compiled on the fly so that this works equally everywhere.

Example

package main

// Uniform variables.
var Time float
var Cursor vec2
var ScreenSize vec2

// Fragment is the entry point of the fragment shader.
// Fragment returns the color value for the current position.
func Fragment(position vec4, texCoord vec2, color vec4) vec4 {
	// You can define variables with a short variable declaration like Go.
	lightpos := vec3(Cursor, 50)
	lightdir := normalize(lightpos - position.xyz)
	normal := normalize(imageSrc1UnsafeAt(texCoord) - 0.5)
	ambient := 0.25
	diffuse := 0.75 * max(0.0, dot(normal.xyz, lightdir))

	// You can treat multiple source images by
	// imageSrc[N]At or imageSrc[N]UnsafeAt.
	return imageSrc0UnsafeAt(texCoord) * (ambient + diffuse)
}

Ebitengine API

NewShader

func NewShader(src []byte) (*Shader, error)

NewShader compiles a shader program in the shading language Kage, and returns the result.

If the compilation fails, NewShader returns an error.

(*Image).DrawRectShader

func DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)

DrawRectShader draws a rectangle with the specified width and height with the specified shader.

DrawRectShaderOptions

type DrawRectShaderOptions struct {
    // GeoM is a geometry matrix to draw.
    // The default (zero) value is identity, which draws the rectangle at (0, 0).
    GeoM GeoM

    // CompositeMode is a composite mode to draw.
    // The default (zero) value is regular alpha blending.
    CompositeMode CompositeMode

    // Uniforms is a set of uniform variables for the shader.
    // The keys are the names of the uniform variables.
    // The values must be float or []float.
    // If the uniform variable type is an array, a vector or a matrix,
    // you have to specify linearly flattened values as a slice.
    // For example, if the uniform variable type is [4]vec4, the number of the slice values will be 16.
    Uniforms map[string]interface{}

    // Images is a set of the source images.
    // All the image must be the same size with the rectangle.
    Images [4]*Image
}

The others

For more primitive rendering, there are also (*Image).DrawTrianglesShader and DrawTrianglesShaderOptions.

Shading language Kage

Syntax

The syntax is basically same as Go. This is completely same in the syntax level. You can do even gofmt.

Kage doesn't have these Go's features so far.

• Most types (rune, string, numeric types except for int, interface, slices, pointers, structs, function types, channels)
• Built-in functions except for len (e.g., new, make, panic)
• New type definition with type
• Structs
• import
• switch
• goto
• for-range
• Goroutines
• defer
• init functions
• Method definition

Entry point

Kage can define only a fragment shader. The Fragment function with the below signature is the entrypoint.

func Fragment(position vec4, texCoord vec2, color vec4) vec4

Built-in types

Kage has these built-in types.

• bool
• int
• float
• vec2, vec3, vec4 (Vector)
• mat2, mat3, mat4 (Matrix)

float is a floating point number. Unlike Go's float32 and float64, float doesn't have a guarantee for the precision.

vec2, vec3, vec4, called vectors, are tuples that has 2, 3, and 4 components respectively. Each component is float. Swizzling operation is available on vector values.

mat2, mat3, mat4 are 2, 3 and 4 dimensional square matrices. Each component is float.

Kage also supports arrays. Kage doesn't support structs yet.

Initializing functions for built-in types

Similar to Go, you can get the type's value by using the type name as a function. Vector types and matrix types are so special that they can take flexible arguments.

v1 := vec4(0)              // Returns a vec4 whose components are all 0.
v2 := vec4(1, 2, 3, 4)     // Returns a vec4 whose components are 1, 2, 3 and 4.
v3 := vec3(5, 6, 7)
v4 := vec4(1, v3)          // Returns a vec4 whose components are 1, 5, 6 and 7.

m1 := mat4(2)              // Returns a mat4 whose diagonal components are 2 and the others are 0.
m2 := mat4(v1, v2, v3, v1) // Returns a mat4 whose columns are v1, v2, v3 and v1.

Swizzling

There is a special operation called Swizzling for vector types. You can read and write multiple components at the same time.

v1 := vec4(1, 2, 3, 4)
v2 := v1.xyz           // Get vec3(1, 2, 3) and initialize v2 with this.
v2.xyz = v2.xxx        // Get vec3(1, 1, 1), and set it to all the components to v2.
                       // Then, v2 is now (1, 1, 1).

Each component is represent like below. You can mix them in the same group, but you cannot in different groups. For example, .xxyy and .abgr are available, but .xxgg is invalid.

• x, y, z, w
• r, g, b, a
• s, t, p, q

Uniform variables

A uniform variable is a global variable whose value is given externally. This value is the same regardless of the position of the pixel.

In Kage, uniform variables are global variables that start with upper cases (i.e., exported variables).

You cannot assign a value into a uniform variable in Kage.

You cannot define other global variables than uniform variables in Kage.

Built-in functions (Go)

Built-in functions (Control)

Built-in functions (mathematics)

Most of the built-in functions are generic. T represents float, vec2, vec3 or vec4 unless otherwise noted. When the type is a vector, the function is applied for each component.

Built-in functions (images)

Textures and images

Ebitengine's image (ebiten.Image) is actually a part of an internal texture. Then, position calculations in shaders are a little complex.

A pixel is a unit for one color dot. On the other hand, texel is a unit covering the whole area with values in between 0 and 1. The meaning of texels depends on a texture, then you cannot mix texels with different textures.

To convert pixels and texels each other, you can use these formulas.

\begin{aligned} (\text{texels}) &= \frac{(\text{pixels})}{(\text{the texture's size in pixels})} \\ (\text{pixels}) &= (\text{texels}) \cdot (\text{the texture's size in pixels}) \\ \end{aligned}

Editor Plugins

There are plugins for some editors by volunteers to edit Kage programs.

• Visual Studio Code
• Vim
• Sublime