ferroui-base 0.4.0

use crate::collections::{FerroList, NotifyCollectionChangedAction, NotifyCollectionChangedEventArgs, ResetBehavior};
use crate::media::{
    can_value_affect_render, subscribe_invalidated, CacheMode, DrawingContext, FlowDirection, Geometry, IBrush, IEffect,
    ITransform, RenderOptions, TextOptions, Transform,
};
use crate::rendering::composition::{CompositionDrawListVisual, CompositionVisual, Compositor};
use crate::reactive::{Disposable, IDisposable};
use crate::rendering::IPresentationSource;
use crate::utilities::HandlerList;
use crate::{
    ferro_class, ferro_property, instantiate, AttachedProperty, DirectProperty, FerroObjectImpl,
    FerroObjectImplExt, FerroProperty, FerroPropertyChangedEventArgs, Nullable, ObjectType, Rect, Ref,
    RelativePoint, StyledElement,
    StyledElementImpl, StyledElementImplExt, StyledProperty, StyledPropertyOptions, Upcast,
    VisualTreeAttachmentEventArgs, WeakRef,
};
use std::cell::{Cell, OnceCell, RefCell};
use std::rc::Rc;

/// Base class for controls that provides rendering and related visual
/// properties.
///
/// The visual class represents elements that have a visual on-screen
/// representation and stores all the information needed for a renderer to
/// render the control. To traverse the visual tree, use the methods in the
/// `visual_tree` module.
#[repr(C)]
pub struct Visual {
    base: StyledElement,
    bounds: Cell<Rect>,
    presentation_source: RefCell<Option<Rc<dyn IPresentationSource>>>,
    visual_parent: RefCell<Option<WeakRef<Visual>>>,
    has_mirror_transform: Cell<bool>,
    // Deviation (DEVIATIONS.md, Visual tree): whether `RenderTransform` has a value, kept by its
    // change handler, so that the transforms of the visual tree skip the property read.
    has_render_transform: Cell<bool>,
    // Not upstream: whether the visual has a manipulation transform (the zoom a scroll presenter
    // applies to its content), kept so that the transforms of the visual tree skip the lookup.
    has_manipulation_transform: Cell<bool>,
    is_effectively_visible: Cell<bool>,
    has_non_uniform_z_index_children: Cell<bool>,
    visual_children: OnceCell<FerroList<Ref<Visual>>>,
    attached_to_visual_tree: HandlerList<dyn Fn(&VisualTreeAttachmentEventArgs)>,
    detached_from_visual_tree: HandlerList<dyn Fn(&VisualTreeAttachmentEventArgs)>,
    is_effectively_visible_changed: HandlerList<dyn Fn()>,
    render_options: Cell<RenderOptions>,
    text_options: Cell<TextOptions>,
    composition_visual: RefCell<Option<CompositionDrawListVisual>>,
    child_composition_visual: RefCell<Option<Rc<CompositionVisual>>>,
    /// What the composition API of WinUI adds to the visual (the `Translation` facade, the
    /// requests to hide the composition visual, the layer composition visual): boxed and
    /// created on first use, so that a visual that uses none of it pays one pointer.
    composition_extras: RefCell<Option<Box<CompositionExtras>>>,
    /// The subscription to the `changed` notification of the render
    /// transform, held while the visual is attached to a visual tree.
    render_transform_subscription: RefCell<Option<Rc<dyn IDisposable>>>,
    affects_render_subscriptions: RefCell<Vec<(&'static FerroProperty, Rc<dyn IDisposable>)>>,
}

/// The state of the WinUI composition API on a visual (see
/// `docs/porting/winui-composition.md`).
#[derive(Default)]
struct CompositionExtras {
    /// `UIElement.Translation`: `None` while the facade was never set, so that the translation
    /// of the composition visual is left to the application.
    translation: Option<crate::Vector3D>,
    /// The number of outstanding requests to hide the composition visual (a connected animation
    /// shows the element through a visual surface while it flies).
    hide_requests: u32,
    /// Source-free presentation suppression honored by both the compositor and immediate
    /// rendering. Unlike composition hiding, bitmap/visual-brush captures also omit it.
    render_suppression_requests: u32,
    /// The number of outstanding requests to keep the composition visual visible although the
    /// visual is not (an implicit hide animation runs).
    show_requests: u32,
    /// A composition visual shown above the children and the child composition visual: the
    /// layer of the connected animations on a top level.
    layer_visual: Option<Rc<CompositionVisual>>,
    /// Composition visuals shown after the children: the images of removed children that play
    /// their implicit hide animations (WinUI's unloading storage).
    unloading_visuals: Vec<Rc<CompositionVisual>>,
    /// The other transform facades of `UIElement` (`Rotation`, `RotationAxis`, `Scale`,
    /// `CenterPoint`, `TransformMatrix`) and the transitions (`OpacityTransition`,
    /// `RotationTransition`, `ScaleTransition`, `TranslationTransition`).
    facades: composition_facades::CompositionFacades,
    /// `UIElement.Lights`: the XAML lights the element holds (winui-materials.md), and the
    /// subscriptions that connect them while the element is in a visual tree.
    lights: Option<FerroList<Ref<crate::media::XamlLight>>>,
    lights_subscriptions: Vec<Rc<dyn IDisposable>>,
    /// The ids of the XAML lights that target the element (`XamlLight.AddTargetElement`), and
    /// the subscription that offers the element to those lights when it enters a tree.
    light_target_ids: Vec<String>,
    light_target_subscription: Option<Rc<dyn IDisposable>>,
    /// The manipulation transform of the visual (see [`Visual::manipulation_transform`]).
    manipulation_transform: Option<crate::Matrix>,
    /// The theme shadow of the visual (`UIElement.Shadow`): `None` while the visual never had a
    /// `Shadow` and is not the child of a popup with one.
    theme_shadow: Option<ThemeShadowState>,
}

/// What a visual knows of the theme shadow it casts (see `visual/theme_shadow.rs`).
#[derive(Default)]
struct ThemeShadowState {
    /// The popup whose `Shadow` the visual casts as its child.
    popup: Option<WeakRef<Visual>>,
    /// Whether the visual is a popup, whose `Shadow` its child casts.
    delegates_to_child: bool,
    /// The visual that draws the shadow, shown by the parent before the composition visual of
    /// this visual.
    visual: Option<Rc<crate::rendering::composition::ThemeShadowVisual>>,
}

mod composition_facades;
mod theme_shadow;
#[cfg(test)]
mod composition_facades_tests;

pub use composition_facades::{ScalarTransition, Vector3Transition, Vector3TransitionComponents};

ferro_class! {
    Visual: StyledElement, virtuals VisualImpl: StyledElementImpl {
        /// Renders the visual to a drawing context.
        fn render(this, context: &mut DrawingContext);
        /// Calls the `on_attached_to_visual_tree` method for this control and
        /// all of its visual descendants.
        fn on_attached_to_visual_tree_core(this, e: &VisualTreeAttachmentEventArgs);
        /// Calls the `on_detached_from_visual_tree` method for this control
        /// and all of its visual descendants.
        fn on_detached_from_visual_tree_core(this, e: &VisualTreeAttachmentEventArgs);
        /// Called when the control is added to a rooted visual tree.
        fn on_attached_to_visual_tree(this, e: &VisualTreeAttachmentEventArgs);
        /// Called when the control is removed from a rooted visual tree.
        fn on_detached_from_visual_tree(this, e: &VisualTreeAttachmentEventArgs);
        /// Called when the control's visual parent changes.
        fn on_visual_parent_changed(this, old_parent: Option<&Ref<Visual>>, new_parent: Option<&Ref<Visual>>);
        /// Whether the control ignores the flow direction policies, i.e. is
        /// never mirrored.
        fn bypass_flow_direction_policies(this) -> bool;
        /// Computes the `has_mirror_transform` value according to the flow
        /// direction of this visual and its parent.
        fn invalidate_mirror_transform(this);
        /// The corner radius the visual clips its content with when
        /// `clip_to_bounds` is set; `None` for a plain rectangular clip.
        /// (Upstream: the `IVisualWithRoundRectClip` interface.)
        fn clip_to_bounds_radius(this) -> Option<crate::CornerRadius>;
        /// The custom hit test of the visual at a point in its own
        /// coordinates; `None` when the visual has none and is hit by what
        /// it occupies or draws. (Upstream: the `ICustomHitTest` interface;
        /// a class implementing it overrides this and the geometry form.)
        fn custom_hit_test(this, point: crate::Point) -> Option<bool>;
        /// The custom hit test of the visual against a geometry in its own
        /// coordinates; `None` when the visual has none.
        fn custom_hit_test_geometry(this, geometry: &Ref<crate::media::Geometry>) -> Option<crate::media::IntersectionResult>;
        /// Ensures that the visual is ready to use as the visual in a
        /// visual brush. (Upstream: the `IVisualBrushInitialize` interface;
        /// a class implementing it overrides this.)
        fn ensure_initialized_for_visual_brush(this);
        /// Creates the composition visual of the visual on `compositor`.
        fn create_composition_visual(this, compositor: &Rc<Compositor>) -> CompositionDrawListVisual;
        /// Releases the composition visual of the visual.
        fn detach_from_compositor(this);
        /// Makes the children of the composition visual match the visual
        /// children (in Z order) and the child composition visual.
        fn synchronize_composition_child_visuals(this);
        /// Copies the properties of the visual to its composition visual.
        fn synchronize_composition_properties(this);
    }
}

crate::ferro_thread_local! {
    static ROOTED_VISUAL_CHILDREN_COUNT: Cell<i32> = const { Cell::new(0) };
}
crate::ferro_class_info!(Visual { new: Visual::new });

crate::ferro_thread_local! {
    // Not upstream: a version of what the effective viewports of the visuals are computed from (the
    // bounds, the visual parents, `ClipToBounds`, `RenderTransform` and `RenderTransformOrigin` of
    // the visuals of the thread), which the layout manager reads to reuse the viewports of shared
    // ancestors within one pass (DEVIATIONS.md, Layout).
    static GEOMETRY_VERSION: Cell<u64> = const { Cell::new(0) };
}

/// The version of the geometry of the visuals of the thread (see `GEOMETRY_VERSION`).
#[inline]
pub(crate) fn geometry_version() -> u64 {
    GEOMETRY_VERSION.with(Cell::get)
}

#[inline]
fn bump_geometry_version() {
    GEOMETRY_VERSION.with(|version| version.set(version.get().wrapping_add(1)));
}

crate::ferro_overrides! { impl FerroObjectImpl for Visual {
    fn constructed(this: &Self) {
        Self::parent_constructed(this);

        // Disable transitions until we're added to the visual tree.
        this.disable_transitions();
    }

    fn on_property_changed(this: &Self, change: &FerroPropertyChangedEventArgs<'_>) {
        Self::parent_on_property_changed(this, change);

        if change.property() == Self::is_visible_property().as_property() {
            let parent_state = this.visual_parent().is_none_or(|p| p.is_effectively_visible());
            this.update_is_effectively_visible(parent_state);
        } else if change.property() == Self::shadow_property().as_property() {
            let old = change.get_old_value::<Option<Ref<crate::media::Shadow>>>().flatten();
            let new = change.get_new_value::<Option<Ref<crate::media::Shadow>>>();
            this.on_shadow_changed(old.as_ref(), new.as_ref());
        } else if change.property() == crate::styling::ThemeVariant::actual_theme_variant_property().as_property() {
            // The shadow of the theme is drawn in the theme of the element.
            if this.may_cast_theme_shadow() {
                this.invalidate_visual();
            }
        } else if change.property() == Self::flow_direction_property().as_property() {
            this.invalidate_mirror_transform();
            if let Some(children) = this.visual_children.get() {
                for child in children.snapshot().iter() {
                    child.invalidate_mirror_transform();
                }
            }
        }
    }
} }

impl StyledElementImpl for Visual {
    fn logical_children_collection_changed(this: &Self, e: &NotifyCollectionChangedEventArgs<'_, Ref<StyledElement>>) {
        Self::parent_logical_children_collection_changed(this, e);
        if let Some(source) = this.presentation_source() {
            source.renderer().recalculate_children(this);
        }
    }

    fn on_templated_parent_control_theme_changed(this: &Self) {
        Self::parent_on_templated_parent_control_theme_changed(this);
        let templated_parent = this.templated_parent();
        if let Some(children) = this.visual_children.get() {
            for child in children.snapshot().iter() {
                if child.templated_parent() == templated_parent {
                    child.on_templated_parent_control_theme_changed();
                }
            }
        }
    }
}

impl VisualImpl for Visual {
    fn render(_this: &Self, _context: &mut DrawingContext) {}

    fn on_attached_to_visual_tree_core(this: &Self, e: &VisualTreeAttachmentEventArgs) {
        *this.presentation_source.borrow_mut() = Some(e.presentation_source().clone());
        ROOTED_VISUAL_CHILDREN_COUNT.with(|count| count.set(count.get() + 1));

        if let Some(render_transform) = this.render_transform() {
            if let Some(mutable_transform) = render_transform.as_mutable_transform() {
                let weak = this.to_ref().downgrade();
                let subscription = mutable_transform.changed(Rc::new(move || {
                    if let Some(visual) = weak.upgrade() {
                        visual.render_transform_value_changed();
                    }
                }));
                this.set_render_transform_subscription(Some(subscription));
            }
        }

        this.enable_transitions();
        let renderer = e.presentation_source().renderer();
        if let Some(compositor) = renderer.compositor() {
            this.attach_to_compositor(&compositor);
        }

        this.invalidate_mirror_transform();
        let parent = this.visual_parent();
        this.update_is_effectively_visible(parent.as_ref().is_none_or(|p| p.is_effectively_visible()));
        this.on_attached_to_visual_tree(e);
        if !this.attached_to_visual_tree.is_empty() {
            for (_, handler) in this.attached_to_visual_tree.snapshot().iter() {
                handler(e);
            }
        }
        this.invalidate_visual();

        if let Some(parent) = &parent {
            renderer.recalculate_children(parent);
            if this.z_index() != 0 {
                parent.has_non_uniform_z_index_children.set(true);
            }
        }

        if let Some(children) = this.visual_children.get() {
            let this_ref = this.to_ref();
            for child in children.snapshot().iter() {
                // An event handler may have modified the children: skip a
                // child which has already been attached, or which has been
                // removed from this visual (this is a snapshot).
                let attached_here = child
                    .presentation_source()
                    .is_some_and(|s| Rc::ptr_eq(&s, e.presentation_source()));
                if !attached_here && child.visual_parent().is_some_and(|p| p == this_ref) {
                    child.on_attached_to_visual_tree_core(e);
                }
            }
        }
    }

    fn on_detached_from_visual_tree_core(this: &Self, e: &VisualTreeAttachmentEventArgs) {
        ROOTED_VISUAL_CHILDREN_COUNT.with(|count| count.set(count.get() - 1));

        this.set_render_transform_subscription(None);

        this.disable_transitions();
        this.update_is_effectively_visible(true);
        this.on_detached_from_visual_tree(e);
        this.detach_from_compositor();
        if !this.detached_from_visual_tree.is_empty() {
            for (_, handler) in this.detached_from_visual_tree.snapshot().iter() {
                handler(e);
            }
        }
        if let Some(source) = this.presentation_source() {
            source.renderer().add_dirty(this);
        }
        *this.presentation_source.borrow_mut() = None;

        if let Some(children) = this.visual_children.get() {
            for child in children.snapshot().iter() {
                // A child removed within an event handler has already been
                // detached by the removal itself.
                if child.presentation_source().is_some() {
                    child.on_detached_from_visual_tree_core(e);
                }
            }
        }
    }

    fn on_attached_to_visual_tree(_this: &Self, _e: &VisualTreeAttachmentEventArgs) {}

    fn on_detached_from_visual_tree(_this: &Self, _e: &VisualTreeAttachmentEventArgs) {}

    fn on_visual_parent_changed(this: &Self, old_parent: Option<&Ref<Visual>>, new_parent: Option<&Ref<Visual>>) {
        this.raise_direct_property_changed(
            Self::visual_parent_property(),
            &old_parent.cloned(),
            &new_parent.cloned(),
        );
    }

    fn bypass_flow_direction_policies(_this: &Self) -> bool {
        false
    }

    fn clip_to_bounds_radius(_this: &Self) -> Option<crate::CornerRadius> {
        None
    }

    fn custom_hit_test(_this: &Self, _point: crate::Point) -> Option<bool> {
        None
    }

    fn custom_hit_test_geometry(
        _this: &Self,
        _geometry: &Ref<crate::media::Geometry>,
    ) -> Option<crate::media::IntersectionResult> {
        None
    }

    fn ensure_initialized_for_visual_brush(_this: &Self) {}

    fn create_composition_visual(this: &Self, compositor: &Rc<Compositor>) -> CompositionDrawListVisual {
        CompositionDrawListVisual::new(compositor, this)
    }

    fn detach_from_compositor(this: &Self) {
        // The shadow visual belongs to the composition visual it follows.
        this.release_theme_shadow_visual();
        let composition_visual = this.composition_visual.borrow_mut().take();
        if let Some(composition_visual) = composition_visual {
            if let Some(child) = this.child_composition_visual() {
                composition_visual.children().remove(&child);
            }
            if let Some(layer) = this.composition_layer_visual() {
                composition_visual.children().remove(&layer);
            }
            composition_visual.set_draw_list(None);
            composition_visual.set_opacity_mask(None);
            // The composition visual and its children refer to each other;
            // nothing collects such a cycle here, so the visual lets go of
            // its children. They are re-added when their visuals are
            // synchronized again.
            composition_visual.children().clear();
        }
    }

    fn synchronize_composition_child_visuals(this: &Self) {
        let Some(composition_visual) = this.composition_visual() else { return };
        let composition_children = composition_visual.children();
        let visual_children: Rc<Vec<Ref<Visual>>> =
            this.visual_children_snapshot().unwrap_or_else(|| Rc::new(Vec::new()));

        let mut sorted_children: Option<Vec<(Ref<Visual>, usize)>> = None;
        if this.has_non_uniform_z_index_children() && visual_children.len() > 1 {
            let mut sorted: Vec<(Ref<Visual>, usize)> =
                visual_children.iter().cloned().enumerate().map(|(index, visual)| (visual, index)).collect();
            // The indices keep the order of elements with the same Z index.
            sorted.sort_by(|lhs, rhs| lhs.0.z_index().cmp(&rhs.0.z_index()).then(lhs.1.cmp(&rhs.1)));
            sorted_children = Some(sorted);
        }

        let mut child_visual = this.child_composition_visual();

        // Check if the current visual somehow got migrated to another compositor
        if child_visual.as_ref().is_some_and(|child| !Rc::ptr_eq(child.compositor(), composition_visual.compositor())) {
            child_visual = None;
        }

        let mut layer_visual = this.composition_layer_visual();
        if layer_visual.as_ref().is_some_and(|layer| !Rc::ptr_eq(layer.compositor(), composition_visual.compositor())) {
            layer_visual = None;
        }

        let unloading_visuals: Vec<Rc<CompositionVisual>> = this
            .read_composition_extras(|extras| extras.unloading_visuals.clone())
            .unwrap_or_default()
            .into_iter()
            .filter(|unloading| Rc::ptr_eq(unloading.compositor(), composition_visual.compositor()))
            .collect();

        let child_count = visual_children.len();
        let child_at = |c: usize| -> &Ref<Visual> {
            match &sorted_children {
                Some(sorted) => &sorted[c].0,
                None => &visual_children[c],
            }
        };

        // The visuals that draw the theme shadows of the children, each shown just before the
        // visual of its child (WinUI parents it under the prepend visual of the caster), so that
        // it is under the child and clipped by the clips of this visual, not by the child's.
        // Looked at only when a child may cast one.
        let shadows: Option<Vec<Option<Rc<CompositionVisual>>>> =
            if visual_children.iter().any(|child| child.may_cast_theme_shadow()) {
                Some((0..child_count).map(|c| child_at(c).ensure_theme_shadow_composition_visual()).collect())
            } else {
                None
            };
        let shadow_at = |c: usize| -> Option<&Rc<CompositionVisual>> {
            shadows.as_ref().and_then(|shadows| shadows[c].as_ref())
        };
        let shadow_count = shadows.as_ref().map_or(0, |shadows| shadows.iter().flatten().count());

        let mut expected_count = child_count + shadow_count + unloading_visuals.len();
        if child_visual.is_some() {
            expected_count += 1;
        }
        if layer_visual.is_some() {
            expected_count += 1;
        }

        let same = |a: &Rc<CompositionVisual>, b: Option<CompositionDrawListVisual>| {
            b.is_some_and(|b| Rc::ptr_eq(a, &b))
        };

        if composition_children.count() == expected_count {
            let mut mismatch = false;
            let mut index = 0;
            for c in 0..child_count {
                if let Some(shadow) = shadow_at(c) {
                    if !Rc::ptr_eq(&composition_children.get(index), shadow) {
                        mismatch = true;
                        break;
                    }
                    index += 1;
                }
                if !same(&composition_children.get(index), child_at(c).composition_visual()) {
                    mismatch = true;
                    break;
                }
                index += 1;
            }

            if !mismatch {
                for unloading in &unloading_visuals {
                    if !Rc::ptr_eq(&composition_children.get(index), unloading) {
                        mismatch = true;
                    }
                    index += 1;
                }
                if let Some(child_visual) = &child_visual {
                    if !Rc::ptr_eq(&composition_children.get(index), child_visual) {
                        mismatch = true;
                    }
                    index += 1;
                }
                if let Some(layer_visual) = &layer_visual {
                    if !Rc::ptr_eq(&composition_children.get(index), layer_visual) {
                        mismatch = true;
                    }
                }
            }

            if !mismatch {
                return;
            }
        }

        composition_children.clear();
        for c in 0..child_count {
            if let Some(shadow) = shadow_at(c) {
                composition_children.add(shadow.clone());
            }
            if let Some(composition_child) = child_at(c).composition_visual() {
                composition_children.add((*composition_child).clone());
            }
        }

        for unloading in unloading_visuals {
            composition_children.add(unloading);
        }
        if let Some(child_visual) = child_visual {
            composition_children.add(child_visual);
        }
        if let Some(layer_visual) = layer_visual {
            composition_children.add(layer_visual);
        }
    }

    fn synchronize_composition_properties(this: &Self) {
        let Some(comp) = this.composition_visual() else { return };
        let bounds = this.bounds();

        // The implicit animations of the transitions, installed before the properties are
        // written (so that a change animates), except on the first synchronization of a new
        // composition visual (so that the initial values do not).
        this.apply_composition_transitions(&comp, false);

        // TODO: Introduce a dirty mask like WPF has, so we don't overwrite properties every time
        comp.set_offset(crate::Vector3D::new(bounds.x, bounds.y, 0.0));
        comp.set_size(crate::Vector::new(bounds.width, bounds.height));
        comp.set_visible(
            (this.is_visible() || this.is_shown_by_composition())
                && !this.is_hidden_by_composition()
                && !this.is_render_suppressed(),
        );
        comp.set_opacity(this.opacity() as f32);
        comp.set_clip_to_bounds(this.clip_to_bounds());
        comp.set_clip(this.clip().and_then(|clip| clip.platform_impl()));

        let opacity_mask = this.opacity_mask();
        let same_mask = match (comp.opacity_mask(), &opacity_mask) {
            (Some(a), Some(b)) => *a == **b,
            (None, None) => true,
            _ => false,
        };
        if !same_mask {
            comp.set_opacity_mask(opacity_mask);
        }

        let cache_mode = this.cache_mode().map(|cache_mode| cache_mode.get_for_compositor(comp.compositor()));
        let same_cache_mode = match (comp.cache_mode(), &cache_mode) {
            (Some(a), Some(b)) => Rc::ptr_eq(&a, b),
            (None, None) => true,
            _ => false,
        };
        if !same_cache_mode {
            comp.set_cache_mode(cache_mode);
        }

        let effect = this.effect();
        if !crate::media::EffectExtensions::effect_equals(comp.effect().as_deref(), effect.as_deref()) {
            comp.set_effect(effect.as_ref().map(crate::media::EffectExtensions::to_immutable));
        }

        comp.set_render_options(this.render_options());
        comp.set_text_options(this.text_options());

        let mut render_transform = crate::Matrix::IDENTITY;

        if this.has_mirror_transform() {
            render_transform = crate::Matrix::new(-1.0, 0.0, 0.0, 1.0, bounds.width, 0.0);
        }

        if let Some(transform) = this.render_transform() {
            let origin = this.render_transform_origin().to_pixels(crate::Size::new(bounds.width, bounds.height));
            let offset = crate::Matrix::create_translation(origin.x, origin.y);
            render_transform = render_transform * ((-offset) * transform.value() * offset);
        }

        // The `TransformMatrix` facade follows the render transform (see
        // `composition_facade_transform_matrix`).
        if let Some(facade) = this.composition_facade_transform_matrix() {
            render_transform = render_transform * facade;
        }

        // The zoom of a scroll presenter, after the transforms of the element itself.
        if let Some(manipulation) = this.manipulation_transform() {
            render_transform = render_transform * manipulation;
        }

        comp.set_transform_matrix(render_transform);

        if let Some(translation) = this.composition_translation() {
            comp.set_translation(translation);
        }

        this.synchronize_composition_facades(&comp);
        this.apply_composition_transitions(&comp, true);

        // The shadow of the theme follows the size, the visibility, the elevation and the theme.
        this.update_theme_shadow_visual();
    }

    fn invalidate_mirror_transform(this: &Self) {
        let flow_direction = this.flow_direction();
        let mut parent_flow_direction = FlowDirection::LeftToRight;
        let bypass = this.bypass_flow_direction_policies();
        let mut parent_bypass = false;

        if let Some(parent) = this.visual_parent() {
            parent_flow_direction = parent.flow_direction();
            parent_bypass = parent.bypass_flow_direction_policies();
        }

        let this_should_be_mirrored = flow_direction == FlowDirection::RightToLeft && !bypass;
        let parent_should_be_mirrored = parent_flow_direction == FlowDirection::RightToLeft && !parent_bypass;

        this.set_has_mirror_transform(this_should_be_mirrored != parent_should_be_mirrored);
    }
}

// Deviation (DEVIATIONS.md, Visual tree): the subscriptions to the values of
// the render-affecting properties are weak events in the managed original (`InvalidatedWeakEvent`): the value does not
// keep the visual, and the entries of visuals that were collected are removed
// from its list when the list is compacted. Here the handler of a visual holds
// it weakly too, and the visual takes its handlers out of the lists when it is
// dropped: a value many visuals share (the geometry of an icon that is a
// resource) would otherwise keep one entry, and the memory of the visual its
// weak reference holds, for every visual that ever drew it.
impl Drop for Visual {
    fn drop(&mut self) {
        for (_, subscription) in self.affects_render_subscriptions.get_mut().drain(..) {
            subscription.dispose();
        }
    }
}

crate::ferro_properties! { impl Visual {
    ferro_property!(
        /// Defines the `Bounds` property.
        pub fn bounds_property() -> DirectProperty<Visual, Rect> {
            FerroProperty::register_direct::<Visual, _>("Bounds", |o| o.bounds(), None, Rect::default())
        }
    );

    ferro_property!(
        /// Defines the `ClipToBounds` property.
        pub fn clip_to_bounds_property() -> StyledProperty<bool> {
            FerroProperty::register::<Visual, _>("ClipToBounds", false)
        }
    );

    ferro_property!(
        /// Defines the `Clip` property.
        pub fn clip_property() -> StyledProperty<Option<Ref<Geometry>>> {
            FerroProperty::register::<Visual, _>("Clip", None)
        }
    );

    ferro_property!(
        /// Defines the `Shadow` property (WinUI `UIElement.Shadow`): the shadow the element casts,
        /// a [`ThemeShadow`](crate::media::ThemeShadow).
        pub fn shadow_property() -> StyledProperty<Option<Ref<crate::media::Shadow>>> {
            FerroProperty::register::<Visual, _>("Shadow", None)
        }
    );

    ferro_property!(
        /// Defines the `Translation` property (WinUI `UIElement.Translation`): the facade
        /// [`translation`](Visual::translation) as a property markup can set
        /// (`Translation="0,0,32"`).
        pub fn translation_property() -> DirectProperty<Visual, crate::Vector3D> {
            FerroProperty::register_direct::<Visual, _>(
                "Translation",
                |o| o.translation(),
                Some(|o, value| o.set_translation(value)),
                crate::Vector3D::default(),
            )
        }
    );

    ferro_property!(
        /// Defines the `CacheMode` property.
        pub fn cache_mode_property() -> StyledProperty<Option<Ref<CacheMode>>> {
            FerroProperty::register::<Visual, _>("CacheMode", None)
        }
    );

    ferro_property!(
        /// Defines the `Effect` property.
        pub fn effect_property() -> StyledProperty<Option<Rc<dyn IEffect>>> {
            FerroProperty::register::<Visual, _>("Effect", None)
        }
    );

    ferro_property!(
        /// Defines the `OpacityMask` property.
        pub fn opacity_mask_property() -> StyledProperty<Option<Rc<dyn IBrush>>> {
            FerroProperty::register::<Visual, _>("OpacityMask", None)
        }
    );

    ferro_property!(
        /// Defines the `RenderTransform` property.
        pub fn render_transform_property() -> StyledProperty<Option<Rc<dyn ITransform>>> {
            FerroProperty::register::<Visual, _>("RenderTransform", None)
        }
    );

    ferro_property!(
        /// Defines the `RenderTransformOrigin` property.
        pub fn render_transform_origin_property() -> StyledProperty<RelativePoint> {
            FerroProperty::register::<Visual, _>("RenderTransformOrigin", RelativePoint::CENTER)
        }
    );

    ferro_property!(
        /// Defines the `IsVisible` property.
        pub fn is_visible_property() -> StyledProperty<bool> {
            FerroProperty::register::<Visual, _>("IsVisible", true)
        }
    );

    ferro_property!(
        /// Defines the `Opacity` property.
        pub fn opacity_property() -> StyledProperty<f64> {
            FerroProperty::register::<Visual, _>("Opacity", 1.0)
        }
    );

    ferro_property!(
        /// Defines the `HasMirrorTransform` property.
        pub fn has_mirror_transform_property() -> DirectProperty<Visual, bool> {
            FerroProperty::register_direct::<Visual, _>("HasMirrorTransform", |o| o.has_mirror_transform(), None, false)
        }
    );

    ferro_property!(
        /// Defines the `FlowDirection` attached property.
        pub fn flow_direction_property() -> AttachedProperty<FlowDirection> {
            FerroProperty::register_attached_with::<Visual, Visual, _>(
                "FlowDirection",
                StyledPropertyOptions::new(FlowDirection::LeftToRight).inherits(true),
            )
        }
    );

    ferro_property!(
        /// Defines the `VisualParent` property.
        pub fn visual_parent_property() -> DirectProperty<Visual, Option<Ref<Visual>>> {
            FerroProperty::register_direct::<Visual, _>("VisualParent", |o| o.visual_parent(), None, None)
        }
    );

    ferro_property!(
        /// Defines the `ZIndex` property.
        pub fn z_index_property() -> StyledProperty<i32> {
            FerroProperty::register::<Visual, _>("ZIndex", 0)
        }
    );
} }

impl Visual {
    fn static_constructor() {
        Self::affects_render::<Visual>(&[
            Self::bounds_property().as_property(),
            Self::clip_property().as_property(),
            Self::clip_to_bounds_property().as_property(),
            Self::is_visible_property().as_property(),
            Self::opacity_property().as_property(),
            Self::opacity_mask_property().as_property(),
            Self::effect_property().as_property(),
            Self::has_mirror_transform_property().as_property(),
        ]);
        Self::render_transform_property().changed().subscribe(Self::render_transform_changed);
        Self::clip_to_bounds_property().changed().subscribe(|_| bump_geometry_version());
        Self::render_transform_origin_property().changed().subscribe(|_| bump_geometry_version());
        Self::z_index_property().changed().subscribe(|e| {
            let Some(sender) = e.sender().downcast_ref::<Visual>() else { return };
            let parent = sender.visual_parent();
            if let Some(parent) = &parent {
                if sender.z_index() != 0 {
                    parent.has_non_uniform_z_index_children.set(true);
                }
            }
            sender.invalidate_visual();
            if let Some(parent) = &parent {
                if let Some(source) = parent.presentation_source() {
                    source.renderer().recalculate_children(parent);
                }
            }
        });
    }

    /// Creates the class data; see [`crate::FerroObject::construct`].
    pub fn construct() -> Self {
        Self {
            base: StyledElement::construct(),
            bounds: Cell::new(Rect::default()),
            presentation_source: RefCell::new(None),
            visual_parent: RefCell::new(None),
            has_mirror_transform: Cell::new(false),
            has_render_transform: Cell::new(false),
            has_manipulation_transform: Cell::new(false),
            is_effectively_visible: Cell::new(true),
            has_non_uniform_z_index_children: Cell::new(false),
            visual_children: OnceCell::new(),
            attached_to_visual_tree: HandlerList::new(),
            detached_from_visual_tree: HandlerList::new(),
            is_effectively_visible_changed: HandlerList::new(),
            render_options: Cell::new(RenderOptions::default()),
            text_options: Cell::new(TextOptions::default()),
            composition_visual: RefCell::new(None),
            child_composition_visual: RefCell::new(None),
            composition_extras: RefCell::new(None),
            render_transform_subscription: RefCell::new(None),
            affects_render_subscriptions: RefCell::new(Vec::new()),
        }
    }

    pub fn new() -> Ref<Self> {
        instantiate(Self::construct())
    }

    // --- events -----------------------------------------------------------

    /// Raised when the control is attached to a rooted visual tree.
    pub fn attached_to_visual_tree(
        &self,
        handler: impl Fn(&VisualTreeAttachmentEventArgs) + 'static,
    ) -> Rc<dyn IDisposable> {
        let token = self.attached_to_visual_tree.add(Rc::new(handler));
        let weak = self.to_ref().downgrade();
        Disposable::create(move || {
            if let Some(this) = weak.upgrade() {
                this.attached_to_visual_tree.remove(token);
            }
        })
    }

    /// Raised when the control is detached from a rooted visual tree.
    pub fn detached_from_visual_tree(
        &self,
        handler: impl Fn(&VisualTreeAttachmentEventArgs) + 'static,
    ) -> Rc<dyn IDisposable> {
        let token = self.detached_from_visual_tree.add(Rc::new(handler));
        let weak = self.to_ref().downgrade();
        Disposable::create(move || {
            if let Some(this) = weak.upgrade() {
                this.detached_from_visual_tree.remove(token);
            }
        })
    }

    /// Raised when `is_effectively_visible` changes.
    pub fn is_effectively_visible_changed(&self, handler: impl Fn() + 'static) -> Rc<dyn IDisposable> {
        let token = self.is_effectively_visible_changed.add(Rc::new(handler));
        let weak = self.to_ref().downgrade();
        Disposable::create(move || {
            if let Some(this) = weak.upgrade() {
                this.is_effectively_visible_changed.remove(token);
            }
        })
    }

    // --- properties -------------------------------------------------------

    /// The bounds of the control relative to its parent.
    #[inline]
    pub fn bounds(&self) -> Rect {
        self.bounds.get()
    }

    /// Sets the bounds of the control. Called by the layout system.
    pub fn set_bounds(&self, value: Rect) {
        if self.bounds.get() != value {
            bump_geometry_version();
        }
        self.set_and_raise_cell(Self::bounds_property(), &self.bounds, value);
    }

    /// Whether the control should be clipped to its bounds.
    pub fn clip_to_bounds(&self) -> bool {
        self.get_value(Self::clip_to_bounds_property())
    }

    pub fn set_clip_to_bounds(&self, value: bool) {
        self.set_value(Self::clip_to_bounds_property(), value)
    }

    /// The geometry clip for this visual.
    pub fn clip(&self) -> Option<Ref<Geometry>> {
        self.get_value(Self::clip_property())
    }

    pub fn set_clip(&self, value: impl Into<Nullable<Geometry>>) {
        self.set_value(Self::clip_property(), value.into().0)
    }

    /// The cache mode of the visual.
    pub fn cache_mode(&self) -> Option<Ref<CacheMode>> {
        self.get_value(Self::cache_mode_property())
    }

    pub fn set_cache_mode(&self, value: impl Into<Nullable<CacheMode>>) {
        self.set_value(Self::cache_mode_property(), value.into().0)
    }

    /// The effect of the control.
    pub fn effect(&self) -> Option<Rc<dyn IEffect>> {
        self.get_value(Self::effect_property())
    }

    pub fn set_effect(&self, value: Option<Rc<dyn IEffect>>) {
        self.set_value(Self::effect_property(), value)
    }

    /// The opacity mask of the control.
    pub fn opacity_mask(&self) -> Option<Rc<dyn IBrush>> {
        self.get_value(Self::opacity_mask_property())
    }

    pub fn set_opacity_mask(&self, value: Option<Rc<dyn IBrush>>) {
        self.set_value(Self::opacity_mask_property(), value)
    }

    /// The render transform of the control.
    pub fn render_transform(&self) -> Option<Rc<dyn ITransform>> {
        self.get_value(Self::render_transform_property())
    }

    pub fn set_render_transform(&self, value: Option<Rc<dyn ITransform>>) {
        self.set_value(Self::render_transform_property(), value)
    }

    /// The transform origin of the control.
    pub fn render_transform_origin(&self) -> RelativePoint {
        self.get_value(Self::render_transform_origin_property())
    }

    pub fn set_render_transform_origin(&self, value: RelativePoint) {
        self.set_value(Self::render_transform_origin_property(), value)
    }

    /// Whether this control and all its parents are visible.
    #[inline]
    pub fn is_effectively_visible(&self) -> bool {
        self.is_effectively_visible.get()
    }

    /// Whether this control is visible.
    pub fn is_visible(&self) -> bool {
        self.get_value(Self::is_visible_property())
    }

    pub fn set_is_visible(&self, value: bool) {
        self.set_value(Self::is_visible_property(), value)
    }

    /// The opacity of the control.
    pub fn opacity(&self) -> f64 {
        self.get_value(Self::opacity_property())
    }

    pub fn set_opacity(&self, value: f64) {
        self.set_value(Self::opacity_property(), value)
    }

    /// Whether `RenderTransform` has a value (not upstream: the transforms of the visual tree
    /// skip the property read when it has none).
    #[inline]
    pub(crate) fn has_render_transform(&self) -> bool {
        self.has_render_transform.get()
    }

    /// The manipulation transform of the visual (not upstream): a transform its parent applies
    /// to it after its render transform and before its position, about its top left corner. The
    /// scroll presenter of a zooming scroll viewer scales its content this way (WinUI applies the
    /// zoom of DirectManipulation to the content of a scroll viewer); it takes part in rendering,
    /// hit testing and the transforms between visuals as the render transform does. `None` by
    /// default.
    pub fn manipulation_transform(&self) -> Option<crate::Matrix> {
        if !self.has_manipulation_transform.get() {
            return None;
        }
        self.read_composition_extras(|extras| extras.manipulation_transform).flatten()
    }

    /// Sets [`manipulation_transform`](Self::manipulation_transform); the identity is no
    /// transform.
    pub fn set_manipulation_transform(&self, value: Option<crate::Matrix>) {
        let value = value.filter(|matrix| !matrix.is_identity());
        if self.manipulation_transform() == value {
            return;
        }
        self.has_manipulation_transform.set(value.is_some());
        self.with_composition_extras(|extras| extras.manipulation_transform = value);
        bump_geometry_version();
        self.invalidate_visual();
    }

    /// Whether the control is mirrored relative to its parent because of its
    /// flow direction.
    #[inline]
    pub fn has_mirror_transform(&self) -> bool {
        self.has_mirror_transform.get()
    }

    /// Sets the mirror transform flag.
    pub fn set_has_mirror_transform(&self, value: bool) {
        self.set_and_raise_cell(Self::has_mirror_transform_property(), &self.has_mirror_transform, value);
    }

    /// The text flow direction.
    pub fn flow_direction(&self) -> FlowDirection {
        self.get_value(Self::flow_direction_property())
    }

    pub fn set_flow_direction(&self, value: FlowDirection) {
        self.set_value(Self::flow_direction_property(), value)
    }

    /// Gets the value of the attached `FlowDirection` property on a visual.
    pub fn get_flow_direction(visual: &Visual) -> FlowDirection {
        visual.get_value(Self::flow_direction_property())
    }

    /// Sets the value of the attached `FlowDirection` property on a visual.
    pub fn set_flow_direction_on(visual: &Visual, value: FlowDirection) {
        visual.set_value(Self::flow_direction_property(), value)
    }

    /// The Z index of the control.
    ///
    /// Controls with a higher Z index appear in front of controls with a
    /// lower one. Among controls with the same value, order of appearance in
    /// the visual children decides.
    pub fn z_index(&self) -> i32 {
        self.get_value(Self::z_index_property())
    }

    pub fn set_z_index(&self, value: i32) {
        self.set_value(Self::z_index_property(), value)
    }

    /// The control's child visuals.
    pub fn visual_children(&self) -> &FerroList<Ref<Visual>> {
        self.visual_children.get_or_init(|| {
            let list = FerroList::new();
            list.set_reset_behavior(ResetBehavior::Remove);
            let weak = self.to_ref().downgrade();
            let validator_owner = weak.clone();
            list.set_validate(Some(Rc::new(move |item: &Ref<Visual>| {
                if let Some(parent) = item.visual_parent() {
                    let owner = validator_owner.upgrade();
                    panic!(
                        "The control {:?} already has a visual parent {:?} while trying to add it as a child of {:?}.",
                        item, parent, owner
                    );
                }
            })));
            list.add_collection_changed(Rc::new(move |e: &NotifyCollectionChangedEventArgs<'_, Ref<Visual>>| {
                if let Some(this) = weak.upgrade() {
                    this.visual_children_changed(e);
                }
            }));
            list
        })
    }

    /// The number of visual children, without creating the collection.
    #[inline]
    pub fn visual_children_count(&self) -> usize {
        self.visual_children.get().map_or(0, FerroList::count)
    }

    /// A snapshot of the visual children, without creating the collection.
    #[inline]
    pub fn visual_children_snapshot(&self) -> Option<Rc<Vec<Ref<Visual>>>> {
        self.visual_children.get().map(FerroList::snapshot)
    }

    /// The presentation source the visual is attached to.
    #[inline]
    pub fn presentation_source(&self) -> Option<Rc<dyn IPresentationSource>> {
        self.presentation_source.borrow().clone()
    }

    /// The root of the visual tree, if the control is attached to one.
    pub fn visual_root(&self) -> Option<Ref<Visual>> {
        self.presentation_source().and_then(|s| s.root_visual())
    }

    /// The render options of the visual; see the accessors on
    /// [`RenderOptions`].
    #[inline]
    pub(crate) fn render_options(&self) -> RenderOptions {
        self.render_options.get()
    }

    pub(crate) fn set_render_options(&self, value: RenderOptions) {
        self.render_options.set(value);
        self.invalidate_visual();
    }

    /// The text options of the visual; see the accessors on
    /// [`TextOptions`].
    #[inline]
    pub(crate) fn text_options(&self) -> TextOptions {
        self.text_options.get()
    }

    pub(crate) fn set_text_options(&self, value: TextOptions) {
        self.text_options.set(value);
        self.invalidate_visual();
    }

    /// The composition visual of the visual, while it is attached to a
    /// visual tree rendered by a compositor.
    pub fn composition_visual(&self) -> Option<CompositionDrawListVisual> {
        self.composition_visual.borrow().clone()
    }

    /// The composition visual shown as the last child of the composition
    /// visual of this visual (see `ElementComposition`).
    pub fn child_composition_visual(&self) -> Option<Rc<CompositionVisual>> {
        self.child_composition_visual.borrow().clone()
    }

    pub fn set_child_composition_visual(&self, value: Option<Rc<CompositionVisual>>) {
        *self.child_composition_visual.borrow_mut() = value;
    }

    fn with_composition_extras<R>(&self, f: impl FnOnce(&mut CompositionExtras) -> R) -> R {
        let mut extras = self.composition_extras.borrow_mut();
        f(extras.get_or_insert_with(Default::default))
    }

    fn read_composition_extras<R>(&self, f: impl FnOnce(&CompositionExtras) -> R) -> Option<R> {
        self.composition_extras.borrow().as_deref().map(f)
    }

    /// `UIElement.Lights`: the XAML lights the element holds. A light added
    /// to the collection is connected to the element (`OnConnected`) while
    /// the element is in a visual tree, and lights the targets of its id in
    /// the subtree of the element (winui-materials.md).
    pub fn lights(&self) -> FerroList<Ref<crate::media::XamlLight>> {
        if let Some(lights) = self.read_composition_extras(|extras| extras.lights.clone()).flatten() {
            return lights;
        }
        let lights: FerroList<Ref<crate::media::XamlLight>> = FerroList::new();
        let subscriptions = crate::media::xaml_light::track_lights(self, &lights);
        self.with_composition_extras(|extras| {
            extras.lights = Some(lights.clone());
            extras.lights_subscriptions = subscriptions;
        });
        lights
    }

    /// Whether the element holds a lights collection.
    pub fn has_lights(&self) -> bool {
        self.read_composition_extras(|extras| extras.lights.as_ref().is_some_and(|lights| lights.count() > 0))
            .unwrap_or(false)
    }

    /// The ids of the XAML lights that target the element.
    pub fn light_target_ids(&self) -> Vec<String> {
        self.read_composition_extras(|extras| extras.light_target_ids.clone()).unwrap_or_default()
    }

    /// Adds `id` to the ids of the XAML lights that target the element;
    /// returns whether it was added.
    pub(crate) fn add_light_target_id(&self, id: &str) -> bool {
        let added = self.with_composition_extras(|extras| {
            if extras.light_target_ids.iter().any(|existing| existing == id) {
                return false;
            }
            extras.light_target_ids.push(id.to_owned());
            true
        });
        if added && self.read_composition_extras(|extras| extras.light_target_subscription.is_none()).unwrap_or(true) {
            let subscription = crate::media::xaml_light::track_light_target(self);
            self.with_composition_extras(|extras| extras.light_target_subscription = Some(subscription));
        }
        added
    }

    /// Removes `id` from the ids of the XAML lights that target the element;
    /// returns whether it was there.
    pub(crate) fn remove_light_target_id(&self, id: &str) -> bool {
        self.read_composition_extras(|extras| extras.light_target_ids.iter().any(|existing| existing == id))
            .unwrap_or(false)
            && self.with_composition_extras(|extras| {
                extras.light_target_ids.retain(|existing| existing != id);
                true
            })
    }

    /// `UIElement.Translation`: the translation of the composition visual of the visual, applied
    /// after its render transform. Zero until set.
    ///
    /// As in WinUI the translation is not a styled property; setting it hands the `Translation`
    /// of the composition visual to this facade, which writes it whenever the visual is
    /// rendered again. While it was never set, the application may animate the `Translation` of
    /// the composition visual itself.
    pub fn translation(&self) -> crate::Vector3D {
        self.composition_translation().unwrap_or_default()
    }

    pub fn set_translation(&self, value: crate::Vector3D) {
        let old = self.translation();
        self.with_composition_extras(|extras| extras.translation = Some(value));
        self.invalidate_visual();
        if old != value {
            self.raise_direct_property_changed(Self::translation_property(), &old, &value);
        }
    }

    fn composition_translation(&self) -> Option<crate::Vector3D> {
        self.read_composition_extras(|extras| extras.translation).flatten()
    }

    /// Whether the composition visual of the visual is hidden by requests of the composition
    /// API (see [`add_composition_hide_request`](Self::add_composition_hide_request)).
    pub fn is_hidden_by_composition(&self) -> bool {
        self.read_composition_extras(|extras| extras.hide_requests > 0).unwrap_or(false)
    }

    /// Hides the composition visual of the visual until the matching
    /// [`remove_composition_hide_request`](Self::remove_composition_hide_request), whatever
    /// `IsVisible` says. Requests are counted. A connected animation hides its source and
    /// destination this way while it shows them through visual surfaces, which render a hidden
    /// visual (WinUI hides the element's visual with `SetConnectedAnimationRunning`).
    pub fn add_composition_hide_request(&self) {
        self.with_composition_extras(|extras| extras.hide_requests += 1);
        self.invalidate_visual();
    }

    /// Ends a request of [`add_composition_hide_request`](Self::add_composition_hide_request).
    pub fn remove_composition_hide_request(&self) {
        self.with_composition_extras(|extras| extras.hide_requests = extras.hide_requests.saturating_sub(1));
        self.invalidate_visual();
    }

    /// Whether presentation owners have suppressed this visual and its descendants in all
    /// render paths. Suppression changes no styled property, layout or logical visibility.
    /// It also applies to immediate bitmap and visual-brush captures; composition-only
    /// hiding remains independently capturable for connected animations.
    pub fn is_render_suppressed(&self) -> bool {
        self.read_composition_extras(|extras| extras.render_suppression_requests > 0)
            .unwrap_or(false)
    }

    /// Suppresses drawing until a matching remove request. Independent owners may hold
    /// requests concurrently. Input behavior is deliberately separate: editors that suppress
    /// presentation may additionally install their own temporary hit-test policy.
    pub fn add_render_suppression_request(&self) {
        let changed = self.with_composition_extras(|extras| {
            let previous = extras.render_suppression_requests;
            extras.render_suppression_requests = previous
                .checked_add(1)
                .expect("Render suppression request count exhausted");
            previous == 0
        });
        if changed {
            self.invalidate_visual();
        }
    }

    /// Releases one request without changing another owner's suppression or authored values.
    /// Removing a request when none is active is harmless.
    pub fn remove_render_suppression_request(&self) {
        if !self.is_render_suppressed() {
            return;
        }
        let changed = self.with_composition_extras(|extras| {
            extras.render_suppression_requests -= 1;
            extras.render_suppression_requests == 0
        });
        if changed {
            self.invalidate_visual();
        }
    }

    /// Whether the composition visual of the visual is kept visible by requests of the
    /// composition API although `IsVisible` is `false` (see
    /// [`add_composition_show_request`](Self::add_composition_show_request)).
    pub fn is_shown_by_composition(&self) -> bool {
        self.read_composition_extras(|extras| extras.show_requests > 0).unwrap_or(false)
    }

    /// Keeps the composition visual of the visual visible until the matching
    /// [`remove_composition_show_request`](Self::remove_composition_show_request), whatever
    /// `IsVisible` says. Requests are counted. An implicit hide animation keeps the element
    /// visible this way until it completes. A hide request wins over a show request.
    pub fn add_composition_show_request(&self) {
        self.with_composition_extras(|extras| extras.show_requests += 1);
        self.invalidate_visual();
    }

    /// Ends a request of [`add_composition_show_request`](Self::add_composition_show_request).
    pub fn remove_composition_show_request(&self) {
        self.with_composition_extras(|extras| extras.show_requests = extras.show_requests.saturating_sub(1));
        self.invalidate_visual();
    }

    /// A composition visual shown above the children of the visual and above its child
    /// composition visual (the layer of the connected animations of a top level, WinUI's
    /// `ConnectedAnimationRoot`).
    pub fn composition_layer_visual(&self) -> Option<Rc<CompositionVisual>> {
        self.read_composition_extras(|extras| extras.layer_visual.clone()).flatten()
    }

    /// Shows `visual` after the children of this visual until
    /// [`remove_composition_unloading_visual`](Self::remove_composition_unloading_visual): the
    /// image of a removed child that plays its implicit hide animation.
    pub(crate) fn add_composition_unloading_visual(&self, visual: Rc<CompositionVisual>) {
        self.with_composition_extras(|extras| extras.unloading_visuals.push(visual));
        if let Some(source) = self.presentation_source() {
            source.renderer().recalculate_children(self);
        }
    }

    /// Ends [`add_composition_unloading_visual`](Self::add_composition_unloading_visual).
    pub(crate) fn remove_composition_unloading_visual(&self, visual: &Rc<CompositionVisual>) {
        self.with_composition_extras(|extras| extras.unloading_visuals.retain(|v| !Rc::ptr_eq(v, visual)));
        if let Some(own) = self.composition_visual() {
            own.children().remove(visual);
        }
        if let Some(source) = self.presentation_source() {
            source.renderer().recalculate_children(self);
        }
    }

    /// Sets the visual of [`composition_layer_visual`](Self::composition_layer_visual).
    pub fn set_composition_layer_visual(&self, value: Option<Rc<CompositionVisual>>) {
        let old = self.with_composition_extras(|extras| std::mem::replace(&mut extras.layer_visual, value.clone()));
        if let (Some(old), Some(own)) = (&old, self.composition_visual()) {
            if !value.as_ref().is_some_and(|new| Rc::ptr_eq(new, old)) {
                own.children().remove(old);
            }
        }
        if let Some(source) = self.presentation_source() {
            source.renderer().recalculate_children(self);
        }
    }

    /// Makes sure the visual has a composition visual on `compositor` and
    /// returns it.
    pub fn attach_to_compositor(&self, compositor: &Rc<Compositor>) -> CompositionDrawListVisual {
        let current = self.composition_visual();
        match current {
            Some(current) if Rc::ptr_eq(current.compositor(), compositor) => current,
            _ => {
                let created = self.create_composition_visual(compositor);
                *self.composition_visual.borrow_mut() = Some(created.clone());
                self.composition_visual_created(&created);
                created
            }
        }
    }

    /// Whether any child has a non-default Z index.
    pub fn has_non_uniform_z_index_children(&self) -> bool {
        self.has_non_uniform_z_index_children.get()
    }

    /// Whether this control is attached to a visual root.
    #[inline]
    pub fn is_attached_to_visual_tree(&self) -> bool {
        self.presentation_source.borrow().is_some()
    }

    /// The control's parent visual.
    #[inline]
    pub fn visual_parent(&self) -> Option<Ref<Visual>> {
        self.visual_parent.borrow().as_ref().and_then(WeakRef::upgrade)
    }

    /// The number of visuals attached to a rooted visual tree (on this
    /// thread; visuals are UI-thread-affine).
    pub(crate) fn rooted_visual_children_count() -> i32 {
        ROOTED_VISUAL_CHILDREN_COUNT.with(Cell::get)
    }

    // --- methods ----------------------------------------------------------

    /// Invalidates the visual and queues a repaint.
    pub fn invalidate_visual(&self) {
        if let Some(source) = self.presentation_source() {
            source.renderer().add_dirty(self);
        }
    }

    /// Indicates that a property change should cause `invalidate_visual` to
    /// be called on objects of class `T`.
    ///
    /// When the value of such a property is a media object that can change
    /// (a brush, pen, geometry, transform, effect or image), its
    /// invalidation invalidates the visual as well.
    pub fn affects_render<T: ObjectType + Upcast<Visual>>(properties: &[&'static FerroProperty]) {
        for property in properties {
            if can_value_affect_render(property.property_type()) {
                property.changed().subscribe(|e| {
                    if let Some(sender) = e.sender().downcast_ref::<T>() {
                        let visual: &Visual = sender.upcast();
                        visual.update_affects_render_subscription(e);
                        visual.invalidate_visual();
                    }
                });
            } else {
                property.changed().subscribe(|e| {
                    if let Some(sender) = e.sender().downcast_ref::<T>() {
                        let visual: &Visual = sender.upcast();
                        visual.invalidate_visual();
                    }
                });
            }
        }
    }

    /// Moves the invalidation subscription of a render-affecting property
    /// from its old value to its new value.
    fn update_affects_render_subscription(&self, e: &FerroPropertyChangedEventArgs<'_>) {
        let property = e.property();
        let old = {
            let mut subscriptions = self.affects_render_subscriptions.borrow_mut();
            let position = subscriptions.iter().position(|(p, _)| *p == property);
            position.map(|position| subscriptions.swap_remove(position))
        };
        if let Some((_, subscription)) = old {
            subscription.dispose();
        }

        let weak = self.to_ref().downgrade();
        let subscription = subscribe_invalidated(
            e.new_value(),
            Rc::new(move || {
                if let Some(target) = weak.upgrade() {
                    target.invalidate_visual();
                }
            }),
        );
        if let Some(subscription) = subscription {
            self.affects_render_subscriptions.borrow_mut().push((property, subscription));
        }
    }

    /// Called when a visual's render transform property changes: while the
    /// visual is attached, the subscription to the transform's `changed`
    /// notification moves from the old value to the new one.
    fn render_transform_changed(e: &FerroPropertyChangedEventArgs<'_>) {
        let Some(sender) = e.sender().downcast_ref::<Visual>() else { return };
        let (_, new_value) = e.get_old_and_new_value::<Option<Rc<dyn ITransform>>>();
        sender.has_render_transform.set(new_value.is_some());
        bump_geometry_version();

        if sender.visual_root().is_some() {

            // The old transform's subscription is the one held.
            let subscription = new_value.as_ref().and_then(|new_value| {
                let new_transform = new_value.as_any().downcast_ref::<Transform>()?;
                let weak = sender.to_ref().downgrade();
                Some(new_transform.changed(move || {
                    if let Some(visual) = weak.upgrade() {
                        visual.render_transform_value_changed();
                    }
                }))
            });
            sender.set_render_transform_subscription(subscription);

            sender.invalidate_visual();
        }
    }

    /// Called when the render transform's `changed` notification is raised.
    fn render_transform_value_changed(&self) {
        bump_geometry_version();
        self.invalidate_visual();
    }

    fn set_render_transform_subscription(&self, value: Option<Rc<dyn IDisposable>>) {
        let previous = self.render_transform_subscription.replace(value);
        if let Some(previous) = previous {
            previous.dispose();
        }
    }

    /// Attaches or detaches the root visual of a presentation source.
    pub fn set_presentation_source_for_root_visual(&self, presentation_source: Option<Rc<dyn IPresentationSource>>) {
        let current = self.presentation_source();
        let same = match (&current, &presentation_source) {
            (Some(a), Some(b)) => Rc::ptr_eq(a, b),
            (None, None) => true,
            _ => false,
        };
        if same {
            return;
        }

        if let Some(current) = current {
            assert!(
                presentation_source.is_none(),
                "Visual is already attached to a presentation source. Only one presentation source can be \
                 attached to a visual tree."
            );
            self.on_detached_from_visual_tree_core(&VisualTreeAttachmentEventArgs::new(None, current));
        }

        *self.presentation_source.borrow_mut() = presentation_source.clone();

        if let Some(source) = presentation_source {
            let e = VisualTreeAttachmentEventArgs::new(None, source);
            self.on_attached_to_visual_tree_core(&e);
        }
    }

    fn update_is_effectively_visible(&self, parent_state: bool) {
        let is_effectively_visible = parent_state && self.is_visible();
        if self.is_effectively_visible.get() == is_effectively_visible {
            return;
        }
        self.is_effectively_visible.set(is_effectively_visible);
        if !self.is_effectively_visible_changed.is_empty() {
            for (_, handler) in self.is_effectively_visible_changed.snapshot().iter() {
                handler();
            }
        }
        // PERF-SENSITIVE: this is called on the entire hierarchy.
        if let Some(children) = self.visual_children.get() {
            for child in children.snapshot().iter() {
                child.update_is_effectively_visible(is_effectively_visible);
            }
        }
    }

    fn set_visual_parent(&self, value: Option<&Ref<Visual>>) {
        let old = self.visual_parent();
        if old.as_ref() == value {
            return;
        }
        *self.visual_parent.borrow_mut() = value.map(Ref::downgrade);
        bump_geometry_version();

        if let (Some(source), Some(old)) = (self.presentation_source(), &old) {
            let e = VisualTreeAttachmentEventArgs::new(Some(old.clone()), source);
            self.on_detached_from_visual_tree_core(&e);
        }

        if let Some(parent) = value {
            if let Some(source) = parent.presentation_source() {
                let e = VisualTreeAttachmentEventArgs::new(Some(parent.clone()), source);
                self.on_attached_to_visual_tree_core(&e);
            }
        }

        self.on_visual_parent_changed(old.as_ref(), value);
    }

    fn visual_children_changed(&self, e: &NotifyCollectionChangedEventArgs<'_, Ref<Visual>>) {
        match e.action {
            NotifyCollectionChangedAction::Add => {
                let this = self.to_ref();
                for visual in e.new_items {
                    visual.set_visual_parent(Some(&this));
                }
            }
            NotifyCollectionChangedAction::Remove => {
                for visual in e.old_items {
                    visual.set_visual_parent(None);
                }
            }
            NotifyCollectionChangedAction::Replace => {
                for visual in e.old_items {
                    visual.set_visual_parent(None);
                }
                let this = self.to_ref();
                for visual in e.new_items {
                    visual.set_visual_parent(Some(&this));
                }
            }
            NotifyCollectionChangedAction::Move | NotifyCollectionChangedAction::Reset => {}
        }
    }
}