add ncstats to USAGE.md

NEWS.md

@@ -1,6 +1,13 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 1.7.6 (not yet released)
+  * `ncstats` added the new stats `writeout_ns`, `writeout_min_ns`, and
+    `writeout_max_ns`. The `render_*ns` stats now only cover the rendering
+    and rasterizing process. The `writeout*ns` stats cover the time spent
+    writing data out to the terminal. `notcurses_render()` involves both of
+    these processes.
+
 * 1.7.5 (2020-09-29)
   * `ncreel_destroy()` now returns `void` rather than `int`.
   * `nctablet_ncplane()` has been renamed `nctablet_plane()`.

USAGE.md

@@ -12,6 +12,7 @@ version 2, notcurses will honor Semantic Versioning.
 * [Widgets](#widgets) ([Readers](#readers))
 * [Channels](#channels)
 * [Visuals](#visuals) ([QR codes](#qrcodes)) ([Multimedia](#multimedia)) ([Pixels](#pixels))
+* [Stats](#stats)
 * [C++](#c++)
 
 A full API reference [is available](https://nick-black.com/notcurses/). Manual
@@ -2809,6 +2810,47 @@ ncpixel_set_rgb8(uint32_t* pixel, int r, int g, int b){
 }
 ```
 
+## Stats
+
+Notcurses supplies a number of stats related to performance and state.
+Cumulative stats can be reset at any time.
+
+```c
+typedef struct ncstats {
+  // purely increasing stats
+  uint64_t renders;          // number of successful notcurses_render() runs
+  uint64_t failed_renders;   // number of aborted renders, should be 0
+  uint64_t render_bytes;     // bytes emitted to ttyfp
+  int64_t render_max_bytes;  // max bytes emitted for a frame
+  int64_t render_min_bytes;  // min bytes emitted for a frame
+  uint64_t render_ns;        // nanoseconds spent in render+raster
+  int64_t render_max_ns;     // max ns spent in render+raster for a frame
+  int64_t render_min_ns;     // min ns spent in render+raster for a frame
+  uint64_t writeout_ns;      // nanoseconds spent writing frames to terminal
+  int64_t writeout_max_ns;   // max ns spent writing out a frame
+  int64_t writeout_min_ns;   // min ns spent writing out a frame
+  uint64_t cellelisions;     // cells we elided entirely thanks to damage maps
+  uint64_t cellemissions;    // total number of cells emitted to terminal
+  uint64_t fgelisions;       // RGB fg elision count
+  uint64_t fgemissions;      // RGB fg emissions
+  uint64_t bgelisions;       // RGB bg elision count
+  uint64_t bgemissions;      // RGB bg emissions
+  uint64_t defaultelisions;  // default color was emitted
+  uint64_t defaultemissions; // default color was elided
+
+  // current state -- these can decrease
+  uint64_t fbbytes;          // total bytes devoted to all active framebuffers
+  unsigned planes;           // number of planes currently in existence
+} ncstats;
+
+// Acquire an atomic snapshot of the notcurses object's stats.
+void notcurses_stats(const struct notcurses* nc, ncstats* stats);
+
+// Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
+void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
+```
+
+
 ## C++
 
 Marek Habersack has contributed (and maintains) C++ wrappers installed to