Skip to main content

kernel/
paint.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Portable paint primitives — `Color` and `Stroke`.
5//!
6//! These types are the kernel's framework-agnostic color + stroke
7//! vocabulary. Host painters convert to backend-specific types
8//! (egui `Color32`, iced `Color`, vello / wgpu colors) at the draw-
9//! call boundary; portable descriptors flow through `kernel`'s
10//! overlay surface (`OverlayStrokePass`), through `host-contract`
11//! ports, and through `graph-canvas`'s `packet::SceneDrawItem` /
12//! `node_style` / `derive` surfaces — all without coupling the kernel
13//! to a renderer crate.
14//!
15//! **Why these live in kernel, not graph-canvas**: previously
16//! they lived in `graph_canvas::packet`, with kernel importing
17//! them — that made `kernel → graph-canvas` an upward dependency
18//! that blocked the
19//! [cartography layer](../../../../design_docs/mere_docs/research/2026-05-10_cartography_layer_brief.md)
20//! brief's revised §9 step 4 (the `graph-layout` extraction).
21//! Moving these into the kernel and having `graph-canvas` re-export
22//! them reverses the edge to its natural direction (kernel is
23//! foundational; everything else depends on it). The graph-canvas
24//! public API stays stable through the re-export.
25//!
26//! ## Coexistence with `color::Color32`
27//!
28//! The kernel also has [`crate::color::Color32`] — an u8-channel
29//! color type used for egui-shaped host palettes (drag-preview
30//! tinting, etc.). [`Color`] in this module is the f32-channel form
31//! used for renderer-style descriptors. The two coexist by design:
32//! `Color32` is the kernel's host-palette type; `Color` is the
33//! kernel's renderer-descriptor type. A future cleanup may unify
34//! them; for now both ship.
35
36use serde::{Deserialize, Serialize};
37
38/// A color in linear RGBA, 0.0–1.0 per channel.
39///
40/// Framework-agnostic color type. Conversion to/from backend-specific
41/// colors (egui `Color32`, iced `Color`, renderer-specific colors)
42/// happens at the host bridge.
43#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
44pub struct Color {
45    pub r: f32,
46    pub g: f32,
47    pub b: f32,
48    pub a: f32,
49}
50
51impl Color {
52    pub const fn new(r: f32, g: f32, b: f32, a: f32) -> Self {
53        Self { r, g, b, a }
54    }
55
56    pub const WHITE: Self = Self::new(1.0, 1.0, 1.0, 1.0);
57    pub const BLACK: Self = Self::new(0.0, 0.0, 0.0, 1.0);
58    pub const TRANSPARENT: Self = Self::new(0.0, 0.0, 0.0, 0.0);
59}
60
61impl Default for Color {
62    fn default() -> Self {
63        Self::WHITE
64    }
65}
66
67/// Stroke style for lines and shape outlines.
68#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
69pub struct Stroke {
70    pub color: Color,
71    pub width: f32,
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77
78    #[test]
79    fn color_default_is_white() {
80        assert_eq!(Color::default(), Color::WHITE);
81    }
82
83    #[test]
84    fn color_constants_have_expected_channel_values() {
85        assert_eq!(Color::WHITE.r, 1.0);
86        assert_eq!(Color::BLACK.r, 0.0);
87        assert_eq!(Color::TRANSPARENT.a, 0.0);
88    }
89
90    #[test]
91    fn color_serde_round_trip() {
92        let original = Color::new(0.25, 0.5, 0.75, 1.0);
93        let json = serde_json::to_string(&original).unwrap();
94        let decoded: Color = serde_json::from_str(&json).unwrap();
95        assert_eq!(decoded, original);
96    }
97
98    #[test]
99    fn stroke_carries_color_and_width() {
100        let stroke = Stroke {
101            color: Color::BLACK,
102            width: 2.0,
103        };
104        assert_eq!(stroke.color, Color::BLACK);
105        assert_eq!(stroke.width, 2.0);
106    }
107}