Trait DesktopBackend 

pub trait DesktopBackend: Send + 'static {
    // Required methods
    fn list_icons(&mut self) -> Result<Vec<IconSnapshot>, DesktopError>;
    fn get_flags(&mut self) -> Result<u32, DesktopError>;
    fn apply_flags(
        &mut self,
        mask: u32,
        values: u32,
    ) -> Result<(), DesktopError>;
    fn set_positions(
        &mut self,
        moves: &[(IconId, Point)],
    ) -> Result<Vec<IconId>, DesktopError>;
    fn list_monitors(&mut self) -> Result<Vec<MonitorInfo>, DesktopError>;
    fn begin_overlay_session(
        &mut self,
        plans: &[IconRenderPlan],
        render_options: OverlayRenderOptions,
    ) -> Result<(), DesktopError>;
    fn commit_overlay_frame(
        &mut self,
        positions: &[(IconId, Point)],
    ) -> Result<(), DesktopError>;
    fn finalize_overlay_session(
        &mut self,
        final_positions: &[(IconId, Point)],
    ) -> Result<FinalCommitOutcome, DesktopError>;

    // Provided methods
    fn desktop_info(
        &mut self,
        _icons: &[IconSnapshot],
    ) -> Result<DesktopInfo, DesktopError> { ... }
    fn commit_visual_frame(
        &mut self,
        frame: &[IconFrame],
    ) -> Result<(), DesktopError> { ... }
    fn discard_overlay_session(&mut self) { ... }
    fn validate_prepared_session(&mut self) -> Result<(), DesktopError> { ... }
    fn prepare_scene_renderer(
        &mut self,
        _canvas: Canvas,
        _plans: &[IconRenderPlan],
        _options: OverlayRenderOptions,
    ) -> Result<Box<dyn SceneRenderer>, DesktopError> { ... }
    fn capture_overlay(
        &mut self,
        _seconds: f64,
    ) -> Result<CapturedFrame, DesktopError> { ... }
    fn set_real_icons_visible(
        &mut self,
        _visible: bool,
    ) -> Result<(), DesktopError> { ... }
    fn poll_overlay_session(&mut self) -> Result<(), DesktopError> { ... }
    fn render_overlay_snapshot(
        &mut self,
        width_px: u32,
        height_px: u32,
        dpi_scale: f32,
        positions: &[(IconId, Point)],
        render_options: OverlayRenderOptions,
    ) -> Result<SnapshotFrame, DesktopError> { ... }
}

The single point of contact between the animation engine and the OS desktop.

Threading

A DesktopBackend is owned by the engine’s worker thread and is never accessed concurrently. It only needs to be Send, not Sync.

Method contracts

• list_icons returns a snapshot of every icon currently visible on the desktop. Order is unspecified.
• get_flags returns the desktop folder-view flags word verbatim.
• [apply_flags(mask, values)] performs a masked update: new_flags = (old_flags & !mask) | (values & mask) — matching the IFolderView2::SetCurrentFolderFlags semantics used by the legacy Windows implementation.
• set_positions commits the entire batch atomically (from the caller’s perspective) and returns the subset of ids that could not be resolved by the backend so the engine can drop them from the active set. Used by the direct-positioning API and by the engine’s overlay-unavailable fallback path.
• list_monitors returns every connected display in the virtual- screen coordinate system icon positions use. Order is unspecified but the primary monitor always has is_primary = true.
• begin_overlay_session / commit_overlay_frame / finalize_overlay_session together drive the overlay-based animation flow — see the trio’s individual docs.

Required Methods

fn list_icons(&mut self) -> Result<Vec<IconSnapshot>, DesktopError>

fn get_flags(&mut self) -> Result<u32, DesktopError>

fn apply_flags(&mut self, mask: u32, values: u32) -> Result<(), DesktopError>

fn set_positions( &mut self, moves: &[(IconId, Point)], ) -> Result<Vec<IconId>, DesktopError>

Commit a batch of (id, new_position) moves. Returns the ids the backend could not resolve (i.e. icons that vanished or were never on the desktop).

fn list_monitors(&mut self) -> Result<Vec<MonitorInfo>, DesktopError>

Enumerate every connected display. Bounds are reported in the same virtual-screen coordinate system used by list_icons and set_positions.

fn begin_overlay_session( &mut self, plans: &[IconRenderPlan], render_options: OverlayRenderOptions, ) -> Result<(), DesktopError>

Prepare an overlay animation session covering the icons in plans.

The backend acquires whatever OS resources it needs (window, renderer, icon bitmaps), pre-renders the first frame at each icon’s source position, and returns success only after the overlay is ready to display that first frame.

On success the backend has not yet:

• shown the overlay window,
• hidden the real desktop icons.

Both happen implicitly on the first call to commit_overlay_frame.

Errors

• DesktopError::OverlayUnavailable — the platform doesn’t support overlay rendering, or a documented compatibility probe failed. The engine handles this by taking the loud-warning fallback path.
• any other DesktopError — engine surfaces as FinishReason::Error and aborts the animation without moving the icons.

fn commit_overlay_frame( &mut self, positions: &[(IconId, Point)], ) -> Result<(), DesktopError>

Update the overlay’s rendered icon positions to positions.

The first call to this method also, atomically from the caller’s perspective:

• shows the overlay window,
• waits for at least one composition frame to reach the display,
• hides the real desktop icons via the Shell’s own visibility mechanism.

Subsequent calls only update the overlay’s icon-copy positions and re-present. No contact is made with IFolderView2.

fn finalize_overlay_session( &mut self, final_positions: &[(IconId, Point)], ) -> Result<FinalCommitOutcome, DesktopError>

End the animation session and commit the final positions to the Shell.

Sequence:

1. IFolderView2::SelectAndPositionItems(final_positions, SVSI_POSITIONITEM) — one call, all icons, matching legacy.
2. Poll IFolderView2::GetItemPosition until at least one moved icon reports its new position (up to a short timeout).
3. Restore real-icon visibility.
4. Force one desktop repaint.
5. Hide + destroy the overlay window.

This method must clear any Shell-side icon-hiding flag it applied, even on failure paths — the engine relies on this invariant to guarantee the real icons come back after an animation.

Provided Methods

fn desktop_info( &mut self, _icons: &[IconSnapshot], ) -> Result<DesktopInfo, DesktopError>

Query live display/grid metrics using the worker’s current icon snapshot. Must not reposition icons or change folder flags.

fn commit_visual_frame( &mut self, frame: &[IconFrame], ) -> Result<(), DesktopError>

Commit positions and visual clocks together. Non-GPU backends ignore visuals.

fn discard_overlay_session(&mut self)

Discard a prepared, never-started session without touching Shell positions.

fn validate_prepared_session(&mut self) -> Result<(), DesktopError>

Reject a prepared snapshot invalidated by environment changes, before any Shell writes.

fn prepare_scene_renderer( &mut self, _canvas: Canvas, _plans: &[IconRenderPlan], _options: OverlayRenderOptions, ) -> Result<Box<dyn SceneRenderer>, DesktopError>

fn capture_overlay( &mut self, _seconds: f64, ) -> Result<CapturedFrame, DesktopError>

fn set_real_icons_visible(&mut self, _visible: bool) -> Result<(), DesktopError>

fn poll_overlay_session(&mut self) -> Result<(), DesktopError>

fn render_overlay_snapshot( &mut self, width_px: u32, height_px: u32, dpi_scale: f32, positions: &[(IconId, Point)], render_options: OverlayRenderOptions, ) -> Result<SnapshotFrame, DesktopError>

Render one frame of the overlay off-screen and return the raw pixels — never touches an HWND, DirectComposition target, or the real desktop. Safe to call at any time, including while a begin_overlay_session is active on another animation.

positions are in overlay-local pixel coordinates — the caller is responsible for translating from virtual-screen coordinates if needed (subtract the overlay’s origin). Only icons whose id is present in positions are drawn; ids not found in the backend’s caches (never list_icons’d, or the icon vanished) render as placeholder tiles.

dpi_scale is the scale factor to render at (1.0 → 96 DPI, 2.5 → 240 DPI). Icon-bitmap sizing follows the backend-supplied IconRenderPlan::size_px; the DPI setting only affects DirectWrite text hinting.

Default implementation returns DesktopError::OverlayUnavailable — non-rendering backends (FakeBackend, StubBackend) inherit this.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl DesktopBackend for FakeDesktop