Skip to main content

aylis_core/
canvas.rs

1//! Interface de desenho (o "TCanvas"). O core só conhece este trait; a implementação
2//! real (Skia na CPU ou na GPU) fica no crate de renderização.
3
4use crate::color::Color;
5use crate::geometry::{PointF, RectF, SizeF};
6use crate::image::Image;
7use crate::path::Path;
8
9/// Uma parada de cor num gradiente (`offset` de 0 a 1).
10#[derive(Clone, Copy, Debug, PartialEq)]
11pub struct GradientStop {
12    pub offset: f32,
13    pub color: Color,
14}
15
16impl GradientStop {
17    pub const fn new(offset: f32, color: Color) -> Self {
18        Self { offset, color }
19    }
20}
21
22/// Como preencher uma forma.
23#[derive(Clone, Debug, PartialEq)]
24pub enum Brush {
25    Solid(Color),
26    Linear { start: PointF, end: PointF, stops: Vec<GradientStop> },
27    Radial { center: PointF, radius: f32, stops: Vec<GradientStop> },
28    /// Gradiente cônico (ótimo para bordas animadas girando).
29    Sweep { center: PointF, start_angle: f32, stops: Vec<GradientStop> },
30}
31
32impl From<Color> for Brush {
33    fn from(c: Color) -> Self {
34        Brush::Solid(c)
35    }
36}
37
38/// Como uma camada se junta ao que está por baixo dela (o `mix-blend-mode` do CSS e do
39/// Photoshop). Só os modos que o Skia, o Direct2D e o Canvas 2D do navegador desenham igual.
40/// `Difference` com branco é o negativo (a marca d'água que inverte o vídeo por baixo).
41#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
42pub enum BlendMode {
43    /// Por cima, sem mistura.
44    #[default]
45    Normal,
46    Multiply,
47    Screen,
48    Overlay,
49    Darken,
50    Lighten,
51    ColorDodge,
52    ColorBurn,
53    HardLight,
54    SoftLight,
55    /// A diferença entre as cores: o branco inverte, o preto não muda.
56    Difference,
57    /// Como a diferença, com menos contraste.
58    Exclusion,
59    Hue,
60    Saturation,
61    Color,
62    Luminosity,
63}
64
65impl BlendMode {
66    pub const ALL: [BlendMode; 16] = [
67        BlendMode::Normal,
68        BlendMode::Multiply,
69        BlendMode::Screen,
70        BlendMode::Overlay,
71        BlendMode::Darken,
72        BlendMode::Lighten,
73        BlendMode::ColorDodge,
74        BlendMode::ColorBurn,
75        BlendMode::HardLight,
76        BlendMode::SoftLight,
77        BlendMode::Difference,
78        BlendMode::Exclusion,
79        BlendMode::Hue,
80        BlendMode::Saturation,
81        BlendMode::Color,
82        BlendMode::Luminosity,
83    ];
84
85    /// O nome no CSS (`globalCompositeOperation` do Canvas 2D): `color-dodge`...
86    pub fn css(self) -> &'static str {
87        match self {
88            BlendMode::Normal => "source-over",
89            BlendMode::Multiply => "multiply",
90            BlendMode::Screen => "screen",
91            BlendMode::Overlay => "overlay",
92            BlendMode::Darken => "darken",
93            BlendMode::Lighten => "lighten",
94            BlendMode::ColorDodge => "color-dodge",
95            BlendMode::ColorBurn => "color-burn",
96            BlendMode::HardLight => "hard-light",
97            BlendMode::SoftLight => "soft-light",
98            BlendMode::Difference => "difference",
99            BlendMode::Exclusion => "exclusion",
100            BlendMode::Hue => "hue",
101            BlendMode::Saturation => "saturation",
102            BlendMode::Color => "color",
103            BlendMode::Luminosity => "luminosity",
104        }
105    }
106}
107
108impl crate::prop::PropEnum for BlendMode {
109    const NAMES: &'static [&'static str] = &[
110        "normal",
111        "multiply",
112        "screen",
113        "overlay",
114        "darken",
115        "lighten",
116        "color_dodge",
117        "color_burn",
118        "hard_light",
119        "soft_light",
120        "difference",
121        "exclusion",
122        "hue",
123        "saturation",
124        "color",
125        "luminosity",
126    ];
127    fn from_index(i: usize) -> Option<Self> {
128        BlendMode::ALL.get(i).copied()
129    }
130    fn index(self) -> usize {
131        self as usize
132    }
133}
134
135/// Ponta das linhas.
136#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
137pub enum LineCap {
138    #[default]
139    Butt,
140    Round,
141    Square,
142}
143
144/// Junção entre segmentos.
145#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
146pub enum LineJoin {
147    #[default]
148    Miter,
149    Round,
150    Bevel,
151}
152
153/// Como contornar uma forma.
154#[derive(Clone, Debug, PartialEq)]
155pub struct Stroke {
156    pub brush: Brush,
157    pub width: f32,
158    /// Traço e espaço alternados (`[4.0, 2.0]`); `None` = linha contínua.
159    pub dash: Option<Vec<f32>>,
160    pub cap: LineCap,
161    pub join: LineJoin,
162}
163
164impl Stroke {
165    pub fn new(brush: impl Into<Brush>, width: f32) -> Self {
166        Self { brush: brush.into(), width, dash: None, cap: LineCap::Butt, join: LineJoin::Miter }
167    }
168
169    pub fn dashed(mut self, pattern: Vec<f32>) -> Self {
170        self.dash = Some(pattern);
171        self
172    }
173
174    /// Pontas e junções arredondadas (o traço dos ícones).
175    pub fn round(mut self) -> Self {
176        self.cap = LineCap::Round;
177        self.join = LineJoin::Round;
178        self
179    }
180}
181
182/// Sombra projetada.
183#[derive(Clone, Copy, Debug, PartialEq)]
184pub struct Shadow {
185    pub color: Color,
186    /// Desfoque (raio, em unidades lógicas).
187    pub blur: f32,
188    pub offset: PointF,
189    /// Quanto a sombra cresce além da forma (negativo encolhe).
190    pub spread: f32,
191}
192
193impl Shadow {
194    pub fn new(color: Color, blur: f32, dx: f32, dy: f32) -> Self {
195        Self { color, blur, offset: PointF::new(dx, dy), spread: 0.0 }
196    }
197
198    /// Até onde a sombra passa da forma: o desfoque (os renderizadores usam sigma = metade
199    /// do raio, e o desfoque some em 3 sigmas), o espalhamento e o deslocamento.
200    pub fn reach(&self) -> f32 {
201        self.blur * 1.5 + self.spread.max(0.0) + self.offset.x.abs().max(self.offset.y.abs())
202    }
203
204    /// Lê `"dx dy desfoque [espalhamento] [#cor]"`, como o `box-shadow` do CSS (aceita `px`).
205    /// Sem cor, fica preto a 25%.
206    pub fn parse(spec: &str) -> Option<Shadow> {
207        let mut numbers = Vec::new();
208        let mut color = None;
209        for token in spec.split(|c: char| c.is_whitespace() || c == ',').filter(|t| !t.is_empty()) {
210            let number = token.strip_suffix("px").unwrap_or(token);
211            if let Ok(v) = number.parse::<f32>() {
212                numbers.push(v);
213            } else if color.is_none() {
214                color = Some(token.parse::<Color>().ok()?);
215            } else {
216                return None;
217            }
218        }
219        if !(2..=4).contains(&numbers.len()) {
220            return None;
221        }
222        Some(Shadow {
223            color: color.unwrap_or(Color::BLACK.with_opacity(0.25)),
224            blur: numbers.get(2).copied().unwrap_or(0.0).max(0.0),
225            offset: PointF::new(numbers[0], numbers[1]),
226            spread: numbers.get(3).copied().unwrap_or(0.0),
227        })
228    }
229
230    /// O texto que [`Shadow::parse`] lê (o espalhamento só aparece quando não é zero).
231    pub fn to_spec(&self) -> String {
232        let n = |v: f32| format!("{}", (v * 100.0).round() / 100.0);
233        let mut s = format!("{} {} {}", n(self.offset.x), n(self.offset.y), n(self.blur));
234        if self.spread != 0.0 {
235            s += &format!(" {}", n(self.spread));
236        }
237        s + " " + &self.color.to_hex()
238    }
239}
240
241#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
242pub enum FontWeight {
243    Thin,
244    Light,
245    #[default]
246    Normal,
247    Medium,
248    SemiBold,
249    Bold,
250    Black,
251}
252
253/// Fonte. `family` vazio = fonte padrão do sistema.
254#[derive(Clone, Debug, PartialEq)]
255pub struct FontSpec {
256    pub family: String,
257    pub size: f32,
258    pub weight: FontWeight,
259    pub italic: bool,
260    pub underline: bool,
261    /// Riscado no meio.
262    pub strikeout: bool,
263}
264
265impl Default for FontSpec {
266    fn default() -> Self {
267        Self { family: String::new(), size: 14.0, weight: FontWeight::Normal, italic: false, underline: false, strikeout: false }
268    }
269}
270
271impl FontSpec {
272    pub fn new(family: impl Into<String>, size: f32) -> Self {
273        Self { family: family.into(), size, ..Default::default() }
274    }
275
276    pub fn weight(mut self, weight: FontWeight) -> Self {
277        self.weight = weight;
278        self
279    }
280}
281
282/// Alinhamento do texto dentro do retângulo.
283#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
284pub enum TextAlign {
285    /// Esquerda (ou topo).
286    #[default]
287    Leading,
288    Center,
289    /// Direita (ou base).
290    Trailing,
291    /// Justificado: as linhas quebradas ocupam a largura
292    /// toda, com o espaço que sobra dividido entre as palavras; a última linha de cada
293    /// parágrafo (e o texto de uma linha só) fica à esquerda. Na vertical, vale o topo.
294    Justify,
295}
296
297impl crate::prop::PropEnum for TextAlign {
298    const NAMES: &'static [&'static str] = &["leading", "center", "trailing", "justify"];
299
300    fn from_index(index: usize) -> Option<Self> {
301        [TextAlign::Leading, TextAlign::Center, TextAlign::Trailing, TextAlign::Justify].get(index).copied()
302    }
303
304    fn index(self) -> usize {
305        self as usize
306    }
307}
308
309#[derive(Clone, Debug, PartialEq)]
310pub struct TextStyle {
311    pub font: FontSpec,
312    pub color: Color,
313    pub h_align: TextAlign,
314    pub v_align: TextAlign,
315    /// Quebra automática de linha (nas palavras; palavra maior que a largura, no caractere).
316    pub wrap: bool,
317    /// Reticências quando não couber (por caractere, por palavra ou nenhuma).
318    pub trimming: crate::text::Trimming,
319}
320
321impl Default for TextStyle {
322    fn default() -> Self {
323        Self {
324            font: FontSpec::default(),
325            color: Color::BLACK,
326            h_align: TextAlign::Leading,
327            v_align: TextAlign::Center,
328            wrap: false,
329            trimming: crate::text::Trimming::Character,
330        }
331    }
332}
333
334/// Superfície de desenho. Coordenadas em unidades lógicas, relativas à transformação
335/// atual (o `Ui` já posiciona o canvas na origem de cada controle antes de pintá-lo).
336pub trait Canvas {
337    /// Guarda transformação, clip e camada atuais.
338    fn save(&mut self);
339    /// Volta ao último `save` (ou `save_layer`).
340    fn restore(&mut self);
341    fn translate(&mut self, dx: f32, dy: f32);
342    fn scale(&mut self, sx: f32, sy: f32);
343    fn rotate(&mut self, degrees: f32);
344    fn clip_rect(&mut self, rect: RectF);
345    /// Abre uma camada com opacidade; tudo até o `restore` correspondente é composto
346    /// junto com essa opacidade.
347    fn save_layer(&mut self, opacity: f32);
348
349    /// Como [`save_layer`](Self::save_layer), e no `restore` a camada se junta ao que está
350    /// por baixo pelo modo `mode`. `bounds`: até onde a camada desenha (nas coordenadas de
351    /// agora), para o renderizador misturar só ali. O padrão (um canvas sem mistura) é a
352    /// camada normal.
353    fn save_layer_blend(&mut self, opacity: f32, mode: BlendMode, bounds: RectF) {
354        let _ = (mode, bounds);
355        self.save_layer(opacity);
356    }
357
358    /// Preenche um retângulo (`radius` > 0 arredonda os cantos).
359    fn fill_rect(&mut self, rect: RectF, radius: f32, brush: &Brush);
360    /// Traça a borda de um retângulo **por dentro**: o traço inteiro cabe em `rect` (o
361    /// `box-sizing: border-box` do CSS), nos três renderizadores. Uma moldura de 1 px fica no
362    /// primeiro pixel de dentro, nítida; para traçar pelo meio da linha, aumente o retângulo
363    /// em meia largura do traço (o relatório do Tabernáculo, T09).
364    fn stroke_rect(&mut self, rect: RectF, radius: f32, stroke: &Stroke);
365    fn fill_ellipse(&mut self, rect: RectF, brush: &Brush);
366    /// Traça a elipse por dentro de `rect`, como o [`stroke_rect`](Self::stroke_rect).
367    fn stroke_ellipse(&mut self, rect: RectF, stroke: &Stroke);
368    fn draw_line(&mut self, from: PointF, to: PointF, stroke: &Stroke);
369    fn draw_text(&mut self, text: &str, rect: RectF, style: &TextStyle);
370    /// Tamanho do texto numa linha só (sem quebra), com a mesma fonte usada no desenho.
371    fn measure_text(&mut self, text: &str, style: &TextStyle) -> SizeF;
372
373    /// Desenha a parte `src` da imagem (em pixels da imagem) no retângulo `dest`. O padrão
374    /// não desenha nada (canvases de teste).
375    fn draw_image(&mut self, image: &Image, src: RectF, dest: RectF, opacity: f32) {
376        let _ = (image, src, dest, opacity);
377    }
378
379    /// Tamanho da imagem em pixels (decodifica se preciso). `None` se não der para ler.
380    fn image_size(&mut self, image: &Image) -> Option<SizeF> {
381        image.known_size()
382    }
383
384    /// Recorta para um retângulo de cantos arredondados (o padrão recorta sem arredondar).
385    fn clip_round_rect(&mut self, rect: RectF, radius: f32) {
386        let _ = radius;
387        self.clip_rect(rect);
388    }
389
390    /// Preenche um caminho (regra "não zero"). O padrão não preenche (canvases de teste).
391    fn fill_path(&mut self, path: &Path, brush: &Brush) {
392        let _ = (path, brush);
393    }
394
395    /// Recorta para o interior do caminho (`inverse`: para o exterior). O padrão recorta
396    /// para o retângulo do caminho (e não recorta com `inverse`).
397    fn clip_path(&mut self, path: &Path, inverse: bool) {
398        if !inverse {
399            self.clip_rect(path.bounds());
400        }
401    }
402
403    /// Desfoca o que já foi desenhado embaixo de `rect` (cantos `radius`), com o desvio
404    /// `blur` (o "material" do vidro: Liquid Glass, Mica, Acrylic). Devolve `false` se o
405    /// canvas não sabe desfocar (quem chama usa um fundo mais opaco no lugar).
406    fn backdrop_blur(&mut self, rect: RectF, radius: f32, blur: f32) -> bool {
407        let _ = (rect, radius, blur);
408        false
409    }
410
411    /// Máscara de alfa (o "track matte" do After Effects). `begin_masked` abre uma camada
412    /// para o conteúdo; depois de desenhá-lo, `begin_mask` passa a desenhar a máscara (o
413    /// alfa dela recorta o conteúdo; com `inverse`, o contrário) e `end_mask` compõe tudo.
414    /// Devolve `false` se o canvas não sabe fazer (aí quem chama recorta com
415    /// [`clip_path`](Canvas::clip_path)).
416    fn begin_masked(&mut self, inverse: bool) -> bool {
417        let _ = inverse;
418        false
419    }
420
421    /// Veja [`begin_masked`](Canvas::begin_masked).
422    fn begin_mask(&mut self) {}
423
424    /// Veja [`begin_masked`](Canvas::begin_masked).
425    fn end_mask(&mut self) {}
426
427    /// Desenho caro e parado (um mapa com centenas de caminhos, um gráfico vetorial)
428    /// guardado como imagem pela `key`: `true` quando a imagem guardada já foi desenhada em
429    /// `rect` (quem chama não desenha nada). Com `false`, quem chama desenha em `rect` e
430    /// chama [`end_cached`](Canvas::end_cached), que guarda o resultado e o compõe. A
431    /// chave deve mudar com tudo o que muda o desenho (cores, destaque, área); o tamanho em
432    /// pixels já entra nela. O padrão não guarda nada (desenha sempre).
433    fn begin_cached(&mut self, key: u64, rect: RectF) -> bool {
434        let _ = (key, rect);
435        false
436    }
437
438    /// Veja [`begin_cached`](Canvas::begin_cached).
439    fn end_cached(&mut self) {}
440
441    /// Solta as imagens guardadas com a `key` de [`begin_cached`](Canvas::begin_cached): o
442    /// núcleo chama quando a camada de um controle deixa de valer (a transição acabou, o
443    /// desenho de dentro mudou), para ela não ocupar memória até sair pelo limite.
444    fn forget_cached(&mut self, key: u64) {
445        let _ = key;
446    }
447
448    /// Contorna um caminho. O padrão desenha as curvas como retas.
449    fn stroke_path(&mut self, path: &Path, stroke: &Stroke) {
450        for (points, closed) in path.flatten(8) {
451            for w in points.windows(2) {
452                self.draw_line(w[0], w[1], stroke);
453            }
454            if closed && points.len() > 2 {
455                self.draw_line(points[points.len() - 1], points[0], stroke);
456            }
457        }
458    }
459
460    /// Sombra de um retângulo (de cantos arredondados). O padrão não desenha.
461    fn draw_shadow(&mut self, rect: RectF, radius: f32, shadow: &Shadow) {
462        let _ = (rect, radius, shadow);
463    }
464
465    /// Quantos pixels da tela há em uma unidade lógica, com a transformação atual (para
466    /// quem desenha por fora, como o 3D, criar a imagem já no tamanho certo).
467    fn device_scale(&self) -> f32 {
468        1.0
469    }
470
471    /// A GPU em que este canvas desenha, para quem desenha por fora (o 3D) usar a mesma e
472    /// entregar o resultado sem passar pela CPU. `None`: canvas na CPU.
473    fn gpu_device(&self) -> Option<GpuDevice> {
474        None
475    }
476
477    /// Compõe no retângulo `dest` uma imagem que já está na GPU (veja [`GpuSurface`]), sem
478    /// copiar para a CPU. Devolve `false` se o canvas não sabe (quem chama copia os pixels
479    /// e usa [`draw_image`](Canvas::draw_image)).
480    fn draw_gpu_surface(&mut self, dest: RectF, surface: &GpuSurface) -> bool {
481        let _ = (dest, surface);
482        false
483    }
484
485    /// Quem desenha por fora (o 3D) mexeu no estado da GPU deste canvas (no OpenGL, o mesmo
486    /// contexto): o canvas não pode confiar no que guardou. Vale também quando o resultado
487    /// volta pela CPU, com [`draw_image`](Canvas::draw_image).
488    fn gpu_state_changed(&mut self) {}
489}
490
491/// A GPU de um canvas (veja [`Canvas::gpu_device`]).
492#[derive(Clone, Copy, Debug, PartialEq, Eq)]
493pub enum GpuDevice {
494    /// Direct3D 11 (o Direct2D), no adaptador com este LUID.
495    Direct3D11 { adapter_luid: i64 },
496    /// OpenGL (o Skia na GPU). `loader` é o endereço de uma
497    /// `unsafe extern "C" fn(*const c_char) -> *const c_void` que acha as funções do OpenGL
498    /// pelo nome; `context` identifica o contexto (quem desenha por fora cria os recursos
499    /// nele, e por isso precisa de um por contexto).
500    OpenGl { loader: usize, context: usize },
501    /// Navegador (Canvas 2D): quem desenha por fora usa um `<canvas>` próprio (WebGPU ou
502    /// WebGL), que o canvas copia na GPU com `drawImage`.
503    Web,
504}
505
506/// Imagem na GPU desenhada por fora do aylis (o 3D), para o renderizador compor com os
507/// controles sem passar pela CPU (veja [`Canvas::draw_gpu_surface`]).
508///
509/// Os números são handles do sistema; o núcleo não os interpreta.
510#[derive(Clone, Copy, Debug, PartialEq, Eq)]
511pub enum GpuSurface {
512    /// Textura BGRA (alfa pré-multiplicado) compartilhada do Direct3D 12, com duas cercas
513    /// compartilhadas: o renderizador espera `ready` chegar a `ready_value` antes de ler,
514    /// e marca `release` com `release_value` quando o quadro que a leu terminar (aí quem
515    /// desenha pode reescrever a textura).
516    ///
517    /// Vale também para uma textura do Direct3D 11 com handle NT e cercas `ID3D11Fence`
518    /// compartilhadas (os quadros de vídeo do `aylis-media`): o renderizador abre as duas do
519    /// mesmo jeito.
520    D3D12 {
521        /// Identifica a textura (o handle pode ser reaproveitado pelo sistema depois de fechado).
522        id: u64,
523        texture: isize,
524        width: u32,
525        height: u32,
526        ready: isize,
527        ready_value: u64,
528        release: isize,
529        release_value: u64,
530    },
531    /// Textura do OpenGL (RGBA, alfa pré-multiplicado), no mesmo contexto do canvas: os
532    /// comandos já estão em ordem, sem cercas.
533    GlTexture { id: u64, texture: u32, width: u32, height: u32 },
534    /// Um `<canvas>` da página com `id="aylis-3d-<element>"`, já desenhado neste quadro.
535    WebCanvas { element: u32, width: u32, height: u32 },
536}
537
538/// Medição de texto, usada fora da pintura (layout, auto-size).
539pub trait TextService {
540    /// Tamanho do texto; com `max_width`, considera a quebra de linha.
541    fn measure(&self, text: &str, style: &TextStyle, max_width: Option<f32>) -> SizeF;
542}
543
544/// Sublinhado e tachado de uma linha de texto já desenhada (para os renderizadores que não
545/// fazem sozinhos): `x` e `width` são os da linha, `top` e `line_height` a faixa dela.
546pub fn decorate_line(canvas: &mut dyn Canvas, font: &FontSpec, color: Color, x: f32, width: f32, top: f32, line_height: f32) {
547    if !(font.underline || font.strikeout) || width <= 0.0 {
548        return;
549    }
550    let stroke = Stroke::new(color, (font.size / 14.0).max(1.0));
551    let middle = top + line_height / 2.0;
552    if font.underline {
553        let y = middle + font.size * 0.45;
554        canvas.draw_line(PointF::new(x, y), PointF::new(x + width, y), &stroke);
555    }
556    if font.strikeout {
557        let y = middle + font.size * 0.05;
558        canvas.draw_line(PointF::new(x, y), PointF::new(x + width, y), &stroke);
559    }
560}