Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / a1890f0836ae7459ceab62ae752e9d6d5082f1b1 / . / www / api / constitute.html
blob: 1442fc5d421e0628670ca232aff38ae9ad947099 [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>
cristya1890f02015-05-15 23:32:44 +0000[diff] [blame^]51 <a class="magick-nav-item " href="http://www.imagemagick.org/script/search.php">Search</a>
52 <a class="magick-nav-item pull-right" href="http://www.imagemagick.org/discourse-server/">Community</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">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]141Image *PingImages(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]142</pre>
143
144<p>A description of each parameter follows:</p>
145
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]146<dd>
147</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]148
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]149<dd> </dd>
150<dl class="dl-horizontal">
151<dt>image_info</dt>
152<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]153
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]154<dd> </dd>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]155<dt>exception</dt>
156<dd>return any errors or warnings in this structure. </dd>
157
158<dd> </dd>
159</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]160<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]161
162<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>
163
164<p>The format of the ReadImage method is:</p>
165
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]166<pre class="text">
167Image *ReadImage(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]168</pre>
169
170<p>A description of each parameter follows:</p>
171
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]172<dd>
173</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]174
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]175<dd> </dd>
176<dl class="dl-horizontal">
177<dt>image_info</dt>
178<dd>Read the image defined by the file or filename members of this structure. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]179
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]180<dd> </dd>
181<dt>exception</dt>
182<dd>return any errors or warnings in this structure. </dd>
183
184<dd> </dd>
185</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]186<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]187
188<p>ReadImages() reads one or more images and returns them as an image list.</p>
189
190<p>The format of the ReadImage method is:</p>
191
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]192<pre class="text">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]193Image *ReadImages(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]194</pre>
195
196<p>A description of each parameter follows:</p>
197
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]198<dd>
199</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]200
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]201<dd> </dd>
202<dl class="dl-horizontal">
203<dt>image_info</dt>
204<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]205
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]206<dd> </dd>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]207<dt>exception</dt>
208<dd>return any errors or warnings in this structure. </dd>
209
210<dd> </dd>
211</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]212<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]213
214<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>
215
216<p>The format of the WriteImage method is:</p>
217
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]218<pre class="text">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]219MagickBooleanType WriteImage(const ImageInfo *image_info,Image *image)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]220</pre>
221
222<p>A description of each parameter follows:</p>
223
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]224<dd>
225</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]226
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]227<dd> </dd>
228<dl class="dl-horizontal">
229<dt>image_info</dt>
230<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]231
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]232<dd> </dd>
233<dt>image</dt>
234<dd>the image. </dd>
235
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]236<dd> </dd>
237</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]238<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]239
240<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>
241
242<p>The format of the WriteImages method is:</p>
243
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]244<pre class="text">
245MagickBooleanType WriteImages(const ImageInfo *image_info,Image *images,
246 const char *filename,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]247</pre>
248
249<p>A description of each parameter follows:</p>
250
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]251<dd>
252</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]253
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]254<dd> </dd>
255<dl class="dl-horizontal">
256<dt>image_info</dt>
257<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]258
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]259<dd> </dd>
260<dt>images</dt>
261<dd>the image list. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]262
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]263<dd> </dd>
264<dt>filename</dt>
265<dd>the image filename. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]266
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]267<dd> </dd>
268<dt>exception</dt>
269<dd>return any errors or warnings in this structure. </dd>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]270
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]271<dd> </dd>
272</dl>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]273</div>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]274 <footer class="magick-footer">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]275 <div class="magick-nav-item pull-left">
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]276 <a href="../support.html">Donate</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]277 </div>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]278 <p><a href="../sitemap.html">Sitemap</a> •
279 <a href="../links.html">Related</a> •
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]280 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Image Studio</a> •
281 <a href="http://jqmagick.imagemagick.org/">JqMagick</a> •
282 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
283</p>
284 <p><a href="constitute.html#">Back to top</a> •
cristyabed55c2015-05-06 17:07:00 +0000[diff] [blame]285 <a href="http://www.imagemagick.org/script/contact.php">Contact Us</a></p>
cristya1890f02015-05-15 23:32:44 +0000[diff] [blame^]286 <p><small>© 1999-2015 ImageMagick Studio LLC</small></p>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]287 </footer>
288</div><!-- /.container -->
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]289
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]290 <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]291 <script src="../js/bootstrap.min.js"></script>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]292 <script type="text/javascript">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]293 /* <![CDATA[ */
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]294 (function() {
295 var s = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
296 s.type = 'text/javascript';
297 s.async = true;
298 s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
299 t.parentNode.insertBefore(s, t);
300 })();
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]301 /* ]]> */
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]302 </script>
cristy44cbd482013-08-04 20:53:36 +0000[diff] [blame]303</div>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]304</body>
cristy5a367e42015-05-05 12:39:18 +0000[diff] [blame]305</html>