Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 29dc865bd0ebcc51ba89cbde1d57715a044d18ac / . / www / api / constitute.html
blob: a1af09083478aa960f83ef20cd6d8905aa05e29f [file] [log] [blame]
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame^]1<!DOCTYPE html>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]2<html lang="en">
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]3<head>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]4 <meta charset="utf-8">
5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
6 <meta name="viewport" content="width=device-width, initial-scale=1">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]7 <title>ImageMagick: MagickCore, C API for ImageMagick: Constitute an Image</title>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]8 <meta http-equiv="content-language" content="en-US">
9 <meta http-equiv="content-type" content="text/html; charset=utf-8">
10 <meta http-equiv="reply-to" content="magick-users@imagemagick.org">
11 <meta name="application-name" content="ImageMagick">
12 <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.">
13 <meta name="application-url" content="http://www.imagemagick.org">
14 <meta name="generator" content="PHP">
15 <meta name="keywords" content="magickcore, c, api, for, imagemagick:, constitute, an, image, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert">
16 <meta name="rating" content="GENERAL">
17 <meta name="robots" content="INDEX, FOLLOW">
18 <meta name="generator" content="ImageMagick Studio LLC">
19 <meta name="author" content="ImageMagick Studio LLC">
20 <meta name="revisit-after" content="2 DAYS">
21 <meta name="resource-type" content="document">
cristy4e638cd2015-05-07 16:47:40 +0000[diff] [blame]22 <meta name="copyright" content="Copyright (c) 1999-2015 ImageMagick Studio LLC">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]23 <meta name="distribution" content="Global">
24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1">
cristy2f563d42015-05-06 23:36:51 +0000[diff] [blame]25 <link rel="icon" href="../images/wand.png">
26 <link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon">
27 <link rel="stylesheet" href="../css/bootstrap.min.css">
28 <link rel="stylesheet" href="../css/magick.css">
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]29</head>
30
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]31<body>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]32<div class="main">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]33<div class="magick-masthead">
34 <div class="container">
35 <script type="text/javascript">
36 <!--
37 google_ad_client = "pub-3129977114552745";
38 google_ad_slot = "5439289906";
39 google_ad_width = 728;
40 google_ad_height = 90;
41 //-->
42 </script>
43 <center><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
44 </script></center>
45 <nav class="magick-nav">
cristy2f563d42015-05-06 23:36:51 +0000[diff] [blame]46 <a class="magick-nav-item " href="../index.html">Home</a>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]47 <a class="magick-nav-item " href="../binary-releases.html">Downloads</a>
48 <a class="magick-nav-item " href="../command-line-tools.html">Tools</a>
49 <a class="magick-nav-item " href="../command-line-options.html">Options</a>
50 <a class="magick-nav-item " href="api.html">Development</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]51 <a class="magick-nav-item" href="http://www.imagemagick.org/discourse-server/">Community</a>
cristyabed55c2015-05-06 17:07:00 +0000[diff] [blame]52 <a class="magick-nav-item navbar-right " href="http://www.imagemagick.org/script/search.php">Search</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]53 </nav>
54 </div>
55</div>
56<div class="container">
cristy4e638cd2015-05-07 16:47:40 +0000[diff] [blame]57<div class="magick-header">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]58<p class="text-center"><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>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]59
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]60<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ConstituteImage">ConstituteImage</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]61
62<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>
63
64<pre class="text">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]65image = ConstituteImage(640,480,"RGB",CharPixel,pixels,&amp;exception);
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]66</pre>
67
68<p>The format of the ConstituteImage method is:</p>
69
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]70<pre class="text">
71Image *ConstituteImage(const size_t columns,const size_t rows,
72 const char *map,const StorageType storage,const void *pixels,
73 ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]74</pre>
75
76<p>A description of each parameter follows:</p>
77
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]78<dd>
79</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]80
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]81<dd> </dd>
82<dl class="dl-horizontal">
83<dt>columns</dt>
84<dd>width in pixels of the image. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]85
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]86<dd> </dd>
87<dt>rows</dt>
88<dd>height in pixels of the image. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]89
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]90<dd> </dd>
91<dt>map</dt>
92<dd> 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. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]93
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]94<dd> </dd>
95<dt>storage</dt>
96<dd>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. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]97
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]98<dd> </dd>
99<dt>pixels</dt>
100<dd>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. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]101
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]102<dd> </dd>
103<dt>exception</dt>
104<dd>return any errors or warnings in this structure. </dd>
105
106<dd> </dd>
107</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]108<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImage">PingImage</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]109
110<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>
111
112<p>The format of the PingImage method is:</p>
113
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]114<pre class="text">
115Image *PingImage(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]116</pre>
117
118<p>A description of each parameter follows:</p>
119
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]120<dd>
121</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]122
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]123<dd> </dd>
124<dl class="dl-horizontal">
125<dt>image_info</dt>
126<dd>Ping the image defined by the file or filename members of this structure. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]127
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]128<dd> </dd>
129<dt>exception</dt>
130<dd>return any errors or warnings in this structure. </dd>
131
132<dd> </dd>
133</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]134<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="PingImages">PingImages</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]135
136<p>PingImages() pings one or more images and returns them as an image list.</p>
137
138<p>The format of the PingImage method is:</p>
139
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]140<pre class="text">
141Image *PingImages(ImageInfo *image_info,const char *filename,
142 ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]143</pre>
144
145<p>A description of each parameter follows:</p>
146
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]147<dd>
148</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]149
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]150<dd> </dd>
151<dl class="dl-horizontal">
152<dt>image_info</dt>
153<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]154
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]155<dd> </dd>
156<dt>filename</dt>
157<dd>the image filename. </dd>
158
159<dd> </dd>
160<dt>exception</dt>
161<dd>return any errors or warnings in this structure. </dd>
162
163<dd> </dd>
164</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]165<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImage">ReadImage</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]166
167<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>
168
169<p>The format of the ReadImage method is:</p>
170
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]171<pre class="text">
172Image *ReadImage(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]173</pre>
174
175<p>A description of each parameter follows:</p>
176
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]177<dd>
178</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]179
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]180<dd> </dd>
181<dl class="dl-horizontal">
182<dt>image_info</dt>
183<dd>Read the image defined by the file or filename members of this structure. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]184
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]185<dd> </dd>
186<dt>exception</dt>
187<dd>return any errors or warnings in this structure. </dd>
188
189<dd> </dd>
190</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]191<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="ReadImages">ReadImages</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]192
193<p>ReadImages() reads one or more images and returns them as an image list.</p>
194
195<p>The format of the ReadImage method is:</p>
196
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]197<pre class="text">
198Image *ReadImages(ImageInfo *image_info,const char *filename,
199 ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]200</pre>
201
202<p>A description of each parameter follows:</p>
203
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]204<dd>
205</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]206
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]207<dd> </dd>
208<dl class="dl-horizontal">
209<dt>image_info</dt>
210<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]211
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]212<dd> </dd>
213<dt>filename</dt>
214<dd>the image filename. </dd>
215
216<dd> </dd>
217<dt>exception</dt>
218<dd>return any errors or warnings in this structure. </dd>
219
220<dd> </dd>
221</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]222<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImage">WriteImage</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]223
224<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>
225
226<p>The format of the WriteImage method is:</p>
227
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]228<pre class="text">
229MagickBooleanType WriteImage(const ImageInfo *image_info,Image *image,
230 ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]231</pre>
232
233<p>A description of each parameter follows:</p>
234
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]235<dd>
236</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]237
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]238<dd> </dd>
239<dl class="dl-horizontal">
240<dt>image_info</dt>
241<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]242
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]243<dd> </dd>
244<dt>image</dt>
245<dd>the image. </dd>
246
247<dd> </dd>
248<dt>exception</dt>
249<dd>return any errors or warnings in this structure. </dd>
250
251<dd> </dd>
252</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]253<h2><a href="http://www.imagemagick.org/api/MagickCore/constitute_8c.html" id="WriteImages">WriteImages</a></h2>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]254
255<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>
256
257<p>The format of the WriteImages method is:</p>
258
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]259<pre class="text">
260MagickBooleanType WriteImages(const ImageInfo *image_info,Image *images,
261 const char *filename,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]262</pre>
263
264<p>A description of each parameter follows:</p>
265
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]266<dd>
267</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]268
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]269<dd> </dd>
270<dl class="dl-horizontal">
271<dt>image_info</dt>
272<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]273
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]274<dd> </dd>
275<dt>images</dt>
276<dd>the image list. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]277
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]278<dd> </dd>
279<dt>filename</dt>
280<dd>the image filename. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]281
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]282<dd> </dd>
283<dt>exception</dt>
284<dd>return any errors or warnings in this structure. </dd>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]285
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]286<dd> </dd>
287</dl>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]288</div>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]289 <footer class="magick-footer">
290 <div class="magick-nav-item navbar-left">
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]291 <a href="../support.html">Donate</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]292 </div>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]293 <p><a href="../sitemap.html">Sitemap</a> •
294 <a href="../links.html">Related</a> •
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]295 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Image Studio</a> •
296 <a href="http://jqmagick.imagemagick.org/">JqMagick</a> •
297 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
298</p>
299 <p><a href="constitute.html#">Back to top</a> •
cristyabed55c2015-05-06 17:07:00 +0000[diff] [blame]300 <a href="http://www.imagemagick.org/script/contact.php">Contact Us</a></p>
cristy4e638cd2015-05-07 16:47:40 +0000[diff] [blame]301 <p class="small">© 1999-2015 ImageMagick Studio LLC</p>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]302 </footer>
303</div><!-- /.container -->
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]304
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]305 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
cristy2f563d42015-05-06 23:36:51 +0000[diff] [blame]306 <script src="../js/bootstrap.min.js"></script>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]307 <script type="text/javascript">
308 /* */
309 (function() {
310 var s = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
311 s.type = 'text/javascript';
312 s.async = true;
313 s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
314 t.parentNode.insertBefore(s, t);
315 })();
316 /* */
317 </script>
cristy44cbd482013-08-04 20:53:36 +0000[diff] [blame]318</div>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]319</body>
cristy5a367e42015-05-05 12:39:18 +0000[diff] [blame]320</html>