window_host.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/view/pending_damage.hpp>
#include <pulp/view/view.hpp>
#include <algorithm>
#include <cstdint>
#include <set>
#include <string>
#include <memory>
#include <functional>
#include <vector>
 
#include <pulp/platform/gpu_fwd.hpp>
 
namespace pulp::render {
class RenderLoop;
}
 
namespace pulp::canvas {
class Canvas;
}
 
namespace pulp::view {
 
class NativeViewHost;
 
enum class WindowType;  // Forward-declared from window_manager.hpp
 
struct WindowOptions {
    struct MenuCommand {
        std::string menu;
        std::string title;
        KeyCode key = KeyCode::unknown;
        std::uint16_t modifiers = kModNone;
        std::function<void()> action;
        enum class AppMenuSection : std::uint8_t { commands, after_about };
        AppMenuSection app_menu_section = AppMenuSection::commands;
    };
 
    std::string title = "Pulp";
    float width = 400;
    float height = 300;
    float min_width = 0;   
    float min_height = 0;  
    bool resizable = true;
    bool use_gpu = false;  

    std::uint32_t background_rgb = 0x1E1E2E;

    bool initially_hidden = false;

    bool secondary_window = false;
 
    // ── Multi-window hints ──────────────────────────────────────────────
    // These are used by WindowManager to configure platform-specific
    // window behavior. Callers creating standalone windows can ignore them.
 
    WindowType* window_type = nullptr;  
    void* parent_native_handle = nullptr; 
    void* shared_gpu_device = nullptr;  

    std::vector<MenuCommand> menu_commands;
};
 
// Native window that hosts a View tree and renders it.
//
// Platform support:
//   - macOS: native NSWindow-backed impl in window_host_mac.mm, including
//     native content handles and child-view attach/bounds/detach.
//   - iOS: native UIWindow-backed impl in window_host_ios.mm. The standalone
//     iOS host does not currently expose native child-view embedding.
//   - Windows/Linux/Android: no built-in impl — the host app or a future
//     platform module registers a factory via set_factory(). Without a
//     factory, create() returns nullptr so callers can surface "platform
//     unsupported" through has_factory() rather than a silent null.
class WindowHost {
public:
    struct ContentSize {
        uint32_t width = 0;
        uint32_t height = 0;
    };
 
    using ResizeCallback = std::function<void(uint32_t width, uint32_t height)>;
 
    // Create a window hosting the given view tree
    static std::unique_ptr<WindowHost> create(View& root, const WindowOptions& options);
 
    // Host-registered factory. Installed by the platform layer of a host app
    // on non-Apple targets. Apple targets use the built-in native impl and
    // ignore the factory.
    using Factory = std::function<std::unique_ptr<WindowHost>(
        View& root, const WindowOptions& options)>;
    static void set_factory(Factory factory);
    static void clear_factory();
    static bool has_factory();

    virtual ~WindowHost();
 
    // Show/hide the window
    virtual void show() = 0;
    virtual void hide() = 0;
    virtual bool is_visible() const = 0;
 
    // Request a repaint immediately. Platform impls translate this to the
    // native invalidation call (setNeedsDisplay, InvalidateRect, …).
    virtual void repaint() = 0;
 
    // ── VBlank-locked safe-repaint ──────────────────────────────────────
    //
    // The canonical pattern for "something changed, the UI needs to redraw"
    // is *"set a dirty flag, repaint on the next frame"* rather than the
    // legacy periodic-polling pattern (Binding::poll() on a timer).
    //
    // mark_dirty() is the consumer entry point. When a RenderLoop has been
    // attached via attach_render_loop(), it coalesces every call between
    // two vblanks into exactly one request_frame() — so N state changes in
    // one frame cost one repaint, locked to the display refresh. When no
    // RenderLoop is attached it falls through to repaint() so existing
    // callers keep working unchanged.
    //
    // Non-virtual on purpose: the coalescing policy is platform-agnostic
    // and lives here so every platform host shares one implementation.
    void mark_dirty();
 
    // Bounded variant: accumulate a dirty region (in root/window coordinates)
    // so a host's paint path can invalidate + composite only the changed area
    // instead of the whole surface — the "static chrome doesn't re-composite"
    // win when a single live sub-view (meter, grid, custom overlay) updates.
    // Schedules a repaint exactly like the no-arg mark_dirty(). A zero/negative
    // rect, or any call after a full mark_dirty() in the same frame, escalates
    // to a full repaint. A host that never consults pending_dirty_bounds()
    // simply repaints in full, so bounded marks are always safe to ignore.
    void mark_dirty(const Rect& root_rect);
 
    // Schedule a frame WITHOUT adding damage: for work that changed nothing
    // yet needs a frame to run (a requestAnimationFrame callback queued by a
    // message handler). Whatever that frame changes marks its own damage; a
    // frame that marks nothing repaints in full, as an unbounded one always
    // has.
    void request_frame() {
        schedule_repaint();
    }
 
    // True when the pending repaint covers the whole surface. Defaults true
    // (the first frame is always full) and after any no-arg mark_dirty();
    // becomes false once clear_pending_dirty() runs and only bounded
    // mark_dirty(rect) calls have arrived since.
    bool pending_repaint_is_full() const { return damage_.is_full(); }
 
    // Bounding box (root coords) of the bounded mark_dirty(rect) calls since the
    // last clear_pending_dirty(). Only meaningful when pending_repaint_is_full()
    // is false and has_pending_dirty_bounds() is true.
    bool has_pending_dirty_bounds() const { return damage_.has_bounds(); }
    Rect pending_dirty_bounds() const { return damage_.bounds(); }
 
    // Reset the accumulated dirty region. A host calls this after it has
    // painted and submitted the frame (mirrors DirtyTracker::clear()).
    void clear_pending_dirty() { damage_.clear(); }
 
    // Read this frame's damage and clear it in one step, so a host cannot
    // consult the accessors above and then clear a different logical state.
    // A frame that does NOT reach its intended output hands the snapshot back
    // with restore_pending_dirty(). Same contract as PluginViewHost — both
    // hosts share one PendingDamage.
    PendingDamage::Snapshot take_pending_dirty() { return damage_.take(); }
    void restore_pending_dirty(const PendingDamage::Snapshot& snapshot) {
        damage_.restore(snapshot);
    }
 
    // Consume the accumulated dirty region and paint `root`, then clear the
    // pending region. This is the reference consumer for the bounded-invalidation
    // path (invalidate → accumulate → consume).
    //
    // SAFE BY DEFAULT: with `surface_preserves_outside_clip == false` (the
    // default) this always paints the whole tree — identical to
    // `root.paint_all(canvas)` plus the clear. Only when the caller AFFIRMS that
    // its surface preserves the previous frame's content outside the clip does a
    // bounded (non-full) pending region clip the canvas to pending_dirty_bounds()
    // so a clip-honoring backend (Skia) skips re-rasterizing static chrome. The
    // opt-in is a hard requirement, not just advice: clipping a frame whose
    // surface does NOT preserve outside content (a swapchain that clears each
    // frame, or any frame invalidated with a full `setNeedsDisplay:YES`) would
    // leave the static chrome blank. A host earns `true` by invalidating only the
    // dirty region through the platform's native damage path (AppKit
    // `setNeedsDisplayInRect:`, an X/Win damage rect, a content-preserving
    // swapchain) — and by escalating any relayout that MOVES a live sub-view to a
    // full repaint, so the accumulated bounds can't clip away the sub-view's new
    // position. `root`'s own background/border fill happens inside paint_all(),
    // so it is clipped too. Backends that ignore clips still paint correctly.
    void paint_root(canvas::Canvas& canvas, View& root,
                    bool surface_preserves_outside_clip = false);
 
    // Attach (or detach, with nullptr) a vblank-paced RenderLoop that
    // mark_dirty() should drive. Ownership stays with the caller; the loop
    // must outlive the host or be detached first. Optional — hosts that
    // already run their own native display-link loop can leave this unset
    // and mark_dirty() degrades to a direct repaint().
    void attach_render_loop(render::RenderLoop* loop) { render_loop_ = loop; }
 
    // The attached RenderLoop, or nullptr.
    render::RenderLoop* render_loop() const { return render_loop_; }
 
    // Native host/window handles for embedding child platform views such as
    // WebViews. These are instance capabilities, not platform guarantees:
    // callers must check for non-null handles before attempting native child
    // embedding. Default implementations return nullptr on hosts that do not
    // expose native handles.
    virtual void position_beside(WindowHost* other) { (void)other; }
 
    virtual void* native_window_handle() const { return nullptr; }
    virtual void* native_content_view_handle() const { return nullptr; }
    virtual void* dawn_device_handle() const { return nullptr; }
    virtual void* dawn_queue_handle() const { return nullptr; }
    virtual void* dawn_instance_handle() const { return nullptr; }
    virtual render::GpuSurface* gpu_surface() const { return nullptr; }

    virtual double gpu_render_time_ms() const { return 0.0; }

    virtual bool gpu_render_timing_available() const { return false; }
 
    virtual ContentSize get_content_size() const;
 
    // Attach/detach a platform-native child view inside this host. Coordinates
    // use Pulp's top-left origin convention. Returning false is the canonical
    // unsupported/rejected signal. Non-Apple factory-backed hosts that support
    // native child embedding must override all three methods and should keep
    // attachment state in the concrete host.
    virtual bool attach_native_child_view(void* child_view,
                                          float x,
                                          float y,
                                          float width,
                                          float height) {
        (void) child_view;
        (void) x;
        (void) y;
        (void) width;
        (void) height;
        return false;
    }
    virtual bool set_native_child_view_bounds(void* child_view,
                                              float x,
                                              float y,
                                              float width,
                                              float height) {
        (void) child_view;
        (void) x;
        (void) y;
        (void) width;
        (void) height;
        return false;
    }
    virtual void detach_native_child_view(void* child_view) { (void) child_view; }
 
    // Clip an attached native child to `(x, y, width, height)` — the visible
    // sub-rectangle expressed in the child's OWN [0,0,frame_w,frame_h] box, in
    // Pulp's top-left origin convention (same units as
    // set_native_child_view_bounds). The host masks the native view to that rect
    // (e.g. a CALayer mask on Apple) so a child inside a scroll region does not
    // spill past the viewport; masking preserves the child's content size rather
    // than reflowing it by resizing the frame. When has_clip is false, any
    // existing clip is removed. Returns false when unsupported or when the child
    // is not attached to this host. Default: no-op unsupported.
    virtual bool set_native_child_view_clip(void* child_view,
                                            bool has_clip,
                                            float x,
                                            float y,
                                            float width,
                                            float height) {
        (void) child_view;
        (void) has_clip;
        (void) x;
        (void) y;
        (void) width;
        (void) height;
        return false;
    }
 
    // Capture the current visible content as a PNG image.
    //
    // Semantics: "whatever the compositor sees" — on macOS this prefers
    // `screencapture` and the content-view cache before falling back to a
    // direct GPU-backbuffer readback. Suitable for live screenshots of a
    // visible window.
    virtual std::vector<uint8_t> capture_png() { return {}; }
 
    // Capture the host's own back-buffer as a PNG image (issue #2001).
    //
    // Semantics: "host-managed pixels, deterministically." Implementations
    // MUST NOT call show()/makeKeyAndOrderFront/etc., and MUST bypass any
    // compositor-side capture path (`screencapture`, content-view caching).
    // For GPU-backed hosts, this reads the actual rendered back-buffer; for
    // non-GPU hosts, it can fall back to the rasterized content view.
    //
    // Default delegates to capture_png() so non-overriding hosts keep their
    // current behavior. Test harnesses (`test/mac_window_harness.{hpp,mm}`)
    // depend on the override existing on macOS GPU hosts so hidden-window
    // tests get reproducible bytes.
    virtual std::vector<uint8_t> capture_back_buffer_png() {
        return capture_png();
    }
 
    // Clear any cached host-side input targets before the view tree is rebuilt.
    virtual void invalidate_input_state() {}
 
    // Request the host to close and exit its event loop.
    virtual void request_close() {}
 
    // Called periodically while the host event loop is running.
    // Used for editor-side polling such as hot reload.
    virtual void set_idle_callback(std::function<void()> cb) { (void)cb; }
    virtual void set_resize_callback(ResizeCallback cb);
 
    // Install an APP-LEVEL key monitor: keyDown/keyUp events anywhere in the app
    // are forwarded to `handler` before the focused window's responder chain sees
    // them; return true to CONSUME (the event then doesn't reach any window). Use
    // it to route keyboard input to a popout window (e.g. a Musical Typing
    // keyboard) regardless of WHICH window is currently key — so typing keeps
    // working after the user clicks a control in another window. Pass `{}` to
    // remove. No-op on platforms without an app-global key hook.
    virtual void set_app_key_monitor(std::function<bool(const KeyEvent&)> handler) {
        (void)handler;
        note_unsupported_feature("set_app_key_monitor");
    }
 
    // Install a handler for files the OS asks this app to open: a double-click
    // in Finder, a drag onto the app icon or Dock tile, or `open -a`. Paths are
    // delivered on the main thread.
    //
    // Install it BEFORE run_event_loop(). A launch-time open arrives while the
    // app is still finishing launch — before the loop starts — so a handler set
    // afterwards would miss the very file that caused the launch. Any paths that
    // arrive before a handler exists are held and delivered as soon as one is
    // installed; passing `{}` removes the handler without discarding them.
    //
    // Declaring the document type is the other half of this: without a
    // CFBundleDocumentTypes entry (pulp_declare_standalone_document_type() in
    // CMake) the OS never routes the file here at all.
    virtual void set_open_files_handler(
        std::function<void(const std::vector<std::string>&)> handler) {
        (void)handler;
        note_unsupported_feature("set_open_files_handler");
    }
 
    // Set a callback for when the window is closed
    virtual void set_close_callback(std::function<void()> cb) = 0;
 
    // Run the event loop (blocks until the window is closed)
    // Call this for standalone UI preview mode
    virtual void run_event_loop() = 0;
 
    // ── D.1 Client-side window decoration ───────────────────────────────
    virtual void set_client_decoration(bool enabled) {
        (void)enabled;
        note_unsupported_feature("set_client_decoration");
    }

    enum class HitTestRegion {
        none, client, caption,
        resize_n, resize_s, resize_e, resize_w,
        resize_ne, resize_nw, resize_se, resize_sw,
        close, minimize, maximize
    };
 
    // ── D.2 Window features ─────────────────────────────────────────────
    virtual void set_fixed_aspect_ratio(float ratio) {
        (void)ratio;
        note_unsupported_feature("set_fixed_aspect_ratio");
    }

    virtual void set_always_on_top(bool on_top) {
        (void)on_top;
        note_unsupported_feature("set_always_on_top");
    }

    virtual void request_content_size(float w, float h) {
        (void)w; (void)h;
        note_unsupported_feature("request_content_size");
    }

    virtual void set_design_viewport(float design_w, float design_h) {
        (void)design_w; (void)design_h;
        note_unsupported_feature("set_design_viewport");
    }

    static bool compute_design_viewport_transform(
        float window_w, float window_h,
        float design_w, float design_h,
        float& sx, float& sy, float& tx, float& ty,
        bool top_align = false) {
        if (design_w <= 0.0f || design_h <= 0.0f ||
            window_w <= 0.0f || window_h <= 0.0f) {
            return false;
        }
        const float s = std::min(window_w / design_w, window_h / design_h);
        sx = s;
        sy = s;
        tx = (window_w - design_w * s) * 0.5f;
        ty = top_align ? 0.0f : (window_h - design_h * s) * 0.5f;
        return true;
    }

    static Point design_viewport_window_to_root(Point pt,
                                                float window_w, float window_h,
                                                float design_w, float design_h,
                                                bool top_align = false) {
        float sx, sy, tx, ty;
        if (!compute_design_viewport_transform(window_w, window_h,
                                               design_w, design_h,
                                               sx, sy, tx, ty, top_align)) {
            return pt;
        }
        if (sx <= 0.0f || sy <= 0.0f) return pt;
        return {(pt.x - tx) / sx, (pt.y - ty) / sy};
    }
 
    // Report the active design-viewport transform that maps ROOT (design-space)
    // coordinates to HOST (window-space) coordinates:
    //   x' = x*sx + tx,  y' = y*sy + ty,  w' = w*sx,  h' = h*sy
    // Returns true and fills the outputs when a design viewport is active;
    // returns false (identity — outputs untouched) when no viewport is set.
    //
    // Mirrors `PluginViewHost::design_viewport_transform`. `NativeViewHost`
    // uses it to place an embedded native child at the same letterbox-scaled
    // position as the surrounding Pulp widgets. Default: no viewport → false.
    // Only the GPU window host (which actually scales paint) overrides it; the
    // CPU window host does not implement a design viewport at all, so the
    // false default is correct there.
    virtual bool design_viewport_transform(float& sx, float& sy,
                                           float& tx, float& ty) const {
        (void)sx; (void)sy; (void)tx; (void)ty;
        return false;
    }
 
    // ── D.3 DPI / Monitor utilities ─────────────────────────────────────
    virtual float dpi_scale() const { return 1.0f; }

    virtual Size max_dimensions() const { return {1920, 1080}; }

    float convert_to_logical(float px) const { return px / dpi_scale(); }

    float convert_to_native(float logical) const { return logical * dpi_scale(); }

    struct MonitorInfo {
        Rect bounds;
        float dpi_scale = 1.0f;
        std::string name;
    };

    virtual std::vector<MonitorInfo> get_monitors() const {
        return {{{{0, 0, 1920, 1080}, 1.0f, "Default"}}};
    }
 
    // ── D.4 Mouse relative mode ─────────────────────────────────────────
    virtual void set_mouse_relative_mode(bool enabled) {
        (void)enabled;
        note_unsupported_feature("set_mouse_relative_mode");
    }
 
    // Keep new virtuals at the tail of the public vtable. WindowHost is an SDK
    // extension surface (set_factory accepts downstream subclasses), so
    // inserting a virtual among existing methods would shift every later slot.
    virtual bool is_gpu_backed() const { return gpu_surface() != nullptr; }

    virtual bool supports_deferred_close() const {
        return false;
    }

    virtual void request_close_deferred() {
        note_unsupported_feature("request_close_deferred");
    }

    virtual bool supports_compositor_capture() const { return false; }

    virtual bool event_loop_blocks_until_close() const { return true; }

    virtual bool event_loop_supports_exit_drain() const {
        return false;
    }

    virtual void run_event_loop_until(std::function<bool()> ready_to_return) {
        run_event_loop();
        if (ready_to_return)
            (void)ready_to_return();
    }

    virtual bool supports_back_buffer_capture() const { return false; }

    virtual bool supports_gpu_submission_evidence() const {
        return false;
    }

    virtual bool last_frame_gpu_submission_observed() const {
        return false;
    }

    virtual std::vector<double> frame_time_samples_ms() const { return {}; }

    virtual void log_gpu_diagnostics_summary() {}

    bool feature_marked_unsupported(const char* method) const {
        return unsupported_features_logged_.count(method) > 0;
    }
 
protected:
    void note_unsupported_feature(const char* method);
 
private:
    // Method names already logged by note_unsupported_feature(), so each
    // unsupported feature diagnoses exactly once per host instead of once per
    // call.
    std::set<std::string> unsupported_features_logged_;
 
    // Shared vblank-paced-or-direct repaint scheduling for mark_dirty() and
    // mark_dirty(Rect).
    void schedule_repaint();
 
    // Optional vblank-paced RenderLoop driven by mark_dirty().
    render::RenderLoop* render_loop_ = nullptr;
 
    // Accumulated dirty region for the pending frame (root/window coords).
    // The SAME abstraction the plug-in host uses (PluginViewHost::damage_) —
    // this used to be three hand-rolled fields plus a copy of the union logic,
    // which is how the two hosts drifted apart on what "damage" even means.
    PendingDamage damage_;
 
private:
    // ── Attached-view registry ──────────────────────────────────────────────
    //
    // See the equivalent block in PluginViewHost. A NativeViewHost holds a RAW,
    // non-owning pointer back here and dereferences it in its destructor; if the
    // host dies first, that is a use-after-free. Every built-in host nulls the
    // back-reference in its own destructor, but that is a per-subclass
    // convention, and `set_factory` is public API.
    //
    // The BASE destructor clears every still-attached view's pointer. It does
    // NOT call detach_native_child_view() — the derived object is already gone,
    // so that would dispatch to the base default and the real OS detach would
    // silently not happen. Derived destructors keep doing the OS detach through
    // their live vtable; this only makes the pointer invariant structural.
    friend class NativeViewHost;
    void register_native_view(NativeViewHost* view);
    void unregister_native_view(NativeViewHost* view);
 
    std::vector<NativeViewHost*> attached_native_views_;
};
 
} // namespace pulp::view