Profiler

#include <Ultralight/platform/Profiler.h>

Overview

User-defined profiling interface.

Implement this class to receive profiling callbacks from the library. The callbacks provide structured timing data (scopes, events, counters) that can be forwarded to any profiling backend – Tracy, Optick, Unreal Insights, the built-in Perfetto trace file writer provided below (CreateProfilerPerfetto()), or a custom implementation.

Precondition

Requires the Pro edition or higher.

Usage

1. Subclass Profiler and implement all pure virtual methods.
2. Call Platform::instance().set_profiler(myProfiler) before creating the Renderer or App.
3. Your profiler instance should outlive the Renderer/App.

Frame Timing

The library automatically calls BeginFrame() and EndFrame() around each rendering frame. Implement these to measure dirty-to-display latency and detect jank.

Threading

All methods may be called concurrently from any thread. Implementations must be thread-safe.

See also

Platform::set_profiler

Public Member Functions
virtual	~Profiler ()
virtual void	BeginScope (const char *name)=0
	Enter a named profiling scope.
virtual void	EndScope ()=0
	Exit the most recently entered scope on the current thread.
virtual void	BeginFrame (uint64_t frame_id)
	Called when a new rendering frame begins.
virtual void	EndFrame ()
	Called when a rendering frame ends.
virtual void	EmitEvent (const char *name, const char *detail)=0
	Record an instant (point-in-time) event on the timeline.
virtual void	EmitCounter (const char *name, int64_t value)=0
	Record a counter value.
virtual uint64_t	BeginEvent (const char *name, const char *detail)=0
	Begin an async event that may span multiple frames.
virtual void	EndEvent (uint64_t id)=0
	End a previously started async event.

Constructor & Destructor Documentation

~Profiler()

virtual ~Profiler ( )

virtual

Member Function Documentation

BeginEvent()

virtual uint64_t BeginEvent ( const char * name, const char * detail )

pure virtual

Begin an async event that may span multiple frames.

Unlike scopes, async events can overlap and are not bound to a single call stack. Use these for long-running operations like page loads or resource fetches.

Parameters

name	A static string literal identifying the event type (e.g., "View.PageLoad").
detail	Optional context string (may be nullptr).

Returns

A non-zero event ID that must be passed to EndEvent() to close the span. Returning 0 is reserved as a "no event" sentinel.

BeginFrame()

virtual void BeginFrame ( uint64_t frame_id )

inlinevirtual

Called when a new rendering frame begins.

Called automatically by the library– users do not call this directly.

Parameters

frame_id

Monotonic frame counter.

BeginScope()

virtual void BeginScope ( const char * name )

pure virtual

Enter a named profiling scope.

Calls are always balanced (BeginScope / EndScope pairs). Implementations should maintain a per-thread stack of active scopes.

Parameters

name	A static string literal identifying the scope (e.g., "Ultralight.Layout"). The string should be valid for the lifetime of the library.

EmitCounter()

virtual void EmitCounter ( const char * name, int64_t value )

pure virtual

Record a counter value.

Called periodically with named numeric values (e.g., memory usage, object counts). Profiling tools typically render these as line or area charts.

Parameters

name	A static string literal identifying the counter (e.g., "Memory.VRAM").
value	The current value.

EmitEvent()

virtual void EmitEvent ( const char * name, const char * detail )

pure virtual

Record an instant (point-in-time) event on the timeline.

Parameters

name	A static string literal identifying the event (e.g., "View.LoadURL").
detail	Optional context string (may be nullptr).

EndEvent()

virtual void EndEvent ( uint64_t id )

pure virtual

End a previously started async event.

Parameters

id	The event ID returned by BeginEvent().

EndFrame()

virtual void EndFrame ( )

inlinevirtual

Called when a rendering frame ends.

Called automatically by the library– users do not call this directly.

EndScope()

virtual void EndScope ( )

pure virtual

Exit the most recently entered scope on the current thread.

---

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

• Ultralight/platform/Profiler.h