shaders

Documentation

Overview

Package shaders provides a ShaderMaterial.Instance with the shader pipeline written within Go.

Shaders are multi-stage programs executed on the GPU. They can be used to gain precise control over rendering calculations, such as lighting, shadows, and post-processing effects.

To create a new 2D shader in Go, define a struct that embeds shaders.Type2D and implements the pipeline methods you would like to overide. For example:

type MyShader struct {
	shaders.Type2D

	MyUniform vec2.XY `gd:"my_uniform"`
}

// The pipeline functions are named after what they return, not what they accept as
// input.

// Fragment returns a fragment for the given vertex (also known as a vertex shader).
func (MyShader) Fragment(vertex shaders.Vertex2D) shaders.Fragment2D {
	return shaders.Fragment2D{
		Position: vertex.Position,
	}
}

// Material returns a material for the given fragment (also known as a fragment shader).
func (MyShader) Material(fragment shaders.Fragment2D) shaders.Material2D {
	return shaders.Material2D{
		Color: rgba.New(1, 0, 0, 1),
	}
}

// Lighting calculates the lighting for the given material (also known as a lighting pass).
func (MyShader) Lighting(material shaders.Material2D) vec4.RGBA {
	return material.Color
}

Each sub-package provides GPU-specific shader types that can be used within a shader pipeline. Keep in mind that the Go code is compiled to run on the GPU, so non-GPU values, function calls or branches will only take affect during compilation and not when rendering.

All for loops will be unrolled. The shaders package does not currently support non-constant loops.

Index

• Variables
• func Compile[V, F, M comparable](prog Program[V, F, M])
• type Fragment2D
• type FragmentReadOnly2D
• type Globals
• type Light2D
• type Material2D
  • func (mat Material2D) FromScreenUV(uv vec2.XY) vec2.XY
  • func (mat Material2D) ToScreenUV(pos vec2.XY) vec2.XY
• type MaterialReadOnly2D
• type MaterialSDF
  • func (mat MaterialSDF) Texture(pos vec2.XY) float.X
  • func (mat MaterialSDF) TextureNormal(pos vec2.XY) vec3.XYZ
• type Program
• type RenderingOption2D
• type Type2D
  • func (Type2D) Fragment(vertix Vertex2D) Fragment2D
  • func (Type2D) Lighting(material Material2D) vec4.RGBA
  • func (Type2D) Material(fragment Fragment2D) Material2D
• type Type3D
• type Vertex2D

Variables

var RenderingOptions2D = xyz.AccessorFor(RenderingOption2D.Values)

Functions

func Compile

func Compile[V, F, M comparable](prog Program[V, F, M])

Types

type Fragment2D

type Fragment2D struct {
	FragmentReadOnly2D

	Position  vec2.XY   `gd:"VERTEX"`     // Vertex, in local space.
	UV        vec2.XY   `gd:"UV"`         // Normalized texture coordinates. Range from 0 to 1.
	Color     vec4.RGBA `gd:"COLOR"`      // Color from vertex primitive.
	PointSize float.X   `gd:"POINT_SIZE"` // Point size for point drawing.
}

type FragmentReadOnly2D

type FragmentReadOnly2D struct {
	Globals

	Pixel                    vec4.XYZW                    `gd:"FRAGCOORD"`                  // Coordinate of pixel center. In screen space. xy specifies position in window. Origin is upper-left.
	PixelSize                vec2.XY                      `gd:"SCREEN_PIXEL_SIZE"`          // Size of individual pixels. Equal to inverse of resolution.
	Point                    vec2.XY                      `gd:"POINT_COORD"`                // Coordinate for drawing points.
	Texture                  texture.Sampler2D[vec4.RGBA] `gd:"TEXTURE"`                    // Default 2D texture.
	TexturePixelSize         vec2.XY                      `gd:"TEXTURE_PIXEL_SIZE"`         // Normalized pixel size of default 2D texture. For a Sprite2D with a texture of size 64x32px, TexturePixelSize = vec2(1/64, 1/32)
	AtLightPass              bool.X                       `gd:"AT_LIGHT_PASS"`              // Always false.
	SpecularShininessTexture texture.Sampler2D[vec4.RGBA] `gd:"SPECULAR_SHININESS_TEXTURE"` // Specular shininess texture of this object.
	SpecularShininess        vec4.XYZW                    `gd:"SPECULAR_SHININESS"`         // Specular shininess color, as sampled from the texture.
	UV                       vec2.XY                      `gd:"UV"`                         // UV from vertex function.
	ScreenUV                 vec2.XY                      `gd:"SCREEN_UV"`                  // Screen UV coordinate for current pixel.
	Normal                   vec3.XYZ                     `gd:"NORMAL"`                     // Normal from vertex function.
	NormalTexture            texture.Sampler2D[vec4.RGBA] `gd:"NORMAL_TEXTURE"`             // Default 2D normal texture.
}

type Globals

type Globals struct {
	// Global time since the engine has started, in seconds. It repeats after every 3,600 seconds (which can be changed with
	// the rollover setting). It's not affected by time_scale or pausing. If you need a TIME variable that can be scaled or
	// paused, add your own global shader uniform and update it each frame.
	Time vec1.X `gd:"TIME"`
}

type Light2D

type Light2D struct {
	Color         vec4.RGBA `gd:"LIGHT_COLOR"`          // Color of Light multiplied by Light's texture.
	Energy        float.X   `gd:"LIGHT_ENERGY"`         // Energy multiplier of Light.
	Position      vec3.XYZ  `gd:"LIGHT_POSITION"`       // Position of Light in screen space. If using a DirectionalLight2D this is always vec3(0,0,0).
	Direction     vec3.XYZ  `gd:"LIGHT_DIRECTION"`      // Direction of Light in screen space.
	IsDirectional bool.X    `gd:"LIGHT_IS_DIRECTIONAL"` // true if this pass is a DirectionalLight2D.
}

type Material2D

type Material2D struct {
	MaterialReadOnly2D

	SDF MaterialSDF

	Position            vec2.XY   `gd:"VERTEX"`        // Pixel position in screen space.
	PositionForShadows  vec2.XY   `gd:"SHADOW_VERTEX"` // Same as Position but can be written to alter shadows.
	PositionForLighting vec3.XYZ  `gd:"LIGHT_VERTEX"`  // Same as Position but can be written to alter lighting. Z component represents height.
	Normal              vec3.XYZ  `gd:"NORMAL"`        // Normal from vertex function.
	Color               vec4.RGBA `gd:"COLOR"`         // Color from vertex primitive.
}

func (Material2D) FromScreenUV

func (mat Material2D) FromScreenUV(uv vec2.XY) vec2.XY

func (Material2D) ToScreenUV

func (mat Material2D) ToScreenUV(pos vec2.XY) vec2.XY

type MaterialReadOnly2D

type MaterialReadOnly2D struct {
	Globals
	Light2D

	Pixel             vec4.XYZW                    `gd:"FRAGCOORD"`          // Coordinate of pixel center. In screen space. xy specifies position in window. Origin is upper-left.
	UV                vec2.XY                      `gd:"UV"`                 // UV from vertex function.
	Texture           texture.Sampler2D[vec4.RGBA] `gd:"TEXTURE"`            // Current texture in use for CanvasItem.
	TexturePixelSize  vec2.XY                      `gd:"TEXTURE_PIXEL_SIZE"` // Normalized pixel size of default 2D texture. For a Sprite2D with a texture of size 64x32px, TexturePixelSize = vec2(1/64, 1/32)
	ScreenUV          vec2.XY                      `gd:"SCREEN_UV"`          // Screen UV coordinate for current pixel.
	Point             vec2.XY                      `gd:"POINT_COORD"`        // Coordinate for drawing points.
	SpecularShininess vec4.XYZW                    `gd:"SPECULAR_SHININESS"` // Specular shininess, as set in the object's texture.
}

type MaterialSDF

type MaterialSDF struct{}

func (MaterialSDF) Texture

func (mat MaterialSDF) Texture(pos vec2.XY) float.X

func (MaterialSDF) TextureNormal

func (mat MaterialSDF) TextureNormal(pos vec2.XY) vec3.XYZ

type Program

type Program[V, F, M any] interface {
	Super() ShaderMaterial.Instance

	Fragment(V) F
	Material(F) M
	Lighting(M) vec4.RGBA
	// contains filtered or unexported methods
}

type RenderingOption2D

type RenderingOption2D xyz.Switch[string, struct {
	BlendingModeMix            RenderingOption2D `json:"blend_mix"`             // Mix blend mode (alpha is transparency), default.
	BlendingModeAdd            RenderingOption2D `json:"blend_add"`             // Additive blend mode.
	BlendingModeSub            RenderingOption2D `json:"blend_sub"`             // Subtractive blend mode.
	BlendingModeMul            RenderingOption2D `json:"blend_mul"`             // Multiplicative blend mode.
	BlendingPremultipliedAlpha RenderingOption2D `json:"blend_premul_alpha"`    // Pre-multiplied alpha blend mode.
	BlendingDisabled           RenderingOption2D `json:"blend_disabled"`        // Disable blending, values (including alpha) are written as-is.
	Unshaded                   RenderingOption2D `json:"unshaded"`              // Result is just albedo. No lighting/shading happens in material.
	LightOnly                  RenderingOption2D `json:"light_only"`            // Only draw on light pass.
	SkipVertexTransform        RenderingOption2D `json:"skip_vertex_transform"` // VERTEX needs to be transformed manually in vertex function.
	WorldVertexCoordinates     RenderingOption2D `json:"world_vertex_coords"`   // VERTEX is modified in world coordinates instead of local.
}]

type Type2D

type Type2D struct {
	classdb.Extension[goShader, ShaderMaterial.Instance]
}

func (Type2D) Fragment

func (Type2D) Fragment(vertix Vertex2D) Fragment2D

func (Type2D) Lighting

func (Type2D) Lighting(material Material2D) vec4.RGBA

func (Type2D) Material

func (Type2D) Material(fragment Fragment2D) Material2D

type Type3D

type Type3D struct {
	classdb.Extension[goShader, ShaderMaterial.Instance]
}

type Vertex2D

type Vertex2D struct {
	Globals

	// Local space to world space transform. World space is the coordinates you normally use in the editor.
	ModelMatrix mat4.ColumnMajor `gd:"MODEL_MATRIX"`
	// World space to canvas space transform. In canvas space the origin is the upper-left corner of the
	// screen and coordinates ranging from (0, 0) to viewport size.
	CanvasMatrix mat4.ColumnMajor `gd:"CANVAS_MATRIX"`
	// Canvas space to clip space. In clip space coordinates ranging from (-1, -1) to (1, 1).
	ScreenMatrix mat4.ColumnMajor `gd:"SCREEN_MATRIX"`

	InstanceID     int.X     `gd:"INSTANCE_ID"`     // InstanceID for instancing.
	InstanceCustom vec4.XYZW `gd:"INSTANCE_CUSTOM"` // InstanceCustom data.
	AtLightPass    bool.X    `gd:"AT_LIGHT_PASS"`   // Always false.

	// Normalized pixel size of default 2D texture. For a Sprite2D with a texture of size 64x32px,
	// TEXTURE_PIXEL_SIZE = vec2(1/64, 1/32)
	TexturePixelSize vec2.XY `gd:"TEXTURE_PIXEL_SIZE"`

	Position vec2.XY `gd:"VERTEX"`    // Vertex, in local space.
	ID       float.X `gd:"VERTEX_ID"` // The index of the current vertex in the vertex buffer.

	UV        vec2.XY   `gd:"UV"`         // Normalized texture coordinates. Range from 0 to 1.
	Color     vec4.RGBA `gd:"COLOR"`      // Color from vertex primitive.
	PointSize float.X   `gd:"POINT_SIZE"` // Point size for point drawing.
	Custom0   vec4.XYZW `gd:"CUSTOM0"`    // Custom value from vertex primitive.
	Custom1   vec4.XYZW `gd:"CUSTOM1"`    // Custom value from vertex primitive.
}