add tb_get_cell

Author: adsr

termbox2.h

@@ -65,7 +65,7 @@ extern "C" {
 
 // __ffi_start
 
-#define TB_VERSION_STR "2.6.0-dev"
+#define TB_VERSION_STR "2.7.0-dev"
 
 /* The following compile-time options are supported:
  *
@@ -512,6 +512,25 @@ int tb_set_cell_ex(int x, int y, uint32_t *ch, size_t nch, uintattr_t fg,
     uintattr_t bg);
 int tb_extend_cell(int x, int y, uint32_t ch);
 
+/* Return a pointer to the cell at the specified position.
+ *
+ * Cell memory may be invalid or freed after subsequent library calls, so
+ * callers must copy any data that they need to persist across calls. Modifying
+ * cell memory results in undefined behavior.
+ *
+ * Callers may use pointer math to access cells relative to the requested one.
+ * The cell grid memory layout is a contiguous array indexable by the expression
+ * `(y * width) + x`.
+ *
+ * If `back` is non-zero, return cell from the internal back buffer. Otherwise,
+ * return cell from the front buffer. Note the front buffer is updated on each
+ * call to `tb_present`, whereas the back buffer is updated immediately by
+ * `tb_set_cell` and other functions that modify cell contents.
+ *
+ * If the position is invalid, `TB_ERR_OUT_OF_BOUNDS` is returned.
+ */
+int tb_get_cell(int x, int y, int back, struct tb_cell **cell);
+
 /* Set the input mode. Termbox has two input modes:
  *
  * 1. `TB_INPUT_ESC`
@@ -2505,6 +2524,11 @@ int tb_set_cell_ex(int x, int y, uint32_t *ch, size_t nch, uintattr_t fg,
     return TB_OK;
 }
 
+int tb_get_cell(int x, int y, int back, struct tb_cell **cell) {
+    if_not_init_return();
+    return cellbuf_get(back ? &global.back : &global.front, x, y, cell);
+}
+
 int tb_extend_cell(int x, int y, uint32_t ch) {
     if_not_init_return();
 #ifdef TB_OPT_EGC

tests/test_set_get/expected.ansi

@@ -0,0 +1,24 @@
+#5a
+#5set=0
+#5invalid_get=-9
+#5back_get=0
+#5back_ch=a
+#5back_fg=3
+#5back_bg=0
+#5front1_get=0
+#5front1_ch=
+#5front1_fg=0
+#5front1_bg=0
+#5present=0
+#5front2_get=0
+#5front2_ch=a
+#5front2_fg=3
+#5front2_bg=0
+
+
+
+
+
+
+
+

tests/test_set_get/test.php

@@ -0,0 +1,41 @@
+<?php
+declare(strict_types=1);
+
+$test->ffi->tb_init();
+
+$w = $test->ffi->tb_width();
+$h = $test->ffi->tb_height();
+$green = $test->defines['TB_GREEN'];
+$cellp = $test->ffi->new('struct tb_cell *');
+$back = 1;
+$front = 0;
+
+$result = [];
+
+$result['set'] = $test->ffi->tb_set_cell(0, 0, ord('a'), $green, 0); // 0 (TB_OK)
+
+$result['invalid_get'] = $test->ffi->tb_get_cell(-1, -1, $back, FFI::addr($cellp)); // -9 (TB_ERR_OUT_OF_BOUNDS)
+
+$result['back_get'] = $test->ffi->tb_get_cell(0, 0, $back, FFI::addr($cellp)); // 0 (TB_OK)
+$result['back_ch'] = chr($cellp->ch); // 'a'
+$result['back_fg'] = $cellp->fg; // 3 (green)
+$result['back_bg'] = $cellp->bg; // 0
+
+$result['front1_get'] = $test->ffi->tb_get_cell(0, 0, $front, FFI::addr($cellp));
+$result['front1_ch'] = chr($cellp->ch); // <space> (front buffer empty)
+$result['front1_fg'] = $cellp->fg; // 0
+$result['front1_bg'] = $cellp->bg; // 0
+
+$result['present'] = $test->ffi->tb_present(); // 0 (TB_OK) (front buffer now populated)
+
+$result['front2_get'] = $test->ffi->tb_get_cell(0, 0, $front, FFI::addr($cellp)); // 0 (TB_OK)
+$result['front2_ch'] = chr($cellp->ch); // 'a'
+$result['front2_fg'] = $cellp->fg; // 3 (green)
+$result['front2_bg'] = $cellp->bg; // 0
+
+$y = 1;
+foreach ($result as $k => $v) $test->ffi->tb_printf(0, $y++, 0, 0, '%s=%s', $k, "$v");
+
+$test->ffi->tb_present();
+
+$test->screencap();