Documentation
¶
Overview ¶
A package that makes it easy to execute shaders with very little setup. Here's a basic example:
package main
import "github.com/tinne26/kage-desk/display"
func main() {
display.SetTitle("basic-shader")
display.SetSize(512, 512)
display.Shader() // will look for a .kage file in the local directory
}
Here's a slightly more advanced example:
package main
import _ "embed"
import "github.com/hajimehoshi/ebiten/v2"
import "github.com/tinne26/kage-desk/display"
//go:embed shader.kage
var shader []byte
func main() {
display.SetTitle("nice-shader")
display.SetSize(512, 512, display.Resizable, display.HiRes)
display.SetBackColor(display.BCJade) // set a background color
display.LinkUniformKey("Mode", 1, ebiten.KeyDigit1, ebiten.KeyNumpad1)
display.LinkUniformKey("Mode", 2, ebiten.KeyDigit2, ebiten.KeyNumpad2)
display.SetUniformInfo("Mode", "%d")
display.Shader(shader) // shader program passed explicitly
}
In this example we have embedded the shader explicitly (great for WASM and single executable builds), made the screen resizable, made the game layout take device scaling into account, defined keys 1 and 2 to change a uniform named "Mode" and configured the program to show the value of that new uniform in screen with SetUniformInfo().
You also get some additional uniforms, images, vertex colors and shortcuts for free; please refer to Shader() for more details on all that.
Finally, the package also detects some flags like '--maxfps' (unlimit fps and display them on the title), '--fullscreen' and '--opengl' (Windows would use DirectX by default otherwise).
Index ¶
- Constants
- Variables
- func DrawShader(screen *ebiten.Image, rect image.Rectangle, shader *ebiten.Shader, ...)
- func Image(img image.Image)
- func ImageSpiderCatDog() *ebiten.Image
- func ImageWaterfall() *ebiten.Image
- func LinkShaderImage(n int, image *ebiten.Image)
- func LinkUniformKey(name string, value any, keys ...ebiten.Key)
- func PositionRectVertices(vertices *[4]ebiten.Vertex, sxl, sxr, syt, syb, dxl, dxr, dyt, dyb float32)
- func RGB(r, g, b uint8) color.RGBA
- func RGBA(r, g, b, a uint8) color.RGBA
- func RectToF32(rect image.Rectangle) (xl, xr, yt, yb float32)
- func RectToUniform(rect image.Rectangle) []float32
- func SetBackColor(backColor color.RGBA)
- func SetSize(width, height int, options ...WindowOption)
- func SetTitle(title string)
- func SetUniformFmt(name string, formatter func(any) string)
- func SetUniformInfo(name, verb string, infos ...string)
- func Shader(args ...any)
- func StrFn(str string) func(any) string
- type WindowOption
Constants ¶
const (
MaxFPS debugMode = 0b0001
)
Variables ¶
var ( BCBlack = color.RGBA{0, 0, 0, 255} BCDark = color.RGBA{12, 20, 18, 255} // dark but not black BCWhite = color.RGBA{255, 255, 255, 255} BCGray = color.RGBA{128, 128, 128, 255} BCBronze = color.RGBA{192, 128, 64, 255} // a bit of everything BCOrchid = color.RGBA{128, 64, 192, 255} // a bit of everything BCJade = color.RGBA{8, 162, 116, 255} // a bit of everything BCRed = color.RGBA{255, 0, 0, 255} BCGreen = color.RGBA{0, 255, 0, 255} BCMagenta = color.RGBA{255, 0, 255, 255} BCCyan = color.RGBA{0, 255, 255, 255} )
Predefined background colors, to make life easier.
Functions ¶
func DrawShader ¶
func DrawShader(screen *ebiten.Image, rect image.Rectangle, shader *ebiten.Shader, opts *ebiten.DrawTrianglesShaderOptions)
Similar to ebiten.DrawRectShader, but the options are ebiten.DrawTrianglesShaderOptions and the size of the destination rect can be different from the images from the options. When this happens, the textures will be stretched to fill the whole shader rectangle.
In general, though, if the shader's target rectangle and the image sizes are different, you should compute the texture coordinates on your own.
func Image ¶
Similar concept to Shader(), but for single images. You can press 'E' at any time to export the image as a file too.
func ImageSpiderCatDog ¶
func ImageSpiderCatDog() *ebiten.Image
The source 0 image used for Shader(). You can access it manually too. 384x384.
func ImageWaterfall ¶
func ImageWaterfall() *ebiten.Image
The source 1 image used for Shader(). You can access it manually too. 512x512.
func LinkShaderImage ¶
func LinkShaderImage(n int, image *ebiten.Image)
Links a specific image for use with shaders. The given n can only be 0, 1, 2 or 3.
By default, two sample textures are already linked for images 0 and 1 (see ImageSpiderCatDog() and ImageWaterfall()). You can override them with your own or restore them by setting their values back to nil.
func LinkUniformKey ¶
Links a uniform in the following manner: when 'key' is triggered, 'value' is set for uniform 'name'. If the uniform hadn't been linked yet, the value will also be set as the starting value.
func PositionRectVertices ¶
func PositionRectVertices(vertices *[4]ebiten.Vertex, sxl, sxr, syt, syb, dxl, dxr, dyt, dyb float32)
Given 4 vertices and source x left, right, y top, bottom and dest x left, right, y top and bottom coordinates, assigns them to vertices 0 (top-left), 1 (top-right), 2 (bottom-left), 3 (bottom-right).
func RGB ¶
Creates a fully opaque color.RGBA from the given values.
func RectToF32 ¶
Given an image.Rectangle, returns the min and max x and min and max y coordinates as float32 values, in this order.
func RectToUniform ¶
Converts an image.Rectangle to a []float32 for use as a shader uniform.
The []float32 always has 4 values: min x, min y, max x, max y.
func SetBackColor ¶
Sets a background color to use on the canvas.
func SetSize ¶
func SetSize(width, height int, options ...WindowOption)
Sets the logical layout size you want to work with. Common options include Resizable and HiRes.
func SetTitle ¶
func SetTitle(title string)
Sets a window title. Fairly equivalent to ebiten.SetWindowTitle(), but also stores the title internally in case you pass the --maxfps tag, which will display the FPS on the title bar in addition to the title.
func SetUniformFmt ¶
Similar to SetUniformInfo(), but with a fully customizable formatter. For fixed strings, you may rely on StrFn().
func SetUniformInfo ¶
Allows displaying additional information for a given uniform. You can pass up to three strings. If you don't pass any, the information will be displayed as "UniformName: {value}". The first string you can pass will be used as a prefix, the second as a suffix, and the third would replace the original "UniformName: " completely. For example, ("Mode", "%d", "[", "]") would result in "[Mode: 0]", while ("Cursor", "%vec2[0]", "", "(move cursor)", "X: ") would result in something like "X: 0.14 (move cursor)".
By default, no info is shown.
Example setup in combination with LinkUniformKey():
display.LinkUniformKey("Mode", 1, ebiten.KeyDigit1, ebiten.KeyNumpad1)
display.LinkUniformKey("Mode", 2, ebiten.KeyDigit2, ebiten.KeyNumpad2)
display.LinkUniformKey("Mode", 3, ebiten.KeyDigit3, ebiten.KeyNumpad3)
display.SetUniformInfo("Mode", "%d", "", " [change with 1, 2, 3]")
There are some additional special verbs for ease of use: "%vec2", "%vec3", "%vec4", "%ivec2", "%ivec4", "%RGB8", "%rgb", "%RGBA8", "%rgba", "%percent", "%vec2-percent", "%vec2[0]", "%vec2[1]", "%hide". If none of these are enough, see SetUniformFmt().
func Shader ¶
func Shader(args ...any)
Loads and executes a shader. The shader might be explicitly given as a string or byte slice; otherwise, the method will try to search on the current directory for a relevant .kage file.
The shaders have a few functionalities built-in:
- Multiple uniforms are given by default. This includes 'Time float', 'Cursor vec2' (in [0, 1] normalized coordinates), 'MouseButtons int' (0b00 if none, 0b10 if left, 0b01 if right, 0b11 if both).
- Sample textures are linked to Images[0] and Images[1] if image usage is detected. You can also LinkShaderImage() on your own.
Types ¶
type WindowOption ¶
type WindowOption uint8
const ( Windowed WindowOption = 0b0001 Fullscreen WindowOption = 0b0010 Resizable WindowOption = 0b0100 DisplayScaling WindowOption = 0b1000 HiRes WindowOption = 0b1000 // better name than DisplayScaling )
Source Files