pulp::render::HeadlessSurface Class Reference

One-call wrapper for the existing offscreen Dawn + Skia path (GpuSurface::create_dawn() + native_surface_handle=nullptr + SkiaSurface::create). More...

#include <headless_surface.hpp>

Classes
struct	Config
struct	Rgba

Public Types
using	PaintFn = std::function<void(canvas::Canvas&)>
	Caller-supplied paint callback.

Public Member Functions
virtual	~HeadlessSurface ()=default
virtual bool	is_ready () const =0
	True when the underlying GpuSurface + SkiaSurface are live and ready to accept paint callbacks.
virtual Rgba	render_rgba (const PaintFn &paint)=0
	Run one offscreen frame: begin_frame → fill → user paint → read pixels → end_frame.
virtual std::vector< uint8_t >	render_png (const PaintFn &paint)=0
	Convenience: render and PNG-encode in one call.
virtual std::string	last_error () const =0
	Last error message recorded by the wrapper. Empty when no error.

Static Public Member Functions
static std::unique_ptr< HeadlessSurface >	create (const Config &config, std::string *last_error_out=nullptr)
	Create a headless offscreen surface, or nullptr if Skia/Dawn aren't available or the underlying GpuSurface/SkiaSurface initialization failed.
static std::vector< uint8_t >	encode_png (const Rgba &rgba, std::string *error_out=nullptr)
	PNG-encode an already-captured RGBA buffer.
static uint64_t	rgba_fingerprint (const Rgba &rgba)
	Cheap deterministic fingerprint of an RGBA buffer — FNV-1a 64.

Detailed Description

One-call wrapper for the existing offscreen Dawn + Skia path (GpuSurface::create_dawn() + native_surface_handle=nullptr + SkiaSurface::create).

Intended for CI golden tests and any other callsite that wants "render this scene to an RGBA / PNG buffer with no window".

The wrapper does NOT introduce a new render path — it just hides the begin_frame/end_frame ceremony and the GPU readback dance so a test can do:

auto h = HeadlessSurface::create({640, 360}); if (!h || !h->is_ready()) { SUCCEED("Dawn/Graphite unavailable — golden skipped."); return; } auto rgba = h->render_rgba([&](canvas::Canvas& c) { paint_my_scene(c); }); auto png = HeadlessSurface::encode_png(rgba);

When Skia/Dawn isn't linked (the PULP_HAS_SKIA=0 build), the factory returns nullptr and last_error() carries the reason so the caller can soft-skip. The header is always safe to include — no Skia/Dawn types leak into it.

Member Typedef Documentation

PaintFn

using pulp::render::HeadlessSurface::PaintFn = std::function<void(canvas::Canvas&)>

Caller-supplied paint callback.

The Canvas is the live Skia canvas for the current offscreen frame. The wrapper applies the background fill BEFORE invoking this callback.

Constructor & Destructor Documentation

~HeadlessSurface()

virtual pulp::render::HeadlessSurface::~HeadlessSurface ( )

virtualdefault

Member Function Documentation

create()

std::unique_ptr< HeadlessSurface > pulp::render::HeadlessSurface::create ( const Config & config, std::string * last_error_out = nullptr )

static

Create a headless offscreen surface, or nullptr if Skia/Dawn aren't available or the underlying GpuSurface/SkiaSurface initialization failed.

last_error_out (if non-null) is filled with a human-readable reason in the failure case.

encode_png()

std::vector< uint8_t > pulp::render::HeadlessSurface::encode_png ( const Rgba & rgba, std::string * error_out = nullptr )

static

PNG-encode an already-captured RGBA buffer.

Returns empty on failure. Available even on builds where the runtime surface itself isn't (e.g. host-side post-processing of a fixture snapshot). When PULP_HAS_SKIA is off the implementation returns empty bytes and records a reason in error_out.

is_ready()

virtual bool pulp::render::HeadlessSurface::is_ready ( ) const

pure virtual

True when the underlying GpuSurface + SkiaSurface are live and ready to accept paint callbacks.

False after a failed init or when the device was lost.

last_error()

virtual std::string pulp::render::HeadlessSurface::last_error ( ) const

pure virtual

Last error message recorded by the wrapper. Empty when no error.

render_png()

virtual std::vector< uint8_t > pulp::render::HeadlessSurface::render_png ( const PaintFn & paint )

pure virtual

Convenience: render and PNG-encode in one call.

Returns empty bytes on failure (same semantics as render_rgba).

render_rgba()

virtual Rgba pulp::render::HeadlessSurface::render_rgba ( const PaintFn & paint )

pure virtual

Run one offscreen frame: begin_frame → fill → user paint → read pixels → end_frame.

Returns an empty Rgba on failure (callers should soft-skip when is_ready() was true but readback failed — the GPU adapter may be too constrained for readback).

rgba_fingerprint()

uint64_t pulp::render::HeadlessSurface::rgba_fingerprint ( const Rgba & rgba )

static

Cheap deterministic fingerprint of an RGBA buffer — FNV-1a 64.

Useful for golden-bytes assertions where storing the full PNG in-tree is overkill but the test still wants drift detection. Independent of Skia, always available.

---

The documentation for this class was generated from the following file:

• /home/runner/work/pulp/pulp/core/render/include/pulp/render/headless_surface.hpp