Surface
-
class Surface
Top-level rendering target.
A Surface owns a Canvas, a Device, and a Renderer. The typical frame cycle is: beginFrame() → draw via canvas() → endFrame() → flush().
Note
The caller must ensure the GL context is current when using a GPU-backed surface.
Public Functions
-
~Surface()
-
void beginFrame(Color clearColor = {0, 0, 0, 255})
Begin a new frame, clearing to the specified color.
- Parameters:
clearColor – The color to clear the render target to (default: opaque black).
-
inline Canvas *canvas() const
Get the Canvas used for drawing on this surface.
- Returns:
Pointer to the Canvas.
-
void endFrame()
End the current frame (finishes recording).
-
void flush()
Execute recorded commands and submit to the backend.
-
PixelData getPixelData() const
Get a non-owning pixel data descriptor for host integration.
- Returns:
A PixelData descriptor.
-
bool isGPU() const
Check if this is a GPU-backed surface.
- Returns:
True if GPU-backed.
-
std::shared_ptr<Image> makeSnapshot() const
Create an immutable snapshot of current surface contents.
- Returns:
Shared pointer to the snapshot Image.
-
Pixmap *peekPixels()
Direct pixel access (raster surfaces only).
- Returns:
Pointer to the underlying Pixmap, or nullptr for GPU/recording surfaces.
-
const Pixmap *peekPixels() const
Direct pixel access (raster surfaces only).
- Returns:
Pointer to the underlying Pixmap, or nullptr for GPU/recording surfaces.
-
void resize(i32 w, i32 h)
Resize the surface to new dimensions.
- Parameters:
w – New width in pixels.
h – New height in pixels.
-
void setGlyphCache(GlyphCache *cache)
Set the glyph cache used for text rendering.
- Parameters:
cache – Pointer to the glyph cache.
Public Static Functions
Create a GPU surface.
Falls back to CPU if context is null or invalid.
- Parameters:
context – Shared pointer to the GPU context.
w – Width in pixels.
h – Height in pixels.
fmt – Pixel format (default BGRA8888).
- Returns:
Unique pointer to the new Surface.
-
static std::unique_ptr<Surface> MakeRaster(i32 w, i32 h, PixelFormat fmt = PixelFormat::BGRA8888)
Create a CPU raster surface that allocates its own pixel buffer.
- Parameters:
w – Width in pixels.
h – Height in pixels.
fmt – Pixel format (default BGRA8888).
- Returns:
Unique pointer to the new Surface.
-
static std::unique_ptr<Surface> MakeRasterDirect(const PixmapInfo &info, void *pixels)
Create a CPU raster surface wrapping a caller-owned pixel buffer (zero-copy).
-
~Surface()