Canvas
-
namespace ezgl
A library for creating a graphical user interface.
-
class canvas
- #include <canvas.hpp>
Responsible for creating, destroying, and maintaining the rendering context of a QWidget.
The backing widget is selected at runtime via render_backend (one of immediate / deferred / rhi); the canvas connects to the widget’s resize and paint events to remain responsive.
Each canvas is double-buffered. A draw callback (see: ezgl::draw_canvas_fn) is invoked each time the canvas needs to be redrawn. This may be caused by the user (e.g., resizing the screen), but can also be forced by the programmer.
Public Functions
-
~canvas() = default
Destructor.
-
inline char const *id() const
Get the name (identifier) of the canvas.
-
int width() const
Get the width of the canvas in pixels.
-
int height() const
Get the height of the canvas in pixels.
-
void redraw()
Force the canvas to redraw itself.
This will invoke the ezgl::draw_canvas_fn callback and queue a redraw of the QWidget.
-
void redraw_camera_only()
Redraw using only a camera (MVP) update — no geometry re-upload.
On the RHI path this reuses the existing vertex buffers, rebuilds the cached overlay for the new camera, and avoids re-running the draw callback. Falls back to a full redraw on non-RHI paths or before the first frame.
-
inline void set_renderer_type(renderer_type t)
Set the rendering backend type. Must be called before application::run().
-
inline renderer_type get_renderer_type() const
-
inline void set_frame_timing_callback(std::function<void(double)> fn)
Register a callback invoked after each canvas::redraw() completes. Receives the total CPU time of the redraw in milliseconds — for RHI this includes both command recording and flush(); for QPainter backends it covers the full draw callback execution.
-
renderer *create_animation_renderer()
Create an animation renderer that can be used to draw on top of the current canvas
-
bool print_pdf(const char *file_name, int width = 0, int height = 0)
print_pdf, print_svg, and print_png generate a PDF, SVG, or PNG output file showing all the graphical content of the current canvas.
- Parameters:
file_name – name of the output file
- Returns:
returns true if the function has successfully generated the output file, otherwise failed due to errors such as out of memory occurs.
-
bool print_svg(const char *file_name, int width = 0, int height = 0)
-
bool print_png(const char *file_name, int width = 0, int height = 0)
-
void draw_offscreen(int width, int height)
Run the draw callback on an offscreen surface of the given size without saving any file. Use this to measure pure render time, separate from PNG/PDF encoding overhead.
Protected Functions
-
canvas(std::string canvas_id, draw_canvas_fn draw_callback, rectangle coordinate_system, color background_color)
Create a canvas that can be drawn to.
-
void initialize(QWidget *drawing_area)
Lazy initialization of the canvas class.
This function is required because the GUI is not built until ezgl::application::run() loads the .ui file (UI loading is deferred from the constructor to run() so Qt resources are registered). Canvas construction happens before that via add_canvas(), so the backing widget is bound here at run time, before exec() starts the event loop.
Private Functions
-
QImage render_to_image(int surface_width, int surface_height)
-
void begin_deferred_redraw_cycle()
-
void end_deferred_redraw_cycle()
Private Members
-
draw_canvas_fn m_draw_callback
-
QWidget *m_drawing_area = nullptr
-
renderer_type m_renderer_type = renderer_type::rhi
Friends
- friend class application
-
~canvas() = default
-
class canvas