Documentation ¶
Overview ¶
Package tge core contains interfaces and core implementation for supported targets:
- desktop : MacOS, Linux, Windows
- android : Android 5+
- ios : IOS 8+ (Work in progress)
- browser : Chrome, Firefox, Safari (limited support)
TGE Core should not be used directly, it only defines interfaces and is used by TGE Command Line Tool :
see https://github.com/thommil/tge-cli
App ¶
An App is the main entry point of TGE, the main() function should normally just starts the Runtime, any other code not handled by the Runtime is potenitally not portable:
import "github.com/thommil/tge" func main() { tge.Run(&MyApp{}) }
The App interface is described here and the implementation details in the auto generated app.go using tge-cli.
Runtime ¶
The Runtime instance is initialized through the Run(*App) function of main package. At startup, the Runtime looks for registered plugins and initializes them. Then the App instance is initialized and started.
The Runtime instance also exposes API for loading assets and subscribing to events in a generic way.
Runtime exposes none portable objects like Host (backend) and Renderer (graphical context), they can be used to implement custom behaviour depending on target in Apps or Plugins, the implementations are as follows:
Host: - desktop : *sdl.Window - SDL2 from https://github.com/veandco/go-sdl2 - android/ios : mobile.App - Custom gomobile from https://github.com/thommil/tge-mobile - browser : *js.Value - Gobal element through WebAssembly from Go 1.12 Renderer: - desktop : *sdl.GLContext - SDL2 from https://github.com/veandco/go-sdl2 - android/ios : gl.Context - Custom gomobile from https://github.com/thommil/tge-mobile - browser : *js.Value - WebGL/WebGL2 context through WebAssembly from Go 1.12
Rendering ¶
TGE uses Go channel mechanism to handle rendering, two loops are running side by side:
- Ticker loop with Tick() : handle CPU treatments (physics, AI, logical) and trigger rendering
- Render loop with Render() : handle GPU treatments (draw calls)
Both loops are synchronized using a dedicated channel passed in parameter of each method. As this method allows to make CPU/GPU treatments asynchronous, shared objects between contexts must correctly handled to avoid conflicts. The sync channel is typed as interface{}, it can also be used to pass content and select specific treatments based on underlying interface type. See examples for more details.
A good candidate for copy if the reflect.Copy() function:
reflect.Copy(reflect.ValueOf(renderData), reflect.ValueOf(tickData))
If your data is based on something else than slices but its size justifies low level memory copy, you can also put ticker data in a single element slice and use reflect.Copy() on it.
Events ¶
Minimal set of events is handled by Runtime at the most possible portable way. Events are then propagated through publish/subscribe:
Subscribe(channel string, listener Listener) Unsubscribe(channel string, listener Listener) Publish(event Event)
Events are in their raw form (ie modifiers or gestures are not handled). It's up to the application to implement specific needs. The aim of this approach is to keep the runtime generic and fast by limiting treatments.
A dedicated plugin to generate advanced events will be available soon.
Plugins ¶
As TGE core is intended to be as light as possible, all heavy treatments are deported to plugins. The goal is to offer a portable API from Plugins by relying on Runtime.
Plugins are automatically registered at Go init() step, to use it, just import them as standard Go packages, ex:
import "github.com/thommil/tge-gl" func (app *App) OnStart(runtime tge.Runtime) error{ gl.ClearColor(0, 0, 0, 1) }
It's also possible to create custom plugins by implementing Plugin interface and registering it in the Go init() function :
package myplugin import ( tge "github.com/thommil/tge" ) type plugin struct { Name string } func init() { tge.Register(plugin{"myplugin"}) } func (p *plugin) Init(runtime tge.Runtime) error { // Init code HERE if needed return nil } func (p *plugin) GetName() string { return p.Name } func (p *plugin) Dispose() { // Dispose code HERE if needed }
Index ¶
Constants ¶
const ( // AllEventsDisable disables all input events on App AllEventsDisable = 0x00 // MouseButtonEventEnabled enabled mouse buttons events receiver on App MouseButtonEventEnabled = 0x01 // MouseMotionEventEnabled enabled mouse motion events receiver on App MouseMotionEventEnabled = 0x02 // ScrollEventEnabled enabled scroll event receiver on App ScrollEventEnabled = 0x04 // KeyEventEnabled enabled key event receiver on App KeyEventEnabled = 0x08 // AllEventsEnabled enables all input events on App AllEventsEnabled = 0xFFFF )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type App ¶
type App interface { // OnCreate is called at App instanciation, the Runtime resources are not // yet available. Settings and treatments not related to Runtime should be done here. OnCreate(settings *Settings) error // OnStart is called when all Runtime resources are available but looping as not been // started. Initializations should be done here (GL conf, physics engine ...). OnStart(runtime Runtime) error // OnResume is called just after OnStart and also when the Runtime is awaken after a pause. OnResume() // OnRender is called each time the graphical context is redrawn. This method should only implements // graphical calls and not logical ones. The syncChan is used to wait for Tick() loop draw commands OnRender(elaspedTime time.Duration, syncChan <-chan interface{}) // OnTick handles logical operations like physics, AI or any background task not relatd to graphics. // The syncChan is used to notify Render() loop with draw commands. OnTick(elaspedTime time.Duration, syncChan chan<- interface{}) // OnPause is called when the Runtime lose focus (alt-tab, home button, tab change ...) This is a good entry point to // set and display a pause screen OnPause() // OnStop is called when the Runtime is ending, context saving should be done here. On current Android version this // handler is also called when the application is paused (and restart after). OnStop() // OnDispose is called when all exit treatments are done for cleaning task (memory, tmp files ...) OnDispose() }
App is the main entry point of a TGE Application. Created using TGE Command Line Tools.
See generated app.go by tge-cli for more details and explanations.
type Button ¶
type Button byte
Button indicates the type of button or touch used in event
const ( // ButtonNone Button for not available or not applicable ButtonNone Button = 0x00 // ButtonLeft Button for left button ButtonLeft Button = 0x01 // ButtonRight Button for right button ButtonRight Button = 0x02 // ButtonMiddle Button for middle button ButtonMiddle Button = 0x04 // TouchFirst Button for first finger touch TouchFirst Button = 0x10 // TouchSecond Button for second finger touch TouchSecond Button = 0x20 // TouchThird Button for third finger touch TouchThird Button = 0x40 // ButtonLeftOrTouchFirst helper to test left button or first touch ButtonLeftOrTouchFirst Button = 0x11 )
Buttons values
type Event ¶
type Event interface { // Type defines a unique keywork/channel for event Channel() string }
Event interface defines an event base by its channel
type EventMask ¶
type EventMask int
EventMask defines mask event for enable/disable events receivers at runtime level
type KeyCode ¶
type KeyCode int
KeyCode is used to map raw key codes values
const ( KeyCodeUnknown KeyCode = 0 // Printable KeyCodeA KeyCode = 1 KeyCodeB KeyCode = 2 KeyCodeC KeyCode = 3 KeyCodeD KeyCode = 4 KeyCodeE KeyCode = 5 KeyCodeF KeyCode = 6 KeyCodeG KeyCode = 7 KeyCodeH KeyCode = 8 KeyCodeI KeyCode = 9 KeyCodeJ KeyCode = 10 KeyCodeK KeyCode = 11 KeyCodeL KeyCode = 12 KeyCodeM KeyCode = 13 KeyCodeN KeyCode = 14 KeyCodeO KeyCode = 15 KeyCodeP KeyCode = 16 KeyCodeQ KeyCode = 17 KeyCodeR KeyCode = 18 KeyCodeS KeyCode = 19 KeyCodeT KeyCode = 20 KeyCodeU KeyCode = 21 KeyCodeV KeyCode = 22 KeyCodeW KeyCode = 23 KeyCodeX KeyCode = 24 KeyCodeY KeyCode = 25 KeyCodeZ KeyCode = 26 KeyCode1 KeyCode = 27 KeyCode2 KeyCode = 28 KeyCode3 KeyCode = 29 KeyCode4 KeyCode = 30 KeyCode5 KeyCode = 31 KeyCode6 KeyCode = 32 KeyCode7 KeyCode = 33 KeyCode8 KeyCode = 34 KeyCode9 KeyCode = 35 KeyCode0 KeyCode = 36 KeyCodeReturnEnter KeyCode = 37 KeyCodeTab KeyCode = 38 KeyCodeSpacebar KeyCode = 39 KeyCodeHyphenMinus KeyCode = 40 // - KeyCodeEqualSign KeyCode = 41 // = KeyCodeLeftSquareBracket KeyCode = 42 // [ KeyCodeRightSquareBracket KeyCode = 43 // ] KeyCodeBackslash KeyCode = 44 // \ KeyCodeSemicolon KeyCode = 45 // ; KeyCodeApostrophe KeyCode = 46 // ' KeyCodeGraveAccent KeyCode = 47 // ` KeyCodeComma KeyCode = 48 // , KeyCodeFullStop KeyCode = 49 // . KeyCodeSlash KeyCode = 50 // / KeyCodeKeypadSlash KeyCode = 51 // / KeyCodeKeypadAsterisk KeyCode = 52 // * KeyCodeKeypadHyphenMinus KeyCode = 53 // - KeyCodeKeypadPlusSign KeyCode = 54 // + KeyCodeKeypadEnter KeyCode = 55 KeyCodeKeypad1 KeyCode = 56 KeyCodeKeypad2 KeyCode = 57 KeyCodeKeypad3 KeyCode = 58 KeyCodeKeypad4 KeyCode = 59 KeyCodeKeypad5 KeyCode = 60 KeyCodeKeypad6 KeyCode = 61 KeyCodeKeypad7 KeyCode = 62 KeyCodeKeypad8 KeyCode = 63 KeyCodeKeypad9 KeyCode = 64 KeyCodeKeypad0 KeyCode = 65 KeyCodeKeypadFullStop KeyCode = 66 // . KeyCodeKeypadEqualSign KeyCode = 67 // = KeyCodeAt KeyCode = 68 // @ KeyCodeGreaterThan KeyCode = 69 // > KeyCodeLesserThan KeyCode = 70 // < KeyCodeDollar KeyCode = 71 // $ KeyCodeColon KeyCode = 72 // : KeyCodeLeftParenthesis KeyCode = 73 // ( KeyCodeLRightParenthesis KeyCode = 74 // ) KeyCodeAmpersand KeyCode = 75 // & KeyCodeHash KeyCode = 76 // # KeyDoubleQuote KeyCode = 77 // " KeyQuote KeyCode = 78 // ' KeyParapgrah KeyCode = 79 // § KeyExclamationMark KeyCode = 80 // ! KeyUnderscore KeyCode = 81 // _ KeyQuestionMark KeyCode = 82 // ? KeyPercent KeyCode = 83 // % KeyDegree KeyCode = 84 // ° KeyCodeEscape KeyCode = 101 KeyCodeCapsLock KeyCode = 102 KeyCodeDeleteBackspace KeyCode = 103 KeyCodePause KeyCode = 104 KeyCodeInsert KeyCode = 105 KeyCodeHome KeyCode = 106 KeyCodePageUp KeyCode = 107 KeyCodeDeleteForward KeyCode = 108 KeyCodeEnd KeyCode = 109 KeyCodePageDown KeyCode = 110 KeyCodeRightArrow KeyCode = 111 KeyCodeLeftArrow KeyCode = 112 KeyCodeDownArrow KeyCode = 113 KeyCodeUpArrow KeyCode = 114 KeyCodeKeypadNumLock KeyCode = 115 KeyCodeHelp KeyCode = 116 KeyCodeMute KeyCode = 120 KeyCodeVolumeUp KeyCode = 121 KeyCodeVolumeDown KeyCode = 122 KeyCodeF1 KeyCode = 201 KeyCodeF2 KeyCode = 202 KeyCodeF3 KeyCode = 203 KeyCodeF4 KeyCode = 204 KeyCodeF5 KeyCode = 205 KeyCodeF6 KeyCode = 206 KeyCodeF7 KeyCode = 207 KeyCodeF8 KeyCode = 208 KeyCodeF9 KeyCode = 209 KeyCodeF10 KeyCode = 210 KeyCodeF11 KeyCode = 211 KeyCodeF12 KeyCode = 212 KeyCodeLeftControl KeyCode = 301 KeyCodeLeftShift KeyCode = 302 KeyCodeLeftAlt KeyCode = 303 KeyCodeLeftGUI KeyCode = 304 KeyCodeRightControl KeyCode = 305 KeyCodeRightShift KeyCode = 306 KeyCodeRightAlt KeyCode = 307 KeyCodeRightGUI KeyCode = 308 KeyCodeCompose KeyCode = 0x10000 )
Keycode constants
func (KeyCode) IsFunction ¶
IsFunction indicates a function KeyCode
func (KeyCode) IsModifier ¶
IsModifier indicates a modifier KeyCode
func (KeyCode) IsPrintable ¶
IsPrintable indicates a printable KeyCode
type KeyEvent ¶
KeyEvent defines a down/up key event, the Key attribute is portable across targets, the Value is the string representation of the key
type Listener ¶
Listener is the callback definition for publish/subscribe, the return value indicates if the event has been consumed (true) and propagation stopped, in other case the next registered Listener is called
type MouseEvent ¶
MouseEvent is triggered on mouse/touch down/up event and mouse motion event too
type Plugin ¶
type Plugin interface { // Init is called before Runtime looping Init(runtime Runtime) error // GetName allows Runtime to identify plugin by its name GetName() string // Dispose is called at end of Runtime before exiting Dispose() }
Plugin interface defines the API used by the Runtime to handle plugins
type ResizeEvent ¶
type ResizeEvent struct {
Width, Height int32
}
ResizeEvent is triggered when TGE painting area is resized
func (ResizeEvent) Channel ¶
func (e ResizeEvent) Channel() string
Channel of ResizeEvent = "resize"
type Runtime ¶
type Runtime interface { // GetAsset retrieves assets in []byte form, assets are always stored in // package asset folder independently of the target GetAsset(path string) ([]byte, error) // GetHost is for low level and target specific implementation and allows to // retrieve the underlying backend of the Runtime (see package description) GetHost() interface{} // GetRenderer is for low level and target specific implementation and allows to // retrieve the underlying graphical context of the Runtime (see package description) GetRenderer() interface{} // GetSettings returns the current Runtime settings GetSettings() Settings // Subscribe register a new Listener to specified channel Subscribe(channel string, listener Listener) // Unsubscribe deregister a new Listener from specified channel Unsubscribe(channel string, listener Listener) // Publish send an Event on channel defined in the Event.Channel() Publish(event Event) // Stop allows App to end the Runtime directly Stop() }
Runtime defines the commmon API across runtimes implementations
type ScrollEvent ¶
type ScrollEvent struct {
X, Y int32
}
ScrollEvent is called only on desktop/browser, X/Y values are only [-1, 0, 1] to normalize scrolling across targets
func (ScrollEvent) Channel ¶
func (e ScrollEvent) Channel() string
Channel of ScrollEvent = "scroll"
type Settings ¶
type Settings struct { // Name of the App Name string `json:"name" yaml:"name"` // Fullscreen indicates if the app must be run in fullscreen mode Fullscreen bool `json:"fullscreen" yaml:"fullscreen"` // Width of the window if run windowed only Width int `json:"width" yaml:"width"` // Height of the window if run windowed only Height int `json:"height" yaml:"height"` // EventMask allows to enabled/disable events receiver on Runtime EventMask EventMask `json:"event_mask" yaml:"event_mask"` }
Settings definition of TGE application
type Type ¶
type Type byte
Type is a component of events to indicate a generic way of defining an event action.