initial commit

2026-11-04 14:29:22 -06:00
parent 73028cc5ba
commit 3f37abf34a
170 changed files with 22100 additions and 0 deletions
@@ -0,0 +1,115 @@
+using System.Windows;
+
+namespace LiveWall.Sdk;
+
+/// <summary>
+/// A visual layer drawn on top of the wallpaper, inside LiveWall's desktop overlay window (the same
+/// window that carries the desktop icons). Because that window is per-pixel transparent, only the
+/// pixels you paint block the mouse - everything else falls through to the desktop.
+/// </summary>
+public interface IWallpaperOverlay
+{
+    /// <summary>Shown in the plugin's UI and the diagnostics report.</summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Creates the visual. Called once per display, on the UI thread. Keep it cheap and transparent.
+    /// The returned element is stretched to the display and is not hit-testable by default.
+    /// </summary>
+    FrameworkElement CreateView(OverlayContext context);
+
+    /// <summary>Called whenever the wallpaper, playback or interaction state changes.</summary>
+    void Update(OverlayState state);
+
+    /// <summary>Called when the user hides the overlay or the plugin is disabled.</summary>
+    void OnVisibilityChanged(bool visible) { }
+}
+
+/// <summary>Display specific context handed to <see cref="IWallpaperOverlay.CreateView"/>.</summary>
+public sealed class OverlayContext
+{
+    public int DisplayIndex { get; init; }
+    public string DeviceName { get; init; } = "";
+    public double Width { get; init; }
+    public double Height { get; init; }
+    public double DpiScale { get; init; } = 1.0;
+    public bool Primary { get; init; }
+}
+
+/// <summary>State handed to <see cref="IWallpaperOverlay.Update"/>.</summary>
+public sealed class OverlayState
+{
+    public string Kind { get; init; } = "";
+    public string Source { get; init; } = "";
+    public string Title { get; init; } = "";
+    public bool IsPlaying { get; init; }
+    public bool IsPaused { get; init; }
+    public bool IsInteractive { get; init; }
+    public DateTime TimestampUtc { get; init; } = DateTime.UtcNow;
+}
+
+/// <summary>A page the plugin adds to the LiveWall settings window (Plugins tab).</summary>
+public interface IPluginSettingsPage
+{
+    string Title { get; }
+
+    /// <summary>One or two sentences for the page header.</summary>
+    string Description { get; }
+
+    /// <summary>Builds the page content. Called once, on the UI thread.</summary>
+    FrameworkElement CreateView();
+}
+
+/// <summary>
+/// Rewrites wallpaper requests before the engine applies them: resolve a URL, swap a file, pin a
+/// playlist entry, or veto a change by returning the previous request.
+/// </summary>
+public interface IWallpaperFilter
+{
+    /// <summary>Higher runs first. 0 is a good default.</summary>
+    int Priority { get; }
+
+    /// <summary>Return the request to apply (return the argument unchanged to leave it alone).</summary>
+    WallpaperRequest Apply(WallpaperRequest request, IHostActions host);
+}
+
+/// <summary>
+/// Renders wallpaper sources the built-in players cannot handle. The first renderer whose
+/// <see cref="CanRender"/> returns true wins (highest <see cref="Priority"/> first), so a plugin can
+/// also take over a source LiveWall would otherwise play itself.
+/// </summary>
+public interface IWallpaperRendererPlugin
+{
+    string Name { get; }
+
+    /// <summary>Higher wins over other plugins (built-in renderers are not in this race).</summary>
+    int Priority { get; }
+
+    /// <summary>Decides whether this renderer handles the source string.</summary>
+    bool CanRender(WallpaperRequest request);
+
+    IWallpaperRenderer Create();
+}
+
+/// <summary>The renderer instance. LiveWall owns its lifetime.</summary>
+public interface IWallpaperRenderer : IDisposable
+{
+    /// <summary>The visual shown as the wallpaper. Keep the background opaque.</summary>
+    FrameworkElement View { get; }
+
+    /// <summary>Loads the source. Throw to report a problem (it is shown to the user).</summary>
+    void Load(WallpaperRequest request);
+
+    void Play();
+    void Pause();
+    void Unload();
+
+    /// <summary>Volume is 0–100, speed 0.25–4.</summary>
+    void ApplyPlayback(bool muted, double volume, double speed);
+
+    /// <summary>Raised when playback fails (message is shown in the status bar and the log).</summary>
+    event EventHandler<string>? Failed;
+
+    /// <summary>Raised when a non-looping source finished.</summary>
+    event EventHandler? Ended;
+}