perf_timer.h File Reference

High-precision performance measurement (CPU and GPU). More...

#include "gl_common.h"
#include <stdbool.h>
#include <time.h>

Include dependency graph for perf_timer.h:

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

Go to the source code of this file.

Data Structures
struct	PerfTimer
	CPU high-precision timer. More...
struct	GPUTimer
	GPU performance timer using OpenGL Query Objects. More...
struct	HybridTimer
	Hybrid timer combining CPU and GPU measurements. More...
struct	HybridTimerRAII
	Internal helper for scope-based timing. More...

Macros
#define	PERF_MEASURE_MS(var_name)
	Automatically measures a code block and stores result in var_name.
#define	PERF_MEASURE_LOG(label)
	Automatically measures and logs a code block to the "perf" category.
#define	GPU_MEASURE_MS(var_name)
	Automatically measures a GPU block and stores result in var_name.
#define	GPU_MEASURE_LOG(label)
	Automatically measures and logs a GPU block to "perf.gpu".
#define	HYBRID_MEASURE_LOG(label)
	Hybrid measurement macro. Useful for identifying driver vs GPU bottlenecks.
#define	HYBRID_MEASURE_DEBUG_MS(var_name, label)
	Hybrid measurement with DEBUG-level console logging.
#define	HYBRID_FUNC_TIMER(label)
	Scoped hybrid timer. Automatically logs on scope exit.

Functions
void	perf_timer_start (PerfTimer *timer)
	Starts the CPU timer.
double	perf_timer_elapsed_ms (PerfTimer *timer)
	Stops the timer and returns elapsed time in milliseconds.
double	perf_timer_elapsed_us (PerfTimer *timer)
	Stops the timer and returns elapsed time in microseconds.
double	perf_timer_elapsed_s (PerfTimer *timer)
	Stops the timer and returns elapsed time in seconds.
void	gpu_timer_start (GPUTimer *timer)
	Initializes and starts a GPU measurement.
void	gpu_timer_stop (GPUTimer *timer)
	Explicitly stops the GPU timer (records end timestamp).
double	gpu_timer_elapsed_ms (GPUTimer *timer, int wait_for_result)
	Stops the GPU timer and retrieves the result.
void	gpu_timer_cleanup (GPUTimer *timer)
	Releases OpenGL resources associated with the GPU timer.
HybridTimer	perf_hybrid_start (void)
	Starts both CPU and GPU measurement simultaneously.
void	perf_hybrid_stop (HybridTimer *timer, const char *label)
	Stops both measurements and logs the results to the console.
double	perf_hybrid_stop_debug (HybridTimer *timer, const char *label)
	Like perf_hybrid_stop, but logs at DEBUG level instead of INFO.
static void	hybrid_timer_cleanup_raii (HybridTimerRAII *timer_raii)
	Internal cleanup function for HybridTimerRAII.

Detailed Description

High-precision performance measurement (CPU and GPU).

This module provides timers for measuring CPU wall-clock time using clock_gettime and GPU execution time using OpenGL timer queries. It also includes RAII-style macros for automatic profiling.

Macro Definition Documentation

GPU_MEASURE_LOG

#define GPU_MEASURE_LOG

(

label

)

Value:

    for (GPUTimer                                                      \
             _gpu_timer = {0},                                         \
             *_gpu_run = (gpu_timer_start(&_gpu_timer), (GPUTimer*)1); \
         _gpu_run; LOG_INFO("perf.gpu", "%s: %.2f ms", label,          \
                            gpu_timer_elapsed_ms(&_gpu_timer, 1)),     \
             gpu_timer_cleanup(&_gpu_timer), _gpu_run = NULL)

Automatically measures and logs a GPU block to "perf.gpu".

GPU_MEASURE_MS

#define GPU_MEASURE_MS

(

var_name

)

Value:

    double var_name = 0.0;                                             \
    for (GPUTimer _gpu_timer##var_name = {0},                          \
                  *_gpu_run = (gpu_timer_start(&_gpu_timer##var_name), \
                               (GPUTimer*)1);                          \
         _gpu_run;                                                     \
         var_name = gpu_timer_elapsed_ms(&_gpu_timer##var_name, 1),    \
                  gpu_timer_cleanup(&_gpu_timer##var_name),            \
                  _gpu_run = NULL)

Automatically measures a GPU block and stores result in var_name.

HYBRID_FUNC_TIMER

#define HYBRID_FUNC_TIMER

(

label

)

Value:

    HybridTimerRAII _h_raii                                 \
        __attribute__((cleanup(hybrid_timer_cleanup_raii))) \
        __attribute__((unused)) = {perf_hybrid_start(), label}

Scoped hybrid timer. Automatically logs on scope exit.

Usage:

void complex_function() {
    HYBRID_FUNC_TIMER("IBL: Specular Map");
    // ... function body ...
}

HYBRID_MEASURE_DEBUG_MS

#define HYBRID_MEASURE_DEBUG_MS	(		var_name,
			label
	)

Value:

    double var_name = 0.0;                                                \
    for (HybridTimer _h##var_name = perf_hybrid_start(),                  \
                     *_h_run = (HybridTimer*)1;                           \
         _h_run; var_name = perf_hybrid_stop_debug(&_h##var_name, label), \
                     _h_run = NULL)

Hybrid measurement with DEBUG-level console logging.

Like HYBRID_MEASURE_LOG but demotes console output to LOG_DEBUG. Tracy zones are still emitted. Captures GPU elapsed ms into var_name.

Usage:

  HYBRID_MEASURE_DEBUG_MS(gpu_ms, "Progressive IBL: Specular Mip 0 Slice
1/24") { pbr_prefilter_mip(...);
  }
  // gpu_ms now contains the GPU time in milliseconds

HYBRID_MEASURE_LOG

#define HYBRID_MEASURE_LOG

(

label

)

Value:

    for (HybridTimer _h = perf_hybrid_start(), *_h_run = (HybridTimer*)1; \
         _h_run; perf_hybrid_stop(&_h, label), _h_run = NULL)

Hybrid measurement macro. Useful for identifying driver vs GPU bottlenecks.

PERF_MEASURE_LOG

#define PERF_MEASURE_LOG

(

label

)

Value:

    for (PerfTimer _timer = {0},                                       \
                   *_run = (perf_timer_start(&_timer), (PerfTimer*)1); \
         _run; LOG_INFO("perf", "%s: %.2f ms", label,                  \
                        perf_timer_elapsed_ms(&_timer)),               \
                   _run = NULL)

Automatically measures and logs a code block to the "perf" category.

PERF_MEASURE_MS

#define PERF_MEASURE_MS

(

var_name

)

Value:

    double var_name = 0.0;                                                 \
    for (PerfTimer                                                         \
             _timer##var_name = {0},                                       \
             *_run = (perf_timer_start(&_timer##var_name), (PerfTimer*)1); \
         _run;                                                             \
         var_name = perf_timer_elapsed_ms(&_timer##var_name), _run = NULL)

Automatically measures a code block and stores result in var_name.

Usage:

PERF_MEASURE_MS(load_time) {
    // Code to measure
}
printf("Took %.2f ms\n", load_time);

Function Documentation

gpu_timer_cleanup()

void gpu_timer_cleanup

(

GPUTimer *

timer

)

Releases OpenGL resources associated with the GPU timer.

Parameters

timer

Pointer to the timer.

gpu_timer_elapsed_ms()

double gpu_timer_elapsed_ms	(	GPUTimer *	timer,
		int	wait_for_result
	)

Stops the GPU timer and retrieves the result.

Parameters

timer	Pointer to the timer.
wait_for_result	If true, blocks until the GPU is finished and result is ready.

Returns

Elapsed time in milliseconds, or -1.0 if not ready and wait_for_result is false.

gpu_timer_start()

void gpu_timer_start

(

GPUTimer *

timer

)

Initializes and starts a GPU measurement.

Parameters

timer

Pointer to the timer.

gpu_timer_stop()

void gpu_timer_stop

(

GPUTimer *

timer

)

Explicitly stops the GPU timer (records end timestamp).

Parameters

timer

Pointer to the timer.

hybrid_timer_cleanup_raii()

static void hybrid_timer_cleanup_raii ( HybridTimerRAII *  timer_raii )

inlinestatic

Internal cleanup function for HybridTimerRAII.

Here is the call graph for this function:

perf_hybrid_start()

HybridTimer perf_hybrid_start

(

void

)

Starts both CPU and GPU measurement simultaneously.

Returns

Initialized and started HybridTimer structure.

Here is the call graph for this function:

perf_hybrid_stop()

void perf_hybrid_stop	(	HybridTimer *	timer,
		const char *	label
	)

Stops both measurements and logs the results to the console.

Parameters

timer	Pointer to the timer.
label	Descriptive string for the log entry.

perf_hybrid_stop_debug()

double perf_hybrid_stop_debug	(	HybridTimer *	timer,
		const char *	label
	)

Like perf_hybrid_stop, but logs at DEBUG level instead of INFO.

Tracy zones are still emitted at full detail. Only the console output is demoted to reduce noise in production. Returns GPU elapsed ms.

Parameters

timer	Pointer to the timer.
label	Descriptive string for the log entry.

Returns

GPU elapsed time in milliseconds.

perf_timer_elapsed_ms()

double perf_timer_elapsed_ms

(

PerfTimer *

timer

)

Stops the timer and returns elapsed time in milliseconds.

Parameters

timer

Pointer to the timer.

Returns

Elapsed time (double precision).

perf_timer_elapsed_s()

double perf_timer_elapsed_s

(

PerfTimer *

timer

)

Stops the timer and returns elapsed time in seconds.

Parameters

timer

Pointer to the timer.

Returns

Elapsed time (double precision).

perf_timer_elapsed_us()

double perf_timer_elapsed_us

(

PerfTimer *

timer

)

Stops the timer and returns elapsed time in microseconds.

Parameters

timer

Pointer to the timer.

Returns

Elapsed time (double precision).

perf_timer_start()

void perf_timer_start

(

PerfTimer *

timer

)

Starts the CPU timer.

Parameters

timer

Pointer to the timer.