From 7fb35ecefdb79b77d8cde8bf2159bf9178dd4124 Mon Sep 17 00:00:00 2001 From: Mike Wey Date: Wed, 26 Oct 2011 00:02:18 +0200 Subject: Document some of the symbols used by DMagick. --- dmagick/Array.d | 9 ++- dmagick/c/geometry.d | 47 ++++++++------ dmagick/c/layer.d | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 213 insertions(+), 21 deletions(-) diff --git a/dmagick/Array.d b/dmagick/Array.d index 5d562ce..8ff60f7 100644 --- a/dmagick/Array.d +++ b/dmagick/Array.d @@ -268,9 +268,12 @@ Image[] morph(Image[] images, size_t frames) } /** - * compares each image the GIF disposed forms of the previous image in the - * sequence. From this it attempts to select the smallest cropped image to - * replace each frame, while preserving the results of the GIF animation. + * For each image compares the GIF disposed forms of the previous image in + * the sequence. From this it attempts to select the smallest cropped image + * to replace each frame, while preserving the results of the GIF animation. + * + * See_Also: $(LINK2 http://www.imagemagick.org/Usage/anim_opt/, + * Examples of ImageMagick Usage) */ Image[] optimizeLayers(Image[] images) { diff --git a/dmagick/c/geometry.d b/dmagick/c/geometry.d index 19a0035..780eae0 100644 --- a/dmagick/c/geometry.d +++ b/dmagick/c/geometry.d @@ -44,31 +44,42 @@ extern(C) AllValues = 0x7fffffff } + /** + * Specify positioning of an object (e.g. text, image) within a + * bounding region (e.g. an image). Gravity provides a convenient way to + * locate objects irrespective of the size of the bounding region, in + * other words, you don't need to provide absolute coordinates in order + * to position an object. + * A common default for gravity is NorthWestGravity. + */ enum GravityType { - UndefinedGravity, - ForgetGravity = 0, - NorthWestGravity = 1, - NorthGravity = 2, - NorthEastGravity = 3, - WestGravity = 4, - CenterGravity = 5, - EastGravity = 6, - SouthWestGravity = 7, - SouthGravity = 8, - SouthEastGravity = 9, - StaticGravity = 10 + UndefinedGravity, /// + ForgetGravity = 0, /// Don't use gravity. + NorthWestGravity = 1, /// Position object at top-left of region. + NorthGravity = 2, /// Position object at top-center of region. + NorthEastGravity = 3, /// Position object at top-right of region. + WestGravity = 4, /// Position object at left-center of region. + CenterGravity = 5, /// Position object at center of region. + EastGravity = 6, /// Position object at right-center of region. + SouthWestGravity = 7, /// Position object at left-bottom of region. + SouthGravity = 8, /// Position object at bottom-center of region. + SouthEastGravity = 9, /// Position object at bottom-right of region. + StaticGravity = 10 /// } + /** + * An AffineMatrix object describes a coordinate transformation. + */ struct AffineMatrix { double - sx, - rx, - ry, - sy, - tx, - ty; + sx, /// The amount of scaling on the x-axis. + rx, /// The amount of rotation on the x-axis, in radians. + ry, /// The amount of rotation on the y-axis, in radians. + sy, /// The amount of scaling on the y-axis. + tx, /// The amount of translation on the x-axis, in pixels. + ty; /// The amount of translation on the x-axis, in pixels. } struct GeometryInfo diff --git a/dmagick/c/layer.d b/dmagick/c/layer.d index ccf73b5..8928453 100644 --- a/dmagick/c/layer.d +++ b/dmagick/c/layer.d @@ -17,24 +17,202 @@ extern(C) PreviousDispose = 3 } + /** + * Determines image operation to apply to ordered sequence of images. + */ enum ImageLayerMethod { + /** */ UndefinedLayer, + + /** + * Apply the GIF disposal methods set in the current image sequence + * to form a fully defined animation sequence without, as it should + * be displayed. Effectively converting a GIF animation into + * a 'film strip' like animation. + */ CoalesceLayer, + + /** + * Crop the second and later frames to the smallest rectangle that + * contains all the differences between the two images. No GIF + * disposal methods are taken into account. + * + * This does not preserve a animation's normal working, especially + * when a animation used GIF disposal methods + * such as 'Previous' or 'Background'. + */ CompareAnyLayer, + + /** + * As CompareAnyLayer but crop to the bounds of any opaque pixels + * which become transparent in the second frame. That is the + * smallest image needed to mask or erase pixels for the next frame. + */ CompareClearLayer, + + /** + * As CompareAnyLayer but crop to pixels that add extra color to + * the next image, as a result of overlaying color pixels. That is + * the smallest single overlaid image to add or change colors. + * + * This can, be used with the -compose alpha composition method + * 'change-mask', to reduce the image to just the pixels that need + * to be overlaid. + */ CompareOverlayLayer, + + /** + * This is like CoalesceLayer but shows the look of the animation + * after the GIF disposal method has been applied, before the next + * sub-frame image is overlaid. That is the 'dispose' image that + * results from the application of the GIF disposal method. This + * allows you to check what is going wrong with a particular + * animation you may be developing. + */ DisposeLayer, + + /** + * Optimize a coalesced animation into GIF animation using a number + * of general techniques. This is currently a short cut to apply + * both the OptimizeImageLayer and OptimizeTransLayer methods + * but will expand to include other methods. + */ OptimizeLayer, + + /** + * Optimize a coalesced animation into GIF animation by reducing + * the number of pixels per frame as much as possible by attempting + * to pick the best GIF disposal method to use, while ensuring the + * result will continue to animate properly. + * + * There is no guarantee that the best optimization will be found. + * But then no reasonably fast GIF optimization algorithm can do + * this. However this does seem to do better than most other GIF + * frame optimizers seen. + */ OptimizeImageLayer, + + /** + * As OptimizeImageLayer but attempt to improve the overall + * optimization by adding extra frames to the animation, without + * changing the final look or timing of the animation. The frames + * are added to attempt to separate the clearing of pixels from the + * overlaying of new additional pixels from one animation frame to + * the next. If this does not improve the optimization (for the next + * frame only), it will fall back to the results of the previous + * normal OptimizeImageLayer technique. + * + * There is the possibility that the change in the disposal style + * will result in a worsening in the optimization of later frames, + * though this is unlikely. In other words there no guarantee that + * it is better than the normal 'optimize-frame' technique. + */ OptimizePlusLayer, + + /** + * Given a GIF animation, replace any pixel in the sub-frame overlay + * images with transparency, if it does not change the resulting + * animation by more than the current fuzz factor. + * + * This should allow a existing frame optimized GIF animation to + * compress into a smaller file size due to larger areas of one + * (transparent) color rather than a pattern of multiple colors + * repeating the current disposed image of the last frame. + */ OptimizeTransLayer, + + /** + * Remove (and merge time delays) of duplicate consecutive images, + * so as to simplify layer overlays of coalesced animations. Usually + * this is a result of using a constant time delay across the whole + * animation, or after a larger animation was split into smaller + * sub-animations. The duplicate frames could also have been used as + * part of some frame optimization methods. + */ RemoveDupsLayer, + + /** + * Remove any image with a zero time delay, unless ALL the images + * have a zero time delay (and is not a proper timed animation, a + * warning is then issued). In a GIF animation, such images are + * usually frames which provide partial intermediary updates between + * the frames that are actually displayed to users. These frames are + * usually added for improved frame optimization in GIF animations. + */ RemoveZeroLayer, + + /** + * Alpha Composition of two image lists, separated by a "null:" + * image, with the destination image list first, and the source + * images last. An image from each list are composited together + * until one list is finished. The separator image and source image + * lists are removed. + * + * The geometry offset is adjusted according to gravity in + * accordance of the virtual canvas size of the first image in each + * list. Unlike a normal composite operation, the canvas offset is + * also added to the final composite positioning of each image. + * + * If one of the image lists only contains one image, that image is + * applied to all the images in the other image list, regardless of + * which list it is. In this case it is the image meta-data of the + * list which preserved. + */ CompositeLayer, + + /** + * As FlattenLayer but merging all the given image layers into a + * new layer image just large enough to hold all the image without + * clipping or extra space. The new image's virtual offset will + * prevere the position of the new layer, even if this offset is + * negative. the virtual canvas size of the first image is preserved. + * + * Caution is advised when handling image layers with negative + * offsets as few image file formats handle them correctly. + */ MergeLayer, + + /** + * Create a canvas the size of the first images virtual canvas using + * the current background color, and compose each image in turn onto + * that canvas. Images falling outside that canvas will be clipped. + * Final image will have a zero virtual canvas offset. + * + * This is usually used as one of the final 'image layering' + * operations overlaying all the prepared image layers into a + * final image. + * + * For a single image this method can also be used to fillout a + * virtual canvas with real pixels, or to underlay a opaque color + * to remove transparency from an image. + */ FlattenLayer, + + /** + * As FlattenLayer but expanding the initial canvas size of the + * first image so as to hold all the image layers. However as a + * virtual canvas is 'locked' to the origin, by definition, image + * layers with a negative offsets will still be clipped by the top + * and left edges. + * + * This method is commonly used to layout individual image using + * various offset but without knowing the final canvas size. The + * resulting image will, like FlattenLayer not have any virtual + * offset, so can be saved to any image file format. This method + * corresponds to mosaic, above. + */ MosaicLayer, + + /** + * Find the minimal bounds of all the images in the current image + * sequence, then adjust the offsets so all images are contained + * on a minimal positive canvas. None of the image data is modified, + * only the virtual canvas size and offset. Then all the images will + * have the same canvas size, and all will have a positive offset, + * at least one image will touch every edge of that canvas with + * actual pixel data, though that data may be transparent. + */ TrimBoundsLayer } -- cgit v1.2.3