sokol.sapp #

fn android_get_native_activity() voidptr

Android: get native activity handle

fn bind_mouse_cursor_image(cursor MouseCursor, desc &ImageDesc) MouseCursor

bind a custom mouse cursor image to a cursor type

fn cancel_quit()

cancel a pending quit (when SAPP_EVENTTYPE_QUIT_REQUESTED has been received)

fn color_format() int

color_format gets default framebuffer color pixel format

fn consume_event()

call from inside event callback to consume the current event (don't forward to platform)

fn create_default_pass(action gfx.PassAction) gfx.Pass

create_default_pass creates a default gfx.Pass compatible with sapp and sokol.gfx.begin_pass/1.

fn create_desc() gfx.Desc

create_desc creates a default gfx.Desc configured for use with sapp.

fn d3d11_get_swap_chain() voidptr

D3D11: get pointer to IDXGISwapChain object

fn depth_format() int

depth_format gets default framebuffer depth pixel format

fn dpi_scale() f32

returns the dpi scaling factor (window pixels to framebuffer pixels)

fn egl_get_context() voidptr

EGL: get EGLContext object

fn egl_get_display() voidptr

EGL: get EGLDisplay object

fn frame_count() u64

get the current frame counter (for comparison with sapp_event.frame_count)

fn frame_duration() f64

get an averaged/smoothed frame duration in seconds

fn get_clipboard_string() &char

read string from clipboard (usually during SAPP_EVENTTYPE_CLIPBOARD_PASTED)

fn get_dropped_file_path(index int) string

get_dropped_file_path returns the path of a dropped file by index.

fn get_environment() Environment

get runtime environment information

fn get_mouse_cursor() MouseCursor

get current mouse cursor type

fn get_num_dropped_files() int

get_num_dropped_files returns the number of files dropped onto the window.

fn get_swapchain() Swapchain

get current frame's swapchain information (call once per frame!)

fn gl_get_framebuffer() u32

GL: get framebuffer object

fn gl_get_major_version() int

GL: get major version

fn gl_get_minor_version() int

GL: get minor version

fn gl_is_gles() bool

GL: return true if the context is GLES

fn glue_environment() gfx.Environment

glue_environment returns a gfx.Environment compatible for use with sapp specific gfx.Passes. The returned gfx.Environment can be used when rendering via sapp. See also: documentation at the top of thirdparty/sokol/sokol_gfx.h

fn glue_swapchain() gfx.Swapchain

glue_swapchain returns a gfx.Swapchain compatible for use with sapp specific display/rendering gfx.Passes. The returned gfx.Swapchain can be used when rendering via sapp. See also: documentation at the top of thirdparty/sokol/sokol_gfx.h

fn height() int

returns the current framebuffer height in pixels

fn high_dpi() bool

returns true when high_dpi was requested and actually running in a high-dpi scenario

fn html5_ask_leave_site(ask bool)

HTML5: enable or disable the hardwired "Leave Site?" dialog box

fn html5_get_dropped_file_size(index int) u32

HTML5: get byte size of a dropped file

fn ios_get_window() voidptr

iOS: get ARC-bridged pointer to iOS UIWindow

fn is_fullscreen() bool

Check if full screen rendering

fn isvalid() bool

returns true after sokol-app has been initialized

fn keyboard_shown() bool

return true if the mobile device onscreen keyboard is currently shown

fn lock_mouse(locked bool)

lock_mouse locks or unlocks the mouse cursor, confining it to the window.

fn macos_get_window() voidptr

macOS: get ARC-bridged pointer to macOS NSWindow

fn mouse_locked() bool

mouse_locked returns true if the mouse is currently locked to the window.

fn mouse_shown() bool

show or hide the mouse cursor

fn query_desc() Desc

return a copy of the sapp_desc structure

fn quit()

initiate a "hard quit" (quit application without sending SAPP_EVENTTYPE_QUIT_REQUESTED)

fn request_quit()

initiate a "soft quit" (sends SAPP_EVENTTYPE_QUIT_REQUESTED)

fn run(desc &Desc)

special run-function for SOKOL_NO_ENTRY (in standard mode this is an empty stub)

fn sample_count() int

sample_count gets default framebuffer sample count

fn screenshot(path string) !

screenshot takes a screenshot of the current window and saves it to path. The format is inferred from the extension of the file name in path.

Supported formats are: .png, .ppm.

fn screenshot_png(path string) !

screenshot_png takes a screenshot of the current window and saves it to path as a .png file.

fn screenshot_ppm(path string) !

screenshot_ppm takes a screenshot of the current window and saves it to path as a .ppm file.

fn screenshot_window() &Screenshot

screenshot_window captures a screenshot of the current window.

fn set_clipboard_string(str &u8)

write string into clipboard

fn set_icon(icon_desc &IconDesc)

set the window icon (only on Windows and Linux)

fn set_mouse_cursor(cursor MouseCursor)

set mouse cursor

fn show_keyboard(visible bool)

show or hide the mobile device onscreen keyboard

fn show_mouse(visible bool)

show or hide the mouse cursor

fn toggle_fullscreen()

Toggle full screen

fn unbind_mouse_cursor_image(cursor MouseCursor)

unbind a custom mouse cursor image

fn userdata() voidptr

return the userdata pointer optionally provided in sapp_desc

fn width() int

returns the current framebuffer width in pixels

fn win32_get_hwnd() voidptr

Win32: get the HWND window handle

fn x11_get_display() voidptr

X11: get Display

fn x11_get_window() voidptr

X11: get Window

type Allocator = C.sapp_allocator

type Atom = u64

type Colormap = u64

type Cursor = u64

type D3d11Environment = C.sapp_d3d11_environment

type D3d11Swapchain = C.sapp_d3d11_swapchain

type Desc = C.sapp_desc

type EGLConfig = voidptr

type EGLContext = voidptr

type EGLDisplay = voidptr

type EGLNativeWindowType = voidptr

type EGLSurface = voidptr

type EGLint = i32

type Environment = C.sapp_environment

type EnvironmentDefaults = C.sapp_environment_defaults

type Event = C.sapp_event

fn (e &Event) str() string

type GlDesc = C.sapp_gl_desc

type GlSwapchain = C.sapp_gl_swapchain

type Html5Desc = C.sapp_html5_desc

type IconDesc = C.sapp_icon_desc

type ImageDesc = C.sapp_image_desc

type IosDesc = C.sapp_ios_desc

type KeySym = u64

type Logger = C.sapp_logger

type MetalEnvironment = C.sapp_metal_environment

type MetalSwapchain = C.sapp_metal_swapchain

type Range = C.sapp_range

type Swapchain = C.sapp_swapchain

type Time = u64

type TouchPoint = C.sapp_touchpoint

type VisualID = u64

type VulkanEnvironment = C.sapp_vulkan_environment

type VulkanSwapchain = C.sapp_vulkan_swapchain

type WgpuEnvironment = C.sapp_wgpu_environment

type WgpuSwapchain = C.sapp_wgpu_swapchain

type Win32Desc = C.sapp_win32_desc

type Window = u64

type XID = u64

X11 types

type XcursorPixel = u32

type XkbDescPtr = &C.XkbDescRec

type XrmDatabase = &C.XrmDatabase__rec

enum EventType {
	invalid
	key_down
	key_up
	char
	mouse_down
	mouse_up
	mouse_scroll
	mouse_move
	mouse_enter
	mouse_leave
	touches_began
	touches_moved
	touches_ended
	touches_cancelled
	resized
	iconified
	restored
	focused
	unfocused
	suspended
	resumed
	quit_requested
	clipboard_pasted
	files_dropped
	num
}

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 //(1<<0)
	ctrl  = 2 //(1<<1)
	alt   = 4 //(1<<2)
	super = 8 //(1<<3)
	lmb   = 0x100
	rmb   = 0x200
	mmb   = 0x400
}

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

enum MouseCursor {
	default       = 0
	arrow         = 1
	ibeam         = 2
	crosshair     = 3
	pointing_hand = 4
	resize_ew     = 5
	resize_ns     = 6
	resize_nwse   = 7
	resize_nesw   = 8
	resize_all    = 9
	not_allowed   = 10
	custom_0      = 11
	custom_1      = 12
	custom_2      = 13
	custom_3      = 14
	custom_4      = 15
	custom_5      = 16
	custom_6      = 17
	custom_7      = 18
	custom_8      = 19
	custom_9      = 20
	custom_10     = 21
	custom_11     = 22
	custom_12     = 23
	custom_13     = 24
	custom_14     = 25
	custom_15     = 26
}

enum TouchToolType {
	unknown
	finger
	stylus
	mouse
	eraser
	palm
}

TouchToolType is an Android specific 'tool type' enum for touch events. This lets the application check what type of input device was used for touch events.

Note: the values must remain in sync with the corresponding Android SDK type, so don't change those. See https://developer.android.com/reference/android/view/MotionEvent#TOOL_TYPE_UNKNOWN

struct C.Display {
pub mut:
	_ int // opaque - actual definition from X11 headers
}

X11 types are defined by X11 headers (#preinclude above) Forward declarations for V type checking only

struct C.Screen {
pub mut:
	_ int // opaque - actual definition from X11 headers
}

struct C.Visual {
pub mut:
	_ int // opaque - actual definition from X11 headers
}

struct C.XButtonEvent {
pub mut:
	button u32
	state  u32
	x      int
	y      int
}

union C.XClientMessageData {
pub mut:
	l [5]i64
}

struct C.XClientMessageEvent {
pub mut:
	window       Window
	format       int
	message_type Atom
	data         C.XClientMessageData
}

XSelection* structs are forward-declared above Full definitions come from X11 headers or clipboard module

struct C.XCrossingEvent {
pub mut:
	x     int
	y     int
	state u32
}

struct C.XDestroyWindowEvent {
pub mut:
	window Window
}

union C.XEvent {
pub mut:
	@type             int
	xclient           C.XClientMessageEvent
	xkey              C.XKeyEvent
	xbutton           C.XButtonEvent
	xmotion           C.XMotionEvent
	xcrossing         C.XCrossingEvent
	xfocus            C.XFocusChangeEvent
	xproperty         C.XPropertyEvent
	xselection        C.XSelectionEvent
	xselectionrequest C.XSelectionRequestEvent
	xselectionclear   C.XSelectionClearEvent
	xdestroywindow    C.XDestroyWindowEvent
	xcookie           C.XGenericEventCookie
}

X11 event types are defined in vlib/x/x11/x11.v XEvent union is defined here since it's used extensively in sokol

struct C.XFocusChangeEvent {
pub mut:
	mode int
}

struct C.XGenericEventCookie {
pub mut:
	extension int
	evtype    int
	data      voidptr
}

struct C.XIEventMask {
mut:
	deviceid int
	mask_len int
	mask     &u8 = unsafe { nil }
}

XInput2 types

struct C.XIRawEvent {
mut:
	valuators  C.XIValuatorState
	raw_values &f64 = unsafe { nil }
}

struct C.XIValuatorState {
mut:
	mask_len int
	mask     &u8 = unsafe { nil }
}

struct C.XKeyEvent {
pub mut:
	keycode u32
	state   u32
}

struct C.XMotionEvent {
pub mut:
	x     int
	y     int
	state u32
}

struct C.XPropertyEvent {
pub mut:
	state int
	atom  Atom
}

struct C.XSelectionClearEvent {
pub mut:
	window    Window
	selection Atom
}

struct C.XSelectionEvent {
pub mut:
	type      int
	display   &C.Display = unsafe { nil }
	requestor Window
	selection Atom
	target    Atom
	property  Atom
	time      int
}

struct C.XSelectionRequestEvent {
pub mut:
	display   &C.Display = unsafe { nil }
	owner     Window
	requestor Window
	selection Atom
	target    Atom
	property  Atom
	time      int
}

struct C.XSetWindowAttributes {
mut:
	colormap     Colormap
	border_pixel u64
	event_mask   u64
}

struct C.XSizeHints {
mut:
	flags       i64
	win_gravity int
}

struct C.XVisualInfo {
mut:
	visual   &C.Visual = unsafe { nil }
	visualid VisualID
	depth    int
}

struct C.XWindowAttributes {
mut:
	width     int
	height    int
	map_state int
}

struct C.XcursorImage {
mut:
	width  u32
	height u32
	xhot   u32
	yhot   u32
	pixels &u32 = unsafe { nil }
}

Xcursor types

struct C.XkbDescRec {
mut:
	min_key_code u8
	max_key_code u8
	names        &C.XkbNamesRec = unsafe { nil }
}

XKB types

struct C.XkbKeyAliasRec {
mut:
	real  [4]u8
	alias [4]u8
}

struct C.XkbKeyNameRec {
mut:
	name [4]u8
}

struct C.XkbNamesRec {
mut:
	keys            &C.XkbKeyNameRec  = unsafe { nil }
	key_aliases     &C.XkbKeyAliasRec = unsafe { nil }
	num_key_aliases u8
}

struct C.XrmDatabase__rec {}

struct C.XrmValue {
	addr &char = unsafe { nil }
}

struct C.pollfd {
mut:
	fd      int
	events  i16
	revents i16
}

struct C.sapp_allocator {
pub mut:
	alloc_fn  memory.FnAllocatorAlloc = unsafe { nil }
	free_fn   memory.FnAllocatorFree  = unsafe { nil }
	user_data voidptr
}

struct C.sapp_d3d11_environment {
pub:
	device         voidptr
	device_context voidptr
}

struct C.sapp_d3d11_swapchain {
pub:
	render_view        voidptr
	resolve_view       voidptr
	depth_stencil_view voidptr
}

struct C.sapp_desc {
pub mut:
	// these are the user-provided callbacks without user data
	init_cb    fn ()       = unsafe { nil }
	frame_cb   fn ()       = unsafe { nil }
	cleanup_cb fn ()       = unsafe { nil }
	event_cb   fn (&Event) = unsafe { nil } // &sapp_event

	user_data           voidptr // these are the user-provided callbacks with user data
	init_userdata_cb    fn (voidptr)         = unsafe { nil }
	frame_userdata_cb   fn (voidptr)         = unsafe { nil }
	cleanup_userdata_cb fn (voidptr)         = unsafe { nil }
	event_userdata_cb   fn (&Event, voidptr) = unsafe { nil }

	width                        int       // the preferred width of the window / canvas
	height                       int       // the preferred height of the window / canvas
	sample_count                 int       // MSAA sample count
	swap_interval                int       // the preferred swap interval (ignored on some platforms)
	high_dpi                     bool      // whether the rendering canvas is full-resolution on HighDPI displays
	fullscreen                   bool      // whether the window should be created in fullscreen mode
	alpha                        bool      // whether the framebuffer should have an alpha channel (ignored on some platforms)
	window_title                 &char     // the window title as UTF-8 encoded string
	enable_clipboard             bool      // enable clipboard access, default is false
	clipboard_size               int       // max size of clipboard content in bytes
	enable_dragndrop             bool      // enable file dropping (drag'n'drop), default is false
	max_dropped_files            int       // max number of dropped files to process (default: 1)
	max_dropped_file_path_length int       // max length in bytes of a dropped UTF-8 file path (default: 2048)
	icon                         IconDesc  // the initial window icon to set
	allocator                    Allocator // optional memory allocation overrides (default: malloc/free)
	logger                       Logger    // logging callback override (default: NO LOGGING!)
	// backend-specific options
	gl    GlDesc    // OpenGL specific options
	win32 Win32Desc // Win32 specific options
	html5 Html5Desc // HTML5 specific options
	ios   IosDesc   // iOS specific options
	// V patches
	__v_native_render bool // V patch to allow for native rendering
	min_width         int  // V patch to allow for min window width
	min_height        int  // V patch to allow for min window height
}

struct C.sapp_environment {
pub:
	defaults EnvironmentDefaults
	metal    MetalEnvironment
	d3d11    D3d11Environment
	wgpu     WgpuEnvironment
	vulkan   VulkanEnvironment
}

struct C.sapp_environment_defaults {
pub:
	color_format int
	depth_format int
	sample_count int
}

--- environment structs (returned by sapp_get_environment) ---

struct C.sapp_event {
pub mut:
	frame_count        u64                         // current frame counter, always valid, useful for checking if two events were issued in the same frame
	type               EventType                   // the event type, always valid
	key_code           KeyCode                     // the virtual key code, only valid in KEY_UP, KEY_DOWN
	char_code          u32                         // the UTF-32 character code, only valid in CHAR events
	key_repeat         bool                        // true if this is a key-repeat event, valid in KEY_UP, KEY_DOWN and CHAR
	modifiers          u32                         // current modifier keys, valid in all key-, char- and mouse-events
	mouse_button       MouseButton                 // mouse button that was pressed or released, valid in MOUSE_DOWN, MOUSE_UP
	mouse_x            f32                         // current horizontal mouse position in pixels, always valid except during mouse lock
	mouse_y            f32                         // current vertical mouse position in pixels, always valid except during mouse lock
	mouse_dx           f32                         // relative horizontal mouse movement since last frame, always valid
	mouse_dy           f32                         // relative vertical mouse movement since last frame, always valid
	scroll_x           f32                         // horizontal mouse wheel scroll distance, valid in MOUSE_SCROLL events
	scroll_y           f32                         // vertical mouse wheel scroll distance, valid in MOUSE_SCROLL events
	num_touches        int                         // number of valid items in the touches[] array
	touches            [max_touchpoints]TouchPoint // current touch points, valid in TOUCHES_BEGIN, TOUCHES_MOVED, TOUCHES_ENDED
	window_width       int                         // current window- and framebuffer width in pixels, always valid
	window_height      int                         // current window- and framebuffer height in pixels, always valid
	framebuffer_width  int                         // = window_width * dpi_scale
	framebuffer_height int                         // = window_height * dpi_scale
}

struct C.sapp_gl_desc {
pub mut:
	major_version int // override GL/GLES major version
	minor_version int // override GL/GLES minor version
}

struct C.sapp_gl_swapchain {
pub:
	framebuffer u32
}

struct C.sapp_html5_desc {
pub:
	canvas_selector                           &char = c'#canvas' // css selector of the HTML5 canvas element, default is "#canvas"
	canvas_resize                             bool // if true, the HTML5 canvas size is set to sapp_desc.width/height
	preserve_drawing_buffer                   bool // HTML5 only: whether to preserve default framebuffer content between frames
	premultiplied_alpha                       bool // HTML5 only: whether the rendered pixels use premultiplied alpha convention
	ask_leave_site                            bool // initial state of the internal html5_ask_leave_site flag
	update_document_title                     bool // if true, update the HTML document.title with sapp_desc.window_title
	bubble_mouse_events                       bool // if true, mouse events will bubble up to the web page
	bubble_touch_events                       bool // same for touch events
	bubble_wheel_events                       bool // same for wheel events
	bubble_key_events                         bool // if true, bubble up *all* key events to browser
	bubble_char_events                        bool // if true, bubble up character events to browser
	use_emsc_set_main_loop                    bool // if true, use emscripten_set_main_loop() instead of emscripten_request_animation_frame_loop()
	emsc_set_main_loop_simulate_infinite_loop bool // this will be passed as the simulate_infinite_loop arg to emscripten_set_main_loop()
}

struct C.sapp_icon_desc {
pub:
	sokol_default bool
	images        [max_iconimages]ImageDesc
}

struct C.sapp_image_desc {
pub:
	width            int
	height           int
	cursor_hotspot_x int
	cursor_hotspot_y int
	pixels           Range
}

struct C.sapp_ios_desc {
pub:
	keyboard_resizes_canvas bool // if true, showing the iOS keyboard shrinks the canvas
}

struct C.sapp_logger {
pub mut:
	func      memory.FnLogCb = unsafe { nil }
	user_data voidptr
}

struct C.sapp_metal_environment {
pub:
	device voidptr
}

struct C.sapp_metal_swapchain {
pub:
	current_drawable      voidptr
	depth_stencil_texture voidptr
	msaa_color_texture    voidptr
}

--- swapchain structs (returned by sapp_get_swapchain) ---

struct C.sapp_range {
pub:
	ptr  voidptr
	size usize
}

sapp_range is a general pointer/size-pair struct for passing binary blobs into sokol_app.h

struct C.sapp_swapchain {
pub:
	width        int
	height       int
	sample_count int
	color_format int
	depth_format int
	metal        MetalSwapchain
	d3d11        D3d11Swapchain
	wgpu         WgpuSwapchain
	vulkan       VulkanSwapchain
	gl           GlSwapchain
}

struct C.sapp_touchpoint {
pub:
	identifier       u64
	pos_x            f32
	pos_y            f32
	android_tooltype TouchToolType
	changed          bool
}

struct C.sapp_vulkan_environment {
pub:
	instance           voidptr
	physical_device    voidptr
	device             voidptr
	queue              voidptr
	queue_family_index u32
}

struct C.sapp_vulkan_swapchain {
pub:
	render_image               voidptr
	render_view                voidptr
	resolve_image              voidptr
	resolve_view               voidptr
	depth_stencil_image        voidptr
	depth_stencil_view         voidptr
	render_finished_semaphore  voidptr
	present_complete_semaphore voidptr
}

struct C.sapp_wgpu_environment {
pub:
	device voidptr
}

struct C.sapp_wgpu_swapchain {
pub:
	render_view        voidptr
	resolve_view       voidptr
	depth_stencil_view voidptr
}

struct C.sapp_win32_desc {
pub:
	console_utf8   bool // if true, set the output console codepage to UTF-8
	console_create bool // if true, attach stdout/stderr to a new console window
	console_attach bool // if true, attach stdout/stderr to parent process
}

struct Screenshot {
	width  int
	height int
	size   int
mut:
	pixels &u8 = unsafe { nil }
}

fn (mut ss Screenshot) free()

free - free only the Screenshot pixels.

fn (mut ss Screenshot) destroy()

destroy - free the Screenshot pixels, then free the screenshot data structure itself.