blob: 786b4163f44b9a9fa0f7593fd5427c63647fa961 [file] [log] [blame]
cristy44cbd482013-08-04 20:53:36 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="-//W3C//DTD XHTML 1.1//EN" xml:lang="en" xsi:schemaLocation="http://www.w3.org/1999/xhtml http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
cristy06f63f22012-10-31 00:50:07 +00003<head>
cristy44cbd482013-08-04 20:53:36 +00004 <meta http-equiv="content-type" content="text/html; charset=UTF-8"></meta>
5 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4"></meta>
cristyffb69ed2010-12-25 00:06:48 +00006 <title>ImageMagick: MagickCore, C API for ImageMagick: Constitute an Image</title>
cristy44cbd482013-08-04 20:53:36 +00007 <meta http-equiv="content-language" content="en-US"></meta>
8 <meta http-equiv="content-type" content="text/html; charset=utf-8"></meta>
9 <meta http-equiv="reply-to" content="magick-users@imagemagick.org"></meta>
10 <meta name="application-name" content="ImageMagick"></meta>
11 <meta name="description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats. In addition, resize, rotate, shear, distort or transform images automagically."></meta>
12 <meta name="application-url" content="http://www.imagemagick.org"></meta>
13 <meta name="generator" content="PHP"></meta>
14 <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"></meta>
15 <meta name="rating" content="GENERAL"></meta>
16 <meta name="robots" content="INDEX, FOLLOW"></meta>
17 <meta name="generator" content="ImageMagick Studio LLC"></meta>
18 <meta name="author" content="ImageMagick Studio LLC"></meta>
19 <meta name="revisit-after" content="2 DAYS"></meta>
20 <meta name="resource-type" content="document"></meta>
21 <meta name="copyright" content="Copyright (c) 1999-2012 ImageMagick Studio LLC"></meta>
22 <meta name="distribution" content="Global"></meta>
23 <link rel="icon" href="../../images/wand.png"></link>
24 <link rel="shortcut icon" href="../../images/wand.ico" type="images/x-icon"></link>
25 <link rel="canonical" href="../../index.html"></link>
26 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"></link>
cristy8ee7f242013-06-20 16:08:44 +000027
28 <!-- Add jQuery library -->
29 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
30
31 <!-- Add mousewheel plugin (this is optional) -->
32 <script type="text/javascript" src="http://www.imagemagick.org/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script>
33
34 <!-- Add fancyBox -->
cristy44cbd482013-08-04 20:53:36 +000035 <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/jquery.fancybox.css?v=2.0.6" type="text/css" media="screen"></link>
cristy8ee7f242013-06-20 16:08:44 +000036 <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/jquery.fancybox.pack.js?v=2.0.6"></script>
37
38 <!-- Optionally add helpers - button, thumbnail and/or media -->
cristy44cbd482013-08-04 20:53:36 +000039 <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.2" type="text/css" media="screen"></link>
cristy8ee7f242013-06-20 16:08:44 +000040 <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.2"></script>
41 <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.0"></script>
42
cristy44cbd482013-08-04 20:53:36 +000043 <link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=2.0.6" type="text/css" media="screen"></link>
cristy8ee7f242013-06-20 16:08:44 +000044 <script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=2.0.6"></script>
45
cristy72da67d2013-02-24 21:40:48 +000046 <script type="text/javascript">
cristy8ee7f242013-06-20 16:08:44 +000047 $(document).ready(function() {
48 $(".fancybox").fancybox();
49 });
cristy72da67d2013-02-24 21:40:48 +000050 </script>
cristy8ee7f242013-06-20 16:08:44 +000051
52 <!-- ImageMagick style -->
53 <style type="text/css" media="all">
54 @import url("../../www/magick.css");
55 </style>
cristy06f63f22012-10-31 00:50:07 +000056</head>
57
58<body id="www-imagemagick-org">
cristy8ee7f242013-06-20 16:08:44 +000059
cristy8ee7f242013-06-20 16:08:44 +000060
cristy8ee7f242013-06-20 16:08:44 +000061
cristy06f63f22012-10-31 00:50:07 +000062<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>
cristy44cbd482013-08-04 20:53:36 +000072
cristy06f63f22012-10-31 00:50:07 +000073</div>
cristy417eeb12013-07-28 18:48:22 +000074<a href="../../discourse-server">
cristy44cbd482013-08-04 20:53:36 +000075 <img src="../../images/logo.jpg" alt="ImageMagick Logo" style="width: 123px; height: 118px; border: 0px; float: right;"></img></a>
cristy8ee7f242013-06-20 16:08:44 +000076<a href="../../index.html">
cristy44cbd482013-08-04 20:53:36 +000077 <img src="../../images/sprite.jpg" alt="ImageMagick Sprite" style="width: 114px; height: 118px; border: 0px; float: right;"></img></a>
cristy06f63f22012-10-31 00:50:07 +000078</div>
79
80<div class="westbar">
81
cristy3ed852e2009-09-05 21:47:34 +000082<div class="menu">
cristy8ee7f242013-06-20 16:08:44 +000083 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +000084</div>
cristy3ed852e2009-09-05 21:47:34 +000085<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +000086 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
cristybb503372010-05-27 20:51:26 +000087</div>
88<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +000089 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
cristybb503372010-05-27 20:51:26 +000090</div>
91<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +000092 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
cristybb503372010-05-27 20:51:26 +000093</div>
94<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +000095 <a title="Binary Release: iOS" href="../../www/binary-releases.html#iOS">iOS</a>
cristyda16f162011-02-19 23:52:17 +000096</div>
97<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +000098 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
cristybb503372010-05-27 20:51:26 +000099</div>
cristy06f63f22012-10-31 00:50:07 +0000100<div class="sep"></div>
cristybb503372010-05-27 20:51:26 +0000101<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000102 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +0000103</div>
104<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000105 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristy3ed852e2009-09-05 21:47:34 +0000106</div>
107<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000108 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristy3ed852e2009-09-05 21:47:34 +0000109</div>
110<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000111 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +0000112</div>
113<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000114 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +0000115</div>
116<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000117 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristy3ed852e2009-09-05 21:47:34 +0000118</div>
119<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000120 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristy3ed852e2009-09-05 21:47:34 +0000121</div>
122<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000123 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000124</div>
125<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000126 <a title="Program Interface: Magick++" href="../../www/magick++.html">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000127</div>
cristy06f63f22012-10-31 00:50:07 +0000128<div class="sep"></div>
cristy44cbd482013-08-04 20:53:36 +0000129<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000130 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristy3ed852e2009-09-05 21:47:34 +0000131</div>
132<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000133 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristy3ed852e2009-09-05 21:47:34 +0000134</div>
135<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000136 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000137 </div>
138<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000139 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000140</div>
cristybb503372010-05-27 20:51:26 +0000141<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000142 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
cristybb503372010-05-27 20:51:26 +0000143</div>
cristy3ed852e2009-09-05 21:47:34 +0000144<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000145 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000146</div>
cristy06f63f22012-10-31 00:50:07 +0000147<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000148<div class="menu">
cristy3dfa2192013-02-24 22:46:05 +0000149 <a title="Search" href="http://www.imagemagick.org/script/search.php">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000150</div>
cristy06f63f22012-10-31 00:50:07 +0000151<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000152<div class="menu">
cristyd8833bf2013-02-24 22:14:53 +0000153 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000154</div>
cristy44cbd482013-08-04 20:53:36 +0000155<div class="sub">
cristyd8833bf2013-02-24 22:14:53 +0000156 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000157</div>
cristy06f63f22012-10-31 00:50:07 +0000158<div class="sep"></div>
cristy8ee7f242013-06-20 16:08:44 +0000159<div class="menu">
160 <a title="Support ImageMagick Development" href="../../www/support.html">Support ImageMagick Development</a>
cristy3ed852e2009-09-05 21:47:34 +0000161</div>
cristy06f63f22012-10-31 00:50:07 +0000162</div>
163
164<div class="eastbar">
cristy44cbd482013-08-04 20:53:36 +0000165
cristy417eeb12013-07-28 18:48:22 +0000166 <div> <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="../../index.html"></a></div>
cristy8ee7f242013-06-20 16:08:44 +0000167 <noscript>
168 <a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
cristy44cbd482013-08-04 20:53:36 +0000169 <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" width="93" height="20" border="0"></img></a>
cristy8ee7f242013-06-20 16:08:44 +0000170 </noscript>
cristy44cbd482013-08-04 20:53:36 +0000171
172
cristy06f63f22012-10-31 00:50:07 +0000173</div>
174
175<div class="main">
176
cristy20398432011-08-11 01:31:50 +0000177<h1>Module constitute Methods</h1>
cristy44cbd482013-08-04 20:53:36 +0000178<p class="navigation-index">[<a href="constitute.html#ConstituteImage">ConstituteImage</a><a href="constitute.html#PingImage">PingImage</a><a href="constitute.html#PingImages">PingImages</a><a href="constitute.html#ReadImage">ReadImage</a><a href="constitute.html#ReadImages">ReadImages</a><a href="constitute.html#WriteImage">WriteImage</a><a href="constitute.html#WriteImages">WriteImages</a>]</p>
cristy3ed852e2009-09-05 21:47:34 +0000179
cristy20398432011-08-11 01:31:50 +0000180<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ConstituteImage">ConstituteImage</a></h2>
181<div class="doc-section">
182
183<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>
184
185<pre class="text">
cristy44cbd482013-08-04 20:53:36 +0000186 image = ConstituteImage(640,480,"RGB",CharPixel,pixels,&amp;exception);
cristy20398432011-08-11 01:31:50 +0000187</pre>
188
189<p>The format of the ConstituteImage method is:</p>
190
191<pre class="code">
192 Image *ConstituteImage(const size_t columns,const size_t rows,
193 const char *map,const StorageType storage,const void *pixels,
194 ExceptionInfo *exception)
195</pre>
196
197<p>A description of each parameter follows:</p>
198
199<h5>columns</h5>
200<p>width in pixels of the image.</p>
201
202<h5>rows</h5>
203<p>height in pixels of the image.</p>
204
205<h5>map</h5>
206<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>
207
208<h5>storage</h5>
209<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>
210
211<h5>pixels</h5>
212<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>
213
214<h5>exception</h5>
215<p>return any errors or warnings in this structure.</p>
216
217 </div>
218<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImage">PingImage</a></h2>
219<div class="doc-section">
220
221<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>
222
223<p>The format of the PingImage method is:</p>
224
225<pre class="code">
226 Image *PingImage(const ImageInfo *image_info,ExceptionInfo *exception)
227</pre>
228
229<p>A description of each parameter follows:</p>
230
231<h5>image_info</h5>
232<p>Ping the image defined by the file or filename members of this structure.</p>
233
234<h5>exception</h5>
235<p>return any errors or warnings in this structure.</p>
236
237 </div>
238<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImages">PingImages</a></h2>
239<div class="doc-section">
240
241<p>PingImages() pings one or more images and returns them as an image list.</p>
242
243<p>The format of the PingImage method is:</p>
244
245<pre class="code">
246 Image *PingImages(const ImageInfo *image_info,ExceptionInfo *exception)
247</pre>
248
249<p>A description of each parameter follows:</p>
250
251<h5>image_info</h5>
252<p>the image info.</p>
253
254<h5>exception</h5>
255<p>return any errors or warnings in this structure.</p>
256
257 </div>
258<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImage">ReadImage</a></h2>
259<div class="doc-section">
260
261<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>
262
263<p>The format of the ReadImage method is:</p>
264
265<pre class="code">
266 Image *ReadImage(const ImageInfo *image_info,ExceptionInfo *exception)
267</pre>
268
269<p>A description of each parameter follows:</p>
270
271<h5>image_info</h5>
272<p>Read the image defined by the file or filename members of this structure.</p>
273
274<h5>exception</h5>
275<p>return any errors or warnings in this structure.</p>
276
277 </div>
278<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImages">ReadImages</a></h2>
279<div class="doc-section">
280
281<p>ReadImages() reads one or more images and returns them as an image list.</p>
282
283<p>The format of the ReadImage method is:</p>
284
285<pre class="code">
286 Image *ReadImages(const ImageInfo *image_info,ExceptionInfo *exception)
287</pre>
288
289<p>A description of each parameter follows:</p>
290
291<h5>image_info</h5>
292<p>the image info.</p>
293
294<h5>exception</h5>
295<p>return any errors or warnings in this structure.</p>
296
297 </div>
298<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImage">WriteImage</a></h2>
299<div class="doc-section">
300
301<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>
302
303<p>The format of the WriteImage method is:</p>
304
305<pre class="code">
306 MagickBooleanType WriteImage(const ImageInfo *image_info,Image *image)
307</pre>
308
309<p>A description of each parameter follows:</p>
310
311<h5>image_info</h5>
312<p>the image info.</p>
313
314<h5>image</h5>
315<p>the image.</p>
316
317 </div>
318<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImages">WriteImages</a></h2>
319<div class="doc-section">
320
321<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>
322
323<p>The format of the WriteImages method is:</p>
324
325<pre class="code">
326 MagickBooleanType WriteImages(const ImageInfo *image_info,Image *images,
327 const char *filename,ExceptionInfo *exception)
328</pre>
329
330<p>A description of each parameter follows:</p>
331
332<h5>image_info</h5>
333<p>the image info.</p>
334
335<h5>images</h5>
336<p>the image list.</p>
337
338<h5>filename</h5>
339<p>the image filename.</p>
340
341<h5>exception</h5>
342<p>return any errors or warnings in this structure.</p>
343
344 </div>
cristy06f63f22012-10-31 00:50:07 +0000345
346</div>
347
348<div id="linkbar">
cristyac1b4322013-07-28 13:58:06 +0000349 <span id="linkbar-west"> </span>
cristy8ee7f242013-06-20 16:08:44 +0000350
cristy06f63f22012-10-31 00:50:07 +0000351 <span id="linkbar-center">
cristy44cbd482013-08-04 20:53:36 +0000352 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
353 <a href="../../discourse-server">Discourse Server</a>
354 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy8ee7f242013-06-20 16:08:44 +0000355 <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
cristy06f63f22012-10-31 00:50:07 +0000356 </span>
cristyac1b4322013-07-28 13:58:06 +0000357 <span id="linkbar-east"> </span>
cristy44cbd482013-08-04 20:53:36 +0000358</div>
359<div class="footer">
360 <span id="footer-west">© 1999-2013 ImageMagick Studio LLC</span>
361 <span id="footer-east"> <a href="../../www/contact.html">Contact the Wizards</a></span>
362</div>
363<div style="clear: both; margin: 0; width: 100%; "></div>
cristy06f63f22012-10-31 00:50:07 +0000364</body>
365</html>