summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlexander Gavrilov2012-06-13 11:00:54 +0400
committerAlexander Gavrilov2012-06-13 11:00:54 +0400
commit24e2c151136fc7d565f9f9babcf24b199eb6c6f3 (patch)
treeb69a6e0feee17625ab83cf3822ba57b2d7870fec
parent6ca5a0300840dfc710ae6ab1dfb35fd78adff1dc (diff)
downloaddfhack-24e2c151136fc7d565f9f9babcf24b199eb6c6f3.tar.gz
dfhack-24e2c151136fc7d565f9f9babcf24b199eb6c6f3.tar.bz2
dfhack-24e2c151136fc7d565f9f9babcf24b199eb6c6f3.tar.xz
Enhance docs on bitfield refs to cover a question raised on chat recently.
-rw-r--r--LUA_API.rst11
-rw-r--r--Lua API.html11
2 files changed, 19 insertions, 3 deletions
diff --git a/LUA_API.rst b/LUA_API.rst
index 9fb37375..0736b02b 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -219,12 +219,21 @@ Bitfield references
-------------------
Bitfields behave like special fixed-size containers.
-The ``_enum`` property points to the bitfield type.
+Consider them to be something in between structs and
+fixed-size vectors.
+The ``_enum`` property points to the bitfield type.
Numerical indices correspond to the shift value,
and if a subfield occupies multiple bits, the
``ipairs`` order would have a gap.
+Since currently there is no API to allocate a bitfield
+object fully in GC-managed lua heap, consider using the
+lua table assignment feature outlined below in order to
+pass bitfield values to dfhack API functions that need
+them, e.g. ``matinfo:matches{metal=true}``.
+
+
Named types
===========
diff --git a/Lua API.html b/Lua API.html
index 1576652d..568090a7 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -534,10 +534,17 @@ use <tt class="docutils literal">#ref</tt>, or just <tt class="docutils literal"
<div class="section" id="bitfield-references">
<h3><a class="toc-backref" href="#id6">Bitfield references</a></h3>
<p>Bitfields behave like special fixed-size containers.
-The <tt class="docutils literal">_enum</tt> property points to the bitfield type.</p>
-<p>Numerical indices correspond to the shift value,
+Consider them to be something in between structs and
+fixed-size vectors.</p>
+<p>The <tt class="docutils literal">_enum</tt> property points to the bitfield type.
+Numerical indices correspond to the shift value,
and if a subfield occupies multiple bits, the
<tt class="docutils literal">ipairs</tt> order would have a gap.</p>
+<p>Since currently there is no API to allocate a bitfield
+object fully in GC-managed lua heap, consider using the
+lua table assignment feature outlined below in order to
+pass bitfield values to dfhack API functions that need
+them, e.g. <tt class="docutils literal">matinfo:matches{metal=true}</tt>.</p>
</div>
</div>
<div class="section" id="named-types">