From b4f1065f69f7d062ef77b257ed31fc42b3633df9 Mon Sep 17 00:00:00 2001 From: nick black Date: Sun, 4 Oct 2020 10:17:57 -0400 Subject: [PATCH] declare notcurses_render_to_buffer() #214 --- NEWS.md | 2 ++ USAGE.md | 6 ++++++ doc/man/man3/notcurses_render.3.md | 8 ++++++++ include/notcurses/notcurses.h | 6 ++++++ python/src/notcurses/build_notcurses.py | 3 ++- 5 files changed, 24 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index 0f2ac67e1..99f5fc3ac 100644 --- a/NEWS.md +++ b/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`. diff --git a/USAGE.md b/USAGE.md index a3d0dc45d..77cd99059 100644 --- a/USAGE.md +++ b/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); diff --git a/doc/man/man3/notcurses_render.3.md b/doc/man/man3/notcurses_render.3.md index 0148affec..cf0c7e383 100644 --- a/doc/man/man3/notcurses_render.3.md +++ b/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 diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 070735d3e..6f3bcef1b 100644 --- a/include/notcurses/notcurses.h +++ b/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); diff --git a/python/src/notcurses/build_notcurses.py b/python/src/notcurses/build_notcurses.py index 065bf056e..707118975 100644 --- a/python/src/notcurses/build_notcurses.py +++ b/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);