//! Shape fills: what paints a shape's, text box's or canvas's interior, and a shape outline's //! gradient (DrawingML `a:solidFill` / `a:gradFill`, ECMA-376 §20.1.8.54 and §20.1.8.33; VML //! `v:fill`). //! //! A gradient is kept as the file states it (stops, linear angle or path focus, tile rectangle, //! `rotWithShape`, flip) so saving writes it back; drawing approximates rectangular and //! shape-following paths as circular. Transparencies are percent (0 = opaque); rectangles are //! percent insets (left, top, right, bottom) from the shape's edges. use serde::{Deserialize, Deserializer, Serialize, Serializer}; use std::sync::Arc; use crate::props::Rgb; #[cfg(test)] use crate::wordart::MAX_STOPS; use crate::wordart::{GradStop, clamp, sanitized_stops}; /// A shape's fill. In `.json` documents an opaque solid fill is written `[r, g, b]` as before /// fills had transparency or gradients; the rest are tagged (`{"type": "gradient", ...}`). #[derive(Clone, Debug, PartialEq)] pub enum Fill { Solid { color: Rgb, transparency: f32 }, Gradient(Arc), } /// A gradient fill. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Gradient { pub stops: Vec, pub kind: GradientKind, /// `a:tileRect`: where the gradient's area sits relative to the shape (percent insets). #[serde(default, skip_serializing_if = "Option::is_none")] pub tile: Option<[f32; 4]>, /// Turns with the shape (`rotWithShape`). #[serde(default)] pub rot_with_shape: bool, #[serde(default, skip_serializing_if = "GradientFlip::is_none")] pub flip: GradientFlip, } /// How a gradient runs. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "type", rename_all = "camelCase")] pub enum GradientKind { /// Along a line at `angle` degrees (0 = left to right, 90 = top to bottom). `scaled`: the /// angle is scaled with the shape's aspect ratio. Linear { angle: f32, #[serde(default)] scaled: bool, }, /// Outwards from `focus` (percent insets from the shape's edges, `a:fillToRect`). Path { shape: PathShape, focus: [f32; 4] }, } /// A path gradient's outline (`a:path/@path`). #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub enum PathShape { Circle, Rect, Shape, } /// How the gradient's tile is mirrored when tiled (`a:gradFill/@flip`). #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub enum GradientFlip { #[default] None, X, Y, Xy, } impl GradientFlip { pub fn is_none(&self) -> bool { *self == GradientFlip::None } } /// Largest rectangle inset kept, percent (hostile files). const MAX_INSET: f32 = 1000.0; fn rect(r: [f32; 4]) -> [f32; 4] { r.map(|v| clamp(v, -MAX_INSET, MAX_INSET, 0.0)) } impl Fill { /// An opaque solid fill. pub fn solid(color: Rgb) -> Fill { Fill::Solid { color, transparency: 0.0 } } /// The one colour standing for the fill where only one fits: the solid colour, or a /// gradient's middle stop. pub fn main_color(&self) -> Rgb { match self { Fill::Solid { color, .. } => *color, Fill::Gradient(g) => g.stops.get(g.stops.len() / 2).map_or(Rgb::BLACK, |s| s.color), } } /// Finite, in range: at most [`MAX_STOPS`] stops, in order, positions and transparencies /// 0–100%, angles 0–360°. A gradient with one stop is that stop's solid colour; with none, /// no fill (`None`). pub fn sanitized(&self) -> Option { Some(match self { Fill::Solid { color, transparency } => Fill::Solid { color: *color, transparency: clamp(*transparency, 0.0, 100.0, 0.0) }, Fill::Gradient(g) => { let stops = sanitized_stops(&g.stops); match stops[..] { [] => return None, [s] => return Some(Fill::Solid { color: s.color, transparency: s.transparency }), _ => {} } let kind = match g.kind { GradientKind::Linear { angle, scaled } => { GradientKind::Linear { angle: clamp(angle, -1e6, 1e6, 0.0).rem_euclid(360.0) % 360.0, scaled } } GradientKind::Path { shape, focus } => GradientKind::Path { shape, focus: rect(focus) }, }; Fill::Gradient(Arc::new(Gradient { stops, kind, tile: g.tile.map(rect), rot_with_shape: g.rot_with_shape, flip: g.flip })) } }) } } /// The tagged `.json` form of fills other than opaque solid ones. #[derive(Serialize, Deserialize)] #[serde(tag = "type", rename_all = "camelCase")] enum Tagged { Solid { color: Rgb, #[serde(default)] transparency: f32, }, Gradient(Gradient), } #[derive(Deserialize)] #[serde(untagged)] enum AnyForm { Plain(Rgb), Tagged(Tagged), } impl Serialize for Fill { fn serialize(&self, s: S) -> Result { match self { Fill::Solid { color, transparency: 0.0 } => color.serialize(s), Fill::Solid { color, transparency } => Tagged::Solid { color: *color, transparency: *transparency }.serialize(s), Fill::Gradient(g) => Tagged::Gradient(Gradient::clone(g)).serialize(s), } } } impl<'de> Deserialize<'de> for Fill { fn deserialize>(d: D) -> Result { Ok(match AnyForm::deserialize(d)? { AnyForm::Plain(color) => Fill::solid(color), AnyForm::Tagged(Tagged::Solid { color, transparency }) => Fill::Solid { color, transparency }, AnyForm::Tagged(Tagged::Gradient(g)) => Fill::Gradient(Arc::new(g)), }) } } #[cfg(test)] mod tests { use super::*; fn stop(pos: f32, color: Rgb, transparency: f32) -> GradStop { GradStop { pos, color, transparency } } fn grad(stops: Vec, kind: GradientKind) -> Fill { Fill::Gradient(Arc::new(Gradient { stops, kind, tile: None, rot_with_shape: true, flip: GradientFlip::None })) } #[test] fn opaque_solid_fills_are_written_as_before_and_old_documents_load() { let f = Fill::solid(Rgb(1, 2, 3)); assert_eq!(serde_json::to_string(&f).ok().as_deref(), Some("[1,2,3]")); assert_eq!(serde_json::from_str::("[1,2,3]").ok(), Some(f)); } #[test] fn transparent_and_gradient_fills_round_trip_tagged() { let fills = [ Fill::Solid { color: Rgb::WHITE, transparency: 70.0 }, grad(vec![stop(0.0, Rgb(9, 9, 9), 0.0), stop(100.0, Rgb::WHITE, 50.0)], GradientKind::Linear { angle: 90.0, scaled: true }), Fill::Gradient(Arc::new(Gradient { stops: vec![stop(0.0, Rgb::BLACK, 0.0), stop(100.0, Rgb::WHITE, 0.0)], kind: GradientKind::Path { shape: PathShape::Rect, focus: [50.0, 50.0, 50.0, 50.0] }, tile: Some([-10.0, 0.0, 0.0, 0.0]), rot_with_shape: false, flip: GradientFlip::Xy, })), ]; for f in fills { let json = serde_json::to_string(&f).unwrap_or_default(); assert!(json.contains("\"type\""), "{json}"); assert_eq!(serde_json::from_str::(&json).ok(), Some(f), "{json}"); } } #[test] fn hostile_fills_are_sanitized() { let many: Vec = (0..30).map(|i| stop(100.0 - i as f32, Rgb::BLACK, f32::NAN)).collect(); let Some(Fill::Gradient(g)) = grad(many, GradientKind::Linear { angle: -450.0, scaled: false }).sanitized() else { panic!() }; assert_eq!(g.stops.len(), MAX_STOPS); assert!(g.stops.windows(2).all(|w| w[0].pos <= w[1].pos) && g.stops.iter().all(|s| s.transparency == 0.0)); assert_eq!(g.kind, GradientKind::Linear { angle: 270.0, scaled: false }); let path = grad( vec![stop(150.0, Rgb::BLACK, 200.0), stop(-5.0, Rgb::WHITE, 0.0)], GradientKind::Path { shape: PathShape::Circle, focus: [f32::NAN, 1e9, -1e9, 5.0] }, ); let Some(Fill::Gradient(g)) = path.sanitized() else { panic!() }; assert_eq!((g.stops[0].pos, g.stops[1].pos, g.stops[1].transparency), (0.0, 100.0, 100.0)); assert_eq!(g.kind, GradientKind::Path { shape: PathShape::Circle, focus: [0.0, MAX_INSET, -MAX_INSET, 5.0] }); assert_eq!( grad(vec![stop(0.0, Rgb::WHITE, 30.0)], GradientKind::Linear { angle: 0.0, scaled: false }).sanitized(), Some(Fill::Solid { color: Rgb::WHITE, transparency: 30.0 }) ); assert_eq!(grad(vec![], GradientKind::Linear { angle: 0.0, scaled: false }).sanitized(), None); assert_eq!(Fill::Solid { color: Rgb::BLACK, transparency: f32::NAN }.sanitized(), Some(Fill::solid(Rgb::BLACK))); } #[test] fn main_colour_is_the_middle_stop() { let g = grad( vec![stop(0.0, Rgb(1, 0, 0), 0.0), stop(50.0, Rgb(2, 0, 0), 0.0), stop(100.0, Rgb(3, 0, 0), 0.0)], GradientKind::Linear { angle: 0.0, scaled: false }, ); assert_eq!(g.main_color(), Rgb(2, 0, 0)); assert_eq!(Fill::solid(Rgb::WHITE).main_color(), Rgb::WHITE); } }