ebiten

package module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2017 License: Apache-2.0 Imports: 12 Imported by: 925

README

Ebiten (海老天)

Build Status GoDoc Go Report Card

A simple 2D game library in Go

Note: Gamepad is not available on Safari/Android/iOS. Keyboard is not available on Android/iOS.

Features

  • 2D Graphics (Geometry/Color matrix transformation, Various composition modes, Offscreen rendering)
  • Input (Mouse, Keyboard, Gamepads, Touches)
  • Audio (Ogg/Vorbis, WAV, PCM)

Web Site

https://hajimehoshi.github.io/ebiten/

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. 

func update(screen *ebiten.Image) error {
    // Define your game.
}

func main() {
    ebiten.Run(update, 320, 240, 2, "Your game's title")
}

Index

Constants

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

GamepadButtons

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

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

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

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

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

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

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

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

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

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

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

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

	// Sum of source and destination (a.k.a. 'plus' or 'additive')
	// c_out = c_src + c_dst
	CompositeModeLighter = CompositeMode(opengl.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.

View Source 
const (
	Key0            = Key(ui.Key0)
	Key1            = Key(ui.Key1)
	Key2            = Key(ui.Key2)
	Key3            = Key(ui.Key3)
	Key4            = Key(ui.Key4)
	Key5            = Key(ui.Key5)
	Key6            = Key(ui.Key6)
	Key7            = Key(ui.Key7)
	Key8            = Key(ui.Key8)
	Key9            = Key(ui.Key9)
	KeyA            = Key(ui.KeyA)
	KeyB            = Key(ui.KeyB)
	KeyC            = Key(ui.KeyC)
	KeyD            = Key(ui.KeyD)
	KeyE            = Key(ui.KeyE)
	KeyF            = Key(ui.KeyF)
	KeyG            = Key(ui.KeyG)
	KeyH            = Key(ui.KeyH)
	KeyI            = Key(ui.KeyI)
	KeyJ            = Key(ui.KeyJ)
	KeyK            = Key(ui.KeyK)
	KeyL            = Key(ui.KeyL)
	KeyM            = Key(ui.KeyM)
	KeyN            = Key(ui.KeyN)
	KeyO            = Key(ui.KeyO)
	KeyP            = Key(ui.KeyP)
	KeyQ            = Key(ui.KeyQ)
	KeyR            = Key(ui.KeyR)
	KeyS            = Key(ui.KeyS)
	KeyT            = Key(ui.KeyT)
	KeyU            = Key(ui.KeyU)
	KeyV            = Key(ui.KeyV)
	KeyW            = Key(ui.KeyW)
	KeyX            = Key(ui.KeyX)
	KeyY            = Key(ui.KeyY)
	KeyZ            = Key(ui.KeyZ)
	KeyAlt          = Key(ui.KeyAlt)
	KeyApostrophe   = Key(ui.KeyApostrophe)
	KeyBackslash    = Key(ui.KeyBackslash)
	KeyBackspace    = Key(ui.KeyBackspace)
	KeyCapsLock     = Key(ui.KeyCapsLock)
	KeyComma        = Key(ui.KeyComma)
	KeyControl      = Key(ui.KeyControl)
	KeyDelete       = Key(ui.KeyDelete)
	KeyDown         = Key(ui.KeyDown)
	KeyEnd          = Key(ui.KeyEnd)
	KeyEnter        = Key(ui.KeyEnter)
	KeyEqual        = Key(ui.KeyEqual)
	KeyEscape       = Key(ui.KeyEscape)
	KeyF1           = Key(ui.KeyF1)
	KeyF2           = Key(ui.KeyF2)
	KeyF3           = Key(ui.KeyF3)
	KeyF4           = Key(ui.KeyF4)
	KeyF5           = Key(ui.KeyF5)
	KeyF6           = Key(ui.KeyF6)
	KeyF7           = Key(ui.KeyF7)
	KeyF8           = Key(ui.KeyF8)
	KeyF9           = Key(ui.KeyF9)
	KeyF10          = Key(ui.KeyF10)
	KeyF11          = Key(ui.KeyF11)
	KeyF12          = Key(ui.KeyF12)
	KeyGraveAccent  = Key(ui.KeyGraveAccent)
	KeyHome         = Key(ui.KeyHome)
	KeyInsert       = Key(ui.KeyInsert)
	KeyLeft         = Key(ui.KeyLeft)
	KeyLeftBracket  = Key(ui.KeyLeftBracket)
	KeyMinus        = Key(ui.KeyMinus)
	KeyPageDown     = Key(ui.KeyPageDown)
	KeyPageUp       = Key(ui.KeyPageUp)
	KeyPeriod       = Key(ui.KeyPeriod)
	KeyRight        = Key(ui.KeyRight)
	KeyRightBracket = Key(ui.KeyRightBracket)
	KeySemicolon    = Key(ui.KeySemicolon)
	KeyShift        = Key(ui.KeyShift)
	KeySlash        = Key(ui.KeySlash)
	KeySpace        = Key(ui.KeySpace)
	KeyTab          = Key(ui.KeyTab)
	KeyUp           = Key(ui.KeyUp)
	KeyMax          = KeyUp
)

Keys

View Source 
const (
	MouseButtonLeft   = MouseButton(ui.MouseButtonLeft)
	MouseButtonRight  = MouseButton(ui.MouseButtonRight)
	MouseButtonMiddle = MouseButton(ui.MouseButtonMiddle)
)

MouseButtons

View Source 
const ColorMDim = affine.ColorMDim

ColorMDim is a dimension of a ColorM.

View Source 
const FPS = 60

FPS represents how many times game updating happens in a second.

View Source 
const GeoMDim = affine.GeoMDim

GeoMDim is a dimension of a GeoM.

View Source 
const MaxImageSize = graphics.MaxImageSize

Variables

This section is empty.

Functions

func CurrentFPS added in v1.2.0 

func CurrentFPS() float64

CurrentFPS returns the current number of frames per second of rendering.

This function is concurrent-safe.

This value represents how many times rendering happens in 1/60 second and NOT how many times logical game updating (a passed function to Run) happens. Note that logical game updating is assured to happen 60 times in a second as long as the screen is active.

func CursorPosition 

func CursorPosition() (x, y int)

CursorPosition returns a position of a mouse cursor.

This function is concurrent-safe.

func GamepadAxis added in v1.2.0 

func GamepadAxis(id int, axis int) float64

GamepadAxis returns the float value [-1.0 - 1.0] of the axis.

This function is concurrent-safe.

NOTE: Gamepad API is available only on desktops, Chrome and Firefox. To use this API, browsers might require rebooting the browser.

func GamepadAxisNum added in v1.2.0 

func GamepadAxisNum(id int) int

GamepadAxisNum returns the number of axes of the gamepad.

This function is concurrent-safe.

NOTE: Gamepad API is available only on desktops, Chrome and Firefox. To use this API, browsers might require rebooting the browser.

func GamepadButtonNum added in v1.2.0 

func GamepadButtonNum(id int) int

GamepadButtonNum returns the number of the buttons of the gamepad.

This function is concurrent-safe.

NOTE: Gamepad API is available only on desktops, Chrome and Firefox. To use this API, browsers might require rebooting the browser.

func IsGamepadButtonPressed added in v1.2.0 

func IsGamepadButtonPressed(id int, button GamepadButton) bool

IsGamepadButtonPressed returns the boolean indicating the buttons is pressed or not.

This function is concurrent-safe.

The key states vary depending on environments. There can be differences even between Chrome and Firefox. Don't assume that states of a keys are always same when same buttons are pressed.

NOTE: Gamepad API is available only on desktops, Chrome and Firefox. To use this API, browsers might require rebooting the browser.

func IsKeyPressed 

func IsKeyPressed(key Key) bool

IsKeyPressed returns a boolean indicating whether key is pressed.

This function is concurrent-safe.

func IsMouseButtonPressed 

func IsMouseButtonPressed(mouseButton MouseButton) bool

IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.

This function is concurrent-safe.

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

func IsRunningSlowly added in v1.3.0 

func IsRunningSlowly() bool

IsRunningSlowly returns true if the game is running too slowly to keep 60 FPS of rendering. The game screen is not updated when IsRunningSlowly is true. It is recommended to skip heavy processing, especially drawing, when IsRunningSlowly is true.

This function is concurrent-safe.

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.

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

The given function f is guaranteed to be called 60 times a second even if a rendering frame is skipped. f is not called when the screen is not shown.

Run returns error when 1) OpenGL error happens, or 2) f returns error. In the case of 2), Run returns the same error.

The size unit is device-independent pixel.

func RunWithoutMainLoop added in v1.4.0 

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, this function returns immediately.

Typically, Ebiten users don't have to call this directly. Instead, functions in github.com/hajimehoshi/ebiten/mobile module call this.

The size unit is device-independent pixel.

func ScreenScale added in v1.3.0 

func ScreenScale() float64

ScreenScale returns the current screen scale.

If Run is not called, this returns 0.

This function is concurrent-safe.

func SetCursorVisibility added in v1.5.0 

func SetCursorVisibility(visible bool)

SetCursorVisibility changes the state of cursor visiblity.

This function is concurrent-safe.

func SetScreenScale added in v1.2.0 

func SetScreenScale(scale float64)

SetScreenScale changes the scale of the screen.

This function is concurrent-safe.

func SetScreenSize added in v1.2.0 

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.

This function is concurrent-safe.

Types

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 source 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 returns a color matrix to make an image monochrome.

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) ChangeHSV added in v1.3.0 

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

ChangeHSV changes HSV (Hue-Saturation-Value) values. hueTheta is a radian value to ratate 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 added in v1.5.0 

func (c *ColorM) Reset()

Reset resets the ColorM as identity.

func (*ColorM) RotateHue added in v1.2.0 

func (c *ColorM) RotateHue(theta float64)

RotateHue rotates the hue.

func (*ColorM) Scale added in v1.1.0 

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, value float64)

SetElement sets an element at (i, j).

func (*ColorM) Translate added in v1.1.0 

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

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

type CompositeMode added in v1.3.0 

type CompositeMode int

CompositeMode represents Porter-Duff composition mode.

type DrawImageOptions 

type DrawImageOptions struct {
	SourceRect    *image.Rectangle
	GeoM          GeoM
	ColorM        ColorM
	CompositeMode CompositeMode

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

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

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

type Filter 

type Filter int

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

const (
	// FilterNearest represents nearest (crisp-edged) filter
	FilterNearest Filter = iota

	// FilterLinear represents linear filter
	FilterLinear
)

type GamepadButton added in v1.2.0 

type GamepadButton int

A GamepadButton represents a gamepad button.

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) 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) Reset added in v1.5.0 

func (g *GeoM) Reset()

Reset resets the GeoM as identity.

func (*GeoM) Rotate added in v1.1.0 

func (g *GeoM) Rotate(theta float64)

Rotate rotates the matrix by theta.

func (*GeoM) Scale added in v1.1.0 

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) Translate added in v1.1.0 

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

Translate translates the matrix by (x, y).

type Image 

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

Image represents an image. The pixel format is alpha-premultiplied. Image implements image.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 MaxImageSize, NewImage panics.

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 MaxImageSize, NewImageFromImage panics.

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).

This method loads pixels from GPU to system memory if necessary.

This method can't be called before the main loop (ebiten.Run) 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 added in v1.2.0 

func (i *Image) Dispose() error

Dispose disposes the image data. After disposing, the image becomes invalid. This is useful to save memory.

The behavior of any functions for a disposed image is undefined.

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 receiver image.

This method accepts the options. The parts of the given image at the parts of the destination. After determining parts to draw, this applies the geometry matrix and the color matrix.

Here are the default values: 

SourceRect:    nil. When SourceRect is nil, the whole source image is used.
GeoM:          Identity matrix
ColorM:        Identity matrix (that changes no colors)
CompositeMode: CompositeModeSourceOver (regular alpha blending)

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 is disposed, DrawImage does nothing.

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

DrawImage always returns nil as of 1.5.0-alpha.

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 added in v1.2.0 

func (i *Image) ReplacePixels(p []uint8) 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 4 * (width) * (height), ReplacePixels panics.

When the image is disposed, ReplacePixels does nothing.

ReplacePixels always returns nil as of 1.5.0-alpha.

func (*Image) Size 

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

Size returns the size of the image.

type ImagePart 

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

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

type ImageParts added in v1.1.0 

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 SourceRect 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 keybaords and ' (quote) key on Dvorak keyboards.

type MouseButton 

type MouseButton int

A MouseButton represents a mouse button.

type Touch added in v1.4.0 

type Touch interface {
	ID() int
	Position() (x, y int)
}

Touch represents a pointer state.

func Touches added in v1.4.0 

func Touches() []Touch

Touches returns the current touch states.

Source Files

View all Source files

Directories

Path Synopsis
server
Package audio provides audio players.
 Package audio provides audio players.
internal/convert
vorbis
Package vorbis provides Ogg/Vorbis decoder.
 Package vorbis provides Ogg/Vorbis decoder.
wav
Package wav provides WAV (RIFF) decoder.
 Package wav provides WAV (RIFF) decoder.
internal/assets
examples
_server
affine
endian
graphics
loop
opengl
restorable
sync
ui

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.