Cheat Sheet

Hajime Hoshi edited this page Dec 6, 2018 · 12 revisions

This cheat sheet describes the essential APIs that are commonly used. For the complete list of the API, see the GoDoc.

Table of Contents

General

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

Ebiten tries to call f 60 times a second. In other words, TPS (ticks per second) is 60. 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.

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.

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

ebiten.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
}

ebitenutil.DebugPrint

func DebugPrint(image *ebiten.Image, str string) error

(Defined at ebitenutil package)

DebugPrint draws the string str on the image on left top corner.

DebugPrint always returns nil.

Graphics

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

ebiten.NewImage

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

NewImage returns an empty image. NewImage always returns nil error (so you can ignore that).

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

ebiten.NewImageFromImage

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

NewImageFromImage creates a new image with the given image (source). NewImageFromImage always returns nil error.

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

(*ebiten.Image).Clear

func (i *Image) Clear() error

Clear resets the pixels of the image into 0.

Clear always returns nil.

(*ebiten.Image).Fill

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

Fill fills the image with a solid color.

Fill always returns nil.

(*ebiten.Image).Size

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

Size returns the size of the image.

(*ebiten.Image).SubImage

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

(This function was introduced at Ebiten 1.9.0-alpha)

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.

(*ebiten.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.

DrawImage determines the part to draw, then DrawImage applies the geometry matrix and the color matrix.

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 given image is as same as i, DrawImage panics.

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

  • All render targets are same (A in A.DrawImage(B, op))
  • All render sources are same (B in A.DrawImage(B, op))
    • This is not a strong request since different images might share a same inner OpenGL texture in high possibility. This is not 100%, so using the same render source is safer.
  • All ColorM values are same, or all the ColorM have only 'scale' operations
  • All CompositeMode values are same
  • All Filter values are same

For more performance tips, see Performance Tips.

DrawImage always returns nil.

ebiten.DrawImageOptions

type DrawImageOptions struct {
    // (This is deprecated as of 1.9.0-alpha. Use (*Image).SubImage instead if you use Ebiten 1.9.0-alpha or later.)
    //
    // SourceRect is the region of the source image to draw.
    // If SourceRect is nil, whole image is used.
    SourceRect *image.Rectangle

    // 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 Filter
}

DrawImageOptions represents options to render an image on an image.

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

    // FilterNearest represents nearest (crisp-edged) filter
    FilterNearest

    // FilterLinear represents linear filter
    FilterLinear
)

ebiten.GeoM

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

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

The initial value is identity.

(*ebiten.GeoM).Translate

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

Translate translates the matrix by (tx, ty).

(*ebiten.GeoM).Scale

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

Scale scales the matrix by (x, y).

(*ebiten.GeoM).Rotate

func (g *GeoM) Rotate(theta float64)

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

ebiten.ColorM

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

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

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.

(*ebiten.ColorM).Scale

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

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

(*ebiten.ColorM).Translate

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

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

(*ebiten.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).

Input

ebiten.IsKeyPressed

func IsKeyPressed(key Key) bool

IsKeyPressed returns a boolean indicating whether key is pressed.

inpututil.IsKeyJustPressed

func IsKeyJustPressed(key ebiten.Key) bool

(Defined at inpututil package)

IsKeyJustPressed returns a boolean value indicating whether the given key is pressed just in the current frame.

ebiten.Key

type Key int

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
    Key1
    Key2
    Key3
    Key4
    Key5
    Key6
    Key7
    Key8
    Key9
    KeyA
    KeyB
    KeyC
    KeyD
    KeyE
    KeyF
    KeyG
    KeyH
    KeyI
    KeyJ
    KeyK
    KeyL
    KeyM
    KeyN
    KeyO
    KeyP
    KeyQ
    KeyR
    KeyS
    KeyT
    KeyU
    KeyV
    KeyW
    KeyX
    KeyY
    KeyZ
    KeyAlt
    KeyApostrophe
    KeyBackslash
    KeyBackspace
    KeyCapsLock
    KeyComma
    KeyControl
    KeyDelete
    KeyDown
    KeyEnd
    KeyEnter
    KeyEqual
    KeyEscape
    KeyF1
    KeyF2
    KeyF3
    KeyF4
    KeyF5
    KeyF6
    KeyF7
    KeyF8
    KeyF9
    KeyF10
    KeyF11
    KeyF12
    KeyGraveAccent
    KeyHome
    KeyInsert
    KeyLeft
    KeyLeftBracket
    KeyMenu
    KeyMinus
    KeyNumLock
    KeyPageDown
    KeyPageUp
    KeyPause
    KeyPeriod
    KeyPrintScreen
    KeyRight
    KeyRightBracket
    KeyScrollLock
    KeySemicolon
    KeyShift
    KeySlash
    KeySpace
    KeyTab
    KeyUp
)

(Note: Some keys like numpad keys are omitted from the above list.)

ebiten.CursorPosition

func CursorPosition() (x, y int)

CursorPosition returns a position of a mouse cursor.

ebiten.IsMouseButtonPressed

func IsMouseButtonPressed(mouseButton MouseButton) bool

IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.

inpututil.IsMouseButtonJustPressed

func IsMouseButtonJustPressed(button ebiten.MouseButton) bool

(Defined at inpututil package)

IsMouseButtonJustPressed returns a boolean value indicating whether the given mouse button is pressed just in the current frame.

ebiten.MouseButton

type MouseButton int

MouseButton represents a mouse button.

const (
    MouseButtonLeft MouseButton
    MouseButtonRight
    MouseButtonMiddle
)
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.