skp_capture.hpp

Go to the documentation of this file.

#pragma once
 
// skp_capture.hpp — Skia `.skp` (SkPicture) frame capture.
//
// The capture writes a rendered frame as a Skia `.skp` artifact that
// Skia's own `skiadebugger` can replay op-by-op. This is the bridge
// from "a frame looked weird in Pulp" to the best-in-class external
// frame-debugging tool — for free, because Skia ships the format.
//
// Design:
//
//   * `.skp` is the legacy `SkPicture` serialization format. It is
//     fully backend-independent — an `SkPictureRecorder` records draw
//     ops into a backend-agnostic `SkRecord`, and nothing in the
//     Graphite headers references `SkPicture`. So a capture works
//     regardless of which GPU backend (Graphite/Dawn) the process runs
//     and even with no live GPU context at all. We do NOT serialize a
//     `skgpu::graphite::Recording` (that is the GPU command bundle, not
//     a `.skp`).
//
//   * Capture re-runs the frame's draw ops into a fresh recording
//     canvas. `SkpFrameCapture` owns an `SkPictureRecorder` and exposes
//     a `pulp::canvas::Canvas` over its recording `SkCanvas`, so
//     existing view-paint code paints into the capture exactly as it
//     paints a live frame. Capture is a user-triggered action, never a
//     per-frame cost.
//
//   * The one caveat the spike pinned: `SkPicture::serialize()` drops
//     embedded `SkImage`s to `nullptr` by default. `SkpFrameCapture`
//     always supplies `SkSerialProcs::fImageProc` (PNG-encode) so
//     atlas/image draws survive the round trip. A replayer (skiadebugger,
//     or a test) reads the artifact with the matching
//     `SkDeserialProcs::fImageProc` that decodes the PNG payload back to
//     an `SkImage`.
//
//   * GPU-texture-backed embedded images. A raster `SkImage` PNG-encodes
//     with no GPU context. A texture-backed image (atlas / surface
//     snapshot) cannot — Skia's PNG encoder needs the owning context to
//     read the pixels off the GPU first. Pulp renders on Graphite, whose
//     pixel readback is `skgpu::graphite::Context::asyncRescaleAndReadPixels`.
//     So a capture that may embed GPU images must be handed the Graphite
//     `Context` (see `capture_skp_to_file` / `SkpFrameCapture` ctor): the
//     image proc then rasterizes texture-backed images before encoding.
//     If a texture-backed image is met with no `Context`, the proc fails
//     loudly (logged) rather than silently dropping the image.
//
// Graceful degradation: when Skia is not compiled in, `SkpFrameCapture`
// reports `available() == false`, `canvas()` returns `nullptr`, and the
// capture functions return a failed `SkpCaptureResult` with a reason
// string — no crash, no partial file.
 
#include <pulp/canvas/canvas.hpp>
 
#include <cstddef>
#include <functional>
#include <memory>
#include <string>
 
namespace skgpu::graphite {
class Context;
}
 
namespace pulp::render {

struct SkpCaptureResult {
    bool ok = false;             
    std::string path;            
    std::size_t bytes_written = 0; 
    std::size_t op_count = 0;    
    std::string reason;          
 
    explicit operator bool() const { return ok; }
};

class SkpFrameCapture {
public:
    explicit SkpFrameCapture(int width, int height,
                             skgpu::graphite::Context* graphite_context = nullptr);
    ~SkpFrameCapture();
 
    SkpFrameCapture(const SkpFrameCapture&) = delete;
    SkpFrameCapture& operator=(const SkpFrameCapture&) = delete;

    bool available() const;

    canvas::Canvas* canvas();

    SkpCaptureResult finish_to_file(const std::string& path);

    SkpCaptureResult finish_to_memory(std::string& out_blob);
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

SkpCaptureResult capture_skp_to_file(
    int width, int height, const std::string& path,
    const std::function<void(canvas::Canvas&)>& paint,
    skgpu::graphite::Context* graphite_context = nullptr);

bool skp_capture_supported();

SkpCaptureResult maybe_capture_skp_from_env(
    int width, int height,
    const std::function<void(canvas::Canvas&)>& paint,
    skgpu::graphite::Context* graphite_context = nullptr);
 
} // namespace pulp::render