screenshot.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/canvas/text_raster_policy.hpp>
#include <pulp/view/view.hpp>
#include <string>
#include <vector>
#include <cstdint>
#include <functional>
 
namespace pulp::view {
 
enum class ScreenshotBackend {
    default_backend,  
    coregraphics,     
    skia,             
    gpu,              
    auto_select,      
};
 
// Render a view tree to a PNG image buffer (headless, no window needed).
//
// Platform support:
//   - macOS: native CoreGraphics-backed capture.
//   - iOS: provider-backed fallback only; no native capture backend yet.
//   - Windows/Linux: built-in Skia raster backend when Skia is available.
//   - Android or builds without a native backend: the host app registers a
//     provider via set_screenshot_provider(). Without one, returns empty
//     vector / false explicitly.
//
// Callers can probe has_screenshot_provider() to distinguish
// "no backend installed" from "render failed".
//
// `text_raster` is the glyph preblend of the Skia surfaces the render creates
// (skia and gpu backends; see pulp/canvas/text_raster_policy.hpp). An imported
// panel passes select_text_raster_policy() over its captured text so the
// capture renders the way its live surface does. The CoreGraphics backend and
// a host-registered provider ignore it.
std::vector<uint8_t>
render_to_png(View& root, uint32_t width, uint32_t height,
              float scale = 2.0f, // Retina scale factor
              ScreenshotBackend backend = ScreenshotBackend::default_backend,
              canvas::TextRasterPolicy text_raster = canvas::TextRasterPolicy::legacy);
 
// Render a view tree to a PNG file
bool render_to_file(View& root, uint32_t width, uint32_t height, const std::string& output_path,
                    float scale = 2.0f,
                    ScreenshotBackend backend = ScreenshotBackend::default_backend,
                    canvas::TextRasterPolicy text_raster = canvas::TextRasterPolicy::legacy);
 
// ── Smart, always-honest capture (the "always-capturable" must-have) ─────
//
// One entry point so agents/CI don't pick the wrong backend. capture_view()
// inspects the view tree and does the right thing, and NEVER returns a silent
// blank:
//   1. A subtree marked `contains_native_overlay()` (a WebView / native NSView
//      composited by the OS, not painted into the Pulp canvas) → ok=false with a
//      reason; such overlays are invisible to headless capture (use a real
//      window / OS screencapture).
//   2. `requires_gpu_host()` anywhere in the tree → the `gpu` backend
//      (HeadlessSurface, Dawn+Skia) which renders GPU content correctly.
//   3. Otherwise → CPU raster (`skia` / platform default).
// The captured PNG is gated by the content floor (analyze_screenshot_content):
// a blank / clear-only frame sets ok=false with a reason. `png` may still be
// populated when !ok so callers can save it for debugging.
struct CaptureRequirements {
    View* native_overlay = nullptr;  
    bool requires_gpu = false;       
};

CaptureRequirements inspect_capture_requirements(View& root);
 
struct CaptureResult {
    std::vector<uint8_t> png;
    bool ok = false;
    ScreenshotBackend used = ScreenshotBackend::default_backend;
    std::string reason;  
};
 
CaptureResult capture_view(
    View& root,
    uint32_t width,
    uint32_t height,
    float scale = 2.0f,
    ScreenshotBackend backend = ScreenshotBackend::auto_select  // smart by default
);
 
// Render a view tree through the offscreen GPU surface (Dawn + Skia via
// pulp::render::HeadlessSurface). Returns empty bytes if this build has no GPU
// backend (PULP_HAS_SKIA off / no pulp-render). Unlike the raster backends,
// this renders `requires_gpu_host()` views correctly.
std::vector<uint8_t>
render_to_png_gpu(View& root, uint32_t width, uint32_t height, float scale = 2.0f,
                  canvas::TextRasterPolicy text_raster = canvas::TextRasterPolicy::legacy);
 
// True when render_to_png_gpu can produce frames in this build (GPU backend
// compiled in). Lets capture_view fall back honestly when GPU is unavailable.
bool has_gpu_capture();
 
// True when capture_view() has an in-process producer available in this build:
// a platform-native raster backend, portable Skia/GPU capture, or a registered
// ScreenshotProvider whose output this build can decode for the mandatory
// blank/content floor. This is a capability probe only; an individual capture
// can still fail (for example, an unavailable GPU device or a blank frame).
bool has_screenshot_backend();

bool has_screenshot_decoder();

bool passes_capture_content_floor(const std::vector<uint8_t>& png);
 
// Raw-RGBA sibling of render_to_png: render a view tree headlessly and hand
// back the decoded pixel buffer instead of PNG bytes — for callers that want
// to composite or upload the frame themselves (e.g. a foreign host that draws
// Pulp's output into its own surface) without paying a PNG encode + decode
// round-trip. The internal Skia raster path already holds these pixels before
// encoding, so this exposes them directly.
//
// Output: tightly packed RGBA8 (R,G,B,A byte order), premultiplied alpha,
// sRGB, top-to-bottom rows, stride == out_width * 4. The pixel dimensions are
// the logical width/height multiplied by `scale`, returned via out_width /
// out_height so the caller can size its buffer exactly. Returns an empty
// vector on failure (no Skia backend, surface alloc failed, read-back failed).
//
// Backend: forces the Skia raster path when available (the only backend that
// produces a stable, host-independent RGBA buffer). Without Skia this returns
// empty (CoreGraphics capture is PNG-only here).
std::vector<uint8_t>
render_to_rgba(View& root, uint32_t width, uint32_t height, float scale, uint32_t* out_width,
               uint32_t* out_height,
               canvas::TextRasterPolicy text_raster = canvas::TextRasterPolicy::legacy);
 
// Whether this BUILD has a raw-RGBA producer at all — a property of which
// backend was compiled in, not of any particular render.
//
// A pixel test needs to tell two situations apart that look identical from the
// outside: a build with no raster backend, where every probe returns an empty
// buffer no matter what the code under test does, and a build that can
// rasterize but produced nothing, which is a real defect. Deciding from an
// empty result cannot separate them, and skipping on an empty result would
// turn a genuine rasterizer regression into a silently green run.
//
// So the question is asked of the build, and a test may skip only when the
// answer is false. When it is true, an empty buffer stays a failure.
bool raw_rgba_render_available();
 
// ── Host-registered screenshot provider (#299) ──────────────────────────
//
// Non-Apple platforms don't have a built-in screenshot backend in
// core/view. A host app (or future platform module) installs a
// provider here — e.g., a Skia-backed raster renderer on Linux/
// Windows — and render_to_png/file will delegate to it. Apple
// platforms' native impls ignore the provider.
 
using ScreenshotProvider = std::function<std::vector<uint8_t>(
    View& root,
    uint32_t width,
    uint32_t height,
    float scale,
    ScreenshotBackend backend)>;
 
void set_screenshot_provider(ScreenshotProvider provider);
void clear_screenshot_provider();
bool has_screenshot_provider();
 
} // namespace pulp::view