App, Window, And I/O API¶

Native app loop, windows, canvases, input routing, GUI hooks, frame streams, capture, and video.

Status: mixed tiers; see spec/api/status.yml

This generated page lists exported C functions and their canonical public types classified by the v0.4 C API reference policy. Raw Python ctypes call forms are documented separately.

Use this page when integrating Datoviz into a native app loop, window, canvas, GUI, capture, or video path.

Common workflows:

Functions: 209 Types: 108

Symbol Groups¶

Group	Functions	Types	Headers
Application Lifecycle	15	8	3 headers
Canvas Execution	18	12	`include/datoviz/canvas.h`, `include/datoviz/canvas/enums.h`
Display Sizing	0	6	`include/datoviz/app.h`, `include/datoviz/window/size.h`
GUI	34	8	`include/datoviz/gui.h`
Input Routing	26	25	5 headers
Streaming And Video	19	15	4 headers
Views And Capture	59	8	3 headers
Window Hosting	38	26	5 headers

Grouped function index

Application Lifecycle

Function	Header
`dvz_app()`	`include/datoviz/app.h`
`dvz_app_capture_config()`	`include/datoviz/app.h`
`dvz_app_capture_config_from_env()`	`include/datoviz/app.h`
`dvz_app_config()`	`include/datoviz/app.h`
`dvz_app_destroy()`	`include/datoviz/app.h`
`dvz_app_reap_closed_views()`	`include/datoviz/app.h`
`dvz_app_render_once()`	`include/datoviz/app.h`
`dvz_app_resources()`	`include/datoviz/app.h`
`dvz_app_run()`	`include/datoviz/app.h`
`dvz_app_should_exit()`	`include/datoviz/app.h`
`dvz_app_should_stop()`	`include/datoviz/app.h`
`dvz_app_stop()`	`include/datoviz/app.h`
`dvz_app_vk_instance()`	`include/datoviz/app_interop.h`
`dvz_app_with_config()`	`include/datoviz/app.h`
`dvz_app_with_resources()`	`include/datoviz/app.h`

Canvas Execution

Function	Header
`dvz_canvas_capture_png()`	`include/datoviz/canvas.h`
`dvz_canvas_capture_rgba()`	`include/datoviz/canvas.h`
`dvz_canvas_capture_rgba_into()`	`include/datoviz/canvas.h`
`dvz_canvas_config()`	`include/datoviz/canvas.h`
`dvz_canvas_configure_live_image_sink()`	`include/datoviz/canvas.h`
`dvz_canvas_configure_video_sink()`	`include/datoviz/canvas.h`
`dvz_canvas_create()`	`include/datoviz/canvas.h`
`dvz_canvas_destroy()`	`include/datoviz/canvas.h`
`dvz_canvas_frame()`	`include/datoviz/canvas.h`
`dvz_canvas_input()`	`include/datoviz/canvas.h`
`dvz_canvas_live_image_sink_config()`	`include/datoviz/canvas.h`
`dvz_canvas_offscreen_runtime_state()`	`include/datoviz/canvas.h`
`dvz_canvas_present_runtime_state()`	`include/datoviz/canvas.h`
`dvz_canvas_render_mode()`	`include/datoviz/canvas.h`
`dvz_canvas_set_draw_callback()`	`include/datoviz/canvas.h`
`dvz_canvas_stream()`	`include/datoviz/canvas.h`
`dvz_canvas_submit()`	`include/datoviz/canvas.h`
`dvz_canvas_timings()`	`include/datoviz/canvas.h`

GUI

Function	Header
`dvz_gui_begin()`	`include/datoviz/gui.h`
`dvz_gui_button()`	`include/datoviz/gui.h`
`dvz_gui_checkbox()`	`include/datoviz/gui.h`
`dvz_gui_collapsing_header()`	`include/datoviz/gui.h`
`dvz_gui_color_edit4()`	`include/datoviz/gui.h`
`dvz_gui_color_edit_dvz()`	`include/datoviz/gui.h`
`dvz_gui_color_picker4()`	`include/datoviz/gui.h`
`dvz_gui_combo()`	`include/datoviz/gui.h`
`dvz_gui_config()`	`include/datoviz/gui.h`
`dvz_gui_current_window_docked()`	`include/datoviz/gui.h`
`dvz_gui_current_window_rect()`	`include/datoviz/gui.h`
`dvz_gui_demo()`	`include/datoviz/gui.h`
`dvz_gui_dock_window_once()`	`include/datoviz/gui.h`
`dvz_gui_end()`	`include/datoviz/gui.h`
`dvz_gui_pop_font()`	`include/datoviz/gui.h`
`dvz_gui_push_mono()`	`include/datoviz/gui.h`
`dvz_gui_range_float()`	`include/datoviz/gui.h`
`dvz_gui_same_line()`	`include/datoviz/gui.h`
`dvz_gui_separator_text()`	`include/datoviz/gui.h`
`dvz_gui_slider_float()`	`include/datoviz/gui.h`
`dvz_gui_slider_float2()`	`include/datoviz/gui.h`
`dvz_gui_slider_float3()`	`include/datoviz/gui.h`
`dvz_gui_slider_float4()`	`include/datoviz/gui.h`
`dvz_gui_slider_float_format()`	`include/datoviz/gui.h`
`dvz_gui_slider_int()`	`include/datoviz/gui.h`
`dvz_gui_slider_range_float()`	`include/datoviz/gui.h`
`dvz_gui_text()`	`include/datoviz/gui.h`
`dvz_gui_viewport()`	`include/datoviz/gui.h`
`dvz_gui_viewport_config()`	`include/datoviz/gui.h`
`dvz_gui_viewport_destroy()`	`include/datoviz/gui.h`
`dvz_gui_viewport_from_window()`	`include/datoviz/gui.h`
`dvz_gui_viewport_input()`	`include/datoviz/gui.h`
`dvz_gui_viewport_mouse()`	`include/datoviz/gui.h`
`dvz_gui_viewport_window()`	`include/datoviz/gui.h`

Input Routing

Function	Header
`dvz_input_emit_event()`	`include/datoviz/input/router.h`
`dvz_input_emit_keyboard()`	`include/datoviz/input/router.h`
`dvz_input_emit_pointer()`	`include/datoviz/input/router.h`
`dvz_input_emit_resize()`	`include/datoviz/input/router.h`
`dvz_input_emit_scale()`	`include/datoviz/input/router.h`
`dvz_input_router()`	`include/datoviz/input/router.h`
`dvz_input_router_destroy()`	`include/datoviz/input/router.h`
`dvz_input_router_last_resize()`	`include/datoviz/input/router.h`
`dvz_input_subscribe_event()`	`include/datoviz/input/router.h`
`dvz_input_subscribe_keyboard()`	`include/datoviz/input/router.h`
`dvz_input_subscribe_pointer()`	`include/datoviz/input/router.h`
`dvz_input_subscribe_resize()`	`include/datoviz/input/router.h`
`dvz_input_subscribe_scale()`	`include/datoviz/input/router.h`
`dvz_input_timestamp_ns()`	`include/datoviz/input/pointer.h`
`dvz_input_unsubscribe()`	`include/datoviz/input/router.h`
`dvz_keyboard_emit()`	`include/datoviz/input/keyboard.h`
`dvz_keyboard_modifier_bit()`	`include/datoviz/input/keyboard.h`
`dvz_keyboard_modifier_state()`	`include/datoviz/input/keyboard.h`
`dvz_keyboard_modifier_state_destroy()`	`include/datoviz/input/keyboard.h`
`dvz_keyboard_modifier_state_mods()`	`include/datoviz/input/keyboard.h`
`dvz_keyboard_modifier_state_update()`	`include/datoviz/input/keyboard.h`
`dvz_pointer_button_from_glfw()`	`include/datoviz/input/pointer.h`
`dvz_pointer_emit_position()`	`include/datoviz/input/pointer.h`
`dvz_pointer_emit_wheel()`	`include/datoviz/input/pointer.h`
`dvz_pointer_gesture_handler()`	`include/datoviz/input/pointer.h`
`dvz_pointer_gesture_handler_destroy()`	`include/datoviz/input/pointer.h`

Streaming And Video

Function	Header
`dvz_stream_attach_sink()`	`include/datoviz/stream.h`
`dvz_stream_attach_sink_name()`	`include/datoviz/stream.h`
`dvz_stream_config()`	`include/datoviz/stream.h`
`dvz_stream_create()`	`include/datoviz/stream.h`
`dvz_stream_destroy()`	`include/datoviz/stream.h`
`dvz_stream_device()`	`include/datoviz/stream.h`
`dvz_stream_get_config()`	`include/datoviz/stream.h`
`dvz_stream_sink_registry_create()`	`include/datoviz/stream.h`
`dvz_stream_sink_registry_destroy()`	`include/datoviz/stream.h`
`dvz_stream_sink_registry_find()`	`include/datoviz/stream.h`
`dvz_stream_sink_registry_pick()`	`include/datoviz/stream.h`
`dvz_stream_sink_registry_register()`	`include/datoviz/stream.h`
`dvz_stream_sink_video()`	`include/datoviz/video.h`
`dvz_stream_start()`	`include/datoviz/stream.h`
`dvz_stream_stop()`	`include/datoviz/stream.h`
`dvz_stream_submit()`	`include/datoviz/stream.h`
`dvz_stream_update()`	`include/datoviz/stream.h`
`dvz_video_encoder_config()`	`include/datoviz/video.h`
`dvz_video_sink_config()`	`include/datoviz/video.h`

Views And Capture

Function	Header
`dvz_view()`	`include/datoviz/app.h`
`dvz_view_arcball()`	`include/datoviz/app.h`
`dvz_view_bind_controller()`	`include/datoviz/app.h`
`dvz_view_canvas()`	`include/datoviz/app.h`
`dvz_view_capabilities()`	`include/datoviz/app.h`
`dvz_view_capture_from_env()`	`include/datoviz/app.h`
`dvz_view_capture_png()`	`include/datoviz/app.h`
`dvz_view_capture_start()`	`include/datoviz/app.h`
`dvz_view_capture_stop()`	`include/datoviz/app.h`
`dvz_view_connect_panel()`	`include/datoviz/app.h`
`dvz_view_desc()`	`include/datoviz/app.h`
`dvz_view_device_scale()`	`include/datoviz/app.h`
`dvz_view_device_scale_xy()`	`include/datoviz/app.h`
`dvz_view_emit_key()`	`include/datoviz/app.h`
`dvz_view_emit_pointer()`	`include/datoviz/app.h`
`dvz_view_emit_resize()`	`include/datoviz/app.h`
`dvz_view_emit_wheel()`	`include/datoviz/app.h`
`dvz_view_external_surface()`	`include/datoviz/app_interop.h`
`dvz_view_fly()`	`include/datoviz/app.h`
`dvz_view_framebuffer_size()`	`include/datoviz/app.h`
`dvz_view_gui()`	`include/datoviz/gui.h`
`dvz_view_input()`	`include/datoviz/app.h`
`dvz_view_logical_size()`	`include/datoviz/app.h`
`dvz_view_offscreen()`	`include/datoviz/app.h`
`dvz_view_panzoom()`	`include/datoviz/app.h`
`dvz_view_post()`	`include/datoviz/app.h`
`dvz_view_record_start()`	`include/datoviz/app.h`
`dvz_view_record_stop()`	`include/datoviz/app.h`
`dvz_view_release_external_surface()`	`include/datoviz/app_interop.h`
`dvz_view_render_enabled()`	`include/datoviz/app.h`
`dvz_view_render_once()`	`include/datoviz/app.h`
`dvz_view_render_scale()`	`include/datoviz/app.h`
`dvz_view_replay_frame_count()`	`include/datoviz/app.h`
`dvz_view_replay_set_loop()`	`include/datoviz/app.h`
`dvz_view_replay_set_paced()`	`include/datoviz/app.h`
`dvz_view_replay_set_speed()`	`include/datoviz/app.h`
`dvz_view_replay_start()`	`include/datoviz/app.h`
`dvz_view_replay_stop()`	`include/datoviz/app.h`
`dvz_view_request_frame()`	`include/datoviz/app.h`
`dvz_view_resize()`	`include/datoviz/app.h`
`dvz_view_resize_scaled()`	`include/datoviz/app.h`
`dvz_view_resize_scaled_xy()`	`include/datoviz/app.h`
`dvz_view_resolved_size()`	`include/datoviz/app.h`
`dvz_view_set_frame_callback()`	`include/datoviz/app.h`
`dvz_view_set_gui_callback()`	`include/datoviz/gui.h`
`dvz_view_set_render_enabled()`	`include/datoviz/app.h`
`dvz_view_set_request_frame_callback()`	`include/datoviz/app.h`
`dvz_view_set_user_scale()`	`include/datoviz/app.h`
`dvz_view_size()`	`include/datoviz/app.h`
`dvz_view_size_desc_framebuffer_px()`	`include/datoviz/app.h`
`dvz_view_size_desc_host_logical_px()`	`include/datoviz/app.h`
`dvz_view_size_desc_physical_mm()`	`include/datoviz/app.h`
`dvz_view_size_desc_reference_px()`	`include/datoviz/app.h`
`dvz_view_size_resolve()`	`include/datoviz/app.h`
`dvz_view_turntable()`	`include/datoviz/app.h`
`dvz_view_update_external_surface()`	`include/datoviz/app_interop.h`
`dvz_view_user_scale()`	`include/datoviz/app.h`
`dvz_view_wake()`	`include/datoviz/app.h`
`dvz_view_window()`	`include/datoviz/app.h`

Window Hosting

Function	Header
`dvz_window_backend_emit_resize()`	`include/datoviz/window/backend.h`
`dvz_window_backend_emit_scale()`	`include/datoviz/window/backend.h`
`dvz_window_backend_handle()`	`include/datoviz/window/backend.h`
`dvz_window_backend_payload()`	`include/datoviz/window/backend.h`
`dvz_window_backend_router()`	`include/datoviz/window/backend.h`
`dvz_window_backend_set_handle()`	`include/datoviz/window/backend.h`
`dvz_window_backend_set_payload()`	`include/datoviz/window/backend.h`
`dvz_window_backend_surface()`	`include/datoviz/window/backend.h`
`dvz_window_backend_type()`	`include/datoviz/window.h`
`dvz_window_config()`	`include/datoviz/window.h`
`dvz_window_create()`	`include/datoviz/window.h`
`dvz_window_destroy()`	`include/datoviz/window.h`
`dvz_window_external_surface_info()`	`include/datoviz/window/backend.h`
`dvz_window_frame_pending()`	`include/datoviz/window.h`
`dvz_window_glfw_init()`	`include/datoviz/window/backend.h`
`dvz_window_glfw_set_input_callbacks()`	`include/datoviz/window/backend.h`
`dvz_window_host()`	`include/datoviz/window.h`
`dvz_window_host_destroy()`	`include/datoviz/window.h`
`dvz_window_host_poll()`	`include/datoviz/window.h`
`dvz_window_host_register_backend()`	`include/datoviz/window.h`
`dvz_window_host_request_frame()`	`include/datoviz/window.h`
`dvz_window_host_required_extension_count()`	`include/datoviz/window/backend.h`
`dvz_window_host_required_extensions()`	`include/datoviz/window/backend.h`
`dvz_window_host_wait()`	`include/datoviz/window.h`
`dvz_window_host_wait_timeout()`	`include/datoviz/window.h`
`dvz_window_metrics()`	`include/datoviz/window.h`
`dvz_window_register_glfw_backend()`	`include/datoviz/window/backend.h`
`dvz_window_register_headless_backend()`	`include/datoviz/window/backend.h`
`dvz_window_register_wrap_backend()`	`include/datoviz/window/backend.h`
`dvz_window_router()`	`include/datoviz/window.h`
`dvz_window_set_user_data()`	`include/datoviz/window.h`
`dvz_window_should_close()`	`include/datoviz/window.h`
`dvz_window_surface()`	`include/datoviz/window.h`
`dvz_window_user_data()`	`include/datoviz/window.h`
`dvz_window_wrap_attach_surface()`	`include/datoviz/window/backend.h`
`dvz_window_wrap_detach_surface()`	`include/datoviz/window/backend.h`
`dvz_window_wrap_set_required_extensions()`	`include/datoviz/window/backend.h`
`dvz_window_wrap_update_surface()`	`include/datoviz/window/backend.h`

Application Lifecycle¶

Functions

`dvz_app()`¶

Create an app bound to a scene.

Allocates a GPU context, a DRP2 runtime, and a window host. Returns NULL when no suitable GPU is available.

DvzApp * dvz_app(
    DvzScene * scene
);

Field	Type	Description
return	`DvzApp` *	the app, or NULL on failure
`scene`	`DvzScene` *	the scene (borrowed — must outlive the app)

Declared in include/datoviz/app.h:295.

`dvz_app_capture_config()`¶

Return the default app capture configuration.

The returned config enables no capture by default. When enabled, outputs are written in the current directory with basename "capture" at 60 FPS using the automatic video backend.

DvzAppCaptureConfig dvz_app_capture_config(void);

Field	Type	Description
return	`DvzAppCaptureConfig`	the default capture configuration

Declared in include/datoviz/app.h:799.

`dvz_app_capture_config_from_env()`¶

Return an app capture configuration derived from environment variables.

DVZ_CAPTURE accepts comma-, semicolon-, plus-, colon-, pipe-, or space-separated tokens: dvzr, mp4/video, png, all, or false-like values (0, false, off, none). Optional overrides are DVZ_CAPTURE_DIR, DVZ_CAPTURE_BASENAME, DVZ_CAPTURE_FPS, DVZ_CAPTURE_VIDEO_BACKEND, and DVZ_CAPTURE_VIDEO_MODE (auto, external, cpu).

DvzAppCaptureConfig dvz_app_capture_config_from_env(
    const char * basename
);

Field	Type	Description
return	`DvzAppCaptureConfig`	the environment-derived capture configuration
`basename`	`const` `char` *	fallback output basename, or NULL for "capture"

Declared in include/datoviz/app.h:813.

`dvz_app_config()`¶

Return the default app configuration.

DvzAppConfig dvz_app_config(void);

Field	Type	Description
return	`DvzAppConfig`	the default app configuration

Declared in include/datoviz/app.h:276.

`dvz_app_destroy()`¶

Destroy the app and all owned resources (canvases, windows, runtime, GPU context).

The scene supplied at creation is borrowed and is not destroyed.

void dvz_app_destroy(
    DvzApp * app
);

Field	Type	Description
`app`	`DvzApp` *	the owned app to destroy, or NULL

Declared in include/datoviz/app.h:336.

`dvz_app_reap_closed_views()`¶

Destroy native windows that have received a close request.

Hosted integrations should call this after polling the window host and observing dvz_app_should_exit(app). The function runs the same per-view close cleanup used by dvz_app_run(app, 0).

_Bool dvz_app_reap_closed_views(
    DvzApp * app
);

Field	Type	Description
return	`_Bool`	whether any views were reaped
`app`	`DvzApp` *	app to inspect

Declared in include/datoviz/app.h:381.

`dvz_app_render_once()`¶

Render one frame for every view without polling any Datoviz-owned event loop.

int dvz_app_render_once(
    DvzApp * app
);

Field	Type	Description
return	`int`	0 on success, DVZ_CANVAS_FRAME_WAIT_SURFACE if any surface is unavailable, or negative on error
`app`	`DvzApp` *	the app

Declared in include/datoviz/app.h:1119.

`dvz_app_resources()`¶

Return an empty app resource bundle.

DvzAppResources dvz_app_resources(void);

Field	Type	Description
return	`DvzAppResources`	the empty app resources bundle

Declared in include/datoviz/app.h:283.

`dvz_app_run()`¶

Run the frame loop.

Finite runs render the requested number of frames. Interactive runs (frame_count == 0) use the app scheduler: on-demand mode waits for resize/input/request-frame invalidation, while continuous mode renders active windows until the configured exit policy or dvz_app_stop() stops the loop.

void dvz_app_run(
    DvzApp * app,
    uint32_t frame_count
);

Field	Type	Description
`app`	`DvzApp` *	the app
`frame_count`	`uint32_t`	number of frames to render (0 = interactive loop)

Declared in include/datoviz/app.h:1133.

`dvz_app_should_exit()`¶

Return whether the app's interactive loop should exit.

Hosted integrations that drive the app with dvz_app_render_once() should poll their window host, call this function, reap closed views with dvz_app_reap_closed_views() when it returns true, and destroy or replace the hosted app. This mirrors the exit-policy check used by dvz_app_run(app, 0).

_Bool dvz_app_should_exit(
    DvzApp * app
);

Field	Type	Description
return	`_Bool`	whether the app should exit according to stop requests and window-close policy
`app`	`DvzApp` *	app to inspect

Declared in include/datoviz/app.h:368.

`dvz_app_should_stop()`¶

Return whether an app stop has been requested.

_Bool dvz_app_should_stop(
    const DvzApp * app
);

Field	Type	Description
return	`_Bool`	whether dvz_app_stop() has been called
`app`	`const` `DvzApp` *	app to inspect

Declared in include/datoviz/app.h:354.

`dvz_app_stop()`¶

Request that a running app loop stops at the next scheduler checkpoint.

DvzResult dvz_app_stop(
    DvzApp * app
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`app`	`DvzApp` *	app whose run loop should stop

Declared in include/datoviz/app.h:345.

`dvz_app_vk_instance()`¶

Return the Vulkan instance owned by the app.

Hosted integrations use this borrowed handle to create their native VkSurfaceKHR after passing required instance extensions to dvz_app_with_config().

VkInstance dvz_app_vk_instance(
    DvzApp * app
);

Field	Type	Description
return	`VkInstance`	borrowed Vulkan instance handle, or VK_NULL_HANDLE when unavailable
`app`	`DvzApp` *	the app

Declared in include/datoviz/app_interop.h:41.

`dvz_app_with_config()`¶

Create an app bound to a scene with explicit host integration requirements.

Use this entry point when an external UI toolkit owns the native window and requires Vulkan instance extensions before Datoviz creates its GPU context.

DvzApp * dvz_app_with_config(
    DvzScene * scene,
    const DvzAppConfig * config
);

Field	Type	Description
return	`DvzApp` *	the app, or NULL on failure
`scene`	`DvzScene` *	the scene (borrowed — must outlive the app)
`config`	`const` `DvzAppConfig` *	optional app configuration, or NULL for dvz_app_config()

Declared in include/datoviz/app.h:308.

`dvz_app_with_resources()`¶

Create an app bound to a scene with optional caller-provided host resources.

NULL resources make the app allocate the same stack as dvz_app_with_config(). Individual NULL fields are created and owned by the app. Non-NULL fields are borrowed exclusively for the app lifetime and must outlive the app. When a runtime is provided, a GPU context must also be provided, and the runtime must have been created from that GPU context's device and allocator. App config instance-extension fields only affect app-created GPU contexts.

DvzApp * dvz_app_with_resources(
    DvzScene * scene,
    const DvzAppConfig * config,
    const DvzAppResources * resources
);

Field	Type	Description
return	`DvzApp` *	the app, or NULL on failure
`scene`	`DvzScene` *	the scene (borrowed — must outlive the app)
`config`	`const` `DvzAppConfig` *	optional app configuration, or NULL for dvz_app_config()
`resources`	`const` `DvzAppResources` *	optional borrowed resource bundle

Declared in include/datoviz/app.h:325.

Types

DvzApp · typedef

typedef struct DvzApp DvzApp;

Declared in include/datoviz/app.h:37.

DvzAppCaptureConfig · record

struct DvzAppCaptureConfig {
    uint32_t struct_size;
    uint32_t flags;
    const char * directory;
    const char * basename;
    double fps;
    const char * video_backend;
    DvzVideoCaptureMode video_capture_mode;
};

Declared in include/datoviz/app.h:160.

DvzAppCaptureFlags · enum

enum DvzAppCaptureFlags {
    DVZ_APP_CAPTURE_NONE = 0,
    DVZ_APP_CAPTURE_DVZR = 1,
    DVZ_APP_CAPTURE_VIDEO = 2,
    DVZ_APP_CAPTURE_PNG = 4,
};

Declared in include/datoviz/app.h:83.

DvzAppConfig · record

struct DvzAppConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t instance_extension_count;
    const char *const * instance_extensions;
    _Bool enable_canvas_extensions;
    _Bool enable_glfw_extensions;
    DvzAppScheduleMode schedule_mode;
    DvzAppExitPolicy exit_policy;
    double fps_cap;
    const char * font_sans_path;
    const char * font_sans_family;
    const char * font_sans_style;
    uint32_t font_sans_face_index;
    uint32_t font_sans_font_flags;
    const char * font_mono_path;
    const char * font_mono_family;
    const char * font_mono_style;
    uint32_t font_mono_face_index;
    uint32_t font_mono_font_flags;
    float font_ui_size_px;
    float font_mono_size_px;
    float font_text_size_px;
};

Declared in include/datoviz/app.h:133.

DvzAppExitPolicy · enum

enum DvzAppExitPolicy {
    DVZ_APP_EXIT_WHEN_ALL_WINDOWS_CLOSED = 0,
    DVZ_APP_EXIT_WHEN_ANY_WINDOW_CLOSED = 1,
    DVZ_APP_EXIT_NEVER = 2,
};

Declared in include/datoviz/app.h:75.

DvzAppFlags · enum

enum DvzAppFlags {
    DVZ_APP_FLAGS_NONE = 0,
    DVZ_APP_FLAGS_OFFSCREEN = 32768,
    DVZ_APP_FLAGS_EXTERNAL = 524288,
    DVZ_APP_FLAGS_WHITE_BACKGROUND = 1048576,
};

Declared in include/datoviz/runner/enums.h:32.

DvzAppResources · record

struct DvzAppResources {
    uint32_t struct_size;
    uint32_t flags;
    DvzGpuCtx * gpu_ctx;
    DvzDrp2Runtime * runtime;
    DvzWindowHost * window_host;
};

Declared in include/datoviz/app.h:172.

DvzAppScheduleMode · enum

enum DvzAppScheduleMode {
    DVZ_APP_SCHEDULE_ON_DEMAND = 0,
    DVZ_APP_SCHEDULE_CONTINUOUS = 1,
};

Declared in include/datoviz/app.h:68.

Canvas Execution¶

Functions

`dvz_canvas_capture_png()`¶

Capture the latest presented canvas frame and write it to a PNG file.

PNG capture uses the same screenshot/export contract as dvz_canvas_capture_rgba(): sRGB-encoded RGBA8 color with straight linear alpha.

int dvz_canvas_capture_png(
    DvzCanvas * canvas,
    const char * path
);

Field	Type	Description
return	`int`	0 on success or a negative error code
`canvas`	`DvzCanvas` *	canvas handle
`path`	`const` `char` *	output file path

Declared in include/datoviz/canvas.h:311.

`dvz_canvas_capture_rgba()`¶

Capture the latest presented canvas frame into a newly allocated RGBA buffer.

The returned pixels are screenshot/export pixels: tightly packed RGBA8 with sRGB-encoded RGB channels and straight linear alpha. Use a dedicated query/readback API for scientific values that must remain in linear float or data space.

int dvz_canvas_capture_rgba(
    DvzCanvas * canvas,
    uint32_t * out_width,
    uint32_t * out_height,
    uint8_t ** out_rgba
);

Field	Type	Description
return	`int`	0 on success or a negative error code
`canvas`	`DvzCanvas` *	canvas handle
`out_width`	`uint32_t` *	destination width in pixels
`out_height`	`uint32_t` *	destination height in pixels
`out_rgba`	`uint8_t` **	destination pointer receiving an allocated sRGB RGBA8 buffer

Declared in include/datoviz/canvas.h:296.

`dvz_canvas_capture_rgba_into()`¶

Capture the latest presented canvas frame into a caller-provided RGBA buffer.

The returned pixels are screenshot/export pixels: tightly packed RGBA8 with sRGB-encoded RGB channels and straight linear alpha. Use a dedicated query/readback API for scientific values that must remain in linear float or data space.

int dvz_canvas_capture_rgba_into(
    DvzCanvas * canvas,
    uint32_t width,
    uint32_t height,
    uint8_t * out_rgba,
    DvzSize out_size_bytes
);

Field	Type	Description
return	`int`	0 on success or a negative error code
`canvas`	`DvzCanvas` *	canvas handle
`width`	`uint32_t`	expected frame width in pixels
`height`	`uint32_t`	expected frame height in pixels
`out_rgba`	`uint8_t` *	destination buffer receiving sRGB RGBA8 pixels
`out_size_bytes`	`DvzSize`	size of `out_rgba` in bytes

Declared in include/datoviz/canvas.h:275.

`dvz_canvas_config()`¶

Return a default canvas configuration used when callers do not override fields.

The caller must set the borrowed window and device fields before creating a canvas. The returned configuration selects present rendering, FIFO presentation, the runtime default color format, and DVZ_CANVAS_DEFAULT_TIMING_HISTORY timing samples.

DvzCanvasConfig dvz_canvas_config(void);

Field	Type	Description
return	`DvzCanvasConfig`	the initialized configuration

Related: dvz_canvas_create().

Declared in include/datoviz/canvas.h:148.

`dvz_canvas_configure_live_image_sink()`¶

Enable or disable the live-image sink attached to the canvas stream.

int dvz_canvas_configure_live_image_sink(
    DvzCanvas * canvas,
    _Bool enable,
    const DvzCanvasLiveImageSinkConfig * cfg
);

Field	Type	Description
return	`int`	0 on success or a negative sink error
`canvas`	`DvzCanvas` *	canvas owning the stream
`enable`	`_Bool`	true to enable, false to detach the sink
`cfg`	`const` `DvzCanvasLiveImageSinkConfig` *	required configuration when enabling, ignored when disabling

Declared in include/datoviz/canvas.h:338.

`dvz_canvas_configure_video_sink()`¶

Enable or disable the video sink attached to the canvas stream.

int dvz_canvas_configure_video_sink(
    DvzCanvas * canvas,
    _Bool enable,
    const DvzVideoSinkConfig * cfg
);

Field	Type	Description
return	`int`	0 on success or a negative sink error
`canvas`	`DvzCanvas` *	canvas owning the stream
`enable`	`_Bool`	true to enable, false to detach an existing sink
`cfg`	`const` `DvzVideoSinkConfig` *	optional configuration passed to the sink (NULL uses defaults)

Declared in include/datoviz/canvas.h:325.

`dvz_canvas_create()`¶

Allocate a new canvas tied to a window surface and device.

cfg->window and cfg->device are required borrowed objects and must outlive the canvas. The canvas copies the configuration and owns the stream, allocator, synchronization, and render resources it creates; it does not destroy the window or device.

DvzCanvas * dvz_canvas_create(
    const DvzCanvasConfig * cfg
);

Field	Type	Description
return	`DvzCanvas` *	a newly allocated canvas, or NULL when the configuration or runtime setup is invalid
`cfg`	`const` `DvzCanvasConfig` *	required canvas configuration with non-NULL `window` and `device`

Related: dvz_canvas_destroy().

Declared in include/datoviz/canvas.h:170.

`dvz_canvas_destroy()`¶

Destroy the canvas and any stream resources it owns.

void dvz_canvas_destroy(
    DvzCanvas * canvas
);

Field	Type	Description
`canvas`	`DvzCanvas` *	canvas returned by dvz_canvas_create(), or NULL

Related: dvz_canvas_create().

Declared in include/datoviz/canvas.h:179.

`dvz_canvas_frame()`¶

Acquire a new frame, refresh swapchain-backed metadata, and run the draw callback.

int dvz_canvas_frame(
    DvzCanvas * canvas
);

Field	Type	Description
return	`int`	DVZ_CANVAS_FRAME_READY when a frame is ready, DVZ_CANVAS_FRAME_WAIT_SURFACE when the surface is unavailable, or a negative error code when acquisition fails
`canvas`	`DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:206.

`dvz_canvas_input()`¶

Expose the input router owned by the canvas window.

DvzInputRouter * dvz_canvas_input(
    DvzCanvas * canvas
);

Field	Type	Description
return	`DvzInputRouter` *	the borrowed router, valid until the canvas window is destroyed, or NULL when absent
`canvas`	`DvzCanvas` *	canvas owning the router

Declared in include/datoviz/canvas.h:257.

`dvz_canvas_live_image_sink_config()`¶

Return a default live-image sink configuration.

DvzCanvasLiveImageSinkConfig dvz_canvas_live_image_sink_config(void);

Field	Type	Description
return	`DvzCanvasLiveImageSinkConfig`	a configuration with no callback or user data

Declared in include/datoviz/canvas.h:156.

`dvz_canvas_offscreen_runtime_state()`¶

Return the offscreen-mode runtime state for diagnostics.

DvzCanvasOffscreenRuntimeState dvz_canvas_offscreen_runtime_state(
    const DvzCanvas * canvas
);

Field	Type	Description
return	`DvzCanvasOffscreenRuntimeState`	offscreen runtime state, or UNINITIALIZED when unavailable
`canvas`	`const` `DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:247.

`dvz_canvas_present_runtime_state()`¶

Return the present-mode runtime state for diagnostics.

DvzCanvasPresentRuntimeState dvz_canvas_present_runtime_state(
    const DvzCanvas * canvas
);

Field	Type	Description
return	`DvzCanvasPresentRuntimeState`	present runtime state, or UNINITIALIZED when unavailable
`canvas`	`const` `DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:236.

`dvz_canvas_render_mode()`¶

Return the configured render mode for a canvas.

DvzCanvasRenderMode dvz_canvas_render_mode(
    const DvzCanvas * canvas
);

Field	Type	Description
return	`DvzCanvasRenderMode`	render mode currently used by the canvas
`canvas`	`const` `DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:226.

`dvz_canvas_set_draw_callback()`¶

Register a draw callback executed before each successful dvz_canvas_frame() returns.

The callback and user_data are borrowed and must remain valid until replaced, cleared, or the canvas is destroyed. The callback receives a borrowed frame whose Vulkan handles are valid only for that invocation and must not be destroyed, reset, submitted, transitioned, or retained.

void dvz_canvas_set_draw_callback(
    DvzCanvas * canvas,
    DvzCanvasDraw callback,
    void * user_data
);

Field	Type	Description
`canvas`	`DvzCanvas` *	target canvas
`callback`	`DvzCanvasDraw`	draw callback (NULL removes the callback)
`user_data`	`void` *	borrowed opaque pointer supplied to the callback on every invocation

Declared in include/datoviz/canvas.h:195.

`dvz_canvas_stream()`¶

Access the stream underpinning the canvas.

The caller must not destroy the returned stream. It remains valid until the canvas is destroyed or reconfiguring a sink rebuilds the canvas stream.

DvzStream * dvz_canvas_stream(
    DvzCanvas * canvas
);

Field	Type	Description
return	`DvzStream` *	the borrowed underlying stream, or NULL when unavailable
`canvas`	`DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:352.

`dvz_canvas_submit()`¶

Submit the current frame to the internal stream and attached sinks.

int dvz_canvas_submit(
    DvzCanvas * canvas
);

Field	Type	Description
return	`int`	0 when submission succeeds, <0 when the stream submission fails
`canvas`	`DvzCanvas` *	canvas handle

Declared in include/datoviz/canvas.h:216.

`dvz_canvas_timings()`¶

Read the recorded frame timings.

The returned view is owned by the canvas and may be invalidated or overwritten by subsequent frame submissions. It must not be freed and remains valid at most until canvas destruction.

const DvzFrameTiming * dvz_canvas_timings(
    const DvzCanvas * canvas,
    size_t * count
);

Field	Type	Description
return	`const` `DvzFrameTiming` *	the borrowed internal timing buffer, or NULL when no samples are available
`canvas`	`const` `DvzCanvas` *	canvas handle
`count`	`size_t` *	optional output receiving the number of readable samples

Declared in include/datoviz/canvas.h:366.

Types

DvzCanvas · typedef

typedef struct DvzCanvas DvzCanvas;

Declared in include/datoviz/canvas.h:40.

DvzCanvasConfig · record

struct DvzCanvasConfig {
    uint32_t struct_size;
    uint32_t flags;
    DvzWindow * window;
    DvzDevice * device;
    DvzCanvasRenderMode render_mode;
    VkFormat color_format;
    VkPresentModeKHR present_mode;
    _Bool enable_video_sink;
    size_t timing_history;
};

Declared in include/datoviz/canvas.h:59.

DvzCanvasDraw · typedef

typedef void (*)(DvzCanvas *, const DvzStreamFrame *, void *) DvzCanvasDraw;

Declared in include/datoviz/canvas.h:129.

DvzCanvasFlags · enum

enum DvzCanvasFlags {
    DVZ_CANVAS_FLAGS_NONE = 0,
    DVZ_CANVAS_FLAGS_IMGUI = 1,
    DVZ_CANVAS_FLAGS_FPS = 2,
    DVZ_CANVAS_FLAGS_MONITOR = 4,
    DVZ_CANVAS_FLAGS_FULLSCREEN = 8,
    DVZ_CANVAS_FLAGS_VSYNC = 16,
    DVZ_CANVAS_FLAGS_PICK = 32,
    DVZ_CANVAS_FLAGS_PUSH_SCALE = 64,
};

Declared in include/datoviz/canvas/enums.h:20.

DvzCanvasFrameStatus · enum

enum DvzCanvasFrameStatus {
    DVZ_CANVAS_FRAME_READY = 0,
    DVZ_CANVAS_FRAME_WAIT_SURFACE = 1,
};

Declared in include/datoviz/canvas/enums.h:35.

DvzCanvasLiveImageCallback · typedef

typedef int (*)(const DvzCanvasLiveImageFrame *, void *) DvzCanvasLiveImageCallback;

Declared in include/datoviz/canvas.h:113.

DvzCanvasLiveImageFrame · record

struct DvzCanvasLiveImageFrame {
    uint64_t frame_id;
    uint64_t wait_value;
    VkFormat color_format;
    VkImage image;
    VkImageView image_view;
    VkCommandBuffer command_buffer;
    VkExtent2D extent;
    _Bool handles_dirty;
    uint64_t resource_generation;
    _Bool image_valid;
    int memory_fd;
    int wait_semaphore_fd;
};

Declared in include/datoviz/canvas.h:95.

DvzCanvasLiveImageSinkConfig · record

struct DvzCanvasLiveImageSinkConfig {
    uint32_t struct_size;
    uint32_t flags;
    DvzCanvasLiveImageCallback callback;
    void * user_data;
};

Declared in include/datoviz/canvas.h:119.

DvzCanvasOffscreenRuntimeState · enum

enum DvzCanvasOffscreenRuntimeState {
    DVZ_CANVAS_OFFSCREEN_STATE_UNINITIALIZED = 0,
    DVZ_CANVAS_OFFSCREEN_STATE_READY = 1,
    DVZ_CANVAS_OFFSCREEN_STATE_DRAW_PENDING = 2,
    DVZ_CANVAS_OFFSCREEN_STATE_OUTPUT_PENDING = 3,
    DVZ_CANVAS_OFFSCREEN_STATE_FATAL_DEVICE_LOST = 4,
};

Declared in include/datoviz/canvas/enums.h:66.

DvzCanvasPresentRuntimeState · enum

enum DvzCanvasPresentRuntimeState {
    DVZ_CANVAS_PRESENT_STATE_UNINITIALIZED = 0,
    DVZ_CANVAS_PRESENT_STATE_WAIT_SURFACE = 1,
    DVZ_CANVAS_PRESENT_STATE_READY = 2,
    DVZ_CANVAS_PRESENT_STATE_ACQUIRED = 3,
    DVZ_CANVAS_PRESENT_STATE_PRESENT_PENDING = 4,
    DVZ_CANVAS_PRESENT_STATE_FATAL_DEVICE_LOST = 5,
};

Declared in include/datoviz/canvas/enums.h:53.

DvzCanvasRenderMode · enum

enum DvzCanvasRenderMode {
    DVZ_CANVAS_RENDER_MODE_PRESENT = 0,
    DVZ_CANVAS_RENDER_MODE_OFFSCREEN = 1,
};

Declared in include/datoviz/canvas/enums.h:44.

DvzFrameTiming · record

struct DvzFrameTiming {
    uint64_t frame_id;
    double cpu_submit_us;
    double gpu_complete_us;
    double present_start_us;
    double present_done_us;
};

Declared in include/datoviz/canvas.h:75.

Display Sizing¶

Types

DvzExtent · record

struct DvzExtent {
    uint32_t width;
    uint32_t height;
};

Declared in include/datoviz/window/size.h:50.

DvzPhysicalMetricsSource · enum

enum DvzPhysicalMetricsSource {
    DVZ_PHYSICAL_METRICS_NONE = 0,
    DVZ_PHYSICAL_METRICS_MONITOR_EDID = 1,
    DVZ_PHYSICAL_METRICS_GLFW_MONITOR_SIZE = 2,
    DVZ_PHYSICAL_METRICS_PLATFORM_API = 3,
    DVZ_PHYSICAL_METRICS_USER_OVERRIDE = 4,
    DVZ_PHYSICAL_METRICS_ESTIMATED = 5,
};

Declared in include/datoviz/app.h:109.

DvzResolvedExactness · enum

enum DvzResolvedExactness {
    DVZ_RESOLVED_EXACT = 0,
    DVZ_RESOLVED_APPROXIMATE = 1,
    DVZ_RESOLVED_UNKNOWN = 2,
};

Declared in include/datoviz/app.h:120.

DvzResolvedViewSize · record

struct DvzResolvedViewSize {
    uint32_t struct_size;
    uint32_t flags;
    DvzViewSizePolicy requested_policy;
    double requested_width;
    double requested_height;
    double reference_dpi;
    double canvas_width_px;
    double canvas_height_px;
    uint32_t host_logical_width;
    uint32_t host_logical_height;
    uint32_t framebuffer_width;
    uint32_t framebuffer_height;
    double device_scale_x;
    double device_scale_y;
    double canvas_to_host_scale_x;
    double canvas_to_host_scale_y;
    double framebuffer_per_canvas_px_x;
    double framebuffer_per_canvas_px_y;
    double target_width_mm;
    double target_height_mm;
    double estimated_width_mm;
    double estimated_height_mm;
    DvzPhysicalMetricsSource physical_metrics_source;
    DvzResolvedExactness exactness;
};

Declared in include/datoviz/app.h:203.

DvzScaleXY · record

struct DvzScaleXY {
    float x;
    float y;
};

Declared in include/datoviz/window/size.h:58.

DvzSizeSpace · enum

enum DvzSizeSpace {
    DVZ_SIZE_LOGICAL = 0,
    DVZ_SIZE_NATIVE = 1,
    DVZ_SIZE_SURFACE = 2,
    DVZ_SIZE_RENDER = 3,
};

Declared in include/datoviz/window/size.h:36.

GUI¶

Functions

`dvz_gui_begin()`¶

Start an ImGui window.

_Bool dvz_gui_begin(
    DvzGui * gui,
    const char * title,
    _Bool * open,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the window body is visible
`gui`	`DvzGui` *	the GUI overlay
`title`	`const` `char` *	the window title
`open`	`_Bool` *	optional open flag, or NULL
`flags`	`int`	Dear ImGui window flags

Declared in include/datoviz/gui.h:177.

`dvz_gui_button()`¶

Show a button.

_Bool dvz_gui_button(
    DvzGui * gui,
    const char * label
);

Field	Type	Description
return	`_Bool`	whether the button was pressed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	button label

Declared in include/datoviz/gui.h:268.

`dvz_gui_checkbox()`¶

Show a checkbox.

_Bool dvz_gui_checkbox(
    DvzGui * gui,
    const char * label,
    _Bool * value
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	checkbox label
`value`	`_Bool` *	value edited in place

Declared in include/datoviz/gui.h:280.

`dvz_gui_collapsing_header()`¶

Show a collapsible section header.

_Bool dvz_gui_collapsing_header(
    DvzGui * gui,
    const char * label,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the section is open
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	section label
`flags`	`int`	Dear ImGui tree node flags

Declared in include/datoviz/gui.h:482.

`dvz_gui_color_edit4()`¶

Show an RGBA color editor using float channels in [0, 1].

_Bool dvz_gui_color_edit4(
    DvzGui * gui,
    const char * label,
    float[4] rgba,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	color label
`rgba`	`float`[4]	RGBA channels edited in place
`flags`	`int`	Dear ImGui color edit flags

Declared in include/datoviz/gui.h:434.

`dvz_gui_color_edit_dvz()`¶

Show an RGBA color editor using a DvzColor value.

_Bool dvz_gui_color_edit_dvz(
    DvzGui * gui,
    const char * label,
    DvzColor * color,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	color label
`color`	`DvzColor` *	color edited in place
`flags`	`int`	Dear ImGui color edit flags

Declared in include/datoviz/gui.h:447.

`dvz_gui_color_picker4()`¶

Show an RGBA color picker using float channels in [0, 1].

_Bool dvz_gui_color_picker4(
    DvzGui * gui,
    const char * label,
    float[4] rgba,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	color label
`rgba`	`float`[4]	RGBA channels edited in place
`flags`	`int`	Dear ImGui color edit flags

Declared in include/datoviz/gui.h:460.

`dvz_gui_combo()`¶

Show a dropdown combo.

_Bool dvz_gui_combo(
    DvzGui * gui,
    const char * label,
    int * current_item,
    const char *const * items,
    int item_count
);

Field	Type	Description
return	`_Bool`	whether the selection changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	combo label
`current_item`	`int` *	selected item index edited in place
`items`	`const` `char` `const`	item labels
`item_count`	`int`	number of item labels

Declared in include/datoviz/gui.h:293.

`dvz_gui_config()`¶

Return the default GUI overlay configuration.

DvzGuiConfig dvz_gui_config(void);

Field	Type	Description
return	`DvzGuiConfig`	default GUI configuration

Declared in include/datoviz/gui.h:125.

`dvz_gui_current_window_docked()`¶

Return whether the current ImGui window is docked.

Call between dvz_gui_begin() and dvz_gui_end().

_Bool dvz_gui_current_window_docked(
    DvzGui * gui
);

Field	Type	Description
return	`_Bool`	whether the current ImGui window is docked
`gui`	`DvzGui` *	the GUI overlay

Declared in include/datoviz/gui.h:206.

`dvz_gui_current_window_rect()`¶

Return the current ImGui window rectangle in host-window logical pixels.

Call between dvz_gui_begin() and dvz_gui_end().

_Bool dvz_gui_current_window_rect(
    DvzGui * gui,
    DvzRect * out
);

Field	Type	Description
return	`_Bool`	whether the rectangle was written
`gui`	`DvzGui` *	the GUI overlay
`out`	`DvzRect` *	output rectangle

Declared in include/datoviz/gui.h:219.

`dvz_gui_demo()`¶

Show Dear ImGui's demo window.

void dvz_gui_demo(
    DvzGui * gui,
    _Bool * open
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay
`open`	`_Bool` *	optional open flag, or NULL

Declared in include/datoviz/gui.h:503.

`dvz_gui_dock_window_once()`¶

Dock an ImGui window into the default full-view dockspace the first time it is shown.

Call before dvz_gui_begin() with the same title. The request is applied only once per title, so user-driven docking changes are not overwritten on later frames.

DvzResult dvz_gui_dock_window_once(
    DvzGui * gui,
    const char * title,
    DvzGuiDockSlot slot,
    float size_px
);

Field	Type	Description
return	`DvzResult`	DVZ_OK if the request was accepted, DVZ_ERROR otherwise
`gui`	`DvzGui` *	the GUI overlay
`title`	`const` `char` *	the window title
`slot`	`DvzGuiDockSlot`	side of the full-view dockspace
`size_px`	`float`	initial docked size in logical pixels along the split axis, or 0 for default

Declared in include/datoviz/gui.h:194.

`dvz_gui_end()`¶

End the current ImGui window.

void dvz_gui_end(
    DvzGui * gui
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay

Declared in include/datoviz/gui.h:228.

`dvz_gui_pop_font()`¶

Pop the current ImGui font.

void dvz_gui_pop_font(
    DvzGui * gui
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay

Declared in include/datoviz/gui.h:257.

`dvz_gui_push_mono()`¶

Push the default monospace ImGui font.

_Bool dvz_gui_push_mono(
    DvzGui * gui
);

Field	Type	Description
return	`_Bool`	whether the monospace font was available and pushed
`gui`	`DvzGui` *	the GUI overlay

Declared in include/datoviz/gui.h:248.

`dvz_gui_range_float()`¶

Show a float min/max range editor.

_Bool dvz_gui_range_float(
    DvzGui * gui,
    const char * label,
    float * current_min,
    float * current_max,
    float speed,
    float min,
    float max,
    const char * format
);

Field	Type	Description
return	`_Bool`	whether either value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	range label
`current_min`	`float` *	minimum value edited in place
`current_max`	`float` *	maximum value edited in place
`speed`	`float`	drag speed
`min`	`float`	lower clamp value
`max`	`float`	upper clamp value
`format`	`const` `char` *	printf-style value format

Declared in include/datoviz/gui.h:419.

`dvz_gui_same_line()`¶

Place the next item on the same line.

void dvz_gui_same_line(
    DvzGui * gui,
    float offset_from_start_x,
    float spacing
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay
`offset_from_start_x`	`float`	x offset from start, or 0
`spacing`	`float`	spacing between items, or -1 for default

Declared in include/datoviz/gui.h:493.

`dvz_gui_separator_text()`¶

Show a labeled separator.

void dvz_gui_separator_text(
    DvzGui * gui,
    const char * label
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	separator label

Declared in include/datoviz/gui.h:470.

`dvz_gui_slider_float()`¶

Show a float slider.

_Bool dvz_gui_slider_float(
    DvzGui * gui,
    const char * label,
    float * value,
    float min,
    float max
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`float` *	value edited in place
`min`	`float`	minimum value
`max`	`float`	maximum value

Declared in include/datoviz/gui.h:309.

`dvz_gui_slider_float2()`¶

Show a two-component float slider.

_Bool dvz_gui_slider_float2(
    DvzGui * gui,
    const char * label,
    float[2] value,
    float min,
    float max
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`float`[2]	two values edited in place
`min`	`float`	minimum value
`max`	`float`	maximum value

Declared in include/datoviz/gui.h:338.

`dvz_gui_slider_float3()`¶

Show a three-component float slider.

_Bool dvz_gui_slider_float3(
    DvzGui * gui,
    const char * label,
    float[3] value,
    float min,
    float max
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`float`[3]	three values edited in place
`min`	`float`	minimum value
`max`	`float`	maximum value

Declared in include/datoviz/gui.h:353.

`dvz_gui_slider_float4()`¶

Show a four-component float slider.

_Bool dvz_gui_slider_float4(
    DvzGui * gui,
    const char * label,
    float[4] value,
    float min,
    float max
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`float`[4]	four values edited in place
`min`	`float`	minimum value
`max`	`float`	maximum value

Declared in include/datoviz/gui.h:368.

`dvz_gui_slider_float_format()`¶

Show a float slider with an explicit display format.

_Bool dvz_gui_slider_float_format(
    DvzGui * gui,
    const char * label,
    float * value,
    float min,
    float max,
    const char * format
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`float` *	value edited in place
`min`	`float`	minimum value
`max`	`float`	maximum value
`format`	`const` `char` *	printf-style value format

Declared in include/datoviz/gui.h:383.

`dvz_gui_slider_int()`¶

Show an integer slider.

_Bool dvz_gui_slider_int(
    DvzGui * gui,
    const char * label,
    int * value,
    int min,
    int max
);

Field	Type	Description
return	`_Bool`	whether the value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`value`	`int` *	value edited in place
`min`	`int`	minimum value
`max`	`int`	maximum value

Declared in include/datoviz/gui.h:323.

`dvz_gui_slider_range_float()`¶

Show a float range slider with two handles.

_Bool dvz_gui_slider_range_float(
    DvzGui * gui,
    const char * label,
    float * current_min,
    float * current_max,
    float min,
    float max,
    const char * format
);

Field	Type	Description
return	`_Bool`	whether either value changed
`gui`	`DvzGui` *	the GUI overlay
`label`	`const` `char` *	slider label
`current_min`	`float` *	minimum value edited in place
`current_max`	`float` *	maximum value edited in place
`min`	`float`	lower clamp value
`max`	`float`	upper clamp value
`format`	`const` `char` *	optional printf-style value format

Declared in include/datoviz/gui.h:400.

`dvz_gui_text()`¶

Show an unformatted text item.

void dvz_gui_text(
    DvzGui * gui,
    const char * text
);

Field	Type	Description
`gui`	`DvzGui` *	the GUI overlay
`text`	`const` `char` *	null-terminated text

Declared in include/datoviz/gui.h:238.

`dvz_gui_viewport()`¶

Create a dockable ImGui viewport that renders a figure into an owned offscreen window.

A GUI viewport is an ImGui-hosted Datoviz render target. It is not a scene DvzPanel. The supplied figure may contain any scene panels and visuals; the viewport creates and manages the offscreen view used to render that figure, then displays the latest source image in an ImGui window created by dvz_gui_viewport_window(). The GUI overlay and figure are borrowed and must outlive the returned viewport. Destroying the viewport disables its internally created source view but does not destroy the figure.

DvzGuiViewport * dvz_gui_viewport(
    DvzGui * gui,
    DvzFigure * figure,
    const DvzGuiViewportConfig * config
);

Field	Type	Description
return	`DvzGuiViewport` *	a newly allocated GUI viewport owned by the caller, or NULL on failure
`gui`	`DvzGui` *	the borrowed GUI overlay; must not be NULL
`figure`	`DvzFigure` *	the borrowed figure to render; must not be NULL
`config`	`const` `DvzGuiViewportConfig` *	optional viewport configuration borrowed for the call, or NULL for defaults

Declared in include/datoviz/gui.h:523.

`dvz_gui_viewport_config()`¶

Return the default dockable Datoviz GUI viewport configuration.

DvzGuiViewportConfig dvz_gui_viewport_config(void);

Field	Type	Description
return	`DvzGuiViewportConfig`	default GUI viewport configuration

Declared in include/datoviz/gui.h:134.

`dvz_gui_viewport_destroy()`¶

Destroy a dockable ImGui viewport.

An internally created source view is disabled; a caller-provided source view remains enabled. The associated GUI overlay, figure, and source view are not destroyed.

void dvz_gui_viewport_destroy(
    DvzGuiViewport * viewport
);

Field	Type	Description
`viewport`	`DvzGuiViewport` *	the owned GUI viewport to destroy, or NULL

Declared in include/datoviz/gui.h:583.

`dvz_gui_viewport_from_window()`¶

Create a dockable ImGui viewport from an existing offscreen view.

This is the advanced path for callers that already own the source view. Most users should prefer dvz_gui_viewport(), which creates the offscreen source from a figure. The source window must use offscreen canvas rendering. The GUI overlay and source view are borrowed and must outlive the returned viewport; destroying the viewport does not destroy or disable the source.

DvzGuiViewport * dvz_gui_viewport_from_window(
    DvzGui * gui,
    DvzView * source,
    const DvzGuiViewportConfig * config
);

Field	Type	Description
return	`DvzGuiViewport` *	a newly allocated GUI viewport owned by the caller, or NULL on failure
`gui`	`DvzGui` *	the borrowed GUI overlay; must not be NULL
`source`	`DvzView` *	the borrowed offscreen view providing the rendered image; must not be NULL
`config`	`const` `DvzGuiViewportConfig` *	optional viewport configuration borrowed for the call, or NULL for defaults

Declared in include/datoviz/gui.h:541.

`dvz_gui_viewport_input()`¶

Return the input router used by a GUI viewport's offscreen view.

Pass the returned router to dvz_panel_connect_input() to route input through scene panels rendered in the GUI viewport.

struct DvzInputRouter * dvz_gui_viewport_input(
    DvzGuiViewport * viewport
);

Field	Type	Description
return	`struct` `DvzInputRouter` *	the input router, or NULL
`viewport`	`DvzGuiViewport` *	the GUI viewport

Declared in include/datoviz/gui.h:555.

`dvz_gui_viewport_mouse()`¶

Return the last mouse position over a dockable GUI viewport image.

The position and size are in the viewport source window's logical coordinates. The returned state is refreshed by dvz_gui_viewport_window().

_Bool dvz_gui_viewport_mouse(
    DvzGuiViewport * viewport,
    float[2] out_pos,
    float[2] out_size,
    _Bool * out_hovered
);

Field	Type	Description
return	`_Bool`	whether viewport mouse state was available
`viewport`	`DvzGuiViewport` *	the GUI viewport
`out_pos`	`float`[2]	optional output mouse x/y coordinates
`out_size`	`float`[2]	optional output displayed source width/height
`out_hovered`	`_Bool` *	optional output hover state

Declared in include/datoviz/gui.h:570.

`dvz_gui_viewport_window()`¶

Show a dockable ImGui window containing a Datoviz-rendered viewport image.

Hidden or collapsed viewport windows stop rendering their source figure by default after the first image is available. Set DVZ_GUI_VIEWPORT_FLAGS_RENDER_WHEN_HIDDEN to keep the source rendering continuously.

_Bool dvz_gui_viewport_window(
    DvzGuiViewport * viewport,
    const char * title,
    _Bool * open,
    int flags
);

Field	Type	Description
return	`_Bool`	whether the Datoviz image was visible this frame
`viewport`	`DvzGuiViewport` *	the GUI viewport
`title`	`const` `char` *	the ImGui window title
`open`	`_Bool` *	optional open flag, or NULL
`flags`	`int`	Dear ImGui window flags

Declared in include/datoviz/gui.h:601.

Types

DvzGui · typedef

typedef struct DvzGui DvzGui;

Declared in include/datoviz/gui.h:33.

DvzGuiCallback · typedef

typedef void (*)(DvzGui *, DvzView *, void *) DvzGuiCallback;

Declared in include/datoviz/gui.h:36.

DvzGuiConfig · record

struct DvzGuiConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t gui_flags;
    uint32_t default_window_width;
    const char * ini_path;
};

Declared in include/datoviz/gui.h:80.

DvzGuiDockSlot · enum

enum DvzGuiDockSlot {
    DVZ_GUI_DOCK_SLOT_LEFT = 0,
    DVZ_GUI_DOCK_SLOT_RIGHT = 1,
    DVZ_GUI_DOCK_SLOT_TOP = 2,
    DVZ_GUI_DOCK_SLOT_BOTTOM = 3,
};

Declared in include/datoviz/gui.h:66.

DvzGuiFlags · enum

enum DvzGuiFlags {
    DVZ_GUI_FLAGS_NONE = 0,
    DVZ_GUI_FLAGS_DOCKING = 1,
    DVZ_GUI_FLAGS_DOCKSPACE = 2,
};

Declared in include/datoviz/gui.h:44.

DvzGuiViewport · typedef

typedef struct DvzGuiViewport DvzGuiViewport;

Declared in include/datoviz/gui.h:34.

DvzGuiViewportConfig · record

struct DvzGuiViewportConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t viewport_flags;
    uint32_t initial_width;
    uint32_t initial_height;
    uint32_t min_width;
    uint32_t min_height;
    uint32_t resize_step;
    uint32_t resize_delay_frames;
};

Declared in include/datoviz/gui.h:93.

DvzGuiViewportFlags · enum

enum DvzGuiViewportFlags {
    DVZ_GUI_VIEWPORT_FLAGS_NONE = 0,
    DVZ_GUI_VIEWPORT_FLAGS_FORWARD_INPUT = 1,
    DVZ_GUI_VIEWPORT_FLAGS_RENDER_WHEN_HIDDEN = 2,
};

Declared in include/datoviz/gui.h:53.

Input Routing¶

Functions

`dvz_input_emit_event()`¶

Emit a union input event. Callbacks run synchronously on the emitting thread.

void dvz_input_emit_event(
    DvzInputRouter * router,
    const DvzInputEvent * event
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`event`	`const` `DvzInputEvent` *	event borrowed for the duration of the call; must not be NULL

Declared in include/datoviz/input/router.h:294.

`dvz_input_emit_keyboard()`¶

Emit a keyboard event. Callbacks run synchronously on the emitting thread.

void dvz_input_emit_keyboard(
    DvzInputRouter * router,
    const DvzKeyboardEvent * event
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`event`	`const` `DvzKeyboardEvent` *	event borrowed for the duration of the call; must not be NULL

Declared in include/datoviz/input/router.h:196.

`dvz_input_emit_pointer()`¶

Emit a raw pointer event. Callbacks run synchronously on the emitting thread.

void dvz_input_emit_pointer(
    DvzInputRouter * router,
    const DvzPointerEvent * event
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`event`	`const` `DvzPointerEvent` *	event borrowed for the duration of the call; must not be NULL

Declared in include/datoviz/input/router.h:172.

`dvz_input_emit_resize()`¶

Emit a resize event. Callbacks run synchronously on the emitting thread.

The router copies the event and caches it for dvz_input_router_last_resize().

void dvz_input_emit_resize(
    DvzInputRouter * router,
    const DvzInputResizeEvent * event
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`event`	`const` `DvzInputResizeEvent` *	event borrowed for the duration of the call; dimensions are in pixels; must not be NULL

Declared in include/datoviz/input/router.h:224.

`dvz_input_emit_scale()`¶

Emit a scale event. Callbacks run synchronously on the emitting thread.

void dvz_input_emit_scale(
    DvzInputRouter * router,
    const DvzInputScaleEvent * event
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`event`	`const` `DvzInputScaleEvent` *	event borrowed for the duration of the call; must not be NULL

Declared in include/datoviz/input/router.h:266.

`dvz_input_router()`¶

Create an input event router.

DvzInputRouter * dvz_input_router(void);

Field	Type	Description
return	`DvzInputRouter` *	a new owned router, or NULL on allocation failure; destroy it with `dvz_input_router_destroy()`

Declared in include/datoviz/input/router.h:118.

`dvz_input_router_destroy()`¶

Destroy a router.

void dvz_input_router_destroy(
    DvzInputRouter * router
);

Field	Type	Description
`router`	`DvzInputRouter` *	router returned by dvz_input_router(); must not be NULL

Declared in include/datoviz/input/router.h:127.

`dvz_input_router_last_resize()`¶

Read the most recent resize event seen by the router.

Returns true and fills @p out when a resize has been emitted at least once, false otherwise (e.g. for routers that have never had a backend resize). Useful for late subscribers (e.g. controllers connected after window creation) to learn the current window/framebuffer dimensions without waiting for the next resize.

_Bool dvz_input_router_last_resize(
    const DvzInputRouter * router,
    DvzInputResizeEvent * out
);

Field	Type	Description
return	`_Bool`	true if @p out was filled, false if no resize event has been emitted
`router`	`const` `DvzInputRouter` *	router to query; must not be NULL
`out`	`DvzInputResizeEvent` *

Declared in include/datoviz/input/router.h:242.

`dvz_input_subscribe_event()`¶

Subscribe to routed union-style input events.

This stream carries pointer, keyboard, resize, and scale events in one callback. When a DvzPointerGestureHandler is attached to the router, this stream also receives gesture-derived pointer events such as click, double-click, drag-start, drag, and drag-stop.

DvzCallbackId dvz_input_subscribe_event(
    DvzInputRouter * router,
    DvzInputCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzCallbackId`	subscription id, or `DVZ_CALLBACK_ID_NONE` on failure
`router`	`DvzInputRouter` *	target router; must not be NULL
`callback`	`DvzInputCallback`	callback invoked synchronously for each union event; must not be NULL
`user_data`	`void` *	borrowed opaque pointer passed to the callback; may be NULL and must remain valid until unsubscription or router destruction

Declared in include/datoviz/input/router.h:284.

`dvz_input_subscribe_keyboard()`¶

Subscribe to keyboard events.

DvzCallbackId dvz_input_subscribe_keyboard(
    DvzInputRouter * router,
    DvzKeyboardCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzCallbackId`	subscription id, or `DVZ_CALLBACK_ID_NONE` on failure
`router`	`DvzInputRouter` *	target router; must not be NULL
`callback`	`DvzKeyboardCallback`	callback invoked synchronously for each keyboard event; must not be NULL
`user_data`	`void` *	borrowed opaque pointer passed to the callback; may be NULL and must remain valid until unsubscription or router destruction

Declared in include/datoviz/input/router.h:185.

`dvz_input_subscribe_pointer()`¶

Subscribe to raw pointer events.

These callbacks receive backend-normalized pointer position, button, and wheel events emitted directly through dvz_input_emit_pointer(). Gesture-derived events such as click, double-click, drag-start, drag, and drag-stop are emitted on the union input stream; use dvz_input_subscribe_event() when those higher-level pointer events are needed.

The router borrows @p user_data and passes it unchanged to @p callback. The callback and user data must remain valid until the subscription is removed or the router is destroyed.

DvzCallbackId dvz_input_subscribe_pointer(
    DvzInputRouter * router,
    DvzPointerCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzCallbackId`	subscription id, or `DVZ_CALLBACK_ID_NONE` on failure
`router`	`DvzInputRouter` *	target router; must not be NULL
`callback`	`DvzPointerCallback`	callback invoked synchronously for each raw pointer event; must not be NULL
`user_data`	`void` *	borrowed opaque pointer passed to the callback; may be NULL

Declared in include/datoviz/input/router.h:148.

`dvz_input_subscribe_resize()`¶

Subscribe to resize events.

DvzCallbackId dvz_input_subscribe_resize(
    DvzInputRouter * router,
    DvzResizeCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzCallbackId`	subscription id, or `DVZ_CALLBACK_ID_NONE` on failure
`router`	`DvzInputRouter` *	target router; must not be NULL
`callback`	`DvzResizeCallback`	callback invoked synchronously for each resize event; must not be NULL
`user_data`	`void` *	borrowed opaque pointer passed to the callback; may be NULL and must remain valid until unsubscription or router destruction

Declared in include/datoviz/input/router.h:210.

`dvz_input_subscribe_scale()`¶

Subscribe to content scale events.

DvzCallbackId dvz_input_subscribe_scale(
    DvzInputRouter * router,
    DvzScaleCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzCallbackId`	subscription id, or `DVZ_CALLBACK_ID_NONE` on failure
`router`	`DvzInputRouter` *	target router; must not be NULL
`callback`	`DvzScaleCallback`	callback invoked synchronously for each scale event; must not be NULL
`user_data`	`void` *	borrowed opaque pointer passed to the callback; may be NULL and must remain valid until unsubscription or router destruction

Declared in include/datoviz/input/router.h:256.

`dvz_input_timestamp_ns()`¶

Return the current wall-clock timestamp in nanoseconds.

uint64_t dvz_input_timestamp_ns(void);

Field	Type	Description
return	`uint64_t`	Unix wall-clock timestamp in nanoseconds

Declared in include/datoviz/input/pointer.h:118.

`dvz_input_unsubscribe()`¶

Unsubscribe from any router callback by subscription id.

Returns true when a callback was removed and false when @p id is DVZ_CALLBACK_ID_NONE or is not currently registered on this router.

_Bool dvz_input_unsubscribe(
    DvzInputRouter * router,
    DvzCallbackId id
);

Field	Type	Description
return	`_Bool`	true if the subscription was removed, false if it was not registered
`router`	`DvzInputRouter` *	target router; must not be NULL
`id`	`DvzCallbackId`	subscription identifier returned by a subscribe function

Declared in include/datoviz/input/router.h:162.

`dvz_keyboard_emit()`¶

Emit a keyboard event on the router.

The constructed event borrows @p user_data; callbacks run synchronously before this function returns.

void dvz_keyboard_emit(
    DvzInputRouter * router,
    DvzKeyboardEventType type,
    DvzKeyCode key,
    int mods,
    void * user_data
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`type`	`DvzKeyboardEventType`	keyboard event type
`key`	`DvzKeyCode`	backend-normalized key code
`mods`	`int`	bitwise combination of `DvzKeyboardModifiers` values
`user_data`	`void` *	opaque pointer stored in the event; may be NULL

Declared in include/datoviz/input/keyboard.h:129.

`dvz_keyboard_modifier_bit()`¶

Return the modifier bit mask for a key.

int dvz_keyboard_modifier_bit(
    DvzKeyCode key
);

Field	Type	Description
return	`int`	the corresponding `DvzKeyboardModifiers` bit, or zero for a non-modifier key
`key`	`DvzKeyCode`	key code to classify

Declared in include/datoviz/input/keyboard.h:71.

`dvz_keyboard_modifier_state()`¶

Create a modifier tracker.

DvzKeyboardModifierState * dvz_keyboard_modifier_state(void);

Field	Type	Description
return	`DvzKeyboardModifierState` *	a new owned zero-initialized tracker, or NULL on allocation failure; destroy it with `dvz_keyboard_modifier_state_destroy()`

Declared in include/datoviz/input/keyboard.h:81.

`dvz_keyboard_modifier_state_destroy()`¶

Destroy a modifier tracker.

void dvz_keyboard_modifier_state_destroy(
    DvzKeyboardModifierState * state
);

Field	Type	Description
`state`	`DvzKeyboardModifierState` *	owned tracker to destroy; may be NULL

Declared in include/datoviz/input/keyboard.h:90.

`dvz_keyboard_modifier_state_mods()`¶

Return the current modifier mask.

int dvz_keyboard_modifier_state_mods(
    const DvzKeyboardModifierState * state
);

Field	Type	Description
return	`int`	bitwise combination of `DvzKeyboardModifiers` values
`state`	`const` `DvzKeyboardModifierState` *	tracker to query; must not be NULL

Declared in include/datoviz/input/keyboard.h:113.

`dvz_keyboard_modifier_state_update()`¶

Update the modifier tracker with a keyboard event.

DvzResult dvz_keyboard_modifier_state_update(
    DvzKeyboardModifierState * state,
    DvzKeyboardEventType type,
    DvzKeyCode key
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`state`	`DvzKeyboardModifierState` *	tracker to update; must not be NULL
`type`	`DvzKeyboardEventType`	press, repeat, or release event type
`key`	`DvzKeyCode`	modifier key to update

Declared in include/datoviz/input/keyboard.h:102.

`dvz_pointer_button_from_glfw()`¶

Translate a backend mouse button identifier into the Datoviz pointer button enum.

DvzPointerButton dvz_pointer_button_from_glfw(
    int button
);

Field	Type	Description
return	`DvzPointerButton`	the matching pointer button, or `DVZ_POINTER_BUTTON_NONE` if unsupported
`button`	`int`	GLFW mouse-button value

Declared in include/datoviz/input/pointer.h:109.

`dvz_pointer_emit_position()`¶

Emit a normalized pointer event on the router.

Raw coordinates, window dimensions, and @p content_scale are stored unchanged. The constructed event borrows @p user_data and is dispatched synchronously.

void dvz_pointer_emit_position(
    DvzInputRouter * router,
    DvzPointerEventType type,
    float raw_x,
    float raw_y,
    float window_width,
    float window_height,
    DvzPointerButton button,
    int mods,
    float content_scale,
    uint64_t timestamp_ns,
    void * user_data
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`type`	`DvzPointerEventType`	pointer event type
`raw_x`	`float`	horizontal pointer position in backend window coordinates
`raw_y`	`float`	vertical pointer position in backend window coordinates
`window_width`	`float`	window width in the same units as @p raw_x
`window_height`	`float`	window height in the same units as @p raw_y
`button`	`DvzPointerButton`	button associated with the event, or `DVZ_POINTER_BUTTON_NONE`
`mods`	`int`	bitwise combination of keyboard modifier flags
`content_scale`	`float`	backend content scale associated with the event
`timestamp_ns`	`uint64_t`	event timestamp in nanoseconds, or zero if unavailable
`user_data`	`void` *	opaque pointer stored in the event; may be NULL

Declared in include/datoviz/input/pointer.h:140.

`dvz_pointer_emit_wheel()`¶

Emit a wheel event with pixel deltas.

Pointer coordinates, window dimensions, content scale, and wheel deltas are copied unchanged. Dispatch is synchronous.

void dvz_pointer_emit_wheel(
    DvzInputRouter * router,
    float raw_x,
    float raw_y,
    float window_width,
    float window_height,
    float dir_x,
    float dir_y,
    int mods,
    float content_scale,
    uint64_t timestamp_ns,
    void * user_data
);

Field	Type	Description
`router`	`DvzInputRouter` *	target router; must not be NULL
`raw_x`	`float`	horizontal pointer position in backend window coordinates
`raw_y`	`float`	vertical pointer position in backend window coordinates
`window_width`	`float`	window width in the same units as @p raw_x
`window_height`	`float`	window height in the same units as @p raw_y
`dir_x`	`float`	horizontal wheel delta in pixels
`dir_y`	`float`	vertical wheel delta in pixels
`mods`	`int`	bitwise combination of keyboard modifier flags
`content_scale`	`float`	backend content scale associated with the event
`timestamp_ns`	`uint64_t`	event timestamp in nanoseconds, or zero if unavailable
`user_data`	`void` *	opaque pointer stored in the event; may be NULL

Declared in include/datoviz/input/pointer.h:165.

`dvz_pointer_gesture_handler()`¶

Attach the pointer gesture interpreter to the router.

The interpreter listens to raw pointer events and emits gesture-derived pointer events on the router's union input stream. Subscribe with dvz_input_subscribe_event() to receive click, double-click, drag-start, drag, and drag-stop events.

DvzPointerGestureHandler * dvz_pointer_gesture_handler(
    DvzInputRouter * router
);

Field	Type	Description
return	`DvzPointerGestureHandler` *	a new owned handler; destroy it before destroying @p router
`router`	`DvzInputRouter` *	router to observe; borrowed and must outlive the handler

Declared in include/datoviz/input/pointer.h:182.

`dvz_pointer_gesture_handler_destroy()`¶

Destroy the gesture interpreter.

This also removes its raw-pointer subscription from the borrowed router.

void dvz_pointer_gesture_handler_destroy(
    DvzPointerGestureHandler * handler
);

Field	Type	Description
`handler`	`DvzPointerGestureHandler` *	owned handler to destroy; may be NULL

Declared in include/datoviz/input/pointer.h:193.

Types

DvzCallbackId · typedef

typedef uint64_t DvzCallbackId;

Declared in include/datoviz/input/router.h:58.

DvzCallbackIdSpecial · enum

enum DvzCallbackIdSpecial {
    DVZ_CALLBACK_ID_NONE = 0,
};

Declared in include/datoviz/input/router.h:42.

DvzInputCallback · typedef

typedef void (*)(DvzInputRouter *, const DvzInputEvent *, void *) DvzInputCallback;

Declared in include/datoviz/input/router.h:64.

DvzInputEvent · record

struct DvzInputEvent {
    DvzInputEventType type;
    union (unnamed union at include/datoviz/input/router.h:95:5) content;
};

Declared in include/datoviz/input/router.h:92.

DvzInputEventType · enum

enum DvzInputEventType {
    DVZ_INPUT_EVENT_NONE = 0,
    DVZ_INPUT_EVENT_POINTER = 1,
    DVZ_INPUT_EVENT_KEYBOARD = 2,
    DVZ_INPUT_EVENT_RESIZE = 3,
    DVZ_INPUT_EVENT_SCALE = 4,
};

Declared in include/datoviz/input/router.h:31.

DvzInputResizeEvent · record

struct DvzInputResizeEvent {
    uint32_t framebuffer_width;
    uint32_t framebuffer_height;
    uint32_t window_width;
    uint32_t window_height;
    float content_scale_x;
    float content_scale_y;
};

Declared in include/datoviz/input/router.h:72.

DvzInputRouter · typedef

typedef struct DvzInputRouter DvzInputRouter;

Declared in include/datoviz/input/router.h:56.

DvzInputScaleEvent · record

struct DvzInputScaleEvent {
    float content_scale_x;
    float content_scale_y;
};

Declared in include/datoviz/input/router.h:84.

DvzKeyCode · enum

enum DvzKeyCode {
    DVZ_KEY_UNKNOWN = -1,
    DVZ_KEY_NONE = 0,
    DVZ_KEY_SPACE = 32,
    DVZ_KEY_APOSTROPHE = 39,
    DVZ_KEY_COMMA = 44,
    DVZ_KEY_MINUS = 45,
    DVZ_KEY_PERIOD = 46,
    DVZ_KEY_SLASH = 47,
    DVZ_KEY_0 = 48,
    DVZ_KEY_1 = 49,
    DVZ_KEY_2 = 50,
    DVZ_KEY_3 = 51,
    DVZ_KEY_4 = 52,
    DVZ_KEY_5 = 53,
    DVZ_KEY_6 = 54,
    DVZ_KEY_7 = 55,
    DVZ_KEY_8 = 56,
    DVZ_KEY_9 = 57,
    DVZ_KEY_SEMICOLON = 59,
    DVZ_KEY_EQUAL = 61,
    DVZ_KEY_A = 65,
    DVZ_KEY_B = 66,
    DVZ_KEY_C = 67,
    DVZ_KEY_D = 68,
    DVZ_KEY_E = 69,
    DVZ_KEY_F = 70,
    DVZ_KEY_G = 71,
    DVZ_KEY_H = 72,
    DVZ_KEY_I = 73,
    DVZ_KEY_J = 74,
    DVZ_KEY_K = 75,
    DVZ_KEY_L = 76,
    DVZ_KEY_M = 77,
    DVZ_KEY_N = 78,
    DVZ_KEY_O = 79,
    DVZ_KEY_P = 80,
    DVZ_KEY_Q = 81,
    DVZ_KEY_R = 82,
    DVZ_KEY_S = 83,
    DVZ_KEY_T = 84,
    DVZ_KEY_U = 85,
    DVZ_KEY_V = 86,
    DVZ_KEY_W = 87,
    DVZ_KEY_X = 88,
    DVZ_KEY_Y = 89,
    DVZ_KEY_Z = 90,
    DVZ_KEY_LEFT_BRACKET = 91,
    DVZ_KEY_BACKSLASH = 92,
    DVZ_KEY_RIGHT_BRACKET = 93,
    DVZ_KEY_GRAVE_ACCENT = 96,
    DVZ_KEY_WORLD_1 = 161,
    DVZ_KEY_WORLD_2 = 162,
    DVZ_KEY_ESCAPE = 256,
    DVZ_KEY_ENTER = 257,
    DVZ_KEY_TAB = 258,
    DVZ_KEY_BACKSPACE = 259,
    DVZ_KEY_INSERT = 260,
    DVZ_KEY_DELETE = 261,
    DVZ_KEY_RIGHT = 262,
    DVZ_KEY_LEFT = 263,
    DVZ_KEY_DOWN = 264,
    DVZ_KEY_UP = 265,
    DVZ_KEY_PAGE_UP = 266,
    DVZ_KEY_PAGE_DOWN = 267,
    DVZ_KEY_HOME = 268,
    DVZ_KEY_END = 269,
    DVZ_KEY_CAPS_LOCK = 280,
    DVZ_KEY_SCROLL_LOCK = 281,
    DVZ_KEY_NUM_LOCK = 282,
    DVZ_KEY_PRINT_SCREEN = 283,
    DVZ_KEY_PAUSE = 284,
    DVZ_KEY_F1 = 290,
    DVZ_KEY_F2 = 291,
    DVZ_KEY_F3 = 292,
    DVZ_KEY_F4 = 293,
    DVZ_KEY_F5 = 294,
    DVZ_KEY_F6 = 295,
    DVZ_KEY_F7 = 296,
    DVZ_KEY_F8 = 297,
    DVZ_KEY_F9 = 298,
    DVZ_KEY_F10 = 299,
    DVZ_KEY_F11 = 300,
    DVZ_KEY_F12 = 301,
    DVZ_KEY_F13 = 302,
    DVZ_KEY_F14 = 303,
    DVZ_KEY_F15 = 304,
    DVZ_KEY_F16 = 305,
    DVZ_KEY_F17 = 306,
    DVZ_KEY_F18 = 307,
    DVZ_KEY_F19 = 308,
    DVZ_KEY_F20 = 309,
    DVZ_KEY_F21 = 310,
    DVZ_KEY_F22 = 311,
    DVZ_KEY_F23 = 312,
    DVZ_KEY_F24 = 313,
    DVZ_KEY_F25 = 314,
    DVZ_KEY_KP_0 = 320,
    DVZ_KEY_KP_1 = 321,
    DVZ_KEY_KP_2 = 322,
    DVZ_KEY_KP_3 = 323,
    DVZ_KEY_KP_4 = 324,
    DVZ_KEY_KP_5 = 325,
    DVZ_KEY_KP_6 = 326,
    DVZ_KEY_KP_7 = 327,
    DVZ_KEY_KP_8 = 328,
    DVZ_KEY_KP_9 = 329,
    DVZ_KEY_KP_DECIMAL = 330,
    DVZ_KEY_KP_DIVIDE = 331,
    DVZ_KEY_KP_MULTIPLY = 332,
    DVZ_KEY_KP_SUBTRACT = 333,
    DVZ_KEY_KP_ADD = 334,
    DVZ_KEY_KP_ENTER = 335,
    DVZ_KEY_KP_EQUAL = 336,
    DVZ_KEY_LEFT_SHIFT = 340,
    DVZ_KEY_LEFT_CONTROL = 341,
    DVZ_KEY_LEFT_ALT = 342,
    DVZ_KEY_LEFT_SUPER = 343,
    DVZ_KEY_RIGHT_SHIFT = 344,
    DVZ_KEY_RIGHT_CONTROL = 345,
    DVZ_KEY_RIGHT_ALT = 346,
    DVZ_KEY_RIGHT_SUPER = 347,
    DVZ_KEY_MENU = 348,
    DVZ_KEY_LAST = 348,
};

Declared in include/datoviz/input/keycodes.h:20.

DvzKeyboardCallback · typedef

typedef void (*)(DvzInputRouter *, const DvzKeyboardEvent *, void *) DvzKeyboardCallback;

Declared in include/datoviz/input/router.h:61.

DvzKeyboardEvent · record

struct DvzKeyboardEvent {
    DvzKeyboardEventType type;
    DvzKeyCode key;
    int mods;
    void * user_data;
};

Declared in include/datoviz/input/keyboard.h:42.

DvzKeyboardEventType · enum

enum DvzKeyboardEventType {
    DVZ_KEYBOARD_EVENT_NONE = 0,
    DVZ_KEYBOARD_EVENT_PRESS = 1,
    DVZ_KEYBOARD_EVENT_REPEAT = 2,
    DVZ_KEYBOARD_EVENT_RELEASE = 3,
};

Declared in include/datoviz/input/enums.h:33.

DvzKeyboardModifierState · record

struct DvzKeyboardModifierState {
    int mods;
};

Declared in include/datoviz/input/keyboard.h:52.

DvzKeyboardModifiers · enum

enum DvzKeyboardModifiers {
    DVZ_KEY_MODIFIER_NONE = 0,
    DVZ_KEY_MODIFIER_SHIFT = 1,
    DVZ_KEY_MODIFIER_CONTROL = 2,
    DVZ_KEY_MODIFIER_ALT = 4,
    DVZ_KEY_MODIFIER_SUPER = 8,
};

Declared in include/datoviz/input/enums.h:21.

DvzPointerButton · enum

enum DvzPointerButton {
    DVZ_POINTER_BUTTON_NONE = 0,
    DVZ_POINTER_BUTTON_LEFT = 1,
    DVZ_POINTER_BUTTON_MIDDLE = 2,
    DVZ_POINTER_BUTTON_RIGHT = 3,
};

Declared in include/datoviz/input/enums.h:46.

DvzPointerCallback · typedef

typedef void (*)(DvzInputRouter *, const DvzPointerEvent *, void *) DvzPointerCallback;

Declared in include/datoviz/input/router.h:60.

DvzPointerDragEvent · record

struct DvzPointerDragEvent {
    vec2 press_pos;
    vec2 last_pos;
    vec2 shift;
    _Bool is_press_valid;
};

Declared in include/datoviz/input/pointer.h:64.

DvzPointerEvent · record

struct DvzPointerEvent {
    DvzPointerEventType type;
    DvzPointerEventUnion content;
    vec2 pos;
    vec2 window_size;
    DvzPointerButton button;
    int mods;
    float content_scale;
    uint64_t timestamp_ns;
    void * user_data;
};

Declared in include/datoviz/input/pointer.h:82.

DvzPointerEventType · enum

enum DvzPointerEventType {
    DVZ_POINTER_EVENT_NONE = -1,
    DVZ_POINTER_EVENT_RELEASE = 0,
    DVZ_POINTER_EVENT_PRESS = 1,
    DVZ_POINTER_EVENT_MOVE = 2,
    DVZ_POINTER_EVENT_CLICK = 3,
    DVZ_POINTER_EVENT_DOUBLE_CLICK = 5,
    DVZ_POINTER_EVENT_DRAG_START = 10,
    DVZ_POINTER_EVENT_DRAG = 11,
    DVZ_POINTER_EVENT_DRAG_STOP = 12,
    DVZ_POINTER_EVENT_WHEEL = 20,
    DVZ_POINTER_EVENT_ALL = 255,
};

Declared in include/datoviz/input/enums.h:70.

DvzPointerEventUnion · record

union DvzPointerEventUnion {
    DvzPointerWheelEvent w;
    DvzPointerDragEvent d;
};

Declared in include/datoviz/input/pointer.h:74.

DvzPointerGestureHandler · typedef

typedef struct DvzPointerGestureHandler DvzPointerGestureHandler;

Declared in include/datoviz/input/pointer.h:49.

DvzPointerState · enum

enum DvzPointerState {
    DVZ_POINTER_STATE_RELEASE = 0,
    DVZ_POINTER_STATE_PRESS = 1,
    DVZ_POINTER_STATE_CLICK = 3,
    DVZ_POINTER_STATE_CLICK_PRESS = 4,
    DVZ_POINTER_STATE_DOUBLE_CLICK = 5,
    DVZ_POINTER_STATE_DRAGGING = 11,
};

Declared in include/datoviz/input/enums.h:57.

DvzPointerWheelEvent · record

struct DvzPointerWheelEvent {
    vec2 dir;
};

Declared in include/datoviz/input/pointer.h:57.

DvzResizeCallback · typedef

typedef void (*)(DvzInputRouter *, const DvzInputResizeEvent *, void *) DvzResizeCallback;

Declared in include/datoviz/input/router.h:62.

DvzScaleCallback · typedef

typedef void (*)(DvzInputRouter *, const DvzInputScaleEvent *, void *) DvzScaleCallback;

Declared in include/datoviz/input/router.h:63.

Streaming And Video¶

Functions

`dvz_stream_attach_sink()`¶

Attach a backend sink to a stream before it starts streaming.

int dvz_stream_attach_sink(
    DvzStream * stream,
    const DvzStreamSinkBackend * backend,
    const void * config
);

Field	Type	Description
return	`int`	0 on success or -1 if the backend is invalid, the stream is running, the backend probe fails, or the backend creation fails
`stream`	`DvzStream` *	target stream
`backend`	`const` `DvzStreamSinkBackend` *	borrowed sink backend descriptor retained until stream destruction
`config`	`const` `void` *	borrowed backend-specific configuration retained until sink destruction

Declared in include/datoviz/stream.h:76.

`dvz_stream_attach_sink_name()`¶

Look up a registered sink backend by name and attach it to the stream.

int dvz_stream_attach_sink_name(
    DvzStream * stream,
    const char * backend_name,
    const void * config
);

Field	Type	Description
return	`int`	0 on success or -1 when the named backend cannot be found or attached
`stream`	`DvzStream` *	target stream
`backend_name`	`const` `char` *	backend name (use "auto" or NULL for automatic selection)
`config`	`const` `void` *	borrowed backend-specific configuration retained until sink destruction

Declared in include/datoviz/stream.h:89.

`dvz_stream_config()`¶

Return a default stream configuration (1920×1080 @ 60 FPS, RGBA8).

DvzStreamConfig dvz_stream_config(void);

Field	Type	Description
return	`DvzStreamConfig`	a configuration initialized with common output parameters

Related: dvz_stream_create().

Declared in include/datoviz/stream.h:35.

`dvz_stream_create()`¶

Allocate a stream tied to a Vulkan device and the requested configuration.

The stream copies cfg and frame descriptors, but borrows the Vulkan device, sink registry, backend descriptors, backend configurations, and Vulkan handles referenced by frames. The registry must remain valid while attachment by name is possible. Backend descriptors and their configuration payloads must remain valid until the corresponding sink is destroyed.

DvzStream * dvz_stream_create(
    DvzDevice * device,
    DvzStreamSinkRegistry * sink_registry,
    const DvzStreamConfig * cfg
);

Field	Type	Description
return	`DvzStream` *	a new stream handle or NULL when allocation fails
`device`	`DvzDevice` *	the device that owns the stream (may be NULL if not required)
`sink_registry`	`DvzStreamSinkRegistry` *	required borrowed registry that holds available sink backends
`cfg`	`const` `DvzStreamConfig` *	optional configuration, falls back to the default when NULL

Related: dvz_stream_destroy().

Declared in include/datoviz/stream.h:52.

`dvz_stream_destroy()`¶

Stop the stream, detach sinks, and free the associated resources.

void dvz_stream_destroy(
    DvzStream * stream
);

Field	Type	Description
`stream`	`DvzStream` *	stream handle to destroy (NULL-safe)

Related: dvz_stream_create().

Declared in include/datoviz/stream.h:62.

`dvz_stream_device()`¶

Return the Vulkan device associated with the stream.

DvzDevice * dvz_stream_device(
    DvzStream * stream
);

Field	Type	Description
return	`DvzDevice` *	the borrowed device supplied at creation, or NULL when absent
`stream`	`DvzStream` *	stream handle

Declared in include/datoviz/stream.h:149.

`dvz_stream_get_config()`¶

Return the configuration currently driving the stream.

const DvzStreamConfig * dvz_stream_get_config(
    DvzStream * stream
);

Field	Type	Description
return	`const` `DvzStreamConfig` *	the borrowed internal configuration, valid until stream destruction, or NULL
`stream`	`DvzStream` *	stream handle

Declared in include/datoviz/stream.h:159.

`dvz_stream_sink_registry_create()`¶

Allocate a stream sink registry instance.

DvzStreamSinkRegistry * dvz_stream_sink_registry_create(void);

Field	Type	Description
return	`DvzStreamSinkRegistry` *	allocated registry or NULL on failure

Declared in include/datoviz/stream.h:207.

`dvz_stream_sink_registry_destroy()`¶

Destroy a stream sink registry and free its internal storage.

void dvz_stream_sink_registry_destroy(
    DvzStreamSinkRegistry * registry
);

Field	Type	Description
`registry`	`DvzStreamSinkRegistry` *	registry to destroy (NULL-safe)

Declared in include/datoviz/stream.h:215.

`dvz_stream_sink_registry_find()`¶

Find a registered sink backend by name.

const DvzStreamSinkBackend * dvz_stream_sink_registry_find(
    DvzStreamSinkRegistry * registry,
    const char * name
);

Field	Type	Description
return	`const` `DvzStreamSinkBackend` *	a borrowed registered backend descriptor, or NULL when no match is found
`registry`	`DvzStreamSinkRegistry` *	registry to query
`name`	`const` `char` *	backend name to look up

Declared in include/datoviz/stream.h:184.

`dvz_stream_sink_registry_pick()`¶

Pick a sink backend by name or probe registered backends automatically.

const DvzStreamSinkBackend * dvz_stream_sink_registry_pick(
    DvzStreamSinkRegistry * registry,
    const char * name,
    const void * config
);

Field	Type	Description
return	`const` `DvzStreamSinkBackend` *	a borrowed registered backend descriptor, or NULL when none are available
`registry`	`DvzStreamSinkRegistry` *	registry to query
`name`	`const` `char` *	requested backend name, "auto", or NULL for automatic selection
`config`	`const` `void` *	configuration forwarded to the backend probe callbacks

Declared in include/datoviz/stream.h:198.

`dvz_stream_sink_registry_register()`¶

Register a sink backend for later attachment by name or automatic selection.

The registry stores the descriptor pointer rather than copying the descriptor or its name. Both must remain valid until the registry is destroyed.

void dvz_stream_sink_registry_register(
    DvzStreamSinkRegistry * registry,
    const DvzStreamSinkBackend * backend
);

Field	Type	Description
`registry`	`DvzStreamSinkRegistry` *	registry that owns the backend database
`backend`	`const` `DvzStreamSinkBackend` *	borrowed backend descriptor with callbacks and a persistent unique name

Declared in include/datoviz/stream.h:172.

`dvz_stream_sink_video()`¶

Access the built-in video sink backend that encodes stream frames.

const DvzStreamSinkBackend * dvz_stream_sink_video(void);

Field	Type	Description
return	`const` `DvzStreamSinkBackend` *	the video sink backend descriptor (caller registers it in the target sink registry)

Declared in include/datoviz/video.h:144.

`dvz_stream_start()`¶

Start the stream by providing a frame description and launching every sink.

The descriptor is copied, but its Vulkan and operating-system handles remain borrowed and must satisfy the ownership and lifetime contract in DvzStreamFrame until updated or stopped.

int dvz_stream_start(
    DvzStream * stream,
    const DvzStreamFrame * frame
);

Field	Type	Description
return	`int`	0 on success or -1 if the stream is already running, lacks a frame, or a sink fails to start
`stream`	`DvzStream` *	stream to start
`frame`	`const` `DvzStreamFrame` *	required frame image and synchronization descriptor

Declared in include/datoviz/stream.h:104.

`dvz_stream_stop()`¶

Stop the stream and all attached sinks.

int dvz_stream_stop(
    DvzStream * stream
);

Field	Type	Description
return	`int`	0 when the stream is stopped or already idle
`stream`	`DvzStream` *	stream to stop (NULL-safe)

Declared in include/datoviz/stream.h:139.

`dvz_stream_submit()`¶

Submit the current frame to all sinks, forwarding the timeline wait value.

int dvz_stream_submit(
    DvzStream * stream,
    uint64_t wait_value
);

Field	Type	Description
return	`int`	0 when every sink accepts the submission or the first non-zero sink error
`stream`	`DvzStream` *	active stream
`wait_value`	`uint64_t`	timeline semaphore value sinks should wait for

Declared in include/datoviz/stream.h:115.

`dvz_stream_update()`¶

Update the frame description while the stream is running, restarting sinks if needed.

The descriptor is copied. Replaced borrowed handles may be released only after this call has stopped or successfully updated every sink.

int dvz_stream_update(
    DvzStream * stream,
    const DvzStreamFrame * frame
);

Field	Type	Description
return	`int`	0 on success or a sink error code (negative when a restart fails)
`stream`	`DvzStream` *	active stream
`frame`	`const` `DvzStreamFrame` *	required new frame metadata to apply

Declared in include/datoviz/stream.h:129.

`dvz_video_encoder_config()`¶

Return the encoder configuration used when no overrides are supplied.

Width, height, and FPS are zero in the returned initializer. Canvas/stream users inherit those fields from the stream; standalone encoder creation resolves them to 1080p60.

DvzVideoEncoderConfig dvz_video_encoder_config(void);

Field	Type	Description
return	`DvzVideoEncoderConfig`	a config tuned for inherited-size HEVC capture with MP4 streaming muxing

Declared in include/datoviz/video.h:122.

`dvz_video_sink_config()`¶

Return the default video sink configuration that wraps the encoder defaults.

The nested encoder leaves width, height, and FPS unresolved so canvas/stream attachment can inherit the active stream geometry and cadence.

DvzVideoSinkConfig dvz_video_sink_config(void);

Field	Type	Description
return	`DvzVideoSinkConfig`	a sink config whose encoder uses `dvz_video_encoder_config()` and null bitstream

Declared in include/datoviz/video.h:135.

Types

DvzStream · typedef

typedef struct DvzStream DvzStream;

Declared in include/datoviz/stream/frame_stream.h:36.

DvzStreamConfig · record

struct DvzStreamConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t width;
    uint32_t height;
    uint32_t fps;
    VkFormat color_format;
};

Declared in include/datoviz/stream/frame_stream.h:48.

DvzStreamFrame · record

struct DvzStreamFrame {
    VkImage image;
    VkDeviceMemory memory;
    VkDeviceSize memory_size;
    VkCommandBuffer command_buffer;
    VkImageView image_view;
    VkExtent2D extent;
    VkFormat color_format;
    VkImageLayout image_layout;
    uint32_t usage;
    _Bool command_buffer_recording;
    _Bool image_borrowed;
    _Bool image_view_borrowed;
    _Bool command_buffer_borrowed;
    _Bool handles_dirty;
    uint64_t resource_generation;
    _Bool image_valid;
    int memory_fd;
    int wait_semaphore_fd;
};

Declared in include/datoviz/stream/frame_stream.h:80.

DvzStreamFrameUsage · enum

enum DvzStreamFrameUsage {
    DVZ_STREAM_FRAME_USAGE_NONE = 0,
    DVZ_STREAM_FRAME_USAGE_RENDER_TARGET = 1,
    DVZ_STREAM_FRAME_USAGE_COPY_SRC = 2,
    DVZ_STREAM_FRAME_USAGE_COPY_DST = 4,
};

Declared in include/datoviz/stream/frame_stream.h:61.

DvzStreamSink · record

struct DvzStreamSink {
    DvzStream * stream;
    const DvzStreamSinkBackend * backend;
    void * backend_data;
    const void * config;
    _Bool started;
};

Declared in include/datoviz/stream/frame_stream.h:105.

DvzStreamSinkBackend · record

struct DvzStreamSinkBackend {
    const char * name;
    _Bool (*)(const void *) probe;
    int (*)(DvzStreamSink *, const void *) create;
    int (*)(DvzStreamSink *, const DvzStreamFrame *) start;
    int (*)(DvzStreamSink *, uint64_t) submit;
    int (*)(DvzStreamSink *) stop;
    int (*)(DvzStreamSink *, const DvzStreamFrame *) update;
    void (*)(DvzStreamSink *) destroy;
};

Declared in include/datoviz/stream/frame_stream.h:126.

DvzStreamSinkRegistry · typedef

typedef struct DvzStreamSinkRegistry DvzStreamSinkRegistry;

Declared in include/datoviz/stream/frame_stream.h:39.

DvzStreamSinkRequest · record

struct DvzStreamSinkRequest {
    const char * backend;
    const void * config;
};

Declared in include/datoviz/stream/frame_stream.h:117.

DvzVideoCaptureMode · enum

enum DvzVideoCaptureMode {
    DVZ_VIDEO_CAPTURE_AUTO = 0,
    DVZ_VIDEO_CAPTURE_EXTERNAL = 1,
    DVZ_VIDEO_CAPTURE_CPU_READBACK = 2,
};

Declared in include/datoviz/video/types.h:20.

DvzVideoCodec · enum

enum DvzVideoCodec {
    DVZ_VIDEO_CODEC_H264 = 0,
    DVZ_VIDEO_CODEC_HEVC = 1,
};

Declared in include/datoviz/video.h:44.

DvzVideoEncoderConfig · record

struct DvzVideoEncoderConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t width;
    uint32_t height;
    uint32_t fps;
    VkFormat color_format;
    DvzVideoCodec codec;
    DvzVideoMux mux;
    const char * mp4_path;
    const char * raw_path;
    const char * backend;
};

Declared in include/datoviz/video.h:76.

DvzVideoMux · enum

enum DvzVideoMux {
    DVZ_VIDEO_MUX_NONE = 0,
    DVZ_VIDEO_MUX_MP4_STREAMING = 1,
    DVZ_VIDEO_MUX_MP4_POST = 2,
};

Declared in include/datoviz/video.h:53.

DvzVideoSinkCaptureFn · typedef

typedef int (*)(void *, uint32_t *, uint32_t *, size_t *, uint8_t **) DvzVideoSinkCaptureFn;

Declared in include/datoviz/video.h:64.

DvzVideoSinkConfig · record

struct DvzVideoSinkConfig {
    uint32_t struct_size;
    uint32_t flags;
    DvzVideoEncoderConfig encoder;
    FILE * bitstream;
    DvzVideoCaptureMode capture_mode;
    DvzVideoSinkCaptureFn capture_rgba;
    DvzVideoSinkReleaseFn release_rgba;
    void * capture_user_data;
};

Declared in include/datoviz/video.h:94.

DvzVideoSinkReleaseFn · typedef

typedef void (*)(void *, uint8_t *) DvzVideoSinkReleaseFn;

Declared in include/datoviz/video.h:71.

Views And Capture¶

Functions

`dvz_view()`¶

Create a view for a figure from an explicit descriptor.

Descriptor dimensions use the size_policy and size_* fields. For offscreen views, DVZ_VIEW_SIZE_FRAMEBUFFER_PX preserves exact-pixel output; DVZ_VIEW_SIZE_HOST_LOGICAL_PX derives the framebuffer size from logical dimensions and device scale. render_scale is tracked separately for future supersampling and does not currently change the framebuffer size.

DvzView * dvz_view(
    DvzApp * app,
    DvzFigure * figure,
    const DvzViewDesc * desc
);

Field	Type	Description
return	`DvzView` *	the view handle, or NULL on failure
`app`	`DvzApp` *	the app
`figure`	`DvzFigure` *	the figure to render (borrowed)
`desc`	`const` `DvzViewDesc` *	view descriptor

Declared in include/datoviz/app.h:476.

`dvz_view_arcball()`¶

Create, bind, and connect an arcball controller for one panel.

DvzArcball * dvz_view_arcball(
    DvzView * view,
    DvzPanel * panel,
    const DvzArcballDesc * desc
);

Field	Type	Description
return	`DvzArcball` *	the arcball payload, or NULL on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel
`desc`	`const` `DvzArcballDesc` *	arcball descriptor, or NULL for defaults

Declared in include/datoviz/app.h:750.

`dvz_view_bind_controller()`¶

Bind a controller to a panel and connect the panel to a view input router.

DvzResult dvz_view_bind_controller(
    DvzView * view,
    DvzPanel * panel,
    DvzController * controller,
    DvzDimMask dims
);

Field	Type	Description
return	`DvzResult`	0 on success, -1 on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel
`controller`	`DvzController` *	the scene-owned controller
`dims`	`DvzDimMask`	dimension mask

Declared in include/datoviz/app.h:725.

`dvz_view_canvas()`¶

Return the underlying DvzCanvas for a window.

Gives access to the full canvas API (capture, video sink, live-image sink, etc.).

struct DvzCanvas * dvz_view_canvas(
    DvzView * view
);

Field	Type	Description
return	`struct` `DvzCanvas` *	the canvas, or NULL if the window was not created with GPU support
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:591.

`dvz_view_capabilities()`¶

Return the runtime capability snapshot for a live view.

The snapshot is scene-facing and backend-neutral. It reports the runtime facts used by scene planning and query/readback adaptation without exposing Vulkan, canvas, or runtime handles.

_Bool dvz_view_capabilities(
    const DvzView * view,
    DvzCapabilitySnapshot * out
);

Field	Type	Description
return	`_Bool`	true when live runtime-backed fields were available; false means only defaults were used
`view`	`const` `DvzView` *	the view
`out`	`DvzCapabilitySnapshot` *	output capability snapshot

Declared in include/datoviz/app.h:675.

`dvz_view_capture_from_env()`¶

Start captures for a view from environment variables.

This is a convenience wrapper around dvz_app_capture_config_from_env() and dvz_view_capture_start(). If DVZ_CAPTURE is unset or disables capture, the function is a no-op and returns success.

DvzResult dvz_view_capture_from_env(
    DvzView * view,
    const char * basename
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`basename`	`const` `char` *	fallback output basename, or NULL for "capture"

Declared in include/datoviz/app.h:842.

`dvz_view_capture_png()`¶

Capture the last rendered frame and write it to a PNG file.

Convenience wrapper around dvz_view_canvas() + dvz_canvas_capture_png(). Call after at least one dvz_app_run() iteration. PNG capture is an sRGB RGBA8 screenshot/export, not a scientific linear-float readback.

DvzResult dvz_view_capture_png(
    DvzView * view,
    const char * path
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`path`	`const` `char` *	output file path

Declared in include/datoviz/app.h:788.

`dvz_view_capture_start()`¶

Start configured captures for a view.

DVZR capture records emitted app DRP2 frame streams, video capture enables the canvas video sink, and PNG capture is written when dvz_view_capture_stop() is called after rendering. PNG and CPU video capture use sRGB RGBA8 screenshot pixels.

DvzResult dvz_view_capture_start(
    DvzView * view,
    const DvzAppCaptureConfig * config
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`config`	`const` `DvzAppCaptureConfig` *	capture configuration, or NULL for dvz_app_capture_config()

Declared in include/datoviz/app.h:827.

`dvz_view_capture_stop()`¶

Stop active captures started by dvz_view_capture_start().

Video capture is disabled, DVZR recordings are closed, and pending PNG capture is written from the last rendered frame as sRGB RGBA8 screenshot pixels.

DvzResult dvz_view_capture_stop(
    DvzView * view
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:854.

`dvz_view_connect_panel()`¶

Connect a panel's bound controllers to a view input router.

DvzResult dvz_view_connect_panel(
    DvzView * view,
    DvzPanel * panel
);

Field	Type	Description
return	`DvzResult`	0 on success, -1 on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel

Declared in include/datoviz/app.h:713.

`dvz_view_desc()`¶

Return the default descriptor for one view kind.

DvzViewDesc dvz_view_desc(
    DvzViewKind kind
);

Field	Type	Description
return	`DvzViewDesc`	initialized view descriptor
`kind`	`DvzViewKind`	view kind

Related: dvz_view().

Declared in include/datoviz/app.h:395.

`dvz_view_device_scale()`¶

Return the current device scale for a view.

float dvz_view_device_scale(
    const DvzView * view
);

Field	Type	Description
return	`float`	physical pixels per logical pixel, or 1 when unavailable
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:612.

`dvz_view_device_scale_xy()`¶

Return the current two-axis device scale for a view.

DvzScaleXY dvz_view_device_scale_xy(
    const DvzView * view
);

Field	Type	Description
return	`DvzScaleXY`	physical pixels per logical pixel along X and Y
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:621.

`dvz_view_emit_key()`¶

Emit a hosted keyboard event for a view.

DvzResult dvz_view_emit_key(
    DvzView * view,
    DvzKeyboardEventType type,
    DvzKeyCode key,
    int mods
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`type`	`DvzKeyboardEventType`	keyboard event type
`key`	`DvzKeyCode`	Datoviz key code
`mods`	`int`	keyboard modifier bit mask

Declared in include/datoviz/app.h:580.

`dvz_view_emit_pointer()`¶

Emit a hosted pointer position/button event for a view.

DvzResult dvz_view_emit_pointer(
    DvzView * view,
    DvzPointerEventType type,
    float x,
    float y,
    float window_width,
    float window_height,
    DvzPointerButton button,
    int mods
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`type`	`DvzPointerEventType`	pointer event type
`x`	`float`	pointer x position in host-window coordinates
`y`	`float`	pointer y position in host-window coordinates
`window_width`	`float`	logical host-window width
`window_height`	`float`	logical host-window height
`button`	`DvzPointerButton`	pointer button, or DVZ_POINTER_BUTTON_NONE
`mods`	`int`	keyboard modifier bit mask

Declared in include/datoviz/app.h:547.

`dvz_view_emit_resize()`¶

Emit a hosted resize event for a view.

External UI adapters call this after host resize notifications so Datoviz controllers and figure sizing see the host's logical and framebuffer dimensions.

DvzResult dvz_view_emit_resize(
    DvzView * view,
    uint32_t framebuffer_width,
    uint32_t framebuffer_height,
    uint32_t window_width,
    uint32_t window_height,
    float content_scale_x,
    float content_scale_y
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`framebuffer_width`	`uint32_t`	framebuffer width in physical pixels
`framebuffer_height`	`uint32_t`	framebuffer height in physical pixels
`window_width`	`uint32_t`	logical host-window width
`window_height`	`uint32_t`	logical host-window height
`content_scale_x`	`float`	horizontal content scale
`content_scale_y`	`float`	vertical content scale

Declared in include/datoviz/app.h:529.

`dvz_view_emit_wheel()`¶

Emit a hosted pointer wheel event for a view.

DvzResult dvz_view_emit_wheel(
    DvzView * view,
    float x,
    float y,
    float window_width,
    float window_height,
    float dx,
    float dy,
    int mods
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`x`	`float`	pointer x position in host-window coordinates
`y`	`float`	pointer y position in host-window coordinates
`window_width`	`float`	logical host-window width
`window_height`	`float`	logical host-window height
`dx`	`float`	horizontal wheel delta
`dy`	`float`	vertical wheel delta
`mods`	`int`	keyboard modifier bit mask

Declared in include/datoviz/app.h:565.

`dvz_view_external_surface()`¶

Create a hosted present view around an externally-owned Vulkan surface.

The caller owns the native event loop and must create the Vulkan surface using the instance extensions passed to dvz_app_with_config(). Datoviz owns only the rendering objects built on top of the supplied surface unless surface->owned_by_datoviz is true.

DvzView * dvz_view_external_surface(
    DvzApp * app,
    DvzFigure * figure,
    const DvzWindowExternalSurfaceInfo * surface
);

Field	Type	Description
return	`DvzView` *	the view handle, or NULL on failure
`app`	`DvzApp` *	the app
`figure`	`DvzFigure` *	the figure to render (borrowed)
`surface`	`const` `DvzWindowExternalSurfaceInfo` *	external Vulkan surface description

Declared in include/datoviz/app_interop.h:61.

`dvz_view_fly()`¶

Create, bind, and connect a fly controller for one panel.

DvzFly * dvz_view_fly(
    DvzView * view,
    DvzPanel * panel,
    const DvzFlyDesc * desc
);

Field	Type	Description
return	`DvzFly` *	the fly payload, or NULL on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel
`desc`	`const` `DvzFlyDesc` *	fly descriptor, or NULL for defaults

Declared in include/datoviz/app.h:762.

`dvz_view_framebuffer_size()`¶

Return the current framebuffer view size.

void dvz_view_framebuffer_size(
    const DvzView * view,
    uint32_t * out_width,
    uint32_t * out_height
);

Field	Type	Description
`view`	`const` `DvzView` *	the view
`out_width`	`uint32_t` *	output framebuffer width in physical pixels, may be NULL
`out_height`	`uint32_t` *	output framebuffer height in physical pixels, may be NULL

Declared in include/datoviz/app.h:662.

`dvz_view_gui()`¶

Attach a Dear ImGui overlay to a GLFW view.

DvzGui * dvz_view_gui(
    DvzView * view,
    const DvzGuiConfig * config
);

Field	Type	Description
return	`DvzGui` *	the GUI overlay, or NULL on failure
`view`	`DvzView` *	the view
`config`	`const` `DvzGuiConfig` *	optional GUI configuration

Declared in include/datoviz/gui.h:145.

`dvz_view_input()`¶

Return the input router for a view.

Pass the returned router to dvz_panel_connect_input() to route panel-local input through scene-owned controller bindings. Returns NULL when GPU support is absent.

struct DvzInputRouter * dvz_view_input(
    DvzView * view
);

Field	Type	Description
return	`struct` `DvzInputRouter` *	the input router, or NULL
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:603.

`dvz_view_logical_size()`¶

Return the current logical view size.

void dvz_view_logical_size(
    const DvzView * view,
    uint32_t * out_width,
    uint32_t * out_height
);

Field	Type	Description
`view`	`const` `DvzView` *	the view
`out_width`	`uint32_t` *	output logical width in pixels, may be NULL
`out_height`	`uint32_t` *	output logical height in pixels, may be NULL

Declared in include/datoviz/app.h:651.

`dvz_view_offscreen()`¶

Create an offscreen view for a figure.

The figure's panels and visuals are rendered into an offscreen framebuffer of the given size on every call to dvz_app_run().

DvzView * dvz_view_offscreen(
    DvzApp * app,
    DvzFigure * figure,
    uint32_t width,
    uint32_t height
);

Field	Type	Description
return	`DvzView` *	the view handle, or NULL on failure
`app`	`DvzApp` *	the app
`figure`	`DvzFigure` *	the figure to render (borrowed)
`width`	`uint32_t`	framebuffer width in pixels
`height`	`uint32_t`	framebuffer height in pixels

Declared in include/datoviz/app.h:491.

`dvz_view_panzoom()`¶

Create, bind, and connect a panzoom controller for one panel.

DvzPanzoom * dvz_view_panzoom(
    DvzView * view,
    DvzPanel * panel,
    const DvzPanzoomDesc * desc
);

Field	Type	Description
return	`DvzPanzoom` *	the panzoom payload, or NULL on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel
`desc`	`const` `DvzPanzoomDesc` *	panzoom descriptor, or NULL for defaults

Declared in include/datoviz/app.h:738.

`dvz_view_post()`¶

Post a callback to run on the view owner thread.

The callback is queued from any thread and drained near the start of dvz_view_render_once(). The queue stores the callback pointer and user_data value verbatim; the caller must ensure both remain valid until the callback has run.

DvzResult dvz_view_post(
    DvzView * view,
    DvzViewPostCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on invalid input or queue overflow
`view`	`DvzView` *	the view
`callback`	`DvzViewPostCallback`	callback to run on the owner thread
`user_data`	`void` *	opaque pointer forwarded to the callback

Declared in include/datoviz/app.h:1054.

`dvz_view_record_start()`¶

Start recording emitted scene DRP2 frame streams for a view.

The recording is a .dvzr directory written by the DRP2 linear recorder. Frames are appended from the app draw path after successful runtime execution. Call dvz_view_record_stop() to close the recording before replaying it.

DvzResult dvz_view_record_start(
    DvzView * view,
    const char * path
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`path`	`const` `char` *	output recording directory path

Declared in include/datoviz/app.h:868.

`dvz_view_record_stop()`¶

Stop recording emitted scene DRP2 frame streams for a view.

DvzResult dvz_view_record_stop(
    DvzView * view
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:877.

`dvz_view_release_external_surface()`¶

Release a hosted external surface before the host destroys it.

Clears the request-frame callback, marks the surface temporarily unavailable, and runs one render-once step so the present swapchain observes the unavailable surface and releases borrowed surface-dependent objects. The host remains responsible for destroying the VkSurfaceKHR.

int dvz_view_release_external_surface(
    DvzView * view
);

Field	Type	Description
return	`int`	DVZ_CANVAS_FRAME_WAIT_SURFACE on clean release, or a negative error code
`view`	`DvzView` *	view created with dvz_view_external_surface()

Declared in include/datoviz/app_interop.h:90.

`dvz_view_render_enabled()`¶

Return whether rendering is enabled for a view.

_Bool dvz_view_render_enabled(
    const DvzView * view
);

Field	Type	Description
return	`_Bool`	whether rendering is enabled
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:1013.

`dvz_view_render_once()`¶

Render one frame for a single view without polling any Datoviz-owned event loop.

This is the primary hosted-loop primitive for Qt, SDL, Tk, IPython, and other integrations where the caller owns scheduling. Returns the dvz_canvas_frame() status when no frame was submitted. Disabled views are skipped and return DVZ_CANVAS_FRAME_READY without submitting.

int dvz_view_render_once(
    DvzView * view
);

Field	Type	Description
return	`int`	DVZ_CANVAS_FRAME_READY after a submitted frame, DVZ_CANVAS_FRAME_WAIT_SURFACE while the surface is unavailable, after a disabled-view no-op, or a negative error code
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:1109.

`dvz_view_render_scale()`¶

Return the current render scale.

float dvz_view_render_scale(
    const DvzView * view
);

Field	Type	Description
return	`float`	render scale, defaulting to 1
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:684.

`dvz_view_replay_frame_count()`¶

Return the number of frames in the active replay recording.

uint32_t dvz_view_replay_frame_count(
    const DvzView * view
);

Field	Type	Description
return	`uint32_t`	replay frame count, or 0 when no replay is active
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:942.

`dvz_view_replay_set_loop()`¶

Enable or disable replay looping.

Looping resets the app DRP2 runtime before replay starts from frame zero again.

DvzResult dvz_view_replay_set_loop(
    DvzView * view,
    _Bool loop
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`loop`	`_Bool`	whether the recording should loop

Declared in include/datoviz/app.h:933.

`dvz_view_replay_set_paced()`¶

Enable or disable timestamp-paced replay.

DvzResult dvz_view_replay_set_paced(
    DvzView * view,
    _Bool paced
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`paced`	`_Bool`	whether replay waits for recorded timestamps

Declared in include/datoviz/app.h:909.

`dvz_view_replay_set_speed()`¶

Set replay speed multiplier.

Values below or equal to zero are ignored. A value of 2 plays twice as fast.

DvzResult dvz_view_replay_set_speed(
    DvzView * view,
    double speed
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`speed`	`double`	replay speed multiplier

Declared in include/datoviz/app.h:921.

`dvz_view_replay_start()`¶

Start live replay of a DRP2 recording in a view.

The replay path executes recorded DRP2 frame streams directly. App recordings render into the current view frame by attaching that borrowed frame under the recording's target id.

DvzResult dvz_view_replay_start(
    DvzView * view,
    const char * path
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`path`	`const` `char` *	input `.dvzr` recording directory

Declared in include/datoviz/app.h:890.

`dvz_view_replay_stop()`¶

Stop live replay and release the loaded recording.

DvzResult dvz_view_replay_stop(
    DvzView * view
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:899.

`dvz_view_request_frame()`¶

Request that the host schedules another frame for a view.

Hosted UI adapters should map the registered callback to their native repaint primitive, for example QWindow::requestUpdate(), QWidget::update(), an SDL wakeup, or a Tk idle callback.

DvzResult dvz_view_request_frame(
    DvzView * view
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:1025.

`dvz_view_resize()`¶

Resize a view's logical and framebuffer extent.

Intended for offscreen or externally-hosted windows whose size is controlled by another UI toolkit. GLFW windows should normally be resized by the platform window itself.

DvzResult dvz_view_resize(
    DvzView * view,
    uint32_t width,
    uint32_t height
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`width`	`uint32_t`	width in pixels
`height`	`uint32_t`	height in pixels

Declared in include/datoviz/app.h:956.

`dvz_view_resize_scaled()`¶

Resize a view with distinct logical and framebuffer dimensions.

This is intended for hosted/offscreen views displayed in a higher-DPI container. The figure uses logical dimensions while the canvas renders into framebuffer dimensions derived from the device scale.

DvzResult dvz_view_resize_scaled(
    DvzView * view,
    uint32_t logical_width,
    uint32_t logical_height,
    float device_scale
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`logical_width`	`uint32_t`	logical width in pixels
`logical_height`	`uint32_t`	logical height in pixels
`device_scale`	`float`	physical pixels per logical pixel

Declared in include/datoviz/app.h:972.

`dvz_view_resize_scaled_xy()`¶

Resize a view with distinct logical dimensions and per-axis device scale.

This is intended for hosted/offscreen views displayed in a container whose X and Y device scales differ. Most callers should use dvz_view_resize_scaled() when the scale is uniform.

DvzResult dvz_view_resize_scaled_xy(
    DvzView * view,
    uint32_t logical_width,
    uint32_t logical_height,
    float device_scale_x,
    float device_scale_y
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	the view
`logical_width`	`uint32_t`	logical width in pixels
`logical_height`	`uint32_t`	logical height in pixels
`device_scale_x`	`float`	physical pixels per logical pixel along X
`device_scale_y`	`float`	physical pixels per logical pixel along Y

Declared in include/datoviz/app.h:989.

`dvz_view_resolved_size()`¶

Return the current resolved view size contract.

DvzResolvedViewSize dvz_view_resolved_size(
    const DvzView * view
);

Field	Type	Description
return	`DvzResolvedViewSize`	resolved view size metrics, or zeroed metrics on invalid input
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:640.

`dvz_view_set_frame_callback()`¶

Register a callback invoked after each successful frame for one view.

The callback runs after the scene frame artifact has been emitted, executed, request processing has completed, and the artifact-owned stream snapshot has been destroyed. Scene mutations from the callback are therefore allowed and become visible on the next frame. The callback and user data are retained until replaced, cleared, or the view is destroyed; the caller must keep them valid for that lifetime.

DvzResult dvz_view_set_frame_callback(
    DvzView * view,
    DvzViewFrameCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`callback`	`DvzViewFrameCallback`	callback pointer, or NULL to clear it
`user_data`	`void` *	opaque pointer forwarded to the callback

Declared in include/datoviz/app.h:1089.

`dvz_view_set_gui_callback()`¶

Register a GUI callback called while building each ImGui frame.

The callback can be registered only after dvz_view_gui() has created the overlay; calling this before overlay creation returns DVZ_ERROR. The callback and user data are retained until replaced, cleared, or the view is destroyed; the caller must keep them valid for that lifetime.

DvzResult dvz_view_set_gui_callback(
    DvzView * view,
    DvzGuiCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`callback`	`DvzGuiCallback`	callback pointer, or NULL to clear it
`user_data`	`void` *	opaque pointer forwarded to the callback

Declared in include/datoviz/gui.h:163.

`dvz_view_set_render_enabled()`¶

Enable or disable rendering for a view.

Disabled windows remain owned by the app but dvz_view_render_once() skips them. This is intended for hosted/offscreen integrations such as hidden dock tabs.

DvzResult dvz_view_set_render_enabled(
    DvzView * view,
    _Bool enabled
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`enabled`	`_Bool`	whether rendering should be enabled

Declared in include/datoviz/app.h:1004.

`dvz_view_set_request_frame_callback()`¶

Register a callback invoked whenever Datoviz requests another frame.

This is a passive scheduling signal: it does not change dvz_app_run() behavior and does not render by itself. The host remains responsible for calling dvz_view_render_once(). The callback and user data are retained until replaced, cleared, or the view is destroyed; the caller must keep them valid for that lifetime.

DvzResult dvz_view_set_request_frame_callback(
    DvzView * view,
    DvzViewRequestFrameCallback callback,
    void * user_data
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`callback`	`DvzViewRequestFrameCallback`	callback pointer, or NULL to clear it
`user_data`	`void` *	opaque pointer forwarded to the callback

Declared in include/datoviz/app.h:1070.

`dvz_view_set_user_scale()`¶

Set the user scale for UI-like scene quantities.

DvzResult dvz_view_set_user_scale(
    DvzView * view,
    float scale
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view
`scale`	`float`	positive user scale

Declared in include/datoviz/app.h:703.

`dvz_view_size()`¶

Return the current view size in an explicit size space.

DvzExtent dvz_view_size(
    const DvzView * view,
    DvzSizeSpace space
);

Field	Type	Description
return	`DvzExtent`	size in the requested space, or zero on invalid input
`view`	`const` `DvzView` *	the view
`space`	`DvzSizeSpace`	requested size space

Declared in include/datoviz/app.h:631.

`dvz_view_size_desc_framebuffer_px()`¶

Return a framebuffer-exact size request.

DvzViewSizeDesc dvz_view_size_desc_framebuffer_px(
    uint32_t width,
    uint32_t height
);

Field	Type	Description
return	`DvzViewSizeDesc`	initialized view size descriptor
`width`	`uint32_t`	framebuffer width in device pixels
`height`	`uint32_t`	framebuffer height in device pixels

Declared in include/datoviz/app.h:406.

`dvz_view_size_desc_host_logical_px()`¶

Return a host-window logical-pixel size request.

DvzViewSizeDesc dvz_view_size_desc_host_logical_px(
    uint32_t width,
    uint32_t height
);

Field	Type	Description
return	`DvzViewSizeDesc`	initialized view size descriptor
`width`	`uint32_t`	host/window logical width
`height`	`uint32_t`	host/window logical height

Declared in include/datoviz/app.h:416.

`dvz_view_size_desc_physical_mm()`¶

Return a physical-millimeter size request.

The canvas/reference extent is derived from the physical target and reference_dpi.

DvzViewSizeDesc dvz_view_size_desc_physical_mm(
    double width_mm,
    double height_mm,
    double reference_dpi
);

Field	Type	Description
return	`DvzViewSizeDesc`	initialized view size descriptor
`width_mm`	`double`	target width in millimeters
`height_mm`	`double`	target height in millimeters
`reference_dpi`	`double`	reference pixels per inch, or <= 0 for 96

Declared in include/datoviz/app.h:446.

`dvz_view_size_desc_reference_px()`¶

Return a reference-pixel size request.

Reference pixels are CSS-like canvas units. A reference-pixel canvas targets a physical size of width/reference_dpi by height/reference_dpi inches when live-window physical metrics are available.

DvzViewSizeDesc dvz_view_size_desc_reference_px(
    double width,
    double height,
    double reference_dpi
);

Field	Type	Description
return	`DvzViewSizeDesc`	initialized view size descriptor
`width`	`double`	canvas/reference width
`height`	`double`	canvas/reference height
`reference_dpi`	`double`	reference pixels per inch, or <= 0 for 96

Declared in include/datoviz/app.h:432.

`dvz_view_size_resolve()`¶

Resolve a size descriptor without creating a view.

This deterministic resolver uses descriptor overrides only. Live-window backend metrics may refine the final resolved size after view creation; query that with dvz_view_resolved_size().

DvzResolvedViewSize dvz_view_size_resolve(
    const DvzViewSizeDesc * desc,
    DvzViewKind kind
);

Field	Type	Description
return	`DvzResolvedViewSize`	resolved size metrics
`desc`	`const` `DvzViewSizeDesc` *	size descriptor
`kind`	`DvzViewKind`	target view kind

Declared in include/datoviz/app.h:460.

`dvz_view_turntable()`¶

Create, bind, and connect a turntable controller for one panel.

DvzTurntable * dvz_view_turntable(
    DvzView * view,
    DvzPanel * panel,
    const DvzTurntableDesc * desc
);

Field	Type	Description
return	`DvzTurntable` *	the turntable payload, or NULL on validation error
`view`	`DvzView` *	the view
`panel`	`DvzPanel` *	the panel
`desc`	`const` `DvzTurntableDesc` *	turntable descriptor, or NULL for defaults

Declared in include/datoviz/app.h:773.

`dvz_view_update_external_surface()`¶

Update the hosted external surface associated with a view.

Use this when the host toolkit recreates or resizes its native surface. A NULL surface handle is accepted to mark the surface temporarily unavailable; rendering then returns DVZ_CANVAS_FRAME_WAIT_SURFACE until a valid surface is supplied again.

DvzResult dvz_view_update_external_surface(
    DvzView * view,
    const DvzWindowExternalSurfaceInfo * surface
);

Field	Type	Description
return	`DvzResult`	0 on success, negative on error
`view`	`DvzView` *	view created with dvz_view_external_surface()
`surface`	`const` `DvzWindowExternalSurfaceInfo` *	external Vulkan surface description

Declared in include/datoviz/app_interop.h:76.

`dvz_view_user_scale()`¶

Return the current user scale for UI-like scene quantities.

float dvz_view_user_scale(
    const DvzView * view
);

Field	Type	Description
return	`float`	user scale, defaulting to 1
`view`	`const` `DvzView` *	the view

Declared in include/datoviz/app.h:693.

`dvz_view_wake()`¶

Wake the host scheduler for a view.

This function is safe to call from another thread. It requests scheduler attention without executing user-posted callbacks immediately; posted callbacks are drained on the view owner thread by dvz_view_render_once().

DvzResult dvz_view_wake(
    DvzView * view
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success, DVZ_ERROR on validation error
`view`	`DvzView` *	the view

Declared in include/datoviz/app.h:1038.

`dvz_view_window()`¶

Create an interactive native-window view for a figure.

Opens a visible window backed by a present (swapchain) canvas. The frame loop started by dvz_app_run(app, 0) drives rendering until the user closes the window.

Uses the configured native window backend. Returns NULL when the backend is unavailable, no display is available, or window creation fails.

DvzView * dvz_view_window(
    DvzApp * app,
    DvzFigure * figure,
    uint32_t width,
    uint32_t height,
    const char * title
);

Field	Type	Description
return	`DvzView` *	the view handle, or NULL on failure
`app`	`DvzApp` *	the app
`figure`	`DvzFigure` *	the figure to render (borrowed)
`width`	`uint32_t`	window width in pixels
`height`	`uint32_t`	window height in pixels
`title`	`const` `char` *	window title string, or NULL for a default title

Declared in include/datoviz/app.h:510.

Types

DvzView · typedef

typedef struct DvzView DvzView;

Declared in include/datoviz/app.h:44.

DvzViewDesc · record

struct DvzViewDesc {
    uint32_t struct_size;
    uint32_t flags;
    DvzViewKind kind;
    DvzViewSizePolicy size_policy;
    double size_width;
    double size_height;
    double size_reference_dpi;
    double size_requested_device_scale;
    double size_monitor_dpi_x_override;
    double size_monitor_dpi_y_override;
    _Bool size_strict_framebuffer_size;
    float device_scale;
    float user_scale;
    float render_scale;
    const char * title;
    _Bool has_position;
    int32_t x;
    int32_t y;
};

Declared in include/datoviz/app.h:237.

DvzViewFrameCallback · typedef

typedef void (*)(DvzView *, void *) DvzViewFrameCallback;

Declared in include/datoviz/app.h:58.

DvzViewKind · enum

enum DvzViewKind {
    DVZ_VIEW_OFFSCREEN = 0,
    DVZ_VIEW_WINDOW = 1,
    DVZ_VIEW_EXTERNAL_SURFACE = 2,
};

Declared in include/datoviz/app.h:92.

DvzViewPostCallback · typedef

typedef void (*)(DvzView *, void *) DvzViewPostCallback;

Declared in include/datoviz/app.h:60.

DvzViewRequestFrameCallback · typedef

typedef void (*)(DvzView *, void *) DvzViewRequestFrameCallback;

Declared in include/datoviz/app.h:59.

DvzViewSizeDesc · record

struct DvzViewSizeDesc {
    uint32_t struct_size;
    uint32_t flags;
    DvzViewSizePolicy policy;
    double width;
    double height;
    double reference_dpi;
    double requested_device_scale;
    double monitor_dpi_x_override;
    double monitor_dpi_y_override;
    _Bool strict_framebuffer_size;
};

Declared in include/datoviz/app.h:188.

DvzViewSizePolicy · enum

enum DvzViewSizePolicy {
    DVZ_VIEW_SIZE_FRAMEBUFFER_PX = 0,
    DVZ_VIEW_SIZE_HOST_LOGICAL_PX = 1,
    DVZ_VIEW_SIZE_REFERENCE_PX = 2,
    DVZ_VIEW_SIZE_PHYSICAL_MM = 3,
};

Declared in include/datoviz/app.h:100.

Window Hosting¶

Functions

`dvz_window_backend_emit_resize()`¶

Emit a resize event and refresh the cached surface state.

void dvz_window_backend_emit_resize(
    DvzWindow * window,
    uint32_t framebuffer_width,
    uint32_t framebuffer_height,
    uint32_t window_width,
    uint32_t window_height,
    float content_scale_x,
    float content_scale_y
);

Field	Type	Description
`window`	`DvzWindow` *	window whose router receives the event
`framebuffer_width`	`uint32_t`	framebuffer width in pixels
`framebuffer_height`	`uint32_t`	framebuffer height in pixels
`window_width`	`uint32_t`	logical window width
`window_height`	`uint32_t`	logical window height
`content_scale_x`	`float`	horizontal content scale
`content_scale_y`	`float`	vertical content scale

Declared in include/datoviz/window/backend.h:312.

`dvz_window_backend_emit_scale()`¶

Emit a content scale event.

void dvz_window_backend_emit_scale(
    DvzWindow * window,
    float content_scale_x,
    float content_scale_y
);

Field	Type	Description
`window`	`DvzWindow` *	window whose router receives the event
`content_scale_x`	`float`	horizontal content scale
`content_scale_y`	`float`	vertical content scale

Declared in include/datoviz/window/backend.h:326.

`dvz_window_backend_handle()`¶

Retrieve the backend-specific handle stored with the window.

void * dvz_window_backend_handle(
    const DvzWindow * window
);

Field	Type	Description
return	`void` *	the borrowed pointer previously set with dvz_window_backend_set_handle(), or NULL
`window`	`const` `DvzWindow` *	window queried for the handle

Declared in include/datoviz/window/backend.h:168.

`dvz_window_backend_payload()`¶

Retrieve backend payload associated with the window.

void * dvz_window_backend_payload(
    const DvzWindow * window
);

Field	Type	Description
return	`void` *	the borrowed backend payload pointer, or NULL
`window`	`const` `DvzWindow` *	window queried for payload

Declared in include/datoviz/window/backend.h:190.

`dvz_window_backend_router()`¶

Access the router attached to the window.

DvzInputRouter * dvz_window_backend_router(
    DvzWindow * window
);

Field	Type	Description
return	`DvzInputRouter` *	the borrowed router used for input emission, valid until window destruction
`window`	`DvzWindow` *	window that owns the router

Declared in include/datoviz/window/backend.h:136.

`dvz_window_backend_set_handle()`¶

Store a backend-specific handle on the window.

The window stores the pointer without taking ownership.

void dvz_window_backend_set_handle(
    DvzWindow * window,
    void * handle
);

Field	Type	Description
`window`	`DvzWindow` *	target window
`handle`	`void` *	borrowed native handle managed by the backend, or NULL

Declared in include/datoviz/window/backend.h:158.

`dvz_window_backend_set_payload()`¶

Store additional backend data on the window.

The window stores the pointer without taking ownership.

void dvz_window_backend_set_payload(
    DvzWindow * window,
    void * payload
);

Field	Type	Description
`window`	`DvzWindow` *	window to mutate
`payload`	`void` *	borrowed opaque backend payload pointer, or NULL

Declared in include/datoviz/window/backend.h:180.

`dvz_window_backend_surface()`¶

Access the surface description for mutation.

DvzWindowSurface * dvz_window_backend_surface(
    DvzWindow * window
);

Field	Type	Description
return	`DvzWindowSurface` *	mutable borrowed surface storage, valid until window destruction
`window`	`DvzWindow` *	window whose surface is requested

Declared in include/datoviz/window/backend.h:146.

`dvz_window_backend_type()`¶

Return the backend currently serving the window.

DvzBackend dvz_window_backend_type(
    const DvzWindow * window
);

Field	Type	Description
return	`DvzBackend`	backend identifier (GLFW, OFFSCREEN, etc.)
`window`	`const` `DvzWindow` *	window whose backend is requested

Declared in include/datoviz/window.h:215.

`dvz_window_config()`¶

Return the default configuration used when callers pass NULL.

DvzWindowConfig dvz_window_config(void);

Field	Type	Description
return	`DvzWindowConfig`	sensible defaults (width, height, title, scale)

Related: dvz_window_create().

Declared in include/datoviz/window.h:117.

`dvz_window_create()`¶

Create a window using the preferred backend.

DvzWindow * dvz_window_create(
    DvzWindowHost * host,
    DvzBackend backend,
    const DvzWindowConfig * config
);

Field	Type	Description
return	`DvzWindow` *	pointer to the created window or NULL on failure
`host`	`DvzWindowHost` *	host that manages the window
`backend`	`DvzBackend`	preferred backend (falls back to DVZ_BACKEND_OFFSCREEN when available)
`config`	`const` `DvzWindowConfig` *	window configuration or NULL for defaults

Related: dvz_window_destroy().

Declared in include/datoviz/window.h:129.

`dvz_window_destroy()`¶

Destroy a window and free backend resources.

void dvz_window_destroy(
    DvzWindow * window
);

Field	Type	Description
`window`	`DvzWindow` *	window returned by dvz_window_create()

Related: dvz_window_create().

Declared in include/datoviz/window.h:139.

`dvz_window_external_surface_info()`¶

Return a default external-surface descriptor.

DvzWindowExternalSurfaceInfo dvz_window_external_surface_info(void);

Field	Type	Description
return	`DvzWindowExternalSurfaceInfo`	zeroed surface descriptor with a valid ABI prologue

Declared in include/datoviz/window/backend.h:127.

`dvz_window_frame_pending()`¶

Check whether a pending frame has yet to be processed.

_Bool dvz_window_frame_pending(
    const DvzWindow * window
);

Field	Type	Description
return	`_Bool`	true if dvz_window_host_request_frame() is still outstanding
`window`	`const` `DvzWindow` *	window to query

Declared in include/datoviz/window.h:205.

`dvz_window_glfw_init()`¶

Initialize GLFW so instance extensions can be queried before a window exists.

_Bool dvz_window_glfw_init(void);

Field	Type	Description
return	`_Bool`	true when GLFW is initialized, false when the backend is unavailable

Declared in include/datoviz/window/backend.h:198.

`dvz_window_glfw_set_input_callbacks()`¶

Register raw GLFW input callbacks for integrations that must see events before Datoviz routing.

These callbacks are only used by GLFW windows. A callback returning true consumes the event and prevents the corresponding Datoviz pointer/keyboard event from being emitted. The callback table is copied, but user_data is borrowed and must remain valid until the callbacks are replaced, cleared, or the window is destroyed.

void dvz_window_glfw_set_input_callbacks(
    DvzWindow * window,
    const DvzWindowGlfwInputCallbacks * callbacks,
    void * user_data
);

Field	Type	Description
`window`	`DvzWindow` *	target window
`callbacks`	`const` `DvzWindowGlfwInputCallbacks` *	callback table, or NULL to clear it
`user_data`	`void` *	borrowed opaque pointer forwarded to every callback

Declared in include/datoviz/window/backend.h:214.

`dvz_window_host()`¶

Create a window host that stores available backends and owned windows.

DvzWindowHost * dvz_window_host(void);

Field	Type	Description
return	`DvzWindowHost` *	a newly allocated host, or NULL on allocation failure

Declared in include/datoviz/window.h:44.

`dvz_window_host_destroy()`¶

Destroy a window host and all windows associated with it.

void dvz_window_host_destroy(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host returned by dvz_window_host(), or NULL

Declared in include/datoviz/window.h:53.

`dvz_window_host_poll()`¶

Poll every registered backend for events.

void dvz_window_host_poll(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host whose backends should be polled

Declared in include/datoviz/window.h:77.

`dvz_window_host_register_backend()`¶

Register a backend so it can be used during window creation.

The descriptor is copied into the host. Pointers stored inside it, including name, user_data, and callback-dependent state, remain borrowed and must outlive the host or be unregistered only by destroying the host.

void dvz_window_host_register_backend(
    DvzWindowHost * host,
    const DvzWindowBackend * backend
);

Field	Type	Description
`host`	`DvzWindowHost` *	host that receives the backend
`backend`	`const` `DvzWindowBackend` *	backend descriptor containing the callback table and borrowed state

Declared in include/datoviz/window.h:67.

`dvz_window_host_request_frame()`¶

Request a frame for the given window.

void dvz_window_host_request_frame(
    DvzWindowHost * host,
    DvzWindow * window
);

Field	Type	Description
`host`	`DvzWindowHost` *	hosting the window
`window`	`DvzWindow` *	window requiring a new frame

Declared in include/datoviz/window.h:104.

`dvz_window_host_required_extension_count()`¶

Query the required Vulkan instance extension count for a backend.

uint32_t dvz_window_host_required_extension_count(
    DvzWindowHost * host,
    DvzBackend backend
);

Field	Type	Description
return	`uint32_t`	required extension count, or 0 on unavailable backend
`host`	`DvzWindowHost` *	host that contains the backend registry
`backend`	`DvzBackend`	backend to query

Declared in include/datoviz/window/backend.h:280.

`dvz_window_host_required_extensions()`¶

Query backend-required Vulkan instance extension names.

The returned names are borrowed from backend state and remain valid until that backend state is reconfigured or the host is destroyed.

int dvz_window_host_required_extensions(
    DvzWindowHost * host,
    DvzBackend backend,
    uint32_t capacity,
    const char ** out_extensions
);

Field	Type	Description
return	`int`	number of names written, or -1 on invalid input/backend unavailable
`host`	`DvzWindowHost` *	host that contains the backend registry
`backend`	`DvzBackend`	backend to query
`capacity`	`uint32_t`	maximum number of names that can be written in out_extensions
`out_extensions`	`const` `char` **	output array receiving borrowed extension-name pointers

Declared in include/datoviz/window/backend.h:296.

`dvz_window_host_wait()`¶

Wait for backend events, blocking until an event is available when supported.

void dvz_window_host_wait(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host whose backends should wait for events

Declared in include/datoviz/window.h:85.

`dvz_window_host_wait_timeout()`¶

Wait for backend events with a timeout.

void dvz_window_host_wait_timeout(
    DvzWindowHost * host,
    double seconds
);

Field	Type	Description
`host`	`DvzWindowHost` *	host whose backends should wait for events
`seconds`	`double`	maximum wait duration in seconds

Declared in include/datoviz/window.h:94.

`dvz_window_metrics()`¶

Return the cached logical/native/surface metrics for the window.

The returned storage is updated in place when the window metrics change and must not be freed.

const DvzWindowMetrics * dvz_window_metrics(
    const DvzWindow * window
);

Field	Type	Description
return	`const` `DvzWindowMetrics` *	the borrowed metrics data, valid until window destruction
`window`	`const` `DvzWindow` *	window to query

Declared in include/datoviz/window.h:162.

`dvz_window_register_glfw_backend()`¶

Register the GLFW backend on the host.

void dvz_window_register_glfw_backend(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host that should expose the GLFW backend

Declared in include/datoviz/window/backend.h:348.

`dvz_window_register_headless_backend()`¶

Register the built-in headless backend on the host.

void dvz_window_register_headless_backend(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host that should expose the headless backend

Declared in include/datoviz/window/backend.h:339.

`dvz_window_register_wrap_backend()`¶

Register the built-in wrap backend on the host.

void dvz_window_register_wrap_backend(
    DvzWindowHost * host
);

Field	Type	Description
`host`	`DvzWindowHost` *	host that should expose the wrap backend

Declared in include/datoviz/window/backend.h:357.

`dvz_window_router()`¶

Retrieve the router used to emit input events for the window.

DvzInputRouter * dvz_window_router(
    DvzWindow * window
);

Field	Type	Description
return	`DvzInputRouter` *	the borrowed input router, valid until window destruction
`window`	`DvzWindow` *	window owning the router

Declared in include/datoviz/window.h:172.

`dvz_window_set_user_data()`¶

Store an opaque user data pointer on the window.

The window does not take ownership. The pointer must remain valid for every callback that uses it, until replaced or the window is destroyed.

void dvz_window_set_user_data(
    DvzWindow * window,
    void * user_data
);

Field	Type	Description
`window`	`DvzWindow` *	destination window
`user_data`	`void` *	borrowed pointer copied verbatim, or NULL to clear it

Declared in include/datoviz/window.h:185.

`dvz_window_should_close()`¶

Return whether the window has been requested to close by the user or OS.

Returns false for backends that have no interactive close signal (headless, offscreen).

_Bool dvz_window_should_close(
    const DvzWindow * window
);

Field	Type	Description
return	`_Bool`	true if the window should be closed
`window`	`const` `DvzWindow` *	window to query

Declared in include/datoviz/window.h:227.

`dvz_window_surface()`¶

Return the cached surface information for the window.

The returned storage is updated in place when the backend surface changes and must not be freed.

const DvzWindowSurface * dvz_window_surface(
    const DvzWindow * window
);

Field	Type	Description
return	`const` `DvzWindowSurface` *	the borrowed surface data, valid until window destruction
`window`	`const` `DvzWindow` *	window to query

Declared in include/datoviz/window.h:151.

`dvz_window_user_data()`¶

Read the user data pointer previously stored on a window.

void * dvz_window_user_data(
    const DvzWindow * window
);

Field	Type	Description
return	`void` *	the borrowed pointer passed to dvz_window_set_user_data(), or NULL
`window`	`const` `DvzWindow` *	window queried for user data

Declared in include/datoviz/window.h:195.

`dvz_window_wrap_attach_surface()`¶

Attach an externally-created Vulkan surface to a wrap window.

When info->owned_by_datoviz is false, the instance and surface remain caller-owned and must outlive their attachment. When true, Datoviz destroys the surface on replacement, detachment, or window destruction; the Vulkan instance always remains caller-owned and must outlive the surface.

int dvz_window_wrap_attach_surface(
    DvzWindow * window,
    const DvzWindowExternalSurfaceInfo * info
);

Field	Type	Description
return	`int`	0 on success, -1 on invalid args/backend mismatch/invalid handles
`window`	`DvzWindow` *	target window created with DVZ_BACKEND_WRAP
`info`	`const` `DvzWindowExternalSurfaceInfo` *	external surface description copied into the window

Declared in include/datoviz/window/backend.h:244.

`dvz_window_wrap_detach_surface()`¶

Detach the external Vulkan surface from a wrap window.

void dvz_window_wrap_detach_surface(
    DvzWindow * window
);

Field	Type	Description
`window`	`DvzWindow` *	target window created with DVZ_BACKEND_WRAP

Declared in include/datoviz/window/backend.h:268.

`dvz_window_wrap_set_required_extensions()`¶

Configure the required Vulkan instance extensions for the wrap backend.

int dvz_window_wrap_set_required_extensions(
    DvzWindowHost * host,
    uint32_t count,
    const char *const * extensions
);

Field	Type	Description
return	`int`	0 on success, -1 on invalid input or allocation failure
`host`	`DvzWindowHost` *	host that owns the wrap backend state
`count`	`uint32_t`	number of extension names passed in extensions
`extensions`	`const` `char` `const`	extension-name array copied by the host, or NULL when count is zero

Declared in include/datoviz/window/backend.h:228.

`dvz_window_wrap_update_surface()`¶

Update the externally-managed Vulkan surface associated with a wrap window.

Ownership of the old and replacement surfaces follows each descriptor's owned_by_datoviz value. Passing matching null handles reports temporary surface loss.

int dvz_window_wrap_update_surface(
    DvzWindow * window,
    const DvzWindowExternalSurfaceInfo * info
);

Field	Type	Description
return	`int`	0 on success, -1 on invalid args/backend mismatch/rejected update
`window`	`DvzWindow` *	target window created with DVZ_BACKEND_WRAP
`info`	`const` `DvzWindowExternalSurfaceInfo` *	replacement surface description copied into the window

Declared in include/datoviz/window/backend.h:259.

Types

DvzBackend · enum

enum DvzBackend {
    DVZ_BACKEND_NONE = 0,
    DVZ_BACKEND_GLFW = 1,
    DVZ_BACKEND_QT = 2,
    DVZ_BACKEND_OFFSCREEN = 3,
    DVZ_BACKEND_WRAP = 4,
};

Declared in include/datoviz/runner/enums.h:20.

DvzHiDpiPolicy · enum

enum DvzHiDpiPolicy {
    DVZ_HIDPI_AUTO = 0,
    DVZ_HIDPI_DISABLED = 1,
    DVZ_HIDPI_FRAMEBUFFER = 2,
    DVZ_HIDPI_NATIVE_WINDOW = 3,
    DVZ_HIDPI_EXTERNAL = 4,
};

Declared in include/datoviz/window/types.h:57.

DvzWindow · typedef

typedef struct DvzWindow DvzWindow;

Declared in include/datoviz/window/types.h:46.

DvzWindowBackend · record

struct DvzWindowBackend {
    const char * name;
    DvzBackend type;
    void * user_data;
    DvzWindowBackendProcs procs;
};

Declared in include/datoviz/window/backend.h:81.

DvzWindowBackendCreate · typedef

typedef _Bool (*)(DvzWindowBackend *, DvzWindow *, const DvzWindowConfig *) DvzWindowBackendCreate;

Declared in include/datoviz/window/backend.h:36.

DvzWindowBackendDestroy · typedef

typedef void (*)(DvzWindowBackend *, DvzWindow *) DvzWindowBackendDestroy;

Declared in include/datoviz/window/backend.h:38.

DvzWindowBackendPoll · typedef

typedef void (*)(DvzWindowBackend *, DvzWindowHost *) DvzWindowBackendPoll;

Declared in include/datoviz/window/backend.h:39.

DvzWindowBackendProbe · typedef

typedef _Bool (*)(DvzWindowBackend *, DvzWindowHost *) DvzWindowBackendProbe;

Declared in include/datoviz/window/backend.h:35.

DvzWindowBackendProcs · record

struct DvzWindowBackendProcs {
    DvzWindowBackendProbe probe;
    DvzWindowBackendCreate create;
    DvzWindowBackendDestroy destroy;
    DvzWindowBackendPoll poll;
    DvzWindowBackendWait wait;
    DvzWindowBackendWaitTimeout wait_timeout;
    DvzWindowBackendRequestFrame request_frame;
    DvzWindowBackendShouldClose should_close;
    DvzWindowBackendRequiredExtensionCount required_extension_count;
    DvzWindowBackendRequiredExtensionAt required_extension_at;
};

Declared in include/datoviz/window/backend.h:65.

DvzWindowBackendRequestFrame · typedef

typedef void (*)(DvzWindowBackend *, DvzWindow *) DvzWindowBackendRequestFrame;

Declared in include/datoviz/window/backend.h:43.

DvzWindowBackendRequiredExtensionAt · typedef

typedef const char *(*)(DvzWindowBackend *, DvzWindowHost *, uint32_t) DvzWindowBackendRequiredExtensionAt;

Declared in include/datoviz/window/backend.h:48.

DvzWindowBackendRequiredExtensionCount · typedef

typedef uint32_t (*)(DvzWindowBackend *, DvzWindowHost *) DvzWindowBackendRequiredExtensionCount;

Declared in include/datoviz/window/backend.h:46.

DvzWindowBackendShouldClose · typedef

typedef _Bool (*)(const DvzWindowBackend *, const DvzWindow *) DvzWindowBackendShouldClose;

Declared in include/datoviz/window/backend.h:44.

DvzWindowBackendWait · typedef

typedef void (*)(DvzWindowBackend *, DvzWindowHost *) DvzWindowBackendWait;

Declared in include/datoviz/window/backend.h:40.

DvzWindowBackendWaitTimeout · typedef

typedef void (*)(DvzWindowBackend *, DvzWindowHost *, double) DvzWindowBackendWaitTimeout;

Declared in include/datoviz/window/backend.h:41.

DvzWindowConfig · record

struct DvzWindowConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t width;
    uint32_t height;
    const char * title;
    _Bool resizable;
    _Bool visible;
    float user_scale;
    DvzHiDpiPolicy hidpi_policy;
    _Bool has_position;
    int32_t x;
    int32_t y;
};

Declared in include/datoviz/window/types.h:72.

DvzWindowExternalSurfaceInfo · record

struct DvzWindowExternalSurfaceInfo {
    uint32_t struct_size;
    uint32_t flags;
    VkInstance instance;
    VkSurfaceKHR surface;
    VkExtent2D extent;
    float scale_x;
    float scale_y;
    _Bool owned_by_datoviz;
};

Declared in include/datoviz/window/backend.h:91.

DvzWindowGlfwCharCallback · typedef

typedef _Bool (*)(DvzWindow *, uint32_t, void *) DvzWindowGlfwCharCallback;

Declared in include/datoviz/window/backend.h:57.

DvzWindowGlfwCursorPosCallback · typedef

typedef _Bool (*)(DvzWindow *, double, double, void *) DvzWindowGlfwCursorPosCallback;

Declared in include/datoviz/window/backend.h:50.

DvzWindowGlfwInputCallbacks · record

struct DvzWindowGlfwInputCallbacks {
    DvzWindowGlfwCursorPosCallback cursor_pos;
    DvzWindowGlfwMouseButtonCallback mouse_button;
    DvzWindowGlfwScrollCallback scroll;
    DvzWindowGlfwKeyCallback key;
    DvzWindowGlfwCharCallback character;
};

Declared in include/datoviz/window/backend.h:105.

DvzWindowGlfwKeyCallback · typedef

typedef _Bool (*)(DvzWindow *, int, int, int, int, void *) DvzWindowGlfwKeyCallback;

Declared in include/datoviz/window/backend.h:55.

DvzWindowGlfwMouseButtonCallback · typedef

typedef _Bool (*)(DvzWindow *, int, int, int, void *) DvzWindowGlfwMouseButtonCallback;

Declared in include/datoviz/window/backend.h:51.

DvzWindowGlfwScrollCallback · typedef

typedef _Bool (*)(DvzWindow *, double, double, void *) DvzWindowGlfwScrollCallback;

Declared in include/datoviz/window/backend.h:53.

DvzWindowHost · typedef

typedef struct DvzWindowHost DvzWindowHost;

Declared in include/datoviz/app.h:55.

DvzWindowMetrics · record

struct DvzWindowMetrics {
    DvzExtent logical_size;
    DvzExtent native_size;
    DvzExtent surface_size;
    DvzExtent render_size;
    DvzScaleXY content_scale;
    DvzScaleXY framebuffer_scale;
    DvzScaleXY device_scale;
    DvzScaleXY native_to_logical;
    DvzHiDpiPolicy active_hidpi_policy;
    uint64_t generation;
};

Declared in include/datoviz/window/types.h:90.

DvzWindowSurface · record

struct DvzWindowSurface {
    VkInstance instance;
    VkSurfaceKHR surface;
    VkExtent2D extent;
    VkFormat format;
    VkColorSpaceKHR color_space;
    float scale_x;
    float scale_y;
};

Declared in include/datoviz/window/types.h:108.

App, Window, And I/O API¶

Symbol Groups¶

Application Lifecycle¶

dvz_app()¶

dvz_app_capture_config()¶

dvz_app_capture_config_from_env()¶

dvz_app_config()¶

dvz_app_destroy()¶

dvz_app_reap_closed_views()¶

dvz_app_render_once()¶

dvz_app_resources()¶

dvz_app_run()¶

dvz_app_should_exit()¶

dvz_app_should_stop()¶

dvz_app_stop()¶

dvz_app_vk_instance()¶

dvz_app_with_config()¶

dvz_app_with_resources()¶

Canvas Execution¶

dvz_canvas_capture_png()¶

dvz_canvas_capture_rgba()¶

dvz_canvas_capture_rgba_into()¶

dvz_canvas_config()¶

dvz_canvas_configure_live_image_sink()¶

dvz_canvas_configure_video_sink()¶

dvz_canvas_create()¶

dvz_canvas_destroy()¶

dvz_canvas_frame()¶

dvz_canvas_input()¶

dvz_canvas_live_image_sink_config()¶

dvz_canvas_offscreen_runtime_state()¶

dvz_canvas_present_runtime_state()¶

dvz_canvas_render_mode()¶

dvz_canvas_set_draw_callback()¶

dvz_canvas_stream()¶

dvz_canvas_submit()¶

dvz_canvas_timings()¶

Display Sizing¶

GUI¶

dvz_gui_begin()¶

dvz_gui_button()¶

dvz_gui_checkbox()¶

dvz_gui_collapsing_header()¶

dvz_gui_color_edit4()¶

dvz_gui_color_edit_dvz()¶

dvz_gui_color_picker4()¶

dvz_gui_combo()¶

dvz_gui_config()¶

dvz_gui_current_window_docked()¶

dvz_gui_current_window_rect()¶

dvz_gui_demo()¶

dvz_gui_dock_window_once()¶

dvz_gui_end()¶

dvz_gui_pop_font()¶

dvz_gui_push_mono()¶

dvz_gui_range_float()¶

dvz_gui_same_line()¶

dvz_gui_separator_text()¶

dvz_gui_slider_float()¶

dvz_gui_slider_float2()¶

dvz_gui_slider_float3()¶

dvz_gui_slider_float4()¶

dvz_gui_slider_float_format()¶

dvz_gui_slider_int()¶

dvz_gui_slider_range_float()¶

dvz_gui_text()¶

dvz_gui_viewport()¶

dvz_gui_viewport_config()¶

dvz_gui_viewport_destroy()¶

dvz_gui_viewport_from_window()¶

dvz_gui_viewport_input()¶

dvz_gui_viewport_mouse()¶

dvz_gui_viewport_window()¶

Input Routing¶

dvz_input_emit_event()¶

dvz_input_emit_keyboard()¶

dvz_input_emit_pointer()¶

dvz_input_emit_resize()¶

dvz_input_emit_scale()¶

dvz_input_router()¶

`dvz_app()`¶

`dvz_app_capture_config()`¶

`dvz_app_capture_config_from_env()`¶

`dvz_app_config()`¶

`dvz_app_destroy()`¶

`dvz_app_reap_closed_views()`¶

`dvz_app_render_once()`¶

`dvz_app_resources()`¶

`dvz_app_run()`¶

`dvz_app_should_exit()`¶

`dvz_app_should_stop()`¶

`dvz_app_stop()`¶

`dvz_app_vk_instance()`¶

`dvz_app_with_config()`¶

`dvz_app_with_resources()`¶

`dvz_canvas_capture_png()`¶

`dvz_canvas_capture_rgba()`¶

`dvz_canvas_capture_rgba_into()`¶

`dvz_canvas_config()`¶

`dvz_canvas_configure_live_image_sink()`¶

`dvz_canvas_configure_video_sink()`¶

`dvz_canvas_create()`¶

`dvz_canvas_destroy()`¶

`dvz_canvas_frame()`¶

`dvz_canvas_input()`¶

`dvz_canvas_live_image_sink_config()`¶

`dvz_canvas_offscreen_runtime_state()`¶

`dvz_canvas_present_runtime_state()`¶

`dvz_canvas_render_mode()`¶

`dvz_canvas_set_draw_callback()`¶

`dvz_canvas_stream()`¶

`dvz_canvas_submit()`¶

`dvz_canvas_timings()`¶

`dvz_gui_begin()`¶

`dvz_gui_button()`¶

`dvz_gui_checkbox()`¶

`dvz_gui_collapsing_header()`¶

`dvz_gui_color_edit4()`¶

`dvz_gui_color_edit_dvz()`¶

`dvz_gui_color_picker4()`¶

`dvz_gui_combo()`¶

`dvz_gui_config()`¶

`dvz_gui_current_window_docked()`¶

`dvz_gui_current_window_rect()`¶

`dvz_gui_demo()`¶

`dvz_gui_dock_window_once()`¶

`dvz_gui_end()`¶

`dvz_gui_pop_font()`¶

`dvz_gui_push_mono()`¶

`dvz_gui_range_float()`¶

`dvz_gui_same_line()`¶

`dvz_gui_separator_text()`¶

`dvz_gui_slider_float()`¶

`dvz_gui_slider_float2()`¶

`dvz_gui_slider_float3()`¶

`dvz_gui_slider_float4()`¶

`dvz_gui_slider_float_format()`¶

`dvz_gui_slider_int()`¶

`dvz_gui_slider_range_float()`¶

`dvz_gui_text()`¶

`dvz_gui_viewport()`¶

`dvz_gui_viewport_config()`¶

`dvz_gui_viewport_destroy()`¶

`dvz_gui_viewport_from_window()`¶

`dvz_gui_viewport_input()`¶

`dvz_gui_viewport_mouse()`¶

`dvz_gui_viewport_window()`¶

`dvz_input_emit_event()`¶

`dvz_input_emit_keyboard()`¶

`dvz_input_emit_pointer()`¶

`dvz_input_emit_resize()`¶

`dvz_input_emit_scale()`¶

`dvz_input_router()`¶

`dvz_input_router_destroy()`¶

`dvz_input_router_last_resize()`¶

`dvz_input_subscribe_event()`¶

`dvz_input_subscribe_keyboard()`¶

`dvz_input_subscribe_pointer()`¶

`dvz_input_subscribe_resize()`¶

`dvz_input_subscribe_scale()`¶