From: anthony Date: Fri, 16 Mar 2012 08:25:58 +0000 (+0000) Subject: MagickWand function documentation X-Git-Tag: 7.0.1-0~6034 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f93964e21c9969b8c7a86c3ca5b62def79bf047b;p=imagemagick MagickWand function documentation --- diff --git a/MagickWand/magick-image.c b/MagickWand/magick-image.c index 278edb95b..d51c003f2 100644 --- a/MagickWand/magick-image.c +++ b/MagickWand/magick-image.c @@ -372,19 +372,21 @@ WandExport MagickBooleanType MagickAdaptiveThresholdImage(MagickWand *wand, % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% MagickAddImage() adds a clone of the images in the second wand and -% inserts them into the first wand, at the current image location. +% MagickAddImage() adds a clone of the images from the second wand and +% inserts them into the first wand. % % Use MagickSetLastIterator(), to append new images into an existing wand, % current image will be set to last image so later adds with also be % appened to end of wand. % -% Use MagickSetFirstIterator() to prepend new images into wand. Later images -% added will also be prepended. +% Use MagickSetFirstIterator() to prepend new images into wand, any more +% images added will also be prepended before other images in the wand. +% However the order of a list of new images will not change. % % Otherwise the new images will be inserted just after the current image, -% and later image will also be added after current image but before the -% just added images. +% and any later image will also be added after this current image but +% before the previously added images. Caution is advised when multiple +% image adds are inserted into the middle of the wand image list. % % The format of the MagickAddImage method is: % @@ -395,10 +397,9 @@ WandExport MagickBooleanType MagickAdaptiveThresholdImage(MagickWand *wand, % % o wand: the magick wand. % -% o add_wand: A wand that contains image list to be added +% o add_wand: A wand that contains the image list to be added % */ - static inline MagickBooleanType InsertImageInWand(MagickWand *wand, Image *images) { @@ -677,7 +678,13 @@ WandExport MagickBooleanType MagickAnimateImages(MagickWand *wand, % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% MagickAppendImages() append a set of images. +% MagickAppendImages() append the images in a wand from the current image +% onwards, creating a new wand with the single image result. This is +% affected by the gravity and background settings of the first image. +% +% Typically you would call either MagickResetIterator() or +% MagickSetFirstImage() before calling this function to ensure that all +% the images in the wand's image list will be appended together. % % The format of the MagickAppendImages method is: % @@ -6833,12 +6840,19 @@ WandExport MagickBooleanType MagickNewImage(MagickWand *wand,const size_t width, %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % MagickNextImage() sets the next image in the wand as the current image. -% It returns MagickTrue if their is another image to be processed. % -% Returns MagickFalse when current image is already the last image -% in the wand (no more next images), at whcih point you can use -% MagickPreviousImage() to again iterate over the images in the reverse -% direction, starting with the last image (again). +% It is typically used after MagickResetIterator(), after which its first use +% will set the first image as the current image (unless the wand is empty). +% +% It will return MagickFalse when no more images are left to be returned +% which happens when the wand is empty, or the current image is the last +% image. +% +% When the above condition (end of image list) is reached, the iterator is +% automaticall set so that you can start using MagickPreviousImage() to +% again iterate over the images in the reverse direction, starting with the +% last image (again). You can jump to this condition immeditally using +% MagickSetLastIterator(). % % The format of the MagickNextImage method is: % @@ -7434,13 +7448,21 @@ WandExport MagickWand *MagickPreviewImages(MagickWand *wand, % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% MagickPreviousImage() assocates the previous image in an image list with -% the magick wand. +% MagickPreviousImage() sets the previous image in the wand as the current +% image. +% +% It is typically used after MagickSetLastIterator(), after which its first +% use will set the last image as the current image (unless the wand is empty). +% +% It will return MagickFalse when no more images are left to be returned +% which happens when the wand is empty, or the current image is the first +% image. At that point the iterator is than reset to again process images in +% the forward direction, again starting with the first image in list. Images +% added at this point are prepended. % -% Returns MagickFalse when current image is the first image (no more previous -% images). The Iterator is than reset (as per MagickResetIterator()) ready -% to again process images in the forward direction, again starting with the -% first image in list. Images added at this point are prepended. +% Also at that point any images added to the wand using MagickAddImages() or +% MagickReadImages() will be prepended before the first image. In this sense +% the condition is not quite exactly the same as MagickResetIterator(). % % The format of the MagickPreviousImage method is: % diff --git a/MagickWand/magick-wand.c b/MagickWand/magick-wand.c index cc44b0c5d..dc91a5cd7 100644 --- a/MagickWand/magick-wand.c +++ b/MagickWand/magick-wand.c @@ -90,6 +90,7 @@ WandExport void ClearMagickWand(MagickWand *wand) assert(wand->signature == WandSignature); if (wand->debug != MagickFalse) (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name); + wand->image_info=DestroyImageInfo(wand->image_info); wand->images=DestroyImageList(wand->images); wand->image_info=AcquireImageInfo(); wand->insert_before=MagickFalse; @@ -809,9 +810,17 @@ WandExport void *MagickRelinquishMemory(void *memory) % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% MagickResetIterator() resets the wand iterator. Use it in conjunction -% with MagickNextImage() to iterate over all the images in a wand -% container. +% MagickResetIterator() resets the wand iterator. +% +% It is typically used either before iterating though images, or before +% calling specific functions such as MagickAppendImages() to append all +% images together. +% +% Afterward you can use MagickNextImage() to iterate over all the images +% in a wand container, starting with the first image. +% +% Using this before MagickAddImages() or MagickReadImages() will cause +% new images to be inserted between the first and second image. % % The format of the MagickResetIterator method is: % @@ -846,9 +855,16 @@ WandExport void MagickResetIterator(MagickWand *wand) % % MagickSetFirstIterator() sets the wand iterator to the first image. % -% Flags are set to point not only to the 'next' image to be processed, -% but also sets that MagickAddImage() (such as from MagickReadImage()) -% should add prepend images. +% After using any images added to the wand using MagickAddImage() or +% MagickReadImage() will be prepended before any image in the wand. +% +% Also the current image has been set to the first image (if any) in the +% Magick Wand. Using MagickNextImage() will then set teh current image +% to the second image in the list (if present). +% +% This operation is similar to MagickResetIterator() but differs in how +% MagickAddImage(), MagickReadImage(), and MagickNextImage() behaves +% afterward. % % The format of the MagickSetFirstIterator method is: % @@ -881,8 +897,23 @@ WandExport void MagickSetFirstIterator(MagickWand *wand) % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% MagickSetIteratorIndex() set the iterator to the position in the image list -% specified with the index parameter. +% MagickSetIteratorIndex() set the iterator to the given position in the +% image list specified with the index parameter. A zero index will set +% the first image as current, and so on. Negative indexes can be used +% to specify an image relative to the end of the images in the wand, with +% -1 being the last image in the wand. +% +% If the index is invalid (range too large for number of images in wand) +% the function will return magickFalse, but no 'exception' will be raised, +% as it is not actually an error. In that case the current image will not +% change. +% +% After using any images added to the wand using MagickAddImage() or +% MagickReadImage() will be added after the image indexed, regardless +% of if a zero (first image in list) or negative index (from end) is used. +% +% Jumping to index 0 is similar to MagickResetIterator() but differs in how +% MagickNextImage() behaves afterward. % % The format of the MagickSetIteratorIndex method is: % @@ -911,8 +942,7 @@ WandExport MagickBooleanType MagickSetIteratorIndex(MagickWand *wand, image=GetImageFromList(wand->images,index); if (image == (Image *) NULL) { - (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError, - "NoSuchImage","`%s'",wand->name); + InheritException(wand->exception,&wand->images->exception); return(MagickFalse); } wand->images=image; @@ -933,9 +963,14 @@ WandExport MagickBooleanType MagickSetIteratorIndex(MagickWand *wand, % % MagickSetLastIterator() sets the wand iterator to the last image. % -% Flags are set to point not only to the 'previous' image to be processed, -% but also define where InsertImageInWand() (such as from MagickReadImage()) -% should instert new images. +% The last image is actually the current image, and the next use of +% MagickPreviousImage() will not change this allowing this function to be +% used to iterate over the images in the reverse direction. In this sense it +% is more like MagickResetIterator() than MagickSetFirstIterator(). +% +% Typically this function is used before MagickAddImage(), MagickReadImage() +% functions to ensure new images are appended to the very end of wand's image +% list. % % The format of the MagickSetLastIterator method is: % @@ -954,7 +989,7 @@ WandExport void MagickSetLastIterator(MagickWand *wand) (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name); wand->images=GetLastImageInList(wand->images); wand->insert_before=MagickFalse; /* Insert/add after current (last) image */ - wand->image_pending=MagickFalse; /* PreviousImage will set previous image */ + wand->image_pending=MagickTrue; /* PreviousImage will return last image */ } /*