* Documentation updates. Moved the canvas and font format definitions to

the Doxygen documentation.

cucul/cucul.h

@@ -38,7 +38,7 @@ typedef struct cucul_dither cucul_dither_t;
 /** font structure */
 typedef struct cucul_font cucul_font_t;
 
-/** \defgroup attributes libcucul attribute definitions
+/** \defgroup attr_defines libcucul attribute definitions
  *
  *  Colours and styles that can be used with cucul_set_attr().
  *

cucul/export.c

@@ -204,64 +204,6 @@ static void *export_caca(cucul_canvas_t *cv, unsigned long int *bytes)
     return data;
 }
 
-/*
- * The libcaca canvas format, version 1
- * ------------------------------------
- *
- * All types are big endian.
- *
- * struct
- * {
- * magic:
- *    uint8_t caca_header[2];    // "\xCA\xCA"
- *    uint8_t caca_file_type[2]; // "CV"
- *
- * canvas_header:
- *    uint32_t control_size;     // Control size (canvas_data - canvas_header)
- *    uint32_t data_size;        // Data size (EOF - canvas_data)
- *
- *    uint16_t version;          // Canvas format version
- *                               //  bit 0: set to 1 if canvas is compatible
- *                               //         with version 1 of the format
- *                               //  bits 1-15: unused yet, must be 0
- *
- *    uint32_t frames;           // Frame count
- *
- *    uint16_t flags;            // Feature flags
- *                               //  bits 0-15: unused yet, must be 0
- *
- * frame_info:
- *    struct
- *    {
- *       uint32_t width;         // Frame width
- *       uint32_t height;        // Frame height
- *       uint32_t duration;      // Frame duration in milliseconds, 0 to
- *                               // not specify a duration
- *       uint32_t attr;          // Graphics context attribute
- *       int32_t cursor_x;       // Cursor X coordinate
- *       int32_t cursor_y;       // Cursor Y coordinate
- *       int32_t handle_x;       // Handle X coordinate
- *       int32_t handle_y;       // Handle Y coordinate
- *    }
- *    frame_list[frames];
- *
- * control_extension_1:
- * control_extension_2:
- *    ...
- * control_extension_N:
- *    ...                        // reserved for future use
- *
- * canvas_data:
- *    uint8_t data[data_size];   // canvas data
- *
- * data_extension_1:
- * data_extension_2:
- *    ...
- * data_extension_N:
- *    ...                        // reserved for future use
- * };
- */
-
 /* Generate UTF-8 representation of current canvas. */
 static void *export_utf8(cucul_canvas_t *cv, unsigned long int *bytes, int cr)
 {

cucul/font.c

@@ -488,72 +488,3 @@ int cucul_render_canvas(cucul_canvas_t *cv, cucul_font_t *f,
     return 0;
 }
 
-/*
- * The libcaca font format, version 1
- * ----------------------------------
- *
- * All types are big endian.
- *
- * struct
- * {
- * magic:
- *    uint8_t caca_header[2];    // "\xCA\xCA"
- *    uint8_t caca_file_type[2]; // "FT"
- *
- * font_header:
- *    uint32_t control_size;     // Control size (font_data - font_header)
- *    uint32_t data_size;        // Data size (EOF - font_data)
- *
- *    uint16_t version;          // Font format version
- *                               //  bit 0: set to 1 if font is compatible
- *                               //         with version 1 of the format
- *                               //  bits 1-15: unused yet, must be 0
- *
- *    uint16_t blocks;           // Number of blocks in the font
- *    uint32_t glyphs;           // Total number of glyphs in the font
- *
- *    uint16_t bpp;              // Bits per pixel for glyph data (valid
- *                               // Values are 1, 2, 4 and 8)
- *    uint16_t width;            // Maximum glyph width
- *    uint16_t height;           // Maximum glyph height
- *
- *    uint16_t flags;            // Feature flags
- *                               //  bit 0: set to 1 if font is fixed width
- *                               //  bits 1-15: unused yet, must be 0
- *
- * block_info:
- *    struct
- *    {
- *       uint32_t start;         // Unicode index of the first glyph
- *       uint32_t stop;          // Unicode index of the last glyph + 1
- *       uint32_t index;         // Glyph info index of the first glyph
- *    }
- *    block_list[blocks];
- *
- * glyph_info:
- *    struct
- *    {
- *       uint16_t width;         // Glyph width in pixels
- *       uint16_t height;        // Glyph height in pixels
- *       uint32_t data_offset;   // Offset (starting from data) to the data
- *                               // for the first character
- *    }
- *    glyph_list[glyphs];
- *
- * control_extension_1:
- * control_extension_2:
- *    ...
- * control_extension_N:
- *    ...                        // reserved for future use
- *
- * font_data:
- *    uint8_t data[data_size];   // glyph data
- *
- * data_extension_1:
- * data_extension_2:
- *    ...
- * data_extension_N:
- *    ...                        // reserved for future use
- * };
- */
-

cucul/frame.c

@@ -96,7 +96,7 @@ int cucul_set_canvas_frame(cucul_canvas_t *cv, unsigned int frame)
  *  - \c ENOMEM Not enough memory to allocate new frame.
  *
  *  \param cv A libcucul canvas
- *  \param frame The index where to insert the new frame
+ *  \param id The index where to insert the new frame
  *  \return 0 in case of success, -1 if an error occurred.
  */
 int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
@@ -151,7 +151,7 @@ int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
  *    last frame of the canvas.
  *
  *  \param cv A libcucul canvas
- *  \param frame The index of the frame to delete
+ *  \param id The index of the frame to delete
  *  \return 0 in case of success, -1 if an error occurred.
  */
 int cucul_free_canvas_frame(cucul_canvas_t *cv, unsigned int id)

doc/Makefile.am

@@ -2,7 +2,7 @@
 
 EXTRA_DIST = doxygen.cfg.in footer.html header.html $(man_MANS) $(doxygen_DOX)
 
-doxygen_DOX = libcaca.dox user.dox migrating.dox tutorial.dox style.dox
+doxygen_DOX = libcaca.dox user.dox migrating.dox tutorial.dox canvas.dox font.dox style.dox
 man_MANS = caca-config.1 cacafire.1 cacaview.1 cacaserver.1 img2irc.1 cacaplay.1
 
 if BUILD_DOCUMENTATION

doc/canvas.dox

@@ -0,0 +1,60 @@
+/* $Id$ */
+
+/** \page canvas The libcaca canvas format (version 1)
+
+ All types are big endian.
+
+ \code
+struct
+{
+magic:
+   uint8_t caca_header[2];    // "\xCA\xCA"
+   uint8_t caca_file_type[2]; // "CV"
+
+canvas_header:
+   uint32_t control_size;     // Control size (canvas_data - canvas_header)
+   uint32_t data_size;        // Data size (EOF - canvas_data)
+
+   uint16_t version;          // Canvas format version
+                              //  bit 0: set to 1 if canvas is compatible
+                              //         with version 1 of the format
+                              //  bits 1-15: unused yet, must be 0
+
+   uint32_t frames;           // Frame count
+
+   uint16_t flags;            // Feature flags
+                              //  bits 0-15: unused yet, must be 0
+
+frame_info:
+   struct
+   {
+      uint32_t width;         // Frame width
+      uint32_t height;        // Frame height
+      uint32_t duration;      // Frame duration in milliseconds, 0 to
+                              // not specify a duration
+      uint32_t attr;          // Graphics context attribute
+      int32_t cursor_x;       // Cursor X coordinate
+      int32_t cursor_y;       // Cursor Y coordinate
+      int32_t handle_x;       // Handle X coordinate
+      int32_t handle_y;       // Handle Y coordinate
+   }
+   frame_list[frames];
+
+control_extension_1:
+control_extension_2:
+   ...
+control_extension_N:
+   ...                        // reserved for future use
+
+canvas_data:
+   uint8_t data[data_size];   // canvas data
+
+data_extension_1:
+data_extension_2:
+   ...
+data_extension_N:
+   ...                        // reserved for future use
+};
+ \endcode
+
+*/

doc/font.dox

@@ -0,0 +1,71 @@
+/* $Id$ */
+
+/** \page font The libcaca font format (version 1)
+
+ All types are big endian.
+
+ \code
+struct
+{
+magic:
+   uint8_t caca_header[2];    // "\xCA\xCA"
+   uint8_t caca_file_type[2]; // "FT"
+
+font_header:
+   uint32_t control_size;     // Control size (font_data - font_header)
+   uint32_t data_size;        // Data size (EOF - font_data)
+
+   uint16_t version;          // Font format version
+                              //  bit 0: set to 1 if font is compatible
+                              //         with version 1 of the format
+                              //  bits 1-15: unused yet, must be 0
+
+   uint16_t blocks;           // Number of blocks in the font
+   uint32_t glyphs;           // Total number of glyphs in the font
+
+   uint16_t bpp;              // Bits per pixel for glyph data (valid
+                              // Values are 1, 2, 4 and 8)
+   uint16_t width;            // Maximum glyph width
+   uint16_t height;           // Maximum glyph height
+
+   uint16_t flags;            // Feature flags
+                              //  bit 0: set to 1 if font is fixed width
+                              //  bits 1-15: unused yet, must be 0
+
+block_info:
+   struct
+   {
+      uint32_t start;         // Unicode index of the first glyph
+      uint32_t stop;          // Unicode index of the last glyph + 1
+      uint32_t index;         // Glyph info index of the first glyph
+   }
+   block_list[blocks];
+
+glyph_info:
+   struct
+   {
+      uint16_t width;         // Glyph width in pixels
+      uint16_t height;        // Glyph height in pixels
+      uint32_t data_offset;   // Offset (starting from data) to the data
+                              // for the first character
+   }
+   glyph_list[glyphs];
+
+control_extension_1:
+control_extension_2:
+   ...
+control_extension_N:
+   ...                        // reserved for future use
+
+font_data:
+   uint8_t data[data_size];   // glyph data
+
+data_extension_1:
+data_extension_2:
+   ...
+data_extension_N:
+   ...                        // reserved for future use
+};
+\endcode
+
+*/

doc/libcaca.dox

@@ -40,6 +40,8 @@
 
  There is also information specially targeted at \e libcaca developers:
 
+ - \subpage font
+ - \subpage canvas
  - \subpage style
 
  \section user User's documentation