derived: add DerivedGfxInfoStats
Add DerivedGfxInfoStats that parse output from GfxInfoFramesInstrument
to produce FPS data and rendering statistics.
diff --git a/doc/derived_measurements.rst b/doc/derived_measurements.rst
index 285bce6..0a678bb 100644
--- a/doc/derived_measurements.rst
+++ b/doc/derived_measurements.rst
@@ -124,3 +124,58 @@
sites of the coresponding channels according to the following patters:
``"<site>_total_energy"`` and ``"<site>_average_power"``.
+
+FPS / Rendering
+~~~~~~~~~~~~~~~
+
+.. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)
+
+ Produces FPS (frames-per-second) and other dervied statistics from
+ :class:`GfxInfoFramesInstrument` output. This takes several optional
+ parameters in creation:
+
+ :param drop_threshold: FPS in an application, such as a game, which this
+ processor is primarily targeted at, cannot reasonably
+ drop to a very low value. This is specified to this
+ threhold. If an FPS for a frame is computed to be
+ lower than this treshold, it will be dropped on the
+ assumption that frame rednering was suspended by the
+ system (e.g. when idling), or there was some sort of
+ error, and therefore this should be used in
+ performance calculations. defaults to ``5``.
+ :param suffix: The name of the gerated per-frame FPS csv file will be
+ derived from the input frames csv file by appending this
+ suffix. This cannot be specified at the same time as
+ a ``filename``.
+ :param filename: As an alternative to the suffix, a complete file name for
+ FPS csv can be specified. This cannot be used at the same
+ time as the ``suffix``.
+ :param outdir: By default, the FPS csv file will be placed in the same
+ directory as the input frames csv file. This can be changed
+ by specifying an alternate directory here
+
+ .. warning:: Specifying both ``filename`` and ``oudir`` will mean that exactly
+ the same file will be used for FPS output on each invocation of
+ ``process()`` (even for different inputs) resulting in previous
+ results being overwritten.
+
+.. method:: DerivedGfxInfoStats.process(measurement_csv)
+
+ Process the fames csv generated by :class:`GfxInfoFramesInstrument` and
+ returns a list containing exactly three entries: :class:`DerivedMetric`\ s
+ ``fps`` and ``total_frames``, followed by a :class:`MeasurentCsv` containing
+ per-frame FPSs values.
+
+.. method:: DerivedGfxInfoStats.process_raw(gfxinfo_frame_raw_file)
+
+ As input, this takes a single argument, which should be the path to the raw
+ output file of :class:`GfxInfoFramesInstrument`. The returns stats
+ accumulated by gfxinfo. At the time of wrinting, the stats (in order) are:
+ ``janks``, ``janks_pc`` (percentage of all frames),
+ ``render_time_50th_ptile`` (50th percentile, or median, for time to render a
+ frame), ``render_time_90th_ptile``, ``render_time_95th_ptile``,
+ ``render_time_99th_ptile``, ``missed_vsync``, ``hight_input_latency``,
+ ``slow_ui_thread``, ``slow_bitmap_uploads``, ``slow_issue_draw_commands``.
+ Please see the `gfxinfo documentation`_ for details.
+
+.. _gfxinfo documentation: https://developer.android.com/training/testing/performance.html