tessera_ui/renderer/drawer/
command.rs

1//! Draw command traits and barrier requirements.
2//!
3//! This module defines the core traits and types for graphics rendering
4//! commands in the unified command system.
5
6use downcast_rs::{Downcast, impl_downcast};
7use dyn_clone::DynClone;
8
9use crate::{
10    px::PxRect,
11    render_graph::DrawGeometry,
12    render_scene::{DrawRegion, PaddingRect, SampleRegion},
13};
14
15/// Trait for graphics rendering commands that can be processed by draw
16/// pipelines.
17///
18/// Implement this trait for structs that represent graphics operations such as
19/// shape drawing, text rendering, image display, or custom visual effects.
20///
21/// # Example
22///
23/// ```
24/// use tessera_ui::DrawCommand;
25///
26/// #[derive(Clone, PartialEq)]
27/// struct RectangleCommand {
28///     color: [f32; 4],
29///     corner_radius: f32,
30/// }
31///
32/// impl DrawCommand for RectangleCommand {
33///     fn apply_opacity(&mut self, opacity: f32) {
34///         self.color[3] *= opacity.clamp(0.0, 1.0);
35///     }
36/// }
37/// ```
38pub trait DrawCommand: DynClone + Downcast + Send + Sync {
39    /// Whether unchanged commands can keep their pixels between frames.
40    ///
41    /// Opt in only when every visual change invalidates the command's paint
42    /// fragment or geometry. Leave this disabled for commands whose textures or
43    /// other resources can change independently, including deferred uploads.
44    /// Applying opacity must preserve the declared draw and sampling regions.
45    fn supports_partial_redraw(&self) -> bool {
46        false
47    }
48
49    /// Specifies sample requirements for this draw operation.
50    ///
51    /// As a default implementation, this returns `None`, indicating that
52    /// the command does not need to sample from previously rendered content.
53    ///
54    /// Override this method if your command requires sampling from prior
55    /// contents.
56    fn sample_region(&self) -> Option<SampleRegion> {
57        None
58    }
59
60    /// Specifies the drawing region for this command.
61    ///
62    /// As a default implementation, this returns `DrawRegion::PaddedLocal` with
63    /// zero padding, indicating that the command draws within its own bounds.
64    ///
65    /// Override this method if your command draws to a different region but do
66    /// not want to affect layout calculations.
67    fn draw_region(&self) -> DrawRegion {
68        DrawRegion::PaddedLocal(PaddingRect::ZERO)
69    }
70
71    /// Applies an opacity multiplier to this command.
72    ///
73    /// In most cases you must implement this on your command to support
74    /// opacity changes in the UI.
75    fn apply_opacity(&mut self, opacity: f32);
76
77    /// Returns an absolute rectangle used for ordering decisions.
78    ///
79    /// The default implementation returns `None`, which falls back to the draw
80    /// region derived from the command size and position.
81    fn ordering_rect(&self, _geometry: DrawGeometry) -> Option<PxRect> {
82        None
83    }
84}
85
86impl_downcast!(DrawCommand);
87
88dyn_clone::clone_trait_object!(DrawCommand);
tessera_ui/renderer/drawer/command.rs

tessera_ui/renderer/drawer/
command.rs
