gg #

Description

gg is V's simple graphics module. It is currently implemented using sokol, and makes easy creating apps that just need a way to draw simple 2D shapes, and to react to user's keyboard/mouse input.

Example

module main

import gg

fn main() {
    mut context := gg.new_context(
        bg_color:     gg.rgb(174, 198, 255)
        width:        600
        height:       400
        window_title: 'Polygons'
        frame_fn:     frame
    )
    context.run()
}

fn frame(mut ctx gg.Context) {
    ctx.begin()
    ctx.draw_convex_poly([f32(100.0), 100.0, 200.0, 100.0, 300.0, 200.0, 200.0, 300.0, 100.0, 300.0],
        gg.blue)
    ctx.draw_poly_empty([f32(50.0), 50.0, 70.0, 60.0, 90.0, 80.0, 70.0, 110.0], gg.black)
    ctx.draw_triangle_filled(450, 142, 530, 280, 370, 280, gg.red)
    ctx.end()
}

Multi-Window Applications

gg.App is an additive multi-window facade for programs that need to manage more than one native window from the same gg application. It is opt-in and is compiled only when the program is built with -d gg_multiwindow. examples/gg/multiwindow.v is the interactive example:

v -d gg_multiwindow run examples/gg/multiwindow.v

The existing single-window gg.Context API and behavior are unchanged. A normal import gg program that uses gg.new_context() does not load the native multi-window implementation. Without -d gg_multiwindow, the opt-in API surface is a non-render compatibility stub: accidental gg.App calls report a clear "compile with -d gg_multiwindow" error instead of pulling in x.multiwindow or native backend code.

Users normally import only gg. x.multiwindow is the lower-level lifecycle, window and render-surface layer used by the facade, and is available for backend or direct-control callers. Use backend: .auto for native applications. It selects the appropriate platform backend at runtime/build time, falling back only when a native backend is unavailable. On Linux, X11 native windows are opt-in with -d x_multiwindow_x11; Wayland remains opt-in with -d sokol_wayland. Tests and headless tools can request backend: .mock explicitly; the lower-level .mock path remains dependency-light and does not link X11/EGL/OpenGL by default.

The basic lifecycle is:

import gg

fn main() {
    mut app := gg.new_app(backend: .auto)!
    defer {
        app.stop() or {}
    }

    main_window := app.create_window(
        title:  'Main'
        width:  800
        height: 600
    )!

    app.run(
        event_fn: fn (event gg.WindowEvent, mut app gg.App) ! {
            match event.kind {
                .window_close_requested {
                    app.destroy_window(event.window)!
                }
                .window_destroyed {
                    if app.window_ids()!.len == 0 {
                        app.stop()!
                    }
                }
                else {}
            }
        }
    )!

    _ = main_window
}

Lifecycle-only applications can run with just event_fn; they do not require a renderer. frame_fn and draw_window() require an already render-capable app; they do not re-run .auto backend selection. Programs that plan to render should use gg.new_app(require_renderer: true) or verify app.capabilities().explicit_swapchain before rendering. Linux X11 rendering, including under Xvfb, needs both flags:

xvfb-run -a v -d gg_multiwindow -d x_multiwindow_x11 run examples/gg/multiwindow.v

AppConfig.app_id supplies the native application identity (currently the Wayland xdg_toplevel app id). A modal WindowConfig must name a live owner from the same app; ownerless modal windows are rejected before native allocation, whether hidden or visible. Destroying an owner destroys its complete owned-window tree child-first; stop() uses the same child-before-owner order for every remaining window. Destroying the final window does not stop the app automatically, so event loops should call app.stop() explicitly. For every destroyed descendant, pending clipboard and portal requests are cancelled and portal leases are invalidated during sealing, before any teardown result can be delivered. Their service cancellations precede readback cancellation and the final window_destroyed event in the canonical queue; teardown replay does not duplicate those terminals. After a window generation is sealed, state/capability queries and new service, readback, and native-borrow admissions fail as stale. Already admitted work follows the terminal or cancellation flow, and queued terminals remain deliverable.

examples/gg/multiwindow_render_runtime.v is an unattended CI probe, not an interactive launch target. Backend lanes compile it with -d gg_multiwindow plus -d x_multiwindow_x11, -d sokol_wayland, -d sokol_metal, or -d sokol_d3d11 as appropriate, and select the matching backend through V_MULTIWINDOW_PROBE_BACKEND. A process-tree watchdog supplies the private parent gate, enforces the deadline, and checks process cleanup. After all window and renderer cleanup succeeds, the probe emits {"example":"multiwindow_render_runtime","status":"PASS","cleanup":"complete"}.

Multi-Window Events

gg.App.run() dispatches all four ordered event families: lifecycle through event_fn, input through input_fn, native service results through window_service_fn, and readback terminals through readback_fn. Lifecycle events use gg.WindowEvent and cover created, resized, close-requested and destroyed windows. Input events use gg.WindowInputEvent, which adds the target gg.WindowId to the normal gg.Event payload so existing key, mouse, scroll, focus and window-state event fields keep the same gg-facing types. If any of the four queue callbacks returns an error, run() reinserts the current event and every untouched suffix event in their original order. All four handlers must therefore be idempotent, not only readback handlers. For native multi-window events, gg.Event.frame_count is assigned by the underlying multi-window owner poll cycle so events collected by the same app.poll_events() call share a frame count.

input_fn has the gg.AppInputFn shape:

fn (event gg.WindowInputEvent, mut app gg.App) !

For manual owner loops, call app.poll_events() and then either app.drain_window_queued_events() or a specialized drain. The canonical drain returns lifecycle, input, service, and readback envelopes in exact global acceptance order. drain_events(), drain_input_events(), and drain_window_service_events() each consume only a contiguous prefix of their own family; if another family is at the head, they return empty without skipping it. There is deliberately no separate gg readback drain: consume readbacks via readback_fn in run() or .readback entries from the canonical drain.

Input support is capability-driven. Check app.capabilities() before relying on a class of native events: input_events, mouse_events, keyboard_events, text_events, focus_events, drop_events and touch_events report what the selected backend can actually deliver. cursor_shapes reports whether app.set_window_cursor(id, shape) can update native hover cursor feedback, and is independent from interactive move/resize support. interactive_move_resize reports whether the runtime backend has the native handles needed for app.begin_window_move(id) and app.begin_window_resize(id, edge); individual calls can still fail when the platform requires a recent user-action serial. native_decorations reports whether native/server-side window decorations are effective for the running backend. Plain capability probes do not necessarily open a display, so runtime globals are authoritative only after gg.new_app() via app.capabilities(); on Wayland that includes wl_touch for touch, wl_data_device for drops, seats for interactive move/resize, and xdg-decoration negotiation for native decorations. Wayland cursor-shape reporting is stricter: cursor_shapes is true only after a wp_cursor_shape_device_v1 has been created for the active wl_pointer. Wayland requests server-side decorations through xdg-decoration when available; the compositor's configure(mode) decides the effective server_side or client_side mode. If server_side is refused or xdg-decoration is unavailable, apps and examples may draw a client-side fallback. Wayland cursor shape feedback uses wp_cursor_shape_manager_v1 when the compositor exposes it and the seat has a pointer; cursor theme selection remains compositor-side. wl_cursor_theme client-side fallback is not implemented, so app.capabilities() reports cursor_shapes == false on Wayland compositors that do not advertise cursor-shape-v1. Wayland uses fractional-scale-v1 only when viewporter is also present; otherwise framebuffer metrics follow integer wl_output scale. Backends must leave unsupported classes false instead of emulating partial support. Current native backends route window-scoped mouse, keyboard, focus, resize and iconified/restored events where the platform implementation supports them. drop_events is true on native backends that clone dropped file paths into WindowInputEvent.dropped_files; touch_events is true only where native touch input is wired. Win32 reports the WM_TOUCH began/moved/ended states; AppKit also reports cancelled touches from touchesCancelledWithEvent:. Clipboard paste is reported as an event signal; clipboard contents are not carried by WindowInputEvent. X11 text uses XIM/XIC with Xutf8LookupString. X11 file drops accept inline or bounded 1 MiB ICCCM INCR XDND text/uri-list transfers, refresh their timeout only on progress, never publish a partial drop, and safely finish even if the source window disappears. Wayland text uses xkb keymap/state for key-press characters, and Wayland file drops use wl_data_device/wl_data_offer text/uri-list. A drop exactly at the byte limit is accepted only after EOF confirms that no extra byte remains; neither Linux text path implements full IME/composed text yet.

Window Services and Native Borrows

Services are capability-first. Query window_operation_capability(window, operation) on the running app immediately before an optional call. The runtime answer is authoritative: .conditional can still require compositor support, window configuration, or a recent user action. .asynchronous means the call is not synchronously authoritative; it does not promise a later queued result. Check .state_observable before waiting for a state observation. Wayland minimize is asynchronous with state_observable == false, so no resulting minimized-state observation is guaranteed. Use window_state() for the latest observed state and monitor_ids() plus monitor_info() for generation-checked monitor snapshots. Full observations can authoritatively clear membership; partial state observations preserve the last known ids. Monitor names are descriptive, not stable identities. X11 root work-area/current-desktop changes refresh the complete monitor projection while failed refreshes preserve the last snapshot. Win32 keeps the app-level monitor projection current even while the app has no managed windows and refreshes it before the next first window. Window membership observations contain only ids in the currently available public monitor snapshot; staged native monitor and metrics updates become visible together.

Clipboard reads and writes return ClipboardRequestId; match it with the terminal .clipboard WindowServiceEvent. Portal export returns PortalParentRequestId; a ready event contains both an opaque identifier and a PortalParentLeaseId. Keep the lease alive for the external consumer and call release_portal_parent() explicitly afterward. Native X11 identifiers start with x11: and Wayland xdg-foreign-v2 identifiers start with wayland:. Treat everything after the prefix as opaque. Wayland clipboard uses the seat data device, writes require a recent input serial, and portal export requires xdg-foreign-v2. If preparing a replacement Wayland clipboard source fails before selection submission, the previously published clipboard value remains unchanged. A compositor clipboard send already accepted by Wayland uses its own bounded text snapshot and can finish after replacement or source cancellation. Each active X11 clipboard read has an isolated native conversion requestor, so late inline, failure, or INCR replies cannot complete a later request; failure to start a queued conversion is delivered as its terminal failure. Replies to external X11 requestors, including INCR chunks, use a checked connection so an expired requestor fails that transfer without affecting later clipboard work. For X11 INCR reads, the advertised length is a lower bound; actual growth is accepted only within the per-request and aggregate clipboard byte limits. Queued clipboard terminal payloads share a 16 MiB, 64-operation bound across backends and remain charged until their service events are delivered or discarded.

with_native_window() is callback-only. Inside its callback, invoke exactly the accessor matching app.capabilities().backend:

• with_win32: HWND;
• with_appkit: NSWindow pointer;
• with_x11: Display pointer and X11 Window;
• with_wayland: wl_display and wl_surface pointers.

NativeWindowLease expires when the outer with_native_window() callback returns. A backend handle expires sooner, when its nested lease.with_* callback returns. Never store, return, or use either authority after its own callback lifetime.

Window and managed-image readbacks are asynchronous. WindowReadbackConfig{} captures the full target; rect requests a positive, fully contained region in framebuffer coordinates. Every request admits and enqueues one terminal result as .ready, .cancelled, or .failed, but a callback failure can replay that same queued result until acknowledgment; handlers must be idempotent. Ready results own top-left RGBA8 bytes, an explicit stride, dimensions, and the producing submitted_frame; cancellation/failure does not carry pixels. Pending and queued readbacks share a 256 MiB, 64-operation bound. A producer reserves its tight RGBA8 size before allocation or capture, and that storage remains charged until the terminal event is delivered or discarded. Pending requests are cancelled during window/app teardown. app.capabilities().readback is only the backend-wide availability summary for the current renderer (Mock has its deterministic window path; AppKit requires a ready Metal renderer). window_readback_capabilities() reports per-window path availability. The request still validates app/window ownership, same-window image scope, single-sample 2D render-target eligibility, and rectangle bounds.

The compact end-to-end example is:

v -d gg_multiwindow run examples/gg/multiwindow_services.v

It gates operations on runtime capabilities, queries state and monitors, correlates clipboard/portal request ids, releases portal leases, uses a scoped native borrow, and requests readback only when available.

Runtime support differs by backend:

This table is orientation only. Always prefer the live per-window capability over backend-name assumptions. Relative mouse lock on Wayland, for example, requires both relative-pointer and pointer-constraints globals.

The multi-window event queue is separate from legacy gg.Context callbacks. Normal single-window applications keep using the existing event_fn, keydown_fn, move_fn, scroll_fn and related callbacks on gg.Context, and do not import or initialize x.multiwindow.

gg.App manages native windows through x.multiwindow. The lower-level x.multiwindow layer owns native lifetimes and the owner queue; gg.App owns sokol.gfx/sokol.sgl renderer state only after rendering is initialized. Create, run, stop and render from the owner thread. Background threads should schedule owner-side work with app.post() or app.try_post() and let the run loop drain it. A gg.App render owner cannot coexist with an active legacy gg.Context renderer owner in the same process, but the legacy gg.Context API remains available for normal single-window programs.

The public facade maps gg.App/WindowId, WindowEvent, WindowInputEvent, WindowServiceEvent, WindowReadbackResult, and WindowQueuedEvent to the corresponding x.multiwindow app/id, lifecycle, input, service, readback, and queued-envelope types. Likewise, window_state, monitor_ids, window_operation_capability, and drain_window_queued_events map to the lower-level service_* queries and drain_queued_events. Keep application code on the gg side unless it deliberately needs the low-level backend layer; opaque ids, leases, and native handles are not interchangeable across the facade.

Per-Window Render API

With -d gg_multiwindow, WindowConfig provides per-window clear color, redraw mode, sample count, and init/frame/cleanup callbacks. Callback contexts provide immutable metrics and target snapshots, bounded frame/pass authority, app- and window-scoped managed resource IDs, pass methods, and the recording subset of WindowSglContext. RunConfig also provides app-resource lifecycle callbacks for resources shared by multiple windows.

Multi-window render targets support exactly sample_count: 1. A different sample count is rejected when a renderer is required or active. With an X11 or Wayland GL renderer active, request_window_capture() reads the framebuffer owned by gg after drawing and publishes it only after the producing frame is submitted. request_image_readback() reads a managed single-sample 2D render target. Without an active X11 renderer, window capture falls back to the native XGetImage path; that path reflects the X server drawable and cannot guarantee frame-exact compositor presentation under XWayland. Neither path is desktop or compositor capture. Results are owned top-left RGBA8 values delivered through RunConfig.readback_fn and support bounded pixel regions. Query window_readback_capabilities() before either operation. AppKit exposes the same asynchronous contract when its Metal renderer and private pre-present hook are active; GLCore33 and rendererless AppKit builds report unsupported. Win32 readback remains unsupported in this tranche.

Managed IDs are scoped to their app and, where applicable, their window. Stale, foreign, or expired IDs and callback leases return errors instead of exposing raw gfx.Environment, gfx.Swapchain, native drawable, command-buffer, or present authority. Rendering uses owner-thread batches, backend-issued ready credits, late target acquisition, ordered finalization, and one global commit per submitted batch.

Renderer behavior is exercised in the dedicated X11, Wayland, AppKit, and Win32 CI lanes. Those lanes set VGG_MULTIWINDOW_RUNTIME_PROBES=1, VGG_MULTIWINDOW_RUNTIME_BACKEND, and V_MULTIWINDOW_PROBE_BACKEND; compile with the matching native flag; and run tests and probes through the process-tree watchdog. The checks cover multi-window submission, resource cleanup and replacement, stale leases, callback-driven teardown, recovery, and native fault paths. A normal legacy gg.Context import remains isolated from x.multiwindow and native multi-window backend dependencies. The implementation follows the V-vendored Sokol revision and matching pinned sokol_gfx.h and sokol_gl.h contracts.

Troubleshooting

A common problem, if you draw a lot of primitive elements in the same frame, is that there is a chance that your program can exceed the maximum allowed amount of vertices and commands, imposed by sokol. The symptom is that your frame will be suddenly black, after it becomes more complex. Sokol's default for vertices is 131072. Sokol's default for commands is 32768.

To solve that, you can try adding these lines at the top of your program: #flag -D_SGL_DEFAULT_MAX_VERTICES=4194304 #flag -D_SGL_DEFAULT_MAX_COMMANDS=65536 You can see an example of that in: https://github.com/vlang/v/blob/master/examples/gg/many_thousands_of_circles_overriding_max_vertices.v

Another approach is to use several draw passes, and limit the amount of draw calls that you make in each, demonstrated in: https://github.com/vlang/v/blob/master/examples/gg/many_thousands_of_circles.v

Another approach to that problem, is to draw everything yourself in a streaming texture, then upload that streaming texture as a single draw command to the GPU. You can see an example of that done in: https://github.com/vlang/v/blob/master/examples/gg/random.v and in: https://github.com/vlang/v/blob/master/examples/gg/random_stars.v

A third approach, is to only upload your changing inputs to the GPU, and do all the calculations and drawing there in shaders.

fn capabilities_for_backend(backend MultiWindowBackend) !Capabilities

capabilities_for_backend reports capabilities for a backend policy.

fn capabilities_for_backend_with_renderer(backend MultiWindowBackend) !Capabilities

capabilities_for_backend_with_renderer reports capabilities while requiring renderer startup. Compile with -d gg_multiwindow to enable this API.

fn color_from_string(s string) Color

color_from_string returns a Color, corresponding to the given string or black Color if string is not found in lookup table, or a hex color if starting with #

fn create_default_pass(action gfx.PassAction) gfx.Pass

fn dpi_scale() f32

dpi_scale returns the DPI scale coefficient for the screen. Do not use for Android development, use Context.scale instead.

fn frgb[T](r T, g T, b T) Color

frgb builds a Color instance from the given floating point values (between 0.0 and 1.0) r, g, b

fn frgba[T](r T, g T, b T, a T) Color

frgba builds a Color instance from the given floating point values (between 0.0 and 1.0) r, g, b, a

fn hex(color u32) Color

hex takes in a 32 bit integer and splits it into 4 byte values

fn high_dpi() bool

high_dpi returns true if gg is running on a high DPI monitor or screen.

fn is_fullscreen() bool

is it fullscreen

fn new_app(config AppConfig) !&App

new_app creates a gg multi-window application.

fn new_context(cfg Config) &Context

new_context returns an initialized Context allocated on the heap.

fn rgb(r u8, g u8, b u8) Color

rgb builds a Color instance from the given r, g, b u8 values

fn rgba(r u8, g u8, b u8, a u8) Color

rgba builds a Color instance from the given r, g, b, a u8 values

fn screen_size() Size

screen_size returns the size of the active screen.

fn set_window_title(title string)

set_window_title sets main window's title

fn start(cfg Config)

start creates a new context and runs it right away. It is a convenient way to start short/throwaway gg based prototypes, that do not need to keep and update their own state, like simple animations/visualisations that depend only on the time, or the ctx.frame counter. Use gg.new_context() for more complex ones.

fn toggle_fullscreen()

toggle fullscreen

fn window_size() Size

window_size returns the Size of the active window. Do not use for Android development, use Context.window_size() instead.

fn window_size_real_pixels() Size

window_size_real_pixels returns the Size of the active window without scale

fn EndEnum.from[W](input W) !EndEnum

fn GfxRenderOwner.from[W](input W) !GfxRenderOwner

fn HorizontalAlign.from[W](input W) !HorizontalAlign

fn ImageEffect.from[W](input W) !ImageEffect

fn KeyCode.from[W](input W) !KeyCode

fn Modifier.from[W](input W) !Modifier

fn Modifier.zero() Modifier

fn MouseButton.from[W](input W) !MouseButton

fn MouseButtons.from[W](input W) !MouseButtons

fn MouseButtons.zero() MouseButtons

fn MultiWindowBackend.from[W](input W) !MultiWindowBackend

fn MultiWindowRenderPhase.from[W](input W) !MultiWindowRenderPhase

fn MultiWindowResourceOperation.from[W](input W) !MultiWindowResourceOperation

fn MultiWindowResourceScope.from[W](input W) !MultiWindowResourceScope

fn PaintStyle.from[W](input W) !PaintStyle

fn PenLineType.from[W](input W) !PenLineType

fn ScreenshotOutput.from[W](input W) !ScreenshotOutput

fn TextureFilter.from[W](input W) !TextureFilter

fn VerticalAlign.from[W](input W) !VerticalAlign

fn WindowCleanupReason.from[W](input W) !WindowCleanupReason

fn WindowCursorShape.from[W](input W) !WindowCursorShape

fn WindowEventKind.from[W](input W) !WindowEventKind

fn WindowMappingState.from[W](input W) !WindowMappingState

fn WindowObservedBool.from[W](input W) !WindowObservedBool

fn WindowOperation.from[W](input W) !WindowOperation

fn WindowQueuedEventKind.from[W](input W) !WindowQueuedEventKind

fn WindowReadbackStatus.from[W](input W) !WindowReadbackStatus

fn WindowRedrawMode.from[W](input W) !WindowRedrawMode

fn WindowResizeEdge.from[W](input W) !WindowResizeEdge

fn WindowServiceEventKind.from[W](input W) !WindowServiceEventKind

fn WindowServiceStatus.from[W](input W) !WindowServiceStatus

fn WindowSupportLevel.from[W](input W) !WindowSupportLevel

fn WindowTitlebarAppearance.from[W](input W) !WindowTitlebarAppearance

fn WindowVisibilityState.from[W](input W) !WindowVisibilityState

type AppEventFn = fn (event WindowEvent, mut app App) !

AppEventFn is called by App.run() for each drained multi-window event.

type AppFrameFn = fn (mut app App) !

AppFrameFn is a render-frame callback and requires a render-capable backend with explicit swapchains.

type AppInputFn = fn (event WindowInputEvent, mut app App) !

AppInputFn is called by App.run() for each drained multi-window input event.

type AppJobFn = fn (mut app App) !

AppJobFn is executed later by app.drain_pending() on the owner side.

type AppKitNativeWindowFn = fn (ns_window voidptr) !

AppKitNativeWindowFn receives a borrowed NSWindow pointer valid only for the callback.

type AppResourceCleanupFn = fn (mut AppResourceContext) !

AppResourceCleanupFn releases app-scoped managed resources.

type AppResourceContext = WindowResourceContext

AppResourceContext uses the same managed resource operations with app scope.

type AppResourceFrameFn = fn (mut AppResourceContext) !

AppResourceFrameFn updates app-scoped managed resources during a batch.

type AppResourceInitFn = fn (mut AppResourceContext) !

AppResourceInitFn initializes app-scoped managed resources.

type FNCb = fn (data voidptr)

type FNChar = fn (c u32, data voidptr)

FNChar defines the type of a function that will be called once per character

type FNClick = fn (x f32, y f32, button MouseButton, data voidptr)

FNClick defines the type of a function that will be called for every mouse click

type FNEvent = fn (e &Event, data voidptr)

FNEvent defines the type of a function that will be called for every event

type FNEvent2 = fn (data voidptr, e &Event)

FNEvent2 same as FNEvent with inverted arguments TODO: deprecate this, in favor of event_fn

type FNFail = fn (msg string, data voidptr)

FNFail defines the type of a function that will be called when there is a fail

type FNKeyDown = fn (c KeyCode, m Modifier, data voidptr)

FNKeyDown defines the type of a function that will be called for every key pressed down

type FNKeyUp = fn (c KeyCode, m Modifier, data voidptr)

FNKeyUp defines the type of a function that will be called for every release of a pressed key

type FNMove = fn (x f32, y f32, data voidptr)

FNMove defines the type of a function that will be called for every mouse move on the screen

type FNUnClick = fn (x f32, y f32, button MouseButton, data voidptr)

FNUnClick defines the type of a function that will be called every time a mouse button is released

type FNUpdate = fn (dt f32, data voidptr)

FNUpdate defines the type of a function, that will be called at the start of each frame with an argument dt, that has the passed time in seconds, since the previous update.

type NativeWindowBorrowFn = fn (mut NativeWindowLease) !

NativeWindowBorrowFn receives a native lease that expires with the callback.

type TouchPoint = C.sapp_touchpoint

type WaylandNativeWindowFn = fn (display voidptr, surface voidptr) !

WaylandNativeWindowFn receives borrowed wl_display and wl_surface pointers valid only for the callback.

type Win32NativeWindowFn = fn (hwnd voidptr) !

Win32NativeWindowFn receives a borrowed HWND valid only for the callback.

type WindowCleanupFn = fn (mut WindowCleanupContext) !

WindowCleanupFn releases window-scoped resources during terminal cleanup.

type WindowDrawFn = fn (mut window WindowContext) !

WindowDrawFn records drawing commands for one WindowContext.

type WindowFrameFn = fn (mut WindowContext) !

WindowFrameFn records one managed window frame.

type WindowInitFn = fn (mut WindowInitContext) !

WindowInitFn initializes window-scoped managed resources.

type WindowPassFn = fn (mut WindowPassContext) !

WindowPassFn records commands in one callback-bounded managed pass.

type WindowReadbackFn = fn (WindowReadbackResult, mut App) !

WindowReadbackFn receives ordered terminal readback results from App.run.

type WindowResourceFn = fn (mut WindowResourceContext) !

WindowResourceFn receives callback-bounded managed resource authority.

type WindowServiceFn = fn (event WindowServiceEvent, mut app App) !

WindowServiceFn is called by App.run for ordered native service events.

type WindowSglFn = fn (mut WindowSglContext) !

WindowSglFn records SGL commands in one callback-bounded managed pass.

type X11NativeWindowFn = fn (display voidptr, window u64) !

X11NativeWindowFn receives borrowed Display and Window handles valid only for the callback.

enum EndEnum {
	clear
	passthru
}

enum HorizontalAlign {
	left   = C.FONS_ALIGN_LEFT
	center = C.FONS_ALIGN_CENTER
	right  = C.FONS_ALIGN_RIGHT
}

enum ImageEffect {
	// TODO(FireRedz): Add more effects
	alpha
	add
}

enum KeyCode {
	invalid       = 0
	space         = 32
	apostrophe    = 39 //'
	comma         = 44 //,
	minus         = 45 //-
	period        = 46 //.
	slash         = 47 ///
	_0            = 48
	_1            = 49
	_2            = 50
	_3            = 51
	_4            = 52
	_5            = 53
	_6            = 54
	_7            = 55
	_8            = 56
	_9            = 57
	semicolon     = 59 //;
	equal         = 61 //=
	a             = 65
	b             = 66
	c             = 67
	d             = 68
	e             = 69
	f             = 70
	g             = 71
	h             = 72
	i             = 73
	j             = 74
	k             = 75
	l             = 76
	m             = 77
	n             = 78
	o             = 79
	p             = 80
	q             = 81
	r             = 82
	s             = 83
	t             = 84
	u             = 85
	v             = 86
	w             = 87
	x             = 88
	y             = 89
	z             = 90
	left_bracket  = 91  //[
	backslash     = 92  //\
	right_bracket = 93  //]
	grave_accent  = 96  //`
	world_1       = 161 // non-us #1
	world_2       = 162 // non-us #2
	escape        = 256
	enter         = 257
	tab           = 258
	backspace     = 259
	insert        = 260
	delete        = 261
	right         = 262
	left          = 263
	down          = 264
	up            = 265
	page_up       = 266
	page_down     = 267
	home          = 268
	end           = 269
	caps_lock     = 280
	scroll_lock   = 281
	num_lock      = 282
	print_screen  = 283
	pause         = 284
	f1            = 290
	f2            = 291
	f3            = 292
	f4            = 293
	f5            = 294
	f6            = 295
	f7            = 296
	f8            = 297
	f9            = 298
	f10           = 299
	f11           = 300
	f12           = 301
	f13           = 302
	f14           = 303
	f15           = 304
	f16           = 305
	f17           = 306
	f18           = 307
	f19           = 308
	f20           = 309
	f21           = 310
	f22           = 311
	f23           = 312
	f24           = 313
	f25           = 314
	kp_0          = 320
	kp_1          = 321
	kp_2          = 322
	kp_3          = 323
	kp_4          = 324
	kp_5          = 325
	kp_6          = 326
	kp_7          = 327
	kp_8          = 328
	kp_9          = 329
	kp_decimal    = 330
	kp_divide     = 331
	kp_multiply   = 332
	kp_subtract   = 333
	kp_add        = 334
	kp_enter      = 335
	kp_equal      = 336
	left_shift    = 340
	left_control  = 341
	left_alt      = 342
	left_super    = 343
	right_shift   = 344
	right_control = 345
	right_alt     = 346
	right_super   = 347
	menu          = 348
}

enum Modifier {
	shift // (1<<0)
	ctrl  // (1<<1)
	alt   // (1<<2)
	super // (1<<3)
}

fn (e &Modifier) all(flag_ Modifier) bool

fn (mut e Modifier) clear(flag_ Modifier)

fn (mut e Modifier) clear_all()

fn (e &Modifier) has(flag_ Modifier) bool

fn (e &Modifier) is_empty() bool

fn (mut e Modifier) set(flag_ Modifier)

fn (mut e Modifier) set_all()

fn (mut e Modifier) toggle(flag_ Modifier)

enum MouseButton {
	left    = 0
	right   = 1
	middle  = 2
	invalid = 256
}

enum MouseButtons {
	left
	right
	middle
}

Note: unlike the MouseButton enum from above,the [flag]-ed enum here can have combined states, representing several pressed buttons at once.

fn (e &MouseButtons) all(flag_ MouseButtons) bool

fn (mut e MouseButtons) clear(flag_ MouseButtons)

fn (mut e MouseButtons) clear_all()

fn (e &MouseButtons) has(flag_ MouseButtons) bool

fn (e &MouseButtons) is_empty() bool

fn (mut e MouseButtons) set(flag_ MouseButtons)

fn (mut e MouseButtons) set_all()

fn (mut e MouseButtons) toggle(flag_ MouseButtons)

enum MultiWindowBackend {
	auto
	mock
	x11
	wayland
	appkit
	win32
}

MultiWindowBackend selects the implementation behind gg.App.

enum PaintStyle {
	fill
	stroke
}

enum PenLineType {
	solid
	dashed
	dotted
}

enum TextureFilter {
	linear
	nearest
}

TextureFilter controls how gg samples textures when images are scaled.

enum VerticalAlign {
	top      = C.FONS_ALIGN_TOP
	middle   = C.FONS_ALIGN_MIDDLE
	bottom   = C.FONS_ALIGN_BOTTOM
	baseline = C.FONS_ALIGN_BASELINE
}

enum WindowCleanupReason {
	requested
	native_closed
	init_failed
	app_stop
	renderer_lost
}

WindowCleanupReason identifies why a window render lifetime is ending.

enum WindowCursorShape {
	default
	pointer
	move
	n_resize
	s_resize
	e_resize
	w_resize
	ne_resize
	nw_resize
	se_resize
	sw_resize
	ew_resize
	ns_resize
	nesw_resize
	nwse_resize
	grab
	grabbing
	text
	crosshair
	not_allowed
	resize_all
}

WindowCursorShape identifies a native cursor image for hover feedback.

enum WindowEventKind {
	window_created
	window_destroyed
	window_close_requested
	window_resized
}

WindowEventKind describes lifecycle events routed to a specific window.

enum WindowMappingState {
	unknown
	unmapped
	mapped
}

WindowMappingState reports whether a native window is attached to the platform's visible window hierarchy.

enum WindowObservedBool {
	unknown
	off
	on
}

WindowObservedBool distinguishes an observed false value from unavailable native state.

enum WindowOperation {
	show
	hide
	focus
	raise
	position
	minimize
	maximize
	restore
	fullscreen
	clipboard_read
	clipboard_write
	portal_parent
	native_borrow
	mouse_lock
	titlebar_appearance
	image_readback
	window_capture
}

WindowOperation identifies a runtime native-window service.

enum WindowQueuedEventKind {
	lifecycle
	input
	service
	readback
}

WindowQueuedEventKind identifies one of the four canonical queue families.

enum WindowReadbackStatus {
	ready
	cancelled
	failed
}

WindowReadbackStatus is the terminal state of an asynchronous readback.

enum WindowRedrawMode {
	on_demand
	continuous
}

WindowRedrawMode controls when a window is eligible for a render frame.

enum WindowResizeEdge {
	top
	bottom
	left
	right
	top_left
	top_right
	bottom_left
	bottom_right
}

WindowResizeEdge identifies the edge or corner used for an interactive, user-driven native resize operation.

enum WindowServiceEventKind {
	state
	metrics
	capability
	monitor
	clipboard
	portal_parent
}

WindowServiceEventKind selects the payload carried by WindowServiceEvent.

enum WindowServiceStatus {
	ready
	cancelled
	failed
}

WindowServiceStatus is the terminal status of an asynchronous service request.

enum WindowSupportLevel {
	unsupported
	available
	conditional
}

WindowSupportLevel reports whether a native operation is usable for one live window on the selected backend.

enum WindowTitlebarAppearance {
	system
	light
	dark
}

WindowTitlebarAppearance requests the platform default or a light/dark native titlebar where the backend exposes such an operation.

enum WindowVisibilityState {
	unknown
	hidden
	visible
	occluded
}

WindowVisibilityState is the latest native visibility observation.

struct App {
pub:
	config AppConfig
}

App is the additive multi-window facade for gg users.

Compile with -d gg_multiwindow to enable this API.

fn (mut app App) begin_window_move(id WindowId) !

begin_window_move starts a user-driven native move for a live window.

fn (mut app App) begin_window_resize(id WindowId, edge WindowResizeEdge) !

begin_window_resize starts a user-driven native resize for a live resizable window.

fn (app &App) capabilities() Capabilities

capabilities reports the active app backend contract.

fn (mut app App) create_window(config WindowConfig) !WindowId

create_window creates a window managed by this app.

fn (mut app App) destroy_window(id WindowId) !

destroy_window destroys a live window and its owned descendants child-first. Destroying the final window does not stop the app; call stop explicitly.

fn (mut app App) drain_events() ![]WindowEvent

drain_events consumes only the contiguous lifecycle prefix of the ordered queue.

fn (mut app App) drain_input_events() ![]WindowInputEvent

drain_input_events consumes only the contiguous input prefix of the ordered queue.

fn (mut app App) drain_pending(max_jobs int) !int

drain_pending executes up to max_jobs queued owner-side callbacks.

fn (mut app App) drain_window_queued_events() ![]WindowQueuedEvent

drain_window_queued_events consumes lifecycle, input, service, and readback events in exact global admission order.

fn (mut app App) drain_window_service_events() ![]WindowServiceEvent

drain_window_service_events consumes only the contiguous service prefix of the ordered queue. It never skips lifecycle, input, or readback events.

fn (mut app App) draw_window(id WindowId, draw WindowDrawFn) !

draw_window renders one live window through its WindowContext.

fn (mut app App) hide_window(id WindowId) !

hide_window requests that a live window become hidden or unmapped.

fn (mut app App) maximize_window(id WindowId) !

maximize_window requests native maximization.

fn (mut app App) minimize_window(id WindowId) !

minimize_window requests native minimization.

fn (app &App) monitor_ids() ![]WindowMonitorId

monitor_ids returns generation-checked ids for currently available monitors.

fn (app &App) monitor_info(id WindowMonitorId) !WindowMonitorInfo

monitor_info returns the latest snapshot for a monitor generation. Names are descriptive; the generation-checked id is the identity.

fn (mut app App) poll_events() !int

poll_events routes native lifecycle, input, service, and readback events into the gg.App canonical queue.

fn (mut app App) post(f AppJobFn) !

post submits a short callback to be executed when owner-side work is drained.

fn (mut app App) raise_window(id WindowId) !

raise_window asks the platform to raise a live window.

fn (mut app App) release_portal_parent(id PortalParentLeaseId) !

release_portal_parent releases a ready portal-parent export lease.

fn (mut app App) request_clipboard_text(id WindowId) !ClipboardRequestId

request_clipboard_text starts an asynchronous clipboard read. Match the id with a terminal clipboard WindowServiceEvent.

fn (mut app App) request_portal_parent(id WindowId) !PortalParentRequestId

request_portal_parent starts an asynchronous native-parent export. A ready event owns a lease that must be released explicitly.

fn (mut app App) request_redraw(id WindowId) !

request_redraw makes a window eligible for a future on-demand frame.

fn (mut app App) request_window_capture(id WindowId, config WindowReadbackConfig) !WindowReadbackId

request_window_capture queues an asynchronous full-target or bounded-region capture. The terminal result is delivered by RunConfig.readback_fn or the canonical window queue; gg has no separate readback drain.

fn (mut app App) request_window_focus(id WindowId) !

request_window_focus asks the platform to focus a live window.

fn (mut app App) resize_window(id WindowId, width int, height int) !

resize_window requests a live window resize.

fn (mut app App) restore_window(id WindowId) !

restore_window leaves the supported minimized, maximized, or fullscreen state.

fn (mut app App) run(config RunConfig) !

run starts the owner loop and dispatches lifecycle, input, service, and readback callbacks in canonical order. Rendering callbacks require swapchains. A queue-callback error reinserts the current event and untouched suffix, so event, input, service, and readback handlers must be idempotent.

fn (mut app App) set_clipboard_text(id WindowId, text string) !ClipboardRequestId

set_clipboard_text starts an asynchronous clipboard write. Match the id with a terminal clipboard WindowServiceEvent.

fn (mut app App) set_window_clear_color(id WindowId, color Color) !

set_window_clear_color updates the clear color used for the window's managed swapchain pass.

fn (mut app App) set_window_cursor(id WindowId, shape WindowCursorShape) !

set_window_cursor updates the native hover cursor for a live window.

fn (mut app App) set_window_fullscreen(id WindowId, enabled bool) !

set_window_fullscreen requests or leaves native fullscreen state.

fn (mut app App) set_window_mouse_lock(id WindowId, enabled bool) !

set_window_mouse_lock requests or releases relative pointer confinement.

fn (mut app App) set_window_position(id WindowId, x int, y int) !

set_window_position requests a native top-level position when supported.

fn (mut app App) set_window_title(id WindowId, title string) !

set_window_title updates a live window title.

fn (mut app App) set_window_titlebar_appearance(id WindowId, appearance WindowTitlebarAppearance) !

set_window_titlebar_appearance requests a supported native titlebar theme.

fn (mut app App) show_window(id WindowId) !

show_window requests that a live window become mapped and visible.

fn (mut app App) stop() !

stop shuts down the app and destroys live windows.

fn (app &App) supports_window_cursor(id WindowId, shape WindowCursorShape) !WindowSupportLevel

supports_window_cursor reports support for one native cursor shape.

fn (mut app App) try_post(f AppJobFn) !

try_post submits a short callback without waiting for queue capacity.

fn (app &App) window_exists(id WindowId) bool

window_exists reports whether id still refers to a live window.

fn (app &App) window_ids() ![]WindowId

window_ids returns live window ids in stable app order.

fn (app &App) window_info(id WindowId) !WindowInfo

window_info returns a snapshot of a live window.

fn (app &App) window_infos() ![]WindowInfo

window_infos returns live window snapshots in stable app order.

fn (app &App) window_metrics(id WindowId) !WindowMetrics

window_metrics returns the latest committed logical and framebuffer metrics for a window.

fn (app &App) window_operation_capability(id WindowId, operation WindowOperation) !WindowOperationCapability

window_operation_capability reports authoritative runtime support for one operation on one live window. Query it immediately before optional operations.

fn (app &App) window_readback_capabilities(id WindowId) !WindowReadbackCapabilities

window_readback_capabilities reports current path availability for one live window. Requests still validate ownership, same-window image scope, single-sample render-target eligibility, and rectangle bounds.

fn (app &App) window_render_target_info(id WindowId) !WindowRenderTargetInfo

window_render_target_info returns the current color, depth, and sampling contract for a window.

fn (app &App) window_state(id WindowId) !WindowState

window_state returns the latest native state observed for a live window. Unknown fields were not reported by the running backend.

fn (mut app App) with_native_window(id WindowId, f NativeWindowBorrowFn) !

with_native_window borrows a live native window only for the callback. The lease and nested backend handles must not escape or be retained.

struct AppConfig {
pub:
	backend          MultiWindowBackend = .auto
	queue_size       int                = 128
	require_renderer bool
	app_id           string
}

AppConfig configures a multi-window gg application facade. app_id supplies the native application identity where supported (currently Wayland xdg-shell).

struct Capabilities {
pub:
	backend                 MultiWindowBackend
	mock                    bool
	native                  bool
	multi_window            bool
	owner_queue             bool
	explicit_swapchain      bool
	readback                bool
	d3d11                   bool
	metal                   bool
	x11                     bool
	wayland                 bool
	win32                   bool
	gl                      bool
	input_events            bool
	mouse_events            bool
	keyboard_events         bool
	text_events             bool
	focus_events            bool
	drop_events             bool
	touch_events            bool
	cursor_shapes           bool
	interactive_move_resize bool
	native_decorations      bool
}

Capabilities reports the active gg.App backend-wide contract. Optional per-window service/readback queries remain authoritative for runtime state.

struct ClipboardRequestId {
	app_instance u64
	serial       u64
}

ClipboardRequestId identifies one accepted asynchronous clipboard request.

fn (id ClipboardRequestId) str() string

str returns a diagnostic clipboard request identity.

struct ClipboardResult {
pub:
	id     ClipboardRequestId
	window WindowId
	status WindowServiceStatus
	text   string
	error  string
}

ClipboardResult is the terminal result matched to ClipboardRequestId.

struct Color {
pub mut:
	r u8
	g u8
	b u8
	a u8 = 255
}

Color represents a 32 bit color value in sRGB format

fn (a Color) + (b Color) Color

• adds b to a, with a maximum value of 255 for each channel

fn (a Color) - (b Color) Color

• subtracts b from a, with a minimum value of 0 for each channel the alpha channel will be set as the minimum between a.a and b.a

fn (c Color) * (c2 Color) Color

• multiplies Color c and c2 keeping channel values in [0, 255] range

fn (c Color) / (c2 Color) Color

/ divides c by c2 and converts each channel's value to u8(int)

fn (a Color) over(b Color) Color

over implements an a over b operation. see https://keithp.com/~keithp/porterduff/p253-porter.pdf

fn (c Color) eq(c2 Color) bool

eq checks if color c and c2 are equal in every channel

fn (c Color) str() string

str returns a string representation of the Color c

fn (c Color) rgba8() i32

rgba8 converts a color value to an 32bit int in the RGBA8 order. see https://developer.apple.com/documentation/coreimage/ciformat

fn (c Color) bgra8() i32

bgra8 converts a color value to an 32bit int in the BGRA8 order. see https://developer.apple.com/documentation/coreimage/ciformat

fn (c Color) abgr8() i32

abgr8 converts a color value to an 32bit int in the ABGR8 order. see https://developer.apple.com/documentation/coreimage/ciformat

fn (c Color) to_css_string() string

to_css_string returns a CSS compatible string e.g. rgba(10,11,12,13) of the color c.

struct Config {
pub:
	width         int = 800 // desired start width of the window
	height        int = 600 // desired start height of the window
	retina        bool // TODO: implement or deprecate
	resizable     bool = true // prevent user-initiated resizing when supported by the platform backend
	user_data     voidptr // a custom pointer to the application data/instance. When it is not set explicitly, it will default to a pointer to the current gg.Context instance.
	font_size     int     // TODO: implement or deprecate
	create_window bool    // TODO: implement or deprecate
	// window_user_ptr voidptr
	window_title      string = 'A GG Window. Set window_title: to change it.' // the desired title of the window
	icon              sapp.IconDesc
	html5_canvas_name string = 'canvas'
	borderless_window bool  // create the window without native decorations when supported by the platform backend
	always_on_top     bool  // TODO: implement or deprecate
	bg_color          Color // The background color of the window. By default, the first thing gg does in ctx.begin(), is clear the whole buffer with that color.
	init_fn           FNCb   = unsafe { nil } // Called once, after Sokol has finished its setup. Some gg and Sokol functions have to be called *in this* callback, or after this callback, but not before
	frame_fn          FNCb   = unsafe { nil } // Called once per frame, usually 60 times a second (depends on swap_interval). See also https://dri.freedesktop.org/wiki/ConfigurationOptions/#synchronizationwithverticalrefreshswapintervals
	native_frame_fn   FNCb   = unsafe { nil }
	cleanup_fn        FNCb   = unsafe { nil } // Called once, after Sokol determines that the application is finished/closed. Put your app specific cleanup/free actions here.
	fail_fn           FNFail = unsafe { nil } // Called once per Sokol error/log message. TODO: currently it does nothing with latest Sokol, reimplement using Sokol's new sapp_logger APIs.

	update_fn FNUpdate = unsafe { nil } // Called once at the start of each frame, so usually ~60 times a second. The first argument is the delta `dt` time passed, since the *previous* update call (in seconds).

	event_fn FNEvent  = unsafe { nil } // Called once per each user initiated event, received by Sokol/GG.
	on_event FNEvent2 = unsafe { nil } // Called once per each user initiated event, received by Sokol/GG. Same as event_fn, just the parameter order is different. TODO: deprecate this, in favor of event_fn
	quit_fn  FNEvent  = unsafe { nil } // Called when the user closes the app window.

	keydown_fn FNKeyDown = unsafe { nil } // Called once per key press, no matter how long the key is held down. Note that here you can access the scan code/physical key, but not the logical character.
	keyup_fn   FNKeyUp   = unsafe { nil } // Called once per key press, when the key is released.
	char_fn    FNChar    = unsafe { nil } // Called once per character (after the key is pressed down, and then released). Note that you can access the character/utf8 rune here, not just the scan code.

	move_fn    FNMove    = unsafe { nil } // Called while the mouse/touch point is moving.
	click_fn   FNClick   = unsafe { nil } // Called once when the mouse/touch button is clicked.
	unclick_fn FNUnClick = unsafe { nil } // Called once when the mouse/touch button is released.
	leave_fn   FNEvent   = unsafe { nil } // Called once when the mouse/touch point leaves the window.
	enter_fn   FNEvent   = unsafe { nil } // Called once when the mouse/touch point enters again the window.
	resized_fn FNEvent   = unsafe { nil } // Called once when the window has changed its size.
	scroll_fn  FNEvent   = unsafe { nil } // Called while the user is scrolling. The direction of scrolling is indicated by either 1 or -1.
	// wait_events       bool // set this to true for UIs, to save power
	fullscreen     bool // set this to true, if you want your window to start in fullscreen mode (suitable for games/demos/screensavers)
	scale          f32 = 1.0
	sample_count   int // bigger values usually have performance impact, but can produce smoother/antialiased lines, if you draw lines or polygons (2 is usually good enough)
	texture_filter TextureFilter = .linear // default texture filter for newly created images; use `.nearest` for pixel art scaling
	swap_interval  int           = 1       // 1 = 60fps, 2 = 30fps etc. Honored on Windows, macOS, Linux, iOS, and HTML5; Android support is not implemented yet.
	// ved needs this
	// init_text bool
	font_path             string
	custom_bold_font_path string
	ui_mode               bool // refreshes only on events to save CPU usage
	// font bytes for embedding
	font_bytes_normal []u8
	font_bytes_bold   []u8
	font_bytes_mono   []u8
	font_bytes_italic []u8
	native_rendering  bool // Cocoa on macOS/iOS, GDI+ on Windows
	// drag&drop
	enable_dragndrop             bool // enable file dropping (drag'n'drop), default is false
	max_dropped_files            int = 1    // max number of dropped files to process (default: 1)
	max_dropped_file_path_length int = 2048 // max length in bytes of a dropped UTF-8 file path (default: 2048)

	min_width  int // desired minimum width of the window
	min_height int // desired minimum height of the window
}

struct Context {
mut:
	render_text bool = true
	// a cache with all images created by the user. used for sokol image init and to save space
	// (so that the user can store image ids, not entire Image objects)
	image_cache                 []Image
	needs_refresh               bool = true
	ticks                       int // for ui mode only
	last_bg_overlay_frame       u64
	translucent_bg_seed_pending bool
pub:
	native_rendering bool
pub mut:
	scale       f32 = 1.0 // will get set to 2.0 for retina, will remain 1.0 for normal
	width       int
	height      int
	clear_pass  gfx.PassAction
	bg_color    Color
	window      sapp.Desc
	pipeline    &PipelineContainer = unsafe { nil }
	config      Config
	user_data   voidptr
	ft          &FT = unsafe { nil }
	font_inited bool
	ui_mode     bool // do not redraw everything 60 times/second, but only when the user requests
	frame       u64  // the current frame counted from the start of the application; always increasing
	//
	timer        time.StopWatch // starts right after new_context, and can be controlled/stopped/restarted in whatever way the user wants.
	update_timer time.StopWatch // measures how much time has passed since the start of the frame.
	frame_timer  time.StopWatch // enforces swap_interval as a fallback when the platform ignores vsync.
	// Note: when there is an update_fn, this timer is reset by GG itself, at the start of each frame.

	mbtn_mask     u8
	mouse_buttons MouseButtons // typed version of mbtn_mask; easier to use for user programs
	mouse_pos_x   int
	mouse_pos_y   int
	mouse_dx      int
	mouse_dy      int
	scroll_x      int
	scroll_y      int

	key_modifiers     Modifier           // the current key modifiers
	key_repeat        bool               // whether the pressed key was an autorepeated one
	pressed_keys      [key_code_max]bool // an array representing all currently pressed keys
	pressed_keys_edge [key_code_max]bool // true when the previous state of pressed_keys,
	// *before* the current event was different
	fps         FPSConfig
	has_started bool
}

fn (ctx &Context) begin()

begin prepares the context for drawing.

fn (mut ctx Context) cache_image(img Image) int

cache_image caches the image img in memory for later reuse. cache_image returns the cache index of the cached image.

See also: get_cached_image_by_idx See also: remove_cached_image_by_idx

fn (mut ctx Context) create_image(file string, cfg ImageConfig) !Image

create_image creates an Image from file.

fn (mut ctx Context) create_image_from_byte_array(b []u8, cfg ImageConfig) !Image

create_image_from_byte_array creates an Image from the byte array b.

See also: create_image_from_memory

fn (mut ctx Context) create_image_from_byte_array_with_filter(b []u8, texture_filter TextureFilter) !Image

create_image_from_byte_array_with_filter creates an Image from b with the requested texture filter.

fn (mut ctx Context) create_image_from_memory(buf &u8, bufsize int, cfg ImageConfig) !Image

create_image_from_memory creates an Image from the memory buffer buf of size bufsize.

See also: create_image_from_byte_array

fn (mut ctx Context) create_image_from_memory_with_filter(buf &u8, bufsize int, texture_filter TextureFilter) !Image

create_image_from_memory_with_filter creates an Image from buf with the requested texture filter.

fn (mut ctx Context) create_image_with_filter(file string, texture_filter TextureFilter) !Image

create_image_with_filter creates an Image from file with the requested texture filter.

fn (mut ctx Context) create_image_with_size(file string, width int, height int) Image

create_image_with_size creates an Image from file in the given width x height dimension.

Todo: copypasta

fn (ctx &Context) draw_arc_empty(x f32, y f32, inner_radius f32, thickness f32, start_angle f32, end_angle f32,
	segments int, c Color)

draw_arc_empty draws the outline of an arc. x,y defines the end point of the arc (center of the circle that the arc is part of). inner_radius defines the radius of the arc (length from the center point where the arc is drawn). thickness defines how wide the arc is drawn. start_angle is the angle in radians at which the arc starts. end_angle is the angle in radians at which the arc ends. segments affects how smooth/round the arc is. c is the color of the arc outline.

fn (ctx &Context) draw_arc_filled(x f32, y f32, inner_radius f32, thickness f32, start_angle f32, end_angle f32,
	segments int, c Color)

draw_arc_filled draws a filled arc. x,y defines the central point of the arc (center of the circle that the arc is part of). inner_radius defines the radius of the arc (length from the center point where the arc is drawn). thickness defines how wide the arc is drawn. start_angle is the angle in radians at which the arc starts. end_angle is the angle in radians at which the arc ends. segments affects how smooth/round the arc is. c is the fill color of the arc.

fn (ctx Context) draw_arc_line(x f32, y f32, radius f32, start_angle f32, end_angle f32, segments int,
	c Color)

draw_arc_line draws a line arc. x,y defines the end point of the arc (center of the circle that the arc is part of). radius defines the radius of the arc (length from the center point where the arc is drawn). start_angle is the angle in radians at which the arc starts. end_angle is the angle in radians at which the arc ends. segments affects how smooth/round the arc is. c is the color of the arc/outline.

fn (ctx &Context) draw_circle_empty(x f32, y f32, radius f32, c Color)

draw_circle_empty draws the outline of a circle. x,y defines the center of the circle. radius defines the radius of the circle. c is the color of the outline.

fn (ctx &Context) draw_circle_filled(x f32, y f32, radius f32, c Color)

draw_circle_filled draws a filled circle. x,y defines the center of the circle. radius defines the radius of the circle. c is the fill color.

fn (ctx &Context) draw_circle_line(x f32, y f32, radius int, segments int, c Color)

draw_circle_line draws the outline of a circle with a specific number of segments. x,y defines the center of the circle. radius defines the radius of the circle. segments affects how smooth/round the circle is. c is the color of the outline.

fn (ctx &Context) draw_circle_with_segments(x f32, y f32, radius f32, segments int, c Color)

draw_circle_with_segments draws a filled circle with a specific number of segments. x,y defines the center of the circle. radius defines the radius of the circle. segments affects how smooth/round the circle is. c is the fill color.

fn (ctx &Context) draw_convex_poly(points []f32, c Color)

draw_convex_poly draws a convex polygon, given an array of points, and a color. NOTE that the points must be given in clockwise winding order. The contents of the points array should be x and y coordinate pairs.

fn (ctx &Context) draw_cubic_bezier(points []f32, c Color)

draw_cubic_bezier draws a cubic Bézier curve, also known as a spline, from four points. The four points is provided as one points array which contains a stream of point pairs (x and y coordinates). Thus a cubic Bézier could be declared as: points := [x1, y1, control_x1, control_y1, control_x2, control_y2, x2, y2]. Please see draw_cubic_bezier_in_steps to control the amount of steps (segments) used to draw the curve.

fn (ctx &Context) draw_cubic_bezier_in_steps(points []f32, steps u32, c Color)

draw_cubic_bezier_in_steps draws a cubic Bézier curve, also known as a spline, from four points. The smoothness of the curve can be controlled with the steps parameter. steps determines how many iterations is taken to draw the curve. The four points is provided as one points array which contains a stream of point pairs (x and y coordinates). Thus a cubic Bézier could be declared as: points := [x1, y1, control_x1, control_y1, control_x2, control_y2, x2, y2].

fn (ctx &Context) draw_cubic_bezier_recursive(points []f32, c Color)

draw_cubic_bezier_recursive draws a cubic Bézier curve, also known as a spline, from four points, where the first and the last points, will be part of the curve, and the middle 2 points are control ones. Unlike draw_cubic_bezier_in_steps, this method does not use a fixed number of steps for the whole curve, but tries to produce more tesselation points dynamically for the curvier parts.

fn (ctx &Context) draw_cubic_bezier_recursive_scalar(x1 f32, y1 f32, x2 f32, y2 f32, x3 f32, y3 f32,
	x4 f32, y4 f32, c Color)

draw_cubic_bezier_recursive_scalar is the same as draw_cubic_bezier_recursive, except that the points are given as indiviual x,y f32 scalar parameters, and not in a single dynamic array parameter.

fn (ctx &Context) draw_ellipse_empty(x f32, y f32, rw f32, rh f32, c Color)

draw_ellipse_empty draws the outline of an ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. c is the color of the outline.

fn (ctx &Context) draw_ellipse_empty_rotate(x f32, y f32, rw f32, rh f32, rota f32, c Color)

draw_ellipse_empty_rotate draws the outline of an ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. rota defines the rotation angle of the ellipse, in radians. c is the color of the outline.

fn (ctx &Context) draw_ellipse_filled(x f32, y f32, rw f32, rh f32, c Color)

draw_ellipse_filled draws an opaque ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. c is the fill color.

fn (ctx &Context) draw_ellipse_filled_rotate(x f32, y f32, rw f32, rh f32, rota f32, c Color)

draw_ellipse_filled draws an opaque ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. rota defines the rotation angle of the ellipse, in radians. c is the fill color.

fn (ctx &Context) draw_ellipse_thick(x f32, y f32, rw f32, rh f32, th f32, c Color)

draw_ellipse_empty draws the outline of an ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. th defines the thickness of the ellipse. c is the color of the outline.

fn (ctx &Context) draw_ellipse_thick_rotate(x f32, y f32, rw f32, rh f32, th f32, rota f32, c Color)

draw_ellipse_empty draws the outline of an ellipse. x,y defines the center of the ellipse. rw defines the width radius of the ellipse. rh defines the height radius of the ellipse. th defines the thickness of the ellipse. rota defines the rotation angle of the ellipse, in radians. c is the color of the outline.

fn (ctx &Context) draw_image(x f32, y f32, width f32, height f32, img_ &Image)

draw_image draws the provided image onto the screen.

fn (ctx &Context) draw_image_3d(x f32, y f32, z f32, width f32, height f32, img_ &Image)

draw_image_3d draws an image with a z depth

fn (ctx &Context) draw_image_by_id(x f32, y f32, width f32, height f32, id int)

draw_image_by_id draws an image by its id

fn (ctx &Context) draw_image_flipped(x f32, y f32, width f32, height f32, img_ &Image)

draw_image_flipped draws the provided image flipped horizontally (use draw_image_with_config to flip vertically)

fn (ctx &Context) draw_image_part(img_rect Rect, part_rect Rect, img_ &Image)

Draw part of an image using uv coordinates img_rect is the size and position (in pixels on screen) of the displayed rectangle (ie the draw_image args) part_rect is the size and position (in absolute pixels in the image) of the wanted part eg. On a 600600 context, to display only the first 400400 pixels of a 2000*2000 image on the entire context surface, call : draw_image_part(Rect{0, 0, 600, 600}, Rect{0, 0, 400, 400}, img)

fn (ctx &Context) draw_image_with_config(config DrawImageConfig)

draw_image_with_config takes in a config that details how the provided image should be drawn onto the screen

fn (ctx &Context) draw_line(x f32, y f32, x2 f32, y2 f32, c Color)

draw_line draws a line between the points x,y and x2,y2 in color c.

fn (ctx &Context) draw_line_with_config(x f32, y f32, x2 f32, y2 f32, config PenConfig)

draw_line_with_config draws a line between the points x,y and x2,y2 using PenConfig.

fn (ctx &Context) draw_pixel(x f32, y f32, c Color, params DrawPixelConfig)

draw_pixel draws one pixel on the screen.

NOTE calling this function frequently is very inefficient, for drawing shapes it's recommended to draw whole primitives with functions like draw_rect_empty or draw_triangle_empty etc.

fn (ctx &Context) draw_pixels(points []f32, c Color, params DrawPixelConfig)

draw_pixels draws pixels from an array of points [x, y, x2, y2, etc...]

NOTE calling this function frequently is very inefficient, for drawing shapes it's recommended to draw whole primitives with functions like draw_rect_empty or draw_triangle_empty etc.

fn (ctx &Context) draw_poly_empty(points []f32, c Color)

draw_poly_empty draws the outline of a polygon, given an array of points, and a color. NOTE that the points must be given in clockwise winding order.

fn (ctx &Context) draw_polygon_filled(x f32, y f32, size f32, edges int, rotation f32, c Color)

draw_polygon_filled draws a filled polygon. x,y defines the center of the polygon. size defines the size of the polygon. edges defines number of edges in the polygon. rotation defines rotation of the polygon. c is the fill color.

fn (ctx &Context) draw_rect(p DrawRectParams)

fn (ctx &Context) draw_rect_empty(x f32, y f32, w f32, h f32, c Color)

draw_rect_empty draws the outline of a rectangle. x,y is the top-left corner of the rectangle. w is the width, h is the height and c is the color of the outline.

Note: it is much more efficient to draw lots of empty rectangles one after the other, without filled rectangles between them, than to draw a mix.

fn (ctx &Context) draw_rect_empty_no_context(x f32, y f32, w f32, h f32, c Color)

draw_rect_empty_no_context draws the outline of a rectangle, but without saving/restoring the context. It is intended to be used in loops, where you do manually: sgl.begin_lines() before the loop, then draw many rectangles, then call manually sgl.end() after the loop. x,y is the top-left corner of the rectangle. w is the width, h is the height and c is the color of the outline.

Note: it is much more efficient to draw lots of empty rectangles one after the other, without filled rectangles between them, than to draw a mix.

fn (ctx &Context) draw_rect_filled(x f32, y f32, w f32, h f32, c Color)

draw_rect_filled draws a filled rectangle. x,y is the top-left corner of the rectangle. w is the width, h is the height and c is the color of the fill.

Note: it is much more efficient to draw lots of filled rectangles one after the other, without empty rectangles between them, than to draw a mix.

fn (ctx &Context) draw_rect_filled_no_context(x f32, y f32, w f32, h f32, c Color)

draw_rect_filled_no_context draws a filled rectangle, but without saving/restoring the context. It is intended to be used in loops, where you do manually: sgl.begin_quads() before the loop, then draw many rectangles, then call manually sgl.end() after the loop. x,y is the top-left corner of the rectangle. w is the width, h is the height and c is the color of the fill.

Note: it is much more efficient to draw lots of filled rectangles one after the other, without empty rectangles between them, than to draw a mix.

fn (ctx &Context) draw_rounded_rect_border(x f32, y f32, w f32, h f32, r f32, border_w f32, border_c Color, bg Color)

draw_rounded_rect_border draws a rounded rectangle with a border using the given parameters. when border width < 1 or the color is transparent, draws a borderless filled rounded rectangle. when the background is transparent, draws a hollow rounded rectangle with only a border. x,y is the top-left corner of the rectangle. w is the width, h is the height. r is the radius of the corner-rounding in pixels. border_w is the width of the border,This implementation uses the mainstream inner border scheme (extending inward). border_c is the color of the border. bg is the background or fill color of the rounded rectangle,supporting transparent colors.

fn (ctx &Context) draw_rounded_rect_empty(x f32, y f32, w f32, h f32, radius f32, c Color)

draw_rounded_rect_empty draws the outline of a rounded rectangle with a thickness of 1 px. x,y is the top-left corner of the rectangle. w is the width, h is the height. radius is the radius of the corner-rounding in pixels. c is the color of the outline.

fn (ctx &Context) draw_rounded_rect_filled(x f32, y f32, w f32, h f32, radius f32, c Color)

draw_rounded_rect_filled draws a filled rounded rectangle. x,y is the top-left corner of the rectangle. w is the width, h is the height . radius is the radius of the corner-rounding in pixels. c is the color of the filled. it divides the rounded rectangle into 2 shapes, the top rounded part and the bottom rounded part which are connected at both extremes.

fn (ctx &Context) draw_slice_empty(x f32, y f32, radius f32, start_angle f32, end_angle f32, segments int,
	c Color)

draw_slice_empty draws the outline of a circle slice/pie

fn (ctx &Context) draw_slice_filled(x f32, y f32, radius f32, start_angle f32, end_angle f32, segments int,
	c Color)

draw_slice_filled draws a filled circle slice/pie x,y defines the end point of the slice (center of the circle that the slice is part of). radius defines the radius ("length") of the slice. start_angle is the angle in radians at which the slice starts. end_angle is the angle in radians at which the slice ends. segments affects how smooth/round the slice is. c is the fill color.

fn (ctx &Context) draw_square_empty(x f32, y f32, s f32, c Color)

draw_square_empty draws the outline of a square. x,y is the top-left corner of the square. s is the length of each side of the square. c is the color of the outline.

fn (ctx &Context) draw_square_filled(x f32, y f32, s f32, c Color)

draw_square_filled draws a filled square. x,y is the top-left corner of the square. s is the length of each side of the square. c is the fill color.

fn (ctx &Context) draw_text(x int, y int, text_ string, cfg TextCfg)

draw_text draws the string in text_ starting at top-left position x,y. Text settings can be provided with cfg.

fn (ctx &Context) draw_text2(p DrawTextParams)

fn (ctx &Context) draw_text_def(x int, y int, text string)

draw_text draws the string in text_ starting at top-left position x,y using default text settings.

fn (ctx &Context) draw_text_default(x int, y int, text string)

default draw_text (draw_text_def but without set_text_cfg)

fn (ctx &Context) draw_triangle_empty(x f32, y f32, x2 f32, y2 f32, x3 f32, y3 f32, c Color)

draw_triangle_empty draws the outline of a triangle. x,y defines the first point x2,y2 defines the second point x3,y3 defines the third point c is the color of the outline.

fn (ctx &Context) draw_triangle_filled(x f32, y f32, x2 f32, y2 f32, x3 f32, y3 f32, c Color)

draw_triangle_filled draws a filled triangle. x,y defines the first point x2,y2 defines the second point x3,y3 defines the third point c is the color of the outline.

fn (ctx &Context) end(options EndOptions)

end finishes all the drawing for the context ctx. All accumulated draw calls before ctx.end(), will be done in a separate Sokol pass.

Note: each Sokol pass, has a limit on the number of draw calls, that can be done in it.Once that limit is reached, the whole pass will not draw anything, which can be frustrating.

To overcome this limitation, you may use several passes, when you want to make thousands of draw calls (for example, if you need to draw thousands of circles/rectangles/sprites etc), where each pass will render just a limited amount of primitives.

In the context of the gg module (without dropping to using sgl and gfx directly), it means, that you will need a new pair of ctx.begin() and ctx.end() calls, surrounding all the draw calls, that should be done in each pass.

The default ctx.end() is equivalent to ctx.end(how:.clear). It will erase the existing rendered content with the background color, before drawing anything else. You can call ctx.end(how:.passthru) for a pass, that will not erase the previously rendered content in the context.

fn (mut ctx Context) get_cached_image_by_idx(image_idx int) &Image

get_cached_image_by_idx returns a cached Image identified by image_idx. If image not found, returns Image{ok: false}

See also: cache_image See also: remove_cached_image_by_idx

fn (ctx &Context) has_text_style() bool

empty function

fn (mut ctx Context) is_key_down(k KeyCode) bool

is_key_down returns whether the given key is currently pressed. You can use this, if you do not want to implement your own key event handling.

fn (mut ctx Context) new_streaming_image(w int, h int, channels int, sicfg StreamingImageConfig) int

new_streaming_image returns a cached image_idx of a special image, that can be updated each frame by calling: gg.update_pixel_data(image_idx, buf) ... where buf is a pointer to the actual pixel data for the image.

Note: you still need to call app.gg.draw_image after that, to actually draw it.

Note: Sokol needs to be setup, before calling this function. In practice, this often means, that you have to call it once in the init_fn callback of gg.new_context, or gg.start, and then store the result in your app instance.

fn (ctx &Context) quit()

quit closes the context window and exits the event loop for it

fn (mut ctx Context) record_frame()

record_frame records the current frame to a file or stdout. record_frame acts according to settings specified in gg.recorder_settings.

fn (mut ctx Context) refresh_ui()

refresh_ui requests a complete re-draw of the window contents.

fn (mut ctx Context) remove_cached_image_by_idx(image_idx int)

remove_cached_image_by_idx removes an Image identified by image_idx from the image cache.

See also: cache_image See also: get_cached_image_by_idx

fn (mut ctx Context) resize(width int, height int)

Resize the context's Window

fn (mut ctx Context) run()

run starts the main loop of the context.

fn (ctx &Context) scissor_rect(x int, y int, w int, h int)

required for ui.DrawDevice interface (with &gg.Context as an instance)

fn (mut ctx Context) set_bg_color(c Color)

set_bg_color sets the color of the window background to c.

fn (ctx &Context) set_text_cfg(cfg TextCfg)

set_text_cfg sets the current text configuration

fn (ctx &Context) set_text_style(font_name string, font_path string, size int, color Color, align int,
	vertical_align int)

empty function

fn (ctx &Context) show_fps()

fn (ctx &Context) text_height(s string) int

text_height returns the height of the string s in pixels.

fn (ctx &Context) text_size(s string) (int, int)

text_size returns the width and height of the string s in pixels.

fn (ctx &Context) text_width(s string) int

text_width returns the width of the string s in pixels.

fn (ctx &Context) text_width_f(s string) f32

text_width returns the width of the string s in pixels.

fn (mut ctx Context) update_pixel_data(cached_image_idx int, buf &u8)

update_pixel_data is a helper for working with image streams (i.e. images, that are updated dynamically by the CPU on each frame)

fn (ctx Context) window_size() Size

window_size returns the current dimensions of the window.

struct DrawImageConfig {
pub mut:
	flip_x    bool // set to true, if you need to flip the image horizontally (around a vertical axis), <- will become ->
	flip_y    bool // set to true, if you need to flip the image vertically (around a horizontal axiz), -\/- will become -/\-
	img       &Image = unsafe { nil }
	img_id    int
	img_rect  Rect // defines the size and position on image when rendering to the screen
	part_rect Rect // defines the size and position of part of the image to use when rendering
	z         f32
	color     Color       = white
	effect    ImageEffect = .alpha

	rotation f32 // the amount to rotate the image in degrees, counterclockwise. Use a negative value, to rotate it clockwise.
}

DrawImageConfig struct defines the various options that can be used to draw an image onto the screen

struct DrawPixelConfig {
pub mut:
	size f32 = 1.0
}

struct DrawRectParams {
pub:
	x          f32
	y          f32
	w          f32
	h          f32
	color      Color      = black
	style      PaintStyle = .fill
	is_rounded bool
	radius     f32
}

struct DrawTextParams {
pub:
	x    int
	y    int
	text string

	color          Color           = black
	size           int             = 16
	align          HorizontalAlign = .left
	vertical_align VerticalAlign   = .top
	max_width      int
	family         string
	bold           bool
	mono           bool
	italic         bool
}

struct EndOptions {
pub:
	how EndEnum
}

struct Event {
pub mut:
	frame_count        u64
	typ                sapp.EventType
	key_code           KeyCode
	char_code          u32
	key_repeat         bool
	modifiers          u32
	mouse_button       MouseButton
	mouse_x            f32
	mouse_y            f32
	mouse_dx           f32
	mouse_dy           f32
	scroll_x           f32
	scroll_y           f32
	num_touches        int
	touches            [8]TouchPoint
	window_width       int
	window_height      int
	framebuffer_width  int
	framebuffer_height int
}

struct FPSConfig {
pub mut:
	x                int  // horizontal position on screen
	y                int  // vertical position on screen
	width            int  // minimum width
	height           int  // minimum height
	show             bool // do not show by default, use `-d show_fps` or set it manually in your app to override with: `app.gg.fps.show = true`
	text_config      TextCfg = TextCfg{
		color:          yellow
		size:           20
		align:          .center
		vertical_align: .middle
	}
	background_color Color = Color{
		r: 0
		g: 0
		b: 0
		a: 128
	}
}

struct FT {
pub:
	fons        &fontstash.Context = unsafe { nil }
	font_normal int
	font_bold   int
	font_mono   int
	font_italic int
pub mut:
	fonts_map map[string]int // for storing custom fonts, provided via cfg.family in draw_text()
	scale     f32 = 1.0
}

fn (ft &FT) flush()

flush prepares the font for use.

struct Image {
pub mut:
	id             int
	width          int
	height         int
	nr_channels    int
	nr_mipmaps     int
	ok             bool
	data           voidptr
	ext            string
	simg_ok        bool
	simg           gfx.Image
	ssmp           gfx.Sampler
	path           string
	texture_filter TextureFilter = .linear
}

Image holds the fields and data needed to represent a bitmap/pixel based image in memory.

fn (mut img Image) init_sokol_image() &Image

init_sokol_image initializes this Image for use with the sokol graphical backend system.

fn (mut img Image) update_pixel_data(buf &u8)

update_pixel_data updates the sokol specific pixel data associated with this Image.

struct ImageConfig {
pub:
	texture_filter ?TextureFilter
	max_mipmaps    int = 1 // a value below 1 means as many as possible
}

struct NativeWindowLease {
	app          &App = unsafe { nil }
	app_instance u64
	window       WindowId
	lease_epoch  u64
	backend      MultiWindowBackend
	primary      voidptr
	secondary    u64
}

NativeWindowLease is an opaque, callback-bounded native-service seam.

fn (mut lease NativeWindowLease) with_appkit(f AppKitNativeWindowFn) !

with_appkit exposes the borrowed NSWindow pointer only during f.

fn (mut lease NativeWindowLease) with_wayland(f WaylandNativeWindowFn) !

with_wayland exposes borrowed wl_display and wl_surface pointers only during f.

fn (mut lease NativeWindowLease) with_win32(f Win32NativeWindowFn) !

with_win32 exposes the borrowed HWND only during f.

fn (mut lease NativeWindowLease) with_x11(f X11NativeWindowFn) !

with_x11 exposes borrowed Display and Window handles only during f.

struct PenConfig {
pub:
	color     Color
	line_type PenLineType = .solid
	thickness f32         = 1
}

struct PipelineContainer {
pub mut:
	alpha sgl.Pipeline
	add   sgl.Pipeline
}

struct PortalParentLeaseId {
	app_instance u64
	serial       u64
}

PortalParentLeaseId identifies a portal parent export until release or window/app teardown invalidates it.

fn (id PortalParentLeaseId) str() string

str returns a diagnostic portal-parent lease identity.

struct PortalParentRequestId {
	app_instance u64
	serial       u64
}

PortalParentRequestId identifies one accepted native-parent request.

fn (id PortalParentRequestId) str() string

str returns a diagnostic portal-parent request identity.

struct PortalParentResult {
pub:
	id         PortalParentRequestId
	window     WindowId
	status     WindowServiceStatus
	lease      PortalParentLeaseId
	identifier string
	error      string
}

PortalParentResult is the terminal result matched to PortalParentRequestId. A ready event already queued before teardown can carry a stale lease.

struct Rect {
pub mut:
	x      f32
	y      f32
	width  f32
	height f32
}

Rect represents a rectangular shape in gg.

struct RunConfig {
pub:
	frame_fn                AppFrameFn           = unsafe { nil }
	event_fn                AppEventFn           = unsafe { nil }
	input_fn                AppInputFn           = unsafe { nil }
	window_service_fn       WindowServiceFn      = unsafe { nil }
	app_resource_init_fn    AppResourceInitFn    = unsafe { nil }
	app_resource_frame_fn   AppResourceFrameFn   = unsafe { nil }
	app_resource_cleanup_fn AppResourceCleanupFn = unsafe { nil }
	readback_fn             WindowReadbackFn     = unsafe { nil }
	max_pending_jobs        int                  = 64
}

RunConfig configures the gg.App loop. event_fn, input_fn, window_service_fn, and readback_fn receive the four canonical queue families in global order. An error from any of those callbacks reinserts the current event and untouched suffix in the same order, so all four handlers must be idempotent. Use event_fn without frame_fn for lifecycle-only loops without a renderer.

struct SSRecorderSettings {
pub mut:
	stop_at_frame     i64 = -1
	screenshot_frames []u64
	screenshot_folder string
	screenshot_prefix string
	screenshot_output ScreenshotOutput = .file
}