john/McRogueFace
1
0
Fork 0
Code Issues 57 Pull requests Projects Releases Wiki Activity

feat(grid): numpy buffer views for ColorLayer/TileLayer via layer.edit(); closes #335

Browse source 
Implements the #328 bulk-edit convention for grid layers. Writable zero-copy
views of layer data are exposed ONLY through a context manager:

    with layer.edit() as view:        # ColorLayer -> (h, w, 4) uint8
        np.asarray(view)[...] = ...    # TileLayer  -> (h, w) int32 (-1 = no tile)
    # on __exit__ the whole layer is conservatively invalidated (markDirty),
    # so the edit re-renders.

Both layers already stored dense, contiguous, row-major data (std::vector<
sf::Color> / std::vector<int>; render caches chunk separately), so the views are
true zero-copy aliases. A new internal _LayerEdit type is the buffer exporter
(bf_getbuffer) and the context manager (__enter__ returns memoryview(self),
__exit__ calls GridLayer::markDirty()); it is not directly instantiable. The
conservative whole-layer invalidation on exit means no change-tracking is
needed, and it composes with the #351 render early-out (markDirty bumps
content_generation).

Independent of GridData SoA (#332): these are the render layers, not the logic
grid. A contiguous walkable/transparent view now has its storage prerequisite
from #332 but remains a separate follow-up.

Regression test issue_335_layer_edit_test.py: buffer shape/format/readonly,
zero-copy writeback both directions, the -1 tile sentinel, optional numpy
aliasing, and a screenshot check that __exit__ actually re-renders. API-surface
golden re-baselined (two new edit methods); docs/stubs regenerated; frozen
docstring gate 100%. Suite 312/312.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
John McCardle 2026-07-11 02:04:42 -04:00
commit ad223b1ac0
9 changed files with 344 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/API_REFERENCE_DYNAMIC.md
View file

@ -1,6 +1,6 @@
# McRogueFace API Reference
*Generated on 2026-07-02 20:21:29*
*Generated on 2026-07-11 02:02:32*
*This documentation was dynamically generated from the compiled module.*
@ -1276,6 +1276,15 @@ Note:
- `discovered`: Color for previously seen cells
- `unknown`: Color for never-seen cells
#### `edit() -> context manager`
Context manager yielding a zero-copy, writable view of the layer's RGBA data with shape (height, width, 4), dtype uint8. Writes to the view alias the layer's storage (no copy). On exit the whole layer is invalidated and re-rendered.
Note:
Use as `with layer.edit() as view:` -- e.g. np.asarray(view)[...] = ....
**See also:** [Bulk-edit convention](#328) (docs/api-stability.md)
#### `fill(color: Color) -> None`
Fill the entire layer with the specified color.
@ -4526,6 +4535,15 @@ Get the tile index at a cell position. Returns -1 if no tile is set.
**Raises:** IndexError: If coordinates are out of bounds
#### `edit() -> context manager`
Context manager yielding a zero-copy, writable view of the layer's tile indices with shape (height, width), dtype int32 (-1 = no tile). Writes to the view alias the layer's storage (no copy). On exit the whole layer is invalidated and re-rendered.
Note:
Use as `with layer.edit() as view:` -- e.g. np.asarray(view)[...] = ....
**See also:** [Bulk-edit convention](#328) (docs/api-stability.md)
#### `fill(index: int) -> None`
Fill the entire layer with the specified tile index.

20
docs/api_reference_dynamic.html
View file

@ -108,7 +108,7 @@
<body>
<div class="container">
<h1>McRogueFace API Reference</h1>
<p><em>Generated on 2026-07-02 20:21:29</em></p>
<p><em>Generated on 2026-07-11 02:02:32</em></p>
<p><em>This documentation was dynamically generated from the compiled module.</em></p>
<p><strong>Threading:</strong> any access to mcrfpy objects from a non-main thread must happen inside <code>with mcrfpy.lock():</code>; behavior outside the lock is undefined. See <a href="threading-model.md">docs/threading-model.md</a>.</p>
@ -1417,6 +1417,15 @@ Note:</p>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">edit() -> context manager</code></h5>
<p>Context manager yielding a zero-copy, writable view of the layer&#x27;s RGBA data with shape (height, width, 4), dtype uint8. Writes to the view alias the layer&#x27;s storage (no copy). On exit the whole layer is invalidated and re-rendered.
Note:
Use as `with layer.edit() as view:` -- e.g. np.asarray(view)[...] = ....
<p class="see-also">See also: <a href="#328">Bulk-edit convention</a></p> (docs/api-stability.md)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(color: Color) -> None</code></h5>
<p>Fill the entire layer with the specified color.</p>
@ -4775,6 +4784,15 @@ Note:</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: If coordinates are out of bounds</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">edit() -> context manager</code></h5>
<p>Context manager yielding a zero-copy, writable view of the layer&#x27;s tile indices with shape (height, width), dtype int32 (-1 = no tile). Writes to the view alias the layer&#x27;s storage (no copy). On exit the whole layer is invalidated and re-rendered.
Note:
Use as `with layer.edit() as view:` -- e.g. np.asarray(view)[...] = ....
<p class="see-also">See also: <a href="#328">Bulk-edit convention</a></p> (docs/api-stability.md)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(index: int) -> None</code></h5>
<p>Fill the entire layer with the specified tile index.</p>

28
docs/mcrfpy.3
View file

@ -14,11 +14,11 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "MCRFPY" "3" "2026-07-02" "McRogueFace 0.2.8-6-g19d80b4" ""
.TH "MCRFPY" "3" "2026-07-11" "McRogueFace 0.2.8-32-g2ceb18e" ""
.hy
.SH McRogueFace API Reference
.PP
\f[I]Generated on 2026-07-02 20:21:29\f[R]
\f[I]Generated on 2026-07-11 02:02:32\f[R]
.PP
\f[I]This documentation was dynamically generated from the compiled
module.\f[R]
@ -1477,6 +1477,18 @@ Note:
\f[V]visible\f[R]: Color for currently visible cells -
\f[V]discovered\f[R]: Color for previously seen cells -
\f[V]unknown\f[R]: Color for never-seen cells
.SS \f[V]edit() -> context manager\f[R]
.PP
Context manager yielding a zero-copy, writable view of the layer\[cq]s
RGBA data with shape (height, width, 4), dtype uint8.
Writes to the view alias the layer\[cq]s storage (no copy).
On exit the whole layer is invalidated and re-rendered.
.PP
Note: Use as \f[V]with layer.edit() as view:\f[R] \[en]
e.g.\ np.asarray(view)[\&...]
= \&....
.PP
\f[B]See also:\f[R] Bulk-edit convention (docs/api-stability.md)
.SS \f[V]fill(color: Color) -> None\f[R]
.PP
Fill the entire layer with the specified color.
@ -4870,6 +4882,18 @@ Vector; or pass x and y separately
\f[B]Returns:\f[R] Tile index at the specified cell, or -1 if empty
.PP
\f[B]Raises:\f[R] IndexError: If coordinates are out of bounds
.SS \f[V]edit() -> context manager\f[R]
.PP
Context manager yielding a zero-copy, writable view of the layer\[cq]s
tile indices with shape (height, width), dtype int32 (-1 = no tile).
Writes to the view alias the layer\[cq]s storage (no copy).
On exit the whole layer is invalidated and re-rendered.
.PP
Note: Use as \f[V]with layer.edit() as view:\f[R] \[en]
e.g.\ np.asarray(view)[\&...]
= \&....
.PP
\f[B]See also:\f[R] Bulk-edit convention (docs/api-stability.md)
.SS \f[V]fill(index: int) -> None\f[R]
.PP
Fill the entire layer with the specified tile index.