Skip to main content

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 {}