Code documentation

[aaf.git] / aaf.h

diff --git a/aaf.h b/aaf.h
index ac87f060752fed43c79db6128ae4ec9f902e2de2..8e9608da618862f763346303dbd581319b606367 100644 (file)
--- a/aaf.h
+++ b/aaf.h
@@ -4,26 +4,89 @@
 #include <stdio.h>
 #include <stdint.h>
 
+/**
+ * @file
+ */
+
+/** Maximum allowed number of glyphs in AAF file */
 #define AAF_GLYPH_MAX 256
 
+/**
+ * Structure containing information about given glyph
+ */
 struct aaf_glyph {
+       /**
+        * Width of glyph.
+        * The width (in pixels) of the glyph corresponding to its ascii
+        */
        uint16_t w;
+
+       /**
+        * Height of glyph.
+        * The height (in pixels) of the glyph corresponding to its ascii
+        */
        uint16_t h;
+       
+       /**
+        * Offset of glyph.
+        * The width (in pixels) of the glyph corresponding to its ascii
+        */
        uint32_t off;
 };
 
+/**
+ * Structure containing informations about AAF file
+ */
 struct aaf {
+       /**
+        * Signature used to identify file type.
+        * Should be equal to: "AAFF"
+        */
        char signature[4];
+       
+       /**
+        * Maximum glyph Height.
+        * This is the maximum height of the glyph, including ascenders and
+        * descenders.
+        */
        uint16_t max_h;
+       
+       /**
+        * Horizontal gap.
+        * Gap size (in pixels) between adjacent glyphs.
+        */
        uint16_t gap_h;
+       
+       /**
+        * Width of space.
+        * The width of the space character.
+        */
        uint16_t space_width;
+       
+       /**
+        * Vertical gap.
+        * The number of pixels between two lines of glyphs.
+        */
        uint16_t gap_v;
        
        struct aaf_glyph glyphs[AAF_GLYPH_MAX];
 };
 
+/**
+ * Structure containing informations about glyph display
+ */
 struct aaf_glyph_data {
-       /* variable size array of values 0-9 */
+       /**
+        * Variable size array containing values 0-9
+        *
+        * Array size can be calculated using: aaf_glyph::w * aaf_glyph::h
+        *
+        * 0 means that the pixel is transparent.
+        *
+        * The values 1 to 9 represent the relative brightness of that pixel,
+        * with 9 being the brightest. There does not appear to be a linear
+        * increase in brightness from values 1 to 9.
+        */
        uint8_t * pixels;
 };
 
@@ -35,13 +98,13 @@ struct aaf_glyph_data {
  *
  * @return when succesful function returns 0, otherwise non-zero value
  */
-int read_aaf(FILE * in, struct aaf * _aaf);
+int aaf_read(FILE * in, struct aaf * _aaf);
 
 /**
  * Reads AAF glyph data from input stream
  * Returned structure is an array with number of elements equal to AAF_GLYPH_MAX.
  * Every X element of array relates to _aaf->glyphs[X].
- * Structure should be freed using free_aaf_glyph_data function.
+ * Structure should be freed using aaf_free_glyph_data function.
  *
  * @param in opened input stream
  * @param _aaf pointer to AAF header information
@@ -49,14 +112,14 @@ int read_aaf(FILE * in, struct aaf * _aaf);
  * @return when succesful returns pointer to newly allocated array of struct
  * aaf_glyph_data. On error NULL is returned.
  */
-struct aaf_glyph_data ** read_aaf_glyph_data(FILE * in, struct aaf * _aaf);
+struct aaf_glyph_data ** aaf_read_glyph_data(FILE * in, struct aaf * _aaf);
 
 /**
- * Function used to free data allocated using read_aaf_glyph_data.
+ * Function used to free memory allocated using aaf_read_glyph_data.
  *
  * @param data pointer to array of glyph data
  */
-void free_aaf_glyph_data(struct aaf_glyph_data ** data);
+void aaf_free_glyph_data(struct aaf_glyph_data ** data);
 
 /**
  * Writes AAF glyph as PGM image
@@ -64,8 +127,8 @@ void free_aaf_glyph_data(struct aaf_glyph_data ** data);
  * @param out opened output stream for writting
  * @param glyph glyph description
  * @param data glyph data
- * @return 0 if data was written succesfully, negative value when error occured
+ * @return 0 if data was written succesfully, non-zero value when error occured
  */
-int write_aaf_glyph_as_pgm(FILE * out, const struct aaf_glyph * glyph, const struct aaf_glyph_data * data);
+int aaf_write_glyph_as_pgm(FILE * out, const struct aaf_glyph * glyph, const struct aaf_glyph_data * data);
 
 #endif /* __AAF_H */