Gondwana.Widgets.Hud.ProfilerWidget Class Reference

Displays detached RuntimeProfiler snapshots as a screen-space HUD widget. More...

Inheritance diagram for Gondwana.Widgets.Hud.ProfilerWidget:

Public Member Functions
	ProfilerWidget (RenderSurfaceHostBase renderSurfaceHost, View view, Rectangle bounds, string? nickname=null)
	Creates a view-level runtime-profiler widget.
ProfilerWidget	SetSourceVisible (string sourceName, bool visible)
	Sets whether all measurements from a named profiler source are displayed.
ProfilerWidget	SetMeasurementVisible (string metricKey, bool visible)
	Sets a visibility override for a metric key across all profiler sources.
ProfilerWidget	SetMeasurementVisible (string sourceName, string metricKey, bool visible)
	Sets a visibility override for one metric on one named profiler source.
ProfilerWidget	ClearVisibilityOverrides ()
	Removes all explicit source and measurement visibility overrides.
ProfilerWidget	SetMeasurementDescription (string metricKey, string? description)
	Defines or replaces hover help for a measurement key.
bool	IsMeasurementVisible (string sourceName, string metricKey)
	Returns whether a metric would be displayed under the current source/metric visibility rules.
ProfilerWidget	SetColors (SKColor foreground, SKColor background)
	Sets profiler text and background colors.
ProfilerWidget	SetFont (SKTypeface typeface, float size, float? minSize=null)
	Sets the profiler typeface and text size.
ProfilerWidget	SetProfilerZOrder (int zOrder)
	Sets the base Z-order used by the profiler label and scrollbar.
ProfilerWidget	Refresh ()
	Immediately reads and formats the latest completed profiler snapshot.
override void	Dispose ()
	Disposes the composite and every child it owns.
Public Member Functions inherited from Gondwana.Widgets.ContainerWidget
override DirectComposite	Add (IDirectCompositeChild child, bool keepCurrentOffset=true, Vector2? explicitLocalOffsetPx=null)
	Adds a composite-compatible direct drawable as a child. Parameters child The child to add. keepCurrentOffset true to preserve the child's current offset from the composite anchor. explicitLocalOffsetPx The offset to use when keepCurrentOffset is false. Returns The current composite. Exceptions ArgumentException Thrown when the child uses another render surface, mode, view, or scene layer. InvalidOperationException Thrown when the child already has another parent or would create a cycle.
override DirectComposite	Remove (IDirectCompositeChild child)
	Removes a child without disposing it. Parameters child The child to detach. Returns The current composite.
override DirectComposite	Clear ()
	Removes every child without disposing them. Returns The current composite.
Public Member Functions inherited from Gondwana.Widgets.WidgetBase
virtual bool	HitTest (View view, Point screenPositionPx)
	Determines whether the widget can be hit at the specified screen position within the specified view.
virtual bool	HitTest (Point screenPositionPx)
	Determines whether the widget can be hit at the specified screen position.
WidgetBase	Show ()
	Shows the widget and registers it for input routing.
WidgetBase	Hide ()
	Hides the widget and releases any routed input state.
WidgetBase	Activate ()
	Activates the widget and brings it to the front of the input order.
WidgetBase	Cancel ()
	Cancels the widget.
Public Member Functions inherited from Gondwana.Drawing.Direct.DirectComposite
	DirectComposite (RenderSurfaceHostBase renderSurfaceHost, DirectDrawingMode mode, PointF anchor=default, string? nickname=null)
	Initializes a new instance of the DirectComposite class.
Vector2	GetPosition ()
	Gets the current composite anchor.
void	SetPosition (Vector2 position)
	Sets the composite anchor and repositions all children from their stored offsets.
DirectComposite	SetPosition (float x, float y)
	Sets the composite anchor and repositions all children from their stored offsets.
DirectComposite	SetLocalOffset (IDirectCompositeChild child, Vector2 newLocalOffsetPx)
	Changes one child's local offset and reapplies its position.
DirectComposite	SetZOrder (int zOrder)
	Applies one Z-order to every descendant.
DirectComposite	SetOpacity (float opacity)
	Applies one opacity to every descendant.
DirectComposite	SetIsVisible (bool visible)
	Applies one visibility value to every descendant.
DirectComposite	FadeTo (float targetOpacity, float durationSec)
	Fades every descendant to the requested opacity.
DirectComposite	FadeIn (float durationSec)
	Fades every descendant to full opacity.
DirectComposite	FadeOut (float durationSec)
	Fades every descendant to zero opacity.
RectangleF	GetDrawLocationScreen (View view)
	Gets the union of all visible descendants as projected through a view.
void	Draw (BackbufferBase backbuffer, RectangleF destRectScreen)
	Performs no direct rendering because descendants render independently.
virtual void	Update (long tick)
	Advances composite movement.

Protected Member Functions
override void	ProcessShown ()
	Performs processing when the widget is shown before notification callbacks are invoked.
override void	ProcessHidden ()
	Performs processing when the widget is hidden before notification callbacks are invoked.
Protected Member Functions inherited from Gondwana.Widgets.ContainerWidget
	ContainerWidget (RenderSurfaceHostBase renderSurfaceHost, DirectDrawingMode mode, PointF anchor=default, string? nickname=null)
	Initializes a new instance of the ContainerWidget class.
TWidget	Add< TWidget > (TWidget widget, Vector2 localOffsetPx)
	Adds a child widget at a local offset from this container's anchor.
bool	RemoveChild (WidgetBase widget, bool dispose=false)
	Removes a child widget from the container.
override void	OnChildAdded (IDirectCompositeChild child)
	Called after a child has been successfully added. Parameters child The child that was added. Overrides should perform only non-throwing bookkeeping. Derived types that need additional validation should override Add, perform that validation before calling the base implementation, and then allow this callback to perform the resulting bookkeeping.
override void	OnChildRemoved (IDirectCompositeChild child)
	Called after a child has been removed from the composite. Parameters child The child that was removed.
override void	ProcessActivated ()
	Performs processing when the widget is activated before notification callbacks are invoked.
override void	ProcessCancelled ()
	Performs processing when the widget is cancelled before notification callbacks are invoked.
Protected Member Functions inherited from Gondwana.Widgets.WidgetBase
	WidgetBase (RenderSurfaceHostBase renderSurfaceHost, DirectDrawingMode mode, PointF anchor=default, string? nickname=null)
	Initializes a new instance of the WidgetBase class.
virtual void	ProcessPointerEnter (WidgetPointerEventArgs args)
	Performs processing when a pointer enters the widget before notification callbacks are invoked.
virtual void	ProcessPointerLeave (WidgetPointerEventArgs args)
	Performs processing when a pointer leaves the widget before notification callbacks are invoked.
virtual void	ProcessPointerDown (WidgetPointerEventArgs args)
	Performs processing when a pointer press begins on the widget before notification callbacks are invoked.
virtual void	ProcessPointerMove (WidgetPointerEventArgs args)
	Performs processing when pointer movement is routed to the widget before notification callbacks are invoked.
virtual void	ProcessPointerUp (WidgetPointerEventArgs args)
	Performs processing when a pointer press is released for the widget before notification callbacks are invoked.
virtual void	ProcessFocusGained ()
	Performs processing when the widget gains focus before notification callbacks are invoked.
virtual void	ProcessFocusLost ()
	Performs processing when the widget loses focus before notification callbacks are invoked.
virtual void	ProcessKeyboardInput (WidgetKeyboardEventArgs args)
	Performs processing when keyboard input is routed to the widget before notification callbacks are invoked.
virtual bool	ShouldDispatchPointerClick (WidgetPointerEventArgs args)
	Determines whether a pointer-click event should be dispatched for the specified pointer event data.
virtual void	OnShown ()
	Called when the widget is shown.
virtual void	OnHidden ()
	Called when the widget is hidden.
virtual void	OnActivated ()
	Called when the widget is activated.
virtual void	OnCancelled ()
	Called when the widget is cancelled.
virtual void	OnPointerEnter (WidgetPointerEventArgs args)
	Called when a pointer enters the widget bounds.
virtual void	OnPointerLeave (WidgetPointerEventArgs args)
	Called when a pointer leaves the widget bounds.
virtual void	OnPointerDown (WidgetPointerEventArgs args)
	Called when a pointer press begins on the widget.
virtual void	OnPointerMove (WidgetPointerEventArgs args)
	Called when pointer movement is routed to the widget.
virtual void	OnPointerUp (WidgetPointerEventArgs args)
	Called when a pointer press is released for the widget.
virtual void	OnMouseWheel (WidgetMouseWheelEventArgs args)
	Called when mouse-wheel input is routed to the widget.
virtual void	OnPointerClick (WidgetPointerEventArgs args)
	Called when a pointer click is dispatched to the widget.
virtual void	OnFocusGained ()
	Called when the widget gains focus.
virtual void	OnFocusLost ()
	Called when the widget loses focus.
virtual void	OnKeyboardInput (WidgetKeyboardEventArgs args)
	Called when keyboard input is routed to the widget.

Properties
LabelWidget	Display [get]
	Gets the label used to render profiler text and optional scrolling.
Rectangle	Bounds [get]
	Gets the current widget bounds in view pixels.
Size	Size [get, set]
	Gets or sets the widget size while preserving its current position.
TimeSpan	RefreshInterval [get, set]
	Gets or sets how frequently the widget reads and formats the latest completed snapshot.
ProfilerMeasurementVisibilityMode	MeasurementVisibilityMode [get, set]
	Gets or sets the default measurement visibility policy.
string	HeaderText [get, set]
	Gets or sets the heading displayed when ShowHeader is enabled.
bool	ShowHeader [get, set]
	Gets or sets whether HeaderText is displayed.
bool	ShowSnapshotMetadata [get, set]
	Gets or sets whether generation, elapsed-window, and truncation information is displayed.
bool	ShowSourceHeaders [get, set]
	Gets or sets whether source name/backend headings are displayed.
bool	ShowUnavailableMeasurements [get, set]
	Gets or sets whether unsupported, not-applicable, and not-yet-sampled measurements are shown when they are otherwise visible.
bool	MeasurementTooltipsEnabled [get, set]
	Gets or sets whether hovering a rendered measurement shows its definition.
bool	ShowMetricSelector [get, set]
	Gets or sets whether the built-in Metrics selector control is displayed.
TooltipWidget	MeasurementTooltip [get]
	Gets the tooltip used for measurement definitions.
ProfilerContextInfo	ContextInfo = ProfilerContextInfo.None [get, set]
	Gets or sets the supplemental runtime context rendered before profiler measurements.
Func< ProfilerWidgetExtensionContext, IEnumerable< string >?>?	AdditionalLinesProvider [get, set]
	Gets or sets an optional callback that supplies application-specific diagnostic lines.
bool	IsCollectionActive [get]
	Gets whether this widget currently owns an active profiler collection request.
Properties inherited from Gondwana.Widgets.ContainerWidget
IReadOnlyList< WidgetBase >	ChildWidgets [get]
	Gets a snapshot of the child widgets directly owned by this container.
Properties inherited from Gondwana.Widgets.WidgetBase
bool	IsInputEnabled [get, set]
	Gets or sets a value indicating whether the widget can participate in input routing.
bool	IsPointerInputEnabled [get, set]
	Gets or sets a value indicating whether the widget can receive pointer input.
bool	IsKeyboardInputEnabled [get, set]
	Gets or sets a value indicating whether the widget can receive keyboard input.
bool	CanReceiveFocus [get, set]
	Gets or sets a value indicating whether the widget can receive keyboard focus.
bool	IsFocused [get, set]
	Gets a value indicating whether the widget currently has keyboard focus.
Properties inherited from Gondwana.Drawing.Direct.DirectComposite
Guid	Id = Guid.NewGuid() [get]
	Gets the unique identifier of the composite.
string?	Nickname [get]
	Gets the optional diagnostic nickname of the composite.
RenderSurfaceHostBase	RenderSurfaceHost [get]
	Gets the render surface host shared by the composite and its children.
DirectDrawingMode	Mode [get]
	Gets the coordinate mode shared by the composite and its children.
SceneLayer?	SceneLayer [get]
	Gets the scene layer shared by all children in scene-layer mode.
View?	View [get]
	Gets the view shared by all children in view mode.
ReadOnlyCollection< IDirectCompositeChild >	Children [get]
	Gets the children owned by the composite.
MovementController	Movement [get]
	Gets the movement controller used to move the composite anchor.
MovementSpace	PositionSpace [get]
	Gets the coordinate space used by the movement controller.
bool	Visible [get, set]
	Gets or sets the visibility of all descendants.
int	ZOrder [get]
	Gets the composite Z-order.
Rectangle	ScreenBounds [get]
	Gets the union of all visible descendants' screen-space bounds.
Rectangle	WorldBounds [get]
	Gets the union of all visible descendants' world-space bounds.

Additional Inherited Members
Events inherited from Gondwana.Widgets.WidgetBase
Action?	Shown
	Occurs when the widget is shown.
Action?	Hidden
	Occurs when the widget is hidden.
Action?	Activated
	Occurs when the widget is activated.
Action?	Cancelled
	Occurs when the widget is cancelled.
Action< WidgetPointerEventArgs >?	PointerEnter
	Occurs when a pointer enters the widget bounds.
Action< WidgetPointerEventArgs >?	PointerLeave
	Occurs when a pointer leaves the widget bounds.
Action< WidgetPointerEventArgs >?	PointerDown
	Occurs when a pointer button or touch press begins on the widget.
Action< WidgetPointerEventArgs >?	PointerMove
	Occurs when a pointer moves while routed to the widget.
Action< WidgetPointerEventArgs >?	PointerUp
	Occurs when a pointer button or touch press is released for the widget.
Action< WidgetPointerEventArgs >?	PointerClick
	Occurs when a pointer press and release completes as a click on the widget.
Action< WidgetMouseWheelEventArgs >?	MouseWheel
	Occurs when mouse-wheel input is routed to the widget while the pointer is over it.
Action?	FocusGained
	Occurs when the widget gains keyboard focus.
Action?	FocusLost
	Occurs when the widget loses keyboard focus.
Action< WidgetKeyboardEventArgs >?	KeyboardInput
	Occurs when keyboard input is routed to the widget.
Events inherited from Gondwana.Drawing.Direct.DirectComposite
EventHandler< IDirectDrawable >?	Disposing
	Occurs when the composite is being disposed.
Events inherited from Gondwana.Drawing.Direct.IDirectDrawable
EventHandler< IDirectDrawable >?	Disposing
	Occurs when the object is being disposed.

Detailed Description

Displays detached RuntimeProfiler snapshots as a screen-space HUD widget.

The widget acquires one profiler collection request while shown and releases it when hidden or disposed. Multiple profiler consumers remain independent. The widget only reads detached snapshots; it does not inspect live scene collections or renderer objects.

Definition at line 121 of file ProfilerWidget.cs.

Constructor & Destructor Documentation

ProfilerWidget()

Gondwana.Widgets.Hud.ProfilerWidget.ProfilerWidget	(	RenderSurfaceHostBase	renderSurfaceHost,
		View	view,
		Rectangle	bounds,
		string?	nickname = null )

Creates a view-level runtime-profiler widget.

Parameters

renderSurfaceHost	The render surface host that owns the widget.
view	The view that renders the widget.
bounds	The widget bounds in view pixels.
nickname	An optional diagnostic nickname.

Definition at line 163 of file ProfilerWidget.cs.

Member Function Documentation

ClearVisibilityOverrides()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.ClearVisibilityOverrides

(

)

Removes all explicit source and measurement visibility overrides.

Returns

The current widget.

Definition at line 480 of file ProfilerWidget.cs.

Dispose()

override void Gondwana.Widgets.Hud.ProfilerWidget.Dispose ( )

virtual

Disposes the composite and every child it owns.

Reimplemented from Gondwana.Drawing.Direct.DirectComposite.

Definition at line 609 of file ProfilerWidget.cs.

IsMeasurementVisible()

bool Gondwana.Widgets.Hud.ProfilerWidget.IsMeasurementVisible	(	string	sourceName,
		string	metricKey )

Returns whether a metric would be displayed under the current source/metric visibility rules.

Parameters

sourceName	The profiler source name.
metricKey	The metric key.

Returns

true when the metric is selected for display.

Definition at line 512 of file ProfilerWidget.cs.

ProcessHidden()

override void Gondwana.Widgets.Hud.ProfilerWidget.ProcessHidden ( )

protectedvirtual

Performs processing when the widget is hidden before notification callbacks are invoked.

Reimplemented from Gondwana.Widgets.ContainerWidget.

Definition at line 599 of file ProfilerWidget.cs.

ProcessShown()

override void Gondwana.Widgets.Hud.ProfilerWidget.ProcessShown ( )

protectedvirtual

Performs processing when the widget is shown before notification callbacks are invoked.

Reimplemented from Gondwana.Widgets.ContainerWidget.

Definition at line 582 of file ProfilerWidget.cs.

Refresh()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.Refresh

(

)

Immediately reads and formats the latest completed profiler snapshot.

Returns

The current widget.

Definition at line 563 of file ProfilerWidget.cs.

SetColors()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetColors	(	SKColor	foreground,
		SKColor	background )

Sets profiler text and background colors.

Parameters

foreground	Text color.
background	Background color.

Returns

The current widget.

Definition at line 525 of file ProfilerWidget.cs.

SetFont()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetFont	(	SKTypeface	typeface,
		float	size,
		float?	minSize = null )

Sets the profiler typeface and text size.

Parameters

typeface	Typeface to use.
size	Primary text size.
minSize	Optional minimum text size.

Returns

The current widget.

Definition at line 538 of file ProfilerWidget.cs.

SetMeasurementDescription()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetMeasurementDescription	(	string	metricKey,
		string?	description )

Defines or replaces hover help for a measurement key.

Parameters

metricKey	The metric key.
description	Human-readable definition. Null or whitespace removes the override.

Returns

The current widget.

Definition at line 494 of file ProfilerWidget.cs.

SetMeasurementVisible() [1/2]

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetMeasurementVisible	(	string	metricKey,
		bool	visible )

Sets a visibility override for a metric key across all profiler sources.

Parameters

metricKey	The metric key, such as "cycle.cpu.ms".
visible	true to show the metric; otherwise, false.

Returns

The current widget.

Definition at line 451 of file ProfilerWidget.cs.

SetMeasurementVisible() [2/2]

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetMeasurementVisible	(	string	sourceName,
		string	metricKey,
		bool	visible )

Sets a visibility override for one metric on one named profiler source.

Parameters

sourceName	The profiler source name.
metricKey	The metric key.
visible	true to show the metric; otherwise, false.

Returns

The current widget.

Definition at line 465 of file ProfilerWidget.cs.

SetProfilerZOrder()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetProfilerZOrder

(

int

zOrder

)

Sets the base Z-order used by the profiler label and scrollbar.

Parameters

zOrder

The base Z-order.

Returns

The current widget.

Definition at line 549 of file ProfilerWidget.cs.

SetSourceVisible()

ProfilerWidget Gondwana.Widgets.Hud.ProfilerWidget.SetSourceVisible	(	string	sourceName,
		bool	visible )

Sets whether all measurements from a named profiler source are displayed.

Parameters

sourceName	The profiler source name, such as "Engine" or "Render surface".
visible	true to show the source; otherwise, false.

Returns

The current widget.

Definition at line 438 of file ProfilerWidget.cs.

Property Documentation

AdditionalLinesProvider

Func<ProfilerWidgetExtensionContext, IEnumerable<string>?>? Gondwana.Widgets.Hud.ProfilerWidget.AdditionalLinesProvider

getset

Gets or sets an optional callback that supplies application-specific diagnostic lines.

The callback runs on the profiler widget's refresh thread, normally the Engine thread, and should remain lightweight. Returned lines are inserted after the header and before built-in runtime context and profiler measurements.

Definition at line 425 of file ProfilerWidget.cs.

Bounds

Rectangle Gondwana.Widgets.Hud.ProfilerWidget.Bounds

get

Gets the current widget bounds in view pixels.

Definition at line 231 of file ProfilerWidget.cs.

ContextInfo

ProfilerContextInfo Gondwana.Widgets.Hud.ProfilerWidget.ContextInfo = ProfilerContextInfo.None

getset

Gets or sets the supplemental runtime context rendered before profiler measurements.

The default is ProfilerContextInfo.None so ordinary profiler displays remain telemetry-only unless a consumer explicitly requests broader runtime context.

Definition at line 415 of file ProfilerWidget.cs.

Display

LabelWidget Gondwana.Widgets.Hud.ProfilerWidget.Display

get

Gets the label used to render profiler text and optional scrolling.

Definition at line 226 of file ProfilerWidget.cs.

HeaderText

string Gondwana.Widgets.Hud.ProfilerWidget.HeaderText

getset

Gets or sets the heading displayed when ShowHeader is enabled.

Definition at line 303 of file ProfilerWidget.cs.

IsCollectionActive

bool Gondwana.Widgets.Hud.ProfilerWidget.IsCollectionActive

get

Gets whether this widget currently owns an active profiler collection request.

Definition at line 430 of file ProfilerWidget.cs.

MeasurementTooltip

TooltipWidget Gondwana.Widgets.Hud.ProfilerWidget.MeasurementTooltip

get

Gets the tooltip used for measurement definitions.

Definition at line 406 of file ProfilerWidget.cs.

MeasurementTooltipsEnabled

bool Gondwana.Widgets.Hud.ProfilerWidget.MeasurementTooltipsEnabled

getset

Gets or sets whether hovering a rendered measurement shows its definition.

Definition at line 359 of file ProfilerWidget.cs.

MeasurementVisibilityMode

ProfilerMeasurementVisibilityMode Gondwana.Widgets.Hud.ProfilerWidget.MeasurementVisibilityMode

getset

Gets or sets the default measurement visibility policy.

Definition at line 285 of file ProfilerWidget.cs.

RefreshInterval

TimeSpan Gondwana.Widgets.Hud.ProfilerWidget.RefreshInterval

getset

Gets or sets how frequently the widget reads and formats the latest completed snapshot.

This controls display refresh only. Profiler observations are still recorded at their normal instrumentation boundaries.

Definition at line 265 of file ProfilerWidget.cs.

ShowHeader

bool Gondwana.Widgets.Hud.ProfilerWidget.ShowHeader

getset

Gets or sets whether HeaderText is displayed.

Definition at line 316 of file ProfilerWidget.cs.

ShowMetricSelector

bool Gondwana.Widgets.Hud.ProfilerWidget.ShowMetricSelector

getset

Gets or sets whether the built-in Metrics selector control is displayed.

The selector is populated from the latest detached snapshot and exposes a persistent, scrollable checklist together with show-all/hide-all, runtime-context, unavailable-state, and tooltip controls.

Definition at line 382 of file ProfilerWidget.cs.

ShowSnapshotMetadata

bool Gondwana.Widgets.Hud.ProfilerWidget.ShowSnapshotMetadata

getset

Gets or sets whether generation, elapsed-window, and truncation information is displayed.

Definition at line 325 of file ProfilerWidget.cs.

ShowSourceHeaders

bool Gondwana.Widgets.Hud.ProfilerWidget.ShowSourceHeaders

getset

Gets or sets whether source name/backend headings are displayed.

Definition at line 334 of file ProfilerWidget.cs.

ShowUnavailableMeasurements

bool Gondwana.Widgets.Hud.ProfilerWidget.ShowUnavailableMeasurements

getset

Gets or sets whether unsupported, not-applicable, and not-yet-sampled measurements are shown when they are otherwise visible.

Definition at line 344 of file ProfilerWidget.cs.

Size

Size Gondwana.Widgets.Hud.ProfilerWidget.Size

getset

Gets or sets the widget size while preserving its current position.

Definition at line 247 of file ProfilerWidget.cs.