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, const 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, const 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,
const 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 and present it to the window.
int dvz_canvas_frame(DvzCanvas* canvas);
Parameter | Type | Description |
---|---|---|
canvas |
DvzCanvas* |
the canvas |
returns |
int |
if the frame was successfully presented, 1 othersiwe |
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 |