Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / c4ebbd4faa5a23a7593db20ab73f9a7c45335760 / . / www / api / constitute.html
blob: b1fd3293b90a227eebfb778f23d88a869b1a21df [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>
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]47 <a class="magick-nav-item " href="../binary-releases.html">Download</a>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]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>
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]50 <a class="magick-nav-item " href="../resources.html">Resources</a>
51 <a class="magick-nav-item " href="api.html">Develop</a>
cristya1890f02015-05-15 23:32:44 +0000[diff] [blame]52 <a class="magick-nav-item " href="http://www.imagemagick.org/script/search.php">Search</a>
53 <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]54 </nav>
55 </div>
56</div>
57<div class="container">
cristy4e638cd2015-05-07 16:47:40 +0000[diff] [blame]58<div class="magick-header">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]59<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]60
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]61<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]62
63<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>
64
65<pre class="text">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]66image = ConstituteImage(640,480,"RGB",CharPixel,pixels,&amp;exception);
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]67</pre>
68
69<p>The format of the ConstituteImage method is:</p>
70
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]71<pre class="text">
72Image *ConstituteImage(const size_t columns,const size_t rows,
73 const char *map,const StorageType storage,const void *pixels,
74 ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]75</pre>
76
77<p>A description of each parameter follows:</p>
78
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]79<dd>
80</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]81
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]82<dd> </dd>
83<dl class="dl-horizontal">
84<dt>columns</dt>
85<dd>width in pixels of the image. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]86
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]87<dd> </dd>
88<dt>rows</dt>
89<dd>height in pixels of the image. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]90
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]91<dd> </dd>
92<dt>map</dt>
93<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]94
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]95<dd> </dd>
96<dt>storage</dt>
97<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]98
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]99<dd> </dd>
100<dt>pixels</dt>
101<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]102
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]103<dd> </dd>
104<dt>exception</dt>
105<dd>return any errors or warnings in this structure. </dd>
106
107<dd> </dd>
108</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]109<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]110
111<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>
112
113<p>The format of the PingImage method is:</p>
114
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]115<pre class="text">
116Image *PingImage(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]117</pre>
118
119<p>A description of each parameter follows:</p>
120
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]121<dd>
122</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]123
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]124<dd> </dd>
125<dl class="dl-horizontal">
126<dt>image_info</dt>
127<dd>Ping the image defined by the file or filename members of this structure. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]128
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]129<dd> </dd>
130<dt>exception</dt>
131<dd>return any errors or warnings in this structure. </dd>
132
133<dd> </dd>
134</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]135<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]136
137<p>PingImages() pings one or more images and returns them as an image list.</p>
138
139<p>The format of the PingImage method is:</p>
140
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]141<pre class="text">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]142Image *PingImages(const ImageInfo *image_info,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>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]156<dt>exception</dt>
157<dd>return any errors or warnings in this structure. </dd>
158
159<dd> </dd>
160</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]161<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]162
163<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>
164
165<p>The format of the ReadImage method is:</p>
166
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]167<pre class="text">
168Image *ReadImage(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]169</pre>
170
171<p>A description of each parameter follows:</p>
172
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]173<dd>
174</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]175
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]176<dd> </dd>
177<dl class="dl-horizontal">
178<dt>image_info</dt>
179<dd>Read the image defined by the file or filename members of this structure. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]180
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]181<dd> </dd>
182<dt>exception</dt>
183<dd>return any errors or warnings in this structure. </dd>
184
185<dd> </dd>
186</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]187<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]188
189<p>ReadImages() reads one or more images and returns them as an image list.</p>
190
191<p>The format of the ReadImage method is:</p>
192
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]193<pre class="text">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]194Image *ReadImages(const ImageInfo *image_info,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]195</pre>
196
197<p>A description of each parameter follows:</p>
198
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]199<dd>
200</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]201
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]202<dd> </dd>
203<dl class="dl-horizontal">
204<dt>image_info</dt>
205<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]206
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]207<dd> </dd>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]208<dt>exception</dt>
209<dd>return any errors or warnings in this structure. </dd>
210
211<dd> </dd>
212</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]213<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]214
215<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>
216
217<p>The format of the WriteImage method is:</p>
218
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]219<pre class="text">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]220MagickBooleanType WriteImage(const ImageInfo *image_info,Image *image)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]221</pre>
222
223<p>A description of each parameter follows:</p>
224
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]225<dd>
226</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]227
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]228<dd> </dd>
229<dl class="dl-horizontal">
230<dt>image_info</dt>
231<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]232
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]233<dd> </dd>
234<dt>image</dt>
235<dd>the image. </dd>
236
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]237<dd> </dd>
238</dl>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]239<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]240
241<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>
242
243<p>The format of the WriteImages method is:</p>
244
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]245<pre class="text">
246MagickBooleanType WriteImages(const ImageInfo *image_info,Image *images,
247 const char *filename,ExceptionInfo *exception)
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]248</pre>
249
250<p>A description of each parameter follows:</p>
251
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]252<dd>
253</dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]254
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]255<dd> </dd>
256<dl class="dl-horizontal">
257<dt>image_info</dt>
258<dd>the image info. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]259
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]260<dd> </dd>
261<dt>images</dt>
262<dd>the image list. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]263
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]264<dd> </dd>
265<dt>filename</dt>
266<dd>the image filename. </dd>
cristy20398432011-08-11 01:31:50 +0000[diff] [blame]267
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]268<dd> </dd>
269<dt>exception</dt>
270<dd>return any errors or warnings in this structure. </dd>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]271
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]272<dd> </dd>
273</dl>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]274</div>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]275 <footer class="magick-footer">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]276 <div class="magick-nav-item pull-left">
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]277 <a href="../support.html">Donate</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]278 </div>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]279 <p><a href="../sitemap.html">Sitemap</a> •
280 <a href="../links.html">Related</a> •
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]281 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Image Studio</a> •
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]282 <a href="http://jqmagick.imagemagick.org/">JqMagick</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]283</p>
284 <p><a href="constitute.html#">Back to top</a> •
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]285 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
cristyabed55c2015-05-06 17:07:00 +0000[diff] [blame]286 <a href="http://www.imagemagick.org/script/contact.php">Contact Us</a></p>
cristya1890f02015-05-15 23:32:44 +0000[diff] [blame]287 <p><small>© 1999-2015 ImageMagick Studio LLC</small></p>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]288 </footer>
289</div><!-- /.container -->
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]290
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]291 <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]292 <script src="../js/bootstrap.min.js"></script>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]293 <script type="text/javascript">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]294 /* <![CDATA[ */
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]295 (function() {
296 var s = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
297 s.type = 'text/javascript';
298 s.async = true;
299 s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
300 t.parentNode.insertBefore(s, t);
301 })();
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame]302 /* ]]> */
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]303 </script>
cristy44cbd482013-08-04 20:53:36 +0000[diff] [blame]304</div>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]305</body>
cristy5a367e42015-05-05 12:39:18 +0000[diff] [blame]306</html>