document new function ncplane_abs_yx() #1286

NEWS.md

@@ -8,6 +8,9 @@ rearrangements of Notcurses.
   * `ncplane_putstr_yx()`, `ncplane_putstr_stained()`, and
     `ncplane_putnstr_yx()` now return the number of columns output, as
     long documented (they were mistakenly returning the number of bytes).
+  * `ncplane_abs_yx()` has been added, returning the absolute coordinates of
+    the plane's origin (i.e. coordinates relative to its pile). This call is
+    O(N) on the binding depth of the plane in question.
 
 * 2.1.4 (2021-01-03):
   * Direct mode now supports `NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS`, and by

USAGE.md

@@ -802,12 +802,16 @@ ncplane_resize_simple(struct ncplane* n, int ylen, int xlen){
 // standard plane.
 int ncplane_move_yx(struct ncplane* n, int y, int x);
 
-// Get the origin of this plane relative to the standard plane, or the plane to
-// which it is bound (if it is bound to a plane).
+// Get the origin of plane 'n' relative to its bound plane, or its pile (if
+// 'n' is a root plane).
 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);
 int ncplane_y(const struct ncplane* n);
 int ncplane_x(const struct ncplane* n);
 
+// Get the origin of plane 'n' relative to its pile. This is O(N) on the
+// binding depth of 'n'. Either or both of 'x' and y' may be NULL.
+void ncplane_abs_yx(const struct ncplane* n, int* y, int* x);
+
 // Return the dimensions of this ncplane.
 void ncplane_dim_yx(struct ncplane* n, int* restrict rows, int* restrict cols);
 
@@ -826,7 +830,7 @@ ncplane_dim_x(const struct ncplane* n){
 }
 
 // provided a coordinate relative to the origin of 'src', map it to the same
-// absolute coordinate relative to thte origin of 'dst'. either or both of 'y'
+// absolute coordinate relative to the origin of 'dst'. either or both of 'y'
 // and 'x' may be NULL. if 'dst' is NULL, it is taken to be the standard plane.
 void ncplane_translate(const struct ncplane* src, const struct ncplane* dst,
                        int* restrict y, int* restrict x);

doc/man/man3/notcurses_plane.3.md

@@ -61,6 +61,8 @@ typedef struct ncplane_options {
 
 **int ncplane_x(const struct ncplane* ***n***);**
 
+**void ncplane_abs_yx(const struct ncplane* ***n***, int* ***y***, int* ***x***);**
+
 **struct ncplane* ncplane_parent(struct ncplane* ***n***);**
 
 **const struct ncplane* ncplane_parent_const(const struct ncplane* ***n***);**
@@ -230,6 +232,12 @@ to multiple ncplanes. So long as all threads are readers, multiple threads may
 work with a single ncplane. A reading function is any which accepts a **const
 struct ncplane**.
 
+**ncplane_yx** returns the coordinates of the specified plane's origin, relative
+to the plane to which it is bound. Either or both of ***y*** and ***x*** may
+be **NULL**. **ncplane_y** and **ncplane_x** allow a single component of this
+location to be retrieved. **ncplane_abs_yx** returns the coordinates of the
+specified plane's origin relative to its pile.
+
 **ncplane_translate** translates coordinates expressed relative to the plane
 ***src***, and writes the coordinates of that cell relative to ***dst***. The cell
 need not intersect with ***dst***, though this will yield coordinates which are

include/notcurses/notcurses.h

@@ -1164,7 +1164,7 @@ API struct ncplane* ncplane_reparent_family(struct ncplane* n, struct ncplane* n
 API struct ncplane* ncplane_dup(const struct ncplane* n, void* opaque);
 
 // provided a coordinate relative to the origin of 'src', map it to the same
-// absolute coordinate relative to thte origin of 'dst'. either or both of 'y'
+// absolute coordinate relative to the origin of 'dst'. either or both of 'y'
 // and 'x' may be NULL. if 'dst' is NULL, it is taken to be the standard plane.
 API void ncplane_translate(const struct ncplane* src, const struct ncplane* dst,
                            int* RESTRICT y, int* RESTRICT x);
@@ -1311,12 +1311,16 @@ API int ncplane_base(struct ncplane* n, nccell* c);
 // standard plane.
 API int ncplane_move_yx(struct ncplane* n, int y, int x);
 
-// Get the origin of this plane relative to the standard plane, or the plane to
-// which it is bound (if it is bound to a plane).
+// Get the origin of plane 'n' relative to its bound plane, or pile (if 'n' is
+// a root plane). To get absolute coordinates, use ncplane_abs_yx().
 API void ncplane_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x);
 API int ncplane_y(const struct ncplane* n);
 API int ncplane_x(const struct ncplane* n);
 
+// Get the origin of plane 'n' relative to its pile. This is O(N) on the
+// binding depth of 'n'. Either or both of 'x' and y' may be NULL.
+API void ncplane_abs_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x);
+
 // Get the plane to which the plane 'n' is bound, if any.
 API struct ncplane* ncplane_parent(struct ncplane* n);
 API const struct ncplane* ncplane_parent_const(const struct ncplane* n);