#define ThrowWandException(severity,tag,context) \
{ \
(void) ThrowMagickException(wand->exception,GetMagickModule(),severity, \
- tag,"`%s'",context); \
+ tag,"'%s'",context); \
return(MagickFalse); \
}
\f
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;
+ wand->image_pending=MagickFalse;
ClearMagickException(wand->exception);
wand->debug=IsEventLogging();
}
InheritException(clone_wand->exception,wand->exception);
clone_wand->image_info=CloneImageInfo(wand->image_info);
clone_wand->images=CloneImageList(wand->images,clone_wand->exception);
+ clone_wand->insert_before=MagickFalse;
+ clone_wand->image_pending=MagickFalse;
clone_wand->debug=IsEventLogging();
if (clone_wand->debug != MagickFalse)
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",clone_wand->name);
if (description == (char *) NULL)
{
(void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "MemoryAllocationFailed","`%s'",wand->name);
+ "MemoryAllocationFailed","'%s'",wand->name);
return((char *) NULL);
}
*description='\0';
if (wand->images == (Image *) NULL)
{
(void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "ContainsNoIterators","`%s'",wand->name);
+ "ContainsNoIterators","'%s'",wand->name);
return(-1);
}
return(GetImageIndexInList(wand->images));
if (wand->images == (Image *) NULL)
{
(void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "ContainsNoImages","`%s'",wand->name);
+ "ContainsNoImages","'%s'",wand->name);
return((double *) NULL);
}
font_metrics=(double *) AcquireQuantumMemory(13UL,sizeof(*font_metrics));
if (wand->images == (Image *) NULL)
{
(void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "ContainsNoImages","`%s'",wand->name);
+ "ContainsNoImages","'%s'",wand->name);
return((double *) NULL);
}
font_metrics=(double *) AcquireQuantumMemory(13UL,sizeof(*font_metrics));
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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:
%
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
wand->images=GetFirstImageInList(wand->images);
wand->insert_before=MagickFalse; /* Insert/add after current (first) image */
- wand->image_pending=MagickTrue; /* NextImage will remain this image */
+ wand->image_pending=MagickTrue; /* NextImage will set first image */
}
\f
/*
%
% 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:
%
return(MagickFalse);
image=GetImageFromList(wand->images,index);
if (image == (Image *) NULL)
- {
- (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "NoSuchImage","`%s'",wand->name);
- return(MagickFalse);
- }
+ return(MagickFalse); /* this is not an exception! Just range error. */
wand->images=image;
wand->insert_before=MagickFalse; /* Insert/Add after (this) image */
wand->image_pending=MagickFalse; /* NextImage will set next 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 / blobdiff