carnelian/render/generic/
mod.rs

1// Copyright 2020 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use std::fmt::Debug;
6use std::hash::Hash;
7use std::io::Read;
8use std::ops::Add;
9use std::{error, fmt, u32};
10
11use anyhow::Error;
12use display_utils::PixelFormat;
13use euclid::default::{Point2D, Rect, Size2D, Transform2D, Vector2D};
14use euclid::{point2, size2};
15use fidl::endpoints::ClientEnd;
16use fidl_fuchsia_sysmem2::BufferCollectionTokenMarker;
17
18use crate::color::Color;
19use crate::drawing::DisplayRotation;
20use crate::{Point, ViewAssistantContext};
21
22pub mod forma;
23
24pub use self::forma::Forma;
25
26/// Either Spinel or Forma. Zero-sized.
27pub trait Backend: Copy + Debug + Default + Eq + Hash + Ord + Sized + 'static {
28    /// Buffer-backed image that can be used for rendering or storing pixel data.
29    type Image: Copy + Debug + Eq + Hash + Ord;
30    /// Backend's rendering context.
31    type Context: Context<Self>;
32    /// Vector path.
33    type Path: Clone + Eq;
34    /// Stateful path builder.
35    type PathBuilder: PathBuilder<Self>;
36    /// Compact rasterized form of any number of paths.
37    type Raster: Raster;
38    /// Stateful raster builder.
39    type RasterBuilder: RasterBuilder<Self>;
40    /// Composition of stylized rasters.
41    type Composition: Composition<Self>;
42
43    /// Creates a new rendering context
44    fn new_context(
45        token: ClientEnd<BufferCollectionTokenMarker>,
46        size: Size2D<u32>,
47        display_rotation: DisplayRotation,
48    ) -> Self::Context;
49}
50
51/// Rectangular copy region.
52#[derive(Clone, Copy, Debug, PartialEq)]
53pub struct CopyRegion {
54    /// Top-left origin of source rectangle.
55    pub src_offset: Point2D<u32>,
56    /// Top-left origin of destination rectangle.
57    pub dst_offset: Point2D<u32>,
58    /// Size of both source and destination rectangles.
59    pub extent: Size2D<u32>,
60}
61
62/// Rendering extensions.
63#[derive(Clone, Debug, Default, PartialEq)]
64pub struct RenderExt<B: Backend> {
65    /// Clears render image before rendering.
66    pub pre_clear: Option<PreClear>,
67    /// Copies from source image to render image before rendering.
68    pub pre_copy: Option<PreCopy<B>>,
69    /// Copies from render image to destination image after rendering.
70    pub post_copy: Option<PostCopy<B>>,
71}
72
73/// Pre-render image clear.
74#[derive(Clone, Debug, PartialEq)]
75pub struct PreClear {
76    /// Clear color.
77    pub color: Color,
78}
79
80/// Pre-render image copy.
81#[derive(Clone, Debug, PartialEq)]
82pub struct PreCopy<B: Backend> {
83    /// Source image to copy from.
84    pub image: B::Image,
85    /// Copy region properties.
86    pub copy_region: CopyRegion,
87}
88
89/// Post-render image copy.
90#[derive(Clone, Debug, PartialEq)]
91pub struct PostCopy<B: Backend> {
92    /// Destination image to copy to. Must be different from render image.
93    pub image: B::Image,
94    /// Copy region properties.
95    pub copy_region: CopyRegion,
96}
97
98/// Rendering context and API start point.
99pub trait Context<B: Backend> {
100    /// Returns the context's pixel format.
101    fn pixel_format(&self) -> PixelFormat;
102    /// Optionally returns a `PathBuilder`. May return `None` of old builder is still alive.
103    fn path_builder(&self) -> Option<B::PathBuilder>;
104    /// Optionally returns a `RasterBuilder`. May return `None` of old builder is still alive.
105    fn raster_builder(&self) -> Option<B::RasterBuilder>;
106    /// Creates a new image with `size`.
107    fn new_image(&mut self, size: Size2D<u32>) -> B::Image;
108    /// Creates a new image from PNG `reader`.
109    fn new_image_from_png<R: Read>(
110        &mut self,
111        reader: &mut png::Reader<R>,
112    ) -> Result<B::Image, Error>;
113    /// Returns the image at `image_index`.
114    fn get_image(&mut self, image_index: u32) -> B::Image;
115    /// Returns the `context`'s current image.
116    fn get_current_image(&mut self, context: &ViewAssistantContext) -> B::Image;
117    /// Renders the composition with an optional clip to the image.
118    fn render(
119        &mut self,
120        composition: &mut B::Composition,
121        clip: Option<Rect<u32>>,
122        image: B::Image,
123        ext: &RenderExt<B>,
124    ) {
125        self.render_with_clip(
126            composition,
127            clip.unwrap_or_else(|| {
128                Rect::new(point2(u32::MIN, u32::MIN), size2(u32::MAX, u32::MAX))
129            }),
130            image,
131            ext,
132        );
133    }
134    /// Renders the composition with a clip to the image.
135    fn render_with_clip(
136        &mut self,
137        composition: &mut B::Composition,
138        clip: Rect<u32>,
139        image: B::Image,
140        ext: &RenderExt<B>,
141    );
142}
143
144/// Builds one closed path.
145pub trait PathBuilder<B: Backend> {
146    /// Move end-point to.
147    fn move_to(&mut self, point: Point) -> &mut Self;
148    /// Create line from end-point to point and update end-point.
149    fn line_to(&mut self, point: Point) -> &mut Self;
150    /// Create quadratic Bézier from end-point to `p2` with `p1` as control point.
151    fn quad_to(&mut self, p1: Point, p2: Point) -> &mut Self;
152    /// Create cubic Bézier from end-point to `p3` with `p1` and `p2` as control points.
153    fn cubic_to(&mut self, p1: Point, p2: Point, p3: Point) -> &mut Self;
154    /// Create rational quadratic Bézier from end-point to `p2` with `p1` as control point
155    /// and `w` as its weight.
156    fn rat_quad_to(&mut self, p1: Point, p2: Point, w: f32) -> &mut Self;
157    /// Create rational cubic Bézier from end-point to `p3` with `p1` and `p2` as control
158    /// points, and `w1` and `w2` their weights.
159    fn rat_cubic_to(&mut self, p1: Point, p2: Point, p3: Point, w1: f32, w2: f32) -> &mut Self;
160    /// Closes the path with a line if not yet closed and builds the path.
161    ///
162    /// Consumes the builder; another one can be requested from the `Context`.
163    fn build(self) -> B::Path;
164}
165
166/// Raster.
167pub trait Raster: Add<Output = Self> + Clone + Eq {
168    /// Translate raster.
169    fn translate(self, translation: Vector2D<i32>) -> Self;
170}
171
172/// Builds one Raster.
173pub trait RasterBuilder<B: Backend> {
174    /// Add a path to the raster with optional transform.
175    fn add(&mut self, path: &B::Path, transform: Option<&Transform2D<f32>>) -> &mut Self {
176        #[allow(clippy::or_fun_call)] // TODO(https://fxbug.dev/379717231)
177        self.add_with_transform(path, transform.unwrap_or(&Transform2D::identity()))
178    }
179    /// Add a path to the raster with transform.
180    fn add_with_transform(&mut self, path: &B::Path, transform: &Transform2D<f32>) -> &mut Self;
181    /// Builds the raster.
182    ///
183    /// Consumes the builder; another one can be requested from the `Context`.
184    fn build(self) -> B::Raster;
185}
186
187/// Raster fill rule that determines how self-intersecting parts of the path are filled. It uses the
188/// winding number--the count of how many full counter-clockwise revolutions ('windings') the curve
189/// makes around a point--to determine whether this point should be filled or not.
190#[derive(Clone, Copy, Debug, PartialEq)]
191pub enum FillRule {
192    /// Points with non-zero winding number are filled.
193    NonZero,
194    /// Points with odd non-zero numbers are filled.
195    EvenOdd,
196}
197
198#[derive(Clone, Copy, Debug)]
199pub enum GradientType {
200    Linear,
201    Radial,
202}
203
204#[derive(Clone, Debug)]
205pub struct Gradient {
206    pub r#type: GradientType,
207    pub start: Point,
208    pub end: Point,
209    pub stops: Vec<(Color, f32)>,
210}
211
212/// Raster fill type.
213#[derive(Clone, Debug)]
214pub enum Fill {
215    /// Fills the raster with a uniform color.
216    Solid(Color),
217    /// Fills the raster with a gradient.
218    Gradient(Gradient),
219}
220
221/// Raster blend mode. See https://www.w3.org/TR/compositing/#blending for more details.
222#[derive(Clone, Copy, Debug, PartialEq)]
223pub enum BlendMode {
224    /// Normal. Source is placed over the destination.
225    Over,
226    /// The source color is multiplied by the destination color and replaces the destination.
227    Multiply,
228    /// Multiplies the complements of the backdrop and source color values, then complements the
229    /// result.
230    Screen,
231    /// Multiplies or screens the colors, depending on the backdrop color value.
232    Overlay,
233    /// Selects the darker of the backdrop and source colors.
234    Darken,
235    /// Selects the lighter of the backdrop and source colors.
236    Lighten,
237    /// Brightens the backdrop color to reflect the source color. Painting with black produces no
238    /// changes.
239    ColorDodge,
240    /// Darkens the backdrop color to reflect the source color. Painting with white produces no
241    /// change.
242    ColorBurn,
243    /// Multiplies or screens the colors, depending on the source color value. The effect is
244    /// similar to shining a harsh spotlight on the backdrop.
245    HardLight,
246    /// Darkens or lightens the colors, depending on the source color value. The effect is similar
247    /// to shining a diffused spotlight on the backdrop.
248    SoftLight,
249    /// Subtracts the darker of the two constituent colors from the lighter color.
250    Difference,
251    /// Produces an effect similar to that of the `Difference` mode but lower in contrast.
252    /// Painting with white inverts the backdrop color; painting with black produces no change.
253    Exclusion,
254    /// Creates a color with the hue of the source color and the saturation and luminosity of the backdrop color.
255    Hue,
256    /// Creates a color with the saturation of the source color and the hue and luminosity of the backdrop color.
257    /// Painting with this mode in an area of the backdrop that is a pure gray (no saturation) produces no change.
258    Saturation,
259    /// Creates a color with the hue and saturation of the source color and the luminosity of the backdrop color.
260    /// This preserves the gray levels of the backdrop and is useful for coloring monochrome images or tinting color images.
261    Color,
262    /// Creates a color with the luminosity of the source color and the hue and saturation of the backdrop color.
263    /// This produces an inverse effect to that of the `Color` mode.
264    Luminosity,
265}
266
267/// Raster style.
268#[derive(Clone, Debug)]
269pub struct Style {
270    /// Raster fill rule.
271    pub fill_rule: FillRule,
272    /// Raster fill type.
273    pub fill: Fill,
274    /// Raster blend mode.
275    pub blend_mode: BlendMode,
276}
277
278#[derive(Debug, PartialEq)]
279pub enum OrderError {
280    ExceededLayerLimit(u32),
281}
282
283impl fmt::Display for OrderError {
284    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
285        write!(
286            f,
287            "exceeded layer limit ({})",
288            match self {
289                OrderError::ExceededLayerLimit(val) => val,
290            }
291        )
292    }
293}
294
295const CARNELIAN_MAX_ORDER: usize = (1 << 18) - 1;
296
297pub type Order = GenericOrder<CARNELIAN_MAX_ORDER>;
298
299type GuaranteedOrderType = u16;
300static_assertions::const_assert!((GuaranteedOrderType::MAX as u32) < (Order::MAX.as_u32()));
301
302impl error::Error for OrderError {}
303
304#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
305pub struct GenericOrder<const MAX: usize>(u32);
306
307impl<const MAX: usize> GenericOrder<MAX> {
308    pub const MAX: Self = Self(MAX as u32);
309
310    pub const fn as_u32(&self) -> u32 {
311        self.0
312    }
313
314    pub const fn new(order: u32) -> Result<Self, OrderError> {
315        if order > Self::MAX.as_u32() {
316            Err(OrderError::ExceededLayerLimit(Self::MAX.as_u32()))
317        } else {
318            Ok(Self(order))
319        }
320    }
321
322    /// Create an order from a sixteen bit value that is guaranteed to
323    /// below the maximum value for an order and thus doesn't need
324    /// to be returned as a result and can be used in constant expressions.
325    pub const fn from_u16(order: GuaranteedOrderType) -> Self {
326        Self(order as u32)
327    }
328}
329
330impl<const MAX: usize> TryFrom<u32> for GenericOrder<MAX> {
331    type Error = OrderError;
332
333    fn try_from(order: u32) -> Result<Self, OrderError> {
334        Self::new(order)
335    }
336}
337
338impl<const MAX: usize> TryFrom<usize> for GenericOrder<MAX> {
339    type Error = OrderError;
340
341    fn try_from(order: usize) -> Result<Self, OrderError> {
342        u32::try_from(order)
343            .map_err(|_| OrderError::ExceededLayerLimit(Self::MAX.as_u32()))
344            .and_then(|x| Self::try_from(x))
345    }
346}
347
348/// 2D layer containing a raster with a style.
349#[derive(Clone, Debug)]
350pub struct Layer<B: Backend> {
351    /// Layer raster.
352    pub raster: B::Raster,
353    /// Layer clip.
354    pub clip: Option<B::Raster>,
355    /// Layer style.
356    pub style: Style, // Will also contain txty when available.
357}
358
359/// A group of ordered layers.
360pub trait Composition<B: Backend> {
361    /// Creates a composition of ordered layers where the layers with lower index appear on top.
362    fn new(background_color: Color) -> Self;
363    /// Resets composition by removing all layers.
364    fn clear(&mut self);
365    /// Inserts layer into the composition.
366    fn insert(&mut self, order: Order, layer: Layer<B>);
367    /// Removes layer from the composition.
368    fn remove(&mut self, order: Order);
369}
370
371#[cfg(test)]
372pub(crate) mod tests {
373    use super::*;
374
375    use fuchsia_async as fasync;
376
377    #[test]
378    fn generic_compile_test() {
379        fn _generic<B: Backend>(
380            token: ClientEnd<BufferCollectionTokenMarker>,
381            size: Size2D<u32>,
382            display_rotation: DisplayRotation,
383            view_context: &ViewAssistantContext,
384        ) {
385            let mut context = B::new_context(token, size, display_rotation);
386
387            let mut path_builder = context.path_builder().unwrap();
388            path_builder.move_to(point2(0.0, 0.0)).line_to(point2(1.0, 1.0));
389            let path = path_builder.build();
390
391            let mut raster_builder = context.raster_builder().unwrap();
392            raster_builder.add(&path, None);
393            let raster = raster_builder.build();
394
395            let src_image = context.new_image(size2(100, 100));
396            let dst_image = context.get_current_image(view_context);
397
398            let mut composition: B::Composition = Composition::new(Color::new());
399            composition.insert(
400                Order::default(),
401                Layer {
402                    raster: raster.clone() + raster,
403                    clip: None,
404                    style: Style {
405                        fill_rule: FillRule::NonZero,
406                        fill: Fill::Solid(Color::white()),
407                        blend_mode: BlendMode::Over,
408                    },
409                },
410            );
411
412            context.render(
413                &mut composition,
414                None,
415                dst_image,
416                &RenderExt {
417                    pre_copy: Some(PreCopy {
418                        image: src_image,
419                        copy_region: CopyRegion {
420                            src_offset: Point2D::zero(),
421                            dst_offset: Point2D::zero(),
422                            extent: size2(100, 100),
423                        },
424                    }),
425                    ..Default::default()
426                },
427            );
428        }
429    }
430
431    // Currently, render API tests are only run if a compatible Vulkan driver is found. This means
432    // that these tests will be skipped on CI, but be able to run manually through the
433    // `carnelian_tests` component.
434    fn has_vk_instance() -> bool {
435        false
436    }
437
438    pub(crate) fn run(f: impl Fn()) {
439        if !has_vk_instance() {
440            return;
441        }
442
443        let mut executor = fasync::LocalExecutor::new();
444        let f = async { f() };
445        executor.run_singlethreaded(f);
446    }
447}
carnelian/render/generic/mod.rs

carnelian/render/generic/
mod.rs
