#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);
- if (wand->quantize_info != (QuantizeInfo *) NULL )
- wand->quantize_info=DestroyQuantizeInfo(wand->quantize_info);
- if (wand->draw_info != (DrawInfo *) NULL )
- wand->draw_info=DestroyDrawInfo(wand->draw_info);
wand->image_info=AcquireImageInfo();
+ wand->insert_before=MagickFalse;
+ wand->image_pending=MagickFalse;
ClearMagickException(wand->exception);
wand->debug=IsEventLogging();
}
clone_wand->exception=AcquireExceptionInfo();
InheritException(clone_wand->exception,wand->exception);
clone_wand->image_info=CloneImageInfo(wand->image_info);
- if ( wand->quantize_info == (QuantizeInfo *) NULL )
- clone_wand->quantize_info=(QuantizeInfo *) NULL;
- else
- clone_wand->quantize_info=CloneQuantizeInfo(wand->quantize_info);
- if ( wand->draw_info == (DrawInfo *) NULL )
- clone_wand->draw_info=(DrawInfo *) NULL;
- else
- clone_wand->draw_info=CloneDrawInfo(wand->image_info,wand->draw_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);
assert(wand->signature == WandSignature);
if (wand->debug != MagickFalse)
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
- if (wand->quantize_info != (QuantizeInfo *) NULL )
- wand->quantize_info=DestroyQuantizeInfo(wand->quantize_info);
- if (wand->draw_info != (DrawInfo *) NULL )
- wand->draw_info=DestroyDrawInfo(wand->draw_info);
- wand->image_info=DestroyImageInfo(wand->image_info);
wand->images=DestroyImageList(wand->images);
- wand->exception=DestroyExceptionInfo(wand->exception);
+ if (wand->image_info != (ImageInfo *) NULL )
+ wand->image_info=DestroyImageInfo(wand->image_info);
+ if (wand->exception != (ExceptionInfo *) NULL )
+ wand->exception=DestroyExceptionInfo(wand->exception);
RelinquishWandId(wand->id);
wand->signature=(~WandSignature);
wand=(MagickWand *) RelinquishMagickMemory(wand);
if (description == (char *) NULL)
{
(void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
- "MemoryAllocationFailed","`%s'",wand->name);
+ "MemoryAllocationFailed","'%s'",wand->name);
return((char *) NULL);
}
*description='\0';
% %
% %
% %
-% M a g i c k G e t E x c e p t i o n T y p e %
+% M a g i c k G e t E x c e p t i o n T y p e %
% %
% %
% %
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:
%
if (wand->debug != MagickFalse)
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
wand->images=GetFirstImageInList(wand->images);
- wand->set_first=MagickFalse; /* we did not jump to the first image */
- wand->image_pending=MagickTrue; /* this image is the 'next' image */
+ wand->insert_before=MagickFalse; /* Insert/add after current (first) image */
+ wand->image_pending=MagickTrue; /* NextImage will set first image */
}
\f
/*
%
% MagickSetFirstIterator() sets the wand iterator to the first image.
%
+% 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:
%
% void MagickSetFirstIterator(MagickWand *wand)
if (wand->debug != MagickFalse)
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
wand->images=GetFirstImageInList(wand->images);
- wand->set_first=MagickTrue; /* we jumped to the first image */
- wand->image_pending=MagickFalse; /* but this image is not 'next' */
+ wand->insert_before=MagickTrue; /* Insert/add before the first image */
+ wand->image_pending=MagickFalse; /* NextImage will set next image */
}
\f
/*
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
-% 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->set_first=MagickFalse; /* we are not at very start of list */
- wand->image_pending=MagickFalse; /* but it is not iteration pending */
+ wand->insert_before=MagickFalse; /* Insert/Add after (this) image */
+ wand->image_pending=MagickFalse; /* NextImage will set next image */
return(MagickTrue);
}
/*
%
% MagickSetLastIterator() sets the wand iterator to the last image.
%
+% 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 MagickSetLastIterator(MagickWand *wand)
if (wand->debug != MagickFalse)
(void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
wand->images=GetLastImageInList(wand->images);
- wand->set_first=MagickFalse; /* we are not at very start of list */
- wand->image_pending=MagickFalse; /* and is not iteration pending */
+ wand->insert_before=MagickFalse; /* Insert/add after current (last) image */
+ wand->image_pending=MagickTrue; /* PreviousImage will return last image */
}
\f
/*
(double) wand->id);
wand->images=NewImageList();
wand->image_info=AcquireImageInfo();
- wand->quantize_info=(QuantizeInfo *) NULL; /* not used in MagickWand API */
- wand->draw_info=(DrawInfo *) NULL; /* not used in MagickWand API */
wand->exception=AcquireExceptionInfo();
wand->debug=IsEventLogging();
if (wand->debug != MagickFalse)