terrain Package
===============

.. contents:: Contents
    :local:

:mod:`terrain` Package
----------------------

.. automodule:: nbtparse.minecraft.terrain
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`dimension` Module
-----------------------

.. automodule:: nbtparse.minecraft.terrain.dimension
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`region` Module
---------------------

.. automodule:: nbtparse.minecraft.terrain.region
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`~.terrain.chunk` Module
-----------------------------

.. automodule:: nbtparse.minecraft.terrain.chunk
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`voxel` Module
-------------------

.. automodule:: nbtparse.minecraft.terrain.voxel
    :members:
    :imported-members:
    :undoc-members:
    :show-inheritance:

Performance of the :mod:`voxel` module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :mod:`.voxel` module is implemented both in pure Python and in `Cython`_.
When you import it, you will receive the most performant version available.

.. _Cython: http://cython.org

When running ``setup.py`` on a system with a compatible version of Cython,
pass the ``--cythonize`` flag to request compilation of the Cython version
into C, or ``--pure-python`` to request the total exclusion of the Cython
version.  If neither flag is passed, the script assumes the Cython-to-C
conversion has already happened and goes looking for a C version.  Note that
the tarball provided on PyPI has the C source code included, so
``--cythonize`` is not normally necessary unless building directly from
version control.

The Cython version is, generally speaking, far more performant than the Python
version, unless you happen to be a PyPy user.  Both versions are optimized
under the assumption that tile entities are relatively rare and most blocks
are ordinary blocks.  This assumption allows the Cython version to release the
`GIL`_ when copying memory.  It should be possible, in principle, to realize
considerable gains from parallelism here.  However, the current implementation
does not do so.

.. _GIL: https://docs.python.org/3/glossary.html#term-global-interpreter-lock

The Cython version of the module implements the buffer protocol, as described
in `PEP 3118`_.  This allows C code fast access to the underlying memory
backing a VoxelBuffer.  VoxelBuffers provide buffers compatible with the flag
value ``PyBUF_RECORDS``.  Each element is an ``unsigned short`` with native
byte order (i.e. the format string is ``H``).  The block ID is stored in the
12 least significant bits, and the data value is stored in the next 4 bits.
On those arcane architectures where ``unsigned short`` is not 16 bits, the
remaining high bits are ignored.

Both the pure Python and the Cython versions of VoxelBuffer are acceptable
arguments to :func:`numpy.asarray` and some other NumPy functions.  The memory
layout is substantially identical to that described above.  This is generally
a fast operation with no significant memory copying, even if you are using the
pure Python version.  Keep in mind that the elements of the array will be
numbers (as described above) and not :class:`~.voxel.Block` objects.

.. _PEP 3118: https://www.python.org/dev/peps/pep-3118/

.. note::

    As an implementation detail, buffers are contiguous in the YZX order (that
    is, with the second index changing least often and the first index
    changing most often).  This behavior is not contractual, but it may help
    you maximize CPU cache hits.

.. warning::

    Modifications made through the buffer protocol or NumPy will not trigger
    notifications to any observers which may be registered.

:mod:`filters` Module
---------------------

.. automodule:: nbtparse.minecraft.terrain.filters
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`tile` Module
------------------

.. automodule:: nbtparse.minecraft.terrain.tile
    :members:
    :undoc-members:
    :show-inheritance: