wip

doc/src/datastructure.rst

@@ -6,23 +6,210 @@ The Data Structure
 
 .. _TMX Format: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/
 
+Definitions
+-----------
+
+Tiled use the 3 leftmost bits to store if a tile is flipped.
+
+.. c:macro:: TMX_FLIPPED_HORIZONTALLY
+
+Used to tell if a cell has the horizontal flip flag set: `int is_horizontally_flipped = cell & TMX_FLIPPED_HORIZONTALLY;`.
+
+.. c:macro:: TMX_FLIPPED_VERTICALLY
+
+Used to tell if a cell has the vertical flip flag set: `int is_horizontally_flipped = cell & TMX_FLIPPED_VERTICALLY;`.
+
+.. c:macro:: TMX_FLIPPED_DIAGONALLY
+
+Used to tell if a cell has the diagonal flip flag set: `int is_horizontally_flipped = cell & TMX_FLIPPED_DIAGONALLY;`.
+
+.. c:macro:: TMX_FLIP_BITS_REMOVAL
+
+Used to remove all flip flags: `int gid = cell & TMX_FLIPPED_HORIZONTALLY;`.
+
 Enumerations
 ------------
 
-Neque numquam voluptas consequatur vitae aliquid id. Porro excepturi tempore
-facilis. Sapiente aut inventore eos dolor laborum neque. Quia laborum totam sunt
-omnis non sed fugit laborum. Molestias architecto ea alias fuga et non omnis.
-Laborum temporibus velit enim.
+.. c:type:: enum tmx_map_orient
+
+Map orientation (orthogonal, isometric, hexagonal, ...).
+
++-----------------+-----------------------------------------------+
+| Map orientation | Description                                   |
++-----------------+-----------------------------------------------+
+| O_NONE          | In case of error, or unknown map orientation. |
++-----------------+-----------------------------------------------+
+| O_ORT           | Orthogonal map.                               |
++-----------------+-----------------------------------------------+
+| O_ISO           | Isometric map.                                |
++-----------------+-----------------------------------------------+
+| O_STA           | Staggered map.                                |
++-----------------+-----------------------------------------------+
+| O_HEX           | Hexagonal map.                                |
++-----------------+-----------------------------------------------+
+
+.. c:type:: enum tmx_map_renderorder
+
+How the tile layers should be drawn, the order in which tiles on tile layers are rendered.
+This is especially usefull if you're drawing overlapping tiles (see the perspective_walls.tmx example that ships with
+Tiled).
+
++-----------------+-----------------------------------------------+
+| Map renderorder | Description                                   |
++-----------------+-----------------------------------------------+
+| R_NONE          | In case of error, or unknown map renderorder. |
++-----------------+-----------------------------------------------+
+| R_RIGHTDOWN     | Draw tiles from right to left, top to bottom. |
++-----------------+-----------------------------------------------+
+| R_RIGHTUP       | Draw tiles from right to left, bottom to top. |
++-----------------+-----------------------------------------------+
+| R_LEFTDOWN      | Draw tiles from left to right, top to bottom. |
++-----------------+-----------------------------------------------+
+| R_LEFTUP        | Draw tiles from left to right, bottom to top. |
++-----------------+-----------------------------------------------+
+
+
+.. c:type:: enum tmx_stagger_index
+
+For staggered and hexagonal maps, determines whether the "even" or "odd" indexes along the staggered axis are shifted.
+
++---------------+---------------------------------------------+
+| Stagger index | Description                                 |
++---------------+---------------------------------------------+
+| SI_NONE       | In case of error, or unknown stagger index. |
++---------------+---------------------------------------------+
+| SI_EVEN       | Odd.                                        |
++---------------+---------------------------------------------+
+| SI_ODD        | Even.                                       |
++---------------+---------------------------------------------+
+
+.. c:type:: enum tmx_stagger_axis
+
+For staggered and hexagonal maps, determines which axis ("x" or "y") is staggered.
+
++--------------+--------------------------------------------+
+| Stagger axis | Description                                |
++--------------+--------------------------------------------+
+| SA_NONE      | In case of error, or unknown stagger axis. |
++--------------+--------------------------------------------+
+| SA_X         | x axis.                                    |
++--------------+--------------------------------------------+
+| SA_Y         | y axis.                                    |
++--------------+--------------------------------------------+
+
+.. c:type:: enum tmx_layer_type
+
+Type of layer.
+
++------------+------------------------------------------------------+
+| Layer type | Description                                          |
++------------+------------------------------------------------------+
+| L_NONE     | In case of error, or unknown layer type.             |
++------------+------------------------------------------------------+
+| L_LAYER    | Tile layer type, use `content.gids`.                 |
++------------+------------------------------------------------------+
+| L_OBJGR    | Objectgroup layer type, use `content.objgr`.         |
++------------+------------------------------------------------------+
+| L_IMAGE    | Image layer type, use `content.image`.               |
++------------+------------------------------------------------------+
+| L_GROUP    | Group of layer layer type, use `content.group_head`. |
++------------+------------------------------------------------------+
+
+.. 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").
+
++------------------+------------------------------------------------------+
+| Object draworder | Description                                          |
++------------------+------------------------------------------------------+
+| G_NONE           | In case of error, or unknown draw order.             |
++------------------+------------------------------------------------------+
+| G_INDEX          | Draw objects as they are ordered in the linked-list. |
++------------------+------------------------------------------------------+
+| G_TOPDOWN        | Draw objects sorted by their y-coordinate, objects   |
+|                  | must then be reordered by their y-coordinate.        |
++------------------+------------------------------------------------------+
+
+.. c:type:: enum tmx_obj_type
+
+Type of object.
+
++-------------+----------------------------------------------------------+
+| Object type | Description                                              |
++-------------+----------------------------------------------------------+
+| OT_NONE     | In case of error, or unknown object type.                |
++-------------+----------------------------------------------------------+
+| OT_SQUARE   | Square, use members `x`, `y`, `width` and `height`.      |
++-------------+----------------------------------------------------------+
+| OT_POLYGON  | Polygon, use `content.shape`.                            |
++-------------+----------------------------------------------------------+
+| OT_POLYLINE | Polyline, use `content.shape`.                           |
++-------------+----------------------------------------------------------+
+| OT_ELLIPSE  | Ellipse, use members `x`, `y`, width (horizontal radius) |
+|             | and height (vertical radius)                             |
++-------------+----------------------------------------------------------+
+| OT_TILE     | Tile, use `content.gid`.                                 |
++-------------+----------------------------------------------------------+
+| OT_TEXT     | Text, use `content.text`.                                |
++-------------+----------------------------------------------------------+
+| OT_POINT    | Point, use members `x`, `y`.                             |
++-------------+----------------------------------------------------------+
+
+.. c:type:: enum tmx_property_type
+
+Type of property.
+
++---------------+--------------------------------------------------------+
+| Property type | Description                                            |
++---------------+--------------------------------------------------------+
+| PT_NONE       | In case of error, or unknown property type.            |
++---------------+--------------------------------------------------------+
+| PT_INT        | Integer, use `value.integer`.                          |
++---------------+--------------------------------------------------------+
+| PT_FLOAT      | Float, use `value.decimal`.                            |
++---------------+--------------------------------------------------------+
+| PT_BOOL       | Boolean, use `value.boolean`.                          |
++---------------+--------------------------------------------------------+
+| PT_STRING     | String, use `value.string`.                            |
++---------------+--------------------------------------------------------+
+| PT_COLOR      | Color, use `value.color` (RGBA encoded in an integer). |
++---------------+--------------------------------------------------------+
+| PT_FILE       | Path to a file, use `value.file`.                      |
++---------------+--------------------------------------------------------+
+
+.. c:type:: enum tmx_horizontal_align
+
+Horizontal alignment of the text within the object.
+
++------------+------------------------------------------+
+| Text align | Description                              |
++------------+------------------------------------------+
+| HA_NONE    | In case of error, or unknown text align. |
++------------+------------------------------------------+
+| HA_LEFT    | Left.                                    |
++------------+------------------------------------------+
+| HA_CENTER  | Center.                                  |
++------------+------------------------------------------+
+| HA_RIGHT   | Right.                                   |
++------------+------------------------------------------+
+
+.. c:type:: enum tmx_vertical_align
+
+Vertical alignment of the text within the object.
+
++------------+------------------------------------------+
+| Text align | Description                              |
++------------+------------------------------------------+
+| VA_NONE    | In case of error, or unknown text align. |
++------------+------------------------------------------+
+| VA_TOP     | Top.                                     |
++------------+------------------------------------------+
+| VA_CENTER  | Center.                                  |
++------------+------------------------------------------+
+| VA_BOTTOM  | Bottom.                                  |
++------------+------------------------------------------+
 
-Velit veritatis impedit dolor aut consequatur. Esse quod rerum ex. Corporis
-magni praesentium optio. Et quam ducimus ex incidunt sapiente. Tempore quasi rem
-illum atque et ab inventore enim. Iste eos delectus deleniti nostrum autem
-debitis.
 
 Data Structures
 ---------------
 
-Consequuntur qui cum similique quo quas rerum. Voluptates vero voluptas
-repellendus possimus magnam labore non qui. Quis culpa molestiae error sit est
-et molestiae et. Aperiam voluptatem a neque est. Necessitatibus amet aut sed ut.
-Numquam reprehenderit illum omnis ratione.

doc/src/functions.rst

@@ -8,25 +8,45 @@ Load maps
 
 .. c:function:: tmx_map* tmx_load(const char *path)
 
+Load a TMX map.
+
 .. c:function:: tmx_map* tmx_load_buffer(const char *buffer, int len)
 
+Load a TMX map from the given buffer whose length is len.
+
 .. c:function:: tmx_map* tmx_load_fd(int fd)
 
+Load a TMX map from a C file descriptor.
+
 .. c:type:: typedef int (*tmx_read_functor)(void *userdata, char *buffer, int len)
 
+Definition of the tmx_read_functor callback.
+
 .. c:function:: tmx_map* tmx_load_callback(tmx_read_functor callback, void *userdata)
 
+Load a TMX map using a callback function as defined above.
+
 .. c:function:: void tmx_map_free(tmx_map *map)
 
+Free a loaded TMX map.
+
 External resources
 ------------------
 
+libTMX has a resource manager to store tilesets and object templates to avoid loading them twice or more.  
+
 .. c:type:: tmx_resource_manager
 
+tmx_resource_manager is a private type (it is 
+
 .. c:function:: tmx_resource_manager* tmx_make_resource_manager()
 
+Create a new resource manager.
+
 .. c:function:: void tmx_free_resource_manager(tmx_resource_manager *rc_mgr)
 
+Free a resource manager.
+
 Load resources and maps
 -----------------------
 
@@ -35,50 +55,86 @@ Tilesets
 
 .. c:function:: int tmx_load_tileset(tmx_resource_manager *rc_mgr, const char *path)
 
+Load a tileset at the given path in a resource manager.
+
 .. c:function:: int tmx_load_tileset_buffer(tmx_resource_manager *rc_mgr, const char *buffer, int len, const char *key)
 
+Load a tileset from the given buffer in a resource manager.
+
 .. c:function:: int tmx_load_tileset_fd(tmx_resource_manager *rc_mgr, int fd, const char *key)
 
+Load a tileset from a C file descriptor in a resource manager.
+
 .. c:function:: int tmx_load_tileset_callback(tmx_resource_manager *rc_mgr, tmx_read_functor callback, void *userdata, const char *key)
 
+Load a tileset using a callback function in a resource manager.
+
 Object Templates
 ^^^^^^^^^^^^^^^^
 
 .. c:function:: int tmx_load_template(tmx_resource_manager *rc_mgr, const char *path)
 
+Load a tileset at the given path in a resource manager.
+
 .. c:function:: int tmx_load_template_buffer(tmx_resource_manager *rc_mgr, const char *buffer, int len, const char *key)
 
+Load a tileset from the given buffer in a resource manager.
+
 .. c:function:: int tmx_load_template_fd(tmx_resource_manager *rc_mgr, int fd, const char *key)
 
+Load a tileset from a C file descriptor in a resource manager.
+
 .. c:function:: int tmx_load_template_callback(tmx_resource_manager *rc_mgr, tmx_read_functor callback, void *userdata, const char *key)
 
+Load a tileset using a callback function in a resource manager.
+
 Maps
 ^^^^
 
 .. c:function:: tmx_map* tmx_rcmgr_load(tmx_resource_manager *rc_mgr, const char *path)
 
+Load a TMX map, use a resource manager to resolve/store external resources.
+
 .. c:function:: tmx_map* tmx_rcmgr_load_buffer(tmx_resource_manager *rc_mgr, const char *buffer, int len)
 
+Load a TMX map from the given buffer whose length is len, use a resource manager to resolve/store external resources.
+
 .. c:function:: tmx_map* tmx_rcmgr_load_fd(tmx_resource_manager *rc_mgr, int fd)
 
+Load a TMX map from a C file descriptor, use a resource manager to resolve/store external resources.
+
 .. c:function:: tmx_map* tmx_rcmgr_load_callback(tmx_resource_manager *rc_mgr, tmx_read_functor callback, void *userdata)
 
+Load a TMX map using a callback function as defined above. `userdata` is passed as-is.
+See :c:type:`tmx_read_functor`.
+
 Utilities
 ---------
 
 .. c:function:: tmx_tile* tmx_get_tile(tmx_map *map, unsigned int gid)
 
+Deprecated, use `tmx_map->tiles[gid]`.
+
 .. c:function:: tmx_property* tmx_get_property(tmx_properties *hash, const char *key)
 
+Get a property by its name.
+
 .. c:type:: typedef void (*tmx_property_functor)(tmx_property *property, void *userdata)
 
+Definition of the tmx_property_functor callback, to be used with :c:func:`tmx_property_foreach`.
+
 .. c:function:: void tmx_property_foreach(tmx_properties *hash, tmx_property_functor callback, void *userdata)
 
+Call the given callback function for each properties, userdata is forwarded as-is.
+See :c:type:`tmx_property_functor`.
+
 Error reporting
 ---------------
 
 .. c:function:: void tmx_perror(const char*)
 
+Print to stderr a string describing the last error.
+
 .. c:function:: const char* tmx_strerr(void)
 
-Blah.
+Return a string describing the last error.

doc/src/getting-started.rst

@@ -0,0 +1,4 @@
+Getting Started
+===============
+
+Blah.

doc/src/index.rst

@@ -3,13 +3,21 @@
 About libTMX
 ============
 
-`libTMX <https://github.com/baylej/tmx>`_ is a small and very simple library to load maps created with
+`libTMX <https://github.com/baylej/tmx>`_ is a small and simple library to load maps created with
 `Tiled <https://www.mapeditor.org/>`_.
 
+Tiled map are stored in an `XML <https://www.w3.org/XML/>`_ document.
+XML organizes data in a tree structure, libTMX loads TMX maps in a C datastructures that is organized just like the
+source XML document.
+
+libTMX has an ever-changing API (and ABI) therefore the recommended way to use it is to directly incorporate it in the
+sources of your project.
 
 .. toctree::
    :maxdepth: 1
 
+   getting-started
+   renderer-from-scratch
    build
    datastructure
    functions

doc/src/renderer-from-scratch.rst

@@ -0,0 +1,4 @@
+Creating a map renderer from scratch
+====================================
+
+Blah.