Skip to content

Canvas API

Canvas

dvz_canvas_commands()

Create a set of Vulkan command buffers on a given GPU queue.

DvzCommands* dvz_canvas_commands(
    DvzCanvas* canvas, uint32_t queue_idx, uint32_t count);
Parameter Type Description
canvas DvzCanvas* the canvas
queue_idx uint32_t the index of the GPU queue within the GPU context
count uint32_t number of command buffers to create
returns DvzCommands* set of created command buffers

dvz_canvas_clear_color()

Change the background color of a canvas.

void dvz_canvas_clear_color(
    DvzCanvas* canvas, float red, float green, float blue);
Parameter Type Description
canvas DvzCanvas* the canvas
red float the red component, between 0 and 1
green float the green component, between 0 and 1
blue float the blue component, between 0 and 1

Note

A command buffer refill will be triggered so as to record them again with the updated clear color value.

dvz_canvas_size()

Get the canvas size.

void dvz_canvas_size(DvzCanvas* canvas, DvzCanvasSizeType type, uvec2 size);
Parameter Type Description
canvas DvzCanvas* the canvas
type DvzCanvasSizeType the unit of the requested screen size
size uvec2 the size vector filled by this function

dvz_canvas_aspect()

Get the canvas aspect ratio.

double dvz_canvas_aspect(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas
ratio None the canvas aspect ratio (width / height)

dvz_canvas_close_on_esc()

Whether the canvas should close when Escape is pressed.

void dvz_canvas_close_on_esc(DvzCanvas* canvas, bool value);
Parameter Type Description
canvas DvzCanvas* the canvas
value bool the boolean value

dvz_canvas_recreate()

Recreate the canvas GPU resources and swapchain.

void dvz_canvas_recreate(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas to recreate

dvz_canvas_resize()

Resize a canvas.

void dvz_canvas_resize(DvzCanvas* canvas, uint32_t width, uint32_t height);
Parameter Type Description
canvas DvzCanvas* the canvas to resize
width uint32_t the new width
height uint32_t the new height

dvz_canvas_buffers()

Upload fast-changing data to a special mappable buffer at every canvas frame.

void dvz_canvas_buffers(
    DvzCanvas* canvas, DvzBufferRegions br, VkDeviceSize offset,
    VkDeviceSize size, void* data);
Parameter Type Description
canvas DvzCanvas* the canvas
br DvzBufferRegions the buffer regions
offset VkDeviceSize the offset
size VkDeviceSize the data size
data void* the data to upload

This function is used to upload MVP matrices at every frame in the scene interface.

There are several constraints:

  • the buffer must have the uniform mappable type
  • there must be as many buffer regions as there are swapchain images in the canvas
  • this function must be called at every frame.

dvz_canvas_to_refill()

Trigger a canvas refill at the next frame.

void dvz_canvas_to_refill(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

dvz_canvas_to_close()

Close the canvas at the next frame.

void dvz_canvas_to_close(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

dvz_canvases_destroy()

Destroy all canvases.

void dvz_canvases_destroy(DvzContainer* canvases);
Parameter Type Description
canvases DvzContainer* the container with the canvases.

Misc

dvz_viewport_full()

Get the viewport corresponding to the full canvas.

DvzViewport dvz_viewport_full(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas
returns DvzViewport viewport

dvz_viewport_default()

Create a default viewport.

DvzViewport dvz_viewport_default(uint32_t width, uint32_t height);
Parameter Type Description
width uint32_t the framebuffer width
height uint32_t the framebuffer height
returns DvzViewport viewport

Event emitting

dvz_event_mouse_press()

Emit a mouse press event.

void dvz_event_mouse_press(
    DvzCanvas* canvas, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_release()

Emit a mouse release event.

void dvz_event_mouse_release(
    DvzCanvas* canvas, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_move()

Emit a mouse move event.

void dvz_event_mouse_move(DvzCanvas* canvas, vec2 pos, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the current mouse position, in pixels
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_wheel()

Emit a mouse wheel event.

void dvz_event_mouse_wheel(
    DvzCanvas* canvas, vec2 pos, vec2 dir, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the current mouse position, in pixels
dir vec2 the mouse wheel direction
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_click()

Emit a mouse click event.

void dvz_event_mouse_click(
    DvzCanvas* canvas, vec2 pos, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the click position
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_double_click()

Emit a mouse double-click event.

void dvz_event_mouse_double_click(
    DvzCanvas* canvas, vec2 pos, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the double-click position
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_drag()

Emit a mouse drag event.

void dvz_event_mouse_drag(
    DvzCanvas* canvas, vec2 pos, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the drag start position
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_mouse_drag_end()

Emit a mouse drag end event.

void dvz_event_mouse_drag_end(
    DvzCanvas* canvas, vec2 pos, DvzMouseButton button, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
pos vec2 the drag end position
button DvzMouseButton the mouse button
modifiers int flags with the active keyboard modifiers

dvz_event_key_press()

Emit a key press event.

void dvz_event_key_press(
    DvzCanvas* canvas, DvzKeyCode key_code, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
key_code DvzKeyCode the key
modifiers int flags with the active keyboard modifiers

dvz_event_key_release()

Emit a key release event.

void dvz_event_key_release(
    DvzCanvas* canvas, DvzKeyCode key_code, int modifiers);
Parameter Type Description
canvas DvzCanvas* the canvas
key_code DvzKeyCode the key
modifiers int flags with the active keyboard modifiers

dvz_event_frame()

Emit a frame event.

void dvz_event_frame(
    DvzCanvas* canvas, uint64_t idx, double time, double interval);
Parameter Type Description
canvas DvzCanvas* the canvas
idx uint64_t the frame index
time double the current time
interval double the interval since the last frame event

Typically raised at every canvas frame.

dvz_event_timer()

Emit a timer event.

void dvz_event_timer(
    DvzCanvas* canvas, uint64_t idx, double time, double interval);
Parameter Type Description
canvas DvzCanvas* the canvas
idx uint64_t the timer event index
time double the current time
interval double the interval since the last timer event

Screencast

dvz_screencast()

Prepare the canvas for a screencast.

void dvz_screencast(DvzCanvas* canvas, double interval, bool has_alpha);
Parameter Type Description
canvas DvzCanvas* the canvas
interval double screencast events interval
has_alpha bool whether the screencast array is RGB or RGBA

A screencast is a live record of one or several frames of the canvas during the interactive execution of the app. Creating a screencast is required for: - screenshots, - video records (requires ffmpeg)

This command creates a host-coherent GPU image with the same size as the current framebuffer size.

If the interval is non-zero, the canvas will raise periodic SCREENCAST events every interval seconds. The event payload will contain a pointer to the grabbed framebuffer image.

dvz_screencast_destroy()

Destroy the screencast.

void dvz_screencast_destroy(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

dvz_screenshot()

Make a screenshot.

uint8_t* dvz_screenshot(DvzCanvas* canvas, bool has_alpha);
Parameter Type Description
canvas DvzCanvas* the canvas
returns uint8_t* pointer to the 24-bit RGB framebuffer.

This function creates a screencast if there isn't one already. It is implemented with hard synchronization commands so this command should not be used for creating many successive screenshots. For that, one should register a SCREENCAST event callback.

Important

The caller MUST free the output pointer.

dvz_screenshot_file()

Make a screenshot and save it to a PNG file.

void dvz_screenshot_file(DvzCanvas* canvas, char* png_path);
Parameter Type Description
canvas DvzCanvas* the canvas
png_path char* the path to the PNG file to create

Note

This function uses full GPU synchronization methods so it is relatively inefficient. More efficient methods are not yet implemented.

dvz_canvas_video()

Record a live screencast video of the canvas.

void dvz_canvas_video(
    DvzCanvas* canvas, int framerate, int bitrate, char* path, bool record);
Parameter Type Description
canvas DvzCanvas* the canvas
framerate int the framerate in images per second (30 recommended)
bitrate int the bitrate, in bytes (10000000 for high quality)
path char* path to the file (.mp4 extension recommended)
record bool whether to start recording immediately or not

This function should be run before calling dvz_app_run().

dvz_canvas_pause()

Pause the live video screencast.

void dvz_canvas_pause(DvzCanvas* canvas, bool record);
Parameter Type Description
canvas DvzCanvas* the canvas
record bool whether to pause or continue the recording

dvz_canvas_stop()

Stop the live video screencast and save the file.

void dvz_canvas_stop(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

Internal event loop

dvz_canvas_frame()

Process a single frame in the event loop.

void dvz_canvas_frame(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

This function probably never needs to be called directly, unless writing a custom backend.

dvz_canvas_frame_submit()

Submit the rendered frame to the swapchain system.

void dvz_canvas_frame_submit(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

Internal event system

dvz_event_callback()

Register a callback for canvas events.

void dvz_event_callback(
    DvzCanvas* canvas, DvzEventType type, double param,
    DvzEventMode mode, DvzEventCallback callback, void* user_data);
Parameter Type Description
canvas DvzCanvas* the canvas
type DvzEventType the event type
param double time interval for TIMER events, in seconds
mode DvzEventMode whether the callback is sync or async
callback DvzEventCallback the callback function
user_data void* a pointer to arbitrary user data

These user callbacks run either in the main thread (sync callbacks) or in the background thread * (async callbacks). Callbacks can access the DvzMouse and DvzKeyboard structures with the current state of the mouse and keyboard.

Callback function signature: void(DvzCanvas*, DvzEvent)

The event object has a field with the user-specified pointer user_data.

dvz_event_pending()

Return the number of pending events.

int dvz_event_pending(DvzCanvas* canvas, DvzEventType type);
Parameter Type Description
canvas DvzCanvas* the canvas
type DvzEventType the event type
returns int number of pending events

This is the number of events of the given type that are still being processed or pending in the queue.

dvz_event_stop()

Stop the background event loop.

void dvz_event_stop(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

This function sends a special "closing" event to the event loop, causing it to stop.

dvz_mouse()

Create the mouse object holding the current mouse state.

DvzMouse dvz_mouse(void );

| returns | DvzMouse | object |

dvz_mouse_toggle()

Active or deactivate interactive mouse events.

void dvz_mouse_toggle(DvzMouse* mouse, bool enable);
Parameter Type Description
mouse DvzMouse* the mouse object
enable bool whether to activate or deactivate mouse events

dvz_mouse_reset()

Reset the mouse state.

void dvz_mouse_reset(DvzMouse* mouse);
Parameter Type Description
mouse DvzMouse* the mouse object

dvz_mouse_event()

Emit a mouse event.

void dvz_mouse_event(DvzMouse* mouse, DvzCanvas* canvas, DvzEvent ev);
Parameter Type Description
mouse DvzMouse* the mouse object
canvas DvzCanvas* the canvas
ev DvzEvent the mouse event

dvz_mouse_local()

Convert mouse coordinates from global to local.

void dvz_mouse_local(
    DvzMouse* mouse, DvzMouseLocal* mouse_local, DvzCanvas* canvas,
    DvzViewport viewport);
Parameter Type Description
mouse DvzMouse* the mouse object
mouse_local DvzMouseLocal* the mouse local object
canvas DvzCanvas* the canvas
viewport DvzViewport the viewport defining the local coordinates
  • Global coordinates: in pixels, origin at the top-left corner of the window.
  • Local coordinates: in normalize coordinates [-1, 1], origin at the center of a given viewport, taking viewport margins into account

dvz_keyboard()

Create the keyboard object holding the current keyboard state.

DvzKeyboard dvz_keyboard(void );

| returns | DvzKeyboard | object |

dvz_keyboard_toggle()

Active or deactivate interactive keyboard events.

void dvz_keyboard_toggle(DvzKeyboard* keyboard, bool enable);
Parameter Type Description
keyboard DvzKeyboard* the keyboard object
enable bool whether to activate or deactivate keyboard events

dvz_keyboard_reset()

Reset the keyboard state

void dvz_keyboard_reset(DvzKeyboard* keyboard);

| returns | void | object |

dvz_keyboard_event()

Emit a keyboard event.

void dvz_keyboard_event(DvzKeyboard* keyboard, DvzCanvas* canvas, DvzEvent ev);
Parameter Type Description
keyboard DvzKeyboard* the keyboard object
canvas DvzCanvas* the canvas
ev DvzEvent the keyboard event