ebiten

README

Ebiten

A dead simple 2D game library in Go

Ebiten is an open-source game library, with which you can develop 2D games with simple API for multi platforms in the Go programming language.

• Website (ebiten.org)
• Cheat Sheet

Platforms

• Windows (No Cgo!)
• macOS
• Linux
• FreeBSD
• Android
• iOS
• Web browsers (Chrome, Firefox, Safari and Edge)
  • GopherJS
  • WebAssembly (Experimental)

Note: Gamepad and keyboard are not available on Android/iOS.

For installation on desktops, see the installation instruction.

Features

• 2D Graphics (Geometry/Color matrix transformation, Various composition modes, Offscreen rendering, Fullscreen, Text rendering, Automatic batches, Automatic texture atlas)
• Input (Mouse, Keyboard, Gamepads, Touches)
• Audio (Ogg/Vorbis, MP3, WAV, PCM)

Packages

• ebiten
  • audio
    • mp3
    • vorbis
    • wav
  • ebitenutil
  • inpututil
  • mobile
  • text

Community

Slack

#ebiten channel in Gophers Slack

License

Ebiten is licensed under Apache license version 2.0. See LICENSE file.

Documentation

Overview

Package ebiten provides graphics and input API to develop a 2D game.

You can start the game by calling the function Run.

// update is called every frame (1/60 [s]).
func update(screen *ebiten.Image) error {

    // Write your game's logical update.

    if ebiten.IsDrawingSkipped() {
        // When the game is running slowly, the rendering result
        // will not be adopted.
        return nil
    }

    // Write your game's rendering.

    return nil
}

func main() {
    // Call ebiten.Run to start your game loop.
    if err := ebiten.Run(update, 320, 240, 2, "Your game's title"); err != nil {
        log.Fatal(err)
    }
}

The EBITEN_SCREENSHOT_KEY environment variable specifies the key to take a screenshot. For example, if you run your game with `EBITEN_SCREENSHOT_KEY=q`, you can take a game screen's screenshot by pressing Q key. This works only on desktops.

The EBITEN_INTERNAL_IMAGES_KEY environment variable specifies the key to dump all the internal images. This is valid only when the build tag 'ebitendebug' is specified. This works only on desktops.

In the API document, 'the main thread' means the goroutine in init(), main() and their callees without 'go' statement. It is assured that 'the main thread' runs on the OS main thread. There are some Ebiten functions that must be called on the main thread under some conditions (typically, before ebiten.Run is called).

Index

• Constants
• Variables
• func CurrentFPS() float64
• func CurrentTPS() float64
• func CursorPosition() (x, y int)
• func DeviceScaleFactor() float64
• func GamepadAxis(id int, axis int) float64
• func GamepadAxisNum(id int) int
• func GamepadButtonNum(id int) int
• func GamepadIDs() []int
• func InputChars() []rune
• func IsCursorVisible() bool
• func IsDrawingSkipped() bool
• func IsFullscreen() bool
• func IsGamepadButtonPressed(id int, button GamepadButton) bool
• func IsKeyPressed(key Key) bool
• func IsMouseButtonPressed(mouseButton MouseButton) bool
• func IsRunnableInBackground() bool
• func IsRunningSlowly() bool
• func IsVsyncEnabled() bool
• func IsWindowDecorated() bool
• func IsWindowResizable() bool
• func MaxTPS() int
• func MonitorSize() (int, int)
• func Run(f func(*Image) error, width, height int, scale float64, title string) error
• func RunWithoutMainLoop(f func(*Image) error, width, height int, scale float64, title string) <-chan error
• func ScreenScale() float64
• func ScreenSizeInFullscreen() (int, int)
• func SetCursorVisibility(visible bool)
• func SetCursorVisible(visible bool)
• func SetFullscreen(fullscreen bool)
• func SetMaxTPS(tps int)
• func SetRunnableInBackground(runnableInBackground bool)
• func SetScreenScale(scale float64)
• func SetScreenSize(width, height int)
• func SetVsyncEnabled(enabled bool)
• func SetWindowDecorated(decorated bool)
• func SetWindowIcon(iconImages []image.Image)
• func SetWindowTitle(title string)
• func TouchIDs() []int
• func TouchPosition(id int) (int, int)
• func Wheel() (xoff, yoff float64)
• type Address
• type ColorM
  • func Monochrome() ColorM
  • func RotateHue(theta float64) ColorM
  • func ScaleColor(r, g, b, a float64) ColorM
  • func TranslateColor(r, g, b, a float64) ColorM
  • func (c *ColorM) Add(other ColorM)
  • func (c *ColorM) Apply(clr color.Color) color.Color
  • func (c *ColorM) ChangeHSV(hueTheta float64, saturationScale float64, valueScale float64)
  • func (c *ColorM) Concat(other ColorM)
  • func (c *ColorM) Element(i, j int) float64
  • func (c *ColorM) Reset()
  • func (c *ColorM) RotateHue(theta float64)
  • func (c *ColorM) Scale(r, g, b, a float64)
  • func (c *ColorM) SetElement(i, j int, element float64)
  • func (c *ColorM) String() string
  • func (c *ColorM) Translate(r, g, b, a float64)
• type CompositeMode
• type DrawImageOptions
• type DrawTrianglesOptions
• type Filter
• type GamepadButton
• type GeoM
  • func RotateGeo(theta float64) GeoM
  • func ScaleGeo(x, y float64) GeoM
  • func TranslateGeo(tx, ty float64) GeoM
  • func (g *GeoM) Add(other GeoM)
  • func (g *GeoM) Apply(x, y float64) (float64, float64)
  • func (g *GeoM) Concat(other GeoM)
  • func (g *GeoM) Element(i, j int) float64
  • func (g *GeoM) Invert()
  • func (g *GeoM) IsInvertible() bool
  • func (g *GeoM) Reset()
  • func (g *GeoM) Rotate(theta float64)
  • func (g *GeoM) Scale(x, y float64)
  • func (g *GeoM) SetElement(i, j int, element float64)
  • func (g *GeoM) Skew(skewX, skewY float64)
  • func (g *GeoM) String() string
  • func (g *GeoM) Translate(tx, ty float64)
• type Image
  • func NewImage(width, height int, filter Filter) (*Image, error)
  • func NewImageFromImage(source image.Image, filter Filter) (*Image, error)
  • func (i *Image) At(x, y int) color.Color
  • func (i *Image) Bounds() image.Rectangle
  • func (i *Image) Clear() error
  • func (i *Image) ColorModel() color.Model
  • func (i *Image) Dispose() error
  • func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error
  • func (i *Image) DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)
  • func (i *Image) Fill(clr color.Color) error
  • func (i *Image) ReplacePixels(p []byte) error
  • func (img *Image) Set(x, y int, clr color.Color)
  • func (i *Image) Size() (width, height int)
  • func (i *Image) SubImage(r image.Rectangle) image.Image
• type ImagePart
• type ImageParts
• type Key
  • func (k Key) String() string
• type MouseButton
• type Touch
  • func Touches() []Touch
• type Vertex

Constants

const ColorMDim = affine.ColorMDim

ColorMDim is a dimension of a ColorM.

const DefaultTPS = 60

TPS represents a default ticks per second, that represents how many times game updating happens in a second.

const FPS = DefaultTPS

FPS is deprecated as of 1.8.0-alpha: Use DefaultTPS instead.

const GeoMDim = 3

GeoMDim is a dimension of a GeoM.

const MaxIndicesNum = graphics.IndicesNum

MaxIndicesNum is the maximum number of indices for DrawTriangles.

const UncappedTPS = clock.UncappedTPS

UncappedTPS is a special TPS value that means the game doesn't have limitation on TPS.

Variables

var MaxImageSize = 4096

MaxImageSize is deprecated as of 1.7.0-alpha. No replacement so far.

TODO: Make this replacement (#541)

Functions

func CurrentFPS

func CurrentFPS() float64

CurrentFPS returns the current number of FPS (frames per second), that represents how many swapping buffer happens per second.

On some environments, CurrentFPS doesn't return a reliable value since vsync doesn't work well there. If you want to measure the application's speed, Use CurrentTPS.

CurrentFPS is concurrent-safe.

func CurrentTPS

func CurrentTPS() float64

CurrentTPS returns the current TPS (ticks per second), that represents how many update function is called in a second.

CurrentTPS is concurrent-safe.

func CursorPosition

func CursorPosition() (x, y int)

CursorPosition returns a position of a mouse cursor relative to the game screen (window). The cursor position is 'logical' position and this considers the scale of the screen.

CursorPosition is concurrent-safe.

func DeviceScaleFactor

func DeviceScaleFactor() float64

DeviceScaleFactor returns a device scale factor value of the current monitor which the window belongs to.

DeviceScaleFactor returns a meaningful value on high-DPI display environment, otherwise DeviceScaleFactor returns 1.

DeviceScaleFactor might panic on init function on some devices like Android. Then, it is not recommended to call DeviceScaleFactor from init functions.

DeviceScaleFactor must be called on the main thread before ebiten.Run, and is concurrent-safe after ebiten.Run.

func GamepadAxis

func GamepadAxis(id int, axis int) float64

GamepadAxis returns the float value [-1.0 - 1.0] of the given gamepad (id)'s axis (axis).

GamepadAxis is concurrent-safe.

GamepadAxis always returns 0 on mobiles.

func GamepadAxisNum

func GamepadAxisNum(id int) int

GamepadAxisNum returns the number of axes of the gamepad (id).

GamepadAxisNum is concurrent-safe.

GamepadAxisNum always returns 0 on mobiles.

func GamepadButtonNum

func GamepadButtonNum(id int) int

GamepadButtonNum returns the number of the buttons of the given gamepad (id).

GamepadButtonNum is concurrent-safe.

GamepadButtonNum always returns 0 on mobiles.

func GamepadIDs

func GamepadIDs() []int

GamepadIDs returns a slice indicating available gamepad IDs.

GamepadIDs is concurrent-safe.

GamepadIDs always returns an empty slice on mobiles.

func InputChars

func InputChars() []rune

InputChars return "printable" runes read from the keyboard at the time update is called.

InputChars represents the environment's locale-dependent translation of keyboard input to Unicode characters.

IsKeyPressed is based on a mapping of device (US keyboard) codes to input device keys. "Control" and modifier keys should be handled with IsKeyPressed.

InputChars is concurrent-safe.

func IsCursorVisible

func IsCursorVisible() bool

IsCursorVisible returns a boolean value indicating whether the cursor is visible or not.

IsCursorVisible always returns false on mobiles.

IsCursorVisible is concurrent-safe.

func IsDrawingSkipped

func IsDrawingSkipped() bool

IsDrawingSkipped returns true if rendering result is not adopted. It is recommended to skip drawing images or screen when IsDrawingSkipped is true.

The typical code with IsDrawingSkipped is this:

func update(screen *ebiten.Image) error {

    // Update the state.

    // When IsDrawingSkipped is true, the rendered result is not adopted.
    // Skip rendering then.
    if ebiten.IsDrawingSkipped() {
        return nil
    }

    // Draw something to the screen.

    return nil
}

IsDrawingSkipped is concurrent-safe.

func IsFullscreen

func IsFullscreen() bool

IsFullscreen returns a boolean value indicating whether the current mode is fullscreen or not.

IsFullscreen always returns false on mobiles.

IsFullscreen is concurrent-safe.

func IsGamepadButtonPressed

func IsGamepadButtonPressed(id int, button GamepadButton) bool

IsGamepadButtonPressed returns the boolean indicating the given button of the gamepad (id) is pressed or not.

IsGamepadButtonPressed is concurrent-safe.

The relationships between physical buttons and buttion IDs depend on environments. There can be differences even between Chrome and Firefox.

IsGamepadButtonPressed always returns false on mobiles.

func IsKeyPressed

func IsKeyPressed(key Key) bool

IsKeyPressed returns a boolean indicating whether key is pressed.

Known issue: On Edge browser, some keys don't work well:

• KeyKPEnter and KeyKPEqual are recognized as KeyEnter and KeyEqual.
• KeyPrintScreen is only treated at keyup event.

IsKeyPressed is concurrent-safe.

func IsMouseButtonPressed

func IsMouseButtonPressed(mouseButton MouseButton) bool

IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.

IsMouseButtonPressed is concurrent-safe.

Note that touch events not longer affect IsMouseButtonPressed's result as of 1.4.0-alpha. Use Touches instead.

func IsRunnableInBackground

func IsRunnableInBackground() bool

IsRunnableInBackground returns a boolean value indicating whether the game runs even in background.

IsRunnableInBackground is concurrent-safe.

func IsRunningSlowly

func IsRunningSlowly() bool

IsRunningSlowly is deprecated as of 1.8.0-alpha. Use IsDrawingSkipped instead.

func IsVsyncEnabled

func IsVsyncEnabled() bool

IsVsyncEnabled returns a boolean value indicating whether the game uses the display's vsync.

IsVsyncEnabled is concurrent-safe.

func IsWindowDecorated

func IsWindowDecorated() bool

IsWindowDecorated reports whether the window is decorated.

IsWindowDecorated is concurrent-safe.

func IsWindowResizable

func IsWindowResizable() bool

IsWindowResizable reports whether the window is resizable.

IsWindowResizable is concurrent-safe.

func MaxTPS

func MaxTPS() int

MaxTPS returns the current maximum TPS.

MaxTPS is concurrent-safe.

func MonitorSize

func MonitorSize() (int, int)

MonitorSize is deprecated as of 1.8.0-alpha. Use ScreenSizeInFullscreen instead.

func Run

func Run(f func(*Image) error, width, height int, scale float64, title string) error

Run runs the game. f is a function which is called at every frame. The argument (*Image) is the render target that represents the screen. The screen size is based on the given values (width and height).

A window size is based on the given values (width, height and scale). scale is used to enlarge the screen. Note that the actual screen is multiplied not only by the given scale but also by the device scale on high-DPI display. If you pass inverse of the device scale, you can disable this automatical device scaling as a result. You can get the device scale by DeviceScaleFactor function.

Run must be called on the main thread. Note that Ebiten bounds the main goroutine to the main OS thread by runtime.LockOSThread.

Ebiten tries to call f 60 times a second by default. In other words, TPS (ticks per second) is 60 by default. This is not related to framerate (display's refresh rate).

f is not called when the window is in background by default. This setting is configurable with SetRunnableInBackground.

The given scale is ignored on fullscreen mode or gomobile-build mode.

On non-GopherJS environments, Run returns error when 1) OpenGL error happens, 2) audio error happens or 3) f returns error. In the case of 3), Run returns the same error.

On GopherJS, Run returns immediately. It is because the 'main' goroutine cannot be blocked on GopherJS due to the bug (gopherjs/gopherjs#826). When an error happens, this is shown as an error on the console.

The size unit is device-independent pixel.

Don't call Run twice or more in one process.

func RunWithoutMainLoop

func RunWithoutMainLoop(f func(*Image) error, width, height int, scale float64, title string) <-chan error

RunWithoutMainLoop runs the game, but don't call the loop on the main (UI) thread. Different from Run, RunWithoutMainLoop returns immediately.

Ebiten users should NOT call RunWithoutMainLoop. Instead, functions in github.com/hajimehoshi/ebiten/mobile package calls this.

func ScreenScale

func ScreenScale() float64

ScreenScale returns the current screen scale.

If Run is not called, this returns 0.

ScreenScale is concurrent-safe.

func ScreenSizeInFullscreen

func ScreenSizeInFullscreen() (int, int)

ScreenSizeInFullscreen returns the size in device-independent pixels when the game is fullscreen. The adopted monitor is the 'current' monitor which the window belongs to. The returned value can be given to Run or SetSize function if the perfectly fit fullscreen is needed.

On browsers, ScreenSizeInFullscreen returns the 'window' (global object) size, not 'screen' size since an Ebiten game should not know the outside of the window object. For more details, see SetFullscreen API comment.

On mobiles, ScreenSizeInFullscreen returns (0, 0) so far.

If you use this for screen size with SetFullscreen(true), you can get the fullscreen mode which size is well adjusted with the monitor.

w, h := ScreenSizeInFullscreen()
ebiten.SetFullscreen(true)
ebiten.Run(update, w, h, 1, "title")

Furthermore, you can use them with DeviceScaleFactor(), you can get the finest fullscreen mode.

s := ebiten.DeviceScaleFactor()
w, h := ScreenSizeInFullscreen()
ebiten.SetFullscreen(true)
ebiten.Run(update, int(float64(w) * s), int(float64(h) * s), 1/s, "title")

For actual example, see examples/fullscreen

ScreenSizeInFullscreen must be called on the main thread before ebiten.Run, and is concurrent-safe after ebiten.Run.

func SetCursorVisibility

func SetCursorVisibility(visible bool)

SetCursorVisibility is deprecated as of 1.6.0-alpha. Use SetCursorVisible instead.

func SetCursorVisible

func SetCursorVisible(visible bool)

SetCursorVisible changes the state of cursor visiblity.

SetCursorVisible does nothing on mobiles.

SetCursorVisible is concurrent-safe.

func SetFullscreen

func SetFullscreen(fullscreen bool)

SetFullscreen changes the current mode to fullscreen or not.

On fullscreen mode, the game screen is automatically enlarged to fit with the monitor. The current scale value is ignored.

On desktops, Ebiten uses 'windowed' fullscreen mode, which doesn't change your monitor's resolution.

On browsers, the game screen is resized to fit with the body element (client) size. Additionally, the game screen is automatically resized when the body element is resized. Note that this has nothing to do with 'screen' which is outside of 'window'. It is recommended to put Ebiten game in an iframe, and if you want to make the game 'fullscreen' on browsers with Fullscreen API, you can do this by applying the API to the iframe.

SetFullscreen does nothing on mobiles.

SetFullscreen is concurrent-safe.

func SetMaxTPS

func SetMaxTPS(tps int)

SetMaxTPS sets the maximum TPS (ticks per second), that represents how many updating function is called per second. The initial value is 60.

If tps is UncappedTPS, TPS is uncapped and the game is updated per frame. If tps is negative but not UncappedTPS, SetMaxTPS panics.

SetMaxTPS is concurrent-safe.

func SetRunnableInBackground

func SetRunnableInBackground(runnableInBackground bool)

SetRunnableInBackground sets the state if the game runs even in background.

If the given value is true, the game runs in background e.g. when losing focus. The initial state is false.

Known issue: On browsers, even if the state is on, the game doesn't run in background tabs. This is because browsers throttles background tabs not to often update.

SetRunnableInBackground does nothing on mobiles so far.

SetRunnableInBackground is concurrent-safe.

func SetScreenScale

func SetScreenScale(scale float64)

SetScreenScale changes the scale of the screen.

Note that the actual screen is multiplied not only by the given scale but also by the device scale on high-DPI display. If you pass inverse of the device scale, you can disable this automatical device scaling as a result. You can get the device scale by DeviceScaleFactor function.

SetScreenScale is concurrent-safe.

func SetScreenSize

func SetScreenSize(width, height int)

SetScreenSize changes the (logical) size of the screen. This doesn't affect the current scale of the screen.

Unit is device-independent pixel.

SetScreenSize is concurrent-safe.

func SetVsyncEnabled

func SetVsyncEnabled(enabled bool)

SetVsyncEnabled sets a boolean value indicating whether the game uses the display's vsync.

If the given value is true, the game tries to sync the display's refresh rate. If false, the game ignores the display's refresh rate. The initial value is true. By disabling vsync, the game works more efficiently but consumes more CPU.

Note that the state doesn't affect TPS (ticks per second, i.e. how many the run function is updated per second).

SetVsyncEnabled does nothing on mobiles so far.

SetVsyncEnabled is concurrent-safe.

func SetWindowDecorated

func SetWindowDecorated(decorated bool)

SetWindowDecorated sets the state if the window is decorated.

The window is decorated by default.

SetWindowDecorated works only on desktops. SetWindowDecorated does nothing on other platforms.

SetWindowDecorated panics if SetWindowDecorated is called after Run.

SetWindowDecorated is concurrent-safe.

func SetWindowIcon

func SetWindowIcon(iconImages []image.Image)

SetWindowIcon sets the icon of the game window.

If len(iconImages) is 0, SetWindowIcon reverts the icon to the default one.

For desktops, see the document of glfwSetWindowIcon of GLFW 3.2:

This function sets the icon of the specified window.
If passed an array of candidate images, those of or closest to the sizes
desired by the system are selected.
If no images are specified, the window reverts to its default icon.

The desired image sizes varies depending on platform and system settings.
The selected images will be rescaled as needed.
Good sizes include 16x16, 32x32 and 48x48.

As macOS windows don't have icons, SetWindowIcon doesn't work on macOS.

SetWindowIcon doesn't work on browsers or mobiles.

SetWindowIcon is concurrent-safe.

func SetWindowTitle

func SetWindowTitle(title string)

SetWindowTitle sets the title of the window.

SetWindowTitle does nothing on mobiles.

SetWindowTitle is concurrent-safe.

func TouchIDs

func TouchIDs() []int

TouchIDs returns the current touch states.

TouchIDs returns nil when there are no touches. TouchIDs always returns nil on desktops.

TouchIDs is concurrent-safe.

func TouchPosition

func TouchPosition(id int) (int, int)

TouchPosition returns the position for the touch of the specified ID.

If the touch of the specified ID is not present, TouchPosition returns (0, 0).

TouchPosition is cuncurrent-safe.

func Wheel

func Wheel() (xoff, yoff float64)

Wheel returns the x and y offset of the mouse wheel or touchpad scroll. It returns 0 if the wheel isn't being rolled.

Wheel is concurrent-safe.

Types

type Address

type Address int

Address represents a sampler address mode.

const (
	// AddressClampToZero means that out-of-range texture coordinates return 0 (transparent).
	AddressClampToZero Address = Address(driver.AddressClampToZero)

	// AddressRepeat means that texture coordinates wrap to the other side of the texture.
	AddressRepeat Address = Address(driver.AddressRepeat)
)

type ColorM

type ColorM struct {
	// contains filtered or unexported fields
}

A ColorM represents a matrix to transform coloring when rendering an image.

A ColorM is applied to the straight alpha color while an Image's pixels' format is alpha premultiplied. Before applying a matrix, a color is un-multiplied, and after applying the matrix, the color is multiplied again.

The initial value is identity.

func Monochrome

func Monochrome() ColorM

Monochrome is deprecated as of 1.6.0-alpha. Use ChangeHSV(0, 0, 1) instead.

func RotateHue

func RotateHue(theta float64) ColorM

RotateHue is deprecated as of 1.2.0-alpha. Use RotateHue member function instead.

func ScaleColor

func ScaleColor(r, g, b, a float64) ColorM

ScaleColor is deprecated as of 1.2.0-alpha. Use Scale instead.

func TranslateColor

func TranslateColor(r, g, b, a float64) ColorM

TranslateColor is deprecated as of 1.2.0-alpha. Use Translate instead.

func (*ColorM) Add

func (c *ColorM) Add(other ColorM)

Add is deprecated as of 1.5.0-alpha. Note that this doesn't make sense as an operation for affine matrices.

func (*ColorM) Apply

func (c *ColorM) Apply(clr color.Color) color.Color

Apply pre-multiplies a vector (r, g, b, a, 1) by the matrix where r, g, b, and a are clr's values in straight-alpha format. In other words, Apply calculates ColorM * (r, g, b, a, 1)^T.

func (*ColorM) ChangeHSV

func (c *ColorM) ChangeHSV(hueTheta float64, saturationScale float64, valueScale float64)

ChangeHSV changes HSV (Hue-Saturation-Value) values. hueTheta is a radian value to rotate hue. saturationScale is a value to scale saturation. valueScale is a value to scale value (a.k.a. brightness).

This conversion uses RGB to/from YCrCb conversion.

func (*ColorM) Concat

func (c *ColorM) Concat(other ColorM)

Concat multiplies a color matrix with the other color matrix. This is same as muptiplying the matrix other and the matrix c in this order.

func (*ColorM) Element

func (c *ColorM) Element(i, j int) float64

Element returns a value of a matrix at (i, j).

func (*ColorM) Reset

func (c *ColorM) Reset()

Reset resets the ColorM as identity.

func (*ColorM) RotateHue

func (c *ColorM) RotateHue(theta float64)

RotateHue rotates the hue. theta represents rotating angle in radian.

func (*ColorM) Scale

func (c *ColorM) Scale(r, g, b, a float64)

Scale scales the matrix by (r, g, b, a).

func (*ColorM) SetElement

func (c *ColorM) SetElement(i, j int, element float64)

SetElement sets an element at (i, j).

func (*ColorM) String

func (c *ColorM) String() string

String returns a string representation of ColorM.

func (*ColorM) Translate

func (c *ColorM) Translate(r, g, b, a float64)

Translate translates the matrix by (r, g, b, a).

type CompositeMode

type CompositeMode int

CompositeMode represents Porter-Duff composition mode.

const (
	// Regular alpha blending
	// c_out = c_src + c_dst × (1 - α_src)
	CompositeModeSourceOver CompositeMode = CompositeMode(driver.CompositeModeSourceOver)

	// c_out = 0
	CompositeModeClear CompositeMode = CompositeMode(driver.CompositeModeClear)

	// c_out = c_src
	CompositeModeCopy CompositeMode = CompositeMode(driver.CompositeModeCopy)

	// c_out = c_dst
	CompositeModeDestination CompositeMode = CompositeMode(driver.CompositeModeDestination)

	// c_out = c_src × (1 - α_dst) + c_dst
	CompositeModeDestinationOver CompositeMode = CompositeMode(driver.CompositeModeDestinationOver)

	// c_out = c_src × α_dst
	CompositeModeSourceIn CompositeMode = CompositeMode(driver.CompositeModeSourceIn)

	// c_out = c_dst × α_src
	CompositeModeDestinationIn CompositeMode = CompositeMode(driver.CompositeModeDestinationIn)

	// c_out = c_src × (1 - α_dst)
	CompositeModeSourceOut CompositeMode = CompositeMode(driver.CompositeModeSourceOut)

	// c_out = c_dst × (1 - α_src)
	CompositeModeDestinationOut CompositeMode = CompositeMode(driver.CompositeModeDestinationOut)

	// c_out = c_src × α_dst + c_dst × (1 - α_src)
	CompositeModeSourceAtop CompositeMode = CompositeMode(driver.CompositeModeSourceAtop)

	// c_out = c_src × (1 - α_dst) + c_dst × α_src
	CompositeModeDestinationAtop CompositeMode = CompositeMode(driver.CompositeModeDestinationAtop)

	// c_out = c_src × (1 - α_dst) + c_dst × (1 - α_src)
	CompositeModeXor CompositeMode = CompositeMode(driver.CompositeModeXor)

	// Sum of source and destination (a.k.a. 'plus' or 'additive')
	// c_out = c_src + c_dst
	CompositeModeLighter CompositeMode = CompositeMode(driver.CompositeModeLighter)
)

This name convention follows CSS compositing: https://drafts.fxtf.org/compositing-2/.

In the comments, c_src, c_dst and c_out represent alpha-premultiplied RGB values of source, destination and output respectively. α_src and α_dst represent alpha values of source and destination respectively.

type DrawImageOptions

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

	// ColorM is a color matrix to draw.
	// The default (zero) value is identity, which doesn't change any color.
	ColorM ColorM

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

	// Filter is a type of texture filter.
	// The default (zero) value is FilterDefault.
	//
	// Filter can also be specified at NewImage* functions, but
	// specifying filter at DrawImageOptions is recommended (as of 1.7.0-alpha).
	//
	// If both Filter specified at NewImage* and DrawImageOptions are FilterDefault,
	// FilterNearest is used.
	// If either is FilterDefault and the other is not, the latter is used.
	// Otherwise, Filter specified at DrawImageOptions is used.
	Filter Filter

	// Deprecated (as of 1.5.0-alpha): Use SubImage instead.
	ImageParts ImageParts

	// Deprecated (as of 1.1.0-alpha): Use SubImage instead.
	Parts []ImagePart

	// Deprecated (as of 1.9.0-alpha): Use SubImage instead.
	SourceRect *image.Rectangle
}

A DrawImageOptions represents options to render an image on an image.

type DrawTrianglesOptions

type DrawTrianglesOptions struct {
	// ColorM is a color matrix to draw.
	// The default (zero) value is identity, which doesn't change any color.
	// ColorM is applied before vertex color scale is applied.
	ColorM ColorM

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

	// Filter is a type of texture filter.
	// The default (zero) value is FilterDefault.
	Filter Filter

	// Address is a sampler address mode.
	// The default (zero) value is AddressClampToZero.
	Address Address
}

DrawTrianglesOptions represents options to render triangles on an image.

Note that this API is experimental.

type Filter

type Filter int

Filter represents the type of texture filter to be used when an image is maginified or minified.

const (
	// FilterDefault represents the default filter.
	FilterDefault Filter = 0

	// FilterNearest represents nearest (crisp-edged) filter
	FilterNearest Filter = Filter(driver.FilterNearest)

	// FilterLinear represents linear filter
	FilterLinear Filter = Filter(driver.FilterLinear)
)

type GamepadButton

type GamepadButton int

A GamepadButton represents a gamepad button.

const (
	GamepadButton0   GamepadButton = GamepadButton(driver.GamepadButton0)
	GamepadButton1   GamepadButton = GamepadButton(driver.GamepadButton1)
	GamepadButton2   GamepadButton = GamepadButton(driver.GamepadButton2)
	GamepadButton3   GamepadButton = GamepadButton(driver.GamepadButton3)
	GamepadButton4   GamepadButton = GamepadButton(driver.GamepadButton4)
	GamepadButton5   GamepadButton = GamepadButton(driver.GamepadButton5)
	GamepadButton6   GamepadButton = GamepadButton(driver.GamepadButton6)
	GamepadButton7   GamepadButton = GamepadButton(driver.GamepadButton7)
	GamepadButton8   GamepadButton = GamepadButton(driver.GamepadButton8)
	GamepadButton9   GamepadButton = GamepadButton(driver.GamepadButton9)
	GamepadButton10  GamepadButton = GamepadButton(driver.GamepadButton10)
	GamepadButton11  GamepadButton = GamepadButton(driver.GamepadButton11)
	GamepadButton12  GamepadButton = GamepadButton(driver.GamepadButton12)
	GamepadButton13  GamepadButton = GamepadButton(driver.GamepadButton13)
	GamepadButton14  GamepadButton = GamepadButton(driver.GamepadButton14)
	GamepadButton15  GamepadButton = GamepadButton(driver.GamepadButton15)
	GamepadButton16  GamepadButton = GamepadButton(driver.GamepadButton16)
	GamepadButton17  GamepadButton = GamepadButton(driver.GamepadButton17)
	GamepadButton18  GamepadButton = GamepadButton(driver.GamepadButton18)
	GamepadButton19  GamepadButton = GamepadButton(driver.GamepadButton19)
	GamepadButton20  GamepadButton = GamepadButton(driver.GamepadButton20)
	GamepadButton21  GamepadButton = GamepadButton(driver.GamepadButton21)
	GamepadButton22  GamepadButton = GamepadButton(driver.GamepadButton22)
	GamepadButton23  GamepadButton = GamepadButton(driver.GamepadButton23)
	GamepadButton24  GamepadButton = GamepadButton(driver.GamepadButton24)
	GamepadButton25  GamepadButton = GamepadButton(driver.GamepadButton25)
	GamepadButton26  GamepadButton = GamepadButton(driver.GamepadButton26)
	GamepadButton27  GamepadButton = GamepadButton(driver.GamepadButton27)
	GamepadButton28  GamepadButton = GamepadButton(driver.GamepadButton28)
	GamepadButton29  GamepadButton = GamepadButton(driver.GamepadButton29)
	GamepadButton30  GamepadButton = GamepadButton(driver.GamepadButton30)
	GamepadButton31  GamepadButton = GamepadButton(driver.GamepadButton31)
	GamepadButtonMax GamepadButton = GamepadButton31
)

GamepadButtons

type GeoM

type GeoM struct {
	// contains filtered or unexported fields
}

A GeoM represents a matrix to transform geometry when rendering an image.

The initial value is identity.

func RotateGeo

func RotateGeo(theta float64) GeoM

RotateGeo is deprecated as of 1.2.0-alpha. Use Rotate instead.

func ScaleGeo

func ScaleGeo(x, y float64) GeoM

ScaleGeo is deprecated as of 1.2.0-alpha. Use Scale instead.

func TranslateGeo

func TranslateGeo(tx, ty float64) GeoM

TranslateGeo is deprecated as of 1.2.0-alpha. Use Translate instead.

func (*GeoM) Add

func (g *GeoM) Add(other GeoM)

Add is deprecated as of 1.5.0-alpha. Note that this doesn't make sense as an operation for affine matrices.

func (*GeoM) Apply

func (g *GeoM) Apply(x, y float64) (float64, float64)

Apply pre-multiplies a vector (x, y, 1) by the matrix. In other words, Apply calculates GeoM * (x, y, 1)^T. The return value is x and y values of the result vector.

func (*GeoM) Concat

func (g *GeoM) Concat(other GeoM)

Concat multiplies a geometry matrix with the other geometry matrix. This is same as muptiplying the matrix other and the matrix g in this order.

func (*GeoM) Element

func (g *GeoM) Element(i, j int) float64

Element returns a value of a matrix at (i, j).

func (*GeoM) Invert

func (g *GeoM) Invert()

Invert inverts the matrix. If g is not invertible, Invert panics.

func (*GeoM) IsInvertible

func (g *GeoM) IsInvertible() bool

IsInvertible returns a boolean value indicating whether the matrix g is invertible or not.

func (*GeoM) Reset

func (g *GeoM) Reset()

Reset resets the GeoM as identity.

func (*GeoM) Rotate

func (g *GeoM) Rotate(theta float64)

Rotate rotates the matrix by theta. The unit is radian.

func (*GeoM) Scale

func (g *GeoM) Scale(x, y float64)

Scale scales the matrix by (x, y).

func (*GeoM) SetElement

func (g *GeoM) SetElement(i, j int, element float64)

SetElement sets an element at (i, j).

func (*GeoM) Skew

func (g *GeoM) Skew(skewX, skewY float64)

Skew skews the matrix by (skewX, skewY). The unit is radian.

func (*GeoM) String

func (g *GeoM) String() string

String returns a string representation of GeoM.

func (*GeoM) Translate

func (g *GeoM) Translate(tx, ty float64)

Translate translates the matrix by (tx, ty).

type Image

type Image struct {
	// contains filtered or unexported fields
}

Image represents a rectangle set of pixels. The pixel format is alpha-premultiplied RGBA. Image implements image.Image and draw.Image.

Functions of Image never returns error as of 1.5.0-alpha, and error values are always nil.

func NewImage

func NewImage(width, height int, filter Filter) (*Image, error)

NewImage returns an empty image.

If width or height is less than 1 or more than device-dependent maximum size, NewImage panics.

filter argument is just for backward compatibility. If you are not sure, specify FilterDefault.

Error returned by NewImage is always nil as of 1.5.0-alpha.

func NewImageFromImage

func NewImageFromImage(source image.Image, filter Filter) (*Image, error)

NewImageFromImage creates a new image with the given image (source).

If source's width or height is less than 1 or more than device-dependent maximum size, NewImageFromImage panics.

filter argument is just for backward compatibility. If you are not sure, specify FilterDefault.

Error returned by NewImageFromImage is always nil as of 1.5.0-alpha.

func (*Image) At

func (i *Image) At(x, y int) color.Color

At returns the color of the image at (x, y).

At loads pixels from GPU to system memory if necessary, which means that At can be slow.

At always returns a transparent color if the image is disposed.

Note that important logic should not rely on values returned by At, since the returned values can include very slight differences between some machines.

At can't be called outside the main loop (ebiten.Run's updating function) starts (as of version 1.4.0-alpha).

func (*Image) Bounds

func (i *Image) Bounds() image.Rectangle

Bounds returns the bounds of the image.

func (*Image) Clear

func (i *Image) Clear() error

Clear resets the pixels of the image into 0.

When the image is disposed, Clear does nothing.

Clear always returns nil as of 1.5.0-alpha.

func (*Image) ColorModel

func (i *Image) ColorModel() color.Model

ColorModel returns the color model of the image.

func (*Image) Dispose

func (i *Image) Dispose() error

Dispose disposes the image data. After disposing, most of image functions do nothing and returns meaningless values.

Calling Dispose is not mandatory. GC automatically collects internal resources that no objects refer to. However, calling Dispose explicitly is helpful if memory usage matters.

When the image is disposed, Dipose does nothing.

Dipose always return nil as of 1.5.0-alpha.

func (*Image) DrawImage

func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error

DrawImage draws the given image on the image i.

DrawImage accepts the options. For details, see the document of DrawImageOptions.

For drawing, the pixels of the argument image at the time of this call is adopted. Even if the argument image is mutated after this call, the drawing result is never affected.

When the image i is disposed, DrawImage does nothing. When the given image img is disposed, DrawImage panics.

When the given image is as same as i, DrawImage panics.

DrawImage works more efficiently as batches when the successive calls of DrawImages satisfy the below conditions:

• All render targets are same (A in A.DrawImage(B, op))
• Either all ColorM element values are same or all the ColorM have only diagonal ('scale') elements
• If only (*ColorM).Scale is applied to a ColorM, the ColorM has only diagonal elements. The other ColorM functions might modify the other elements.
• All CompositeMode values are same
• All Filter values are same

Even when all the above conditions are satisfied, multiple draw commands can be used in really rare cases. Ebiten images usually share an internal automatic texture atlas, but when you consume the atlas, or you create a huge image, those images cannot be on the same texture atlas. In this case, draw commands are separated. The texture atlas size is 4096x4096 so far. Another case is when you use an offscreen as a render source. An offscreen doesn't share the texture atlas with high probability.

For more performance tips, see https://ebiten.org/performancetips.html

DrawImage always returns nil as of 1.5.0-alpha.

func (*Image) DrawTriangles

func (i *Image) DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)

DrawTriangles draws a triangle with the specified vertices and their indices.

If len(indices) is not multiple of 3, DrawTriangles panics.

If len(indices) is more than MaxIndicesNum, DrawTriangles panics.

The rule in which DrawTriangles works effectively is same as DrawImage's.

When the image i is disposed, DrawTriangles does nothing.

Internal mipmap is not used on DrawTriangles.

Note that this API is experimental.

func (*Image) Fill

func (i *Image) Fill(clr color.Color) error

Fill fills the image with a solid color.

When the image is disposed, Fill does nothing.

Fill always returns nil as of 1.5.0-alpha.

func (*Image) ReplacePixels

func (i *Image) ReplacePixels(p []byte) error

ReplacePixels replaces the pixels of the image with p.

The given p must represent RGBA pre-multiplied alpha values. len(p) must equal to 4 * (image width) * (image height).

ReplacePixels may be slow (as for implementation, this calls glTexSubImage2D).

When len(p) is not appropriate, ReplacePixels panics.

When the image is disposed, ReplacePixels does nothing.

ReplacePixels always returns nil as of 1.5.0-alpha.

func (*Image) Set

func (img *Image) Set(x, y int, clr color.Color)

Set sets the color at (x, y).

Set loads pixels from GPU to system memory if necessary, which means that Set can be slow.

Set can't be called outside the main loop (ebiten.Run's updating function) starts.

If the image is disposed, Set does nothing.

func (*Image) Size

func (i *Image) Size() (width, height int)

Size returns the size of the image.

func (*Image) SubImage

func (i *Image) SubImage(r image.Rectangle) image.Image

SubImage returns an image representing the portion of the image p visible through r. The returned value shares pixels with the original image.

The returned value is always *ebiten.Image.

If the image is disposed, SubImage returns nil.

In the current Ebiten implementation, SubImage is available only as a rendering source.

type ImagePart

type ImagePart struct {
	Dst image.Rectangle
	Src image.Rectangle
}

An ImagePart is deprecated (as of 1.1.0-alpha): Use SubImage instead.

type ImageParts

type ImageParts interface {
	Len() int
	Dst(i int) (x0, y0, x1, y1 int)
	Src(i int) (x0, y0, x1, y1 int)
}

An ImageParts is deprecated (as of 1.5.0-alpha): Use SubImage instead.

type Key

type Key int

A Key represents a keyboard key. These keys represent pysical keys of US keyboard. For example, KeyQ represents Q key on US keyboards and ' (quote) key on Dvorak keyboards.

const (
	Key0            Key = Key(driver.Key0)
	Key1            Key = Key(driver.Key1)
	Key2            Key = Key(driver.Key2)
	Key3            Key = Key(driver.Key3)
	Key4            Key = Key(driver.Key4)
	Key5            Key = Key(driver.Key5)
	Key6            Key = Key(driver.Key6)
	Key7            Key = Key(driver.Key7)
	Key8            Key = Key(driver.Key8)
	Key9            Key = Key(driver.Key9)
	KeyA            Key = Key(driver.KeyA)
	KeyB            Key = Key(driver.KeyB)
	KeyC            Key = Key(driver.KeyC)
	KeyD            Key = Key(driver.KeyD)
	KeyE            Key = Key(driver.KeyE)
	KeyF            Key = Key(driver.KeyF)
	KeyG            Key = Key(driver.KeyG)
	KeyH            Key = Key(driver.KeyH)
	KeyI            Key = Key(driver.KeyI)
	KeyJ            Key = Key(driver.KeyJ)
	KeyK            Key = Key(driver.KeyK)
	KeyL            Key = Key(driver.KeyL)
	KeyM            Key = Key(driver.KeyM)
	KeyN            Key = Key(driver.KeyN)
	KeyO            Key = Key(driver.KeyO)
	KeyP            Key = Key(driver.KeyP)
	KeyQ            Key = Key(driver.KeyQ)
	KeyR            Key = Key(driver.KeyR)
	KeyS            Key = Key(driver.KeyS)
	KeyT            Key = Key(driver.KeyT)
	KeyU            Key = Key(driver.KeyU)
	KeyV            Key = Key(driver.KeyV)
	KeyW            Key = Key(driver.KeyW)
	KeyX            Key = Key(driver.KeyX)
	KeyY            Key = Key(driver.KeyY)
	KeyZ            Key = Key(driver.KeyZ)
	KeyApostrophe   Key = Key(driver.KeyApostrophe)
	KeyBackslash    Key = Key(driver.KeyBackslash)
	KeyBackspace    Key = Key(driver.KeyBackspace)
	KeyCapsLock     Key = Key(driver.KeyCapsLock)
	KeyComma        Key = Key(driver.KeyComma)
	KeyDelete       Key = Key(driver.KeyDelete)
	KeyDown         Key = Key(driver.KeyDown)
	KeyEnd          Key = Key(driver.KeyEnd)
	KeyEnter        Key = Key(driver.KeyEnter)
	KeyEqual        Key = Key(driver.KeyEqual)
	KeyEscape       Key = Key(driver.KeyEscape)
	KeyF1           Key = Key(driver.KeyF1)
	KeyF2           Key = Key(driver.KeyF2)
	KeyF3           Key = Key(driver.KeyF3)
	KeyF4           Key = Key(driver.KeyF4)
	KeyF5           Key = Key(driver.KeyF5)
	KeyF6           Key = Key(driver.KeyF6)
	KeyF7           Key = Key(driver.KeyF7)
	KeyF8           Key = Key(driver.KeyF8)
	KeyF9           Key = Key(driver.KeyF9)
	KeyF10          Key = Key(driver.KeyF10)
	KeyF11          Key = Key(driver.KeyF11)
	KeyF12          Key = Key(driver.KeyF12)
	KeyGraveAccent  Key = Key(driver.KeyGraveAccent)
	KeyHome         Key = Key(driver.KeyHome)
	KeyInsert       Key = Key(driver.KeyInsert)
	KeyKP0          Key = Key(driver.KeyKP0)
	KeyKP1          Key = Key(driver.KeyKP1)
	KeyKP2          Key = Key(driver.KeyKP2)
	KeyKP3          Key = Key(driver.KeyKP3)
	KeyKP4          Key = Key(driver.KeyKP4)
	KeyKP5          Key = Key(driver.KeyKP5)
	KeyKP6          Key = Key(driver.KeyKP6)
	KeyKP7          Key = Key(driver.KeyKP7)
	KeyKP8          Key = Key(driver.KeyKP8)
	KeyKP9          Key = Key(driver.KeyKP9)
	KeyKPAdd        Key = Key(driver.KeyKPAdd)
	KeyKPDecimal    Key = Key(driver.KeyKPDecimal)
	KeyKPDivide     Key = Key(driver.KeyKPDivide)
	KeyKPEnter      Key = Key(driver.KeyKPEnter)
	KeyKPEqual      Key = Key(driver.KeyKPEqual)
	KeyKPMultiply   Key = Key(driver.KeyKPMultiply)
	KeyKPSubtract   Key = Key(driver.KeyKPSubtract)
	KeyLeft         Key = Key(driver.KeyLeft)
	KeyLeftBracket  Key = Key(driver.KeyLeftBracket)
	KeyMenu         Key = Key(driver.KeyMenu)
	KeyMinus        Key = Key(driver.KeyMinus)
	KeyNumLock      Key = Key(driver.KeyNumLock)
	KeyPageDown     Key = Key(driver.KeyPageDown)
	KeyPageUp       Key = Key(driver.KeyPageUp)
	KeyPause        Key = Key(driver.KeyPause)
	KeyPeriod       Key = Key(driver.KeyPeriod)
	KeyPrintScreen  Key = Key(driver.KeyPrintScreen)
	KeyRight        Key = Key(driver.KeyRight)
	KeyRightBracket Key = Key(driver.KeyRightBracket)
	KeyScrollLock   Key = Key(driver.KeyScrollLock)
	KeySemicolon    Key = Key(driver.KeySemicolon)
	KeySlash        Key = Key(driver.KeySlash)
	KeySpace        Key = Key(driver.KeySpace)
	KeyTab          Key = Key(driver.KeyTab)
	KeyUp           Key = Key(driver.KeyUp)
	KeyAlt          Key = Key(driver.KeyReserved0)
	KeyControl      Key = Key(driver.KeyReserved1)
	KeyShift        Key = Key(driver.KeyReserved2)
	KeyMax          Key = KeyShift
)

Keys.

func (Key) String

func (k Key) String() string

String returns a string representing the key.

If k is an undefined key, String returns an empty string.

type MouseButton

type MouseButton int

A MouseButton represents a mouse button.

const (
	MouseButtonLeft   MouseButton = MouseButton(driver.MouseButtonLeft)
	MouseButtonRight  MouseButton = MouseButton(driver.MouseButtonRight)
	MouseButtonMiddle MouseButton = MouseButton(driver.MouseButtonMiddle)
)

MouseButtons

type Touch

type Touch interface {
	// ID returns an identifier for one stroke.
	ID() int

	// Position returns the position of the touch.
	Position() (x, y int)
}

Touch is deprecated as of 1.7.0. Use TouchPosition instead.

func Touches

func Touches() []Touch

Touches is deprecated as of 1.7.0. Use TouchIDs instead.

type Vertex

type Vertex struct {
	// DstX and DstY represents a point on a destination image.
	DstX float32
	DstY float32

	// SrcX and SrcY represents a point on a source image.
	// Be careful that SrcX/SrcY coordinates are on the image's bounds.
	// This means that a left-upper point of a sub-image might not be (0, 0).
	SrcX float32
	SrcY float32

	// ColorR/ColorG/ColorB/ColorA represents color scaling values.
	// 1 means the original source image color is used.
	// 0 means a transparent color is used.
	ColorR float32
	ColorG float32
	ColorB float32
	ColorA float32
}

Vertex represents a vertex passed to DrawTriangles.

Note that this API is experimental.