Ebitengine 2.5 Release Notes

v2.5.0

Issues for v2.5.0

Xbox support

(#2084)

Ebitengine now supports Xbox! Odencat released a new Ebitengine game "Meg's Monster" on March 2nd, 2023. This game supports multiple platforms including Xbox One and Xbox Series X|S.

We are preparing more updates to make Ebitengine for Xbox available for other users. Stay tuned!

Vector graphics

(#1843, #2387)

Some APIs to render lines or various shapes were added to the vector package:

• type Direction
• type LineCap
• type LineJoin
• func vector.DrawFilledCircle
• func vector.DrawFilledRect
• func vector.StrokeCircle
• func vector.StrokeLine
• func vector.StrokeRect
• func (*vector.Path) AppendVerticesAndIndicesForStroke

Also, a new member AntiAlias was added to ebiten.DrawTrianglesOptions and ebiten.DrawTrianglesShaderOptions. AntiAlias is useful to render vector graphics with smooth edges.

Blend

(#1450, #2382)

A new type ebiten.Blend was added. Blend aims to replace ebiten.CompositeMode. With Blend, you can have finer control than CompositeMode by specifying blend factors and operations for source/destination RGB/alpha values. You can also use preset Blend constants like BlendSourceOver.

RunGameWithOptions

(#2378, #1518)

A new function ebiten.RunGameWithOptions and a new struct ebiten.RunGameOptions were added. RunGameWithOptions is a new function to run a game with options. You can specify options by RunGameOptions.

• GraphicsLibrary specifies a graphics library Ebitengine will use.
• SkipTaskbar indicates whether an application icon is hidden on a task bar or not on Windows. This is useful to create a desktop mascot application.
• etc.

Customizing the screen shader

(#2046)

A new interface ebiten.FinalScreenDrawer was added.

If a game implementing ebiten.Game also implements ebiten.FinalScreenDrawer, its method DrawFinalScreen is called after its Draw is called and you can customize the final screen rendering there. If a game implementing ebiten.Game does NOT implement ebiten.FinalScreenDrawer, the default screen shader, which is similar to the nearest-neighbor filter, is used.

The given arguments of the function DrawFinalScreen are the final screen image as the destination, the offscreen image as the source, and a geometry matrix to enlarge (or shrink) the offscreen to fit with the final screen. The offscreen image is the same as the argument of the game's Draw.

ebiten.ColorScale and colorm

(#2171)

A new struct ebiten.ColorScale and a new package colorm were added. These APIs aim to replace the existing APIs for color matrices. These make your code more explicit about execution costs i.e. a number of draw calls.

For just scalings, you can use the new struct ebiten.ColorScale. For more complex usages of a color matrix, you can use APIs in the package colorm.

A new member ColorScale was also added to ebiten.DrawImageOptions and ebiten.DrawRectShaderOptions.

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

Drag and drop files

(#1868, #2552)

A new function ebiten.DroppedFiles was added. DroppedFiles returns a pseudo file system including the dropped files and directories, and you can access the dropped file contents via the file system. For an actual usage, see the example examples/dropfile.

A float-number version of Layout

(#2285)

A new interface ebiten.LayoutFer was added. LayoutFer has LayoutF method which is a float-number version of Game's Layout. If a game implementing ebiten.Game also implements LayoutFer, its LayoutF is invoked instead of its Layout. You can implement more precise layout caliculation with LayoutF than Layout.

GPU Optimization with SetScreenClearedEveryFrame(false)

(#2342)

When the screen is not cleared every frame by calling SetScreenClearedEveryFrame(false) and your Draw doesn't change the screen, Ebitengine saves GPU usages.

By this optimization, we no longer need FPSModeVsyncOffMinimum, which could save GPU power but was problematic for the performance e.g. when moving a mouse cursor quickly. In Ebitengine 2.5, the type FPSModeType and the APIs using it were deprecated. Instead, ebiten.SetVsyncEnabled and ebiten.IsVsyncEnabled were undeprecated.

Other new APIs

• type ebiten.ColorScaleMode (#2365)
• func ebiten.KeyName (#1904)
• const ebiten.MouseButton0 - const ebiten.MouseButton4 (#2445)
• const ebiten.Termination (#2266)
• func inpututil.AppendJustPressedKeys (#2381)
• func inpututil.AppendJustReleasedKeys (#2381)
• func inpututil.AppendJustPressedGamepadButtons (#2381)
• func inpututil.AppendJustPressedStandardGamepadButtons (#2381)
• func inpututil.AppendJustReleasedGamepadButtons (#2381)
• func inpututil.AppendJustReleasedStandardGamepadButtons (#2381)
• func inpututil.AppendPressedGamepadButtons (#2381)
• func inpututil.AppendPressedStandardGamepadButtons (#2381)

Kage (shader)

• New types are added: ivec2, ivec3, ivec4 (#1911)
• int values are allowed for uniform variables (#2305)
• Arrays are allowed for uniform variables (#2448)

OpenGL ES

(#292)

OpenGL ES is now automatically chosen when available. In order to specify OpenGL ES explicitly, set an environment variable EBITENGINE_OPENGL with es.

Performance improvement

Ebitengine 2.5 has performance improvements including these items:

• Rendering onto sub-images works more efficiently (#2232).
• Memory usage was reduced (#2274).
• Non-squreare internal texture atlasese are allowed (#2327).
• A number of internal textures was reduced (#2581).

Deprecated APIs

Some APIs were deprecated. The deprecated APIs are still available during the version 2, but it is recommended to replace them with the new APIs.

Bug fixes

This release includes all the bug fixes in the version 2.4.

Breaking changes

• Go 1.17 and older versions are no longer supported (#2323, #2421).
• Old Edge browser is no longer supported (#1059).

Miscellaneous

• The build tag example is no longer required for the examples (#1462).
• The package text now considers hinting. text tries to create glyphs with considering sub-pixel shifts, in the case when a font face doesn't use hinting (#2469, #2528).

v2.5.1

Bug fixes

Issues for v2.5.1

• An Ebitengine application with ebiten.SetRunnableOnUnfocused(false) didn't start on macOS (#2620).

v2.5.2

Bug fixes

Issues for v2.5.2

• A mouse cursor position was not correct with CursorModeCapture on Web browsers (#2634).

v2.5.3

Bug fixes

Issues for v2.5.3

• In Kage, a swizzling component r for a vec2 couldn't be compiled (#2652).

v2.5.4

Bug fixes

Issues for v2.5.4

• There were wrong position usages in the shader example (#2638).

v2.5.5

Bug fixes

Issues for v2.5.5

• Fixed a rare crash on an iOS application (#2679).
• Fixed an issue where ebiten.AppendInputChars didn't work correctly on Android (#2682, #2684).

v2.5.6

Bug fixes

Issues for v2.5.6

• Fixed an issue that caused crashes on macOS in Go 1.21 (#2700).

v2.5.7

Bug fixes

Issues for v2.5.7

• Fixed performance issues caused by overflow on 32-bit machines (#2728).

v2.5.8

Bug fixes

Issues for v2.5.8

• Fixed an issue where the application may not launch when the DYLD_FALLBACK_FRAMEWORK_PATH environment variable is set on macOS (#2732).
• Fixed an issue where the contents of the options argument could be incorrectly modified in (*ebiten.Image).DrawImage and (*ebiten.Image).DrawRectShader (#2733).
• Fixed an issue where calling (*audio.Player).Play in an independent goroutine could result in a deadlock (#2737).

v2.5.9

Bug fixes

Issues for v2.5.9

• Fixed an issue where calling ebiten.SetCursorMode or similar functions from a separate goroutine before calling ebiten.RunGame could cause a crash (#2742).

v2.5.10

Bug fixes

Issues for v2.5.10

• Fixed an issue where accessing the view property of EbitenViewController in iOS applications could cause freezing (#2768).
• Fixed an issue where iOS applications could not be built in Xcode 15 (#2772).
• Fixed a crash when playing sound in iOS 17 (#2773).