[ncvisual] add pxoffy+pxoffx fields to ncvisual_options #1682

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 {

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)**,

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'.