2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
6 % M M AAA GGGG IIIII CCCC K K %
7 % MM MM A A G I C K K %
8 % M M M AAAAA G GGG I C KKK %
9 % M M A A G G I C K K %
10 % M M A A GGGG IIIII CCCC K K %
14 % W W W AAAAA N N N D D %
15 % WW WW A A N NN D D %
19 % MagickWand Wand Methods %
26 % Copyright 1999-2019 ImageMagick Studio LLC, a non-profit organization %
27 % dedicated to making software imaging solutions freely available. %
29 % You may not use this file except in compliance with the License. You may %
30 % obtain a copy of the License at %
32 % https://imagemagick.org/script/license.php %
34 % Unless required by applicable law or agreed to in writing, software %
35 % distributed under the License is distributed on an "AS IS" BASIS, %
36 % WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. %
37 % See the License for the specific language governing permissions and %
38 % limitations under the License. %
40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
49 #include "MagickWand/studio.h"
50 #include "MagickWand/MagickWand.h"
51 #include "MagickWand/magick-wand-private.h"
52 #include "MagickWand/wand.h"
55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59 % C l e a r M a g i c k W a n d %
63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
65 % ClearMagickWand() clears resources associated with the wand, leaving the
66 % wand blank, and ready to be used for a new set of images.
68 % The format of the ClearMagickWand method is:
70 % void ClearMagickWand(MagickWand *wand)
72 % A description of each parameter follows:
74 % o wand: the magick wand.
77 WandExport void ClearMagickWand(MagickWand *wand)
79 assert(wand != (MagickWand *) NULL);
80 assert(wand->signature == MagickWandSignature);
81 if (wand->debug != MagickFalse)
82 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
83 wand->image_info=DestroyImageInfo(wand->image_info);
84 wand->images=DestroyImageList(wand->images);
85 wand->image_info=AcquireImageInfo();
86 wand->insert_before=MagickFalse;
87 wand->image_pending=MagickFalse;
88 ClearMagickException(wand->exception);
89 wand->debug=IsEventLogging();
93 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
97 % C l o n e M a g i c k W a n d %
101 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
103 % CloneMagickWand() makes an exact copy of the specified wand.
105 % The format of the CloneMagickWand method is:
107 % MagickWand *CloneMagickWand(const MagickWand *wand)
109 % A description of each parameter follows:
111 % o wand: the magick wand.
114 WandExport MagickWand *CloneMagickWand(const MagickWand *wand)
119 assert(wand != (MagickWand *) NULL);
120 assert(wand->signature == MagickWandSignature);
121 if (wand->debug != MagickFalse)
122 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
123 clone_wand=(MagickWand *) AcquireMagickMemory(sizeof(*clone_wand));
124 if (clone_wand == (MagickWand *) NULL)
125 ThrowWandFatalException(ResourceLimitFatalError,"MemoryAllocationFailed",
127 (void) memset(clone_wand,0,sizeof(*clone_wand));
128 clone_wand->id=AcquireWandId();
129 (void) FormatLocaleString(clone_wand->name,MagickPathExtent,"%s-%.20g",
130 MagickWandId,(double) clone_wand->id);
131 clone_wand->exception=AcquireExceptionInfo();
132 InheritException(clone_wand->exception,wand->exception);
133 clone_wand->image_info=CloneImageInfo(wand->image_info);
134 clone_wand->images=CloneImageList(wand->images,clone_wand->exception);
135 clone_wand->insert_before=MagickFalse;
136 clone_wand->image_pending=MagickFalse;
137 clone_wand->debug=IsEventLogging();
138 if (clone_wand->debug != MagickFalse)
139 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",clone_wand->name);
140 clone_wand->signature=MagickWandSignature;
145 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
149 % D e s t r o y M a g i c k W a n d %
153 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
155 % DestroyMagickWand() deallocates memory associated with an MagickWand.
157 % The format of the DestroyMagickWand method is:
159 % MagickWand *DestroyMagickWand(MagickWand *wand)
161 % A description of each parameter follows:
163 % o wand: the magick wand.
166 WandExport MagickWand *DestroyMagickWand(MagickWand *wand)
168 assert(wand != (MagickWand *) NULL);
169 assert(wand->signature == MagickWandSignature);
170 if (wand->debug != MagickFalse)
171 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
172 wand->images=DestroyImageList(wand->images);
173 if (wand->image_info != (ImageInfo *) NULL )
174 wand->image_info=DestroyImageInfo(wand->image_info);
175 if (wand->exception != (ExceptionInfo *) NULL )
176 wand->exception=DestroyExceptionInfo(wand->exception);
177 RelinquishWandId(wand->id);
178 wand->signature=(~MagickWandSignature);
179 wand=(MagickWand *) RelinquishMagickMemory(wand);
184 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
188 % I s M a g i c k W a n d %
192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
194 % IsMagickWand() returns MagickTrue if the wand is verified as a magick wand.
196 % The format of the IsMagickWand method is:
198 % MagickBooleanType IsMagickWand(const MagickWand *wand)
200 % A description of each parameter follows:
202 % o wand: the magick wand.
205 WandExport MagickBooleanType IsMagickWand(const MagickWand *wand)
207 if (wand == (const MagickWand *) NULL)
209 if (wand->signature != MagickWandSignature)
211 if (LocaleNCompare(wand->name,MagickWandId,strlen(MagickWandId)) != 0)
217 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
221 % M a g i c k C l e a r E x c e p t i o n %
225 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
227 % MagickClearException() clears any exceptions associated with the wand.
229 % The format of the MagickClearException method is:
231 % MagickBooleanType MagickClearException(MagickWand *wand)
233 % A description of each parameter follows:
235 % o wand: the magick wand.
238 WandExport MagickBooleanType MagickClearException(MagickWand *wand)
240 assert(wand != (MagickWand *) NULL);
241 assert(wand->signature == MagickWandSignature);
242 if (wand->debug != MagickFalse)
243 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
244 ClearMagickException(wand->exception);
249 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
253 % M a g i c k G e t E x c e p t i o n %
257 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
259 % MagickGetException() returns the severity, reason, and description of any
260 % error that occurs when using other methods in this API.
262 % The format of the MagickGetException method is:
264 % char *MagickGetException(const MagickWand *wand,ExceptionType *severity)
266 % A description of each parameter follows:
268 % o wand: the magick wand.
270 % o severity: the severity of the error is returned here.
273 WandExport char *MagickGetException(const MagickWand *wand,
274 ExceptionType *severity)
279 assert(wand != (const MagickWand *) NULL);
280 assert(wand->signature == MagickWandSignature);
281 if (wand->debug != MagickFalse)
282 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
283 assert(severity != (ExceptionType *) NULL);
284 *severity=wand->exception->severity;
285 description=(char *) AcquireQuantumMemory(2UL*MagickPathExtent,
286 sizeof(*description));
287 if (description == (char *) NULL)
289 (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
290 "MemoryAllocationFailed","`%s'",wand->name);
291 return((char *) NULL);
294 if (wand->exception->reason != (char *) NULL)
295 (void) CopyMagickString(description,GetLocaleExceptionMessage(
296 wand->exception->severity,wand->exception->reason),MagickPathExtent);
297 if (wand->exception->description != (char *) NULL)
299 (void) ConcatenateMagickString(description," (",MagickPathExtent);
300 (void) ConcatenateMagickString(description,GetLocaleExceptionMessage(
301 wand->exception->severity,wand->exception->description),MagickPathExtent);
302 (void) ConcatenateMagickString(description,")",MagickPathExtent);
308 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
312 % M a g i c k G e t E x c e p t i o n T y p e %
316 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
318 % MagickGetExceptionType() returns the exception type associated with the
319 % wand. If no exception has occurred, UndefinedExceptionType is returned.
321 % The format of the MagickGetExceptionType method is:
323 % ExceptionType MagickGetExceptionType(const MagickWand *wand)
325 % A description of each parameter follows:
327 % o wand: the magick wand.
330 WandExport ExceptionType MagickGetExceptionType(const MagickWand *wand)
332 assert(wand != (MagickWand *) NULL);
333 assert(wand->signature == MagickWandSignature);
334 if (wand->debug != MagickFalse)
335 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
336 return(wand->exception->severity);
340 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
344 % M a g i c k G e t I t e r a t o r I n d e x %
348 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
350 % MagickGetIteratorIndex() returns the position of the iterator in the image
353 % The format of the MagickGetIteratorIndex method is:
355 % ssize_t MagickGetIteratorIndex(MagickWand *wand)
357 % A description of each parameter follows:
359 % o wand: the magick wand.
362 WandExport ssize_t MagickGetIteratorIndex(MagickWand *wand)
364 assert(wand != (MagickWand *) NULL);
365 assert(wand->signature == MagickWandSignature);
366 if (wand->debug != MagickFalse)
367 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
368 if (wand->images == (Image *) NULL)
370 (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
371 "ContainsNoIterators","`%s'",wand->name);
374 return(GetImageIndexInList(wand->images));
378 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
382 % M a g i c k Q u e r y C o n f i g u r e O p t i o n %
386 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
388 % MagickQueryConfigureOption() returns the value associated with the specified
391 % The format of the MagickQueryConfigureOption function is:
393 % char *MagickQueryConfigureOption(const char *option)
395 % A description of each parameter follows:
397 % o option: the option name.
400 WandExport char *MagickQueryConfigureOption(const char *option)
414 exception=AcquireExceptionInfo();
415 configure_info=GetConfigureInfoList(option,&number_options,exception);
416 exception=DestroyExceptionInfo(exception);
417 if (configure_info == (const ConfigureInfo **) NULL)
418 return((char *) NULL);
420 if (number_options != 0)
421 value=AcquireString(configure_info[0]->value);
422 configure_info=(const ConfigureInfo **)
423 RelinquishMagickMemory((void *) configure_info);
428 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
432 % M a g i c k Q u e r y C o n f i g u r e O p t i o n s %
436 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
438 % MagickQueryConfigureOptions() returns any configure options that match the
439 % specified pattern (e.g. "*" for all). Options include NAME, VERSION,
442 % The format of the MagickQueryConfigureOptions function is:
444 % char **MagickQueryConfigureOptions(const char *pattern,
445 % size_t *number_options)
447 % A description of each parameter follows:
449 % o pattern: Specifies a pointer to a text string containing a pattern.
451 % o number_options: Returns the number of configure options in the list.
455 WandExport char **MagickQueryConfigureOptions(const char *pattern,
456 size_t *number_options)
464 exception=AcquireExceptionInfo();
465 options=GetConfigureList(pattern,number_options,exception);
466 exception=DestroyExceptionInfo(exception);
471 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
475 % M a g i c k Q u e r y F o n t M e t r i c s %
479 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
481 % MagickQueryFontMetrics() returns a 13 element array representing the
482 % following font metrics:
484 % Element Description
485 % -------------------------------------------------
492 % 6 maximum horizontal advance
496 % 10 bounding box: y2
500 % The format of the MagickQueryFontMetrics method is:
502 % double *MagickQueryFontMetrics(MagickWand *wand,
503 % const DrawingWand *drawing_wand,const char *text)
505 % A description of each parameter follows:
507 % o wand: the Magick wand.
509 % o drawing_wand: the drawing wand.
514 WandExport double *MagickQueryFontMetrics(MagickWand *wand,
515 const DrawingWand *drawing_wand,const char *text)
529 assert(wand != (MagickWand *) NULL);
530 assert(wand->signature == MagickWandSignature);
531 if (wand->debug != MagickFalse)
532 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
533 assert(drawing_wand != (const DrawingWand *) NULL);
534 if (wand->images == (Image *) NULL)
536 (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
537 "ContainsNoImages","`%s'",wand->name);
538 return((double *) NULL);
540 font_metrics=(double *) AcquireQuantumMemory(13UL,sizeof(*font_metrics));
541 if (font_metrics == (double *) NULL)
542 return((double *) NULL);
543 draw_info=PeekDrawingWand(drawing_wand);
544 if (draw_info == (DrawInfo *) NULL)
546 font_metrics=(double *) RelinquishMagickMemory(font_metrics);
547 return((double *) NULL);
549 (void) CloneString(&draw_info->text,text);
550 (void) memset(&metrics,0,sizeof(metrics));
551 status=GetTypeMetrics(wand->images,draw_info,&metrics,wand->exception);
552 draw_info=DestroyDrawInfo(draw_info);
553 if (status == MagickFalse)
555 font_metrics=(double *) RelinquishMagickMemory(font_metrics);
556 return((double *) NULL);
558 font_metrics[0]=metrics.pixels_per_em.x;
559 font_metrics[1]=metrics.pixels_per_em.y;
560 font_metrics[2]=metrics.ascent;
561 font_metrics[3]=metrics.descent;
562 font_metrics[4]=metrics.width;
563 font_metrics[5]=metrics.height;
564 font_metrics[6]=metrics.max_advance;
565 font_metrics[7]=metrics.bounds.x1;
566 font_metrics[8]=metrics.bounds.y1;
567 font_metrics[9]=metrics.bounds.x2;
568 font_metrics[10]=metrics.bounds.y2;
569 font_metrics[11]=metrics.origin.x;
570 font_metrics[12]=metrics.origin.y;
571 return(font_metrics);
575 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
579 % M a g i c k Q u e r y M u l t i l i n e F o n t M e t r i c s %
583 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
585 % MagickQueryMultilineFontMetrics() returns a 13 element array representing the
586 % following font metrics:
588 % Element Description
589 % -------------------------------------------------
596 % 6 maximum horizontal advance
600 % 10 bounding box: y2
604 % This method is like MagickQueryFontMetrics() but it returns the maximum text
605 % width and height for multiple lines of text.
607 % The format of the MagickQueryFontMetrics method is:
609 % double *MagickQueryMultilineFontMetrics(MagickWand *wand,
610 % const DrawingWand *drawing_wand,const char *text)
612 % A description of each parameter follows:
614 % o wand: the Magick wand.
616 % o drawing_wand: the drawing wand.
621 WandExport double *MagickQueryMultilineFontMetrics(MagickWand *wand,
622 const DrawingWand *drawing_wand,const char *text)
636 assert(wand != (MagickWand *) NULL);
637 assert(wand->signature == MagickWandSignature);
638 if (wand->debug != MagickFalse)
639 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
640 assert(drawing_wand != (const DrawingWand *) NULL);
641 if (wand->images == (Image *) NULL)
643 (void) ThrowMagickException(wand->exception,GetMagickModule(),WandError,
644 "ContainsNoImages","`%s'",wand->name);
645 return((double *) NULL);
647 font_metrics=(double *) AcquireQuantumMemory(13UL,sizeof(*font_metrics));
648 if (font_metrics == (double *) NULL)
649 return((double *) NULL);
650 draw_info=PeekDrawingWand(drawing_wand);
651 if (draw_info == (DrawInfo *) NULL)
653 font_metrics=(double *) RelinquishMagickMemory(font_metrics);
654 return((double *) NULL);
656 (void) CloneString(&draw_info->text,text);
657 (void) memset(&metrics,0,sizeof(metrics));
658 status=GetMultilineTypeMetrics(wand->images,draw_info,&metrics,
660 draw_info=DestroyDrawInfo(draw_info);
661 if (status == MagickFalse)
663 font_metrics=(double *) RelinquishMagickMemory(font_metrics);
664 return((double *) NULL);
666 font_metrics[0]=metrics.pixels_per_em.x;
667 font_metrics[1]=metrics.pixels_per_em.y;
668 font_metrics[2]=metrics.ascent;
669 font_metrics[3]=metrics.descent;
670 font_metrics[4]=metrics.width;
671 font_metrics[5]=metrics.height;
672 font_metrics[6]=metrics.max_advance;
673 font_metrics[7]=metrics.bounds.x1;
674 font_metrics[8]=metrics.bounds.y1;
675 font_metrics[9]=metrics.bounds.x2;
676 font_metrics[10]=metrics.bounds.y2;
677 font_metrics[11]=metrics.origin.x;
678 font_metrics[12]=metrics.origin.y;
679 return(font_metrics);
683 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
687 % M a g i c k Q u e r y F o n t s %
691 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
693 % MagickQueryFonts() returns any font that match the specified pattern (e.g.
696 % The format of the MagickQueryFonts function is:
698 % char **MagickQueryFonts(const char *pattern,size_t *number_fonts)
700 % A description of each parameter follows:
702 % o pattern: Specifies a pointer to a text string containing a pattern.
704 % o number_fonts: Returns the number of fonts in the list.
708 WandExport char **MagickQueryFonts(const char *pattern,
709 size_t *number_fonts)
717 exception=AcquireExceptionInfo();
718 fonts=GetTypeList(pattern,number_fonts,exception);
719 exception=DestroyExceptionInfo(exception);
724 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
728 % M a g i c k Q u e r y F o r m a t s %
732 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
734 % MagickQueryFormats() returns any image formats that match the specified
735 % pattern (e.g. "*" for all).
737 % The format of the MagickQueryFormats function is:
739 % char **MagickQueryFormats(const char *pattern,size_t *number_formats)
741 % A description of each parameter follows:
743 % o pattern: Specifies a pointer to a text string containing a pattern.
745 % o number_formats: This integer returns the number of image formats in the
749 WandExport char **MagickQueryFormats(const char *pattern,
750 size_t *number_formats)
758 exception=AcquireExceptionInfo();
759 formats=GetMagickList(pattern,number_formats,exception);
760 exception=DestroyExceptionInfo(exception);
765 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
769 % M a g i c k R e l i n q u i s h M e m o r y %
773 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
775 % MagickRelinquishMemory() relinquishes memory resources returned by such
776 % methods as MagickIdentifyImage(), MagickGetException(), etc.
778 % The format of the MagickRelinquishMemory method is:
780 % void *MagickRelinquishMemory(void *resource)
782 % A description of each parameter follows:
784 % o resource: Relinquish the memory associated with this resource.
787 WandExport void *MagickRelinquishMemory(void *memory)
789 (void) LogMagickEvent(TraceEvent,GetMagickModule(),"...");
790 return(RelinquishMagickMemory(memory));
794 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
798 % M a g i c k R e s e t I t e r a t o r %
802 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
804 % MagickResetIterator() resets the wand iterator.
806 % It is typically used either before iterating though images, or before
807 % calling specific functions such as MagickAppendImages() to append all
810 % Afterward you can use MagickNextImage() to iterate over all the images
811 % in a wand container, starting with the first image.
813 % Using this before MagickAddImages() or MagickReadImages() will cause
814 % new images to be inserted between the first and second image.
816 % The format of the MagickResetIterator method is:
818 % void MagickResetIterator(MagickWand *wand)
820 % A description of each parameter follows:
822 % o wand: the magick wand.
825 WandExport void MagickResetIterator(MagickWand *wand)
827 assert(wand != (MagickWand *) NULL);
828 assert(wand->signature == MagickWandSignature);
829 if (wand->debug != MagickFalse)
830 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
831 wand->images=GetFirstImageInList(wand->images);
832 wand->insert_before=MagickFalse; /* Insert/add after current (first) image */
833 wand->image_pending=MagickTrue; /* NextImage will set first image */
837 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
841 % M a g i c k S e t F i r s t I t e r a t o r %
845 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
847 % MagickSetFirstIterator() sets the wand iterator to the first image.
849 % After using any images added to the wand using MagickAddImage() or
850 % MagickReadImage() will be prepended before any image in the wand.
852 % Also the current image has been set to the first image (if any) in the
853 % Magick Wand. Using MagickNextImage() will then set teh current image
854 % to the second image in the list (if present).
856 % This operation is similar to MagickResetIterator() but differs in how
857 % MagickAddImage(), MagickReadImage(), and MagickNextImage() behaves
860 % The format of the MagickSetFirstIterator method is:
862 % void MagickSetFirstIterator(MagickWand *wand)
864 % A description of each parameter follows:
866 % o wand: the magick wand.
869 WandExport void MagickSetFirstIterator(MagickWand *wand)
871 assert(wand != (MagickWand *) NULL);
872 assert(wand->signature == MagickWandSignature);
873 if (wand->debug != MagickFalse)
874 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
875 wand->images=GetFirstImageInList(wand->images);
876 wand->insert_before=MagickTrue; /* Insert/add before the first image */
877 wand->image_pending=MagickFalse; /* NextImage will set next image */
881 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
885 % M a g i c k S e t I t e r a t o r I n d e x %
889 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
891 % MagickSetIteratorIndex() set the iterator to the given position in the
892 % image list specified with the index parameter. A zero index will set
893 % the first image as current, and so on. Negative indexes can be used
894 % to specify an image relative to the end of the images in the wand, with
895 % -1 being the last image in the wand.
897 % If the index is invalid (range too large for number of images in wand)
898 % the function will return MagickFalse, but no 'exception' will be raised,
899 % as it is not actually an error. In that case the current image will not
902 % After using any images added to the wand using MagickAddImage() or
903 % MagickReadImage() will be added after the image indexed, regardless
904 % of if a zero (first image in list) or negative index (from end) is used.
906 % Jumping to index 0 is similar to MagickResetIterator() but differs in how
907 % MagickNextImage() behaves afterward.
909 % The format of the MagickSetIteratorIndex method is:
911 % MagickBooleanType MagickSetIteratorIndex(MagickWand *wand,
912 % const ssize_t index)
914 % A description of each parameter follows:
916 % o wand: the magick wand.
918 % o index: the scene number.
921 WandExport MagickBooleanType MagickSetIteratorIndex(MagickWand *wand,
927 assert(wand != (MagickWand *) NULL);
928 assert(wand->signature == MagickWandSignature);
929 if (wand->debug != MagickFalse)
930 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
931 if (wand->images == (Image *) NULL)
933 image=GetImageFromList(wand->images,index);
934 if (image == (Image *) NULL)
935 return(MagickFalse); /* this is not an exception! Just range error. */
937 wand->insert_before=MagickFalse; /* Insert/Add after (this) image */
938 wand->image_pending=MagickFalse; /* NextImage will set next image */
942 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
946 % M a g i c k S e t L a s t I t e r a t o r %
950 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
952 % MagickSetLastIterator() sets the wand iterator to the last image.
954 % The last image is actually the current image, and the next use of
955 % MagickPreviousImage() will not change this allowing this function to be
956 % used to iterate over the images in the reverse direction. In this sense it
957 % is more like MagickResetIterator() than MagickSetFirstIterator().
959 % Typically this function is used before MagickAddImage(), MagickReadImage()
960 % functions to ensure new images are appended to the very end of wand's image
963 % The format of the MagickSetLastIterator method is:
965 % void MagickSetLastIterator(MagickWand *wand)
967 % A description of each parameter follows:
969 % o wand: the magick wand.
972 WandExport void MagickSetLastIterator(MagickWand *wand)
974 assert(wand != (MagickWand *) NULL);
975 assert(wand->signature == MagickWandSignature);
976 if (wand->debug != MagickFalse)
977 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
978 wand->images=GetLastImageInList(wand->images);
979 wand->insert_before=MagickFalse; /* Insert/add after current (last) image */
980 wand->image_pending=MagickTrue; /* PreviousImage will return last image */
984 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
988 % M a g i c k W a n d G e n e s i s %
992 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
994 % MagickWandGenesis() initializes the MagickWand environment.
996 % The format of the MagickWandGenesis method is:
998 % void MagickWandGenesis(void)
1001 WandExport void MagickWandGenesis(void)
1003 if (IsMagickCoreInstantiated() == MagickFalse)
1004 MagickCoreGenesis((char *) NULL,MagickFalse);
1008 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1012 % M a g i c k W a n d T e r m i n u s %
1016 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1018 % MagickWandTerminus() terminates the MagickWand environment.
1020 % The format of the MaickWandTerminus method is:
1022 % void MagickWandTerminus(void)
1025 WandExport void MagickWandTerminus(void)
1028 MagickCoreTerminus();
1032 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1036 % N e w M a g i c k W a n d %
1040 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1042 % NewMagickWand() returns a wand required for all other methods in the API.
1043 % A fatal exception is thrown if there is not enough memory to allocate the
1044 % wand. Use DestroyMagickWand() to dispose of the wand when it is no longer
1047 % The format of the NewMagickWand method is:
1049 % MagickWand *NewMagickWand(void)
1052 WandExport MagickWand *NewMagickWand(void)
1063 depth=MAGICKCORE_QUANTUM_DEPTH;
1064 quantum=GetMagickQuantumDepth(&depth);
1065 if (depth != MAGICKCORE_QUANTUM_DEPTH)
1066 ThrowWandFatalException(WandError,"QuantumDepthMismatch",quantum);
1067 wand=(MagickWand *) AcquireMagickMemory(sizeof(*wand));
1068 if (wand == (MagickWand *) NULL)
1069 ThrowWandFatalException(ResourceLimitFatalError,"MemoryAllocationFailed",
1070 GetExceptionMessage(errno));
1071 (void) memset(wand,0,sizeof(*wand));
1072 wand->id=AcquireWandId();
1073 (void) FormatLocaleString(wand->name,MagickPathExtent,"%s-%.20g",MagickWandId,
1075 wand->images=NewImageList();
1076 wand->image_info=AcquireImageInfo();
1077 wand->exception=AcquireExceptionInfo();
1078 wand->debug=IsEventLogging();
1079 if (wand->debug != MagickFalse)
1080 (void) LogMagickEvent(WandEvent,GetMagickModule(),"%s",wand->name);
1081 wand->signature=MagickWandSignature;
1086 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1090 % N e w M a g i c k W a n d F r o m I m a g e %
1094 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1096 % NewMagickWandFromImage() returns a wand with an image.
1098 % The format of the NewMagickWandFromImage method is:
1100 % MagickWand *NewMagickWandFromImage(const Image *image)
1102 % A description of each parameter follows:
1104 % o image: the image.
1107 WandExport MagickWand *NewMagickWandFromImage(const Image *image)
1112 wand=NewMagickWand();
1113 wand->images=CloneImage(image,0,0,MagickTrue,wand->exception);
1118 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1122 % I s M a g i c k W a n d I n s t a n t i a t e d %
1126 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1128 % IsMagickWandInstantiated() returns MagickTrue if the ImageMagick environment
1129 % is currently instantiated-- that is, MagickWandGenesis() has been called but
1130 % MagickWandTerminus() has not.
1132 % The format of the IsMagickWandInstantiated method is:
1134 % MagickBooleanType IsMagickWandInstantiated(void)
1137 MagickExport MagickBooleanType IsMagickWandInstantiated(void)
1139 return(IsMagickCoreInstantiated());