pulp::render::GpuSurface Class Reference

Abstract GPU surface — a presentable rendering target backed by a native window/view. More...

#include <gpu_surface.hpp>

Classes
struct	AdapterInfo
struct	Config
struct	X11NativeHandle
	Typed X11 surface handle. More...
struct	StartupTimings
	Wall-clock milliseconds spent in each stage of initialize(), measured with a monotonic clock. More...
struct	SwapchainStats
	Swapchain configurations issued since initialize(), the first one included, their total wall-clock milliseconds, and whether the size has settled. More...

Public Types
enum class	AdapterType { unknown , integrated_gpu , discrete_gpu , cpu }
	Native adapter type reported by Dawn/WebGPU. More...
enum class	AdapterBackendPreference { default_backend , null_backend , vulkan , d3d12 }

Public Member Functions
virtual	~GpuSurface ()=default
virtual bool	initialize (const Config &config)=0
virtual void	resize (uint32_t width, uint32_t height)=0
	Record a new size.
virtual bool	begin_frame ()=0
	Acquire the current presentable texture, first configuring the swapchain if the size changed since the last frame.
virtual void	end_frame ()=0
	Present to native surface (or just process events if offscreen).
virtual bool	is_initialized () const =0
virtual bool	has_surface () const =0
virtual uint32_t	width () const =0
virtual uint32_t	height () const =0
virtual void *	dawn_device_handle () const =0
	Opaque accessors for the Dawn device/queue/texture.
virtual void *	dawn_queue_handle () const =0
virtual void *	dawn_instance_handle () const =0
virtual void *	current_texture_handle () const =0
	The current presentable texture, valid only between begin_frame/end_frame.
virtual AdapterInfo	adapter_info () const =0
	Snapshot describing the current adapter/device state for higher-level bridges.
virtual StartupTimings	startup_timings () const
	Stage timings recorded by the most recent initialize() call.
virtual SwapchainStats	swapchain_stats () const
	Kept at the vtable tail for the same reason as startup_timings().

Static Public Member Functions
static std::unique_ptr< GpuSurface >	create_dawn ()

Detailed Description

Abstract GPU surface — a presentable rendering target backed by a native window/view.

Ownership model:

• Platform code creates native views/layers and passes handles here
• GpuSurface owns the Dawn instance, adapter, device, queue, and surface
• SkiaSurface receives the device/queue from GpuSurface (single device)
• begin_frame()/end_frame() bracket each rendered frame with acquire/present

Frame lifecycle: gpu.begin_frame() → acquires current presentable texture skia.begin_frame() → wraps that texture as Graphite render target ... draw ... skia.end_frame() → submits Graphite recording to the shared device/queue gpu.end_frame() → presents to native surface

Member Enumeration Documentation

AdapterBackendPreference

enum class pulp::render::GpuSurface::AdapterBackendPreference

strong

Enumerator
default_backend
null_backend
vulkan	Use the Vulkan backend without Dawn's fallback-adapter hint. This lets a hosted Linux lane select its configured software ICD (lavapipe) and is intentionally separate from force_fallback_adapter.
d3d12	Use the D3D12 backend without Dawn's fallback-adapter hint. On a hosted Windows runner this resolves to the WARP adapter.

AdapterType

enum class pulp::render::GpuSurface::AdapterType

strong

Native adapter type reported by Dawn/WebGPU.

This is independent of the backend API: Metal, D3D12, or Vulkan can each expose hardware, fallback, or CPU adapters.

Enumerator
unknown
integrated_gpu
discrete_gpu
cpu

Constructor & Destructor Documentation

~GpuSurface()

virtual pulp::render::GpuSurface::~GpuSurface ( )

virtualdefault

Member Function Documentation

adapter_info()

virtual AdapterInfo pulp::render::GpuSurface::adapter_info ( ) const

pure virtual

Snapshot describing the current adapter/device state for higher-level bridges.

Returns an unavailable record when no native adapter has been initialized.

begin_frame()

virtual bool pulp::render::GpuSurface::begin_frame ( )

pure virtual

Acquire the current presentable texture, first configuring the swapchain if the size changed since the last frame.

Returns false if not ready, including while either dimension is zero.

create_dawn()

std::unique_ptr< GpuSurface > pulp::render::GpuSurface::create_dawn ( )

static

current_texture_handle()

virtual void * pulp::render::GpuSurface::current_texture_handle ( ) const

pure virtual

The current presentable texture, valid only between begin_frame/end_frame.

Returns nullptr in offscreen mode or if begin_frame wasn't called.

dawn_device_handle()

virtual void * pulp::render::GpuSurface::dawn_device_handle ( ) const

pure virtual

Opaque accessors for the Dawn device/queue/texture.

SkiaSurface (in the same module) interprets these as Dawn C++ types. Returns nullptr if not initialized.

dawn_instance_handle()

virtual void * pulp::render::GpuSurface::dawn_instance_handle ( ) const

pure virtual

dawn_queue_handle()

virtual void * pulp::render::GpuSurface::dawn_queue_handle ( ) const

pure virtual

end_frame()

virtual void pulp::render::GpuSurface::end_frame ( )

pure virtual

Present to native surface (or just process events if offscreen).

has_surface()

virtual bool pulp::render::GpuSurface::has_surface ( ) const

pure virtual

height()

virtual uint32_t pulp::render::GpuSurface::height ( ) const

pure virtual

initialize()

virtual bool pulp::render::GpuSurface::initialize ( const Config & config )

pure virtual

is_initialized()

virtual bool pulp::render::GpuSurface::is_initialized ( ) const

pure virtual

resize()

virtual void pulp::render::GpuSurface::resize ( uint32_t width, uint32_t height )

pure virtual

Record a new size.

width()/height() report it at once, but a presentable surface reconfigures its swapchain only in the next begin_frame(), so several resizes before one frame configure once.

startup_timings()

virtual StartupTimings pulp::render::GpuSurface::startup_timings ( ) const

inlinevirtual

Stage timings recorded by the most recent initialize() call.

The base implementation reports nothing measured. Kept at the vtable tail so existing GpuSurface subclasses keep their slot layout.

swapchain_stats()

virtual SwapchainStats pulp::render::GpuSurface::swapchain_stats ( ) const

inlinevirtual

Kept at the vtable tail for the same reason as startup_timings().

width()

virtual uint32_t pulp::render::GpuSurface::width ( ) const

pure virtual

---

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

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