% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
%
% 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)
{
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% 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:
%
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
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;
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
%
% 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:
%
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
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;
%
% 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:
%
(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 */
}
\f
/*
projects / imagemagick / commitdiff