1
0

run.go 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744
  1. // Copyright 2014 Hajime Hoshi
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. package ebiten
  15. import (
  16. "errors"
  17. "image"
  18. "image/color"
  19. "io/fs"
  20. "sync/atomic"
  21. "github.com/hajimehoshi/ebiten/v2/internal/clock"
  22. "github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver"
  23. "github.com/hajimehoshi/ebiten/v2/internal/ui"
  24. )
  25. // Game defines necessary functions for a game.
  26. type Game interface {
  27. // Update updates a game by one tick. The given argument represents a screen image.
  28. //
  29. // Update updates only the game logic and Draw draws the screen.
  30. //
  31. // You can assume that Update is always called TPS-times per second (60 by default), and you can assume
  32. // that the time delta between two Updates is always 1 / TPS [s] (1/60[s] by default). As Ebitengine already
  33. // adjusts the number of Update calls, you don't have to measure time deltas in Update by e.g. OS timers.
  34. //
  35. // An actual TPS is available by ActualTPS(), and the result might slightly differ from your expected TPS,
  36. // but still, your game logic should stick to the fixed time delta and should not rely on ActualTPS() value.
  37. // This API is for just measurement and/or debugging. In the long run, the number of Update calls should be
  38. // adjusted based on the set TPS on average.
  39. //
  40. // An actual time delta between two Updates might be bigger than expected. In this case, your game's
  41. // Update or Draw takes longer than they should. In this case, there is nothing other than optimizing
  42. // your game implementation.
  43. //
  44. // In the first frame, it is ensured that Update is called at least once before Draw. You can use Update
  45. // to initialize the game state.
  46. //
  47. // After the first frame, Update might not be called or might be called once
  48. // or more for one frame. The frequency is determined by the current TPS (tick-per-second).
  49. //
  50. // If the error returned is nil, game execution proceeds normally.
  51. // If the error returned is Termination, game execution halts, but does not return an error from RunGame.
  52. // If the error returned is any other non-nil value, game execution halts and the error is returned from RunGame.
  53. Update() error
  54. // Draw draws the game screen by one frame.
  55. //
  56. // The give argument represents a screen image. The updated content is adopted as the game screen.
  57. //
  58. // The frequency of Draw calls depends on the user's environment, especially the monitors refresh rate.
  59. // For portability, you should not put your game logic in Draw in general.
  60. Draw(screen *Image)
  61. // Layout accepts a native outside size in device-independent pixels and returns the game's logical screen
  62. // size in pixels. The logical size is used for 1) the screen size given at Draw and 2) calculation of the
  63. // scale from the screen to the final screen size.
  64. //
  65. // On desktops, the outside is a window or a monitor (fullscreen mode). On browsers, the outside is a body
  66. // element. On mobiles, the outside is the view's size.
  67. //
  68. // Even though the outside size and the screen size differ, the rendering scale is automatically adjusted to
  69. // fit with the outside.
  70. //
  71. // Layout is called almost every frame.
  72. //
  73. // It is ensured that Layout is invoked before Update is called in the first frame.
  74. //
  75. // If Layout returns non-positive numbers, the caller can panic.
  76. //
  77. // You can return a fixed screen size if you don't care, or you can also return a calculated screen size
  78. // adjusted with the given outside size.
  79. //
  80. // If the game implements the interface LayoutFer, Layout is never called and LayoutF is called instead.
  81. Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int)
  82. }
  83. // LayoutFer is an interface for the float version of Game.Layout.
  84. type LayoutFer interface {
  85. // LayoutF is the float version of Game.Layout.
  86. //
  87. // If the game implements this interface, Layout is never called and LayoutF is called instead.
  88. //
  89. // LayoutF accepts a native outside size in device-independent pixels and returns the game's logical screen
  90. // size in pixels. The logical size is used for 1) the screen size given at Draw and 2) calculation of the
  91. // scale from the screen to the final screen size. For 1), the actual screen size is a rounded up of the
  92. // logical size.
  93. LayoutF(outsideWidth, outsideHeight float64) (screenWidth, screenHeight float64)
  94. }
  95. // FinalScreen represents the final screen image.
  96. // FinalScreen implements a part of Image functions.
  97. type FinalScreen interface {
  98. Bounds() image.Rectangle
  99. DrawImage(img *Image, options *DrawImageOptions)
  100. DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)
  101. DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)
  102. DrawTrianglesShader(vertices []Vertex, indices []uint16, shader *Shader, options *DrawTrianglesShaderOptions)
  103. Clear()
  104. Fill(clr color.Color)
  105. // private prevents other packages from implementing this interface.
  106. // A new function might be added to this interface in the future
  107. // even if the Ebitengine major version is not updated.
  108. private()
  109. }
  110. // FinalScreenDrawer is an interface for a custom function to render the final screen.
  111. // For an actual usage, see examples/flappy.
  112. type FinalScreenDrawer interface {
  113. // DrawFinalScreen draws the final screen.
  114. // If a game implementing FinalScreenDrawer is passed to RunGame, DrawFinalScreen is called after Draw.
  115. // screen is the final screen. offscreen is the offscreen modified at Draw.
  116. //
  117. // geoM is the default geometry matrix to render the offscreen onto the final screen.
  118. // geoM scales the offscreen to fit the final screen without changing the aspect ratio, and
  119. // translates the offscreen to put it in the center of the final screen.
  120. DrawFinalScreen(screen FinalScreen, offscreen *Image, geoM GeoM)
  121. }
  122. // DefaultTPS represents a default ticks per second, that represents how many times game updating happens in a second.
  123. const DefaultTPS = clock.DefaultTPS
  124. // ActualFPS returns the current number of FPS (frames per second), that represents
  125. // how many swapping buffer happens per second.
  126. //
  127. // On some environments, ActualFPS doesn't return a reliable value since vsync doesn't work well there.
  128. // If you want to measure the application's speed, Use ActualTPS.
  129. //
  130. // This value is for measurement and/or debug, and your game logic should not rely on this value.
  131. //
  132. // ActualFPS is concurrent-safe.
  133. func ActualFPS() float64 {
  134. return clock.ActualFPS()
  135. }
  136. // CurrentFPS returns the current number of FPS (frames per second), that represents
  137. // how many swapping buffer happens per second.
  138. //
  139. // Deprecated: as of v2.4. Use ActualFPS instead.
  140. func CurrentFPS() float64 {
  141. return ActualFPS()
  142. }
  143. var (
  144. isRunGameEnded_ atomic.Bool
  145. )
  146. // SetScreenClearedEveryFrame enables or disables the clearing of the screen at the beginning of each frame.
  147. // The default value is true and the screen is cleared each frame by default.
  148. //
  149. // SetScreenClearedEveryFrame is concurrent-safe.
  150. func SetScreenClearedEveryFrame(cleared bool) {
  151. ui.Get().SetScreenClearedEveryFrame(cleared)
  152. }
  153. // IsScreenClearedEveryFrame returns true if the frame isn't cleared at the beginning.
  154. //
  155. // IsScreenClearedEveryFrame is concurrent-safe.
  156. func IsScreenClearedEveryFrame() bool {
  157. return ui.Get().IsScreenClearedEveryFrame()
  158. }
  159. // SetScreenFilterEnabled enables/disables the use of the "screen" filter Ebitengine uses.
  160. //
  161. // The "screen" filter is a box filter from game to display resolution.
  162. //
  163. // If disabled, nearest-neighbor filtering will be used for scaling instead.
  164. //
  165. // The default state is true.
  166. //
  167. // SetScreenFilterEnabled is concurrent-safe, but takes effect only at the next Draw call.
  168. //
  169. // Deprecated: as of v2.5. Use FinalScreenDrawer instead.
  170. func SetScreenFilterEnabled(enabled bool) {
  171. screenFilterEnabled.Store(enabled)
  172. }
  173. // IsScreenFilterEnabled returns true if Ebitengine's "screen" filter is enabled.
  174. //
  175. // IsScreenFilterEnabled is concurrent-safe.
  176. //
  177. // Deprecated: as of v2.5.
  178. func IsScreenFilterEnabled() bool {
  179. return screenFilterEnabled.Load()
  180. }
  181. // Termination is a special error which indicates Game termination without error.
  182. var Termination = ui.RegularTermination
  183. // RunGame starts the main loop and runs the game.
  184. // game's Update function is called every tick to update the game logic.
  185. // game's Draw function is called every frame to draw the screen.
  186. // game's Layout function is called when necessary, and you can specify the logical screen size by the function.
  187. //
  188. // If game implements FinalScreenDrawer, its DrawFinalScreen is called after Draw.
  189. // The argument screen represents the final screen. The argument offscreen is an offscreen modified at Draw.
  190. // If game does not implement FinalScreenDrawer, the default rendering for the final screen is used.
  191. //
  192. // game's functions are called on the same goroutine.
  193. //
  194. // On browsers, it is strongly recommended to use iframe if you embed an Ebitengine application in your website.
  195. //
  196. // RunGame must be called on the main thread.
  197. // Note that Ebitengine bounds the main goroutine to the main OS thread by runtime.LockOSThread.
  198. //
  199. // Ebitengine tries to call game's Update function 60 times a second by default. In other words,
  200. // TPS (ticks per second) is 60 by default.
  201. // This is not related to framerate (display's refresh rate).
  202. //
  203. // RunGame returns error when 1) an error happens in the underlying graphics driver, 2) an audio error happens
  204. // or 3) Update returns an error. In the case of 3), RunGame returns the same error so far, but it is recommended to
  205. // use errors.Is when you check the returned error is the error you want, rather than comparing the values
  206. // with == or != directly.
  207. //
  208. // If you want to terminate a game on desktops, it is recommended to return Termination at Update, which will halt
  209. // execution without returning an error value from RunGame.
  210. //
  211. // The size unit is device-independent pixel.
  212. //
  213. // Don't call RunGame or RunGameWithOptions twice or more in one process.
  214. func RunGame(game Game) error {
  215. return RunGameWithOptions(game, nil)
  216. }
  217. // RunGameOptions represents options for RunGameWithOptions.
  218. type RunGameOptions struct {
  219. // GraphicsLibrary is a graphics library Ebitengine will use.
  220. //
  221. // The default (zero) value is GraphicsLibraryAuto, which lets Ebitengine choose the graphics library.
  222. GraphicsLibrary GraphicsLibrary
  223. // InitUnfocused indicates whether the window is unfocused or not on launching.
  224. // InitUnfocused is valid on desktops and browsers.
  225. //
  226. // The default (zero) value is false, which means that the window is focused.
  227. InitUnfocused bool
  228. // ScreenTransparent indicates whether the window is transparent or not.
  229. // ScreenTransparent is valid on desktops and browsers.
  230. //
  231. // The default (zero) value is false, which means that the window is not transparent.
  232. ScreenTransparent bool
  233. // SkipTaskbar indicates whether an application icon is shown on a taskbar or not.
  234. // SkipTaskbar is valid only on Windows.
  235. //
  236. // The default (zero) value is false, which means that an icon is shown on a taskbar.
  237. SkipTaskbar bool
  238. // SingleThread indicates whether the single thread mode is used explicitly or not.
  239. // The single thread mode disables Ebitengine's thread safety to unlock maximum performance.
  240. // If you use this you will have to manage threads yourself.
  241. // Functions like `SetWindowSize` will no longer be concurrent-safe with this build tag.
  242. // They must be called from the main thread or the same goroutine as the given game's callback functions like Update.
  243. //
  244. // SingleThread works only with desktops and consoles.
  245. //
  246. // If SingleThread is false, and if the build tag `ebitenginesinglethread` is specified,
  247. // the single thread mode is used.
  248. //
  249. // The default (zero) value is false, which means that the single thread mode is disabled.
  250. SingleThread bool
  251. // DisableHiDPI indicates whether the rendering for HiDPI is disabled or not.
  252. // If HiDPI is disabled, the device scale factor is always 1 i.e. Monitor's DeviceScaleFactor always returns 1.
  253. // This is useful to get a better performance on HiDPI displays, in the expense of rendering quality.
  254. //
  255. // DisableHiDPI is available only on browsers.
  256. //
  257. // The default (zero) value is false, which means that HiDPI is enabled.
  258. DisableHiDPI bool
  259. // ColorSpace indicates the color space of the screen.
  260. //
  261. // ColorSpace is available only with some graphics libraries (macOS Metal and WebGL so far).
  262. // Otherwise, ColorSpace is ignored.
  263. //
  264. // The default (zero) value is ColorSpaceDefault, which means that color space depends on the environment.
  265. ColorSpace ColorSpace
  266. // X11DisplayName is a class name in the ICCCM WM_CLASS window property.
  267. X11ClassName string
  268. // X11InstanceName is an instance name in the ICCCM WM_CLASS window property.
  269. X11InstanceName string
  270. }
  271. // RunGameWithOptions starts the main loop and runs the game with the specified options.
  272. // game's Update function is called every tick to update the game logic.
  273. // game's Draw function is called every frame to draw the screen.
  274. // game's Layout function is called when necessary, and you can specify the logical screen size by the function.
  275. //
  276. // options can be nil. In this case, the default options are used.
  277. //
  278. // If game implements FinalScreenDrawer, its DrawFinalScreen is called after Draw.
  279. // The argument screen represents the final screen. The argument offscreen is an offscreen modified at Draw.
  280. // If game does not implement FinalScreenDrawer, the default rendering for the final screen is used.
  281. //
  282. // game's functions are called on the same goroutine.
  283. //
  284. // On browsers, it is strongly recommended to use iframe if you embed an Ebitengine application in your website.
  285. //
  286. // RunGameWithOptions must be called on the main thread.
  287. // Note that Ebitengine bounds the main goroutine to the main OS thread by runtime.LockOSThread.
  288. //
  289. // Ebitengine tries to call game's Update function 60 times a second by default. In other words,
  290. // TPS (ticks per second) is 60 by default.
  291. // This is not related to framerate (display's refresh rate).
  292. //
  293. // RunGameWithOptions returns error when 1) an error happens in the underlying graphics driver, 2) an audio error happens
  294. // or 3) Update returns an error. In the case of 3), RunGameWithOptions returns the same error so far, but it is recommended to
  295. // use errors.Is when you check the returned error is the error you want, rather than comparing the values
  296. // with == or != directly.
  297. //
  298. // If you want to terminate a game on desktops, it is recommended to return Termination at Update, which will halt
  299. // execution without returning an error value from RunGameWithOptions.
  300. //
  301. // The size unit is device-independent pixel.
  302. //
  303. // Don't call RunGame or RunGameWithOptions twice or more in one process.
  304. func RunGameWithOptions(game Game, options *RunGameOptions) error {
  305. defer isRunGameEnded_.Store(true)
  306. initializeWindowPositionIfNeeded(WindowSize())
  307. op := toUIRunOptions(options)
  308. // This is necessary to change the result of IsScreenTransparent.
  309. screenTransparent.Store(op.ScreenTransparent)
  310. g := newGameForUI(game, op.ScreenTransparent)
  311. if err := ui.Get().Run(g, op); err != nil {
  312. if errors.Is(err, Termination) {
  313. return nil
  314. }
  315. return err
  316. }
  317. return nil
  318. }
  319. func isRunGameEnded() bool {
  320. return isRunGameEnded_.Load()
  321. }
  322. // ScreenSizeInFullscreen returns the size in device-independent pixels when the game is fullscreen.
  323. // The adopted monitor is the 'current' monitor which the window belongs to.
  324. // The returned value can be given to SetSize function if the perfectly fit fullscreen is needed.
  325. //
  326. // On browsers, ScreenSizeInFullscreen returns the 'window' (global object) size, not 'screen' size.
  327. // ScreenSizeInFullscreen's returning value is different from the actual screen size and this is a known issue (#2145).
  328. // For browsers, it is recommended to use Screen API (https://developer.mozilla.org/en-US/docs/Web/API/Screen) if needed.
  329. //
  330. // On mobiles, ScreenSizeInFullscreen returns (0, 0) so far.
  331. //
  332. // ScreenSizeInFullscreen's use cases are limited. If you are making a fullscreen application, you can use RunGame and
  333. // the Game interface's Layout function instead. If you are making a not-fullscreen application but the application's
  334. // behavior depends on the monitor size, ScreenSizeInFullscreen is useful.
  335. //
  336. // ScreenSizeInFullscreen must be called on the main thread before ebiten.RunGame, and is concurrent-safe after
  337. // ebiten.RunGame.
  338. //
  339. // Deprecated: as of v2.6. Use Monitor().Size() instead.
  340. func ScreenSizeInFullscreen() (int, int) {
  341. return ui.Get().ScreenSizeInFullscreen()
  342. }
  343. // CursorMode returns the current cursor mode.
  344. //
  345. // CursorMode returns CursorModeHidden on mobiles.
  346. //
  347. // CursorMode is concurrent-safe.
  348. func CursorMode() CursorModeType {
  349. return CursorModeType(ui.Get().CursorMode())
  350. }
  351. // SetCursorMode sets the render and capture mode of the mouse cursor.
  352. // CursorModeVisible sets the cursor to always be visible.
  353. // CursorModeHidden hides the system cursor when over the window.
  354. // CursorModeCaptured hides the system cursor and locks it to the window.
  355. //
  356. // CursorModeCaptured also works on browsers.
  357. // When the user exits the captured mode not by SetCursorMode but by the UI (e.g., pressing ESC),
  358. // the previous cursor mode is set automatically.
  359. //
  360. // On browsers, setting CursorModeCaptured might be delayed especially just after escaping from a capture.
  361. //
  362. // On browsers, capturing a cursor requires a user gesture, otherwise SetCursorMode does nothing but leave an error message in console.
  363. // This behavior varies across browser implementations.
  364. // Check a user interaction before calling capturing a cursor e.g. by IsMouseButtonPressed or IsKeyPressed.
  365. //
  366. // SetCursorMode does nothing on mobiles.
  367. //
  368. // SetCursorMode is concurrent-safe.
  369. func SetCursorMode(mode CursorModeType) {
  370. ui.Get().SetCursorMode(ui.CursorMode(mode))
  371. }
  372. // IsFullscreen reports whether the current mode is fullscreen or not.
  373. //
  374. // IsFullscreen always returns false on mobiles.
  375. //
  376. // IsFullscreen is concurrent-safe.
  377. func IsFullscreen() bool {
  378. return ui.Get().IsFullscreen()
  379. }
  380. // SetFullscreen changes the current mode to fullscreen or not on desktops and browsers.
  381. //
  382. // In fullscreen mode, the game screen is automatically enlarged
  383. // to fit with the monitor. The current scale value is ignored.
  384. //
  385. // On desktops, Ebitengine uses 'windowed' fullscreen mode, which doesn't change
  386. // your monitor's resolution.
  387. //
  388. // On browsers, triggering fullscreen requires a user gesture, otherwise SetFullscreen does nothing but leave an error message in console.
  389. // This behavior varies across browser implementations.
  390. // Check a user interaction before triggering fullscreen e.g. by IsMouseButtonPressed or IsKeyPressed.
  391. //
  392. // SetFullscreen does nothing on mobiles.
  393. //
  394. // SetFullscreen does nothing on macOS when the window is fullscreened natively by the macOS desktop
  395. // instead of SetFullscreen(true).
  396. //
  397. // SetFullscreen is concurrent-safe.
  398. func SetFullscreen(fullscreen bool) {
  399. ui.Get().SetFullscreen(fullscreen)
  400. }
  401. // IsFocused returns a boolean value indicating whether
  402. // the game is in focus or in the foreground.
  403. //
  404. // IsFocused will only return true if IsRunnableOnUnfocused is false.
  405. //
  406. // IsFocused is concurrent-safe.
  407. func IsFocused() bool {
  408. return ui.Get().IsFocused()
  409. }
  410. // IsRunnableOnUnfocused returns a boolean value indicating whether
  411. // the game runs even in background.
  412. //
  413. // IsRunnableOnUnfocused is concurrent-safe.
  414. func IsRunnableOnUnfocused() bool {
  415. return ui.Get().IsRunnableOnUnfocused()
  416. }
  417. // SetRunnableOnUnfocused sets the state if the game runs even in background.
  418. //
  419. // If the given value is true, the game runs even in background e.g. when losing focus.
  420. // The initial state is true.
  421. //
  422. // Known issue: On browsers, even if the state is on, the game doesn't run in background tabs.
  423. // This is because browsers throttles background tabs not to often update.
  424. //
  425. // SetRunnableOnUnfocused does nothing on mobiles so far.
  426. //
  427. // SetRunnableOnUnfocused is concurrent-safe.
  428. func SetRunnableOnUnfocused(runnableOnUnfocused bool) {
  429. ui.Get().SetRunnableOnUnfocused(runnableOnUnfocused)
  430. }
  431. // DeviceScaleFactor returns a device scale factor value of the current monitor which the window belongs to.
  432. //
  433. // DeviceScaleFactor returns a meaningful value on high-DPI display environment,
  434. // otherwise DeviceScaleFactor returns 1.
  435. //
  436. // DeviceScaleFactor might panic on init function on some devices like Android.
  437. // Then, it is not recommended to call DeviceScaleFactor from init functions.
  438. //
  439. // DeviceScaleFactor must be called on the main thread before the main loop, and is concurrent-safe after the main
  440. // loop.
  441. //
  442. // BUG: DeviceScaleFactor value is not affected by SetWindowPosition before RunGame (#1575).
  443. //
  444. // Deprecated: as of v2.6. Use Monitor().DeviceScaleFactor() instead.
  445. func DeviceScaleFactor() float64 {
  446. return Monitor().DeviceScaleFactor()
  447. }
  448. // IsVsyncEnabled returns a boolean value indicating whether
  449. // the game uses the display's vsync.
  450. func IsVsyncEnabled() bool {
  451. return ui.Get().FPSMode() == ui.FPSModeVsyncOn
  452. }
  453. // SetVsyncEnabled sets a boolean value indicating whether
  454. // the game uses the display's vsync.
  455. func SetVsyncEnabled(enabled bool) {
  456. if enabled {
  457. ui.Get().SetFPSMode(ui.FPSModeVsyncOn)
  458. } else {
  459. ui.Get().SetFPSMode(ui.FPSModeVsyncOffMaximum)
  460. }
  461. }
  462. // FPSModeType is a type of FPS modes.
  463. //
  464. // Deprecated: as of v2.5. Use SetVsyncEnabled instead.
  465. type FPSModeType int
  466. const (
  467. // FPSModeVsyncOn indicates that the game tries to sync the display's refresh rate.
  468. // FPSModeVsyncOn is the default mode.
  469. //
  470. // Deprecated: as of v2.5. Use SetVsyncEnabled(true) instead.
  471. FPSModeVsyncOn FPSModeType = FPSModeType(ui.FPSModeVsyncOn)
  472. // FPSModeVsyncOffMaximum indicates that the game doesn't sync with vsync, and
  473. // the game is updated whenever possible.
  474. //
  475. // Be careful that FPSModeVsyncOffMaximum might consume a lot of battery power.
  476. //
  477. // In FPSModeVsyncOffMaximum, the game's Draw is called almost without sleeping.
  478. // The game's Update is called based on the specified TPS.
  479. //
  480. // Deprecated: as of v2.5. Use SetVsyncEnabled(false) instead.
  481. FPSModeVsyncOffMaximum FPSModeType = FPSModeType(ui.FPSModeVsyncOffMaximum)
  482. // FPSModeVsyncOffMinimum indicates that the game doesn't sync with vsync, and
  483. // the game is updated only when necessary.
  484. //
  485. // FPSModeVsyncOffMinimum is useful for relatively static applications to save battery power.
  486. //
  487. // In FPSModeVsyncOffMinimum, the game's Update and Draw are called only when
  488. // 1) new inputting except for gamepads is detected, or 2) ScheduleFrame is called.
  489. // In FPSModeVsyncOffMinimum, TPS is SyncWithFPS no matter what TPS is specified at SetTPS.
  490. //
  491. // Deprecated: as of v2.5. Use SetScreenClearedEveryFrame(false) instead.
  492. // See examples/skipdraw for GPU optimization with SetScreenClearedEveryFrame(false).
  493. FPSModeVsyncOffMinimum FPSModeType = FPSModeType(ui.FPSModeVsyncOffMinimum)
  494. )
  495. // FPSMode returns the current FPS mode.
  496. //
  497. // FPSMode is concurrent-safe.
  498. //
  499. // Deprecated: as of v2.5. Use SetVsyncEnabled instead.
  500. func FPSMode() FPSModeType {
  501. return FPSModeType(ui.Get().FPSMode())
  502. }
  503. // SetFPSMode sets the FPS mode.
  504. // The default FPS mode is FPSModeVsyncOn.
  505. //
  506. // SetFPSMode is concurrent-safe.
  507. //
  508. // Deprecated: as of v2.5. Use SetVsyncEnabled instead.
  509. func SetFPSMode(mode FPSModeType) {
  510. ui.Get().SetFPSMode(ui.FPSModeType(mode))
  511. }
  512. // ScheduleFrame schedules a next frame when the current FPS mode is FPSModeVsyncOffMinimum.
  513. //
  514. // ScheduleFrame is concurrent-safe.
  515. //
  516. // Deprecated: as of v2.5. Use SetScreenClearedEveryFrame(false) instead.
  517. // See examples/skipdraw for GPU optimization with SetScreenClearedEveryFrame(false).
  518. func ScheduleFrame() {
  519. ui.Get().ScheduleFrame()
  520. }
  521. // TPS returns the current maximum TPS.
  522. //
  523. // TPS is concurrent-safe.
  524. func TPS() int {
  525. return clock.TPS()
  526. }
  527. // MaxTPS returns the current maximum TPS.
  528. //
  529. // Deprecated: as of v2.4. Use TPS instead.
  530. func MaxTPS() int {
  531. return TPS()
  532. }
  533. // ActualTPS returns the current TPS (ticks per second),
  534. // that represents how many times Update function is called in a second.
  535. //
  536. // This value is for measurement and/or debug, and your game logic should not rely on this value.
  537. //
  538. // ActualTPS is concurrent-safe.
  539. func ActualTPS() float64 {
  540. return clock.ActualTPS()
  541. }
  542. // CurrentTPS returns the current TPS (ticks per second),
  543. // that represents how many times Update function is called in a second.
  544. //
  545. // Deprecated: as of v2.4. Use ActualTPS instead.
  546. func CurrentTPS() float64 {
  547. return ActualTPS()
  548. }
  549. // SyncWithFPS is a special TPS value that means TPS syncs with FPS.
  550. const SyncWithFPS = clock.SyncWithFPS
  551. // UncappedTPS is a special TPS value that means TPS syncs with FPS.
  552. //
  553. // Deprecated: as of v2.2. Use SyncWithFPS instead.
  554. const UncappedTPS = SyncWithFPS
  555. // SetTPS sets the maximum TPS (ticks per second),
  556. // that represents how many times updating function is called per second.
  557. // The initial value is 60.
  558. //
  559. // If tps is SyncWithFPS, TPS is uncapped and the game is updated per frame.
  560. // If tps is negative but not SyncWithFPS, SetTPS panics.
  561. //
  562. // SetTPS is concurrent-safe.
  563. func SetTPS(tps int) {
  564. clock.SetTPS(tps)
  565. }
  566. // SetMaxTPS sets the maximum TPS (ticks per second),
  567. // that represents how many times updating function is called per second.
  568. //
  569. // Deprecated: as of v2.4. Use SetTPS instead.
  570. func SetMaxTPS(tps int) {
  571. SetTPS(tps)
  572. }
  573. // IsScreenTransparent reports whether the window is transparent.
  574. //
  575. // IsScreenTransparent is concurrent-safe.
  576. //
  577. // Deprecated: as of v2.5.
  578. func IsScreenTransparent() bool {
  579. if !ui.IsScreenTransparentAvailable() {
  580. return false
  581. }
  582. return screenTransparent.Load()
  583. }
  584. // SetScreenTransparent sets the state if the window is transparent.
  585. //
  586. // SetScreenTransparent panics if SetScreenTransparent is called after the main loop.
  587. //
  588. // SetScreenTransparent does nothing on mobiles.
  589. //
  590. // SetScreenTransparent is concurrent-safe.
  591. //
  592. // Deprecated: as of v2.5. Use RunGameWithOptions instead.
  593. func SetScreenTransparent(transparent bool) {
  594. screenTransparent.Store(transparent)
  595. }
  596. var screenTransparent atomic.Bool
  597. // SetInitFocused sets whether the application is focused on show.
  598. // The default value is true, i.e., the application is focused.
  599. //
  600. // SetInitFocused does nothing on mobile.
  601. //
  602. // SetInitFocused panics if this is called after the main loop.
  603. //
  604. // SetInitFocused is concurrent-safe.
  605. //
  606. // Deprecated: as of v2.5. Use RunGameWithOptions instead.
  607. func SetInitFocused(focused bool) {
  608. initUnfocused.Store(!focused)
  609. }
  610. var initUnfocused atomic.Bool
  611. func toUIRunOptions(options *RunGameOptions) *ui.RunOptions {
  612. const (
  613. defaultX11ClassName = "Ebitengine-Application"
  614. defaultX11InstanceName = "ebitengine-application"
  615. )
  616. if options == nil {
  617. return &ui.RunOptions{
  618. InitUnfocused: initUnfocused.Load(),
  619. ScreenTransparent: screenTransparent.Load(),
  620. X11ClassName: defaultX11ClassName,
  621. X11InstanceName: defaultX11InstanceName,
  622. }
  623. }
  624. if options.X11ClassName == "" {
  625. options.X11ClassName = defaultX11ClassName
  626. }
  627. if options.X11InstanceName == "" {
  628. options.X11InstanceName = defaultX11InstanceName
  629. }
  630. // ui.RunOptions.StrictContextRestoration is not used so far (#3098).
  631. // This might be reused in the future.
  632. // The original comment for StrictContextRestration is as follows:
  633. //
  634. // StrictContextRestration indicates whether the context lost should be restored strictly by Ebitengine or not.
  635. //
  636. // StrictContextRestration is available only on Android. Otherwise, StrictContextRestration is ignored.
  637. // Thus, StrictContextRestration should be used with mobile.SetGameWithOptions, rather than RunGameWithOptions.
  638. //
  639. // In Android, Ebitengien uses `GLSurfaceView`'s `setPreserveEGLContextOnPause(true)`.
  640. // This works in most cases, but it is still possible that the context is lost in some minor cases.
  641. //
  642. // When StrictContextRestration is true, Ebitengine tries to restore the context more strictly
  643. // for such minor cases.
  644. // However, this might cause a performance issue since Ebitengine tries to keep all the information
  645. // to restore the context.
  646. //
  647. // When StrictContextRestration is false, Ebitengine does nothing special to restore the context and
  648. // relies on the OS's behavior.
  649. //
  650. // The default (zero) value is false.
  651. return &ui.RunOptions{
  652. GraphicsLibrary: ui.GraphicsLibrary(options.GraphicsLibrary),
  653. InitUnfocused: options.InitUnfocused,
  654. ScreenTransparent: options.ScreenTransparent,
  655. SkipTaskbar: options.SkipTaskbar,
  656. SingleThread: options.SingleThread,
  657. DisableHiDPI: options.DisableHiDPI,
  658. ColorSpace: graphicsdriver.ColorSpace(options.ColorSpace),
  659. X11ClassName: options.X11ClassName,
  660. X11InstanceName: options.X11InstanceName,
  661. }
  662. }
  663. // DroppedFiles returns a virtual file system that includes only dropped files and/or directories
  664. // at its root directory, at the time Update is called.
  665. //
  666. // DroppedFiles works on desktops and browsers.
  667. //
  668. // DroppedFiles is concurrent-safe.
  669. func DroppedFiles() fs.FS {
  670. return theInputState.droppedFiles()
  671. }