i_slint_core/
graphics.rs

1// Copyright © SixtyFPS GmbH <info@slint.dev>
2// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
3
4#![warn(missing_docs)]
5/*!
6    Graphics Abstractions.
7
8    This module contains the abstractions and convenience types used for rendering.
9
10    The run-time library also makes use of [RenderingCache] to store the rendering primitives
11    created by the backend in a type-erased manner.
12*/
13extern crate alloc;
14use crate::api::PlatformError;
15use crate::lengths::LogicalLength;
16use crate::Coord;
17use crate::SharedString;
18use alloc::boxed::Box;
19
20pub use euclid;
21/// 2D Rectangle
22pub type Rect = euclid::default::Rect<Coord>;
23/// 2D Rectangle with integer coordinates
24pub type IntRect = euclid::default::Rect<i32>;
25/// 2D Point
26pub type Point = euclid::default::Point2D<Coord>;
27/// 2D Size
28pub type Size = euclid::default::Size2D<Coord>;
29/// 2D Size in integer coordinates
30pub type IntSize = euclid::default::Size2D<u32>;
31/// 2D Transform
32pub type Transform = euclid::default::Transform2D<Coord>;
33
34pub(crate) mod color;
35pub use color::*;
36
37#[cfg(feature = "std")]
38mod path;
39#[cfg(feature = "std")]
40pub use path::*;
41
42mod brush;
43pub use brush::*;
44
45pub(crate) mod image;
46pub use self::image::*;
47
48pub(crate) mod bitmapfont;
49pub use self::bitmapfont::*;
50
51pub mod rendering_metrics_collector;
52
53#[cfg(feature = "box-shadow-cache")]
54pub mod boxshadowcache;
55
56pub mod border_radius;
57pub use border_radius::*;
58
59#[cfg(feature = "unstable-wgpu-24")]
60pub mod wgpu_24;
61
62/// CachedGraphicsData allows the graphics backend to store an arbitrary piece of data associated with
63/// an item, which is typically computed by accessing properties. The dependency_tracker is used to allow
64/// for a lazy computation. Typically, back ends store either compute intensive data or handles that refer to
65/// data that's stored in GPU memory.
66pub struct CachedGraphicsData<T> {
67    /// The backend specific data.
68    pub data: T,
69    /// The property tracker that should be used to evaluate whether the primitive needs to be re-created
70    /// or not.
71    pub dependency_tracker: Option<core::pin::Pin<Box<crate::properties::PropertyTracker>>>,
72}
73
74impl<T> CachedGraphicsData<T> {
75    /// Creates a new TrackingRenderingPrimitive by evaluating the provided update_fn once, storing the returned
76    /// rendering primitive and initializing the dependency tracker.
77    pub fn new(update_fn: impl FnOnce() -> T) -> Self {
78        let dependency_tracker = Box::pin(crate::properties::PropertyTracker::default());
79        let data = dependency_tracker.as_ref().evaluate(update_fn);
80        Self { data, dependency_tracker: Some(dependency_tracker) }
81    }
82}
83
84/// The RenderingCache, in combination with CachedGraphicsData, allows back ends to store data that's either
85/// intensive to compute or has bad CPU locality. Back ends typically keep a RenderingCache instance and use
86/// the item's cached_rendering_data() integer as index in the vec_arena::Arena.
87///
88/// This is used only for the [`crate::item_rendering::PartialRenderingCache`]
89pub struct RenderingCache<T> {
90    slab: slab::Slab<CachedGraphicsData<T>>,
91    generation: usize,
92}
93
94impl<T> Default for RenderingCache<T> {
95    fn default() -> Self {
96        Self { slab: Default::default(), generation: 1 }
97    }
98}
99
100impl<T> RenderingCache<T> {
101    /// Returns the generation of the cache. The generation starts at 1 and is increased
102    /// whenever the cache is cleared, for example when the GL context is lost.
103    pub fn generation(&self) -> usize {
104        self.generation
105    }
106
107    /// Retrieves a mutable reference to the cached graphics data at index.
108    pub fn get_mut(&mut self, index: usize) -> Option<&mut CachedGraphicsData<T>> {
109        self.slab.get_mut(index)
110    }
111
112    /// Returns true if a cache entry exists for the given index.
113    pub fn contains(&self, index: usize) -> bool {
114        self.slab.contains(index)
115    }
116
117    /// Inserts data into the cache and returns the index for retrieval later.
118    pub fn insert(&mut self, data: CachedGraphicsData<T>) -> usize {
119        self.slab.insert(data)
120    }
121
122    /// Retrieves an immutable reference to the cached graphics data at index.
123    pub fn get(&self, index: usize) -> Option<&CachedGraphicsData<T>> {
124        self.slab.get(index)
125    }
126
127    /// Removes the cached graphics data at the given index.
128    pub fn remove(&mut self, index: usize) -> CachedGraphicsData<T> {
129        self.slab.remove(index)
130    }
131
132    /// Removes all entries from the cache and increases the cache's generation count, so
133    /// that stale index access can be avoided.
134    pub fn clear(&mut self) {
135        self.slab.clear();
136        self.generation += 1;
137    }
138}
139/// FontRequest collects all the developer-configurable properties for fonts, such as family, weight, etc.
140/// It is submitted as a request to the platform font system (i.e. CoreText on macOS) and in exchange the
141/// backend returns a `Box<dyn Font>`.
142#[derive(Debug, Clone, PartialEq, Default)]
143pub struct FontRequest {
144    /// The name of the font family to be used, such as "Helvetica". An empty family name means the system
145    /// default font family should be used.
146    pub family: Option<SharedString>,
147    /// If the weight is None, the system default font weight should be used.
148    pub weight: Option<i32>,
149    /// If the pixel size is None, the system default font size should be used.
150    pub pixel_size: Option<LogicalLength>,
151    /// The additional spacing (or shrinking if negative) between glyphs. This is usually not submitted to
152    /// the font-subsystem but collected here for API convenience
153    pub letter_spacing: Option<LogicalLength>,
154    /// Whether to select an italic face of the font family.
155    pub italic: bool,
156}
157
158#[cfg(feature = "shared-fontdb")]
159impl FontRequest {
160    /// Returns the relevant properties of this FontRequest propagated into a fontdb Query.
161    pub fn to_fontdb_query(&self) -> i_slint_common::sharedfontdb::fontdb::Query<'_> {
162        use i_slint_common::sharedfontdb::fontdb::{Query, Style, Weight};
163        Query {
164            style: if self.italic { Style::Italic } else { Style::Normal },
165            weight: Weight(self.weight.unwrap_or(/* CSS normal*/ 400) as _),
166            ..Default::default()
167        }
168    }
169}
170
171/// Internal enum to specify which version of OpenGL to request
172/// from the windowing system.
173#[derive(Debug, Clone, PartialEq)]
174pub enum RequestedOpenGLVersion {
175    /// OpenGL
176    OpenGL(Option<(u8, u8)>),
177    /// OpenGL ES
178    OpenGLES(Option<(u8, u8)>),
179}
180
181/// Internal enum specify which graphics API should be used, when
182/// the backend selector requests that from a built-in backend.
183#[derive(Debug, Clone)]
184pub enum RequestedGraphicsAPI {
185    /// OpenGL (ES)
186    OpenGL(RequestedOpenGLVersion),
187    /// Metal
188    Metal,
189    /// Vulkan
190    Vulkan,
191    /// Direct 3D
192    Direct3D,
193    #[cfg(feature = "unstable-wgpu-24")]
194    /// WGPU 24.x
195    WGPU24(wgpu_24::WGPUConfiguration),
196}
197
198impl TryFrom<RequestedGraphicsAPI> for RequestedOpenGLVersion {
199    type Error = PlatformError;
200
201    fn try_from(requested_graphics_api: RequestedGraphicsAPI) -> Result<Self, Self::Error> {
202        match requested_graphics_api {
203            RequestedGraphicsAPI::OpenGL(requested_open_glversion) => Ok(requested_open_glversion),
204            RequestedGraphicsAPI::Metal => {
205                Err("Metal rendering is not supported with an OpenGL renderer".into())
206            }
207            RequestedGraphicsAPI::Vulkan => {
208                Err("Vulkan rendering is not supported with an OpenGL renderer".into())
209            }
210            RequestedGraphicsAPI::Direct3D => {
211                Err("Direct3D rendering is not supported with an OpenGL renderer".into())
212            }
213            #[cfg(feature = "unstable-wgpu-24")]
214            RequestedGraphicsAPI::WGPU24(..) => {
215                Err("WGPU 24.x rendering is not supported with an OpenGL renderer".into())
216            }
217        }
218    }
219}
220
221impl From<RequestedOpenGLVersion> for RequestedGraphicsAPI {
222    fn from(version: RequestedOpenGLVersion) -> Self {
223        Self::OpenGL(version)
224    }
225}
226
227/// Private API exposed to just the renderers to create GraphicsAPI instance with
228/// non-exhaustive enum variant.
229#[cfg(feature = "unstable-wgpu-24")]
230pub fn create_graphics_api_wgpu_24(
231    instance: wgpu_24::wgpu::Instance,
232    device: wgpu_24::wgpu::Device,
233    queue: wgpu_24::wgpu::Queue,
234) -> crate::api::GraphicsAPI<'static> {
235    crate::api::GraphicsAPI::WGPU24 { instance, device, queue }
236}
237
238/// Internal module for use by cbindgen and the C++ platform API layer.
239#[cfg(feature = "ffi")]
240pub mod ffi {
241    #![allow(unsafe_code)]
242
243    /// Expand Rect so that cbindgen can see it. ( is in fact euclid::default::Rect<f32>)
244    #[cfg(cbindgen)]
245    #[repr(C)]
246    struct Rect {
247        x: f32,
248        y: f32,
249        width: f32,
250        height: f32,
251    }
252
253    /// Expand IntRect so that cbindgen can see it. ( is in fact euclid::default::Rect<i32>)
254    #[cfg(cbindgen)]
255    #[repr(C)]
256    struct IntRect {
257        x: i32,
258        y: i32,
259        width: i32,
260        height: i32,
261    }
262
263    /// Expand Point so that cbindgen can see it. ( is in fact euclid::default::Point2D<f32>)
264    #[cfg(cbindgen)]
265    #[repr(C)]
266    struct Point {
267        x: f32,
268        y: f32,
269    }
270
271    /// Expand Box2D so that cbindgen can see it.
272    #[cfg(cbindgen)]
273    #[repr(C)]
274    struct Box2D<T, U> {
275        min: euclid::Point2D<T>,
276        max: euclid::Point2D<T>,
277        _unit: std::marker::PhantomData<U>,
278    }
279
280    #[cfg(feature = "std")]
281    pub use super::path::ffi::*;
282
283    /// Conversion function used by C++ platform API layer to
284    /// convert the PhysicalSize used in the Rust WindowAdapter API
285    /// to the ffi.
286    pub fn physical_size_from_api(
287        size: crate::api::PhysicalSize,
288    ) -> crate::graphics::euclid::default::Size2D<u32> {
289        size.to_euclid()
290    }
291
292    /// Conversion function used by C++ platform API layer to
293    /// convert the PhysicalPosition used in the Rust WindowAdapter API
294    /// to the ffi.
295    pub fn physical_position_from_api(
296        position: crate::api::PhysicalPosition,
297    ) -> crate::graphics::euclid::default::Point2D<i32> {
298        position.to_euclid()
299    }
300
301    /// Conversion function used by C++ platform API layer to
302    /// convert from the ffi to PhysicalPosition.
303    pub fn physical_position_to_api(
304        position: crate::graphics::euclid::default::Point2D<i32>,
305    ) -> crate::api::PhysicalPosition {
306        crate::api::PhysicalPosition::from_euclid(position)
307    }
308}
i_slint_core/graphics.rs

i_slint_core/
graphics.rs
