]> granicus.if.org Git - imagemagick/blob - www/api/constitute.html
(no commit message)
[imagemagick] / www / api / constitute.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
2   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html version="-//W3C//DTD XHTML 1.1//EN"
4       xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
5       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6       xsi:schemaLocation="http://www.w3.org/1999/xhtml
7                           http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
8 <head>
9   <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
10   <meta name="google-site-verification" content="MxsMq6bdLOx0KSuz1MY6yG9ZTIJ7_7DVRfl5NCAT5Yg"/>
11   <title>ImageMagick: MagickCore, C API for ImageMagick: Constitute an Image</title>
12   <meta http-equiv="content-language" content="en-US"/>
13   <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
14   <meta http-equiv="reply-to" content="magick-users@imagemagick.org"/>
15   <meta name="application-name" content="ImageMagick"/>
16   <meta name="description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats.  In addition resize, rotate, shear, distort and transform images automagically."/>
17   <meta name="application-url" content="http://www.imagemagick.org"/>
18   <meta name="generator" content="PHP"/>
19   <meta name="keywords" content="magickcore, c, api, for, imagemagick:, constitute, an, image, ImageMagick, PerlMagick, image processing, OpenMP, software development library, image, photo, software, Magick++, MagickWand"/>
20   <meta name="rating" content="GENERAL"/>
21   <meta name="robots" content="INDEX, FOLLOW"/>
22   <meta name="generator" content="ImageMagick Studio LLC"/>
23   <meta name="author" content="ImageMagick Studio LLC"/>
24   <meta name="revisit-after" content="2 DAYS"/>
25   <meta name="resource-type" content="document"/>
26   <meta name="copyright" content="Copyright (c) 1999-2013 ImageMagick Studio LLC"/>
27   <meta name="distribution" content="Global"/>
28   <link rel="icon" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/wand.png"/>
29   <link rel="shortcut icon" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/wand.ico"  type="images/x-icon"/>
30   <link rel="canonical" href="http://www.imagemagick.org" />
31   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
32   <!-- Add jQuery library -->
33   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
34   
35   <!-- Optionaly include easing and/or mousewheel plugins -->
36   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/jquery.easing-1.3.pack.js"></script>
37   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/jquery.mousewheel-3.0.6.pack.js"></script>
38   
39   <!-- Add fancyBox -->
40   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/jquery.fancybox.css?v=2.0.4" type="text/css" media="screen" />
41   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/jquery.fancybox.pack.js?v=2.0.4"></script>
42   
43   <!-- Optionaly include button and/or thumbnail helpers -->
44   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/helpers/jquery.fancybox-buttons.css?v=2.0.4" type="text/css" media="screen" />
45   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/helpers/jquery.fancybox-buttons.js?v=2.0.4"></script>
46   
47   <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/helpers/jquery.fancybox-thumbs.css?v=2.0.4" type="text/css" media="screen" />
48   <script type="text/javascript" src="http://www.imagemagick.org/fancybox/helpers/jquery.fancybox-thumbs.js?v=2.0.4"></script>
49   <script type="text/javascript">
50         $(document).ready(function() {
51                 $(".fancybox").fancybox();
52         });
53   </script>
54   <!-- ImageMagick style -->
55   <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />
56   <style type="text/css" media="all">
57     @import url("../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/magick.css");
58   </style>
59 </head>
60
61 <body id="www-imagemagick-org">
62 <div class="titlebar">
63 <div style="margin: 17px auto; float: left;">
64   <script type="text/javascript">
65   <!--
66     google_ad_client = "pub-3129977114552745";
67     google_ad_slot = "5439289906";
68     google_ad_width = 728;
69     google_ad_height = 90;
70   //-->
71   </script>
72   <script type="text/javascript"
73     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
74   </script>
75 </div>
76 <a href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../discourse-server">
77   <img src="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/logo.jpg"
78   alt="ImageMagick Logo"
79   style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
80 <a href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../index.html">
81   <img src="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/sprite.jpg"
82   alt="ImageMagick Sprite"
83   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
84 </div>
85
86 <div class="westbar">
87
88 <div class="menu">
89   <a title="About ImageMagick" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../index.html">About ImageMagick</a>
90 </div>
91 <div class="menu">
92   <a title="Binary Releases" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/binary-releases.html">Binary Releases</a>
93 </div>
94 <div class="sub">
95     <a title="Binary Release: Unix" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/binary-releases.html#unix">Unix</a>
96 </div>
97 <div class="sub">
98     <a title="Binary Release: MacOS X" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/binary-releases.html#macosx">Mac OS X</a>
99 </div>
100 <div class="sub">
101     <a title="Binary Release: iOS" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/binary-releases.html#iOS">iOS</a>
102 </div>
103 <div class="sub">
104     <a title="Binary Release: Windows" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/binary-releases.html#windows">Windows</a>
105 </div>
106 <div class="sep"></div>
107 <div class="menu">
108   <a title="Command-line Tools" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/command-line-tools.html">Command-line Tools</a>
109 </div>
110 <div class="sub">
111     <a title="Command-line Tools: Processing" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/command-line-processing.html">Processing</a>
112 </div>
113 <div class="sub">
114     <a title="Command-line Tools: Options" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/command-line-options.html">Options</a>
115 </div>
116 <div class="sub">
117     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
118 </div>
119 <div class="menu">
120   <a title="Program Interfaces" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/api.html">Program Interfaces</a>
121 </div>
122 <div class="sub">
123     <a title="Program Interface: MagickWand" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/magick-wand.html">MagickWand</a>
124 </div>
125 <div class="sub">
126     <a title="Program Interface: MagickCore" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/magick-core.html">MagickCore</a>
127 </div>
128 <div class="sub">
129     <a title="Program Interface: PerlMagick" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/perl-magick.html">PerlMagick</a>
130 </div>
131 <div class="sub">
132     <a title="Program Interface: Magick++" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/magick++.html">Magick++</a>
133 </div>
134 <div class="sep"></div>
135 <div  class="menu">
136    <a title="Install from Source" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/install-source.html">Install from Source</a>
137 </div>
138 <div class="sub">
139     <a title="Install from Source: Unix" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/install-source.html#unix">Unix</a>
140 </div>
141 <div class="sub">
142     <a title="Install from Source: Windows" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/install-source.html#windows">Windows</a>
143  </div>
144 <div class="menu">
145   <a title="Resources" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/resources.html">Resources</a>
146 </div>
147 <div class="menu">
148   <a title="Architecture" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/architecture.html">Architecture</a>
149 </div>
150 <div class="menu">
151   <a title="Download" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/download.html">Download</a>
152 </div>
153 <div class="sep"></div>
154 <div class="menu">
155   <a title="Search" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/search.html">Search</a>
156 </div>
157 <div class="sep"></div>
158 <div class="menu">
159   <a title="Site Map" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/sitemap.html">Site Map</a>
160 </div>
161 <div  class="sub">
162   <a title="Site Map: Links" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/links.html">Links</a>
163 </div>
164 <div class="sep"></div>
165 <div class="menu">
166   <a rel="follow" title="Sponsors" href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../www/sponsors.html">Sponsors:</a>
167
168   <a href="http://www.networkredux.com"> <img src="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/networkredux.png" width="140" height="31" alt="[sponsor]" style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
169   <a href="http://www.dinodirect.com/ipads-tablets/"> <img src="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../images/dino-direct.jpg" width="140" height="90" alt="[sponsor]" style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a><!-- 201208010120 mickey@163... -->
170 <div class="sponsbox">
171 <div class="sponsor">
172   <a rel="follow" title="Sponsor: The Fastest &amp; Easiest Way to Find Images" href="http://www.graphicsfactory.com">The Fastest &amp; Easiest Way to Find Images</a><!-- 201210010270 graphicsfac... -->
173 </div>
174 <div class="sponsor">
175   <a rel="follow" title="Sponsor: VPS" href="http://www.interdominios.com/vps">VPS</a><!-- 201209010090 barsh@inter... -->
176 </div>
177 <div class="sponsor">
178   <a rel="follow" title="Werbebanner Werbeplane" href="http://www.allesbanner.de">Werbebanner Werbeplane</a><!-- 201212010450 info@druck... -->
179 </div>
180 <div class="sponsor">
181   <a rel="follow" title="Entertainment News &amp; Photos" href="http://www.zimbio.com">Entertainment News &amp; Photos</a><!-- 201211010540 bd@zimb... -->
182 </div>
183 <div class="sponsor">
184   <a rel="follow" title="Sponsor: LED24" href="http://led24.de/">LED24</a><!-- 201207010270 info@led24... -->
185 </div>
186 <div class="sponsor">
187   <a rel="follow" title="Sponsor: Best Website Hosting" href="http://www.top-cheap-web-hosting.com">Best Website Hosting</a><!-- 201304010090 eunge.liu-->
188 </div>
189 <div class="sponsor">
190   <a rel="follow" title="Android Tablet" href="http://www.dinodirect.com/ipads-tablets/">Android Tablet</a><!-- 201208010120 mickey@163... -->
191 </div>
192 <div class="sponsor">
193   <a rel="follow" title="Sponsor: Web Site Hosting" href="http://webhostinggeeks.com">Web Site Hosting</a><!-- 201302010900 funds@enmob... -->
194 </div>
195 <div class="sponsor">
196    <a rel="follow" title="Sponsor: Premium Quality Stock Photos" href="http://www.f1online.pro/en/">Premium Quality Stock Photos</a><!-- 2012080100540 ... -->
197 </div>
198 <div class="sponsor">
199    <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 2012070100250 ... -->
200 </div>
201 <div class="sponsor">
202   <a rel="follow" title="Sponsor: Managed Server" href="http://www.robhost.de">Managed Server</a><!-- 201210010720 klikics... -->
203 </div>
204 <div class="sponsor">
205   <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
206 </div>
207 <div  class="sponsor">
208    <a rel="follow" title="Sponsor: Kaffeemaschinen reparatur" href="http://www.kaffeemaschinen-reparatur.de">Kaffeemaschinen reparatur</a><!-- 2012080100030 Temurbas atlas-multimedia-->
209 </div>
210 <div class="sponsor">
211    <a rel="follow" title="Sponsor: Web Hosting" href="http://www.hostucan.com">Web Hosting</a><!-- 2012120100150 racent marketing@webhosting...-->
212 </div>
213 </div>
214 </div>
215 </div>
216
217 <div class="eastbar">
218   <div class="g-plusone" id="gplusone"></div>
219   <script type="text/javascript">
220     window.___gcfg = {
221       lang: 'en-US'
222     };
223
224     (function() {
225       var po = document.createElement('script');
226       po.type = 'text/javascript'; po.async = true;
227       po.src = 'https://apis.google.com/js/plusone.js';
228       var script = document.getElementsByTagName('script')[0];
229       script.parentNode.insertBefore(po, script);
230     })();
231     var gplusone = document.getElementById("gplusone");
232     gplusone.setAttribute("data-size","medium");
233     gplusone.setAttribute("data-count","false");
234   </script>
235 </div>
236
237 <div class="main">
238
239 <h1>Module constitute Methods</h1>
240 <p class="navigation-index">[<a href="constitute.html#ConstituteImage">ConstituteImage</a> &bull; <a href="constitute.html#PingImage">PingImage</a> &bull; <a href="constitute.html#PingImages">PingImages</a> &bull; <a href="constitute.html#ReadImage">ReadImage</a> &bull; <a href="constitute.html#ReadImages">ReadImages</a> &bull; <a href="constitute.html#WriteImage">WriteImage</a> &bull; <a href="constitute.html#WriteImages">WriteImages</a>]</p>
241
242 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ConstituteImage">ConstituteImage</a></h2>
243 <div class="doc-section">
244
245 <p>ConstituteImage() returns an image from the pixel data you supply. The pixel data must be in scanline order top-to-bottom.  The data can be char, short int, int, float, or double.  Float and double require the pixels to be normalized [0..1], otherwise [0..QuantumRange].  For example, to create a 640x480 image from unsigned red-green-blue character data, use:</p>
246
247 <pre class="text">
248   image = ConstituteImage(640,480,"RGB",CharPixel,pixels,&exception);
249 </pre>
250
251 <p>The format of the ConstituteImage method is:</p>
252
253 <pre class="code">
254   Image *ConstituteImage(const size_t columns,const size_t rows,
255     const char *map,const StorageType storage,const void *pixels,
256     ExceptionInfo *exception)
257 </pre>
258
259 <p>A description of each parameter follows:</p>
260
261 <h5>columns</h5>
262 <p>width in pixels of the image.</p>
263
264 <h5>rows</h5>
265 <p>height in pixels of the image.</p>
266
267 <h5>map</h5>
268 <p>This string reflects the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha (0 is transparent), O = opacity (0 is opaque), C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), P = pad.</p>
269
270 <h5>storage</h5>
271 <p>Define the data type of the pixels.  Float and double types are expected to be normalized [0..1] otherwise [0..QuantumRange].  Choose from these types: CharPixel, DoublePixel, FloatPixel, IntegerPixel, LongPixel, QuantumPixel, or ShortPixel.</p>
272
273 <h5>pixels</h5>
274 <p>This array of values contain the pixel components as defined by map and type.  You must preallocate this array where the expected length varies depending on the values of width, height, map, and type.</p>
275
276 <h5>exception</h5>
277 <p>return any errors or warnings in this structure.</p>
278
279  </div>
280 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImage">PingImage</a></h2>
281 <div class="doc-section">
282
283 <p>PingImage() returns all the properties of an image or image sequence except for the pixels.  It is much faster and consumes far less memory than ReadImage().  On failure, a NULL image is returned and exception describes the reason for the failure.</p>
284
285 <p>The format of the PingImage method is:</p>
286
287 <pre class="code">
288   Image *PingImage(const ImageInfo *image_info,ExceptionInfo *exception)
289 </pre>
290
291 <p>A description of each parameter follows:</p>
292
293 <h5>image_info</h5>
294 <p>Ping the image defined by the file or filename members of this structure.</p>
295
296 <h5>exception</h5>
297 <p>return any errors or warnings in this structure.</p>
298
299  </div>
300 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImages">PingImages</a></h2>
301 <div class="doc-section">
302
303 <p>PingImages() pings one or more images and returns them as an image list.</p>
304
305 <p>The format of the PingImage method is:</p>
306
307 <pre class="code">
308   Image *PingImages(const ImageInfo *image_info,ExceptionInfo *exception)
309 </pre>
310
311 <p>A description of each parameter follows:</p>
312
313 <h5>image_info</h5>
314 <p>the image info.</p>
315
316 <h5>exception</h5>
317 <p>return any errors or warnings in this structure.</p>
318
319  </div>
320 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImage">ReadImage</a></h2>
321 <div class="doc-section">
322
323 <p>ReadImage() reads an image or image sequence from a file or file handle. The method returns a NULL if there is a memory shortage or if the image cannot be read.  On failure, a NULL image is returned and exception describes the reason for the failure.</p>
324
325 <p>The format of the ReadImage method is:</p>
326
327 <pre class="code">
328   Image *ReadImage(const ImageInfo *image_info,ExceptionInfo *exception)
329 </pre>
330
331 <p>A description of each parameter follows:</p>
332
333 <h5>image_info</h5>
334 <p>Read the image defined by the file or filename members of this structure.</p>
335
336 <h5>exception</h5>
337 <p>return any errors or warnings in this structure.</p>
338
339  </div>
340 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImages">ReadImages</a></h2>
341 <div class="doc-section">
342
343 <p>ReadImages() reads one or more images and returns them as an image list.</p>
344
345 <p>The format of the ReadImage method is:</p>
346
347 <pre class="code">
348   Image *ReadImages(const ImageInfo *image_info,ExceptionInfo *exception)
349 </pre>
350
351 <p>A description of each parameter follows:</p>
352
353 <h5>image_info</h5>
354 <p>the image info.</p>
355
356 <h5>exception</h5>
357 <p>return any errors or warnings in this structure.</p>
358
359  </div>
360 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImage">WriteImage</a></h2>
361 <div class="doc-section">
362
363 <p>WriteImage() writes an image or an image sequence to a file or file handle. If writing to a file is on disk, the name is defined by the filename member of the image structure.  WriteImage() returns MagickFalse is there is a memory shortage or if the image cannot be written.  Check the exception member of image to determine the cause for any failure.</p>
364
365 <p>The format of the WriteImage method is:</p>
366
367 <pre class="code">
368   MagickBooleanType WriteImage(const ImageInfo *image_info,Image *image)
369 </pre>
370
371 <p>A description of each parameter follows:</p>
372
373 <h5>image_info</h5>
374 <p>the image info.</p>
375
376 <h5>image</h5>
377 <p>the image.</p>
378
379  </div>
380 <h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImages">WriteImages</a></h2>
381 <div class="doc-section">
382
383 <p>WriteImages() writes an image sequence into one or more files.  While WriteImage() can write an image sequence, it is limited to writing the sequence into a single file using a format which supports multiple frames.   WriteImages(), however, does not have this limitation, instead it generates multiple output files if necessary (or when requested).  When ImageInfo's adjoin flag is set to MagickFalse, the file name is expected to include a printf-style formatting string for the frame number (e.g. "image02d.png").</p>
384
385 <p>The format of the WriteImages method is:</p>
386
387 <pre class="code">
388   MagickBooleanType WriteImages(const ImageInfo *image_info,Image *images,
389     const char *filename,ExceptionInfo *exception)
390 </pre>
391
392 <p>A description of each parameter follows:</p>
393
394 <h5>image_info</h5>
395 <p>the image info.</p>
396
397 <h5>images</h5>
398 <p>the image list.</p>
399
400 <h5>filename</h5>
401 <p>the image filename.</p>
402
403 <h5>exception</h5>
404 <p>return any errors or warnings in this structure.</p>
405
406  </div>
407
408 </div>
409
410 <div id="linkbar">
411     <span id="linkbar-west">&nbsp;</span>
412     <span id="linkbar-center">
413       <a href="../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../../discourse-server">Discourse Server</a> &bull;
414       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
415     </span>
416     <span id="linkbar-east">&nbsp;</span>
417   </div>
418   <div class="footer">
419     <span id="footer-west">&copy; 1999-2013 ImageMagick Studio LLC</span>
420     <span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
421   </div>
422   <div style="clear: both; margin: 0; width: 100%; "></div>
423   <script type="text/javascript">
424     var _gaq = _gaq || [];
425     _gaq.push(['_setAccount', 'UA-17690367-1']);
426     _gaq.push(['_trackPageview']);
427
428     (function() {
429       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
430       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
431       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
432     })();
433   </script>
434 </body>
435 </html>