Test and document some filter functions

docs/naturaldocs/run_docs.sh

@@ -67,6 +67,7 @@ sed -e "s/@VERSION@/$VERSION/g" preamble.txt > tmp/preamble.txt
 # Run naturaldocs to create the manual.
 $(nd) --rebuild --rebuild-output --documented-only \
     -i tmp/ \
+    -img images/ \
     -o html html  \
     --project project/ \
     -s Default libgd

src/gd_filter.c

@@ -1,3 +1,8 @@
+/**
+ * File: Image Filters
+ */
+
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -184,10 +189,16 @@ BGD_DECLARE(int) gdImagePixelate(gdImagePtr im, int block_size, const unsigned i
 	return 1;
 }
 
-/*
-	Function: gdImageNegate
-	
-	Invert src image.
+/**
+ * Function: gdImageNegate
+ *
+ * Invert an image
+ *
+ * Parameters:
+ *   src - The image.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
  */
 BGD_DECLARE(int) gdImageNegate(gdImagePtr src)
 {
@@ -220,10 +231,16 @@ BGD_DECLARE(int) gdImageNegate(gdImagePtr src)
 	return 1;
 }
 
-/*
-	Function: gdImageGrayScale
-	
-	Convert the image src to a grayscale image.
+/**
+ * Function: gdImageGrayScale
+ *
+ * Convert an image to grayscale
+ *
+ * Parameters:
+ *   src - The image.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
  */
 BGD_DECLARE(int) gdImageGrayScale(gdImagePtr src)
 {
@@ -257,10 +274,21 @@ BGD_DECLARE(int) gdImageGrayScale(gdImagePtr src)
 	return 1;
 }
 
-/*
-	Function: gdImageBrightness
-	
-	Set the brightness level <level> for the image src.
+/**
+ * Function: gdImageBrightness
+ *
+ * Change the brightness of an image
+ *
+ * Parameters:
+ *   src        - The image.
+ *   brightness - The value to add to the color channels of all pixels.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageContrast>
+ *   - <gdImageColor>
  */
 BGD_DECLARE(int) gdImageBrightness(gdImagePtr src, int brightness)
 {
@@ -307,8 +335,22 @@ BGD_DECLARE(int) gdImageBrightness(gdImagePtr src, int brightness)
 }
 
 
-/*
-	Function: gdImageContrast
+/**
+ * Function: gdImageContrast
+ *
+ * Change the contrast of an image
+ *
+ * Parameters:
+ *   src      - The image.
+ *   contrast - The contrast adjustment value. Negative values increase, postive
+ *              values decrease the contrast. The larger the absolute value, the
+ *              stronger the effect.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageBrightness>
  */
 BGD_DECLARE(int) gdImageContrast(gdImagePtr src, double contrast)
 {
@@ -370,8 +412,23 @@ BGD_DECLARE(int) gdImageContrast(gdImagePtr src, double contrast)
 }
 
 
-/*
-	Function: gdImageColor
+/**
+ * Function: gdImageColor
+ *
+ * Change channel values of an image
+ *
+ * Parameters:
+ *   src   - The image.
+ *   red   - The value to add to the red channel of all pixels.
+ *   green - The value to add to the green channel of all pixels.
+ *   blue  - The value to add to the blue channel of all pixels.
+ *   alpha - The value to add to the alpha channel of all pixels.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageBrightness>
  */
 BGD_DECLARE(int) gdImageColor(gdImagePtr src, const int red, const int green, const int blue, const int alpha)
 {
@@ -415,8 +472,29 @@ BGD_DECLARE(int) gdImageColor(gdImagePtr src, const int red, const int green, co
 	return 1;
 }
 
-/*
-	Function: gdImageConvolution
+/**
+ * Function: gdImageConvolution
+ *
+ * Apply a convolution matrix to an image
+ *
+ * Depending on the matrix a wide range of effects can be accomplished, e.g.
+ * blurring, sharpening, embossing and edge detection.
+ *
+ * Parameters:
+ *   src        - The image.
+ *   filter     - The 3x3 convolution matrix.
+ *   filter_div - The value to divide the convoluted channel values by.
+ *   offset     - The value to add to the convoluted channel values.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageEdgeDetectQuick>
+ *   - <gdImageGaussianBlur>
+ *   - <gdImageEmboss>
+ *   - <gdImageMeanRemoval>
+ *   - <gdImageSmooth>
  */
 BGD_DECLARE(int) gdImageConvolution(gdImagePtr src, float filter[3][3], float filter_div, float offset)
 {
@@ -599,8 +677,22 @@ BGD_DECLARE(int) gdImageSelectiveBlur( gdImagePtr src)
 	return 1;
 }
 
-/*
-	Function: gdImageEdgeDetectQuick
+/**
+ * Function: gdImageEdgeDetectQuick
+ *
+ * Edge detection of an image
+ *
+ * (see edge_detect_quick.jpg)
+ *
+ * Parameters:
+ *   src - The image.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageMeanRemoval>
+ *   - <gdImageConvolution>
  */
 BGD_DECLARE(int) gdImageEdgeDetectQuick(gdImagePtr src)
 {
@@ -642,8 +734,21 @@ BGD_DECLARE(int) gdImageGaussianBlur(gdImagePtr im)
 	return gdImageConvolution(im, filter, 16, 0);
 }
 
-/*
-	Function: gdImageEmboss
+/**
+ * Function: gdImageEmboss
+ *
+ * Emboss an image
+ *
+ * (see emboss.jpg)
+ *
+ * Parameters:
+ *   im - The image.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageConvolution>
  */
 BGD_DECLARE(int) gdImageEmboss(gdImagePtr im)
 {
@@ -659,8 +764,22 @@ BGD_DECLARE(int) gdImageEmboss(gdImagePtr im)
 	return gdImageConvolution(im, filter, 1, 127);
 }
 
-/*
-	Function: gdImageMeanRemoval
+/**
+ * Function: gdImageMeanRemoval
+ *
+ * Mean removal of an image
+ *
+ * (see mean_removal.jpg)
+ *
+ * Parameters:
+ *   im - The image.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageEdgeDetectQuick>
+ *   - <gdImageConvolution>
  */
 BGD_DECLARE(int) gdImageMeanRemoval(gdImagePtr im)
 {
@@ -671,8 +790,22 @@ BGD_DECLARE(int) gdImageMeanRemoval(gdImagePtr im)
 	return gdImageConvolution(im, filter, 1, 0);
 }
 
-/*
-	Function: gdImageSmooth
+/**
+ * Function: gdImageSmooth
+ *
+ * Smooth an image
+ *
+ * (see smooth.jpg)
+ *
+ * Parameters:
+ *   im     - The image.
+ *   weight - The strength of the smoothing.
+ *
+ * Returns:
+ *   Non-zero on success, zero on failure.
+ *
+ * See also:
+ *   - <gdImageConvolution>
  */
 BGD_DECLARE(int) gdImageSmooth(gdImagePtr im, float weight)
 {

tests/CMakeLists.txt

@@ -24,13 +24,17 @@ if (BUILD_TEST)
 		gd
 		gd2
 		gdimagearc
+		gdimagebrightness
 		gdimageclone
+		gdimagecolor
 		gdimagecolorclosest
 		gdimagecolordeallocate
 		gdimagecolorexact
 		gdimagecolorreplace
 		gdimagecolorresolve
 		gdimagecolortransparent
+		gdimagecontrast
+		gdimageconvolution
 		gdimagecopy
 		gdimagecopyresampled
 		gdimagecopyrotated
@@ -43,7 +47,9 @@ if (BUILD_TEST)
 		gdimagefilledrectangle
 		gdimagefilltoborder
 		gdimagefilter
+		gdimagegrayscale
 		gdimageline
+		gdimagenegate
 		gdimageopenpolygon
 		gdimagepixelate
 		gdimagepolygon

tests/Makefile.am

@@ -19,13 +19,17 @@ include freetype/Makemodule.am
 include gd/Makemodule.am
 include gd2/Makemodule.am
 include gdimagearc/Makemodule.am
+include gdimagebrightness/Makemodule.am
 include gdimageclone/Makemodule.am
+include gdimagecolor/Makemodule.am
 include gdimagecolorclosest/Makemodule.am
 include gdimagecolordeallocate/Makemodule.am
 include gdimagecolorexact/Makemodule.am
 include gdimagecolorreplace/Makemodule.am
 include gdimagecolorresolve/Makemodule.am
 include gdimagecolortransparent/Makemodule.am
+include gdimagecontrast/Makemodule.am
+include gdimageconvolution/Makemodule.am
 include gdimagecopy/Makemodule.am
 include gdimagecopyresampled/Makemodule.am
 include gdimagecopyrotated/Makemodule.am
@@ -38,7 +42,9 @@ include gdimagefilledpolygon/Makemodule.am
 include gdimagefilledrectangle/Makemodule.am
 include gdimagefilltoborder/Makemodule.am
 include gdimagefilter/Makemodule.am
+include gdimagegrayscale/Makemodule.am
 include gdimageline/Makemodule.am
+include gdimagenegate/Makemodule.am
 include gdimageopenpolygon/Makemodule.am
 include gdimagepixelate/Makemodule.am
 include gdimagepolygon/Makemodule.am

tests/gdimagebrightness/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimagebrightness/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimagebrightness/Makemodule.am

@@ -0,0 +1,10 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimagebrightness/basic
+endif
+
+EXTRA_DIST += \
+	gdimagebrightness/CMakeLists.txt \
+	gdimagebrightness/basic.png \
+	gdimagebrightness/basic+100.png \
+	gdimagebrightness/basic-100.png

tests/gdimagebrightness/basic.c

@@ -0,0 +1,41 @@
+/**
+ * Basic test for gdImageBrightness()
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+static void test_brightness(int brightness);
+
+
+int main()
+{
+    test_brightness(+100);
+    test_brightness(-100);
+
+    return gdNumFailures();
+}
+
+
+static void test_brightness(int brightness)
+{
+    gdImagePtr im;
+    FILE *fp;
+    char basename[256];
+    char *path;
+
+    fp = gdTestFileOpen2("gdimagebrightness", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    gdImageBrightness(im, brightness);
+
+    sprintf(basename, "basic%+03d.png", brightness);
+    path = gdTestFilePath2("gdimagebrightness", basename);
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+}

tests/gdimagecolor/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimagecolor/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimagecolor/Makemodule.am

@@ -0,0 +1,9 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimagecolor/basic
+endif
+
+EXTRA_DIST += \
+	gdimagecolor/CMakeLists.txt \
+	gdimagecolor/basic.png \
+	gdimagecolor/basic_exp.png

tests/gdimagecolor/basic.c

@@ -0,0 +1,29 @@
+/**
+ * Basic test for gdImageColor()
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+int main()
+{
+    gdImagePtr im;
+    FILE *fp;
+    char *path;
+
+    fp = gdTestFileOpen2("gdimagecolor", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    gdImageColor(im, 127, -127, -127, 0);
+
+    path = gdTestFilePath2("gdimagecolor", "basic_exp.png");
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+
+    return gdNumFailures();
+}

tests/gdimagecontrast/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimagecontrast/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimagecontrast/Makemodule.am

@@ -0,0 +1,10 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimagecontrast/basic
+endif
+
+EXTRA_DIST += \
+	gdimagecontrast/CMakeLists.txt \
+	gdimagecontrast/basic.png \
+	gdimagecontrast/basic+50.png \
+	gdimagecontrast/basic-50.png

tests/gdimagecontrast/basic.c

@@ -0,0 +1,41 @@
+/**
+ * Basic test for gdImageContrast()
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+static void test_contrast(double contrast);
+
+
+int main()
+{
+    test_contrast(+50.0);
+    test_contrast(-50.0);
+
+    return gdNumFailures();
+}
+
+
+static void test_contrast(double contrast)
+{
+    gdImagePtr im;
+    FILE *fp;
+    char basename[256];
+    char *path;
+
+    fp = gdTestFileOpen2("gdimagecontrast", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    gdImageContrast(im, contrast);
+
+    sprintf(basename, "basic%+03.0f.png", contrast);
+    path = gdTestFilePath2("gdimagecontrast", basename);
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+}

tests/gdimageconvolution/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimageconvolution/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimageconvolution/Makemodule.am

@@ -0,0 +1,12 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimageconvolution/basic
+endif
+
+EXTRA_DIST += \
+	gdimageconvolution/CMakeLists.txt \
+	gdimageconvolution/basic.png \
+	gdimageconvolution/basic_edge_detect_quick.png \
+	gdimageconvolution/basic_emboss.png \
+	gdimageconvolution/basic_mean_removal.png \
+	gdimageconvolution/basic_smooth.png

tests/gdimageconvolution/basic.c

@@ -0,0 +1,62 @@
+/**
+ * Basic test for gdImageConvolution() and related functions
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+static void test_convolution(void (*convolution_func)(gdImagePtr im), const char *expected)
+{
+    gdImagePtr im;
+    FILE *fp;
+    char *path;
+
+    fp = gdTestFileOpen2("gdimageconvolution", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    convolution_func(im);
+
+    path = gdTestFilePath2("gdimageconvolution", expected);
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+}
+
+
+static void test_edge_detect_quick(gdImagePtr im)
+{
+    gdImageEdgeDetectQuick(im);
+}
+
+
+static void test_smooth(gdImagePtr im)
+{
+    gdImageSmooth(im, 5);
+}
+
+
+static void test_emboss(gdImagePtr im)
+{
+    gdImageEmboss(im);
+}
+
+
+static void test_mean_removal(gdImagePtr im)
+{
+    gdImageMeanRemoval(im);
+}
+
+
+int main()
+{
+    test_convolution(&test_edge_detect_quick, "basic_edge_detect_quick.png");
+    test_convolution(&test_smooth, "basic_smooth.png");
+    test_convolution(&test_emboss, "basic_emboss.png");
+    test_convolution(&test_mean_removal, "basic_mean_removal.png");
+
+    return gdNumFailures();
+}

tests/gdimagegrayscale/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimagegrayscale/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimagegrayscale/Makemodule.am

@@ -0,0 +1,9 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimagegrayscale/basic
+endif
+
+EXTRA_DIST += \
+	gdimagegrayscale/CMakeLists.txt \
+	gdimagegrayscale/basic.png \
+	gdimagegrayscale/basic_exp.png

tests/gdimagegrayscale/basic.c

@@ -0,0 +1,29 @@
+/**
+ * Basic test for gdImageGrayScale()
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+int main()
+{
+    gdImagePtr im;
+    FILE *fp;
+    char *path;
+
+    fp = gdTestFileOpen2("gdimagegrayscale", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    gdImageGrayScale(im);
+
+    path = gdTestFilePath2("gdimagegrayscale", "basic_exp.png");
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+
+    return gdNumFailures();
+}

tests/gdimagenegate/.gitignore

@@ -0,0 +1 @@
+/basic

tests/gdimagenegate/CMakeLists.txt

@@ -0,0 +1,5 @@
+LIST(APPEND TESTS_FILES
+	basic
+)
+
+ADD_GD_TESTS()

tests/gdimagenegate/Makemodule.am

@@ -0,0 +1,9 @@
+if HAVE_LIBPNG
+libgd_test_programs += \
+	gdimagenegate/basic
+endif
+
+EXTRA_DIST += \
+	gdimagenegate/CMakeLists.txt \
+	gdimagenegate/basic.png \
+	gdimagenegate/basic_exp.png

tests/gdimagenegate/basic.c

@@ -0,0 +1,29 @@
+/**
+ * Basic test for gdImageNegate()
+ */
+
+
+#include "gd.h"
+#include "gdtest.h"
+
+
+int main()
+{
+    gdImagePtr im;
+    FILE *fp;
+    char *path;
+
+    fp = gdTestFileOpen2("gdimagenegate", "basic.png");
+    im = gdImageCreateFromPng(fp);
+    fclose(fp);
+
+    gdImageNegate(im);
+
+    path = gdTestFilePath2("gdimagenegate", "basic_exp.png");
+    gdAssertImageEqualsToFile(path, im);
+    gdFree(path);
+
+    gdImageDestroy(im);
+
+    return gdNumFailures();
+}