Add documentation for the ImageInfo properties

1 files changed, 179 insertions, 44 deletions

diff --git a/dmagick/Options.d b/dmagick/Options.d
index b01e62a..9515076 100644
--- a/dmagick/Options.d
+++ b/dmagick/Options.d
@@ -47,7 +47,9 @@ class Options
 		drawInfo = DestroyDrawInfo(drawInfo);
 	}
 
-	//ImageInfo fields
+	/****************************************************************
+	 * ImageInfo fields
+	 ****************************************************************/
 
 	void adjoin(bool flag)
 	{
@@ -109,6 +111,13 @@ class Options
 		return imageInfo.colorspace;
 	}
 
+	/**
+	 * Specifies the type of compression used when writing the image.
+	 * Only some image formats support compression. For those that do,
+	 * only some compression types are supported. If you specify an
+	 * compression type that is not supported, the default compression
+	 * type (usually NoCompression) is used instead.
+	 */
 	void compression(CompressionType compress)
 	{
 		imageInfo.compression = compress;
@@ -127,6 +136,14 @@ class Options
 	//
 	//}
 
+	/**
+	 * Specifies the vertical and horizontal resolution in pixels.
+	 * The default density is "72.0x72.0". This attribute can be used
+	 * when writing JBIG, PCL, PS, PS2, and PS3 format images.
+	 * 
+	 * This attribute can also be used to specify the width and height
+	 * of HISTOGRAM format images. For HISTOGRAM, the default is 256x200.
+	 */
 	void density(string str)
 	{
 		copyString(imageInfo.density, str);
@@ -136,6 +153,13 @@ class Options
 		return to!(string)(imageInfo.density);
 	}
 
+	/**
+	 * Specifies the image depth
+	 * 
+	 * Either 8, 16, or 32. You can specify 16 and 32
+	 * only when ImageMagick was compiled with a QuantumDepth
+	 * that allows these depth values.
+	 */
 	void depth(size_t d)
 	{
 		imageInfo.depth = d;
@@ -145,6 +169,15 @@ class Options
 		return imageInfo.depth;
 	}
 
+	/**
+	 * This attribute can be used when writing GIF images.
+	 * 
+	 * Apply Floyd/Steinberg error diffusion to the image.
+	 * The basic strategy of dithering is to trade intensity
+	 * resolution for spatial resolution by averaging the intensities
+	 * of several neighboring pixels. Images which suffer from severe
+	 * contouring when reducing colors can be improved with this option.
+	 */
 	void dither(bool d)
 	{
 		imageInfo.dither = d;
@@ -154,6 +187,9 @@ class Options
 		return imageInfo.dither;
 	}
 
+	/**
+	 * Specify the endianess of the image when reading the image file.
+	 */
 	void endian(EndianType type)
 	{
 		imageInfo.endian = type;
@@ -163,6 +199,9 @@ class Options
 		return imageInfo.endian;
 	}
 
+	/**
+	 * Image file descriptor.
+	 */
 	void file(FILE* f)
 	{
 		imageInfo.file = f;
@@ -172,6 +211,9 @@ class Options
 		return imageInfo.file;
 	}
 
+	/**
+	 * Image filename/path.
+	 */
 	void filename(string str)
 	{
 		copyString(imageInfo.filename, str);
@@ -181,6 +223,12 @@ class Options
 		return imageInfo.filename[0 .. strlen(imageInfo.filename.ptr)].idup;
 	}
 
+	/**
+	 * Text rendering font. If the font is a fully qualified
+	 * X server font name, the font is obtained from an X  server.
+	 * To use a TrueType font, precede the TrueType filename with an @.
+	 * Otherwise, specify  a  Postscript font name (e.g. "helvetica")
+	 */
 	void font(string str)
 	{
 		copyString(imageInfo.font, str);
@@ -191,6 +239,12 @@ class Options
 		return to!(string)(drawInfo.font);
 	}
 
+	/**
+	 * Colors within this distance are considered equal. 
+	 * A number of algorithms search for a target  color.
+	 * By default the color must be exact. Use this option to match
+	 * colors that are close to the target color in RGB space.
+	 */
 	void fuzz(double f)
 	{
 		imageInfo.fuzz = f;
@@ -200,6 +254,16 @@ class Options
 		return imageInfo.fuzz;
 	}
 
+	/**
+	 * Specify the type of interlacing scheme for raw image formats
+	 * such as RGB or YUV. NoInterlace means do not interlace,
+	 * LineInterlace uses scanline interlacing, and PlaneInterlace
+	 * uses plane interlacing. PartitionInterlace is like PlaneInterlace
+	 * except the different planes are saved to individual files
+	 * (e.g. image.R, image.G, and image.B). Use LineInterlace or
+	 * PlaneInterlace to create an interlaced GIF or
+	 * progressive JPEG image. The default is NoInterlace.
+	 */
 	void interlace(InterlaceType type)
 	{
 		imageInfo.interlace = type;
@@ -209,6 +273,9 @@ class Options
 		return imageInfo.interlace;
 	}
 
+	/**
+	 * Image format (e.g. "GIF")
+	 */
 	void magick(string str)
 	{
 		copyString(imageInfo.magick, str);
@@ -227,6 +294,10 @@ class Options
 	//
 	//}
 
+	/**
+	 * Transform the image to black and white on input.
+	 * Only the EPT, PDF, and PS formats respect this attribute.
+	 */
 	void monochrome(bool m)
 	{
 		imageInfo.monochrome = m;
@@ -236,15 +307,15 @@ class Options
 		return imageInfo.monochrome;
 	}
 
-	void numberOfScenes(size_t num)
-	{
-		imageInfo.number_scenes = num;
-	}
-	size_t numberOfScenes()
-	{
-		return imageInfo.number_scenes;
-	}
-
+	/**
+	 * Use this option to specify the dimensions and position
+	 * of the Postscript page in dots per inch or in pixels.
+	 * This option is typically used in concert with density.
+	 * 
+	 * Page may also be used to position a GIF image
+	 * (such as for a scene in an animation)
+	 * The default is "612x792"
+	 */
 	void page(string str)
 	{
 		copyString(imageInfo.page, str);
@@ -254,6 +325,9 @@ class Options
 		return to!(string)(imageInfo.page);
 	}
 
+	/**
+	 * Text rendering font point size
+	 */
 	void pointSize(double size)
 	{
 		imageInfo.pointsize = size;
@@ -264,6 +338,11 @@ class Options
 		return drawInfo.pointsize;
 	}
 
+	/**
+	 * The compression level for JPEG, MPEG, JPEG-2000,
+	 * MIFF, MNG, and PNG image format.
+	 * The default is 75
+	 */
 	void quality(size_t q)
 	{
 		imageInfo.quality = q;
@@ -273,6 +352,9 @@ class Options
 		return imageInfo.quality;
 	}
 
+	/**
+	 * Units of image resolution.
+	 */
 	void resolutionUnits(ResolutionType type)
 	{
 		imageInfo.units = type;
@@ -282,6 +364,17 @@ class Options
 		return imageInfo.units;
 	}
 
+	/**
+	 * sampling factors used by JPEG or MPEG-2 encoder and
+	 * YUV decoder/encoder.
+	 * 
+	 * This attribute specifies the sampling factors to be used
+	 * by the JPEG encoder for chroma downsampling.
+	 * If this attribute is omitted, the JPEG library will use its
+	 * own default values. When reading or writing the YUV format and
+	 * when writing the M2V (MPEG-2) format, use sampling-factor="2x1"
+	 * to specify the 4:2:2 downsampling method.
+	 */
 	void samplingFactor(string str)
 	{
 		copyString(imageInfo.sampling_factor, str);
@@ -291,24 +384,48 @@ class Options
 		return to!(string)(imageInfo.sampling_factor);
 	}
 
-	void scene(size_t num)
+	/**
+	 * Set the width and height of the image when reading a
+	 * built-in image format that does not have an inherent size,
+	 * or when reading an image from a multi-resolution file format
+	 * such as Photo CD, JBIG, or JPEG.
+	 */
+	void size(string str)
+	{
+		copyString(imageInfo.size, str);
+	}
+	string size()
+	{
+		return to!(string)(imageInfo.size);
+	}
+
+	/**
+	 * Subimage of an image sequence
+	 */
+	void subImage(size_t num)
 	{
 		imageInfo.scene = num;
 	}
-	size_t scene()
+	size_t subImage()
 	{
 		return imageInfo.scene;
 	}
 
-	void size(string str)
+	/**
+	 * Number of images relative to the base image
+	 */
+	void subRange(size_t num)
 	{
-		copyString(imageInfo.size, str);
+		imageInfo.number_scenes = num;
 	}
-	string size()
+	size_t subRange()
 	{
-		return to!(string)(imageInfo.size);
+		return imageInfo.number_scenes;
 	}
 
+	/**
+	 * Image type.
+	 */
 	void type(ImageType t)
 	{
 		imageInfo.type = t;
@@ -318,6 +435,9 @@ class Options
 		return imageInfo.type;
 	}
 
+	/**
+	 * Print detailed information about the image.
+	 */
 	void verbose(bool v)
 	{
 		imageInfo.verbose = v;
@@ -327,6 +447,9 @@ class Options
 		return imageInfo.verbose;
 	}
 
+	/**
+	 * FlashPix viewing parameters.
+	 */
 	void view(string str)
 	{
 		copyString(imageInfo.view, str);
@@ -336,6 +459,9 @@ class Options
 		return to!(string)(imageInfo.view);
 	}
 
+	/**
+	 * Image virtual pixel method.
+	 */
 	//TODO: Delegates?
 	void virtualPixelMethod(VirtualPixelMethod method)
 	{
@@ -346,6 +472,9 @@ class Options
 		return imageInfo.virtual_pixel_method;
 	}
 
+	/**
+	 * X11 display to display to obtain fonts from or, to capture image from.
+	 */
 	void x11Display(string str)
 	{
 		copyString(imageInfo.server_name, str);
@@ -355,32 +484,36 @@ class Options
 		return to!(string)(imageInfo.server_name);
 	}
 
-	////OrientationType orientation;
-	////MagickBooleanType temporary,
-	////MagickBooleanType affirm,
-	////MagickBooleanType antialias;
-	////char* extract,
-	////char* scenes;
-	////size_t colors;
-	////PreviewType preview_type;
-	////ssize_t group;
-	////MagickBooleanType ping,
-	////char* authenticate;
-	////ChannelType channel;
-	////void* options;
-	////MagickProgressMonitor progress_monitor;
-	////void* client_data,
-	////void* cache;
-	////StreamHandler stream;
-	////void* blob;
-	////size_t length;
-	////char[MaxTextExtent] unique,
-	////char[MaxTextExtent] zero,
-	////size_t signature;
-	////PixelPacket transparent_color;
-	////void* profile;
-	////MagickBooleanType synchronize;
+	//OrientationType orientation;
+	//MagickBooleanType temporary,
+	//MagickBooleanType affirm,
+	//MagickBooleanType antialias;
+	//char* extract,
+	//char* scenes;
+	//size_t colors;
+	//PreviewType preview_type;
+	//ssize_t group;
+	//MagickBooleanType ping,
+	//char* authenticate;
+	//ChannelType channel;
+	//void* options;
+	//MagickProgressMonitor progress_monitor;
+	//void* client_data,
+	//void* cache;
+	//StreamHandler stream;
+	//void* blob;
+	//size_t length;
+	//char[MaxTextExtent] unique,
+	//char[MaxTextExtent] zero,
+	//size_t signature;
+	//PixelPacket transparent_color;
+	//void* profile;
+	//MagickBooleanType synchronize;
 
+	/**
+	 * Copy a string into a static array used
+	 * by ImageMagick for some atributes.
+	 */
 	private void copyString(ref char[MaxTextExtent] dest, string source)
 	{
 		if ( source.length < MaxTextExtent )
@@ -391,9 +524,11 @@ class Options
 	}
 
 	/**
-	 * Using CloneString whould force us to append a \0
-	 * to the end of the string which might relocate the sting,
-	 * and that is wastefull if we are just going to copy it.
+	 * Our implementation of ImageMagick's CloneString.
+	 *
+	 * We use this since using CloneString forces us to
+	 * append a \0 to the end of the string, and the realocation
+	 * whould be wastefull if we are just going to copy it
 	 */
 	private void copyString(ref char* dest, string source)
 	{