Skip to content
modkitv0.2

platform.h

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

Functions

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.

mk_app_runfunction

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

ParameterTypeDescription
descconst mk_app_desc *Application descriptor

Returns MK_SUCCESS or error code

mk_app_startfunction

mk_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().

ParameterTypeDescription
descconst mk_app_desc *Configuration descriptor.

Returns MK_SUCCESS or an error result.

mk_app_stepfunction

mk_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_stopfunction

void mk_app_stop(void)

Stop an externally-driven application and release all runtime resources.

mk_display_boundsfunction

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

ParameterTypeDescription
indexintZero-based index.
xint *Value for x.
yint *Value for y.
widthint *Value for width.
heightint *Value for height.

Returns true if the index is valid.

mk_display_content_scalefunction

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

ParameterTypeDescription
indexintZero-based index.

Returns The resulting value.

mk_display_countfunction

int mk_display_count(void)

Number of connected displays (monitors).

Returns The resulting value.

mk_display_current_orientationfunction

mk_display_orientation mk_display_current_orientation(int index)

Current orientation of the indexed display, or UNKNOWN if unavailable.

ParameterTypeDescription
indexintZero-based index.

Returns The resulting value.

mk_display_namefunction

const char * mk_display_name(int index)

Human-readable name of the i-th display, or NULL if out of range.

ParameterTypeDescription
indexintZero-based index.

Returns A borrowed pointer, or NULL when unavailable.

mk_display_natural_orientationfunction

mk_display_orientation mk_display_natural_orientation(int index)

Natural orientation of the indexed display, or UNKNOWN if unavailable.

ParameterTypeDescription
indexintZero-based index.

Returns The resulting value.

mk_display_usable_boundsfunction

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

ParameterTypeDescription
indexintZero-based index.
xint *Value for x.
yint *Value for y.
widthint *Value for width.
heightint *Value for height.

Returns True when the operation succeeds.

mk_file_dialog_showfunction

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

ParameterTypeDescription
typemk_file_dialog_type_tValue for type.
descconst mk_file_dialog_desc_t *Configuration descriptor.
callbackmk_file_dialog_fnCompletion callback.
user_datavoid *Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_file_dialog_supportedfunction

bool mk_file_dialog_supported(mk_file_dialog_type_t type)

File dialogs are available on desktop and Android SDL backends.

ParameterTypeDescription
typemk_file_dialog_type_tValue for type.

Returns True when the condition holds.

mk_get_delta_timefunction

float mk_get_delta_time(void)

Get time elapsed since last frame in seconds.

Returns The resulting value.

mk_get_display_heightfunction

int mk_get_display_height(void)

Get the native display height in pixels.

Returns The resulting value.

mk_get_display_sizefunction

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

ParameterTypeDescription
widthint *Value for width.
heightint *Value for height.

mk_get_display_widthfunction

int mk_get_display_width(void)

Get the native display width in pixels.

Returns The resulting value.

mk_get_dpi_scalefunction

float 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_alphafunction

float 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_timefunction

float mk_get_fixed_delta_time(void)

Get the configured fixed-update interval (defaults to 1/60 second).

Returns The resulting value.

mk_get_power_infofunction

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

ParameterTypeDescription
secondsint *Value for seconds.
percentint *Value for percent.

Returns The resulting value.

mk_get_preferred_localefunction

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

ParameterTypeDescription
languagechar *Value for language.
language_capsize_tValue for language cap.
countrychar *Value for country.
country_capsize_tValue for country cap.

Returns true if a locale was available. Either buffer may be NULL.

mk_get_renderer_typefunction

mk_renderer_type_t mk_get_renderer_type(void)

Get the current renderer type.

Returns The resulting handle or value.

mk_get_safe_areafunction

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

ParameterTypeDescription
areamk_rect *Value for area.

Returns True when the operation succeeds.

mk_get_safe_insetsfunction

bool mk_get_safe_insets(mk_insets *insets)

Get safe-area insets from each edge in native window units.

ParameterTypeDescription
insetsmk_insets *Value for insets.

Returns True when the operation succeeds.

mk_get_system_themefunction

mk_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_fpsfunction

int mk_get_target_fps(void)

Get the current target frame rate.

Returns Target FPS, or 0 if unlimited/vsync-only

mk_get_timefunction

double mk_get_time(void)

Get time elapsed since application start in seconds.

Returns The resulting value.

mk_get_user_folderfunction

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

ParameterTypeDescription
foldermk_user_folder_tValue for folder.
pathchar *Value for path.
path_capacitysize_tValue for path capacity.

Returns True when the operation succeeds.

mk_get_windowfunction

SDL_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_scalefunction

float 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_sizefunction

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

ParameterTypeDescription
widthint *Value for width.
heightint *Value for height.

mk_get_window_size_pixelsfunction

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

ParameterTypeDescription
widthint *Value for width.
heightint *Value for height.

mk_get_window_ui_scalefunction

float 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_headlessfunction

bool mk_is_headless(void)

Check if running in headless mode (no window).

Returns True when the condition holds.

mk_message_boxfunction

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

ParameterTypeDescription
typemk_message_box_typeValue for type.
titleconst char *Value for title.
messageconst char *Value for message.

Returns true on success.

mk_open_urlfunction

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

ParameterTypeDescription
urlconst char *Value for URL.

Returns true on success.

mk_request_quitfunction

void mk_request_quit(void)

Request application exit.

mk_screenshot_requestfunction

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

ParameterTypeDescription
callbackmk_screenshot_fnFunction to call with screenshot data
user_datavoid *User pointer passed to callback

Returns MK_SUCCESS if request was queued

mk_screenshot_savefunction

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

ParameterTypeDescription
filepathconst char *Output file path

Returns MK_SUCCESS if request was queued

mk_set_target_fpsfunction

void mk_set_target_fps(int fps)

Set the target frame rate at runtime.

ParameterTypeDescription
fpsintTarget FPS (0 = unlimited/vsync-only)

mk_should_quitfunction

bool mk_should_quit(void)

Check if quit has been requested.

Returns True when the operation succeeds.

Structs

mk_app_descstruct

Application descriptor - Sokol-style configuration.

Example:

FieldTypeDescription
init_cbmk_init_fnCalled after init (required).
frame_cbmk_frame_fnCalled each frame (required).
fixed_cbmk_fixed_fnCalled zero or more times before frame_cb.
cleanup_cbmk_cleanup_fnCalled before shutdown.
resize_cbmk_resize_fnCalled on window resize.
event_cbmk_event_fnCalled for SDL events.
input_cbmk_input_fnCalled for input events (alternative to polling).
user_datavoid *Passed to all callbacks.
window_titleconst char *Window title (default: "modkit").
widthintInitial width (default: 1280).
heightintInitial height (default: 720).
window_flagsuint32_tSDL_WINDOW_* flags.
renderermk_renderer_type_tRenderer type (MK_RENDERER_AUTO = auto).
reset_flagsuint32_tReset flags (MK_RESET_* from graphics.h, default: MK_RESET_VSYNC).
video_decodemk_video_decode_mode_tHardware video device opt-in.
debug_flagsuint32_tInitial debug flags, 0 = none.
target_fpsintFrame rate limiting Target frame rate (0 = unlimited/vsync-only, default).
fixed_hzintFixed callback frequency (0 = 60, negative = invalid).
max_fixed_stepsintCatch-up cap per frame (0 = 8, negative = invalid).
asset_pathconst char *Primary asset search path (e.g., "assets/").
asset_pathsconst char **Additional search paths (NULL-terminated array).
web_base_urlconst char *Base URL for web asset fetching (default: same origin).
lifecycle_cbmk_lifecycle_fnImmediate lifecycle notifications.
allowed_orientationsuint32_tMK_ORIENTATION_* flags, 0 = platform default.

mk_file_dialog_descstruct

Data for file dialog desc.

FieldTypeDescription
titleconst char *The title.
default_locationconst char *The default location.
filtersconst mk_file_dialog_filter_t *The filters.
filter_countuint16_tThe filter count.
allow_multipleboolThe allow multiple.

mk_file_dialog_filterstruct

Data for file dialog filter.

FieldTypeDescription
nameconst char *The name.
patternconst char *Semicolon-separated extensions, e.g.

Enums

mk_display_orientationenum

Values for display orientation.

ValueDescription
MK_DISPLAY_ORIENTATION_UNKNOWNSelects unknown.
MK_DISPLAY_ORIENTATION_LANDSCAPESelects landscape.
MK_DISPLAY_ORIENTATION_LANDSCAPE_FLIPPEDSelects landscape flipped.
MK_DISPLAY_ORIENTATION_PORTRAITSelects portrait.
MK_DISPLAY_ORIENTATION_PORTRAIT_FLIPPEDSelects portrait flipped.

mk_file_dialog_typeenum

Values for file dialog type.

ValueDescription
MK_FILE_DIALOG_OPENSelects open.
MK_FILE_DIALOG_SAVESelects save.
MK_FILE_DIALOG_FOLDERSelects folder.

mk_lifecycle_eventenum

Values for lifecycle event.

ValueDescription
MK_LIFECYCLE_SUSPENDINGSelects suspending.
MK_LIFECYCLE_SUSPENDEDSelects suspended.
MK_LIFECYCLE_RESUMINGSelects resuming.
MK_LIFECYCLE_RESUMEDSelects resumed.
MK_LIFECYCLE_LOW_MEMORYSelects low memory.
MK_LIFECYCLE_TERMINATINGSelects terminating.

mk_message_box_typeenum

Severity for mk_message_box().

ValueDescription
MK_MESSAGE_BOX_INFOSelects info.
MK_MESSAGE_BOX_WARNINGSelects warning.
MK_MESSAGE_BOX_ERRORSelects error.

mk_orientation_flagsenum

Values for orientation flags.

ValueDescription
MK_ORIENTATION_PORTRAITSelects portrait.
MK_ORIENTATION_PORTRAIT_UPSIDE_DOWNSelects portrait upside down.
MK_ORIENTATION_LANDSCAPE_LEFTSelects landscape left.
MK_ORIENTATION_LANDSCAPE_RIGHTSelects landscape right.
MK_ORIENTATION_ALLSelects all.

mk_power_stateenum

Battery / power-supply state.

ValueDescription
MK_POWER_UNKNOWNCannot determine power status.
MK_POWER_ON_BATTERYUnplugged, running on battery.
MK_POWER_NO_BATTERYPlugged in, no battery.
MK_POWER_CHARGINGPlugged in, charging.
MK_POWER_CHARGEDPlugged in, fully charged.

mk_user_folderenum

Values for user folder.

ValueDescription
MK_USER_FOLDER_HOMESelects home.
MK_USER_FOLDER_DESKTOPSelects desktop.
MK_USER_FOLDER_DOCUMENTSSelects documents.
MK_USER_FOLDER_DOWNLOADSSelects downloads.
MK_USER_FOLDER_MUSICSelects music.
MK_USER_FOLDER_PICTURESSelects pictures.
MK_USER_FOLDER_PUBLIC_SHARESelects public share.
MK_USER_FOLDER_SAVED_GAMESSelects saved games.
MK_USER_FOLDER_SCREENSHOTSSelects screenshots.
MK_USER_FOLDER_TEMPLATESSelects templates.
MK_USER_FOLDER_VIDEOSSelects videos.
MK_USER_FOLDER_COUNTSelects count.

Typedefs

mk_app_desctypedef

typedef struct mk_app_desc mk_app_desc

Application 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_fntypedef

typedef void(*) mk_cleanup_fn(void *user_data)

Called before shutdown.

mk_display_orientationtypedef

typedef enum mk_display_orientation mk_display_orientation

Values for display orientation.

mk_event_fntypedef

typedef bool(*) mk_event_fn(const SDL_Event *event, void *user_data)

Called for each SDL event (return true to consume).

mk_file_dialog_desc_ttypedef

typedef struct mk_file_dialog_desc mk_file_dialog_desc_t

Data for file dialog desc.

mk_file_dialog_filter_ttypedef

typedef struct mk_file_dialog_filter mk_file_dialog_filter_t

Data for file dialog filter.

mk_file_dialog_fntypedef

typedef 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_ttypedef

typedef enum mk_file_dialog_type mk_file_dialog_type_t

Values for file dialog type.

mk_fixed_fntypedef

typedef void(*) mk_fixed_fn(float dt, void *user_data)

Called at a fixed interval before the frame callback.

mk_frame_fntypedef

typedef void(*) mk_frame_fn(void *user_data)

Called every frame.

mk_init_fntypedef

typedef void(*) mk_init_fn(void *user_data)

Called once after initialization completes.

mk_input_fntypedef

typedef void(*) mk_input_fn(const struct mk_input_event *event, void *user_data)

Callback used for input.

mk_lifecycle_eventtypedef

typedef enum mk_lifecycle_event mk_lifecycle_event

Values for lifecycle event.

mk_lifecycle_fntypedef

typedef 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_typetypedef

typedef enum mk_message_box_type mk_message_box_type

Severity for mk_message_box().

mk_orientation_flagstypedef

typedef enum mk_orientation_flags mk_orientation_flags

Values for orientation flags.

mk_power_statetypedef

typedef enum mk_power_state mk_power_state

Battery / power-supply state.

mk_resize_fntypedef

typedef void(*) mk_resize_fn(int width, int height, void *user_data)

Called when window is resized.

mk_screenshot_fntypedef

typedef void(*) mk_screenshot_fn(const void *data, uint32_t width, uint32_t height, void *user_data)

Callback for screenshot completion.

mk_user_folder_ttypedef

typedef enum mk_user_folder mk_user_folder_t

Values for user folder.

Macros

MK_WINDOW_ALWAYS_ON_TOPdefine

MK_WINDOW_ALWAYS_ON_TOP

Window is always on top.

MK_WINDOW_BORDERLESSdefine

MK_WINDOW_BORDERLESS

Window has no border/decoration.

MK_WINDOW_FULLSCREENdefine

MK_WINDOW_FULLSCREEN

Window starts fullscreen.

MK_WINDOW_HEADLESSdefine

MK_WINDOW_HEADLESS

Headless mode - no window created, for server/batch processing.

MK_WINDOW_HIDDENdefine

MK_WINDOW_HIDDEN

Window starts hidden.

MK_WINDOW_HIDPIdefine

MK_WINDOW_HIDPI

Enable HiDPI/Retina display support.

MK_WINDOW_MAXIMIZEDdefine

MK_WINDOW_MAXIMIZED

Window starts maximized.

MK_WINDOW_MINIMIZEDdefine

MK_WINDOW_MINIMIZED

Window starts minimized.

MK_WINDOW_RESIZABLEdefine

MK_WINDOW_RESIZABLE

Window can be resized.