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

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 window lifecycle events through event_fn and input events through input_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. 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() to collect backend events, then app.drain_events() for lifecycle events and app.drain_input_events() for window-scoped input events. app.run() dispatches lifecycle and input callbacks from the ordered backend queue; the separate drain functions are useful when the application wants to process the two streams independently.

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. 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, and X11 file drops use XDND text/uri-list. Wayland text uses xkb keymap/state for key-press characters, and Wayland file drops use wl_data_device/wl_data_offer text/uri-list; neither Linux text path implements full IME/composed text yet.

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.

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. Readback is not available on the native backends: Capabilities.readback, WindowReadbackCapabilities.offscreen_image, and WindowReadbackCapabilities.window_capture are false. Calls to request_window_capture() or request_image_readback() return gg.multiwindow: requested readback is not supported.

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 WindowReadbackStatus.from[W](input W) !WindowReadbackStatus

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

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

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 AppResourceCleanupFn = fn (mut AppResourceContext) !

type AppResourceContext = WindowResourceContext

AppResourceContext uses the same managed resource operations with app scope.

type AppResourceFrameFn = fn (mut AppResourceContext) !

type AppResourceInitFn = fn (mut AppResourceContext) !

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) !

type TouchPoint = C.sapp_touchpoint

type WindowCleanupFn = fn (mut WindowCleanupContext) !

type WindowDrawFn = fn (mut window WindowContext) !

WindowDrawFn records drawing commands for one WindowContext.

type WindowFrameFn = fn (mut WindowContext) !

type WindowInitFn = fn (mut WindowInitContext) !

type WindowPassFn = fn (mut WindowPassContext) !

type WindowReadbackFn = fn (WindowReadbackResult, mut App) !

type WindowResourceFn = fn (mut WindowResourceContext) !

type WindowSglFn = fn (mut WindowSglContext) !

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
}

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

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.

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

drain_events returns and clears pending window lifecycle events.

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

drain_input_events returns and clears pending window-scoped input events.

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) draw_window(id WindowId, draw WindowDrawFn) !

draw_window renders one live window through its WindowContext.

fn (mut app App) poll_events() !int

poll_events lets the backend route native lifecycle/input events into the gg.App 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) 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 capture of a window's rendered pixels.

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

resize_window requests a live window resize.

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

run starts the multi-window owner loop. event_fn can drive lifecycle-only apps without a renderer; frame_fn/draw_window require explicit swapchains.

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_title(id WindowId, title string) !

set_window_title updates a live window title.

fn (mut app App) stop() !

stop shuts down the app and destroys live windows.

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_readback_capabilities(id WindowId) !WindowReadbackCapabilities

window_readback_capabilities reports the readback operations supported for a window.

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.

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

AppConfig configures a multi-window gg application facade.

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

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
}

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

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

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

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 }
	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. Use event_fn without frame_fn for lifecycle-only loops that do not require a renderer.

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

struct Size {
pub mut:
	width  int
	height int
}

struct StreamingImageConfig {
pub:
	pixel_format gfx.PixelFormat = .rgba8
	wrap_u       gfx.Wrap        = .clamp_to_edge
	wrap_v       gfx.Wrap        = .clamp_to_edge
	min_filter   gfx.Filter      = .linear
	mag_filter   gfx.Filter      = .linear
	num_mipmaps  int             = 1
	num_slices   int             = 1
}

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

fn (cfg &TextCfg) to_css_string() string

to_css_string returns a CSS compatible string of the TextCfg cfg. For example: 'mono 14px serif'.

struct WindowAttachmentsConfig {
pub:
	colors        []WindowImageId
	resolves      []WindowImageId
	depth_stencil ?WindowImageId
}

struct WindowAttachmentsId {
	app_instance u64
	slot         int
	generation   u32
	window       WindowId
}

struct WindowBindings {
pub:
	vertex_buffers []WindowBufferBinding
	index_buffer   ?WindowBufferBinding
	vs             WindowStageBindings
	fs             WindowStageBindings
}

struct WindowBufferBinding {
pub:
	slot   int
	buffer WindowBufferId
	offset int
}

struct WindowBufferId {
	app_instance u64
	slot         int
	generation   u32
	window       WindowId
}

struct WindowCleanupContext {
	app            &App = unsafe { nil }
	app_instance   u64
	lease_epoch    u64
	info           WindowFrameInfo
	cleanup_reason WindowCleanupReason
	has_graphics   bool
}

WindowCleanupContext is a callback-bounded window cleanup lease.

fn (context &WindowCleanupContext) graphics_available() bool

graphics_available reports whether managed graphics teardown is still permitted.

fn (context &WindowCleanupContext) metrics() WindowMetrics

metrics returns the final immutable metrics snapshot supplied to cleanup.

fn (context &WindowCleanupContext) reason() WindowCleanupReason

reason identifies why the window's render lifetime is ending.

fn (context &WindowCleanupContext) render_target_info() WindowRenderTargetInfo

render_target_info returns the final render-target contract supplied to cleanup.

fn (context &WindowCleanupContext) window_id() WindowId

window_id identifies the window that owns this cleanup callback.

fn (mut context WindowCleanupContext) with_native_window(f NativeWindowBorrowFn) !

with_native_window borrows the backend's live native window for the duration of the callback.

fn (mut context WindowCleanupContext) with_resources(f WindowResourceFn) !

with_resources grants managed resource teardown authority during cleanup.

struct WindowConfig {
pub:
	title        string = 'A GG Window'
	width        int    = 800
	height       int    = 600
	min_width    int
	min_height   int
	resizable    bool = true
	visible      bool = true
	high_dpi     bool = true
	borderless   bool
	fullscreen   bool
	clear_color  Color = Color{
		a: 0
	}
	sample_count int              = 1
	redraw_mode  WindowRedrawMode = .on_demand
	init_fn      WindowInitFn     = unsafe { nil }
	frame_fn     WindowFrameFn    = unsafe { nil }
	cleanup_fn   WindowCleanupFn  = unsafe { nil }
}

WindowConfig describes one window at creation time.

struct WindowContext {
	app                        &App = unsafe { nil }
	app_instance               u64
	lease_epoch                u64
	info                       WindowFrameInfo
	compatibility_capabilities Capabilities
}

WindowContext is a callback-bounded window frame lease.

fn (context &WindowContext) capabilities() Capabilities

capabilities reports the app backend capabilities captured for this context.

fn (context &WindowContext) draw_rect_empty(x f32, y f32, w f32, h f32, color Color)

draw_rect_empty is available when compiling with -d gg_multiwindow.

fn (context &WindowContext) draw_rect_filled(x f32, y f32, w f32, h f32, color Color)

draw_rect_filled is available when compiling with -d gg_multiwindow.

fn (context &WindowContext) exists() bool

exists reports whether this context still targets a live window.

fn (context &WindowContext) frame_info() WindowFrameInfo

frame_info returns the immutable window and target snapshot bound to this frame callback.

fn (context &WindowContext) framebuffer_size() Size

framebuffer_size returns the current render target size in pixels.

fn (context &WindowContext) logical_bounds() WindowLogicalRect

logical_bounds returns the current logical drawable rectangle with an origin of zero.

fn (context &WindowContext) logical_size() WindowLogicalSize

logical_size returns the current drawable size in logical coordinates.

fn (context &WindowContext) logical_to_pixel_rect(rect WindowLogicalRect) WindowPixelRect

logical_to_pixel_rect converts a logical rectangle using this frame's admitted metrics.

fn (context &WindowContext) pixel_bounds() WindowPixelRect

pixel_bounds returns the current framebuffer rectangle with an origin of zero.

fn (context &WindowContext) pixel_to_logical_rect(rect WindowPixelRect) WindowLogicalRect

pixel_to_logical_rect converts a framebuffer rectangle using this frame's admitted metrics.

fn (mut context WindowContext) request_image_readback(id WindowImageId, config WindowReadbackConfig) !WindowReadbackId

request_image_readback queues an asynchronous readback of a managed image.

fn (context &WindowContext) size() Size

size returns the current draw size. Logical scaling will be added with native DPI routing.

fn (context &WindowContext) window_id() WindowId

window_id returns the id routed to this draw context.

fn (mut context WindowContext) with_offscreen(config WindowOffscreenPassConfig, f WindowPassFn) !

with_offscreen runs a managed render pass against managed offscreen attachments.

fn (mut context WindowContext) with_offscreen_sgl(config WindowOffscreenPassConfig, f WindowSglFn) !

with_offscreen_sgl runs scoped SGL drawing against managed offscreen attachments.

fn (mut context WindowContext) with_resources(f WindowResourceFn) !

with_resources grants managed resource authority scoped to the current frame callback.

fn (mut context WindowContext) with_swapchain(action gfx.PassAction, f WindowPassFn) !

with_swapchain runs a managed render pass against the current window swapchain.

fn (mut context WindowContext) with_swapchain_sgl(action gfx.PassAction, f WindowSglFn) !

with_swapchain_sgl runs scoped SGL drawing against the current window swapchain.

struct WindowEvent {
pub:
	kind   WindowEventKind
	window WindowId
	// width and height are meaningful for .window_created and .window_resized events.
	width  int
	height int
}

WindowEvent is the multi-window event wrapper. The existing gg.Event remains the legacy single-window gg.Context event type.

struct WindowFrameInfo {
pub:
	window          WindowId
	frame_serial    u64
	submitted_frame u64
	metrics         WindowMetrics
	target          WindowRenderTargetInfo
}

struct WindowId {
	app_instance u64
}

WindowId identifies a window managed by gg.App.

fn (id WindowId) str() string

str returns a diagnostic representation of a WindowId.

struct WindowImageBinding {
pub:
	slot  int
	image WindowImageId
}

struct WindowImageId {
	app_instance u64
	slot         int
	generation   u32
	window       WindowId
}

struct WindowInfo {
pub:
	id                 WindowId
	title              string
	width              int
	height             int
	min_width          int
	min_height         int
	resizable          bool
	visible            bool
	high_dpi           bool
	borderless         bool
	fullscreen         bool
	native_decorations bool
}

WindowInfo is a snapshot of a live gg.App window.

struct WindowInitContext {
	app          &App = unsafe { nil }
	app_instance u64
	lease_epoch  u64
	info         WindowFrameInfo
}

WindowInitContext is a callback-bounded window initialization lease.

fn (context &WindowInitContext) metrics() WindowMetrics

metrics returns the immutable window metrics admitted for initialization.

fn (context &WindowInitContext) render_target_info() WindowRenderTargetInfo

render_target_info returns the render-target contract admitted for initialization.

fn (context &WindowInitContext) window_id() WindowId

window_id identifies the window that owns this initialization callback.

fn (mut context WindowInitContext) with_resources(f WindowResourceFn) !

with_resources grants managed resource authority scoped to the initialization callback.

struct WindowInputEvent {
pub:
	window        WindowId
	event         Event
	dropped_files []string
}

WindowInputEvent routes a normal gg.Event to a specific gg.App window.

struct WindowLogicalRect {
pub:
	x      f32
	y      f32
	width  f32
	height f32
}

struct WindowLogicalSize {
pub:
	width  f32
	height f32
}

struct WindowMetrics {
pub:
	logical_size     WindowLogicalSize
	framebuffer_size WindowPixelSize
	dpi_scale        f32
	metrics_sequence u64
	submitted_frame  u64
}

struct WindowOffscreenPassConfig {
pub:
	attachments WindowAttachmentsId
	action      gfx.PassAction
}

WindowOffscreenPassConfig selects managed attachments and the action used to begin an offscreen pass.

struct WindowPassContext {
	app          &App = unsafe { nil }
	app_instance u64
	window       WindowId
	lease_epoch  u64
	pass_epoch   u64
	info         WindowFrameInfo
}

WindowPassContext bounds draw recording to one managed pass.

fn (mut pass WindowPassContext) apply_bindings(bindings WindowBindings) !

apply_bindings binds managed buffers, images, and samplers for this pass.