From 3b169dfa31d0b999f95f63271aad2a79a847b9a4 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Wed, 7 Apr 2021 20:28:21 -0400
Subject: [PATCH] [notcurses.h] improve ncvisual_from_rgba() docs #1488

---
 USAGE.md                      | 14 +++++++-------
 include/notcurses/notcurses.h | 10 +++++-----
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/USAGE.md b/USAGE.md
index 6703f243b..f83782650 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -3000,13 +3000,13 @@ constructed directly from RGBA or BGRA 8bpc memory:
 
 ```c
 // Prepare an ncvisual, and its underlying plane, based off RGBA content in
-// memory at 'rgba'. 'rgba' must be a flat array of 32-bit 8bpc RGBA pixels.
-// These must be arranged in 'rowstride' lines, where the first 'cols' * 4b
-// are actual data. There must be 'rows' lines. The total size of 'rgba'
-// must thus be at least (rows * rowstride) bytes, of which (rows * cols * 4)
-// bytes are actual data. The resulting plane will be ceil('rows'/2)x'cols'.
-struct ncvisual* ncvisual_from_rgba(struct notcurses* nc, const void* rgba,
-                                    int rows, int rowstride, int cols);
+// memory at 'rgba'. 'rgba' is laid out as 'rows' lines, each of which is
+// 'rowstride' bytes in length. Each line has 'cols' 32-bit 8bpc RGBA pixels
+// followed by possible padding (there will be 'rowstride' - 'cols' * 4 bytes
+// of padding). The total size of 'rgba' is thus (rows * rowstride) bytes, of
+// which (rows * cols * 4) bytes are actual non-padding data.
+struct ncvisual* ncvisual_from_rgba(const void* rgba, int rows,
+                                    int rowstride, int cols);
 
 // ncvisual_from_rgba(), but for BGRA.
 struct ncvisual* ncvisual_from_bgra(struct notcurses* nc, const void* bgra,
diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h
index b47aae31c..bcde3b7ed 100644
--- a/include/notcurses/notcurses.h
+++ b/include/notcurses/notcurses.h
@@ -2391,11 +2391,11 @@ ncplane_double_box_sized(struct ncplane* n, uint32_t styles, uint64_t channels,
 API ALLOC struct ncvisual* ncvisual_from_file(const char* file);
 
 // Prepare an ncvisual, and its underlying plane, based off RGBA content in
-// memory at 'rgba'. 'rgba' must be a flat array of 32-bit 8bpc RGBA pixels.
-// These must be arranged in 'rowstride' lines, where the first 'cols' * 4b
-// are actual data. There must be 'rows' lines. The total size of 'rgba'
-// must thus be at least (rows * rowstride) bytes, of which (rows * cols * 4)
-// bytes are actual data. Resulting planes are ceil('rows' / 2) x 'cols'.
+// memory at 'rgba'. 'rgba' is laid out as 'rows' lines, each of which is
+// 'rowstride' bytes in length. Each line has 'cols' 32-bit 8bpc RGBA pixels
+// followed by possible padding (there will be 'rowstride' - 'cols' * 4 bytes
+// of padding). The total size of 'rgba' is thus (rows * rowstride) bytes, of
+// which (rows * cols * 4) bytes are actual non-padding data.
 API ALLOC struct ncvisual* ncvisual_from_rgba(const void* rgba, int rows,
                                               int rowstride, int cols);