From 8a0240e7134e72fd03a08507c457b15f793b339d Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Tue, 31 Mar 2015 16:45:44 -0400
Subject: [PATCH] Document dfhack.penarray

---
 Lua API.rst | 37 +++++++++++++++++++++++++++++++++++++
 NEWS        |  3 ++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/Lua API.rst b/Lua API.rst
index a616ac08b..60906edc6 100644
--- a/Lua API.rst	
+++ b/Lua API.rst	
@@ -1765,6 +1765,43 @@ Supported callbacks and fields are:
   ``dfhack.gui.getSelected...`` function.
 
 
+PenArray class
+--------------
+
+Screens that require significant computation in their onRender() method can use
+a ``dfhack.penarray`` instance to cache their output.
+
+* ``dfhack.penarray.new(w, h)``
+
+  Creates a new penarray instance with an internal buffer of ``w * h`` tiles.
+  These dimensions currently cannot be changed after a penarray is instantiated.
+
+* ``penarray:clear()``
+
+  Clears the internal buffer, similar to ``dfhack.screen.clear()``.
+
+* ``penarray:get_dims()``
+
+  Returns the x and y dimensions of the internal buffer.
+
+* ``penarray:get_tile(x, y)``
+
+  Returns a pen corresponding to the tile at (``x``, ``y``) in the internal buffer.
+  Note that indices are 0-based.
+
+* ``penarray:set_tile(x, y, pen)``
+
+  Sets the tile at (``x``, ``y``) in the internal buffer to the pen given.
+
+* ``penarray:draw(x, y, w, h, bufferx, buffery)``
+
+  Draws the contents of the internal buffer, beginning at
+  (``bufferx``, ``buffery``) and spanning ``w`` columns and ``h`` rows, to the
+  screen starting at (``x``, ``y``). Any invalid screen and buffer coordinates
+  are skipped.
+
+  ``bufferx`` and ``buffery`` default to 0.
+
 Filesystem module
 -----------------
 
diff --git a/NEWS b/NEWS
index a942cf1eb..3d5be83aa 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,6 @@
 DFHack Future
     Internals
+        A method for caching screen output is now available to Lua (and C++)
     Lua
     New internal commands
     New plugins
@@ -7,8 +8,8 @@ DFHack Future
     New tweaks
     New features
     Fixes
-    Removed
     Misc Improvements
+    Removed
 
 DFHack 0.40.24-r3
     Internals