1 files changed, 48 insertions, 15 deletions

diff --git a/gfx-iso/include/isogfx/isogfx.h b/gfx-iso/include/isogfx/isogfx.h
index a5f7770..22c8fd5 100644
--- a/gfx-iso/include/isogfx/isogfx.h
+++ b/gfx-iso/include/isogfx/isogfx.h
@@ -3,64 +3,97 @@
  */
 #pragma once
 
+#include <stdbool.h>
 #include <stdint.h>
 
 typedef struct IsoGfx IsoGfx;
 
-typedef uint8_t Tile;
+/// Tile handle.
+typedef uint16_t Tile;
+
+/// Colour channel.
 typedef uint8_t Channel;
 
 typedef struct Pixel {
-  Channel r, g, b;
+  Channel r, g, b, a;
 } Pixel;
 
 typedef enum TileDescType {
   TileFromColour,
   TileFromFile,
-  TileFromMemory
+  TileFromMemory,
 } TileDescType;
 
 typedef struct TileDesc {
   TileDescType type;
+  int          width;  /// Tile width in pixels.
+  int          height; /// Tile height in pixels.
   union {
-    Pixel colour;
+    Pixel colour; /// Constant colour tile.
     struct {
       const char* path;
     } file;
     struct {
-      const void* data;
+      const uint8_t* data; /// sizeof(Pixel) * width * height
     } mem;
   };
 } TileDesc;
 
+typedef struct WorldDesc {
+  int tile_width;    /// Base tile width in pixels.
+  int tile_height;   /// Base tile height in pixels.
+  int world_width;   /// World width in tiles.
+  int world_height;  /// World height in tiles.
+  int max_num_tiles; /// 0 for an implementation-defined default.
+} WorldDesc;
+
 typedef struct IsoGfxDesc {
-  int screen_width;
-  int screen_height;
-  int tile_width;
-  int tile_height;
-  int world_width;
-  int world_height;
-  int max_num_tiles; // 0 for an implementation-defined default.
+  int screen_width;  /// Screen width in pixels.
+  int screen_height; /// Screen height in pixels.
 } IsoGfxDesc;
 
+/// Create a new isometric graphics engine.
 IsoGfx* isogfx_new(const IsoGfxDesc*);
 
+/// Destroy the isometric graphics engine.
 void isogfx_del(IsoGfx**);
 
+/// Create an empty world.
+bool isogfx_make_world(IsoGfx*, const WorldDesc*);
+
+/// Load a world from a tile map (.TM) file.
+bool isogfx_load_world(IsoGfx*, const char* filepath);
+
+/// Return the world's width.
+int isogfx_world_width(const IsoGfx*);
+
+/// Return the world's height.
+int isogfx_world_height(const IsoGfx*);
+
+/// Create a new tile.
 Tile isogfx_make_tile(IsoGfx*, const TileDesc*);
 
+/// Set the tile at position (x,y).
 void isogfx_set_tile(IsoGfx*, int x, int y, Tile);
 
+/// Set the tiles in positions in the range (x0,y0) - (x1,y1).
 void isogfx_set_tiles(IsoGfx*, int x0, int y0, int x1, int y1, Tile);
 
+/// Translate Cartesian to isometric coordinates.
 void isogfx_pick_tile(
     const IsoGfx*, double xcart, double ycart, int* xiso, int* yiso);
 
+/// Render the world.
 void isogfx_render(IsoGfx*);
 
+/// Draw/overlay a tile at position (x,y).
+///
+/// This function just renders a tile at position (x,y) and should be called
+/// after isogfx_render() to obtain the correct result. To set the tile at
+/// position (x,y) instead, use isogfx_set_tile().
 void isogfx_draw_tile(IsoGfx*, int x, int y, Tile);
 
+/// Return a pointer to the internal colour buffer.
+///
+/// Call after each call to isogfx_render() to retrieve the render output.
 const Pixel* isogfx_get_screen_buffer(const IsoGfx*);
-
-int isogfx_world_width(const IsoGfx*);
-int isogfx_world_height(const IsoGfx*);