ebiten

package module
v2.8.0-alpha.8 Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2024 License: Apache-2.0 Imports: 29 Imported by: 3,927

README ¶

Ebitengine (v2)

Go Reference Build Status

A dead simple 2D game engine for Go

Ebitengine (formerly known as Ebiten) is an open source game engine for the Go programming language. Ebitengine's simple API allows you to quickly and easily develop 2D games that can be deployed across multiple platforms.

Overview

Platforms

For installation on desktops, see the installation instruction.

Features

  • 2D Graphics (Geometry and color transformation by matrices, Various composition modes, Offscreen rendering, Text rendering, Automatic batches, Automatic texture atlas, Custom shaders)
  • Input (Mouse, Keyboard, Gamepads, Touches)
  • Audio (Ogg/Vorbis, MP3, WAV, PCM)

Packages

Community

License

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

The Ebitengine logo by Hajime Hoshi is licensed under the Creative Commons Attribution-NoDerivatives 4.0.

GLFW

https://github.com/glfw/glfw

Copyright (c) 2002-2006 Marcus Geelnard

Copyright (c) 2006-2019 Camilla Löwy

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would
   be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not
   be misrepresented as being the original software.

3. This notice may not be removed or altered from any source
   distribution.
Go

https://cs.opensource.google/go/go

Copyright (c) 2009 The Go Authors. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
   * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
go-gl/gl

https://github.com/go-gl/gl

The MIT License (MIT)

Copyright (c) 2014 Eric Woroshow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
go-gl/glfw

https://github.com/go-gl/glfw

Copyright (c) 2012 The glfw3-go Authors. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
   * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Documentation ¶

Overview ¶

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

You can start the game by calling the function RunGame. 

// Game implements ebiten.Game interface.
type Game struct{}

// Update proceeds the game state.
// Update is called every tick (1/60 [s] by default).
func (g *Game) Update() error {
    // Write your game's logical update.
    return nil
}

// Draw draws the game screen.
// Draw is called every frame (typically 1/60[s] for 60Hz display).
func (g *Game) Draw(screen *ebiten.Image) {
    // Write your game's rendering.
}

// Layout takes the outside size (e.g., the window size) and returns the (logical) screen size.
// If you don't have to adjust the screen size with the outside size, just return a fixed size.
func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
    return 320, 240
}

func main() {
    game := &Game{}
    // Specify the window size as you like. Here, a doubled size is specified.
    ebiten.SetWindowSize(640, 480)
    ebiten.SetWindowTitle("Your game's title")
    // Call ebiten.RunGame to start your game loop.
    if err := ebiten.RunGame(game); err != nil {
        log.Fatal(err)
    }
}

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 Ebitengine functions (e.g., DeviceScaleFactor) that must be called on the main thread under some conditions (typically, before ebiten.RunGame is called).

Environment variables ¶

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

`EBITENGINE_INTERNAL_IMAGES_KEY` environment variable specifies the key to dump all the internal images. This is valid only when the build tag 'ebitenginedebug' is specified. This works only on desktops and browsers.

`EBITENGINE_GRAPHICS_LIBRARY` environment variable specifies the graphics library. If the specified graphics library is not available, RunGame returns an error. This environment variable works when RunGame is called or RunGameWithOptions is called with GraphicsLibraryAuto. This can take one of the following value: 

"auto":         Ebitengine chooses the graphics library automatically. This is the default value.
"opengl":       OpenGL, OpenGL ES, or WebGL.
"directx":      DirectX. This works only on Windows.
"metal":        Metal. This works only on macOS or iOS.
"playstation5": PlayStation 5. This works only on PlayStation 5.

`EBITENGINE_DIRECTX` environment variable specifies various parameters for DirectX. You can specify multiple values separated by a comma. The default value is empty (i.e. no parameters). 

"debug":                      Use a debug layer.
"warp":                       Use WARP (i.e. software rendering).
"version=VERSION":            Specify a DirectX version (e.g. 11).
"featurelevel=FEATURE_LEVEL": Specify a feature level (e.g. 11_0). This is for DirectX 12.

The options taking arguments are exclusive, and if multiples are specified, the lastly specified value is adopted.

The possible values for the option "version" are "11" and "12". If the version is not specified, the default version 11 is adopted. On Xbox, the "version" option is ignored and DirectX 12 is always adopted.

The option "featurelevel" is valid only for DirectX 12. The possible values are "11_0", "11_1", "12_0", "12_1", and "12_2". The default value is "11_0".

Build tags ¶

`ebitenginedebug` outputs a log of graphics commands. This is useful to know what happens in Ebitengine. In general, the number of graphics commands affects the performance of your game.

`ebitenginegldebug` enables a debug mode for OpenGL. This is valid only when the graphics library is OpenGL. This affects performance very much.

`ebitenginesinglethread` disables Ebitengine's thread safety to unlock maximum performance. If you use this you will have to manage threads yourself. Functions like `SetWindowSize` will no longer be concurrent-safe with this build tag. They must be called from the main thread or the same goroutine as the given game's callback functions like Update `ebitenginesinglethread` works only with desktops and consoles. `ebitenginesinglethread` was deprecated as of v2.7. Use RunGameOptions.SingleThread instead.

`microsoftgdk` is for Microsoft GDK (e.g. Xbox).

`nintendosdk` is for NintendoSDK (e.g. Nintendo Switch).

`nintendosdkprofile` enables a profiler for NintendoSDK.

`playstation5` is for PlayStation 5.

Index ¶

Constants ¶

View Source 
const (
	// FillAll indicates all the triangles are rendered regardless of overlaps.
	//
	// Deprecated: as of v2.8. Use FillRuleFillAll instead.
	FillAll = FillRuleFillAll

	// NonZero means that triangles are rendered based on the non-zero rule.
	// If and only if the number of overlaps is not 0, the region is rendered.
	//
	// Deprecated: as of v2.8. Use FillRuleNonZero instead.
	NonZero = FillRuleNonZero

	// EvenOdd means that triangles are rendered based on the even-odd rule.
	// If and only if the number of overlaps is odd, the region is rendered.
	//
	// Deprecated: as of v2.8. Use FillRuleEvenOdd instead.
	EvenOdd = FillRuleEvenOdd
)
View Source 
const ColorMDim = affine.ColorMDim

ColorMDim is the dimension of a ColorM.

Deprecated: as of v2.5. Use the colorm package instead.

View Source 
const DefaultTPS = clock.DefaultTPS

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

View Source 
const GeoMDim = 3

GeoMDim is a dimension of a GeoM.

View Source 
const MaxIndicesCount = (1 << 16) / 3 * 3

MaxIndicesCount is the maximum number of indices for DrawTriangles and DrawTrianglesShader.

Deprecated: as of v2.6. This constant is no longer used.

View Source 
const MaxIndicesNum = MaxIndicesCount

MaxIndicesNum is the maximum number of indices for DrawTriangles and DrawTrianglesShader.

Deprecated: as of v2.4. This constant is no longer used.

View Source 
const MaxVertexCount = graphicscommand.MaxVertexCount

MaxVertexCount is the maximum number of vertices for DrawTriangles and DrawTrianglesShader.

View Source 
const MaxVerticesCount = graphicscommand.MaxVertexCount

MaxVerticesCount is the maximum number of vertices for DrawTriangles and DrawTrianglesShader.

Deprecated: as of v2.7. Use MaxVertexCount instead.

View Source 
const SyncWithFPS = clock.SyncWithFPS

SyncWithFPS is a special TPS value that means TPS syncs with FPS.

View Source 
const UncappedTPS = SyncWithFPS

UncappedTPS is a special TPS value that means TPS syncs with FPS.

Deprecated: as of v2.2. Use SyncWithFPS instead.

Variables ¶

View Source 
var (
	// BlendSourceOver is a preset Blend for the regular alpha blending.
	//
	//     c_out = c_src + c_dst × (1 - α_src)
	//     α_out = α_src + α_dst × (1 - α_src)
	BlendSourceOver = Blend{
		BlendFactorSourceRGB:        BlendFactorOne,
		BlendFactorSourceAlpha:      BlendFactorOne,
		BlendFactorDestinationRGB:   BlendFactorOneMinusSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorOneMinusSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendClear is a preset Blend for Porter Duff's 'clear'.
	//
	//     c_out = 0
	//     α_out = 0
	BlendClear = Blend{
		BlendFactorSourceRGB:        BlendFactorZero,
		BlendFactorSourceAlpha:      BlendFactorZero,
		BlendFactorDestinationRGB:   BlendFactorZero,
		BlendFactorDestinationAlpha: BlendFactorZero,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendCopy is a preset Blend for Porter Duff's 'copy'.
	//
	//     c_out = c_src
	//     α_out = α_src
	BlendCopy = Blend{
		BlendFactorSourceRGB:        BlendFactorOne,
		BlendFactorSourceAlpha:      BlendFactorOne,
		BlendFactorDestinationRGB:   BlendFactorZero,
		BlendFactorDestinationAlpha: BlendFactorZero,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendDestination is a preset Blend for Porter Duff's 'destination'.
	//
	//     c_out = c_dst
	//     α_out = α_dst
	BlendDestination = Blend{
		BlendFactorSourceRGB:        BlendFactorZero,
		BlendFactorSourceAlpha:      BlendFactorZero,
		BlendFactorDestinationRGB:   BlendFactorOne,
		BlendFactorDestinationAlpha: BlendFactorOne,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendDestinationOver is a preset Blend for Porter Duff's 'destination-over'.
	//
	//     c_out = c_src × (1 - α_dst) + c_dst
	//     α_out = α_src × (1 - α_dst) + α_dst
	BlendDestinationOver = Blend{
		BlendFactorSourceRGB:        BlendFactorOneMinusDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorOneMinusDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorOne,
		BlendFactorDestinationAlpha: BlendFactorOne,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendSourceIn is a preset Blend for Porter Duff's 'source-in'.
	//
	//     c_out = c_src × α_dst
	//     α_out = α_src × α_dst
	BlendSourceIn = Blend{
		BlendFactorSourceRGB:        BlendFactorDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorZero,
		BlendFactorDestinationAlpha: BlendFactorZero,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendDestinationIn is a preset Blend for Porter Duff's 'destination-in'.
	//
	//     c_out = c_dst × α_src
	//     α_out = α_dst × α_src
	BlendDestinationIn = Blend{
		BlendFactorSourceRGB:        BlendFactorZero,
		BlendFactorSourceAlpha:      BlendFactorZero,
		BlendFactorDestinationRGB:   BlendFactorSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendSourceOut is a preset Blend for Porter Duff's 'source-out'.
	//
	//     c_out = c_src × (1 - α_dst)
	//     α_out = α_src × (1 - α_dst)
	BlendSourceOut = Blend{
		BlendFactorSourceRGB:        BlendFactorOneMinusDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorOneMinusDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorZero,
		BlendFactorDestinationAlpha: BlendFactorZero,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendDestinationOut is a preset Blend for Porter Duff's 'destination-out'.
	//
	//     c_out = c_dst × (1 - α_src)
	//     α_out = α_dst × (1 - α_src)
	BlendDestinationOut = Blend{
		BlendFactorSourceRGB:        BlendFactorZero,
		BlendFactorSourceAlpha:      BlendFactorZero,
		BlendFactorDestinationRGB:   BlendFactorOneMinusSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorOneMinusSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendSourceAtop is a preset Blend for Porter Duff's 'source-atop'.
	//
	//     c_out = c_src × α_dst + c_dst × (1 - α_src)
	//     α_out = α_src × α_dst + α_dst × (1 - α_src)
	BlendSourceAtop = Blend{
		BlendFactorSourceRGB:        BlendFactorDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorOneMinusSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorOneMinusSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendDestinationAtop is a preset Blend for Porter Duff's 'destination-atop'.
	//
	//     c_out = c_src × (1 - α_dst) + c_dst × α_src
	//     α_out = α_src × (1 - α_dst) + α_dst × α_src
	BlendDestinationAtop = Blend{
		BlendFactorSourceRGB:        BlendFactorOneMinusDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorOneMinusDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendXor is a preset Blend for Porter Duff's 'xor'.
	//
	//     c_out = c_src × (1 - α_dst) + c_dst × (1 - α_src)
	//     α_out = α_src × (1 - α_dst) + α_dst × (1 - α_src)
	BlendXor = Blend{
		BlendFactorSourceRGB:        BlendFactorOneMinusDestinationAlpha,
		BlendFactorSourceAlpha:      BlendFactorOneMinusDestinationAlpha,
		BlendFactorDestinationRGB:   BlendFactorOneMinusSourceAlpha,
		BlendFactorDestinationAlpha: BlendFactorOneMinusSourceAlpha,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}

	// BlendLighter is a preset Blend for Porter Duff's 'lighter'.
	// This is sum of source and destination (a.k.a. 'plus' or 'additive')
	//
	//     c_out = c_src + c_dst
	//     α_out = α_src + α_dst
	BlendLighter = Blend{
		BlendFactorSourceRGB:        BlendFactorOne,
		BlendFactorSourceAlpha:      BlendFactorOne,
		BlendFactorDestinationRGB:   BlendFactorOne,
		BlendFactorDestinationAlpha: BlendFactorOne,
		BlendOperationRGB:           BlendOperationAdd,
		BlendOperationAlpha:         BlendOperationAdd,
	}
)

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 
var Termination = ui.RegularTermination

Termination is a special error which indicates Game termination without error.

Functions ¶

func ActualFPS ¶ added in v2.4.0 

func ActualFPS() float64

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

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

This value is for measurement and/or debug, and your game logic should not rely on this value.

ActualFPS is concurrent-safe.

func ActualTPS ¶ added in v2.4.0 

func ActualTPS() float64

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

This value is for measurement and/or debug, and your game logic should not rely on this value.

ActualTPS is concurrent-safe.

func AppendInputChars ¶ added in v2.2.0 

func AppendInputChars(runes []rune) []rune

AppendInputChars appends "printable" runes, read from the keyboard at the time Update is called, to runes, and returns the extended buffer. Giving a slice that already has enough capacity works efficiently.

AppendInputChars represents the environment's locale-dependent translation of keyboard input to Unicode characters. On the other hand, Key represents a physical key of US keyboard layout

"Control" and modifier keys should be handled with IsKeyPressed.

AppendInputChars is concurrent-safe.

On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.

func CurrentFPS deprecated 

func CurrentFPS() float64

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

Deprecated: as of v2.4. Use ActualFPS instead.

func CurrentTPS deprecated 

func CurrentTPS() float64

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

Deprecated: as of v2.4. Use ActualTPS instead.

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 returns (0, 0) before the main loop on desktops and browsers.

CursorPosition always returns (0, 0) on mobile native applications.

CursorPosition is concurrent-safe.

func DeviceScaleFactor deprecated 

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 the main loop, and is concurrent-safe after the main loop.

BUG: DeviceScaleFactor value is not affected by SetWindowPosition before RunGame (#1575).

Deprecated: as of v2.6. Use Monitor().DeviceScaleFactor() instead.

func DroppedFiles ¶ added in v2.5.0 

func DroppedFiles() fs.FS

DroppedFiles returns a virtual file system that includes only dropped files and/or directories at its root directory, at the time Update is called.

DroppedFiles works on desktops and browsers.

DroppedFiles is concurrent-safe.

func GamepadAxis deprecated 

func GamepadAxis(id GamepadID, axis GamepadAxisType) float64

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

Deprecated: as of v2.2. Use GamepadAxisValue instead.

func GamepadAxisCount ¶ added in v2.4.0 

func GamepadAxisCount(id GamepadID) int

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

GamepadAxisCount is concurrent-safe.

func GamepadAxisNum deprecated 

func GamepadAxisNum(id GamepadID) int

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

Deprecated: as of v2.4. Use GamepadAxisCount instead.

func GamepadAxisValue ¶ added in v2.2.0 

func GamepadAxisValue(id GamepadID, axis GamepadAxisType) float64

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

GamepadAxisValue is concurrent-safe.

func GamepadButtonCount ¶ added in v2.4.0 

func GamepadButtonCount(id GamepadID) int

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

GamepadButtonCount is concurrent-safe.

func GamepadButtonNum deprecated 

func GamepadButtonNum(id GamepadID) int

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

Deprecated: as of v2.4. Use GamepadButtonCount instead.

func GamepadName ¶ 

func GamepadName(id GamepadID) string

GamepadName returns a string with the name. This function may vary in how it returns descriptions for the same device across platforms. for example the following drivers/platforms see an Xbox One controller as the following:

  • Windows: "Xbox Controller"
  • Chrome: "Xbox 360 Controller (XInput STANDARD GAMEPAD)"
  • Firefox: "xinput"

GamepadName is concurrent-safe.

func GamepadSDLID ¶ 

func GamepadSDLID(id GamepadID) string

GamepadSDLID returns a string with the GUID generated in the same way as SDL. To detect devices, see also the community project of gamepad devices database: https://github.com/gabomdq/SDL_GameControllerDB

GamepadSDLID always returns an empty string on browsers and mobiles.

GamepadSDLID is concurrent-safe.

func InputChars deprecated 

func InputChars() []rune

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

Deprecated: as of v2.2. Use AppendInputChars instead.

func IsFocused ¶ 

func IsFocused() bool

IsFocused returns a boolean value indicating whether the game is in focus or in the foreground.

IsFocused will only return true if IsRunnableOnUnfocused is false.

IsFocused is concurrent-safe.

func IsFullscreen ¶ 

func IsFullscreen() bool

IsFullscreen reports whether the current mode is fullscreen or not.

IsFullscreen always returns false on mobiles.

IsFullscreen is concurrent-safe.

func IsGamepadButtonPressed ¶ 

func IsGamepadButtonPressed(id GamepadID, button GamepadButton) bool

IsGamepadButtonPressed reports whether the given button of the gamepad (id) is pressed or not.

If you want to know whether the given button of gamepad (id) started being pressed in the current tick, use inpututil.IsGamepadButtonJustPressed

IsGamepadButtonPressed is concurrent-safe.

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

func IsKeyPressed ¶ 

func IsKeyPressed(key Key) bool

IsKeyPressed returns a boolean indicating whether key is pressed.

If you want to know whether the key started being pressed in the current tick, use inpututil.IsKeyJustPressed

Note that a Key represents a physical key of US keyboard layout. For example, KeyQ represents Q key on US keyboards and ' (quote) key on Dvorak keyboards.

IsKeyPressed is concurrent-safe.

On Android (ebitenmobile), EbitenView must be focusable to enable to handle keyboard keys.

func IsMouseButtonPressed ¶ 

func IsMouseButtonPressed(mouseButton MouseButton) bool

IsMouseButtonPressed returns a boolean indicating whether mouseButton is pressed.

If you want to know whether the mouseButton started being pressed in the current tick, use inpututil.IsMouseButtonJustPressed

IsMouseButtonPressed is concurrent-safe.

func IsRunnableOnUnfocused ¶ 

func IsRunnableOnUnfocused() bool

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

IsRunnableOnUnfocused is concurrent-safe.

func IsScreenClearedEveryFrame ¶ 

func IsScreenClearedEveryFrame() bool

IsScreenClearedEveryFrame returns true if the frame isn't cleared at the beginning.

IsScreenClearedEveryFrame is concurrent-safe.

func IsScreenFilterEnabled deprecated added in v2.3.0 

func IsScreenFilterEnabled() bool

IsScreenFilterEnabled returns true if Ebitengine's "screen" filter is enabled.

IsScreenFilterEnabled is concurrent-safe.

Deprecated: as of v2.5.

func IsScreenTransparent deprecated 

func IsScreenTransparent() bool

IsScreenTransparent reports whether the window is transparent.

IsScreenTransparent is concurrent-safe.

Deprecated: as of v2.5.

func IsStandardGamepadAxisAvailable ¶ added in v2.4.0 

func IsStandardGamepadAxisAvailable(id GamepadID, axis StandardGamepadAxis) bool

IsStandardGamepadAxisAvailable reports whether the standard gamepad axis is available on the gamepad (id).

IsStandardGamepadAxisAvailable is concurrent-safe.

func IsStandardGamepadButtonAvailable ¶ added in v2.4.0 

func IsStandardGamepadButtonAvailable(id GamepadID, button StandardGamepadButton) bool

IsStandardGamepadButtonAvailable reports whether the standard gamepad button is available on the gamepad (id).

IsStandardGamepadButtonAvailable is concurrent-safe.

func IsStandardGamepadButtonPressed ¶ added in v2.2.0 

func IsStandardGamepadButtonPressed(id GamepadID, button StandardGamepadButton) bool

IsStandardGamepadButtonPressed reports whether the given gamepad (id)'s standard gamepad button (button) is pressed.

IsStandardGamepadButtonPressed returns false when the gamepad doesn't have a standard gamepad layout mapping.

IsStandardGamepadButtonPressed is concurrent safe.

func IsStandardGamepadLayoutAvailable ¶ added in v2.2.0 

func IsStandardGamepadLayoutAvailable(id GamepadID) bool

IsStandardGamepadLayoutAvailable reports whether the gamepad (id) has a standard gamepad layout mapping.

IsStandardGamepadLayoutAvailable is concurrent-safe.

func IsVsyncEnabled ¶ 

func IsVsyncEnabled() bool

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

func IsWindowBeingClosed ¶ added in v2.2.0 

func IsWindowBeingClosed() bool

IsWindowBeingClosed returns true when the user is trying to close the window on desktops. As the window is closed immediately by default, you might want to call SetWindowClosingHandled(true) to prevent the window is automatically closed.

IsWindowBeingClosed always returns false if the platform is not a desktop.

IsWindowBeingClosed is concurrent-safe.

func IsWindowClosingHandled ¶ added in v2.2.0 

func IsWindowClosingHandled() bool

IsWindowClosingHandled reports whether the window closing is handled or not on desktops by SetWindowClosingHandled.

IsWindowClosingHandled always returns false if the platform is not a desktop.

IsWindowClosingHandled is concurrent-safe.

func IsWindowDecorated ¶ 

func IsWindowDecorated() bool

IsWindowDecorated reports whether the window is decorated.

IsWindowDecorated is concurrent-safe.

func IsWindowFloating ¶ 

func IsWindowFloating() bool

IsWindowFloating reports whether the window is always shown above all the other windows.

IsWindowFloating returns false if the platform is not a desktop.

IsWindowFloating is concurrent-safe.

func IsWindowMaximized ¶ 

func IsWindowMaximized() bool

IsWindowMaximized reports whether the window is maximized or not.

IsWindowMaximized returns false when the window is not resizable (WindowResizingModeEnabled).

IsWindowMaximized always returns false if the platform is not a desktop.

IsWindowMaximized is concurrent-safe.

func IsWindowMinimized ¶ 

func IsWindowMinimized() bool

IsWindowMinimized reports whether the window is minimized or not.

IsWindowMinimized always returns false if the platform is not a desktop.

IsWindowMinimized is concurrent-safe.

func IsWindowMousePassthrough ¶ added in v2.6.0 

func IsWindowMousePassthrough() bool

IsWindowMousePassthrough reports whether a mouse cursor passthroughs the window or not on desktops.

IsWindowMousePassthrough always returns false if the platform is not a desktop.

IsWindowMousePassthrough is concurrent-safe.

func IsWindowResizable deprecated 

func IsWindowResizable() bool

IsWindowResizable reports whether the window is resizable by the user's dragging on desktops. On the other environments, IsWindowResizable always returns false.

Deprecated: as of v2.3. Use WindowResizingMode instead.

func KeyName ¶ added in v2.5.0 

func KeyName(key Key) string

KeyName returns a key name for the current keyboard layout. For example, KeyName(KeyQ) returns 'q' for a QWERTY keyboard, and returns 'a' for an AZERTY keyboard.

KeyName returns an empty string if 1) the key doesn't have a physical key name, 2) the platform doesn't support KeyName, or 3) the main loop doesn't start yet.

KeyName is supported by desktops and browsers.

KeyName is concurrent-safe.

func MaxTPS deprecated 

func MaxTPS() int

MaxTPS returns the current maximum TPS.

Deprecated: as of v2.4. Use TPS instead.

func MaximizeWindow ¶ 

func MaximizeWindow()

MaximizeWindow maximizes the window.

MaximizeWindow does nothing when the window is not resizable (WindowResizingModeEnabled).

MaximizeWindow does nothing if the platform is not a desktop.

MaximizeWindow is concurrent-safe.

func MinimizeWindow ¶ 

func MinimizeWindow()

MinimizeWindow minimizes the window.

If the main loop does not start yet, MinimizeWindow does nothing.

MinimizeWindow does nothing if the platform is not a desktop.

MinimizeWindow is concurrent-safe.

func ReadDebugInfo ¶ added in v2.4.0 

func ReadDebugInfo(d *DebugInfo)

ReadDebugInfo writes debug info (e.g. current graphics library) into a provided struct.

func RestoreWindow ¶ 

func RestoreWindow()

RestoreWindow restores the window from its maximized or minimized state.

RestoreWindow panics when the window is not maximized nor minimized.

RestoreWindow is concurrent-safe.

func RunGame ¶ 

func RunGame(game Game) error

RunGame starts the main loop and runs the game. game's Update function is called every tick to update the game logic. game's Draw function is called every frame to draw the screen. game's Layout function is called when necessary, and you can specify the logical screen size by the function.

If game implements FinalScreenDrawer, its DrawFinalScreen is called after Draw. The argument screen represents the final screen. The argument offscreen is an offscreen modified at Draw. If game does not implement FinalScreenDrawer, the default rendering for the final screen is used.

game's functions are called on the same goroutine.

On browsers, it is strongly recommended to use iframe if you embed an Ebitengine application in your website.

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

Ebitengine tries to call game's Update function 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).

RunGame returns error when 1) an error happens in the underlying graphics driver, 2) an audio error happens or 3) Update returns an error. In the case of 3), RunGame returns the same error so far, but it is recommended to use errors.Is when you check the returned error is the error you want, rather than comparing the values with == or != directly.

If you want to terminate a game on desktops, it is recommended to return Termination at Update, which will halt execution without returning an error value from RunGame.

The size unit is device-independent pixel.

Don't call RunGame or RunGameWithOptions twice or more in one process.

func RunGameWithOptions ¶ added in v2.5.0 

func RunGameWithOptions(game Game, options *RunGameOptions) error

RunGameWithOptions starts the main loop and runs the game with the specified options. game's Update function is called every tick to update the game logic. game's Draw function is called every frame to draw the screen. game's Layout function is called when necessary, and you can specify the logical screen size by the function.

options can be nil. In this case, the default options are used.

If game implements FinalScreenDrawer, its DrawFinalScreen is called after Draw. The argument screen represents the final screen. The argument offscreen is an offscreen modified at Draw. If game does not implement FinalScreenDrawer, the default rendering for the final screen is used.

game's functions are called on the same goroutine.

On browsers, it is strongly recommended to use iframe if you embed an Ebitengine application in your website.

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

Ebitengine tries to call game's Update function 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).

RunGameWithOptions returns error when 1) an error happens in the underlying graphics driver, 2) an audio error happens or 3) Update returns an error. In the case of 3), RunGameWithOptions returns the same error so far, but it is recommended to use errors.Is when you check the returned error is the error you want, rather than comparing the values with == or != directly.

If you want to terminate a game on desktops, it is recommended to return Termination at Update, which will halt execution without returning an error value from RunGameWithOptions.

The size unit is device-independent pixel.

Don't call RunGame or RunGameWithOptions twice or more in one process.

func ScheduleFrame deprecated added in v2.2.0 

func ScheduleFrame()

ScheduleFrame schedules a next frame when the current FPS mode is FPSModeVsyncOffMinimum.

ScheduleFrame is concurrent-safe.

Deprecated: as of v2.5. Use SetScreenClearedEveryFrame(false) instead. See examples/skipdraw for GPU optimization with SetScreenClearedEveryFrame(false).

func ScreenSizeInFullscreen deprecated 

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 SetSize function if the perfectly fit fullscreen is needed.

On browsers, ScreenSizeInFullscreen returns the 'window' (global object) size, not 'screen' size. ScreenSizeInFullscreen's returning value is different from the actual screen size and this is a known issue (#2145). For browsers, it is recommended to use Screen API (https://developer.mozilla.org/en-US/docs/Web/API/Screen) if needed.

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

ScreenSizeInFullscreen's use cases are limited. If you are making a fullscreen application, you can use RunGame and the Game interface's Layout function instead. If you are making a not-fullscreen application but the application's behavior depends on the monitor size, ScreenSizeInFullscreen is useful.

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

Deprecated: as of v2.6. Use Monitor().Size() instead.

func SetCursorMode ¶ 

func SetCursorMode(mode CursorModeType)

SetCursorMode sets the render and capture mode of the mouse cursor. CursorModeVisible sets the cursor to always be visible. CursorModeHidden hides the system cursor when over the window. CursorModeCaptured hides the system cursor and locks it to the window.

CursorModeCaptured also works on browsers. When the user exits the captured mode not by SetCursorMode but by the UI (e.g., pressing ESC), the previous cursor mode is set automatically.

On browsers, setting CursorModeCaptured might be delayed especially just after escaping from a capture.

On browsers, capturing a cursor requires a user gesture, otherwise SetCursorMode does nothing but leave an error message in console. This behavior varies across browser implementations. Check a user interaction before calling capturing a cursor e.g. by IsMouseButtonPressed or IsKeyPressed.

SetCursorMode does nothing on mobiles.

SetCursorMode is concurrent-safe.

func SetCursorShape ¶ added in v2.1.0 

func SetCursorShape(shape CursorShapeType)

SetCursorShape sets the cursor shape.

If the platform doesn't implement the given shape, the default cursor shape is used.

SetCursorShape is concurrent-safe.

func SetFPSMode deprecated added in v2.2.0 

func SetFPSMode(mode FPSModeType)

SetFPSMode sets the FPS mode. The default FPS mode is FPSModeVsyncOn.

SetFPSMode is concurrent-safe.

Deprecated: as of v2.5. Use SetVsyncEnabled instead.

func SetFullscreen ¶ 

func SetFullscreen(fullscreen bool)

SetFullscreen changes the current mode to fullscreen or not on desktops and browsers.

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

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

On browsers, triggering fullscreen requires a user gesture, otherwise SetFullscreen does nothing but leave an error message in console. This behavior varies across browser implementations. Check a user interaction before triggering fullscreen e.g. by IsMouseButtonPressed or IsKeyPressed.

SetFullscreen does nothing on mobiles.

SetFullscreen does nothing on macOS when the window is fullscreened natively by the macOS desktop instead of SetFullscreen(true).

SetFullscreen is concurrent-safe.

func SetInitFocused deprecated 

func SetInitFocused(focused bool)

SetInitFocused sets whether the application is focused on show. The default value is true, i.e., the application is focused.

SetInitFocused does nothing on mobile.

SetInitFocused panics if this is called after the main loop.

SetInitFocused is concurrent-safe.

Deprecated: as of v2.5. Use RunGameWithOptions instead.

func SetMaxTPS deprecated 

func SetMaxTPS(tps int)

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

Deprecated: as of v2.4. Use SetTPS instead.

func SetMonitor ¶ added in v2.6.0 

func SetMonitor(monitor *MonitorType)

SetMonitor sets the monitor that the window should be on. This can be called before or after Run.

func SetRunnableOnUnfocused ¶ 

func SetRunnableOnUnfocused(runnableOnUnfocused bool)

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

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

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.

SetRunnableOnUnfocused does nothing on mobiles so far.

SetRunnableOnUnfocused is concurrent-safe.

func SetScreenClearedEveryFrame ¶ 

func SetScreenClearedEveryFrame(cleared bool)

SetScreenClearedEveryFrame enables or disables the clearing of the screen at the beginning of each frame. The default value is true and the screen is cleared each frame by default.

SetScreenClearedEveryFrame is concurrent-safe.

func SetScreenFilterEnabled deprecated added in v2.3.0 

func SetScreenFilterEnabled(enabled bool)

SetScreenFilterEnabled enables/disables the use of the "screen" filter Ebitengine uses.

The "screen" filter is a box filter from game to display resolution.

If disabled, nearest-neighbor filtering will be used for scaling instead.

The default state is true.

SetScreenFilterEnabled is concurrent-safe, but takes effect only at the next Draw call.

Deprecated: as of v2.5. Use FinalScreenDrawer instead.

func SetScreenTransparent deprecated 

func SetScreenTransparent(transparent bool)

SetScreenTransparent sets the state if the window is transparent.

SetScreenTransparent panics if SetScreenTransparent is called after the main loop.

SetScreenTransparent does nothing on mobiles.

SetScreenTransparent is concurrent-safe.

Deprecated: as of v2.5. Use RunGameWithOptions instead.

func SetTPS ¶ added in v2.4.0 

func SetTPS(tps int)

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

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

SetTPS is concurrent-safe.

func SetVsyncEnabled ¶ 

func SetVsyncEnabled(enabled bool)

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

func SetWindowClosingHandled ¶ added in v2.2.0 

func SetWindowClosingHandled(handled bool)

SetWindowClosingHandled sets whether the window closing is handled or not on desktops. The default state is false.

If the window closing is handled, the window is not closed immediately and the game can know whether the window is being closed or not by IsWindowBeingClosed. In this case, the window is not closed automatically. To end the game, you have to return an error value at the Game's Update function.

SetWindowClosingHandled works only on desktops. SetWindowClosingHandled does nothing if the platform is not a desktop.

SetWindowClosingHandled 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 if the platform is not a desktop.

SetWindowDecorated is concurrent-safe.

func SetWindowFloating ¶ 

func SetWindowFloating(float bool)

SetWindowFloating sets the state whether the window is always shown above all the other windows.

SetWindowFloating does nothing if the platform is not a desktop.

SetWindowFloating 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 if the platform is not a desktop.

SetWindowIcon is concurrent-safe.

func SetWindowMousePassthrough ¶ added in v2.6.0 

func SetWindowMousePassthrough(enabled bool)

SetWindowMousePassthrough sets whether a mouse cursor passthroughs the window or not on desktops. The default state is false.

Even if this is set true, some platforms might require a window to be undecorated in order to make the mouse cursor passthrough the window.

SetWindowMousePassthrough works only on desktops. SetWindowMousePassthrough does nothing if the platform is not a desktop.

SetWindowMousePassthrough is concurrent-safe.

func SetWindowPosition ¶ 

func SetWindowPosition(x, y int)

SetWindowPosition sets the window position. The origin position is the upper-left corner of the current monitor. The unit is device-independent pixels.

SetWindowPosition sets the original window position in fullscreen mode.

SetWindowPosition does nothing if the platform is not a desktop.

SetWindowPosition is concurrent-safe.

func SetWindowResizable deprecated 

func SetWindowResizable(resizable bool)

SetWindowResizable sets whether the window is resizable by the user's dragging on desktops. On the other environments, SetWindowResizable does nothing.

Deprecated: as of v2.3, Use SetWindowResizingMode instead.

func SetWindowResizingMode ¶ added in v2.3.0 

func SetWindowResizingMode(mode WindowResizingModeType)

SetWindowResizingMode sets the mode in which a user resizes the window.

SetWindowResizingMode is concurrent-safe.

func SetWindowSize ¶ 

func SetWindowSize(width, height int)

SetWindowSize sets the window size on desktops. SetWindowSize does nothing on other environments.

Even if the application is in fullscreen mode, SetWindowSize sets the original window size.

SetWindowSize panics if width or height is not a positive number.

SetWindowSize is concurrent-safe.

func SetWindowSizeLimits ¶ added in v2.1.0 

func SetWindowSizeLimits(minw, minh, maxw, maxh int)

SetWindowSizeLimits sets the limitation of the window size on desktops. A negative value indicates the size is not limited.

SetWindowSizeLimits is concurrent-safe.

func SetWindowTitle ¶ 

func SetWindowTitle(title string)

SetWindowTitle sets the title of the window.

SetWindowTitle does nothing if the platform is not a desktop.

SetWindowTitle is concurrent-safe.

func StandardGamepadAxisValue ¶ added in v2.2.0 

func StandardGamepadAxisValue(id GamepadID, axis StandardGamepadAxis) float64

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

StandardGamepadAxisValue returns 0 when the gamepad doesn't have a standard gamepad layout mapping.

StandardGamepadAxisValue is concurrent safe.

func StandardGamepadButtonValue ¶ added in v2.2.0 

func StandardGamepadButtonValue(id GamepadID, button StandardGamepadButton) float64

StandardGamepadButtonValue returns a float value [0.0 - 1.0] of the given gamepad (id)'s standard button (button).

StandardGamepadButtonValue returns 0 when the gamepad doesn't have a standard gamepad layout mapping.

StandardGamepadButtonValue is concurrent safe.

func TPS ¶ added in v2.4.0 

func TPS() int

TPS returns the current maximum TPS.

TPS is concurrent-safe.

func TouchPosition ¶ 

func TouchPosition(id TouchID) (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 concurrent-safe.

func UpdateStandardGamepadLayoutMappings ¶ added in v2.2.0 

func UpdateStandardGamepadLayoutMappings(mappings string) (bool, error)

UpdateStandardGamepadLayoutMappings parses the specified string mappings in SDL_GameControllerDB format and updates the gamepad layout definitions.

UpdateStandardGamepadLayoutMappings reports whether the mappings were applied, and returns an error in case any occurred while parsing the mappings.

One or more input definitions can be provided separated by newlines. In particular, it is valid to pass an entire gamecontrollerdb.txt file. Note though that Ebitengine already includes its own copy of this file, so this call should only be necessary to add mappings for hardware not supported yet; ideally games using the StandardGamepad* functions should allow the user to provide mappings and then call this function if provided. When using this facility to support new hardware, please also send a pull request to https://github.com/gabomdq/SDL_GameControllerDB to make your mapping available to everyone else.

A platform field in a line corresponds with a GOOS like the following: 

"Windows":  GOOS=windows
"Mac OS X": GOOS=darwin (not ios)
"Linux":    GOOS=linux (not android)
"Android":  GOOS=android
"iOS":      GOOS=ios
"":         Any GOOS

On platforms where gamepad mappings are not managed by Ebitengine, this always returns false and nil.

UpdateStandardGamepadLayoutMappings is concurrent-safe.

UpdateStandardGamepadLayoutMappings mappings take effect immediately even for already connected gamepads.

UpdateStandardGamepadLayoutMappings works atomically. If an error happens, nothing is updated.

func Vibrate ¶ added in v2.3.0 

func Vibrate(options *VibrateOptions)

Vibrate vibrates the device with the specified options.

Vibrate works on mobiles and browsers.

On browsers, Magnitude in the options is ignored.

On Android, this line is required in the manifest setting to use Vibrate: 

<uses-permission android:name="android.permission.VIBRATE"/>

On Android, Magnitude in the options is recognized only when the API Level is 26 or newer. Otherwise, Magnitude is ignored.

On iOS, CoreHaptics.framework is required to use Vibrate.

On iOS, Vibrate works only when iOS version is 13.0 or newer. Otherwise, Vibrate does nothing.

Vibrate is concurrent-safe.

func VibrateGamepad ¶ added in v2.3.0 

func VibrateGamepad(gamepadID GamepadID, options *VibrateGamepadOptions)

VibrateGamepad vibrates the specified gamepad with the specified options.

VibrateGamepad works only on browsers and Nintendo Switch so far.

VibrateGamepad is concurrent-safe.

func Wheel ¶ 

func Wheel() (xoff, yoff float64)

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

Wheel is concurrent-safe.

func WindowPosition ¶ 

func WindowPosition() (x, y int)

WindowPosition returns the window position. The origin position is the upper-left corner of the current monitor. The unit is device-independent pixels.

WindowPosition panics if the main loop does not start yet.

WindowPosition returns the original window position in fullscreen mode.

WindowPosition returns (0, 0) if the platform is not a desktop.

WindowPosition is concurrent-safe.

func WindowSize ¶ 

func WindowSize() (int, int)

WindowSize returns the window size on desktops. WindowSize returns (0, 0) on other environments.

Even if the application is in fullscreen mode, WindowSize returns the original window size If you need the fullscreen dimensions, see Monitor().Size() instead.

WindowSize is concurrent-safe.

func WindowSizeLimits ¶ added in v2.1.0 

func WindowSizeLimits() (minw, minh, maxw, maxh int)

WindowSizeLimits returns the limitation of the window size on desktops. A negative value indicates the size is not limited.

WindowSizeLimits is concurrent-safe.

Types ¶

type Address ¶ 

type Address int

Address represents a sampler address mode. 

const (
	// AddressUnsafe means there is no guarantee when the texture coordinates are out of range.
	AddressUnsafe Address = Address(builtinshader.AddressUnsafe)

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

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

type Blend ¶ added in v2.5.0 

type Blend struct {
	// BlendFactorSourceRGB is a factor for source RGB values.
	BlendFactorSourceRGB BlendFactor

	// BlendFactorSourceAlpha is a factor for source alpha values.
	BlendFactorSourceAlpha BlendFactor

	// BlendFactorDestinationRGB is a factor for destination RGB values.
	BlendFactorDestinationRGB BlendFactor

	// BlendFactorDestinationAlpha is a factor for destination alpha values.
	BlendFactorDestinationAlpha BlendFactor

	// BlendOperationRGB is an operation for source and destination RGB values.
	BlendOperationRGB BlendOperation

	// BlendOperationAlpha is an operation for source and destination alpha values.
	BlendOperationAlpha BlendOperation
}

Blend is a blending way of the source color and the destination color.

The final color is calculated like this: 

c_src: source RGB values
c_dst: destination RGB values
c_out: result RGB values
α_src: source alpha values
α_dst: destination alpha values
α_out: result alpha values

c_out = BlendOperationRGB((BlendFactorSourceRGB) Ă— c_src, (BlendFactorDestinationRGB) Ă— c_dst)
α_out = BlendOperationAlpha((BlendFactorSourceAlpha) × α_src, (BlendFactorDestinationAlpha) × α_dst)

A blend factor is a factor for source and color destination color values. The default is source-over (regular alpha blending).

A blend operation is a binary operator of a source color and a destination color. The default is adding.

type BlendFactor ¶ added in v2.5.0 

type BlendFactor byte

BlendFactor is a factor for source and destination color values. 

const (
	// BlendFactorDefault is the default factor value.
	// The actual value depends on which source or destination this value is used.
	BlendFactorDefault BlendFactor = iota

	// BlendFactorZero is a factor:
	//
	//     0
	BlendFactorZero

	// BlendFactorOne is a factor:
	//
	//     1
	BlendFactorOne

	// BlendFactorSourceColor is a factor:
	//
	//     (source RGBA)
	BlendFactorSourceColor

	// BlendFactorOneMinusSourceColor is a factor:
	//
	//     1 - (source color)
	BlendFactorOneMinusSourceColor

	// BlendFactorSourceAlpha is a factor:
	//
	//     (source alpha)
	BlendFactorSourceAlpha

	// BlendFactorOneMinusSourceAlpha is a factor:
	//
	//     1 - (source alpha)
	BlendFactorOneMinusSourceAlpha

	// BlendFactorDestinationColor is a factor:
	//
	//     (destination RGBA)
	BlendFactorDestinationColor

	// BlendFactorOneMinusDestinationColor is a factor:
	//
	//     1 - (destination RGBA)
	BlendFactorOneMinusDestinationColor

	// BlendFactorDestinationAlpha is a factor:
	//
	//     (destination alpha)
	BlendFactorDestinationAlpha

	// BlendFactorOneMinusDestinationAlpha is a factor:
	//
	//     1 - (destination alpha)
	BlendFactorOneMinusDestinationAlpha
)

type BlendOperation ¶ added in v2.5.0 

type BlendOperation byte

BlendOperation is an operation for source and destination color values. 

const (
	// BlendOperationAdd represents adding the source and destination color.
	//
	//     c_out = (BlendFactorSourceRGB) Ă— c_src + (BlendFactorDestinationRGB) Ă— c_dst
	//     α_out = (BlendFactorSourceAlpha) × α_src + (BlendFactorDestinationAlpha) × α_dst
	BlendOperationAdd BlendOperation = iota

	// BlendOperationSubtract represents subtracting the source and destination color.
	//
	//     c_out = (BlendFactorSourceRGB) Ă— c_src - (BlendFactorDestinationRGB) Ă— c_dst
	//     α_out = (BlendFactorSourceAlpha) × α_src - (BlendFactorDestinationAlpha) × α_dst
	BlendOperationSubtract

	// BlendOperationReverseSubtract represents subtracting the source and destination color in a reversed order.
	//
	//     c_out = (BlendFactorDestinationRGB) Ă— c_dst - (BlendFactorSourceRGB) Ă— c_src
	//     α_out = (BlendFactorDestinationAlpha) × α_dst - (BlendFactorSourceAlpha) × α_src
	BlendOperationReverseSubtract

	// BlendOperationMin represents a minimum function for the source and destination color.
	// If BlendOperationMin is specified, blend factors are not used.
	//
	//     c_out = min(c_dst, c_src)
	//     α_out = min(α_dst, α_src)
	BlendOperationMin

	// BlendOperationMax represents a maximum function for the source and destination color.
	// If BlendOperationMax is specified, blend factors are not used.
	//
	//     c_out = max(c_dst, c_src)
	//     α_out = max(α_dst, α_src)
	BlendOperationMax
)

type ColorM deprecated 

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.

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Apply deprecated 

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.

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) ChangeHSV deprecated 

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.

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Concat deprecated 

func (c *ColorM) Concat(other ColorM)

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

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Element deprecated 

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

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

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Invert deprecated 

func (c *ColorM) Invert()

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

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) IsInvertible deprecated 

func (c *ColorM) IsInvertible() bool

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

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Reset deprecated 

func (c *ColorM) Reset()

Reset resets the ColorM as identity.

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) RotateHue deprecated 

func (c *ColorM) RotateHue(theta float64)

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

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Scale deprecated 

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

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

Deprecated: as of v2.5. Use ColorScale or the colorm package instead.

func (*ColorM) ScaleWithColor deprecated added in v2.3.0 

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

ScaleWithColor scales the matrix by clr.

Deprecated: as of v2.5. Use ColorScale or the colorm package instead.

func (*ColorM) SetElement deprecated 

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

SetElement sets an element at (i, j).

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) String deprecated 

func (c *ColorM) String() string

String returns a string representation of ColorM.

Deprecated: as of v2.5. Use the colorm package instead.

func (*ColorM) Translate deprecated 

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

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

Deprecated: as of v2.5. Use the colorm package instead.

type ColorScale ¶ added in v2.5.0 

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

ColorScale represents a scale of RGBA color. ColorScale is intended to be applied to a premultiplied-alpha color value.

The initial (zero) value of ColorScale is an identity scale (1, 1, 1, 1).

func (*ColorScale) A ¶ added in v2.5.0 

func (c *ColorScale) A() float32

A returns the alpha scale.

func (*ColorScale) B ¶ added in v2.5.0 

func (c *ColorScale) B() float32

B returns the blue scale.

func (*ColorScale) G ¶ added in v2.5.0 

func (c *ColorScale) G() float32

G returns the green scale.

func (*ColorScale) R ¶ added in v2.5.0 

func (c *ColorScale) R() float32

R returns the red scale.

func (*ColorScale) Reset ¶ added in v2.5.0 

func (c *ColorScale) Reset()

Reset resets the ColorScale as identity.

func (*ColorScale) Scale ¶ added in v2.5.0 

func (c *ColorScale) Scale(r, g, b, a float32)

Scale multiplies the given values to the current scale.

Scale is slightly different from colorm.ColorM's Scale in terms of alphas. ColorScale is applied to premultiplied-alpha colors, while colorm.ColorM is applied to straight-alpha colors. Thus, ColorM.Scale(r, g, b, a) equals to ColorScale.Scale(r*a, g*a, b*a, a).

func (*ColorScale) ScaleAlpha ¶ added in v2.5.0 

func (c *ColorScale) ScaleAlpha(a float32)

ScaleAlpha multiplies the given alpha value to the current scale.

func (*ColorScale) ScaleWithColor ¶ added in v2.5.0 

func (c *ColorScale) ScaleWithColor(clr color.Color)

ScaleWithColor multiplies the given color values to the current scale.

func (*ColorScale) ScaleWithColorScale ¶ added in v2.6.0 

func (c *ColorScale) ScaleWithColorScale(colorScale ColorScale)

ScaleWithColorScale multiplies the given color scale values to the current scale.

func (*ColorScale) SetA ¶ added in v2.5.0 

func (c *ColorScale) SetA(a float32)

SetA overwrites the current alpha value with a.

func (*ColorScale) SetB ¶ added in v2.5.0 

func (c *ColorScale) SetB(b float32)

SetB overwrites the current blue value with b.

func (*ColorScale) SetG ¶ added in v2.5.0 

func (c *ColorScale) SetG(g float32)

SetG overwrites the current green value with g.

func (*ColorScale) SetR ¶ added in v2.5.0 

func (c *ColorScale) SetR(r float32)

SetR overwrites the current red value with r.

func (*ColorScale) String ¶ added in v2.5.0 

func (c *ColorScale) String() string

String returns a string representing the color scale.

type ColorScaleMode ¶ added in v2.5.0 

type ColorScaleMode int

ColorScaleMode is the mode of color scales in vertices. 

const (
	// ColorScaleModeStraightAlpha indicates color scales in vertices are
	// straight-alpha encoded color multiplier.
	ColorScaleModeStraightAlpha ColorScaleMode = iota

	// ColorScaleModePremultipliedAlpha indicates color scales in vertices are
	// premultiplied-alpha encoded color multiplier.
	ColorScaleModePremultipliedAlpha
)

type ColorSpace ¶ added in v2.8.0 

type ColorSpace int

ColorSpace represents the color space of the screen. 

const (
	// ColorSpaceDefault represents the default color space.
	ColorSpaceDefault ColorSpace = iota

	// ColorSpaceSRGB represents the sRGB color space (https://en.wikipedia.org/wiki/SRGB).
	ColorSpaceSRGB

	// ColorSpaceDisplayP3 represents the Display P3 color space (https://en.wikipedia.org/wiki/DCI-P3).
	ColorSpaceDisplayP3
)

type CompositeMode deprecated 

type CompositeMode int

CompositeMode represents Porter-Duff composition mode.

Deprecated: as of v2.5. Use Blend instead. 

const (
	// CompositeModeCustom indicates to refer Blend.
	CompositeModeCustom CompositeMode = iota

	// Deprecated: as of v2.5. Use BlendSourceOver instead.
	CompositeModeSourceOver

	// Deprecated: as of v2.5. Use BlendClear instead.
	CompositeModeClear

	// Deprecated: as of v2.5. Use BlendCopy instead.
	CompositeModeCopy

	// Deprecated: as of v2.5. Use BlendDestination instead.
	CompositeModeDestination

	// Deprecated: as of v2.5. Use BlendDestinationOver instead.
	CompositeModeDestinationOver

	// Deprecated: as of v2.5. Use BlendSourceIn instead.
	CompositeModeSourceIn

	// Deprecated: as of v2.5. Use BlendDestinationIn instead.
	CompositeModeDestinationIn

	// Deprecated: as of v2.5. Use BlendSourceOut instead.
	CompositeModeSourceOut

	// Deprecated: as of v2.5. Use BlendDestinationOut instead.
	CompositeModeDestinationOut

	// Deprecated: as of v2.5. Use BlendSourceAtop instead.
	CompositeModeSourceAtop

	// Deprecated: as of v2.5. Use BlendDestinationAtop instead.
	CompositeModeDestinationAtop

	// Deprecated: as of v2.5. Use BlendXor instead.
	CompositeModeXor

	// Deprecated: as of v2.5. Use BlendLighter instead.
	CompositeModeLighter

	// Deprecated: as of v2.5. Use Blend with BlendFactorDestinationColor and BlendFactorZero instead.
	CompositeModeMultiply
)

type CursorModeType ¶ 

type CursorModeType = ui.CursorMode

CursorModeType represents a render and coordinate mode of a mouse cursor. 

const (
	CursorModeVisible  CursorModeType = ui.CursorModeVisible
	CursorModeHidden   CursorModeType = ui.CursorModeHidden
	CursorModeCaptured CursorModeType = ui.CursorModeCaptured
)

CursorModeTypes

func CursorMode ¶ 

func CursorMode() CursorModeType

CursorMode returns the current cursor mode.

CursorMode returns CursorModeHidden on mobiles.

CursorMode is concurrent-safe.

type CursorShapeType ¶ added in v2.1.0 

type CursorShapeType = ui.CursorShape

CursorShapeType represents a shape of a mouse cursor. 

const (
	CursorShapeDefault    CursorShapeType = CursorShapeType(ui.CursorShapeDefault)
	CursorShapeText       CursorShapeType = CursorShapeType(ui.CursorShapeText)
	CursorShapeCrosshair  CursorShapeType = CursorShapeType(ui.CursorShapeCrosshair)
	CursorShapePointer    CursorShapeType = CursorShapeType(ui.CursorShapePointer)
	CursorShapeEWResize   CursorShapeType = CursorShapeType(ui.CursorShapeEWResize)
	CursorShapeNSResize   CursorShapeType = CursorShapeType(ui.CursorShapeNSResize)
	CursorShapeNESWResize CursorShapeType = CursorShapeType(ui.CursorShapeNESWResize)
	CursorShapeNWSEResize CursorShapeType = CursorShapeType(ui.CursorShapeNWSEResize)
	CursorShapeMove       CursorShapeType = CursorShapeType(ui.CursorShapeMove)
	CursorShapeNotAllowed CursorShapeType = CursorShapeType(ui.CursorShapeNotAllowed)
)

CursorShapeTypes

func CursorShape ¶ added in v2.1.0 

func CursorShape() CursorShapeType

CursorShape returns the current cursor shape.

CursorShape returns CursorShapeDefault on mobiles.

CursorShape is concurrent-safe.

type DebugInfo ¶ added in v2.4.0 

type DebugInfo struct {
	// GraphicsLibrary represents the graphics library currently in use.
	GraphicsLibrary GraphicsLibrary
}

DebugInfo is a struct to store debug info about the graphics.

type DrawImageOptions ¶ 

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

	// ColorScale is a scale of color.
	//
	// ColorScale is slightly different from colorm.ColorM's Scale in terms of alphas.
	// ColorScale is applied to premultiplied-alpha colors, while colorm.ColorM is applied to straight-alpha colors.
	// Thus, ColorM.Scale(r, g, b, a) equals to ColorScale.Scale(r*a, g*a, b*a, a).
	//
	// The default (zero) value is identity, which is (1, 1, 1, 1).
	ColorScale ColorScale

	// ColorM is a color matrix to draw.
	// The default (zero) value is identity, which doesn't change any color.
	//
	// Deprecated: as of v2.5. Use ColorScale or the package colorm instead.
	ColorM ColorM

	// CompositeMode is a composite mode to draw.
	// The default (zero) value is CompositeModeCustom (Blend is used).
	//
	// Deprecated: as of v2.5. Use Blend instead.
	CompositeMode CompositeMode

	// Blend is a blending way of the source color and the destination color.
	// Blend is used only when CompositeMode is CompositeModeCustom.
	// The default (zero) value is the regular alpha blending.
	Blend Blend

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

	// DisableMipmaps disables mipmaps.
	// When Filter is FilterLinear and GeoM shrinks the image, mipmaps are used by default.
	// Mipmap is useful to render a shrunk image with high quality.
	// However, mipmaps can be expensive, especially on mobiles.
	// When DisableMipmaps is true, mipmap is not used.
	// When Filter is not FilterLinear, DisableMipmaps is ignored.
	//
	// The default (zero) value is false.
	DisableMipmaps bool
}

DrawImageOptions represents options for DrawImage.

type DrawRectShaderOptions ¶ 

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

	// ColorScale is a scale of color.
	// This scaling values are passed to the `color vec4` argument of the Fragment function in a Kage program.
	// The default (zero) value is identity, which is (1, 1, 1, 1).
	ColorScale ColorScale

	// CompositeMode is a composite mode to draw.
	// The default (zero) value is CompositeModeCustom (Blend is used).
	//
	// Deprecated: as of v2.5. Use Blend instead.
	CompositeMode CompositeMode

	// Blend is a blending way of the source color and the destination color.
	// Blend is used only when CompositeMode is CompositeModeCustom.
	// The default (zero) value is the regular alpha blending.
	Blend Blend

	// Uniforms is a set of uniform variables for the shader.
	// The keys are the names of the uniform variables.
	// The values must be a numeric type, or a slice or an array of a numeric type.
	// If the uniform variable type is an array, a vector or a matrix,
	// you have to specify linearly flattened values as a slice or an array.
	// For example, if the uniform variable type is [4]vec4, the length will be 16.
	//
	// If a uniform variable's name doesn't exist in Uniforms, this is treated as if zero values are specified.
	Uniforms map[string]any

	// Images is a set of the source images.
	// All the images' sizes must be the same.
	Images [4]*Image
}

DrawRectShaderOptions represents options for DrawRectShader.

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.
	//
	// Deprecated: as of v2.5. Use the package colorm instead.
	ColorM ColorM

	// ColorScaleMode is the mode of color scales in vertices.
	// ColorScaleMode affects the color calculation with vertex colors, but doesn't affect with a color matrix.
	// The default (zero) value is ColorScaleModeStraightAlpha.
	ColorScaleMode ColorScaleMode

	// CompositeMode is a composite mode to draw.
	// The default (zero) value is CompositeModeCustom (Blend is used).
	//
	// Deprecated: as of v2.5. Use Blend instead.
	CompositeMode CompositeMode

	// Blend is a blending way of the source color and the destination color.
	// Blend is used only when CompositeMode is CompositeModeCustom.
	// The default (zero) value is the regular alpha blending.
	Blend Blend

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

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

	// FillRule indicates the rule how an overlapped region is rendered.
	//
	// The rules FillRuleNonZero and FillRuleEvenOdd are useful when you want to render a complex polygon.
	// A complex polygon is a non-convex polygon like a concave polygon, a polygon with holes, or a self-intersecting polygon.
	// See examples/vector for actual usages.
	//
	// The default (zero) value is FillRuleFillAll.
	FillRule FillRule

	// AntiAlias indicates whether the rendering uses anti-alias or not.
	// AntiAlias is useful especially when you pass vertices from the vector package.
	//
	// AntiAlias increases internal draw calls and might affect performance.
	// Use the build tag `ebitenginedebug` to check the number of draw calls if you care.
	//
	// The default (zero) value is false.
	AntiAlias bool

	// DisableMipmaps disables mipmaps.
	// When Filter is FilterLinear and GeoM shrinks the image, mipmaps are used by default.
	// Mipmap is useful to render a shrunk image with high quality.
	// However, mipmaps can be expensive, especially on mobiles.
	// When DisableMipmaps is true, mipmap is not used.
	// When Filter is not FilterLinear, DisableMipmaps is ignored.
	//
	// The default (zero) value is false.
	DisableMipmaps bool
}

DrawTrianglesOptions represents options for DrawTriangles.

type DrawTrianglesShaderOptions ¶ 

type DrawTrianglesShaderOptions struct {
	// CompositeMode is a composite mode to draw.
	// The default (zero) value is CompositeModeCustom (Blend is used).
	//
	// Deprecated: as of v2.5. Use Blend instead.
	CompositeMode CompositeMode

	// Blend is a blending way of the source color and the destination color.
	// Blend is used only when CompositeMode is CompositeModeCustom.
	// The default (zero) value is the regular alpha blending.
	Blend Blend

	// Uniforms is a set of uniform variables for the shader.
	// The keys are the names of the uniform variables.
	// The values must be a numeric type, or a slice or an array of a numeric type.
	// If the uniform variable type is an array, a vector or a matrix,
	// you have to specify linearly flattened values as a slice or an array.
	// For example, if the uniform variable type is [4]vec4, the length will be 16.
	//
	// If a uniform variable's name doesn't exist in Uniforms, this is treated as if zero values are specified.
	Uniforms map[string]any

	// Images is a set of the source images.
	// All the images' sizes must be the same.
	Images [4]*Image

	// FillRule indicates the rule how an overlapped region is rendered.
	//
	// The rules FillRuleNonZero and FillRuleEvenOdd are useful when you want to render a complex polygon.
	// A complex polygon is a non-convex polygon like a concave polygon, a polygon with holes, or a self-intersecting polygon.
	// See examples/vector for actual usages.
	//
	// The default (zero) value is FillRuleFillAll.
	FillRule FillRule

	// AntiAlias indicates whether the rendering uses anti-alias or not.
	// AntiAlias is useful especially when you pass vertices from the vector package.
	//
	// AntiAlias increases internal draw calls and might affect performance.
	// Use the build tag `ebitenginedebug` to check the number of draw calls if you care.
	//
	// The default (zero) value is false.
	AntiAlias bool
}

DrawTrianglesShaderOptions represents options for DrawTrianglesShader.

type FPSModeType deprecated added in v2.2.0 

type FPSModeType = ui.FPSModeType

FPSModeType is a type of FPS modes.

Deprecated: as of v2.5. Use SetVsyncEnabled instead. 

const (
	// FPSModeVsyncOn indicates that the game tries to sync the display's refresh rate.
	// FPSModeVsyncOn is the default mode.
	//
	// Deprecated: as of v2.5. Use SetVsyncEnabled(true) instead.
	FPSModeVsyncOn FPSModeType = ui.FPSModeVsyncOn

	// FPSModeVsyncOffMaximum indicates that the game doesn't sync with vsync, and
	// the game is updated whenever possible.
	//
	// Be careful that FPSModeVsyncOffMaximum might consume a lot of battery power.
	//
	// In FPSModeVsyncOffMaximum, the game's Draw is called almost without sleeping.
	// The game's Update is called based on the specified TPS.
	//
	// Deprecated: as of v2.5. Use SetVsyncEnabled(false) instead.
	FPSModeVsyncOffMaximum FPSModeType = ui.FPSModeVsyncOffMaximum

	// FPSModeVsyncOffMinimum indicates that the game doesn't sync with vsync, and
	// the game is updated only when necessary.
	//
	// FPSModeVsyncOffMinimum is useful for relatively static applications to save battery power.
	//
	// In FPSModeVsyncOffMinimum, the game's Update and Draw are called only when
	// 1) new inputting except for gamepads is detected, or 2) ScheduleFrame is called.
	// In FPSModeVsyncOffMinimum, TPS is SyncWithFPS no matter what TPS is specified at SetTPS.
	//
	// Deprecated: as of v2.5. Use SetScreenClearedEveryFrame(false) instead.
	// See examples/skipdraw for GPU optimization with SetScreenClearedEveryFrame(false).
	FPSModeVsyncOffMinimum FPSModeType = ui.FPSModeVsyncOffMinimum
)

func FPSMode deprecated added in v2.2.0 

func FPSMode() FPSModeType

FPSMode returns the current FPS mode.

FPSMode is concurrent-safe.

Deprecated: as of v2.5. Use SetVsyncEnabled instead.

type FillRule ¶ added in v2.2.0 

type FillRule int

FillRule is the rule whether an overlapped region is rendered with DrawTriangles(Shader). 

const (
	// FillRuleFillAll indicates all the triangles are rendered regardless of overlaps.
	FillRuleFillAll FillRule = FillRule(graphicsdriver.FillRuleFillAll)

	// FillRuleNonZero means that triangles are rendered based on the non-zero rule.
	// If and only if the number of overlaps is not 0, the region is rendered.
	FillRuleNonZero FillRule = FillRule(graphicsdriver.FillRuleNonZero)

	// FillRuleEvenOdd means that triangles are rendered based on the even-odd rule.
	// If and only if the number of overlaps is odd, the region is rendered.
	FillRuleEvenOdd FillRule = FillRule(graphicsdriver.FillRuleEvenOdd)
)

type Filter ¶ 

type Filter int

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

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

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

type FinalScreen ¶ added in v2.5.0 

type FinalScreen interface {
	Bounds() image.Rectangle

	DrawImage(img *Image, options *DrawImageOptions)
	DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)
	DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)
	DrawTrianglesShader(vertices []Vertex, indices []uint16, shader *Shader, options *DrawTrianglesShaderOptions)
	Clear()
	Fill(clr color.Color)
	// contains filtered or unexported methods
}

FinalScreen represents the final screen image. FinalScreen implements a part of Image functions.

type FinalScreenDrawer ¶ added in v2.5.0 

type FinalScreenDrawer interface {
	// DrawFinalScreen draws the final screen.
	// If a game implementing FinalScreenDrawer is passed to RunGame, DrawFinalScreen is called after Draw.
	// screen is the final screen. offscreen is the offscreen modified at Draw.
	//
	// geoM is the default geometry matrix to render the offscreen onto the final screen.
	// geoM scales the offscreen to fit the final screen without changing the aspect ratio, and
	// translates the offscreen to put it in the center of the final screen.
	DrawFinalScreen(screen FinalScreen, offscreen *Image, geoM GeoM)
}

FinalScreenDrawer is an interface for a custom function to render the final screen. For an actual usage, see examples/flappy.

type Game ¶ 

type Game interface {
	// Update updates a game by one tick. The given argument represents a screen image.
	//
	// Update updates only the game logic and Draw draws the screen.
	//
	// You can assume that Update is always called TPS-times per second (60 by default), and you can assume
	// that the time delta between two Updates is always 1 / TPS [s] (1/60[s] by default). As Ebitengine already
	// adjusts the number of Update calls, you don't have to measure time deltas in Update by e.g. OS timers.
	//
	// An actual TPS is available by ActualTPS(), and the result might slightly differ from your expected TPS,
	// but still, your game logic should stick to the fixed time delta and should not rely on ActualTPS() value.
	// This API is for just measurement and/or debugging. In the long run, the number of Update calls should be
	// adjusted based on the set TPS on average.
	//
	// An actual time delta between two Updates might be bigger than expected. In this case, your game's
	// Update or Draw takes longer than they should. In this case, there is nothing other than optimizing
	// your game implementation.
	//
	// In the first frame, it is ensured that Update is called at least once before Draw. You can use Update
	// to initialize the game state.
	//
	// After the first frame, Update might not be called or might be called once
	// or more for one frame. The frequency is determined by the current TPS (tick-per-second).
	//
	// If the error returned is nil, game execution proceeds normally.
	// If the error returned is Termination, game execution halts, but does not return an error from RunGame.
	// If the error returned is any other non-nil value, game execution halts and the error is returned from RunGame.
	Update() error

	// Draw draws the game screen by one frame.
	//
	// The give argument represents a screen image. The updated content is adopted as the game screen.
	//
	// The frequency of Draw calls depends on the user's environment, especially the monitors refresh rate.
	// For portability, you should not put your game logic in Draw in general.
	Draw(screen *Image)

	// Layout accepts a native outside size in device-independent pixels and returns the game's logical screen
	// size in pixels. The logical size is used for 1) the screen size given at Draw and 2) calculation of the
	// scale from the screen to the final screen size.
	//
	// On desktops, the outside is a window or a monitor (fullscreen mode). On browsers, the outside is a body
	// element. On mobiles, the outside is the view's size.
	//
	// Even though the outside size and the screen size differ, the rendering scale is automatically adjusted to
	// fit with the outside.
	//
	// Layout is called almost every frame.
	//
	// It is ensured that Layout is invoked before Update is called in the first frame.
	//
	// If Layout returns non-positive numbers, the caller can panic.
	//
	// You can return a fixed screen size if you don't care, or you can also return a calculated screen size
	// adjusted with the given outside size.
	//
	// If the game implements the interface LayoutFer, Layout is never called and LayoutF is called instead.
	Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int)
}

Game defines necessary functions for a game.

type GamepadAxisType ¶ added in v2.7.0 

type GamepadAxisType = int

GamepadAxisType represents a gamepad axis. This is the same as int for backward compatibility in v2.

type GamepadButton ¶ 

type GamepadButton = gamepad.Button

GamepadButton represents a gamepad button. 

const (
	GamepadButton0   GamepadButton = gamepad.Button0
	GamepadButton1   GamepadButton = gamepad.Button1
	GamepadButton2   GamepadButton = gamepad.Button2
	GamepadButton3   GamepadButton = gamepad.Button3
	GamepadButton4   GamepadButton = gamepad.Button4
	GamepadButton5   GamepadButton = gamepad.Button5
	GamepadButton6   GamepadButton = gamepad.Button6
	GamepadButton7   GamepadButton = gamepad.Button7
	GamepadButton8   GamepadButton = gamepad.Button8
	GamepadButton9   GamepadButton = gamepad.Button9
	GamepadButton10  GamepadButton = gamepad.Button10
	GamepadButton11  GamepadButton = gamepad.Button11
	GamepadButton12  GamepadButton = gamepad.Button12
	GamepadButton13  GamepadButton = gamepad.Button13
	GamepadButton14  GamepadButton = gamepad.Button14
	GamepadButton15  GamepadButton = gamepad.Button15
	GamepadButton16  GamepadButton = gamepad.Button16
	GamepadButton17  GamepadButton = gamepad.Button17
	GamepadButton18  GamepadButton = gamepad.Button18
	GamepadButton19  GamepadButton = gamepad.Button19
	GamepadButton20  GamepadButton = gamepad.Button20
	GamepadButton21  GamepadButton = gamepad.Button21
	GamepadButton22  GamepadButton = gamepad.Button22
	GamepadButton23  GamepadButton = gamepad.Button23
	GamepadButton24  GamepadButton = gamepad.Button24
	GamepadButton25  GamepadButton = gamepad.Button25
	GamepadButton26  GamepadButton = gamepad.Button26
	GamepadButton27  GamepadButton = gamepad.Button27
	GamepadButton28  GamepadButton = gamepad.Button28
	GamepadButton29  GamepadButton = gamepad.Button29
	GamepadButton30  GamepadButton = gamepad.Button30
	GamepadButton31  GamepadButton = gamepad.Button31
	GamepadButtonMax GamepadButton = GamepadButton31
)

GamepadButtons

type GamepadID ¶ 

type GamepadID = gamepad.ID

GamepadID represents a gamepad identifier.

func AppendGamepadIDs ¶ added in v2.2.0 

func AppendGamepadIDs(gamepadIDs []GamepadID) []GamepadID

AppendGamepadIDs appends available gamepad IDs to gamepadIDs, and returns the extended buffer. Giving a slice that already has enough capacity works efficiently.

AppendGamepadIDs is concurrent-safe.

func GamepadIDs deprecated 

func GamepadIDs() []GamepadID

GamepadIDs returns a slice indicating available gamepad IDs.

Deprecated: as of v2.2. Use AppendGamepadIDs instead.

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 (*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 multiplying 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 GraphicsLibrary ¶ added in v2.4.0 

type GraphicsLibrary int

GraphicsLibrary represents graphics libraries supported by the engine. 

const (
	// GraphicsLibraryAuto represents the automatic choose of graphics library by Ebitengine.
	GraphicsLibraryAuto GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryAuto)

	// GraphicsLibraryUnknown represents the state at which graphics library cannot be determined,
	// e.g. hasn't loaded yet or failed to initialize.
	GraphicsLibraryUnknown GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryUnknown)

	// GraphicsLibraryOpenGL represents the graphics library OpenGL.
	GraphicsLibraryOpenGL GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryOpenGL)

	// GraphicsLibraryDirectX represents the graphics library Microsoft DirectX.
	GraphicsLibraryDirectX GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryDirectX)

	// GraphicsLibraryMetal represents the graphics library Apple's Metal.
	GraphicsLibraryMetal GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryMetal)

	// GraphicsLibraryMetal represents the graphics library PlayStation 5.
	GraphicsLibraryPlayStation5 GraphicsLibrary = GraphicsLibrary(ui.GraphicsLibraryPlayStation5)
)

func (GraphicsLibrary) String ¶ added in v2.5.0 

func (g GraphicsLibrary) String() string

String returns a string representing the graphics library.

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 the standard image.Image and draw.Image interfaces.

func NewImage ¶ 

func NewImage(width, height int) *Image

NewImage returns an empty image.

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

NewImage should be called only when necessary. For example, you should avoid to call NewImage every Update or Draw call. Reusing the same image by Clear is much more efficient than creating a new image.

NewImage panics if RunGame already finishes.

func NewImageFromImage ¶ 

func NewImageFromImage(source image.Image) *Image

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.

NewImageFromImage should be called only when necessary. For example, you should avoid to call NewImageFromImage every Update or Draw call. Reusing the same image by Clear and WritePixels is much more efficient than creating a new image.

NewImageFromImage panics if RunGame already finishes.

The returned image's upper-left position is always (0, 0). The source's bounds are not respected.

func NewImageFromImageWithOptions ¶ added in v2.4.0 

func NewImageFromImageWithOptions(source image.Image, options *NewImageFromImageOptions) *Image

NewImageFromImageWithOptions creates a new image with the given image (source) with the given options.

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

If options is nil, the default setting is used.

NewImageFromImageWithOptions should be called only when necessary. For example, you should avoid to call NewImageFromImageWithOptions every Update or Draw call. Reusing the same image by Clear and WritePixels is much more efficient than creating a new image.

NewImageFromImageWithOptions panics if RunGame already finishes.

func NewImageWithOptions ¶ added in v2.4.0 

func NewImageWithOptions(bounds image.Rectangle, options *NewImageOptions) *Image

NewImageWithOptions returns an empty image with the given bounds and the options.

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

The rendering origin position is (0, 0) of the given bounds. If DrawImage is called on a new image created by NewImageOptions, for example, the center of scaling and rotating is (0, 0), that might not be an upper-left position.

If options is nil, the default setting is used.

NewImageWithOptions should be called only when necessary. For example, you should avoid to call NewImageWithOptions every Update or Draw call. Reusing the same image by Clear is much more efficient than creating a new image.

NewImageWithOptions panics if RunGame already finishes.

func (*Image) At ¶ 

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

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

At implements the standard image.Image's At.

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

func (*Image) Bounds ¶ 

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

Bounds returns the bounds of the image.

Bounds implements the standard image.Image's Bounds.

func (*Image) Clear ¶ 

func (i *Image) Clear()

Clear resets the pixels of the image into 0.

When the image is disposed, Clear does nothing.

func (*Image) ColorModel ¶ 

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

ColorModel returns the color model of the image.

ColorModel implements the standard image.Image's ColorModel.

func (*Image) Deallocate ¶ added in v2.7.0 

func (i *Image) Deallocate()

Deallocate clears the image and deallocates the internal state of the image. Even after Deallocate is called, the image is still available. In this case, the image's internal state is allocated again.

Usually, you don't have to call Deallocate since the internal state is automatically released by GC. However, if you are sure that the image is no longer used but not sure how this image object is referred, you can call Deallocate to make sure that the internal state is deallocated.

If the image is a sub-image, Deallocate does nothing.

If the image is disposed, Deallocate does nothing.

func (*Image) Dispose deprecated 

func (i *Image) Dispose()

Dispose disposes the image data. After disposing, most of the 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.

If the image is a sub-image, Dispose does nothing.

If the image is disposed, Dispose does nothing.

Deprecated: as of v2.7. Use Deallocate instead.

func (*Image) DrawImage ¶ 

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

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 the same (A in A.DrawImage(B, op))
  • All Blend values are the same
  • All Filter values are the same

A whole image and its sub-image are considered to be the same, but some environments like browsers might not work efficiently (#2471).

Even when all the above conditions are satisfied, multiple draw commands can be used in really rare cases. Ebitengine 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. 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://ebitengine.org/en/documents/performancetips.html

func (*Image) DrawRectShader ¶ 

func (i *Image) DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)

DrawRectShader draws a rectangle with the specified width and height with the specified shader.

For the details about the shader, see https://ebitengine.org/en/documents/shader.html.

When one of the specified image is non-nil and its size is different from (width, height), DrawRectShader panics. When one of the specified image is non-nil and is disposed, DrawRectShader panics.

If a specified uniform variable's length or type doesn't match with an expected one, DrawRectShader panics.

In a shader, srcPos in Fragment represents a position in a source image. If no source images are specified, srcPos represents the position from (0, 0) to (width, height) in pixels. If the unit is pixels by a compiler directive `//kage:unit pixelss`, srcPos values are valid. If the unit is texels (default), srcPos values still take from (0, 0) to (width, height), but these are invalid since srcPos is expected to be in texels in the texel-unit mode. This behavior is preserved for backward compatibility. It is recommended to use the pixel-unit mode to avoid confusion.

If no source images are specified, imageSrc0Size returns a valid size only when the unit is pixels, but always returns 0 when the unit is texels (default).

Even if a result is an invalid color as a premultiplied-alpha color, i.e. an alpha value exceeds other color values, the value is kept and is not clamped.

When the image i is disposed, DrawRectShader does nothing.

func (*Image) DrawTriangles ¶ 

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

DrawTriangles draws triangles with the specified vertices and their indices.

img is used as a source image. img cannot be nil. If you want to draw triangles with a solid color, use a small white image and adjust the color elements in the vertices. For an actual implementation, see the example 'vector'.

Vertex contains color values, which are interpreted as straight-alpha colors by default. This depends on the option's ColorScaleMode.

If len(vertices) is more than MaxVertexCount, the exceeding part is ignored.

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

If a value in indices is out of range of vertices, or not less than MaxVertexCount, DrawTriangles panics.

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

When the given image is disposed, DrawTriangles panics.

When the image i is disposed, DrawTriangles does nothing.

func (*Image) DrawTrianglesShader ¶ 

func (i *Image) DrawTrianglesShader(vertices []Vertex, indices []uint16, shader *Shader, options *DrawTrianglesShaderOptions)

DrawTrianglesShader draws triangles with the specified vertices and their indices with the specified shader.

Vertex contains color values, which can be interpreted for any purpose by the shader.

For the details about the shader, see https://ebitengine.org/en/documents/shader.html.

If the shader unit is texels, one of the specified image is non-nil and its size is different from (width, height), DrawTrianglesShader panics. If one of the specified image is non-nil and is disposed, DrawTrianglesShader panics.

If len(vertices) is more than MaxVertexCount, the exceeding part is ignored.

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

If a value in indices is out of range of vertices, or not less than MaxVertexCount, DrawTrianglesShader panics.

When a specified image is non-nil and is disposed, DrawTrianglesShader panics.

If a specified uniform variable's length or type doesn't match with an expected one, DrawTrianglesShader panics.

Even if a result is an invalid color as a premultiplied-alpha color, i.e. an alpha value exceeds other color values, the value is kept and is not clamped.

When the image i is disposed, DrawTrianglesShader does nothing.

func (*Image) Fill ¶ 

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

Fill fills the image with a solid color.

When the image is disposed, Fill does nothing.

func (*Image) RGBA64At ¶ added in v2.2.0 

func (i *Image) RGBA64At(x, y int) color.RGBA64

RGBA64At implements the standard image.RGBA64Image's RGBA64At.

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

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

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

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

func (*Image) ReadPixels ¶ added in v2.4.0 

func (i *Image) ReadPixels(pixels []byte)

ReadPixels reads the image's pixels from the image.

The given pixels represent RGBA pre-multiplied alpha values.

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

ReadPixels always sets a transparent color if the image is disposed.

len(pixels) must be 4 * (bounds width) * (bounds height). If len(pixels) is not correct, ReadPixels panics.

ReadPixels also works on a sub-image.

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

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

func (*Image) ReplacePixels deprecated 

func (i *Image) ReplacePixels(pixels []byte)

ReplacePixels replaces the pixels of the image.

Deprecated: as of v2.4. Use WritePixels instead.

func (*Image) Set ¶ 

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

Set sets the color at (x, y).

Set implements the standard draw.Image's Set.

Even if a result is an invalid color as a premultiplied-alpha color, i.e. an alpha value exceeds other color values, the value is kept and is not clamped.

If the image is disposed, Set does nothing.

func (*Image) Size deprecated 

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

Size returns the size of the image.

Deprecated: as of v2.5. Use Bounds().Dx() and Bounds().Dy() or Bounds().Size() instead.

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.

A sub-image returned by SubImage can be used as a rendering source and a rendering destination. If a sub-image is used as a rendering source, the image is used as if it is a small image. If a sub-image is used as a rendering destination, the region being rendered is clipped.

Successive uses of multiple various regions as rendering destination is still efficient when all the underlying images are the same, but some platforms like browsers might not work efficiently.

func (*Image) WritePixels ¶ added in v2.4.0 

func (i *Image) WritePixels(pixels []byte)

WritePixels replaces the pixels of the image.

The given pixels are treated as RGBA pre-multiplied alpha values.

len(pix) must be 4 * (bounds width) * (bounds height). If len(pix) is not correct, WritePixels panics.

WritePixels also works on a sub-image.

Even if a result is an invalid color as a premultiplied-alpha color, i.e. an alpha value exceeds other color values, the value is kept and is not clamped.

When the image is disposed, WritePixels does nothing.

type Key ¶ 

type Key int

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

const (
	KeyA              Key = Key(ui.KeyA)
	KeyB              Key = Key(ui.KeyB)
	KeyC              Key = Key(ui.KeyC)
	KeyD              Key = Key(ui.KeyD)
	KeyE              Key = Key(ui.KeyE)
	KeyF              Key = Key(ui.KeyF)
	KeyG              Key = Key(ui.KeyG)
	KeyH              Key = Key(ui.KeyH)
	KeyI              Key = Key(ui.KeyI)
	KeyJ              Key = Key(ui.KeyJ)
	KeyK              Key = Key(ui.KeyK)
	KeyL              Key = Key(ui.KeyL)
	KeyM              Key = Key(ui.KeyM)
	KeyN              Key = Key(ui.KeyN)
	KeyO              Key = Key(ui.KeyO)
	KeyP              Key = Key(ui.KeyP)
	KeyQ              Key = Key(ui.KeyQ)
	KeyR              Key = Key(ui.KeyR)
	KeyS              Key = Key(ui.KeyS)
	KeyT              Key = Key(ui.KeyT)
	KeyU              Key = Key(ui.KeyU)
	KeyV              Key = Key(ui.KeyV)
	KeyW              Key = Key(ui.KeyW)
	KeyX              Key = Key(ui.KeyX)
	KeyY              Key = Key(ui.KeyY)
	KeyZ              Key = Key(ui.KeyZ)
	KeyAltLeft        Key = Key(ui.KeyAltLeft)
	KeyAltRight       Key = Key(ui.KeyAltRight)
	KeyArrowDown      Key = Key(ui.KeyArrowDown)
	KeyArrowLeft      Key = Key(ui.KeyArrowLeft)
	KeyArrowRight     Key = Key(ui.KeyArrowRight)
	KeyArrowUp        Key = Key(ui.KeyArrowUp)
	KeyBackquote      Key = Key(ui.KeyBackquote)
	KeyBackslash      Key = Key(ui.KeyBackslash)
	KeyBackspace      Key = Key(ui.KeyBackspace)
	KeyBracketLeft    Key = Key(ui.KeyBracketLeft)
	KeyBracketRight   Key = Key(ui.KeyBracketRight)
	KeyCapsLock       Key = Key(ui.KeyCapsLock)
	KeyComma          Key = Key(ui.KeyComma)
	KeyContextMenu    Key = Key(ui.KeyContextMenu)
	KeyControlLeft    Key = Key(ui.KeyControlLeft)
	KeyControlRight   Key = Key(ui.KeyControlRight)
	KeyDelete         Key = Key(ui.KeyDelete)
	KeyDigit0         Key = Key(ui.KeyDigit0)
	KeyDigit1         Key = Key(ui.KeyDigit1)
	KeyDigit2         Key = Key(ui.KeyDigit2)
	KeyDigit3         Key = Key(ui.KeyDigit3)
	KeyDigit4         Key = Key(ui.KeyDigit4)
	KeyDigit5         Key = Key(ui.KeyDigit5)
	KeyDigit6         Key = Key(ui.KeyDigit6)
	KeyDigit7         Key = Key(ui.KeyDigit7)
	KeyDigit8         Key = Key(ui.KeyDigit8)
	KeyDigit9         Key = Key(ui.KeyDigit9)
	KeyEnd            Key = Key(ui.KeyEnd)
	KeyEnter          Key = Key(ui.KeyEnter)
	KeyEqual          Key = Key(ui.KeyEqual)
	KeyEscape         Key = Key(ui.KeyEscape)
	KeyF1             Key = Key(ui.KeyF1)
	KeyF2             Key = Key(ui.KeyF2)
	KeyF3             Key = Key(ui.KeyF3)
	KeyF4             Key = Key(ui.KeyF4)
	KeyF5             Key = Key(ui.KeyF5)
	KeyF6             Key = Key(ui.KeyF6)
	KeyF7             Key = Key(ui.KeyF7)
	KeyF8             Key = Key(ui.KeyF8)
	KeyF9             Key = Key(ui.KeyF9)
	KeyF10            Key = Key(ui.KeyF10)
	KeyF11            Key = Key(ui.KeyF11)
	KeyF12            Key = Key(ui.KeyF12)
	KeyF13            Key = Key(ui.KeyF13)
	KeyF14            Key = Key(ui.KeyF14)
	KeyF15            Key = Key(ui.KeyF15)
	KeyF16            Key = Key(ui.KeyF16)
	KeyF17            Key = Key(ui.KeyF17)
	KeyF18            Key = Key(ui.KeyF18)
	KeyF19            Key = Key(ui.KeyF19)
	KeyF20            Key = Key(ui.KeyF20)
	KeyF21            Key = Key(ui.KeyF21)
	KeyF22            Key = Key(ui.KeyF22)
	KeyF23            Key = Key(ui.KeyF23)
	KeyF24            Key = Key(ui.KeyF24)
	KeyHome           Key = Key(ui.KeyHome)
	KeyInsert         Key = Key(ui.KeyInsert)
	KeyIntlBackslash  Key = Key(ui.KeyIntlBackslash)
	KeyMetaLeft       Key = Key(ui.KeyMetaLeft)
	KeyMetaRight      Key = Key(ui.KeyMetaRight)
	KeyMinus          Key = Key(ui.KeyMinus)
	KeyNumLock        Key = Key(ui.KeyNumLock)
	KeyNumpad0        Key = Key(ui.KeyNumpad0)
	KeyNumpad1        Key = Key(ui.KeyNumpad1)
	KeyNumpad2        Key = Key(ui.KeyNumpad2)
	KeyNumpad3        Key = Key(ui.KeyNumpad3)
	KeyNumpad4        Key = Key(ui.KeyNumpad4)
	KeyNumpad5        Key = Key(ui.KeyNumpad5)
	KeyNumpad6        Key = Key(ui.KeyNumpad6)
	KeyNumpad7        Key = Key(ui.KeyNumpad7)
	KeyNumpad8        Key = Key(ui.KeyNumpad8)
	KeyNumpad9        Key = Key(ui.KeyNumpad9)
	KeyNumpadAdd      Key = Key(ui.KeyNumpadAdd)
	KeyNumpadDecimal  Key = Key(ui.KeyNumpadDecimal)
	KeyNumpadDivide   Key = Key(ui.KeyNumpadDivide)
	KeyNumpadEnter    Key = Key(ui.KeyNumpadEnter)
	KeyNumpadEqual    Key = Key(ui.KeyNumpadEqual)
	KeyNumpadMultiply Key = Key(ui.KeyNumpadMultiply)
	KeyNumpadSubtract Key = Key(ui.KeyNumpadSubtract)
	KeyPageDown       Key = Key(ui.KeyPageDown)
	KeyPageUp         Key = Key(ui.KeyPageUp)
	KeyPause          Key = Key(ui.KeyPause)
	KeyPeriod         Key = Key(ui.KeyPeriod)
	KeyPrintScreen    Key = Key(ui.KeyPrintScreen)
	KeyQuote          Key = Key(ui.KeyQuote)
	KeyScrollLock     Key = Key(ui.KeyScrollLock)
	KeySemicolon      Key = Key(ui.KeySemicolon)
	KeyShiftLeft      Key = Key(ui.KeyShiftLeft)
	KeyShiftRight     Key = Key(ui.KeyShiftRight)
	KeySlash          Key = Key(ui.KeySlash)
	KeySpace          Key = Key(ui.KeySpace)
	KeyTab            Key = Key(ui.KeyTab)
	KeyAlt            Key = Key(ui.KeyReserved0)
	KeyControl        Key = Key(ui.KeyReserved1)
	KeyShift          Key = Key(ui.KeyReserved2)
	KeyMeta           Key = Key(ui.KeyReserved3)
	KeyMax            Key = KeyMeta

	// Keys for backward compatibility.
	// Deprecated: as of v2.1.
	Key0            Key = Key(ui.KeyDigit0)
	Key1            Key = Key(ui.KeyDigit1)
	Key2            Key = Key(ui.KeyDigit2)
	Key3            Key = Key(ui.KeyDigit3)
	Key4            Key = Key(ui.KeyDigit4)
	Key5            Key = Key(ui.KeyDigit5)
	Key6            Key = Key(ui.KeyDigit6)
	Key7            Key = Key(ui.KeyDigit7)
	Key8            Key = Key(ui.KeyDigit8)
	Key9            Key = Key(ui.KeyDigit9)
	KeyApostrophe   Key = Key(ui.KeyQuote)
	KeyDown         Key = Key(ui.KeyArrowDown)
	KeyGraveAccent  Key = Key(ui.KeyBackquote)
	KeyKP0          Key = Key(ui.KeyNumpad0)
	KeyKP1          Key = Key(ui.KeyNumpad1)
	KeyKP2          Key = Key(ui.KeyNumpad2)
	KeyKP3          Key = Key(ui.KeyNumpad3)
	KeyKP4          Key = Key(ui.KeyNumpad4)
	KeyKP5          Key = Key(ui.KeyNumpad5)
	KeyKP6          Key = Key(ui.KeyNumpad6)
	KeyKP7          Key = Key(ui.KeyNumpad7)
	KeyKP8          Key = Key(ui.KeyNumpad8)
	KeyKP9          Key = Key(ui.KeyNumpad9)
	KeyKPAdd        Key = Key(ui.KeyNumpadAdd)
	KeyKPDecimal    Key = Key(ui.KeyNumpadDecimal)
	KeyKPDivide     Key = Key(ui.KeyNumpadDivide)
	KeyKPEnter      Key = Key(ui.KeyNumpadEnter)
	KeyKPEqual      Key = Key(ui.KeyNumpadEqual)
	KeyKPMultiply   Key = Key(ui.KeyNumpadMultiply)
	KeyKPSubtract   Key = Key(ui.KeyNumpadSubtract)
	KeyLeft         Key = Key(ui.KeyArrowLeft)
	KeyLeftBracket  Key = Key(ui.KeyBracketLeft)
	KeyMenu         Key = Key(ui.KeyContextMenu)
	KeyRight        Key = Key(ui.KeyArrowRight)
	KeyRightBracket Key = Key(ui.KeyBracketRight)
	KeyUp           Key = Key(ui.KeyArrowUp)
)

Keys.

func (Key) MarshalText ¶ added in v2.4.0 

func (k Key) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

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.

func (*Key) UnmarshalText ¶ added in v2.4.0 

func (k *Key) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler

type LayoutFer ¶ added in v2.5.0 

type LayoutFer interface {
	// LayoutF is the float version of Game.Layout.
	//
	// If the game implements this interface, Layout is never called and LayoutF is called instead.
	//
	// LayoutF accepts a native outside size in device-independent pixels and returns the game's logical screen
	// size in pixels. The logical size is used for 1) the screen size given at Draw and 2) calculation of the
	// scale from the screen to the final screen size. For 1), the actual screen size is a rounded up of the
	// logical size.
	LayoutF(outsideWidth, outsideHeight float64) (screenWidth, screenHeight float64)
}

LayoutFer is an interface for the float version of Game.Layout.

type MonitorType ¶ added in v2.6.0 

type MonitorType ui.Monitor

MonitorType represents a monitor available to the system.

func AppendMonitors ¶ added in v2.6.0 

func AppendMonitors(monitors []*MonitorType) []*MonitorType

AppendMonitors returns the monitors reported by the system. On desktop platforms, there will always be at least one monitor appended and the first monitor in the slice will be the primary monitor. Any monitors added or removed will show up with subsequent calls to this function.

func Monitor ¶ added in v2.6.0 

func Monitor() *MonitorType

Monitor returns the current monitor.

func (*MonitorType) DeviceScaleFactor ¶ added in v2.7.0 

func (m *MonitorType) DeviceScaleFactor() float64

DeviceScaleFactor returns the device scale factor of the monitor.

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.

func (*MonitorType) Name ¶ added in v2.6.0 

func (m *MonitorType) Name() string

Name returns the monitor's name. On Linux, this reports the monitors in xrandr format. On Windows, this reports "Generic PnP Monitor" for all monitors.

func (*MonitorType) Size ¶ added in v2.7.0 

func (m *MonitorType) Size() (int, int)

Size returns the size of the monitor in device-independent pixels. This is the same as the screen size in fullscreen mode. The returned value can be given to SetSize function if the perfectly fit fullscreen is needed.

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

Size's use cases are limited. If you are making a fullscreen application, you can use RunGame and the Game interface's Layout function instead. If you are making a not-fullscreen application but the application's behavior depends on the monitor size, Size is useful.

type MouseButton ¶ 

type MouseButton = ui.MouseButton

A MouseButton represents a mouse button. 

const (
	MouseButtonLeft   MouseButton = MouseButton0
	MouseButtonMiddle MouseButton = MouseButton1
	MouseButtonRight  MouseButton = MouseButton2

	MouseButton0   MouseButton = ui.MouseButton0
	MouseButton1   MouseButton = ui.MouseButton1
	MouseButton2   MouseButton = ui.MouseButton2
	MouseButton3   MouseButton = ui.MouseButton3
	MouseButton4   MouseButton = ui.MouseButton4
	MouseButtonMax MouseButton = MouseButton4
)

MouseButtons

type NewImageFromImageOptions ¶ added in v2.4.0 

type NewImageFromImageOptions struct {
	// Unmanaged represents whether the image is unmanaged or not.
	// The default (zero) value is false, that means the image is managed.
	//
	// An unmanaged image is never on an internal automatic texture atlas.
	// A regular image is a part of an internal texture atlas, and locating them is done automatically in Ebitengine.
	// Unmanaged is useful when you want finer controls over the image for performance and memory reasons.
	Unmanaged bool

	// PreserveBounds represents whether the new image's bounds are the same as the given image.
	// The default (zero) value is false, that means the new image's upper-left position is adjusted to (0, 0).
	PreserveBounds bool
}

NewImageFromImageOptions represents options for NewImageFromImage.

type NewImageOptions ¶ added in v2.4.0 

type NewImageOptions struct {
	// Unmanaged represents whether the image is unmanaged or not.
	// The default (zero) value is false, that means the image is managed.
	//
	// An unmanaged image is never on an internal automatic texture atlas.
	// A regular image is a part of an internal texture atlas, and locating them is done automatically in Ebitengine.
	// Unmanaged is useful when you want finer controls over the image for performance and memory reasons.
	Unmanaged bool
}

NewImageOptions represents options for NewImage.

type RunGameOptions ¶ added in v2.5.0 

type RunGameOptions struct {
	// GraphicsLibrary is a graphics library Ebitengine will use.
	//
	// The default (zero) value is GraphicsLibraryAuto, which lets Ebitengine choose the graphics library.
	GraphicsLibrary GraphicsLibrary

	// InitUnfocused indicates whether the window is unfocused or not on launching.
	// InitUnfocused is valid on desktops and browsers.
	//
	// The default (zero) value is false, which means that the window is focused.
	InitUnfocused bool

	// ScreenTransparent indicates whether the window is transparent or not.
	// ScreenTransparent is valid on desktops and browsers.
	//
	// The default (zero) value is false, which means that the window is not transparent.
	ScreenTransparent bool

	// SkipTaskbar indicates whether an application icon is shown on a taskbar or not.
	// SkipTaskbar is valid only on Windows.
	//
	// The default (zero) value is false, which means that an icon is shown on a taskbar.
	SkipTaskbar bool

	// SingleThread indicates whether the single thread mode is used explicitly or not.
	// The single thread mode disables Ebitengine's thread safety to unlock maximum performance.
	// If you use this you will have to manage threads yourself.
	// Functions like `SetWindowSize` will no longer be concurrent-safe with this build tag.
	// They must be called from the main thread or the same goroutine as the given game's callback functions like Update.
	//
	// SingleThread works only with desktops and consoles.
	//
	// If SingleThread is false, and if the build tag `ebitenginesinglethread` is specified,
	// the single thread mode is used.
	//
	// The default (zero) value is false, which means that the single thread mode is disabled.
	SingleThread bool

	// DisableHiDPI indicates whether the rendering for HiDPI is disabled or not.
	// If HiDPI is disabled, the device scale factor is always 1 i.e. Monitor's DeviceScaleFactor always returns 1.
	// This is useful to get a better performance on HiDPI displays, in the expense of rendering quality.
	//
	// DisableHiDPI is available only on browsers.
	//
	// The default (zero) value is false, which means that HiDPI is enabled.
	DisableHiDPI bool

	// ColorSpace indicates the color space of the screen.
	//
	// ColorSpace is available only with some graphics libraries (macOS Metal and WebGL so far).
	// Otherwise, ColorSpace is ignored.
	//
	// The default (zero) value is ColorSpaceDefault, which means that color space depends on the environment.
	ColorSpace ColorSpace

	// X11DisplayName is a class name in the ICCCM WM_CLASS window property.
	X11ClassName string

	// X11InstanceName is an instance name in the ICCCM WM_CLASS window property.
	X11InstanceName string

	// StrictContextRestration indicates whether the context lost should be restored strictly by Ebitengine or not.
	//
	// StrictContextRestration is available only on Android. Otherwise, StrictContextRestration is ignored.
	// Thus, StrictContextRestration should be used with mobile.SetGameWithOptions, rather than RunGameWithOptions.
	//
	// In Android, Ebitengien uses `GLSurfaceView`'s `setPreserveEGLContextOnPause(true)`.
	// This works in most cases, but it is still possible that the context is lost in some minor cases.
	//
	// When StrictContextRestration is true, Ebitengine tries to restore the context more strictly
	// for such minor cases.
	// However, this might cause a performance issue since Ebitengine tries to keep all the information
	// to restore the context.
	//
	// When StrictContextRestration is false, Ebitengine does nothing special to restore the context and
	// relies on the OS's behavior.
	//
	// As a side note, especially when StrictContextRestration is false, the activity's launch mode should
	// be singleInstance, or the activity no longer works correctly after the context is lost.
	//
	// The default (zero) value is false.
	StrictContextRestration bool
}

RunGameOptions represents options for RunGameWithOptions.

type Shader ¶ 

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

Shader represents a compiled shader program.

For the details about the shader, see https://ebitengine.org/en/documents/shader.html.

func NewShader ¶ 

func NewShader(src []byte) (*Shader, error)

NewShader compiles a shader program in the shading language Kage, and returns the result.

If the compilation fails, NewShader returns an error.

For the details about the shader, see https://ebitengine.org/en/documents/shader.html.

func (*Shader) Deallocate ¶ added in v2.7.0 

func (s *Shader) Deallocate()

Deallocate deallocates the internal state of the shader. Even after Deallocate is called, the shader is still available. In this case, the shader's internal state is allocated again.

Usually, you don't have to call Deallocate since the internal state is automatically released by GC. However, if you are sure that the shader is no longer used but not sure how this shader object is referred, you can call Deallocate to make sure that the internal state is deallocated.

If the shader is disposed, Deallocate does nothing.

func (*Shader) Dispose deprecated 

func (s *Shader) Dispose()

Dispose disposes the shader program. After disposing, the shader is no longer available.

Deprecated: as of v2.7. Use Deallocate instead.

type StandardGamepadAxis ¶ added in v2.2.0 

type StandardGamepadAxis = gamepaddb.StandardAxis

StandardGamepadAxis represents a gamepad axis in the standard layout.

The layout and the button values are based on the web standard. See https://www.w3.org/TR/gamepad/#remapping. 

const (
	StandardGamepadAxisLeftStickHorizontal  StandardGamepadAxis = gamepaddb.StandardAxisLeftStickHorizontal
	StandardGamepadAxisLeftStickVertical    StandardGamepadAxis = gamepaddb.StandardAxisLeftStickVertical
	StandardGamepadAxisRightStickHorizontal StandardGamepadAxis = gamepaddb.StandardAxisRightStickHorizontal
	StandardGamepadAxisRightStickVertical   StandardGamepadAxis = gamepaddb.StandardAxisRightStickVertical
	StandardGamepadAxisMax                  StandardGamepadAxis = StandardGamepadAxisRightStickVertical
)

StandardGamepadAxes

type StandardGamepadButton ¶ added in v2.2.0 

type StandardGamepadButton = gamepaddb.StandardButton

StandardGamepadButton represents a gamepad button in the standard layout.

The layout and the button values are based on the web standard. See https://www.w3.org/TR/gamepad/#remapping. 

const (
	StandardGamepadButtonRightBottom      StandardGamepadButton = gamepaddb.StandardButtonRightBottom
	StandardGamepadButtonRightRight       StandardGamepadButton = gamepaddb.StandardButtonRightRight
	StandardGamepadButtonRightLeft        StandardGamepadButton = gamepaddb.StandardButtonRightLeft
	StandardGamepadButtonRightTop         StandardGamepadButton = gamepaddb.StandardButtonRightTop
	StandardGamepadButtonFrontTopLeft     StandardGamepadButton = gamepaddb.StandardButtonFrontTopLeft
	StandardGamepadButtonFrontTopRight    StandardGamepadButton = gamepaddb.StandardButtonFrontTopRight
	StandardGamepadButtonFrontBottomLeft  StandardGamepadButton = gamepaddb.StandardButtonFrontBottomLeft
	StandardGamepadButtonFrontBottomRight StandardGamepadButton = gamepaddb.StandardButtonFrontBottomRight
	StandardGamepadButtonCenterLeft       StandardGamepadButton = gamepaddb.StandardButtonCenterLeft
	StandardGamepadButtonCenterRight      StandardGamepadButton = gamepaddb.StandardButtonCenterRight
	StandardGamepadButtonLeftStick        StandardGamepadButton = gamepaddb.StandardButtonLeftStick
	StandardGamepadButtonRightStick       StandardGamepadButton = gamepaddb.StandardButtonRightStick
	StandardGamepadButtonLeftTop          StandardGamepadButton = gamepaddb.StandardButtonLeftTop
	StandardGamepadButtonLeftBottom       StandardGamepadButton = gamepaddb.StandardButtonLeftBottom
	StandardGamepadButtonLeftLeft         StandardGamepadButton = gamepaddb.StandardButtonLeftLeft
	StandardGamepadButtonLeftRight        StandardGamepadButton = gamepaddb.StandardButtonLeftRight
	StandardGamepadButtonCenterCenter     StandardGamepadButton = gamepaddb.StandardButtonCenterCenter
	StandardGamepadButtonMax              StandardGamepadButton = StandardGamepadButtonCenterCenter
)

StandardGamepadButtons

type TouchID ¶ 

type TouchID = ui.TouchID

TouchID represents a touch's identifier.

func AppendTouchIDs ¶ added in v2.2.0 

func AppendTouchIDs(touches []TouchID) []TouchID

AppendTouchIDs appends the current touch states to touches, and returns the extended buffer. Giving a slice that already has enough capacity works efficiently.

If you want to know whether a touch started being pressed in the current tick, use inpututil.JustPressedTouchIDs

AppendTouchIDs doesn't append anything when there are no touches. AppendTouchIDs always does nothing on desktops.

AppendTouchIDs is concurrent-safe.

func TouchIDs deprecated 

func TouchIDs() []TouchID

TouchIDs returns the current touch states.

Deprecated: as of v2.2. Use AppendTouchIDs 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 an upper-left point of a sub-image might not be (0, 0).
	SrcX float32
	SrcY float32

	// ColorR/ColorG/ColorB/ColorA represents color scaling values.
	// Their interpretation depends on the concrete draw call used:
	// - DrawTriangles: straight-alpha or premultiplied-alpha encoded color multiplier.
	//   The format is determined by ColorScaleMode in DrawTrianglesOptions.
	//   If ColorA is 0, the vertex is fully transparent and color is ignored.
	//   If ColorA is 1, the vertex has the color (ColorR, ColorG, ColorB).
	//   Vertex colors are converted to premultiplied-alpha internally and
	//   interpolated linearly respecting alpha.
	// - DrawTrianglesShader: arbitrary floating point values sent to the shader.
	//   These are interpolated linearly and independently of each other.
	ColorR float32
	ColorG float32
	ColorB float32
	ColorA float32

	// Custom0/Custom1/Custom2/Custom3 represents general-purpose values passed to the shader.
	// In order to use them, Fragment must have an additional vec4 argument.
	//
	// These values are valid only when DrawTrianglesShader is used.
	// In other cases, these values are ignored.
	Custom0 float32
	Custom1 float32
	Custom2 float32
	Custom3 float32
}

Vertex represents a vertex passed to DrawTriangles.

type VibrateGamepadOptions ¶ added in v2.3.0 

type VibrateGamepadOptions struct {
	// Duration is the time duration of the effect.
	Duration time.Duration

	// StrongMagnitude is the rumble intensity of a low-frequency rumble motor.
	// The value is in between 0 and 1.
	StrongMagnitude float64

	// WeakMagnitude is the rumble intensity of a high-frequency rumble motor.
	// The value is in between 0 and 1.
	WeakMagnitude float64
}

VibrateGamepadOptions represents the options for gamepad vibration.

type VibrateOptions ¶ added in v2.3.0 

type VibrateOptions struct {
	// Duration is the time duration of the effect.
	Duration time.Duration

	// Magnitude is the strength of the device vibration.
	// The value is in between 0 and 1.
	Magnitude float64
}

VibrateOptions represents the options for device vibration.

type WindowResizingModeType ¶ added in v2.3.0 

type WindowResizingModeType = ui.WindowResizingMode

WindowResizingModeType represents a mode in which a user resizes the window.

Regardless of the resizing mode, an Ebitengine application can still change the window size or make the window fullscreen by calling Ebitengine functions. 

const (
	// WindowResizingModeDisabled indicates the mode to disallow resizing the window by a user.
	WindowResizingModeDisabled WindowResizingModeType = ui.WindowResizingModeDisabled

	// WindowResizingModeOnlyFullscreenEnabled indicates the mode to disallow resizing the window,
	// but allow to make the window fullscreen by a user.
	// This works only on macOS so far.
	// On the other platforms, this is the same as WindowResizingModeDisabled.
	WindowResizingModeOnlyFullscreenEnabled WindowResizingModeType = ui.WindowResizingModeOnlyFullscreenEnabled

	// WindowResizingModeEnabled indicates the mode to allow resizing the window by a user.
	WindowResizingModeEnabled WindowResizingModeType = ui.WindowResizingModeEnabled
)

WindowResizingModeTypes

func WindowResizingMode ¶ added in v2.3.0 

func WindowResizingMode() WindowResizingModeType

WindowResizingMode returns the current mode in which a user resizes the window.

The default mode is WindowResizingModeDisabled.

WindowResizingMode is concurrent-safe.

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
Package audio provides audio players.
 Package audio provides audio players.
internal/convert
mp3
Package mp3 provides MP3 decoder.
 Package mp3 provides MP3 decoder.
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.
cmd
ebitenmobile
ebitenmobile is a wrapper of gomobile for Ebitengine.
 ebitenmobile is a wrapper of gomobile for Ebitengine.
Package ebitenutil provides utility functions for Ebitengine.
 Package ebitenutil provides utility functions for Ebitengine.
examples
2048
2048/2048
address
airship
alphablending
animation
audio
audioinfiniteloop
audiopanning
blend
blocks
blocks/blocks
blur
camera
capture
chipmunk
clip
contextlost
cursor
doomfire
drag
dragmascot
Mascot is a desktop mascot on cross platforms.
 Mascot is a desktop mascot on cross platforms.
dropfile
filter
flappy
flood
font
fontfeature
fontvariation
fontvector
fullscreen
gamepad
highdpi
hsv
hue
infinitescroll
isometric
keyboard
keyboard/keyboard
lasttouch
life
lines
mandelbrot
mascot
Mascot is a desktop mascot on cross platforms.
 Mascot is a desktop mascot on cross platforms.
masking
minify
mixedfont
moire
This example is just to check if Ebitengine can draw fine checker pattern evenly.
 This example is just to check if Ebitengine can draw fine checker pattern evenly.
monitor
mosaic
noise
paint
particles
pcm
perspective
piano
platformer
polygons
raycasting
realtimepcm
resources/audio
resources/fonts
resources/images
resources/images/audio
resources/images/blend
resources/images/blocks
resources/images/flappy
resources/images/keyboard
resources/images/mascot
resources/images/platformer
resources/images/shader
rotate
scroll
set
shader
shapes
sinewave
skipdraw
snake
sprites
spriteshd
squiral
stars
subimage
text
texti18n
textinput
tiles
touch
typewriter
ui
vector
vibrate
video
wav
wheel
windowclosing
windowsize
exp
textinput
Package textinput provides a text-inputting controller.
 Package textinput provides a text-inputting controller.
Package inpututil provides utility functions of input like keyboard or mouse.
 Package inpututil provides utility functions of input like keyboard or mouse.
internal
affine
atlas
buffered
builtinshader
clock
Package clock manages game timers.
 Package clock manages game timers.
cocoa
debug
file
gamepad
gamepaddb
glfw
graphics
graphicscommand
Package graphicscommand represents a low layer for graphics using OpenGL.
 Package graphicscommand represents a low layer for graphics using OpenGL.
graphicsdriver
graphicsdriver/directx
graphicsdriver/metal
graphicsdriver/metal/ca
Package ca provides access to Apple's Core Animation API (https://developer.apple.com/documentation/quartzcore).
 Package ca provides access to Apple's Core Animation API (https://developer.apple.com/documentation/quartzcore).
graphicsdriver/metal/mtl
Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal).
 Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal).
graphicsdriver/opengl
graphicsdriver/opengl/gl
hook
jsutil
Package jsutil offers utility functions for Wasm.
 Package jsutil offers utility functions for Wasm.
microsoftgdk
mipmap
packing
Package packing offers a packing algorithm in 2D space.
 Package packing offers a packing algorithm in 2D space.
png
Package png implements a PNG image decoder and encoder.
 Package png implements a PNG image decoder and encoder.
restorable
Package restorable offers an Image struct that stores image commands and restores its pixel data from the commands when context lost happens.
 Package restorable offers an Image struct that stores image commands and restores its pixel data from the commands when context lost happens.
shader
shaderir
Package shaderir offers intermediate representation for shader programs.
 Package shaderir offers intermediate representation for shader programs.
shaderir/glsl
shaderir/hlsl
shaderir/msl
shaderir/pssl
testing
thread
ui
vettools
vibrate
winver
Package mobile provides functions for mobile platforms (Android and iOS).
 Package mobile provides functions for mobile platforms (Android and iOS).
Package text offers functions to draw texts on an Ebitengine's image.
 Package text offers functions to draw texts on an Ebitengine's image.
v2
Package text offers functions to draw texts on an Ebitengine's image.
 Package text offers functions to draw texts on an Ebitengine's image.
Package vector provides functions for vector graphics rendering.
 Package vector provides functions for vector graphics rendering.

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.