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}