wip

doc/src/build.rst

@@ -80,7 +80,7 @@ Libxml2
 ^^^^^^^
 
 Libxml2 pulls some unnecessary dependencies: ICU, iconv, ... as **libTMX** does not need these unicode libraries (unless
-your software does) you may safely disable support along all the unused features:
+your software does) you may safely disable support along with all the unused features:
 
 Recommended configuration (Unixes):
 
@@ -122,6 +122,8 @@ Recommended configuration (Unixes):
        --with-writer \
        --with-reader
 
+To generate debug symbols, remove ``--without-debug`` and add ``--with-debug``.
+
 On Windows:
 
 .. code-block:: batch
@@ -162,6 +164,12 @@ On Windows:
        output=no^
        python=no
 
+Creates a NMake build script. To create a MakeFile for MinGW, add: ``compiler=mingw``.
+
+To create static libraries using MSVC, add: ``cruntime=/MT``.
+
+To generate debug symbols, set ``debug=yes``.
+
 ZLib
 ^^^^
 Building ZLib requires no special configuration.

doc/src/datastructure.rst

@@ -9,6 +9,8 @@ The Data Structure
 Definitions
 -----------
 
+.. _tile-flip-flags:
+
 Tiled use the 3 leftmost bits to store if a tile is flipped.
 
 .. c:macro:: TMX_FLIPPED_HORIZONTALLY
@@ -115,7 +117,7 @@ Enumerations
 
 .. c:type:: enum tmx_layer_type
 
-   Type of layer.
+   Type of :term:`layer`.
 
    +------------+------------------------------------------------------+
    | Layer type | Description                                          |
@@ -133,8 +135,8 @@ Enumerations
 
 .. c:type:: enum tmx_objgr_draworder
 
-   Whether the objects are drawn according to the order of appearance ("index") or sorted by their y-coordinate
-   ("topdown").
+   Whether the :term:`objects <object>` are drawn according to the order of appearance ("index") or sorted by their
+   y-coordinate ("topdown").
 
    +------------------+------------------------------------------------------+
    | Object draworder | Description                                          |
@@ -149,7 +151,7 @@ Enumerations
 
 .. c:type:: enum tmx_obj_type
 
-   Type of object.
+   Type of :term:`object`.
 
    +-------------+----------------------------------------------------------+
    | Object type | Description                                              |
@@ -230,11 +232,12 @@ Enumerations
 Data Structures
 ---------------
 
-The datastructure is a tree, just like the source document, from the root (:c:type:`tmx_map`) you can access everything.
+The datastructure is a :term:`tree`, just like the source :term:`XML` document, from the root (:c:type:`tmx_map`)
+you can access everything.
 
 .. c:type:: tmx_map
 
-   The root of the datastructure.
+   The :term:`root <Tree>` of the datastructure.
 
    .. c:member:: enum tmx_map_orient orient
 
@@ -283,11 +286,11 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_tileset_list *ts_head
 
-      Head of the tileset linked list, see :c:type:`tmx_`.
+      Head of the tileset :term:`linked list`, see :c:type:`tmx_`.
 
    .. c:member:: tmx_layer *ly_head
 
-      Head of the layers linked list, see :c:type:`tmx_layer`.
+      Head of the layers :term:`linked list`, see :c:type:`tmx_layer`.
 
    .. c:member:: unsigned int tilecount
 
@@ -303,9 +306,11 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
 .. c:type:: tmx_layer
 
+   :term:`Layer` data.
+
    .. c:member:: char *name
 
-      Name of the layer (user defined).
+      Name of the :term:`layer` (user defined).
 
    .. c:member:: double opacity
 
@@ -329,8 +334,8 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: union layer_content content
 
-      Content of the layer, as there are several types of layers (tile, object, image, ...) the content is different for
-      each type.
+      Content of the layer, as there are several types of layers (tile, object, image, ...),
+      the content is different for each type.
 
       .. note::
          You should check the value of member :c:member:`tmx_layer.type` to use the correct union member.
@@ -339,25 +344,28 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
          .. c:member:: int32_t *gids
 
-            Array of tile GID.
-            This layer is a tile layer.
+            Array of layer :term:`cells <Cell>`.
+
+            .. warning::
+               GID=0 (zero) is a special :term:`GID` which means that this :term:`cell` is empty!
 
             Example: iterate on all cells, from left to right, top to bottom:
 
             .. code-block:: c
 
                for(int cell_y = 0; cell_y < map->height; cell_y++) {
                   for(int cell_x = 0; cell_x < map->width; cell_x++) {
-                     int32_t gid = layer->content.gids[cell_y * map->width + cell_x];
+                     int32_t cell = layer->content.gids[cell_y * map->width + cell_x];
+                     int32_t GID = cell & TMX_FLIP_BITS_REMOVAL;
                      /* Draw tile operation... */
                   }
                }
 
-            Example: Direct access to the GID of a cell:
+            Example: Direct access to the cell:
 
             .. code-block:: c
 
-               int32_t get_GID_at(tmx_layer *layer, unsigned int map_width, unsigned int x, unsigned int y) {
+               int32_t get_cell_at(tmx_layer *layer, unsigned int map_width, unsigned int x, unsigned int y) {
                   return layer->content.gids[y * map_width + x];
                }
 
@@ -371,7 +379,7 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
          .. c:member:: tmx_layer *group_head
 
-            This layer is a group of layer, pointer to the head of a linked-list of children layers.
+            This layer is a group of layer, pointer to the head of a :term:`linked list` of children layers.
 
    .. c:member:: tmx_user_data user_data
 
@@ -383,10 +391,12 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_layer *next
 
-      Next element of the linked-list, if NULL then you reached the last element.
+      Next element of the :term:`linked list`, if NULL then you reached the last element.
 
 .. c:type:: tmx_tileset_list
 
+   In map :term:`tileset` data.
+
    .. c:member:: int is_embedded
 
       Private member used internally to free this tileset.
@@ -401,10 +411,12 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_tileset_list *next
 
-      Next element of the linked-list, if NULL then you reached the last element.
+      Next element of the :term:`linked list`, if NULL then you reached the last element.
 
 .. c:type:: tmx_tileset
 
+   :term:`Tileset` data, usually loaded from an external :term:`TSX` file.
+
    .. c:member:: char *name
 
       Name of the tileset (user defined).
@@ -455,9 +467,18 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
 .. c:type:: tmx_tile
 
+   :term:`Tile` data.
+
    .. c:member:: unsigned int id
 
-      LID (Local ID) of the tile, unsigned int GID = :c:member:`tmx_tileset.firstgid` + LID;
+      :term:`LID` (Local ID) of the tile.
+
+      To compute the :term:`GID` in a map from the LID from a tileset, add that LID with the
+      :c:member:`tmx_tileset_list.firstgid` of its in map tileset reference.
+
+      .. code-block:: c
+
+         unsigned int GID = tileset_list->firstgid + LID;
 
    .. c:member:: tmx_tileset *tileset
 
@@ -473,7 +494,7 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_image *image
 
-      Image for this tile, may be NULL if this tileset use a single image (atlas) for all tiles.
+      Image for this tile, may be NULL if this tileset use a single image (:term:`atlas`) for all tiles.
 
    .. c:member:: tmx_object *collision
 
@@ -511,10 +532,12 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_object *head
 
-      Head of the object linked list, see :c:type:`tmx_object`.
+      Head of the object :term:`linked list`, see :c:type:`tmx_object`.
 
 .. c:type:: tmx_object
 
+   :term:`Object` data.
+
    .. c:member:: unsigned int id
 
       Object ID.
@@ -587,7 +610,7 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_object *next
 
-      Next element of the linked-list, if NULL then you reached the last element.
+      Next element of the :term:`linked list`, if NULL then you reached the last element.
 
 .. c:type:: tmx_shape
 
@@ -674,7 +697,7 @@ The datastructure is a tree, just like the source document, from the root (:c:ty
 
    .. c:member:: tmx_tileset_list *tileset_ref
 
-      Head of the linked-list of templates referenced by this object template, may be NULL.
+      Head of the :term:`linked list` of templates referenced by this object template, may be NULL.
 
    .. c:member:: tmx_object *object
 

doc/src/error.rst

@@ -71,7 +71,7 @@ Error functions
    NULL terminator).
    Returned value is never NULL.
 
-Example error management
+Error management example
 ------------------------
 
 This is an example of how you could handle errors:

doc/src/getting-started.rst

@@ -1,4 +1,10 @@
 Getting Started
 ===============
 
-Blah.
+**Tiled** maps are stored in :term:`TMX`, :term:`TSX` and :term:`TX` documents, that are based on the :term:`XML` format.
+XML organizes data in a :term:`tree` structure, **libTMX** loads TMX maps in a C datastructure that is organized just
+like the source XML document.
+
+As **libTMX** has an ever-changing :term:`API` (and :term:`ABI`) therefore the recommended way to use it is to directly
+incorporate it in the sources of your project.
+

doc/src/glossary.rst

@@ -0,0 +1,91 @@
+Glossary
+========
+
+These are special term used by both **Tiled** and **libTMX**, or only the latter.
+
+.. glossary::
+   :sorted:
+
+   ABI
+      *Application Binary Interface*, an interface between two binary program modules, here between your software and
+      the compiled version of **libTMX**. See the `ABI page on wikipedia`_.
+
+   API
+      *Application Programming Interface*, in C, a set of structure and function definitions used to build new sofware
+      using existing material. See the `API page on wikipedia`_.
+
+   Atlas
+      A *texture atlas* is a set of :term:`textures <Texture>` assembled in a single image to reduce the overhead of
+      loading several images from non volatile storage (hard drives, CD, ...) and to optimize the usage of :term:`VRAM`.
+
+   Cell
+      An entry of a tile layer, the content of a cell is the :term:`GID`, possibly tainted with a
+      :ref:`tile flip flag <tile-flip-flags>`.
+
+      See :c:member:`layer_content.gids`.
+
+   GID
+      *Global tile Identifier*, uniquely identifies a tile at map scope.
+
+      To compute the GID from a :term:`LID` in a given map: ``int32_t GID = tileset_list->firstgid + tile->id;``.
+
+      .. warning::
+         GID=0 (zero) is a special GID which means that this :term:`cell` is empty!
+
+   Layer
+      See the `Working with Layers`_ page on Tiled documentation.
+
+   LID
+      *Local tile Identifier*, uniquely identifies a tile at tileset scope.
+
+      See :c:member:`tmx_tile.id`.
+
+   Linked List
+      A linear collection of data elements, each element points to the next.
+      See the `wikipedia page on linked lists`_.
+
+   Object
+      See the `Working with Objects`_ page on Tiled documentation.
+
+   Texture
+      Name given to images meant to be used in video games, usually given to images once they are loaded in memory
+      or in the :term:`VRAM`.
+
+   Tile
+      The atomic element that constitute tile :term:`layers <Layer>` and :term:`tilesets <Tileset>`,
+      usually a small square image.
+
+   Tileset
+      A set of tiles, in **Tiled** tilesets are usually external resources, hence they have a scope that is different
+      from the scope of the map, explaining the :term:`GID` and :term:`LID` paradigm.
+      Tilesets can be based on a single image (an :term:`atlas`) or a collection of images (one for each tile).
+
+   TMX
+      *Tile Map XML* map format used by **Tiled**, it is based on the :term:`XML` format.
+
+   Tree
+      A data structure of nodes, starting at a root node, each nodes may have zero, one or several child nodes.
+      See the `wikipedia page on trees`_.
+
+   TSX
+      *Tile Set XML* tileset format used by **Tiled**, it is based on the :term:`XML` format.
+
+   TX
+      *Template XML* template format used by **Tiled**, it is based on the :term:`XML` format.
+
+   VRAM
+      *Video RAM*, name of the volatile random access memory attributed to the GPU.
+
+   XML
+      *Extensible Markup Language* is the markup language used by the `TMX map format`_.
+      See the `XML specification`_.
+
+
+.. _ABI page on wikipedia: https://en.wikipedia.org/wiki/Application_binary_interface
+.. _API page on wikipedia: https://en.wikipedia.org/wiki/Application_programming_interface
+.. _Working with Layers: http://docs.mapeditor.org/en/stable/manual/layers/
+.. _wikipedia page on linked lists: https://en.wikipedia.org/wiki/Linked_list
+.. _Working with Objects: http://docs.mapeditor.org/en/stable/manual/objects/
+.. _TMX map format: http://docs.mapeditor.org/en/stable/reference/tmx-map-format/
+.. _wikipedia page on trees: https://en.wikipedia.org/wiki/Tree_(data_structure)
+.. _XML specification: https://www.w3.org/TR/2008/REC-xml-20081126/