Classes
struct	TraceOptions
struct	Provenance
struct	SampleEvent
struct	PublishOptions
struct	FixtureHeader
	Header metadata recorded once at the top of a fixture file. More...
struct	FixtureDiff
	Comparison result from assert_matches. More...
struct	FixtureMatchOptions
struct	ScalarSample
	Flatten a fixture's events into a (time, value) series for one (view, metric, component) triple. More...
class	InputRecorder
	Recording handle returned by make_input_recorder. More...
class	TraceHandle
class	TraceBuilder
class	Coordinator
	Process-wide singleton that owns one FrameClock subscription, holds the active trace set, and dispatches sample events to registered sinks. More...
struct	CostSample
	Per-frame cost attribution sample. More...
struct	RenderCostSnapshot
	Snapshot of render-layer cost for the current frame. More...
class	CostAttributor
	Process-wide cost attribution stream. More...

Typedefs
using	Sink = std::function<void(const SampleEvent&)>
using	CostProbe = std::function<RenderCostSnapshot()>

Enumerations
enum class	GeometrySource { Layout , Presentation }
enum class	GeometrySpace { ViewLocal , ViewGlobal , Window , Screen }
enum class	GeometryProperty { MinX , MinY , MaxX , MaxY , MidX , MidY , Width , Height }
enum class	ScrollProperty { ContentOffsetX , ContentOffsetY , VisibleRectMinX , VisibleRectMinY , VisibleRectWidth , VisibleRectHeight , ContentSizeWidth , ContentSizeHeight , InsetTop , InsetBottom , InsetLeft , InsetRight , ScrollableMaxX , ScrollableMaxY }

Functions
std::string	format_line (const SampleEvent &e)
	Render the canonical [PulpMotion][view][metric] ... line for a sample event.
void	publish_value (std::string view_name, std::string metric_name, double value, PublishOptions opts={})
	Single-component publish.
void	publish_components (std::string view_name, std::string metric_name, std::vector< std::pair< std::string, double > > components, PublishOptions opts={})
	Multi-component publish (e.g., a 2D point or a geometry rect).
void	set_ambient_provenance (Provenance p)
void	clear_ambient_provenance ()
Provenance	current_ambient_provenance ()
std::vector< SampleEvent >	load_fixture (const std::string &path)
	Load a fixture file into memory.
FixtureHeader	load_fixture_header (const std::string &path)
	Load a fixture's header (schema version + policy + duration_scale).
FixtureDiff	assert_matches (const std::vector< SampleEvent > &golden, const std::vector< SampleEvent > &captured, FixtureMatchOptions opts={})
FixtureDiff	assert_matches (const FixtureHeader &golden_header, const std::vector< SampleEvent > &golden, const FixtureHeader &captured_header, const std::vector< SampleEvent > &captured, FixtureMatchOptions opts={})
	Overload that also compares fixture headers.
std::vector< ScalarSample >	extract_scalar (const std::vector< SampleEvent > &events, std::string_view view_name, std::string_view metric_name, std::string_view component_name="value")
bool	is_monotonic (const std::vector< ScalarSample > &samples, double epsilon=1e-6)
	Strict monotonicity check with epsilon.
double	settling_time_seconds (const std::vector< ScalarSample > &samples, double epsilon=1e-6)
	Time from first change above epsilon to last change above epsilon.
double	overshoot (const std::vector< ScalarSample > &samples, double epsilon=1e-6)
	Overshoot relative to the final value: max excursion beyond the final value's direction from the first stable region.
double	start_delay_seconds (const std::vector< ScalarSample > &samples, double epsilon=1e-6)
	Time from t0 to the first change above epsilon.
double	frame_jitter_seconds (const std::vector< ScalarSample > &samples)
	Standard deviation of inter-sample intervals — proxy for frame-pacing jitter when the sampler is run at a fixed FPS.
double	final_value (const std::vector< ScalarSample > &samples)
	Returns the last sample's value, or NaN when empty.
double	local_step_outlier_ratio (const std::vector< ScalarSample > &samples, std::size_t window_radius=3, double epsilon=1e-9)
	Local-step outlier ratio.
Sink	make_log_sink ()
	Sink that writes one log line per event via pulp::runtime::log_debug.
Sink	make_buffer_sink (std::vector< SampleEvent > *buffer)
	Sink that appends events to a caller-owned buffer.
Sink	make_fixture_sink (std::string path)
	Sink that appends each SampleEvent as a JSONL line to path.
int	replay_fixture (const std::string &path, const Sink &sink)
	Read a fixture file from disk and dispatch each event to sink.
InputRecorder	make_input_recorder (std::string path)
	Install a fixture sink at path and enable simulate_* recording.
int	replay_inputs (const std::string &path, View &root_view, FrameClock &frame_clock)
	Read a fixture file, find each Input event, resolve view_id from root_view for diagnostics, and re-dispatch the matching View::simulate_* through root_view.
void	record_simulated_input (const std::string &input_kind, const std::string &view_id, std::vector< std::pair< std::string, double > > coords)
	Process-wide entry point called by View::simulate_* when input recording is active.
bool	input_recording_enabled () noexcept
	True while at least one InputRecorder is alive.
CostAttributor::CostSink	make_cost_sink (std::string path)
	Sink that appends each CostSample as a JSONL line to path.
CostAttributor::CostSink	make_cost_buffer_sink (std::vector< CostSample > *buffer)
	Sink that appends each CostSample to a caller-owned buffer.
std::string	serialize_cost_sample (const CostSample &s)
	Serialize one CostSample as a single JSON line (without trailing newline).
std::vector< CostSample >	load_cost_stream (const std::string &path)
	Parse a JSONL CostSample stream from path.
CostProbe	make_render_cost_probe (const pulp::render::RenderPassManager passes, const pulp::render::DirtyTracker dirty)
	Build a CostProbe that snapshots both subsystems each tick.

Variables
constexpr int	kFixtureSchemaVersion = 2
constexpr int	kInvalidFixtureSchemaVersion = 0
	Sentinel for a default-constructed / unrecognised fixture header.
constexpr int	kCostSchemaVersion = 1

Typedef Documentation

◆ CostProbe

using pulp::view::motion::CostProbe = std::function<RenderCostSnapshot()>

◆ Sink

using pulp::view::motion::Sink = std::function<void(const SampleEvent&)>

Enumeration Type Documentation

◆ GeometryProperty

enum class pulp::view::motion::GeometryProperty

strong

Enumerator
MinX
MinY
MaxX
MaxY
MidX
MidY
Width
Height

◆ GeometrySource

enum class pulp::view::motion::GeometrySource

strong

Enumerator
Layout	Yoga-computed bounds, ignoring paint-time transforms.
Presentation	After paint_all() composition; currently falls back to Layout.

◆ GeometrySpace

enum class pulp::view::motion::GeometrySpace

strong

Enumerator
ViewLocal	Origin at the target view's top-left, in its own frame.
ViewGlobal	Root-view coordinate space.
Window	Currently same as ViewGlobal; reserved for window origin.
Screen	Currently same as ViewGlobal; reserved for screen offset.

◆ ScrollProperty

enum class pulp::view::motion::ScrollProperty

strong

Enumerator
ContentOffsetX
ContentOffsetY
VisibleRectMinX
VisibleRectMinY
VisibleRectWidth
VisibleRectHeight
ContentSizeWidth
ContentSizeHeight
InsetTop
InsetBottom
InsetLeft
InsetRight
ScrollableMaxX
ScrollableMaxY

Function Documentation

◆ assert_matches() [1/2]

FixtureDiff pulp::view::motion::assert_matches	(	const FixtureHeader &	golden_header,
		const std::vector< SampleEvent > &	golden,
		const FixtureHeader &	captured_header,
		const std::vector< SampleEvent > &	captured,
		FixtureMatchOptions	opts = {} )

Overload that also compares fixture headers.

Adds a "policy-mismatch" Item to the diff when policy / duration_scale differ and opts.require_matching_policy is true. Otherwise behaves identically to the event-only overload.

◆ assert_matches() [2/2]

FixtureDiff pulp::view::motion::assert_matches	(	const std::vector< SampleEvent > &	golden,
		const std::vector< SampleEvent > &	captured,
		FixtureMatchOptions	opts = {} )

◆ clear_ambient_provenance()

void pulp::view::motion::clear_ambient_provenance ( )

◆ current_ambient_provenance()

Provenance pulp::view::motion::current_ambient_provenance ( )

◆ extract_scalar()

std::vector< ScalarSample > pulp::view::motion::extract_scalar	(	const std::vector< SampleEvent > &	events,
		std::string_view	view_name,
		std::string_view	metric_name,
		std::string_view	component_name = "value" )

◆ final_value()

double pulp::view::motion::final_value ( const std::vector< ScalarSample > & samples )

Returns the last sample's value, or NaN when empty.

◆ format_line()

std::string pulp::view::motion::format_line ( const SampleEvent & e )

Render the canonical [PulpMotion][view][metric] ... line for a sample event.

◆ frame_jitter_seconds()

double pulp::view::motion::frame_jitter_seconds ( const std::vector< ScalarSample > & samples )

Standard deviation of inter-sample intervals — proxy for frame-pacing jitter when the sampler is run at a fixed FPS.

◆ input_recording_enabled()

bool pulp::view::motion::input_recording_enabled ( )

noexcept

True while at least one InputRecorder is alive.

Off by default; View::simulate_* gates on this so the non-recording cost stays a single load + branch.

◆ is_monotonic()

bool pulp::view::motion::is_monotonic	(	const std::vector< ScalarSample > &	samples,
		double	epsilon = 1e-6 )

Strict monotonicity check with epsilon.

Direction inferred from the first non-zero change. Returns false if any subsequent change reverses direction beyond epsilon.

◆ load_cost_stream()

std::vector< CostSample > pulp::view::motion::load_cost_stream ( const std::string & path )

Parse a JSONL CostSample stream from path.

Returns the body events in file order. Empty vector on missing / unreadable / unknown-version files.

◆ load_fixture()

std::vector< SampleEvent > pulp::view::motion::load_fixture ( const std::string & path )

Load a fixture file into memory.

Returns events in file order. Empty vector on missing / unreadable / unknown-version files.

◆ load_fixture_header()

FixtureHeader pulp::view::motion::load_fixture_header ( const std::string & path )

Load a fixture's header (schema version + policy + duration_scale).

Returns a default-constructed FixtureHeader on parse failure.

◆ local_step_outlier_ratio()

double pulp::view::motion::local_step_outlier_ratio	(	const std::vector< ScalarSample > &	samples,
		std::size_t	window_radius = 3,
		double	epsilon = 1e-9 )

Local-step outlier ratio.

Given a sample series, computes for each sample the ratio of its step magnitude to the median step magnitude in a sliding window of window_radius neighbors on each side. Returns the maximum ratio observed. A value of 1.0 means every step is close to the local median (smooth); 5.0 means at least one step was 5x larger than its neighbors (a jump). Useful as a SEPARATE assertion from is_monotonic / overshoot — does NOT conflate continuity, timing, or direction into one number.

Returns 0.0 when samples.size() < 2 * window_radius + 1. The local median excludes the candidate step itself so a one-off jump cannot dominate its own reference window.

◆ make_buffer_sink()

Sink pulp::view::motion::make_buffer_sink ( std::vector< SampleEvent > * buffer )

Sink that appends events to a caller-owned buffer.

For tests and in-process consumers; the buffer pointer must outlive the sink.

◆ make_cost_buffer_sink()

CostAttributor::CostSink pulp::view::motion::make_cost_buffer_sink ( std::vector< CostSample > * buffer )

Sink that appends each CostSample to a caller-owned buffer.

For tests / in-process consumers; the buffer pointer must outlive the sink.

◆ make_cost_sink()

CostAttributor::CostSink pulp::view::motion::make_cost_sink ( std::string path )

Sink that appends each CostSample as a JSONL line to path.

Opens (truncates) the file on first sample, writing a one-line header {"motion_cost_version":1} then a JSONL body. Closes implicitly when the returned CostSink is dropped.

◆ make_fixture_sink()

Sink pulp::view::motion::make_fixture_sink ( std::string path )

Sink that appends each SampleEvent as a JSONL line to path.

Opens the file (truncates) on first event. Subsequent events append. Closes implicitly when the returned Sink is dropped. Pair with Coordinator::add_sink(make_fixture_sink(path)).

◆ make_input_recorder()

InputRecorder pulp::view::motion::make_input_recorder ( std::string path )

Install a fixture sink at path and enable simulate_* recording.

Returns an InputRecorder whose destructor stops both the sink and the recording. Off by default. Repeated calls install independent recorders; each gets its own sink id.

◆ make_log_sink()

Sink pulp::view::motion::make_log_sink ( )

Sink that writes one log line per event via pulp::runtime::log_debug.

◆ make_render_cost_probe()

CostProbe pulp::view::motion::make_render_cost_probe	(	const pulp::render::RenderPassManager *	passes,
		const pulp::render::DirtyTracker *	dirty )

inline

Build a CostProbe that snapshots both subsystems each tick.

Either pointer may be null; the corresponding fields default to

Pointers must outlive the returned probe — callers typically own these as members of their render host.

◆ overshoot()

double pulp::view::motion::overshoot	(	const std::vector< ScalarSample > &	samples,
		double	epsilon = 1e-6 )

Overshoot relative to the final value: max excursion beyond the final value's direction from the first stable region.

Reported as a fraction of total displacement (0.0 = clean, 0.1 = 10% overshoot).

◆ publish_components()

void pulp::view::motion::publish_components	(	std::string	view_name,
		std::string	metric_name,
		std::vector< std::pair< std::string, double > >	components,
		PublishOptions	opts = {} )

Multi-component publish (e.g., a 2D point or a geometry rect).

Components are sorted by name before emission so log lines are stable.

◆ publish_value()

void pulp::view::motion::publish_value	(	std::string	view_name,
		std::string	metric_name,
		double	value,
		PublishOptions	opts = {} )

Single-component publish.

◆ record_simulated_input()

void pulp::view::motion::record_simulated_input	(	const std::string &	input_kind,
		const std::string &	view_id,
		std::vector< std::pair< std::string, double > >	coords )

Process-wide entry point called by View::simulate_* when input recording is active.

Public so the View free functions can reach it without a friend relationship; callers should prefer the View::simulate_* API.

◆ replay_fixture()

int pulp::view::motion::replay_fixture	(	const std::string &	path,
		const Sink &	sink )

Read a fixture file from disk and dispatch each event to sink.

Returns the number of events replayed, or -1 on parse error.

◆ replay_inputs()

int pulp::view::motion::replay_inputs	(	const std::string &	path,
		View &	root_view,
		FrameClock &	frame_clock )

Read a fixture file, find each Input event, resolve view_id from root_view for diagnostics, and re-dispatch the matching View::simulate_* through root_view.

Between inputs the frame_clock is advanced by the delta between recorded t_seconds. Click and drag events also restore the optional pointer metadata components (pointer_type, pressure, modifiers, button, pointer_id). Coordinate-only v2 fixtures retain the historical synthetic mouse defaults. Invalid metadata fields fall back independently to those defaults. Returns the number of inputs replayed, or -1 on parse error.

◆ serialize_cost_sample()

std::string pulp::view::motion::serialize_cost_sample ( const CostSample & s )

Serialize one CostSample as a single JSON line (without trailing newline).

Exposed for tests and the inspector domain.

◆ set_ambient_provenance()

void pulp::view::motion::set_ambient_provenance ( Provenance p )

◆ settling_time_seconds()

double pulp::view::motion::settling_time_seconds	(	const std::vector< ScalarSample > &	samples,
		double	epsilon = 1e-6 )

Time from first change above epsilon to last change above epsilon.

0.0 if fewer than 2 changes.

◆ start_delay_seconds()

double pulp::view::motion::start_delay_seconds	(	const std::vector< ScalarSample > &	samples,
		double	epsilon = 1e-6 )

Time from t0 to the first change above epsilon.

Variable Documentation

◆ kCostSchemaVersion

int pulp::view::motion::kCostSchemaVersion = 1

constexpr

◆ kFixtureSchemaVersion

int pulp::view::motion::kFixtureSchemaVersion = 2

constexpr

◆ kInvalidFixtureSchemaVersion

int pulp::view::motion::kInvalidFixtureSchemaVersion = 0

constexpr

Sentinel for a default-constructed / unrecognised fixture header.

load_fixture_header() returns a FixtureHeader with this version when the file is missing, empty, or its header fails to parse, so callers can distinguish "valid empty fixture" from "load failed".

Pulp 1.88.0 Cross-platform audio plugin framework

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ CostProbe

◆ Sink

Enumeration Type Documentation

◆ GeometryProperty

◆ GeometrySource

◆ GeometrySpace

◆ ScrollProperty

Function Documentation

◆ assert_matches() [1/2]

◆ assert_matches() [2/2]

◆ clear_ambient_provenance()

◆ current_ambient_provenance()

◆ extract_scalar()

◆ final_value()

◆ format_line()

◆ frame_jitter_seconds()

◆ input_recording_enabled()

◆ is_monotonic()

◆ load_cost_stream()

◆ load_fixture()

◆ load_fixture_header()

◆ local_step_outlier_ratio()

◆ make_buffer_sink()

◆ make_cost_buffer_sink()

◆ make_cost_sink()

◆ make_fixture_sink()

◆ make_input_recorder()

◆ make_log_sink()

◆ make_render_cost_probe()

◆ overshoot()

◆ publish_components()

◆ publish_value()

◆ record_simulated_input()

◆ replay_fixture()

◆ replay_inputs()

◆ serialize_cost_sample()

◆ set_ambient_provenance()

◆ settling_time_seconds()

◆ start_delay_seconds()

Variable Documentation

◆ kCostSchemaVersion

◆ kFixtureSchemaVersion

◆ kInvalidFixtureSchemaVersion