From 48fc933fbf56a04e72e786ec6200011a037c9135 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Fri, 8 Oct 2021 01:00:56 -0400
Subject: [PATCH] [ncvisual] add pxoffy+pxoffx fields to ncvisual_options #1682

---
 USAGE.md                           | 7 +++++++
 doc/man/man3/notcurses_visual.3.md | 9 +++++++++
 include/notcurses/notcurses.h      | 8 +++++++-
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/USAGE.md b/USAGE.md
index 37e8464150..04bd641510 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -3378,6 +3378,13 @@ struct ncvisual_options {
   ncblitter_e blitter; // glyph set to use (maps input to output cells)
   uint64_t flags; // bitmask over NCVISUAL_OPTION_*
   uint32_t transcolor; // used only if NCVISUAL_OPTION_ADDALPHA is set
+  // pixel offsets within the cell. if NCBLIT_PIXEL is used, the bitmap will
+  // be drawn offset from the upper-left cell's origin by these amounts. it is
+  // an error if either number exceeds the cell-pixel geometry in its
+  // dimension. if NCBLIT_PIXEL is not used, these fields are ignored.
+  // this functionality can be used for smooth bitmap movement.
+  // FIXME not yet implemented.
+  unsigned pxoffy, pxoffx;
 };
 
 typedef enum {
diff --git a/doc/man/man3/notcurses_visual.3.md b/doc/man/man3/notcurses_visual.3.md
index e5f6aabc3b..a36cba34d4 100644
--- a/doc/man/man3/notcurses_visual.3.md
+++ b/doc/man/man3/notcurses_visual.3.md
@@ -47,6 +47,7 @@ struct ncvisual_options {
   ncblitter_e blitter; // glyph set to use
   uint64_t flags; // bitmask over NCVISUAL_OPTION_*
   uint32_t transcolor; // use this color for ADDALPHA
+  unsigned pxoffy, pxoffx; // pixel offset from origin
 };
 
 typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
@@ -286,6 +287,12 @@ Only one bitmap can be blitted onto a plane at a time (but multiple planes
 with bitmaps may be visible); blitting a second to the same plane will delete
 the original.
 
+**pxoffy** and **pxoffx** can specify an offset from the origin of the upper
+left cell. This can be used for absolute positioning of a bitmap, or for
+smooth movement of same. It is an error if **pxoffy** exceeds the cell height
+in pixels, or **pxoffx** exceeds the cell width in pixels. If
+**NCBLIT_PIXEL** is not used, these fields are ignored.
+
 # RETURN VALUES
 
 **ncvisual_from_file** returns an **ncvisual** object on success, or **NULL**
@@ -371,6 +378,8 @@ Multiple threads may not currently call **ncvisual_render** concurrently
 using the same **ncvisual**, even if targeting distinct **ncplane**s. This
 will likely change in the future.
 
+**pxoffy** and **pxoffx** are not yet implemented.
+
 # SEE ALSO
 
 **notcurses(3)**,
diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h
index 5b2cc1c006..e23ac32667 100644
--- a/include/notcurses/notcurses.h
+++ b/include/notcurses/notcurses.h
@@ -2804,7 +2804,6 @@ API ALLOC struct ncvisual* ncvisual_from_plane(const struct ncplane* n,
 #define NCVISUAL_OPTION_ADDALPHA      0x0010ull // transcolor is in effect
 #define NCVISUAL_OPTION_CHILDPLANE    0x0020ull // interpret n as parent
 #define NCVISUAL_OPTION_NOINTERPOLATE 0x0040ull // non-interpolative scaling
-                                                // 0x0080 is used internally
 
 struct ncvisual_options {
   // if no ncplane is provided, one will be created using the exact size
@@ -2834,6 +2833,13 @@ struct ncvisual_options {
   ncblitter_e blitter; // glyph set to use (maps input to output cells)
   uint64_t flags; // bitmask over NCVISUAL_OPTION_*
   uint32_t transcolor; // treat this color as transparent under NCVISUAL_OPTION_ADDALPHA
+  // pixel offsets within the cell. if NCBLIT_PIXEL is used, the bitmap will
+  // be drawn offset from the upper-left cell's origin by these amounts. it is
+  // an error if either number exceeds the cell-pixel geometry in its
+  // dimension. if NCBLIT_PIXEL is not used, these fields are ignored.
+  // this functionality can be used for smooth bitmap movement.
+  // FIXME not yet implemented.
+  unsigned pxoffy, pxoffx;
 };
 
 // Create an RGBA flat array from the selected region of the ncplane 'nc'.