declare notcurses_render_to_buffer() #214

NEWS.md

@@ -7,6 +7,8 @@ rearrangements of Notcurses.
     and rasterizing process. The `writeout*ns` stats cover the time spent
     writing data out to the terminal. `notcurses_render()` involves both of
     these processes.
+  * `notcurses_render_to_buffer()` has been added, allowing user control of
+    the process of writing frames out to the terminal.
 
 * 1.7.5 (2020-09-29)
   * `ncreel_destroy()` now returns `void` rather than `int`.

USAGE.md

@@ -171,6 +171,12 @@ updated to reflect the changes:
 // successful call to notcurses_render().
 int notcurses_render(struct notcurses* nc);
 
+// Perform the rendering and rasterization portion of notcurses_render(), but
+// do not write the resulting buffer out to the terminal. Using this function,
+// the user can control the writeout process, and render a second frame while
+// writing another. The returned buffer must be freed by the caller.
+int notcurses_render_to_buffer(struct notcurses* nc, char** buf, size_t buflen);
+
 // Write the last rendered frame, in its entirety, to 'fp'. If
 // notcurses_render() has not yet been called, nothing will be written.
 int notcurses_render_to_file(struct notcurses* nc, FILE* fp);

doc/man/man3/notcurses_render.3.md

@@ -16,6 +16,8 @@ notcurses_render - sync the physical display to the virtual ncplanes
 
 **int notcurses_render_to_file(struct notcurses* nc, FILE* fp);**
 
+**int notcurses_render_to_buffer(struct notcurses* nc, char** buf, size_t buflen);**
+
 # DESCRIPTION
 
 **notcurses_render** syncs the physical display to the context's prepared
@@ -29,6 +31,12 @@ While **notcurses_render** is called, you **must not call any other functions
 on the same notcurses context**, with the one exception of **notcurses_getc**
 (and its input-related helpers; see **notcurses_input(3)**.).
 
+**notcurses_render_to_buffer** performs the render and raster processes of
+**notcurses_render**, but does not write the resulting buffer to the
+terminal. The user is responsible for writing the buffer to the terminal in
+its entirety. If there is an error, subsequent frames will be out of sync,
+and **notcurses_refresh(3)** must be called.
+
 A render operation consists of two logical phases: generation of the rendered
 scene, and blitting this scene to the terminal (these two phases might actually
 be interleaved, streaming the output as it is rendered). Frame generation

include/notcurses/notcurses.h

@@ -847,6 +847,12 @@ API int notcurses_stop(struct notcurses* nc);
 // successful call to notcurses_render().
 API int notcurses_render(struct notcurses* nc);
 
+// Perform the rendering and rasterization portion of notcurses_render(), but
+// do not write the resulting buffer out to the terminal. Using this function,
+// the user can control the writeout process, and render a second frame while
+// writing another. The returned buffer must be freed by the caller.
+API int notcurses_render_to_buffer(struct notcurses* nc, char** buf, size_t buflen);
+
 // Write the last rendered frame, in its entirety, to 'fp'. If
 // notcurses_render() has not yet been called, nothing will be written.
 API int notcurses_render_to_file(struct notcurses* nc, FILE* fp);

python/src/notcurses/build_notcurses.py

@@ -52,7 +52,8 @@ struct notcurses* notcurses_init(const notcurses_options*, FILE*);
 void notcurses_version_components(int* major, int* minor, int* patch, int* tweak);
 int notcurses_lex_margins(const char* op, notcurses_options* opts);
 int notcurses_stop(struct notcurses*);
-int notcurses_render(struct notcurses*);
+int notcurses_render(struct notcurses* nc);
+int notcurses_render_to_buffer(struct notcurses* nc, char** buf, size_t buflen);
 int notcurses_render_to_file(struct notcurses* nc, FILE* fp);
 struct ncplane* notcurses_stdplane(struct notcurses*);
 const struct ncplane* notcurses_stdplane_const(const struct notcurses* nc);