ferrochart_core/render.rs
1//! The interface every rendering backend implements.
2//!
3//! Call order (the `&mut` borrow of `build_frame` ends before the two `&self`
4//! borrows of `render`):
5//!
6//! ```ignore
7//! if chart.needs_redraw() != Invalidation::None {
8//! chart.build_frame(now_ms, &text);
9//! renderer.render(chart.frame(), &chart.data_view())?;
10//! }
11//! ```
12//!
13
14use core::fmt;
15
16use crate::chart::ChartDataView;
17use crate::frame::Frame;
18use crate::geom::SizePx;
19
20/// A rendering backend.
21pub trait Renderer {
22 /// Uploads whatever series data changed since this renderer last synced (it
23 /// keeps its own synced generation per series and asks
24 /// `data.changes_since`), then draws `frame`. On error the synced generations
25 /// must not advance, so the next call catches up.
26 ///
27 /// # Errors
28 ///
29 /// A [`RenderError`] if the backend cannot draw (lost surface, out of memory).
30 fn render(&mut self, frame: &Frame, data: &ChartDataView<'_>) -> Result<(), RenderError>;
31
32 /// Resizes the render target.
33 fn resize(&mut self, size: SizePx);
34
35 /// Custom series kinds this renderer draws natively; pass them to
36 /// [`crate::Chart::set_native_kinds`]. None by default.
37 fn native_kinds(&self) -> &[&'static str] {
38 &[]
39 }
40}
41
42/// Error from a [`Renderer`].
43///
44/// # Examples
45///
46/// ```
47/// use ferrochart_core::render::RenderError;
48///
49/// assert_eq!(RenderError::Backend("surface lost").to_string(), "render backend error: surface lost");
50/// ```
51#[derive(Clone, Debug, PartialEq, Eq)]
52#[non_exhaustive]
53pub enum RenderError {
54 /// The target size is zero or too large for the backend.
55 InvalidSize,
56 /// Backend-specific failure.
57 Backend(&'static str),
58}
59
60impl fmt::Display for RenderError {
61 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62 match self {
63 Self::InvalidSize => f.write_str("invalid render target size"),
64 Self::Backend(what) => write!(f, "render backend error: {what}"),
65 }
66 }
67}
68
69impl std::error::Error for RenderError {}