mk_app_is_runningfunction
bool mk_app_is_running(void)Return true while an initialized application has not requested quit.
Returns True when the condition holds.
#include <modkit/platform.h>43 functions · 3 structs · 7 enums · 20 typedefs · 9 macros
Window and platform abstraction (SDL3 wrapper).
Provides a Sokol-style callback API for cross-platform applications. SDL functions are available directly for advanced use.
mk_app_is_runningfunctionbool mk_app_is_running(void)Return true while an initialized application has not requested quit.
Returns True when the condition holds.
mk_app_runfunctionmk_result mk_app_run(const mk_app_desc *desc)Run the application with the given descriptor.
This function does not return until the application exits.
| Parameter | Type | Description |
|---|---|---|
desc | const mk_app_desc * | Application descriptor |
Returns MK_SUCCESS or error code
mk_app_startfunctionmk_result mk_app_start(const mk_app_desc *desc)Initialize the application runtime without taking ownership of the main loop.
Unlike mk_app_run(), frame_cb may be NULL. External hosts can call mk_app_step() for platform/input/asset housekeeping, perform their own frame work, and finish with mk_app_stop().
| Parameter | Type | Description |
|---|---|---|
desc | const mk_app_desc * | Configuration descriptor. |
Returns MK_SUCCESS or an error result.
mk_app_stepfunctionmk_result mk_app_step(void)Advance an externally-driven application by one iteration.
When callbacks are present this invokes fixed_cb/frame_cb using the same scheduling behavior as mk_app_run().
Returns MK_SUCCESS or an error result.
mk_app_stopfunctionvoid mk_app_stop(void)Stop an externally-driven application and release all runtime resources.
mk_display_boundsfunctionbool mk_display_bounds(int index, int *x, int *y, int *width, int *height)Desktop bounds of the i-th display in platform-native screen coordinates.
(x, y) is the top-left in the global desktop layout; useful for placing windows on a specific monitor. Any out pointer may be NULL.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
x | int * | Value for x. |
y | int * | Value for y. |
width | int * | Value for width. |
height | int * | Value for height. |
Returns true if the index is valid.
mk_display_content_scalefunctionfloat mk_display_content_scale(int index)Expected content scale of the i-th display: 1.0 standard, 2.0 at 200%.
Returns 0.0 if the index is invalid.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
Returns The resulting value.
mk_display_countfunctionint mk_display_count(void)Number of connected displays (monitors).
Returns The resulting value.
mk_display_current_orientationfunctionmk_display_orientation mk_display_current_orientation(int index)Current orientation of the indexed display, or UNKNOWN if unavailable.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
Returns The resulting value.
mk_display_namefunctionconst char * mk_display_name(int index)Human-readable name of the i-th display, or NULL if out of range.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
Returns A borrowed pointer, or NULL when unavailable.
mk_display_natural_orientationfunctionmk_display_orientation mk_display_natural_orientation(int index)Natural orientation of the indexed display, or UNKNOWN if unavailable.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
Returns The resulting value.
mk_display_usable_boundsfunctionbool mk_display_usable_bounds(int index, int *x, int *y, int *width, int *height)Usable desktop bounds excluding system-reserved areas.
Any output pointer may be NULL. Outputs are zeroed on failure.
| Parameter | Type | Description |
|---|---|---|
index | int | Zero-based index. |
x | int * | Value for x. |
y | int * | Value for y. |
width | int * | Value for width. |
height | int * | Value for height. |
Returns True when the operation succeeds.
mk_file_dialog_showfunctionmk_result mk_file_dialog_show(mk_file_dialog_type_t type, const mk_file_dialog_desc_t *desc, mk_file_dialog_fn callback, void *user_data)Show a native open/save/folder dialog.
Paths are valid only for the duration of the callback, which is delivered from a later main-loop frame.
| Parameter | Type | Description |
|---|---|---|
type | mk_file_dialog_type_t | Value for type. |
desc | const mk_file_dialog_desc_t * | Configuration descriptor. |
callback | mk_file_dialog_fn | Completion callback. |
user_data | void * | Caller-provided context. |
Returns MK_SUCCESS or an error result.
mk_file_dialog_supportedfunctionbool mk_file_dialog_supported(mk_file_dialog_type_t type)File dialogs are available on desktop and Android SDL backends.
| Parameter | Type | Description |
|---|---|---|
type | mk_file_dialog_type_t | Value for type. |
Returns True when the condition holds.
mk_get_delta_timefunctionfloat mk_get_delta_time(void)Get time elapsed since last frame in seconds.
Returns The resulting value.
mk_get_display_heightfunctionint mk_get_display_height(void)Get the native display height in pixels.
Returns The resulting value.
mk_get_display_sizefunctionvoid mk_get_display_size(int *width, int *height)Get the native display (monitor) resolution in pixels.
Returns the full resolution of the display the window is currently on. For example, 3840x2160 on a 4K monitor regardless of window size or scaling.
| Parameter | Type | Description |
|---|---|---|
width | int * | Value for width. |
height | int * | Value for height. |
mk_get_display_widthfunctionint mk_get_display_width(void)Get the native display width in pixels.
Returns The resulting value.
mk_get_dpi_scalefunctionfloat mk_get_dpi_scale(void)Get the window pixel density.
This is physical backbuffer pixels per native window-coordinate unit: pixel_size / window_size. It is commonly 2.0 or 3.0 on Apple/Wayland/web HiDPI windows, but commonly 1.0 on Windows, Android, and X11 even when the user expects enlarged UI.
Returns The resulting value.
mk_get_fixed_alphafunctionfloat mk_get_fixed_alpha(void)Get the fractional fixed-update remainder for render interpolation.
Returns zero when no fixed callback is configured.
Returns The resulting value.
mk_get_fixed_delta_timefunctionfloat mk_get_fixed_delta_time(void)Get the configured fixed-update interval (defaults to 1/60 second).
Returns The resulting value.
mk_get_power_infofunctionmk_power_state mk_get_power_info(int *seconds, int *percent)Query power/battery state.
Optional out params receive estimated seconds of battery life remaining and charge percent (0-100); each is set to -1 when unknown. Either pointer may be NULL.
| Parameter | Type | Description |
|---|---|---|
seconds | int * | Value for seconds. |
percent | int * | Value for percent. |
Returns The resulting value.
mk_get_preferred_localefunctionbool mk_get_preferred_locale(char *language, size_t language_cap, char *country, size_t country_cap)Get the user's most-preferred locale into the provided buffers, e.g.
language "en", country "US" (country may be empty).
| Parameter | Type | Description |
|---|---|---|
language | char * | Value for language. |
language_cap | size_t | Value for language cap. |
country | char * | Value for country. |
country_cap | size_t | Value for country cap. |
Returns true if a locale was available. Either buffer may be NULL.
mk_get_renderer_typefunctionmk_renderer_type_t mk_get_renderer_type(void)Get the current renderer type.
Returns The resulting handle or value.
mk_get_safe_areafunctionbool mk_get_safe_area(mk_rect *area)Get the safe rectangle for interactive content in native window units.
The rest of the window may still be rendered into.
| Parameter | Type | Description |
|---|---|---|
area | mk_rect * | Value for area. |
Returns True when the operation succeeds.
mk_get_safe_insetsfunctionbool mk_get_safe_insets(mk_insets *insets)Get safe-area insets from each edge in native window units.
| Parameter | Type | Description |
|---|---|---|
insets | mk_insets * | Value for insets. |
Returns True when the operation succeeds.
mk_get_system_themefunctionmk_system_theme mk_get_system_theme(void)Current OS light/dark appearance (for theming UI to match the desktop).
Returns The resulting value.
mk_get_target_fpsfunctionint mk_get_target_fps(void)Get the current target frame rate.
Returns Target FPS, or 0 if unlimited/vsync-only
mk_get_timefunctiondouble mk_get_time(void)Get time elapsed since application start in seconds.
Returns The resulting value.
mk_get_user_folderfunctionbool mk_get_user_folder(mk_user_folder_t folder, char *path, size_t path_capacity)Copy a UTF-8 user-folder path into the caller's buffer.
| Parameter | Type | Description |
|---|---|---|
folder | mk_user_folder_t | Value for folder. |
path | char * | Value for path. |
path_capacity | size_t | Value for path capacity. |
Returns True when the operation succeeds.
mk_get_windowfunctionSDL_Window * mk_get_window(void)Get the SDL window handle for direct SDL calls.
Returns A borrowed pointer, or NULL when unavailable.
mk_get_window_display_scalefunctionfloat mk_get_window_display_scale(void)Get the desired display scale in physical pixels per portable content unit.
This includes both backing-buffer density and platform/user UI scaling. It is distinct from mk_get_dpi_scale(), especially on Windows, Android, and X11.
Returns The resulting value.
mk_get_window_sizefunctionvoid mk_get_window_size(int *width, int *height)Get the current size in SDL's native window-coordinate units.
This is the same coordinate space as mouse input and safe-area rectangles. It is point-like on macOS/iOS/Wayland and CSS-pixel-like on web, but Windows, Android, and X11 use physical pixels. Do not assume these units have the same physical size on every platform; use mk_get_window_ui_scale() when converting portable UI/design units to window coordinates.
| Parameter | Type | Description |
|---|---|---|
width | int * | Value for width. |
height | int * | Value for height. |
mk_get_window_size_pixelsfunctionvoid mk_get_window_size_pixels(int *width, int *height)Get current window size in physical pixels.
Use this for advanced rendering that needs to know actual pixel count. On HiDPI displays, this may be larger than the logical size.
| Parameter | Type | Description |
|---|---|---|
width | int * | Value for width. |
height | int * | Value for height. |
mk_get_window_ui_scalefunctionfloat mk_get_window_ui_scale(void)Get native window-coordinate units per portable UI/design unit.
Equivalent to: mk_get_window_display_scale() / mk_get_dpi_scale() Multiply portable UI sizes and offsets by this value before passing them to canvas or input APIs. It is normally 1.0 on macOS/iOS/Wayland/web and the configured content scale on Windows/Android/X11.
Returns The resulting value.
mk_is_headlessfunctionbool mk_is_headless(void)Check if running in headless mode (no window).
Returns True when the condition holds.
mk_message_boxfunctionbool mk_message_box(mk_message_box_type type, const char *title, const char *message)Show a blocking native message box.
Safe to call before/without a window (e.g. to report a fatal init error).
| Parameter | Type | Description |
|---|---|---|
type | mk_message_box_type | Value for type. |
title | const char * | Value for title. |
message | const char * | Value for message. |
Returns true on success.
mk_open_urlfunctionbool mk_open_url(const char *url)Open a URL (http/https/mailto/file...) in the user's default handler.
On web this opens a new tab (may require a user gesture).
| Parameter | Type | Description |
|---|---|---|
url | const char * | Value for URL. |
Returns true on success.
mk_request_quitfunctionvoid mk_request_quit(void)Request application exit.
mk_screenshot_requestfunctionmk_result mk_screenshot_request(mk_screenshot_fn callback, void *user_data)Request a screenshot of the current frame.
The callback will be called on a future frame when the screenshot is ready.
| Parameter | Type | Description |
|---|---|---|
callback | mk_screenshot_fn | Function to call with screenshot data |
user_data | void * | User pointer passed to callback |
Returns MK_SUCCESS if request was queued
mk_screenshot_savefunctionmk_result mk_screenshot_save(const char *filepath)Request a screenshot and save directly to a file.
Supports PNG, BMP, TGA, JPG formats (determined by extension).
| Parameter | Type | Description |
|---|---|---|
filepath | const char * | Output file path |
Returns MK_SUCCESS if request was queued
mk_set_target_fpsfunctionvoid mk_set_target_fps(int fps)Set the target frame rate at runtime.
| Parameter | Type | Description |
|---|---|---|
fps | int | Target FPS (0 = unlimited/vsync-only) |
mk_should_quitfunctionbool mk_should_quit(void)Check if quit has been requested.
Returns True when the operation succeeds.
mk_app_descstructApplication descriptor - Sokol-style configuration.
Example:
| Field | Type | Description |
|---|---|---|
init_cb | mk_init_fn | Called after init (required). |
frame_cb | mk_frame_fn | Called each frame (required). |
fixed_cb | mk_fixed_fn | Called zero or more times before frame_cb. |
cleanup_cb | mk_cleanup_fn | Called before shutdown. |
resize_cb | mk_resize_fn | Called on window resize. |
event_cb | mk_event_fn | Called for SDL events. |
input_cb | mk_input_fn | Called for input events (alternative to polling). |
user_data | void * | Passed to all callbacks. |
window_title | const char * | Window title (default: "modkit"). |
width | int | Initial width (default: 1280). |
height | int | Initial height (default: 720). |
window_flags | uint32_t | SDL_WINDOW_* flags. |
renderer | mk_renderer_type_t | Renderer type (MK_RENDERER_AUTO = auto). |
reset_flags | uint32_t | Reset flags (MK_RESET_* from graphics.h, default: MK_RESET_VSYNC). |
video_decode | mk_video_decode_mode_t | Hardware video device opt-in. |
debug_flags | uint32_t | Initial debug flags, 0 = none. |
target_fps | int | Frame rate limiting Target frame rate (0 = unlimited/vsync-only, default). |
fixed_hz | int | Fixed callback frequency (0 = 60, negative = invalid). |
max_fixed_steps | int | Catch-up cap per frame (0 = 8, negative = invalid). |
asset_path | const char * | Primary asset search path (e.g., "assets/"). |
asset_paths | const char ** | Additional search paths (NULL-terminated array). |
web_base_url | const char * | Base URL for web asset fetching (default: same origin). |
lifecycle_cb | mk_lifecycle_fn | Immediate lifecycle notifications. |
allowed_orientations | uint32_t | MK_ORIENTATION_* flags, 0 = platform default. |
mk_file_dialog_descstructData for file dialog desc.
| Field | Type | Description |
|---|---|---|
title | const char * | The title. |
default_location | const char * | The default location. |
filters | const mk_file_dialog_filter_t * | The filters. |
filter_count | uint16_t | The filter count. |
allow_multiple | bool | The allow multiple. |
mk_file_dialog_filterstructData for file dialog filter.
| Field | Type | Description |
|---|---|---|
name | const char * | The name. |
pattern | const char * | Semicolon-separated extensions, e.g. |
mk_display_orientationenumValues for display orientation.
| Value | Description |
|---|---|
MK_DISPLAY_ORIENTATION_UNKNOWN | Selects unknown. |
MK_DISPLAY_ORIENTATION_LANDSCAPE | Selects landscape. |
MK_DISPLAY_ORIENTATION_LANDSCAPE_FLIPPED | Selects landscape flipped. |
MK_DISPLAY_ORIENTATION_PORTRAIT | Selects portrait. |
MK_DISPLAY_ORIENTATION_PORTRAIT_FLIPPED | Selects portrait flipped. |
mk_file_dialog_typeenumValues for file dialog type.
| Value | Description |
|---|---|
MK_FILE_DIALOG_OPEN | Selects open. |
MK_FILE_DIALOG_SAVE | Selects save. |
MK_FILE_DIALOG_FOLDER | Selects folder. |
mk_lifecycle_eventenumValues for lifecycle event.
| Value | Description |
|---|---|
MK_LIFECYCLE_SUSPENDING | Selects suspending. |
MK_LIFECYCLE_SUSPENDED | Selects suspended. |
MK_LIFECYCLE_RESUMING | Selects resuming. |
MK_LIFECYCLE_RESUMED | Selects resumed. |
MK_LIFECYCLE_LOW_MEMORY | Selects low memory. |
MK_LIFECYCLE_TERMINATING | Selects terminating. |
mk_message_box_typeenumSeverity for mk_message_box().
| Value | Description |
|---|---|
MK_MESSAGE_BOX_INFO | Selects info. |
MK_MESSAGE_BOX_WARNING | Selects warning. |
MK_MESSAGE_BOX_ERROR | Selects error. |
mk_orientation_flagsenumValues for orientation flags.
| Value | Description |
|---|---|
MK_ORIENTATION_PORTRAIT | Selects portrait. |
MK_ORIENTATION_PORTRAIT_UPSIDE_DOWN | Selects portrait upside down. |
MK_ORIENTATION_LANDSCAPE_LEFT | Selects landscape left. |
MK_ORIENTATION_LANDSCAPE_RIGHT | Selects landscape right. |
MK_ORIENTATION_ALL | Selects all. |
mk_power_stateenumBattery / power-supply state.
| Value | Description |
|---|---|
MK_POWER_UNKNOWN | Cannot determine power status. |
MK_POWER_ON_BATTERY | Unplugged, running on battery. |
MK_POWER_NO_BATTERY | Plugged in, no battery. |
MK_POWER_CHARGING | Plugged in, charging. |
MK_POWER_CHARGED | Plugged in, fully charged. |
mk_user_folderenumValues for user folder.
| Value | Description |
|---|---|
MK_USER_FOLDER_HOME | Selects home. |
MK_USER_FOLDER_DESKTOP | Selects desktop. |
MK_USER_FOLDER_DOCUMENTS | Selects documents. |
MK_USER_FOLDER_DOWNLOADS | Selects downloads. |
MK_USER_FOLDER_MUSIC | Selects music. |
MK_USER_FOLDER_PICTURES | Selects pictures. |
MK_USER_FOLDER_PUBLIC_SHARE | Selects public share. |
MK_USER_FOLDER_SAVED_GAMES | Selects saved games. |
MK_USER_FOLDER_SCREENSHOTS | Selects screenshots. |
MK_USER_FOLDER_TEMPLATES | Selects templates. |
MK_USER_FOLDER_VIDEOS | Selects videos. |
MK_USER_FOLDER_COUNT | Selects count. |
mk_app_desctypedeftypedef struct mk_app_desc mk_app_descApplication descriptor - Sokol-style configuration.
Example:
void init(void* ud) { ... }
void frame(void* ud) { ... }
void cleanup(void* ud) { ... }
int main(int argc, char** argv) {
mk_app_run(&(mk_app_desc){
.init_cb = init,
.frame_cb = frame,
.cleanup_cb = cleanup,
.window_title = "My App",
.width = 1280,
.height = 720,
});
return 0;
}mk_cleanup_fntypedeftypedef void(*) mk_cleanup_fn(void *user_data)Called before shutdown.
mk_display_orientationtypedeftypedef enum mk_display_orientation mk_display_orientationValues for display orientation.
mk_event_fntypedeftypedef bool(*) mk_event_fn(const SDL_Event *event, void *user_data)Called for each SDL event (return true to consume).
mk_file_dialog_desc_ttypedeftypedef struct mk_file_dialog_desc mk_file_dialog_desc_tData for file dialog desc.
mk_file_dialog_filter_ttypedeftypedef struct mk_file_dialog_filter mk_file_dialog_filter_tData for file dialog filter.
mk_file_dialog_fntypedeftypedef void(*) mk_file_dialog_fn(mk_result result, const char *const *paths, uint32_t path_count, int32_t selected_filter, void *user_data)Callback used for file dialog.
mk_file_dialog_type_ttypedeftypedef enum mk_file_dialog_type mk_file_dialog_type_tValues for file dialog type.
mk_fixed_fntypedeftypedef void(*) mk_fixed_fn(float dt, void *user_data)Called at a fixed interval before the frame callback.
mk_frame_fntypedeftypedef void(*) mk_frame_fn(void *user_data)Called every frame.
mk_init_fntypedeftypedef void(*) mk_init_fn(void *user_data)Called once after initialization completes.
mk_input_fntypedeftypedef void(*) mk_input_fn(const struct mk_input_event *event, void *user_data)Callback used for input.
mk_lifecycle_eventtypedeftypedef enum mk_lifecycle_event mk_lifecycle_eventValues for lifecycle event.
mk_lifecycle_fntypedeftypedef void(*) mk_lifecycle_fn(mk_lifecycle_event event, void *user_data)Called immediately for mobile lifecycle events.
May run outside the main thread; do not render or block.
mk_message_box_typetypedeftypedef enum mk_message_box_type mk_message_box_typeSeverity for mk_message_box().
mk_orientation_flagstypedeftypedef enum mk_orientation_flags mk_orientation_flagsValues for orientation flags.
mk_power_statetypedeftypedef enum mk_power_state mk_power_stateBattery / power-supply state.
mk_resize_fntypedeftypedef void(*) mk_resize_fn(int width, int height, void *user_data)Called when window is resized.
mk_screenshot_fntypedeftypedef void(*) mk_screenshot_fn(const void *data, uint32_t width, uint32_t height, void *user_data)Callback for screenshot completion.
mk_user_folder_ttypedeftypedef enum mk_user_folder mk_user_folder_tValues for user folder.
MK_WINDOW_ALWAYS_ON_TOPdefineMK_WINDOW_ALWAYS_ON_TOPWindow is always on top.
MK_WINDOW_BORDERLESSdefineMK_WINDOW_BORDERLESSWindow has no border/decoration.
MK_WINDOW_FULLSCREENdefineMK_WINDOW_FULLSCREENWindow starts fullscreen.
MK_WINDOW_HEADLESSdefineMK_WINDOW_HEADLESSHeadless mode - no window created, for server/batch processing.
MK_WINDOW_HIDDENdefineMK_WINDOW_HIDDENWindow starts hidden.
MK_WINDOW_HIDPIdefineMK_WINDOW_HIDPIEnable HiDPI/Retina display support.
MK_WINDOW_MAXIMIZEDdefineMK_WINDOW_MAXIMIZEDWindow starts maximized.
MK_WINDOW_MINIMIZEDdefineMK_WINDOW_MINIMIZEDWindow starts minimized.
MK_WINDOW_RESIZABLEdefineMK_WINDOW_RESIZABLEWindow can be resized.