stash

[fips] / metrics.h

diff --git a/metrics.h b/metrics.h
index 8b688678d2f5601d1471d67289418ff13f5fc8a4..6cfc1494175cebfe13aec05606961f9facb3d3a7 100644 (file)
--- a/metrics.h
+++ b/metrics.h
@@ -22,34 +22,121 @@
 #ifndef METRICS_H
 #define METRICS_H
 
+#include "metrics-info.h"
+
+typedef enum
+{
+       METRICS_OP_ACCUM,
+       METRICS_OP_BUFFER_DATA,
+       METRICS_OP_BUFFER_SUB_DATA,
+       METRICS_OP_BITMAP,
+       METRICS_OP_BLIT_FRAMEBUFFER,
+       METRICS_OP_CLEAR,
+       METRICS_OP_CLEAR_BUFFER_DATA,
+       METRICS_OP_CLEAR_TEX_IMAGE,
+       METRICS_OP_COPY_PIXELS,
+       METRICS_OP_COPY_TEX_IMAGE,
+       METRICS_OP_DRAW_PIXELS,
+       METRICS_OP_GET_TEX_IMAGE,
+       METRICS_OP_READ_PIXELS,
+       METRICS_OP_TEX_IMAGE,
+
+       /* METRICS_OP_SHADER must be last.
+        * 
+        * All larger values for metrics_op_t are interpreted as:
+        *
+        *      METRICS_OP_SHADER + shader_program_number
+        *
+        * to indicate a specific shader program.
+        */
+       METRICS_OP_SHADER
+} metrics_op_t;
+
+typedef struct metrics metrics_t;
+
+/* Create a new metrics_t object for tracking metrics, given the
+ * pre-initialized metrics_info_t* describing available counters. */
+metrics_t *
+metrics_create (metrics_info_t *info);
+
+/* Free all internal resources of a metrics_t
+ *
+ * All outstanding metrics counters are discarded.
+ *
+ * The metrics_t object remains valid and may be used again.
+ */
+void
+metrics_fini (metrics_t *metrics);
+
+/* Destroy a metrics_t object.
+ *
+ * After this call, the metrics_t* value is and must not be used
+ * further. */
+void
+metrics_destroy (metrics_t *metrics);
+
 /* Start accumulating GPU time.
  *
  * The time accumulated will be accounted against the
  * current program (as set with metrics_set_current_program).
  */
 void
-metrics_counter_start (void);
+metrics_counter_start (metrics_t *metrics);
 
 /* Stop accumulating GPU time (stops the most-recently started counter) */
 void
-metrics_counter_stop (void);
+metrics_counter_stop (metrics_t *metrics);
+
+/* Set a metrics_op_t value to indicate what kind of operation is
+ * being performed.
+ *
+ * The metrics-tracking code will account for timings by accumulating
+ * measured counter values into a separate counter for each
+ * metrics_op_t value, (so that the report can describe which
+ * operations are the most expensive).
+ *
+ * In addition, for the value METRICS_OP_SHADER, each specific shader
+ * program can be distinguished. To accomplish this, pass a value of
+ * METRICS_OP_SHADER + shader_program_number to this function.
+ */
+void
+metrics_set_current_op (metrics_t *metrics, metrics_op_t op);
 
-/* Set the ID of the currently executing shader program.
+/* Return the current metrics_op_t value, (the value most-recently-set
+ * with a call to metrics_set_current_op).
+ */
+metrics_op_t
+metrics_get_current_op (metrics_t *metrics);
+
+/* This pair of functions can be used to indicate a frame end.
+ *
+ * Both functions should be by every function wrapper for a function
+ * that ends a frame, (glXSwapBuffers and similar). The pre_swap
+ * before the call to the underlying swap function, and post_swap
+ * after.
  *
- * The metrics-tracking code will account for per-shader-program
- * timings by accumulating counter values measured while each porogram
- * is active (see metrics_add_counter).
+ * These functions trigger whatever bookkeeping is necessary to
+ * generate a timing report, (such as collecting any outstanding timer
+ * query values), and will also emit those reports when necessary.
  */
 void
-metrics_set_current_program (unsigned program);
+metrics_end_frame_pre_swap (metrics_t *metrics);
 
-/* Should be called at the end of every function wrapper for a
- * function that ends a frame, (glXSwapBuffers and similar).
+void
+metrics_end_frame_post_swap (metrics_t *metrics);
+
+/* Process outstanding metrics requests, accumulating results.
+ *
+ * This function is called automatically by metrics_end_frame.
  *
- * This function performs whatever bookkeeping is necessary to
- * generate a timing report, then emits that report.
+ * During a frame, it may be important to call this function to avoid
+ * too many oustanding timer/performance-monitor queries. At the same
+ * time, it's important not to call this function too frequently,
+ * since collection of metrics information will result in flushes of
+ * the OpenGL pipeline which can interfere with the behavior being
+ * measured.
  */
 void
-metrics_end_frame (void);
+metrics_collect_available (metrics_t *metrics);
 
 #endif