Hosts a render surface and manages rendering of a scene to a backbuffer of the specified type. Provides coordination between the scene, views, and the underlying UI adapter for efficient rendering and presentation. More...

Inheritance diagram for Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >:

Public Member Functions
RenderSurfaceHost()	RenderSurfaceHost (RenderSurfaceAdapterBase renderSurfaceAdapter)
	Initializes a new instance of the RenderSurfaceHost<TBackbuffer> class with the specified render surface adapter.
void	Bind (Scene newScene, bool limitCameraToWorldBoundPx=true)
	Binds a scene to this render surface host, replacing any previously bound scene.
Public Member Functions inherited from Gondwana.Rendering.RenderSurfaceHostBase
SKImage?	GlRenderAndSnapshot ()
	Renders the current scene frame on the active GL/WebGL thread and returns a snapshot of the GPU backbuffer ready to be drawn to the platform surface.
bool	GlRenderToCanvas (SKCanvas destinationCanvas)
	Renders the current scene frame and draws the GPU backbuffer surface directly to another GPU canvas. Linear scaling uses a scoped GPU texture snapshot because direct surface drawing does not support sampling options. No CPU pixel transfer is performed.
bool	GlDrawCurrentFrameToCanvas (SKCanvas destinationCanvas)
	Draws the existing GPU backbuffer surface directly to another GPU canvas without rendering a new scene frame. Linear scaling uses a scoped GPU texture snapshot without CPU pixel transfer.
SKImage?	GlSnapshotCurrentFrame ()
	Returns a snapshot of the current GPU backbuffer without rendering a new scene frame.
void	Dispose ()
	Releases all resources used by this RenderSurfaceHostBase instance.

Protected Member Functions

override void Dispose (bool disposing)

Releases resources used by this RenderSurfaceHostBase instance and unregisters it from the RenderSurfaceHostRegistry.

Parameters

disposing true to release both managed and unmanaged resources; false to release only unmanaged resources (called from finalizer).

This method always unregisters the instance from the registry. Derived classes should override this method to release additional resources but must call the base implementation to ensure proper unregistration.

Protected Member Functions inherited from Gondwana.Rendering.RenderSurfaceHostBase

RenderSurfaceHostBase ()

Initializes a new instance of the RenderSurfaceHostBase class and registers it with the RenderSurfaceHostRegistry.

Properties
override BackbufferBase	Backbuffer `[get]`
	Gets the backbuffer used for off-screen rendering before presentation to the adapter.
override Scene	Scene `[get]`
	Gets the scene currently bound to this render surface host.
override RenderSurfaceAdapterBase	RenderSurfaceAdapter `[get]`
	Gets the platform-specific adapter that provides the underlying rendering surface.
override ViewManager	ViewManager `[get]`
	Gets the view manager that controls camera positions, viewports, and multi-view rendering.
bool	RedrawDirtyRectangleOnly = true `[get, set]`
	Gets or sets a value indicating whether only the dirty (changed) regions of the backbuffer are presented to the adapter each frame.
Properties inherited from Gondwana.Rendering.RenderSurfaceHostBase
Diagnostics.? TelemetrySource	Telemetry `[get, set]`
	Neutral session-local measurements for this host; null when source capacity is exhausted or the shared collector is disposed.
BackbufferBase	Backbuffer `[get]`
	Gets the in-memory BackbufferBase associated with the current rendering context.
float	PresentationScale `[get]`
	Actual scale used to fit this Backbuffer into its current adapter.
Scene	Scene `[get]`
	Gets the source Scenes.Scene used for rendering operations.
RenderSurfaceAdapterBase?	RenderSurfaceAdapter `[get]`
	Gets the platform-specific RenderSurfaceAdapterBase responsible for rendering the image from the Backbuffer.
ViewManager	ViewManager `[get]`
	Gets the view manager that controls camera positions, viewports, and multi-view rendering for this render surface host.
EffectsManager	Effects `[get]`
	Gets the manager that owns presentation effects for this render surface.

Events
EventHandler< RenderSurfaceHostBindEventArgs >?	BindToScene
	Occurs when a scene is bound to or unbound from this render surface host.
Action?	RenderBackbufferBegin
	Occurs at the beginning of the backbuffer rendering process.
Action?	RenderBackbufferEnd
	Occurs at the end of the backbuffer rendering process.
Action?	RenderBackbufferNoOp
	Occurs when a backbuffer render operation is skipped because the scene is not dirty.
Action< GpuRenderFrameDiagnostics >?	GpuRenderFrameDiagnosticsCalculated
	Occurs after a full-frame GPU render when at least one subscriber has requested diagnostics.
Action< SKCanvas >?	RenderBackbufferPostScene
	Occurs after all scene content (layers, sprites, and direct drawings) has been drawn to the backbuffer canvas for the current frame, but before the frame is finalised and presented to the display adapter.
Events inherited from Gondwana.Rendering.RenderSurfaceHostBase
Action< GpuRenderSynchronizationDiagnostics >?	GpuRenderSynchronizationDiagnosticsCalculated
	Occurs after a GPU render/snapshot call when a subscriber requests timing for the shared render-state synchronization gate.

Detailed Description

Hosts a render surface and manages rendering of a scene to a backbuffer of the specified type. Provides coordination between the scene, views, and the underlying UI adapter for efficient rendering and presentation.

RenderSurfaceHost<TBackbuffer> is responsible for managing the lifecycle of the backbuffer, handling scene binding, and coordinating redraws based on scene and view changes. It supports partial or full redraws depending on the state of the scene and the RedrawDirtyRectangleOnly property. Thread safety is not guaranteed; all interactions should occur on the UI thread associated with the render surface adapter.

Template Parameters

TBackbuffer The type of backbuffer used for rendering. Must inherit from BackbufferBase.

Type Constraints

TBackbuffer

:

BackbufferBase

Definition at line 30 of file RenderSurfaceHost.cs.

Member Function Documentation

◆ Bind()

void Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.Bind	(	Scene	newScene,
		bool	limitCameraToWorldBoundPx = true )

Binds a scene to this render surface host, replacing any previously bound scene.

Parameters

newScene	The scene to bind. Must not be `null`.
limitCameraToWorldBoundPx	`true` to constrain all view cameras to the scene's world bounds; `false` to allow cameras to move freely beyond the scene boundaries.

Exceptions

ArgumentNullException	Thrown when newScene is `null`.
InvalidOperationException	Thrown when newScene is already bound to a different render surface host.

Binding a scene unregisters event handlers from the previous scene (if any), registers handlers with the new scene, and triggers a full refresh on the next frame. The BindToScene event fires after the binding operation completes.

If the specified scene is already bound, this method returns immediately without performing any operations.

Definition at line 259 of file RenderSurfaceHost.cs.

◆ Dispose()

override void Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.Dispose ( bool disposing )

protectedvirtual

Releases resources used by this RenderSurfaceHostBase instance and unregisters it from the RenderSurfaceHostRegistry.

Parameters

disposing true to release both managed and unmanaged resources; false to release only unmanaged resources (called from finalizer).

This method always unregisters the instance from the registry. Derived classes should override this method to release additional resources but must call the base implementation to ensure proper unregistration.

Reimplemented from Gondwana.Rendering.RenderSurfaceHostBase.

Definition at line 1070 of file RenderSurfaceHost.cs.

◆ RenderSurfaceHost()

RenderSurfaceHost() Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderSurfaceHost ( RenderSurfaceAdapterBase renderSurfaceAdapter )

Initializes a new instance of the RenderSurfaceHost<TBackbuffer> class with the specified render surface adapter.

Parameters

renderSurfaceAdapter The platform-specific adapter that provides the underlying rendering surface.

Exceptions

ArgumentNullException	Thrown if renderSurfaceAdapter is `null`.
InvalidOperationException	Thrown if the adapter has non-positive dimensions.

Definition at line 122 of file RenderSurfaceHost.cs.

Property Documentation

◆ Backbuffer

override BackbufferBase Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.Backbuffer

get

Gets the backbuffer used for off-screen rendering before presentation to the adapter.

The BackbufferBase instance managing the render target canvas and dirty-rectangle tracking.

The backbuffer holds the rendered frame content and tracks which regions have changed since the last presentation. All rendering operations are performed on the backbuffer's canvas before being copied to the UI adapter during presentation.

Definition at line 181 of file RenderSurfaceHost.cs.

◆ RedrawDirtyRectangleOnly

bool Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RedrawDirtyRectangleOnly = true

getset

Gets or sets a value indicating whether only the dirty (changed) regions of the backbuffer are presented to the adapter each frame.

true to present only dirty regions (default); false to present the entire backbuffer every frame.

Enabling dirty-rectangle-only presentation improves performance by reducing the amount of data transferred to the UI adapter. Disable this when troubleshooting rendering issues or when the adapter does not support partial updates.

Definition at line 234 of file RenderSurfaceHost.cs.

◆ RenderSurfaceAdapter

override RenderSurfaceAdapterBase Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderSurfaceAdapter

get

Gets the platform-specific adapter that provides the underlying rendering surface.

The RenderSurfaceAdapterBase instance representing the UI control or window where rendered content is displayed.

The adapter handles platform-specific presentation details and provides size/resize notifications. The Backbuffer retains its logical dimensions across adapter resizes.

Definition at line 206 of file RenderSurfaceHost.cs.

◆ Scene

override Scene Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.Scene

get

Gets the scene currently bound to this render surface host.

The Scene instance being rendered, or Scene.Empty if no scene is bound.

The scene contains all layers, sprites, and direct drawings that are rendered each frame. Use Bind to change the active scene.

Definition at line 193 of file RenderSurfaceHost.cs.

◆ ViewManager

override ViewManager Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.ViewManager

get

Gets the view manager that controls camera positions, viewports, and multi-view rendering.

The ViewManager instance managing all views associated with this render surface host.

Use the view manager to create, configure, and remove views. Each view defines a viewport rectangle on the backbuffer, a camera position in the scene, and zoom/parallax settings. Views enable split-screen, picture-in-picture, and minimap rendering.

Definition at line 219 of file RenderSurfaceHost.cs.

Event Documentation

◆ BindToScene

EventHandler<RenderSurfaceHostBindEventArgs>? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.BindToScene

Occurs when a scene is bound to or unbound from this render surface host.

This event fires after the scene binding operation completes. Event handlers receive information about the previously bound scene (if any) and the newly bound scene. Use this event to respond to scene changes, such as updating UI elements or resetting state that depends on the active scene.

Definition at line 54 of file RenderSurfaceHost.cs.

◆ GpuRenderFrameDiagnosticsCalculated

Action<GpuRenderFrameDiagnostics>? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.GpuRenderFrameDiagnosticsCalculated

Occurs after a full-frame GPU render when at least one subscriber has requested diagnostics.

Definition at line 74 of file RenderSurfaceHost.cs.

◆ RenderBackbufferBegin

Action? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderBackbufferBegin

Occurs at the beginning of the backbuffer rendering process.

Definition at line 59 of file RenderSurfaceHost.cs.

◆ RenderBackbufferEnd

Action? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderBackbufferEnd

Occurs at the end of the backbuffer rendering process.

Definition at line 64 of file RenderSurfaceHost.cs.

◆ RenderBackbufferNoOp

Action? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderBackbufferNoOp

Occurs when a backbuffer render operation is skipped because the scene is not dirty.

Definition at line 69 of file RenderSurfaceHost.cs.

◆ RenderBackbufferPostScene

Action<SKCanvas>? Gondwana.Rendering.RenderSurfaceHost< TBackbuffer >.RenderBackbufferPostScene

Occurs after all scene content (layers, sprites, and direct drawings) has been drawn to the backbuffer canvas for the current frame, but before the frame is finalised and presented to the display adapter.

Subscribe to this event to draw post-scene overlays or visual effects — such as color-grading filters, vignettes, bloom composites, or debug annotations — directly onto the fully-rendered canvas. The canvas matrix is reset to identity and the clip covers the full surface at the point this event fires. Save and restore canvas state around any operations that modify the matrix or clip region.

This is the per-surface game-instance hook. If you need the same capability from an engine-wide plugin, implement IEnginePlugin.OnPostRenderCanvas instead.

Threading:

CPU/bitmap surfaces — raised on the engine background thread.
Desktop GPU surfaces — raised on the Engine thread with a recording canvas. Use the supplied canvas and CPU resources; no GRContext is current and canvas.Surface is unavailable. Browser WebGL retains its synchronous GL callback behavior.

This event is not raised when a frame is skipped (scene not dirty) or when the surface has no configured views.

Definition at line 112 of file RenderSurfaceHost.cs.

Public Member Functions

Protected Member Functions

Properties

Events

Detailed Description

Member Function Documentation

◆ Bind()

◆ Dispose()

◆ RenderSurfaceHost()

Property Documentation

◆ Backbuffer

◆ RedrawDirtyRectangleOnly

◆ RenderSurfaceAdapter

◆ Scene

◆ ViewManager

Event Documentation

◆ BindToScene

◆ GpuRenderFrameDiagnosticsCalculated

◆ RenderBackbufferBegin

◆ RenderBackbufferEnd

◆ RenderBackbufferNoOp

◆ RenderBackbufferPostScene