From 4985bf1f3f946a3f12f2ff35a518870602d5041c Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Sun, 23 Jan 2022 21:45:06 -0500
Subject: [PATCH] doc ncchannels_channels() and ncchannels_set_channels()

---
 USAGE.md                             | 15 +++++++++++++++
 doc/man/man3/notcurses_cell.3.md     |  4 ++++
 doc/man/man3/notcurses_channels.3.md | 11 +++++++++++
 3 files changed, 30 insertions(+)

diff --git a/USAGE.md b/USAGE.md
index 89efb7109..ba9841a60 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -3156,6 +3156,21 @@ ncchannel_set_default(uint32_t* channel){
   return *channel &= ~NC_BGDEFAULT_MASK;
 }
 
+// Extract the background alpha and coloring bits from a 64-bit channel pair.
+static inline uint64_t
+ncchannels_channels(uint64_t channels){
+  return ncchannels_bchannel(channels) |
+         ((uint64_t)ncchannels_fchannel(channels) << 32u);
+}
+
+// Set the alpha and coloring bits of a channel pair from another channel pair.
+static inline uint64_t
+ncchannels_set_channels(uint64_t* dst, uint64_t channels){
+  ncchannels_set_bchannel(dst, channels & 0xffffffffull);
+  ncchannels_set_fchannel(dst, (channels >> 32u) & 0xffffffffull);
+  return *dst;
+}
+
 // Extract the background alpha and coloring bits from a 64-bit channel
 // pair as a single 32-bit value.
 static inline unsigned
diff --git a/doc/man/man3/notcurses_cell.3.md b/doc/man/man3/notcurses_cell.3.md
index 9a886cd02..9dc194324 100644
--- a/doc/man/man3/notcurses_cell.3.md
+++ b/doc/man/man3/notcurses_cell.3.md
@@ -78,10 +78,14 @@ typedef struct nccell {
 
 **char* nccell_extract(const struct ncplane* ***n***, const nccell* ***c***, uint16_t* ***stylemask***, uint64_t* ***channels***);**
 
+**uint64_t nccell_channels(const nccell* ***c***);**
+
 **uint32_t nccell_bchannel(const nccell* ***c***);**
 
 **uint32_t nccell_fchannel(const nccell* ***c***);**
 
+**uint64_t nccell_set_channels(nccell* ***c***, uint64_t ***channels***);**
+
 **uint64_t nccell_set_bchannel(nccell* ***c***, uint32_t ***channel***);**
 
 **uint64_t nccell_set_fchannel(nccell* ***c***, uint32_t ***channel***);**
diff --git a/doc/man/man3/notcurses_channels.3.md b/doc/man/man3/notcurses_channels.3.md
index e2de43cef..11932bce1 100644
--- a/doc/man/man3/notcurses_channels.3.md
+++ b/doc/man/man3/notcurses_channels.3.md
@@ -89,10 +89,21 @@ notcurses_channels - operations on notcurses channels
 
 **int ncchannels_set_bg_palindex(uint64_t* ***channels***, unsigned ***idx***);**
 
+**uint64_t ncchannels_set_channels(uint64_t* ***dst***, uint64_t ***channels***);**
+
+**uint64_t ncchannels_channels(uint64_t ***channels***);**
+
 **uint64_t ncchannels_combine(uint32_t ***fchan***, uint32_t ***bchan***);**
 
 # DESCRIPTION
 
+Channels ought not be manually manipulated. They contain several bits used
+"behind the scenes", and e.g. direct assignment is likely to lead to strange
+and infrequent failures. To assign one channel pair to another, use
+**ncchannels_set_channels**. To assign a channel to a channel pair's
+foreground, use **ncchannels_set_fchannel**. To assign a channel to a channel
+pair's background, use **ncchannels_set_bchannel**.
+
 **ncchannel_palindex** extracts the palette index from a channel. The channel
 must be palette-indexed, or the return value is meaningless. Verify palette
 indexing with **ncchannel_palindex_p**. A channel can be set to palette