adaptive_sampler.h File Reference

Adaptive sampling utility for performance metrics. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for adaptive_sampler.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	AdaptiveSampleItem
	Represents a single data point in the sampler. More...
struct	Pcg32
	State for a Permuted Congruential Generator (PCG) RNG. More...
struct	AdaptiveSampler
	Collector for performance samples within a rolling or fixed window. More...

Functions
void	adaptive_sampler_add (AdaptiveSampler *sampler, float value, uint64_t frame_index)
	Manually adds a sample to the sampler (e.g. from external source like GPU profiler). More...
void	adaptive_sampler_init (AdaptiveSampler *sampler, float window_duration, size_t target_samples, float initial_fps_guess)
	Initializes the adaptive sampler. More...
int	adaptive_sampler_should_sample (AdaptiveSampler *sampler, float delta_time, double current_time, uint64_t frame_index)
	Determines if a sample should be taken this frame based on probability. More...
int	adaptive_sampler_is_finished (const AdaptiveSampler *sampler, double current_time)
	Checks if the current sampling window has concluded. More...
float	adaptive_sampler_get_average (const AdaptiveSampler *sampler)
	Calculates the arithmetic mean of all samples in the current window. More...
size_t	adaptive_sampler_get_sample_count (const AdaptiveSampler *sampler)
	Returns the number of samples currently in the buffer. More...
void	adaptive_sampler_get_window_range (const AdaptiveSampler *sampler, uint64_t *start_frame, uint64_t *end_frame)
	Retrieves the frame index range covered by the current window. More...
size_t	adaptive_sampler_get_sample_indices (const AdaptiveSampler *sampler, uint64_t *out_indices, size_t max_count)
	Retrieves the list of frame indices for all collected samples. More...
void	adaptive_sampler_reset (AdaptiveSampler *sampler, double current_time)
	Resets the sampler state for a new window. More...
void	adaptive_sampler_cleanup (AdaptiveSampler *sampler)
	Frees all dynamic memory associated with the sampler. More...

Detailed Description

Adaptive sampling utility for performance metrics.

This module provides a mechanism to sample values (like FPS) adaptively over a time window, using a PRNG to avoid aliasing artifacts.

Function Documentation

adaptive_sampler_add()

void adaptive_sampler_add	(	AdaptiveSampler *	sampler,
		float	value,
		uint64_t	frame_index
	)

Manually adds a sample to the sampler (e.g. from external source like GPU profiler).

Parameters

sampler	Pointer to the sampler.
value	The value to add.
frame_index	The frame index associated with this value.

adaptive_sampler_cleanup()

void adaptive_sampler_cleanup

(

AdaptiveSampler *

sampler

)

Frees all dynamic memory associated with the sampler.

Parameters

sampler

Pointer to the sampler.

adaptive_sampler_get_average()

float adaptive_sampler_get_average

(

const AdaptiveSampler *

sampler

)

Calculates the arithmetic mean of all samples in the current window.

Parameters

sampler

Pointer to the sampler.

Returns

The average value.

adaptive_sampler_get_sample_count()

size_t adaptive_sampler_get_sample_count

(

const AdaptiveSampler *

sampler

)

Returns the number of samples currently in the buffer.

Parameters

sampler

Pointer to the sampler.

Returns

Sample count.

adaptive_sampler_get_sample_indices()

size_t adaptive_sampler_get_sample_indices	(	const AdaptiveSampler *	sampler,
		uint64_t *	out_indices,
		size_t	max_count
	)

Retrieves the list of frame indices for all collected samples.

Parameters

sampler	Pointer to the sampler.
out_indices	Buffer to store the frame indices.
max_count	Size of the output buffer.

Returns

Number of indices written to the buffer.

adaptive_sampler_get_window_range()

void adaptive_sampler_get_window_range	(	const AdaptiveSampler *	sampler,
		uint64_t *	start_frame,
		uint64_t *	end_frame
	)

Retrieves the frame index range covered by the current window.

Parameters

sampler	Pointer to the sampler.
start_frame	Output for start frame index (can be NULL).
end_frame	Output for end frame index (can be NULL).

adaptive_sampler_init()

void adaptive_sampler_init	(	AdaptiveSampler *	sampler,
		float	window_duration,
		size_t	target_samples,
		float	initial_fps_guess
	)

Initializes the adaptive sampler.

Parameters

sampler	Pointer to the sampler.
window_duration	Length of the window in seconds.
target_samples	Approximate number of samples to collect.
initial_fps_guess	Starting value for EMA to avoid cold-start bias.

Here is the call graph for this function:

adaptive_sampler_is_finished()

int adaptive_sampler_is_finished	(	const AdaptiveSampler *	sampler,
		double	current_time
	)

Checks if the current sampling window has concluded.

Parameters

sampler	Pointer to the sampler.
current_time	Absolute time in seconds.

Returns

1 if the window duration has elapsed, 0 otherwise.

adaptive_sampler_reset()

void adaptive_sampler_reset	(	AdaptiveSampler *	sampler,
		double	current_time
	)

Resets the sampler state for a new window.

Parameters

sampler	Pointer to the sampler.
current_time	New window start time.

adaptive_sampler_should_sample()

int adaptive_sampler_should_sample	(	AdaptiveSampler *	sampler,
		float	delta_time,
		double	current_time,
		uint64_t	frame_index
	)

Determines if a sample should be taken this frame based on probability.

Parameters

sampler	Pointer to the sampler.
delta_time	Current frame duration.
current_time	Absolute time in seconds.
frame_index	Current frame index.

Returns

1 if a sample should be recorded, 0 otherwise.

Here is the call graph for this function: