Renamed TGA methods, added docs for TGA

include/tga.h

@@ -1,113 +1,92 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file include/tga.h
+ * \brief TGA image reader/writer
  *
- * Project : Freyja
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  :
- * License : GPL See file COPYING, also (C) 2000 Mongoose
- * Comments: TGA plug-in
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2000-10-15:
- * Mongoose - Created
- ================================================================*/
-
+ * \author Mongoose
+ * \author xythobuz
+ */
 #ifndef _TGA_H
 #define _TGA_H
 
 #include <stdio.h>
 
-
-typedef enum
-{
-  TGA_TYPE__NO_DATA    = 0,
-  TGA_TYPE__MAPPED     = 1,
-  TGA_TYPE__COLOR      = 2,
-  TGA_TYPE__GREYSCALE  = 3,
-  TGA_TYPE__MAPPED_RLE = 9,
-  TGA_TYPE__COLOR_RLE  = 10
-  //  TGA_TYPE__GREYSCALE_COMPRESSED  = 11,
-  //  TGA_TYPE__COLOR_HUFFMAN_DELTA_RLE  = 32,
-  //  TGA_TYPE__COLOR_HUFFMAN_DELTA_RLE_4PASS  = 33
-
+/*!
+ * \brief Possible TGA image types
+ */
+typedef enum {
+    TGA_TYPE__NO_DATA    = 0,
+    TGA_TYPE__MAPPED     = 1,
+    TGA_TYPE__COLOR      = 2,
+    TGA_TYPE__GREYSCALE  = 3,
+    TGA_TYPE__MAPPED_RLE = 9,
+    TGA_TYPE__COLOR_RLE  = 10
+    // TGA_TYPE__GREYSCALE_COMPRESSED  = 11,
+    // TGA_TYPE__COLOR_HUFFMAN_DELTA_RLE  = 32,
+    // TGA_TYPE__COLOR_HUFFMAN_DELTA_RLE_4PASS  = 33
 } tga_type_t;
 
+/*!
+ * \brief Data structure representing TGA file header
+ */
+typedef struct {
+    unsigned char comment_lenght;       /*!< Number of bytes in comment */
+    unsigned char colormap_type;        /*!< 0 No colormap; 1 Has colormap  */
+    unsigned char image_type;           /*!< 1 Colormapped; 2 Unmapped;
+                                             9 Colormapped RLE; 10 Unmapped RLE */
+    unsigned short colormap_index;      /*!< Index of first color map entry */
+    unsigned short colormap_lenght;     /*!< Number of color map entries */
+    unsigned char colormap_bbp;         /*!< 16, 24, or 32 bits per pixel format */
+    unsigned short origin_x;            /*!< X coor of lower-left corner */
+    unsigned short origin_y;            /*!< Y coor of lower-left corner */
+    unsigned short width;               /*!< Width in pixels */
+    unsigned short height;              /*!< Height in pixels */
+    unsigned char bpp;                  /*!< Number of bits in a pixel index */
+    unsigned char desc_flags;           /*!< Various magic bits */
+} tga_t;
+
+/*!
+ * \brief Check if a file is a valid TGA image
+ * \param f file to be checked
+ * \returns 0 if valid, else error condition
+ */
+int tga_check(FILE *f);
+
+/*!
+ * \brief Load a TGA image from file
+ * \param f valid image file
+ * \param image Where the pixmap will be stored (or NULL)
+ * \param width where the width will be stored
+ * \param height where the height will be stored
+ * \param type where the type will be stored (tga_type_t)
+ * \returns 0 on success, else error condition
+ */
+int tga_load(FILE *f, unsigned char **image,
+        unsigned int *width, unsigned int *height, char *type);
+
+/*!
+ * \brief Save a pixel buffer into a file on disk
+ * \param f file in which image will be saved
+ * \param image pixmap to be stored
+ * \param width width of pixmap/image
+ * \param height height of pixmap/image
+ * \param type tga_type_t to use
+ * \returns 0 on success, else error condition
+ */
+int tga_save(FILE *f, unsigned char *image,
+        unsigned int width, unsigned int height, char type);
+
+/*!
+ * \brief Save a pixel buffer into a file on disk
+ * \param image pixmap to be stored
+ * \param width width of pixmap/image
+ * \param height height of pixmap/image
+ * \param type tga_type_t to use
+ * \param s format string for file path/name
+ * \returns 0 on success, else error condition
+ */
+int tga_save_filename(unsigned char *image,
+        unsigned int width, unsigned int height,
+        char type,
+        char *s, ...);
 
-typedef struct mtk_image_tga_s
-{
-  unsigned char comment_lenght;       /* Number of bytes in comment */
-  unsigned char colormap_type;        /* 0 No colormap; 1 Has colormap  */
-  unsigned char image_type;           /* 1 Colormapped, 2 Unmapped;
-                     9 Colormapped RLE; 10 Unmapped RLE */
-
-  unsigned short colormap_index;      /* Index of first color map entry */
-  unsigned short colormap_lenght;     /* Number of color map entries */
-  unsigned char colormap_bbp;         /* 16, 24, or 32 bits per pixel format */
-
-  unsigned short origin_x;            /* X coor of lower-left corner */
-  unsigned short origin_y;            /* Y coor of lower-left corner */
-  unsigned short width;               /* Width in pixels */
-  unsigned short height;              /* Height in pixels */
-  unsigned char bpp;                  /* Number of bits in a pixel index */
-  unsigned char desc_flags;           /* Various magic bits */
-
-} mtk_image_tga_t;
-
-
-  int mtk_image__tga_check(FILE *f);
-  /*------------------------------------------------------
-   * Pre  : Filename is to be checked
-   * Post : Returns 0 if valid, else error condition
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.04.01:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  int mtk_image__tga_load(FILE *f, unsigned char **image,
-             unsigned int *width, unsigned int *height, char *type);
-  /*------------------------------------------------------
-   * Pre  : Filename is a valid image file
-   * Post : Image is either a valid pixmap or NULL
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.04.01:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-  int mtk_image__tga_save(FILE *f, unsigned char *image,
-              unsigned int width, unsigned int height, char type);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Image is saved to diskfile if valid and can
-   *
-   *-- History ------------------------------------------
-   *
-   * 2001.04.01:
-   * Mongoose - Created
-   ------------------------------------------------------*/
-
-
-  int mtk_image__tga_save_filename(unsigned char *image,
-                   unsigned int width, unsigned int height,
-                   char type,
-                   char *s, ...);
-  /*------------------------------------------------------
-   * Pre  :
-   * Post : Image is saved to diskfile if valid and can
-   *
-   *-- History ------------------------------------------
-   *
-   * 2003.07.11:
-   * Mongoose - Created
-   ------------------------------------------------------*/
 #endif

src/Texture.cpp

@@ -265,7 +265,7 @@ int Texture::loadFontTTF(const char *filename,
         FILE *f = fopen("font.tga", "wb");
         if (f)
         {
-            mtk_image__tga_save(f, texture->texture, 256, 256, 4);
+            tga_save(f, texture->texture, 256, 256, 4);
             fclose(f);
         }
         else
@@ -957,9 +957,9 @@ int Texture::loadTGA(const char *filename)
     {
         perror("Couldn't load file");
     }
-    else if (!mtk_image__tga_check(f))
+    else if (!tga_check(f))
     {
-        mtk_image__tga_load(f, &image, &w, &h, &type);
+        tga_load(f, &image, &w, &h, &type);
 
         type += 2;
 

src/tga.cpp

@@ -1,28 +1,12 @@
-/*================================================================
+/*!
+ * \file src/tga.cpp
+ * \brief TGA image reader/writer
  *
- * Project : Freyja
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  :
- * License : GPL See file COPYING, also (C) 2000 Mongoose
- * Comments: TGA plug-in
+ * \todo type should pass more info (2 bits for RGBA|RGB|GREY; val for depth)
  *
- *           TODO: type should pass more info
- *                 2 bits for RGBA | RGB | GREY
- *                 val for depth
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2001-10-25:
- * Mongoose - support for screen origin bit
- *
- * 2000-10-15:
- * Mongoose - Created
- ================================================================*/
+ * \author Mongoose
+ * \author xythobuz
+ */
 
 #include <string.h>
 #include <stdarg.h>
@@ -34,7 +18,7 @@
 #endif
 
 
-int mtk_image__tga_check(FILE *f)
+int tga_check(FILE *f)
 {
     char buffer[10];
 
@@ -62,10 +46,10 @@ int mtk_image__tga_check(FILE *f)
 }
 
 
-int mtk_image__tga_load(FILE *f, unsigned char **image,
+int tga_load(FILE *f, unsigned char **image,
         unsigned int *width, unsigned int *height, char *type)
 {
-    mtk_image_tga_t header;
+    tga_t header;
     char comment[256];
     unsigned char pixel[4];
     unsigned char *swap_row = NULL;
@@ -77,7 +61,7 @@ int mtk_image__tga_load(FILE *f, unsigned char **image,
 
     if (!f)
     {
-        fprintf(stderr, "mtk_image__tga_load> Invalid parameters.\n");
+        fprintf(stderr, "tga_load> Invalid parameters.\n");
         return -1;
     }
 
@@ -165,7 +149,7 @@ int mtk_image__tga_load(FILE *f, unsigned char **image,
     if (!size || (!(header.colormap_type == 0 &&
                     (header.image_type == 2 || header.image_type == 10))))
     {
-        fprintf(stderr, "mtk_image__tga_load> Unknown image format.\n");
+        fprintf(stderr, "tga_load> Unknown image format.\n");
         return -2;
     }
 
@@ -223,7 +207,7 @@ int mtk_image__tga_load(FILE *f, unsigned char **image,
                 case TGA_TYPE__COLOR:
                     if (fread((*image), size, 1, f) < 1)
                     {
-                        fprintf(stderr, "mtk_image__tga_load> Image fread failed.\n");
+                        fprintf(stderr, "tga_load> Image fread failed.\n");
                         delete [] *image;
                         return -4;
                     }
@@ -296,7 +280,7 @@ int mtk_image__tga_load(FILE *f, unsigned char **image,
                 case TGA_TYPE__COLOR:
                     if (fread((*image), size, 1, f) < 1)
                     {
-                        fprintf(stderr, "mtk_image__tga_load> Image fread failed.\n");
+                        fprintf(stderr, "tga_load> Image fread failed.\n");
                         delete [] *image;
                         return -4;
                     }
@@ -352,10 +336,10 @@ int mtk_image__tga_load(FILE *f, unsigned char **image,
 }
 
 
-int mtk_image__tga_save(FILE *f, unsigned char *image,
+int tga_save(FILE *f, unsigned char *image,
         unsigned int width, unsigned int height, char type)
 {
-    mtk_image_tga_t header;
+    tga_t header;
     unsigned int size;
     //  unsigned int i;
     //  unsigned char tmp;
@@ -364,7 +348,7 @@ int mtk_image__tga_save(FILE *f, unsigned char *image,
 
     if (!f || !image || !width || !height)
     {
-        fprintf(stderr, "mtk_image__tga_save> Invalid parameters.\n");
+        fprintf(stderr, "tga_save> Invalid parameters.\n");
         return -1;
     }
 
@@ -454,7 +438,7 @@ int mtk_image__tga_save(FILE *f, unsigned char *image,
     // Write image data
     if (fwrite(image, size, 1, f) < 1)
     {
-        perror("mtk_image__tga_save> Disk write failed.\n");
+        perror("tga_save> Disk write failed.\n");
         return -2;
     }
 
@@ -462,7 +446,7 @@ int mtk_image__tga_save(FILE *f, unsigned char *image,
 }
 
 
-int mtk_image__tga_save_filename(unsigned char *image,
+int tga_save_filename(unsigned char *image,
         unsigned int width, unsigned int height,
         char type,
         char *s, ...)
@@ -485,7 +469,7 @@ int mtk_image__tga_save_filename(unsigned char *image,
         return -1;
     }
 
-    v = mtk_image__tga_save(f, image, width, height, type);
+    v = tga_save(f, image, width, height, type);
     fclose(f);
 
     return v;

test/tga.cpp

@@ -20,7 +20,7 @@ const char *testFiles[] = {
 
 TEST checkFile(FILE *f) {
     ASSERTm("File wasn't opened.", f != NULL);
-    ASSERT_FALSEm("File is invalid?!", mtk_image__tga_check(f));
+    ASSERT_FALSEm("File is invalid?!", tga_check(f));
     PASS();
 }
 
@@ -29,7 +29,7 @@ TEST loadFile(FILE *f) {
     unsigned int width, height;
     char type;
     ASSERTm("File wasn't opened.", f != NULL);
-    ASSERT_FALSEm("File couldn't be loaded!", mtk_image__tga_load(f, &image, &width, &height, &type));
+    ASSERT_FALSEm("File couldn't be loaded!", tga_load(f, &image, &width, &height, &type));
     printf("\nWidth: %u\nHeight: %u\nType: %d\n", width, height, type);
     PASS();
 }