Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / e4017e34baec05ee0a45800ed8efb2ff6d5c9f5a / . / www / api / cache.html
blob: 281ce04b3c536120b421fcdb8f9d015a90229ef2 [file] [log] [blame]
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]4<head>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
6 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]7 <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title>
cristy3ed852e2009-09-05 21:47:34 +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"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]11 <meta name="Application-name" content="ImageMagick"/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]12 <meta name="Description" content="ImageMagick is a software suite to create, edit, compose, or convert bitmap images in a variety of formats. Use ImageMagick to scale, rotate, shear, distort and transform images."/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]13 <meta name="Application-url" content="http://www.imagemagick.org"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]14 <meta name="Generator" content="PHP"/>
15 <meta name="Keywords" content="magickcore, c, api, for, imagemagick:, get, or, set, image, pixels, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]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"/>
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]22 <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]23 <meta name="Distribution" content="Global"/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]24 <link rel="icon" href="../../images/wand.png"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]25 <link rel="shortcut icon" href="../../images/wand.ico" type="images/x-icon"/>
26 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
27 <style type="text/css" media="all">
28 @import url("../../www/magick.css");
29 </style>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]30 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
cristy361f4662010-12-31 23:02:52 +0000[diff] [blame]31 <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
32 <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
33 <script type="text/javascript">
34 $(document).ready(function() {
35 $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
36 'transitionIn' : 'elastic',
37 'transitionOut' : 'elastic',
38 'overlayShow' : false,
39 'opacity' : true
40 });
41 });
42 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]43</head>
44
45<body id="www-imagemagick-org">
46<div class="titlebar">
47<a href="../../index.html">
48 <img src="../../images/script.png" alt="[ImageMagick]"
49 style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
50<a href="http://www.networkredux.com">
51 <img src="../../images/networkredux.png" alt="[sponsor]"
52 style="margin: 45px auto; border: 0px; float: left;" /></a>
53<a href="http://www.imagemagick.org/discourse-server/">
54 <img src="../../images/logo.jpg" alt=""
55 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
56<a href="../../index.html">
57 <img src="../../images/sprite.jpg" alt=""
58 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
59</div>
60
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]61<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]62
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]63<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]64 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]65</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]66<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]67<div class="menu">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]68 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
69</div>
70<div class="sub">
71 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
72</div>
73<div class="sub">
74 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
75</div>
76<div class="sub">
77 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
78</div>
79<div class="sep"></div>
80<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]81 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]82</div>
83<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]84 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]85</div>
86<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]87 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]88</div>
89<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]90 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]91</div>
92<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]93 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]94</div>
95<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]96 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]97</div>
98<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]99 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]100</div>
101<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]102 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]103</div>
104<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]105 <a title="Program Interface: Magick++" href="../../www/magick++.html">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]106</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]107<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]108<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]109 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]110</div>
111<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]112 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]113</div>
114<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]115 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]116 </div>
117<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]118 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]119</div>
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]120<div class="menu">
121 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
122</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]123<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]124 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]125</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]126<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]127<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]128 <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]129</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]130<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]131<div class="menu">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]132 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]133</div>
134<div class="sub">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]135 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]136</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]137<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]138<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]139 <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]140
141<div class="sponsbox">
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]142<div class="sponsor">
143 <a title="Sponsor: Web Hosting" href="http://www.bodhost.com/hosting.html">Web Hosting</a><!-- 201104010090 -->
cristy7d52cd62010-10-01 17:26:59 +0000[diff] [blame]144</div>
145<div class="sponsor">
146 <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
cristy73fd1cd2010-09-12 19:14:25 +0000[diff] [blame]147</div>
148<div class="sponsor">
cristyc5baf4f2010-08-31 15:05:33 +0000[diff] [blame]149 <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
150</div>
151<div class="sponsor">
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame]152 <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
153</div>
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]154<div class="sponsor">
155 <a title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
156</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]157</div>
158</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]159</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]160
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]161<div class="eastbar">
162 <script type="text/javascript">
163 <!--
164 google_ad_client = "pub-3129977114552745";
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]165 google_ad_slot = "0574824969";
166 google_ad_width = 160;
167 google_ad_height = 600;
168 //-->
169 </script>
170 <script type="text/javascript"
171 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
172 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]173</div>
174
175<div class="main">
176
cristy307ba182010-12-25 01:00:34 +0000[diff] [blame]177<h1>Module cache
178 Methods</h1>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]179<p class="navigation-index">[<a href="#AcquirePixelCacheNexus">AcquirePixelCacheNexus</a> &bull; <a href="#GetAuthenticIndexQueue">GetAuthenticIndexQueue</a> &bull; <a href="#GetAuthenticPixelQueue">GetAuthenticPixelQueue</a> &bull; <a href="#GetAuthenticPixels">GetAuthenticPixels</a> &bull; <a href="#GetOneAuthenticPixel">GetOneAuthenticPixel</a> &bull; <a href="#GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a> &bull; <a href="#GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a> &bull; <a href="#GetOneVirtualPixel">GetOneVirtualPixel</a> &bull; <a href="#GetVirtualIndexQueue">GetVirtualIndexQueue</a> &bull; <a href="#VirtualPixelModulo">VirtualPixelModulo</a> &bull; <a href="#GetVirtualPixelQueue">GetVirtualPixelQueue</a> &bull; <a href="#GetVirtualPixels">GetVirtualPixels</a> &bull; <a href="#QueueAuthenticPixels">QueueAuthenticPixels</a> &bull; <a href="#SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a> &bull; <a href="#SyncAuthenticPixels">SyncAuthenticPixels</a>]</p>
180
181<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
182_8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
183<div class="doc-section">
184
185<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
186
187<p>The format of the AcquirePixelCacheNexus method is:</p>
188
189<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]190 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]191</pre>
192
193<p>A description of each parameter follows:</p></ol>
194
195<h5>number_threads</h5>
196<ol><p>the number of nexus threads.</p></ol>
197
198 </div>
199<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
200_8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
201<div class="doc-section">
202
203<p>GetAuthenticIndexQueue() returns the authentic black channel or the colormap indexes associated with the last call to QueueAuthenticPixels() or GetVirtualPixels(). NULL is returned if the black channel or colormap indexes are not available.</p></ol>
204
205<p>The format of the GetAuthenticIndexQueue() method is:</p>
206
207<pre class="code">
208 IndexPacket *GetAuthenticIndexQueue(const Image *image)
209</pre>
210
211<p>A description of each parameter follows:</p></ol>
212
213<h5>image</h5>
214<ol><p>the image.</p></ol>
215
216 </div>
217<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
218_8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
219<div class="doc-section">
220
221<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
222
223<p>The format of the GetAuthenticPixelQueue() method is:</p>
224
225<pre class="code">
226 PixelPacket *GetAuthenticPixelQueue(const Image image)
227</pre>
228
229<p>A description of each parameter follows:</p></ol>
230
231<h5>image</h5>
232<ol><p>the image.</p></ol>
233
234 </div>
235<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
236_8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
237<div class="doc-section">
238
239<p>GetAuthenticPixels() obtains a pixel region for read/write access. If the region is successfully accessed, a pointer to a PixelPacket array representing the region is returned, otherwise NULL is returned.</p></ol>
240
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]241<p>The returned pointer may point to a temporary working copy of the pixels or it may point to the original pixels in memory. Performance is maximized if the selected region is part of one row, or one or more full rows, since then there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file. The returned pointer must *never* be deallocated by the user.</p></ol>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]242
243<p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket. If the image type is CMYK or if the storage class is PseduoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to obtain the black color component or colormap indexes (of type IndexPacket) corresponding to the region. Once the PixelPacket (and/or IndexPacket) array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p></ol>
244
245<p>The format of the GetAuthenticPixels() method is:</p>
246
247<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]248 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
249 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]250 ExceptionInfo *exception)
251</pre>
252
253<p>A description of each parameter follows:</p></ol>
254
255<h5>image</h5>
256<ol><p>the image.</p></ol>
257
258<h5>x,y,columns,rows</h5>
259<ol><p>These values define the perimeter of a region of pixels.</p></ol>
260
261<h5>exception</h5>
262<ol><p>return any errors or warnings in this structure.</p></ol>
263
264 </div>
265<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
266_8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
267<div class="doc-section">
268
269<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p></ol>
270
271<p>The format of the GetOneAuthenticPixel() method is:</p>
272
273<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]274 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
275 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]276</pre>
277
278<p>A description of each parameter follows:</p></ol>
279
280<h5>image</h5>
281<ol><p>the image.</p></ol>
282
283<h5>x,y</h5>
284<ol><p>These values define the location of the pixel to return.</p></ol>
285
286<h5>pixel</h5>
287<ol><p>return a pixel at the specified (x,y) location.</p></ol>
288
289<h5>exception</h5>
290<ol><p>return any errors or warnings in this structure.</p></ol>
291
292 </div>
293<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
294_8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
295<div class="doc-section">
296
297<p>GetOneVirtualMagickPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs. If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
298
299<p>The format of the GetOneVirtualMagickPixel() method is:</p>
300
301<pre class="code">
302 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]303 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]304 ExceptionInfo exception)
305</pre>
306
307<p>A description of each parameter follows:</p></ol>
308
309<h5>image</h5>
310<ol><p>the image.</p></ol>
311
312<h5>x,y</h5>
313<ol><p>these values define the location of the pixel to return.</p></ol>
314
315<h5>pixel</h5>
316<ol><p>return a pixel at the specified (x,y) location.</p></ol>
317
318<h5>exception</h5>
319<ol><p>return any errors or warnings in this structure.</p></ol>
320
321 </div>
322<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
323_8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
324<div class="doc-section">
325
326<p>GetOneVirtualMethodPixel() returns a single pixel at the specified (x,y) location as defined by specified pixel method. The image background color is returned if an error occurs. If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
327
328<p>The format of the GetOneVirtualMethodPixel() method is:</p>
329
330<pre class="code">
331 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]332 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
333 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]334</pre>
335
336<p>A description of each parameter follows:</p></ol>
337
338<h5>image</h5>
339<ol><p>the image.</p></ol>
340
341<h5>virtual_pixel_method</h5>
342<ol><p>the virtual pixel method.</p></ol>
343
344<h5>x,y</h5>
345<ol><p>These values define the location of the pixel to return.</p></ol>
346
347<h5>pixel</h5>
348<ol><p>return a pixel at the specified (x,y) location.</p></ol>
349
350<h5>exception</h5>
351<ol><p>return any errors or warnings in this structure.</p></ol>
352
353 </div>
354<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
355_8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
356<div class="doc-section">
357
358<p>GetOneVirtualPixel() returns a single virtual pixel at the specified (x,y) location. The image background color is returned if an error occurs. If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
359
360<p>The format of the GetOneVirtualPixel() method is:</p>
361
362<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]363 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
364 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]365</pre>
366
367<p>A description of each parameter follows:</p></ol>
368
369<h5>image</h5>
370<ol><p>the image.</p></ol>
371
372<h5>x,y</h5>
373<ol><p>These values define the location of the pixel to return.</p></ol>
374
375<h5>pixel</h5>
376<ol><p>return a pixel at the specified (x,y) location.</p></ol>
377
378<h5>exception</h5>
379<ol><p>return any errors or warnings in this structure.</p></ol>
380
381 </div>
382<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
383_8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
384<div class="doc-section">
385
386<p>GetVirtualIndexQueue() returns the virtual black channel or the colormap indexes associated with the last call to QueueAuthenticPixels() or GetVirtualPixels(). NULL is returned if the black channel or colormap indexes are not available.</p></ol>
387
388<p>The format of the GetVirtualIndexQueue() method is:</p>
389
390<pre class="code">
391 const IndexPacket *GetVirtualIndexQueue(const Image *image)
392</pre>
393
394<p>A description of each parameter follows:</p></ol>
395
396<h5>image</h5>
397<ol><p>the image.</p></ol>
398
399 </div>
400<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
401_8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
402<div class="doc-section">
403
404<p>VirtualPixelModulo() computes the remainder of dividing offset by extent. It returns not only the quotient (tile the offset falls in) but also the positive remainer within that tile such that 0 <= remainder < extent. This method is essentially a ldiv() using a floored modulo division rather than the normal default truncated modulo division. </p>
405 </div>
406<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
407_8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
408<div class="doc-section">
409
410<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
411
412<p>The format of the GetVirtualPixelQueue() method is:</p>
413
414<pre class="code">
415 const PixelPacket *GetVirtualPixelQueue(const Image image)
416</pre>
417
418<p>A description of each parameter follows:</p></ol>
419
420<h5>image</h5>
421<ol><p>the image.</p></ol>
422
423 </div>
424<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
425_8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
426<div class="doc-section">
427
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]428<p>GetVirtualPixels() returns an immutable pixel region. If the region is successfully accessed, a pointer to it is returned, otherwise NULL is returned. The returned pointer may point to a temporary working copy of the pixels or it may point to the original pixels in memory. Performance is maximized if the selected region is part of one row, or one or more full rows, since there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file. The returned pointer must *never* be deallocated by the user.</p></ol>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]429
430<p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket. If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to access the black color component or to obtain the colormap indexes (of type IndexPacket) corresponding to the region.</p></ol>
431
432<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
433
434<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
435
436<p>The format of the GetVirtualPixels() method is:</p>
437
438<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]439 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
440 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]441 ExceptionInfo *exception)
442</pre>
443
444<p>A description of each parameter follows:</p></ol>
445
446<h5>image</h5>
447<ol><p>the image.</p></ol>
448
449<h5>x,y,columns,rows</h5>
450<ol><p>These values define the perimeter of a region of pixels.</p></ol>
451
452<h5>exception</h5>
453<ol><p>return any errors or warnings in this structure.</p></ol>
454
455 </div>
456<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
457_8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
458<div class="doc-section">
459
460<p>QueueAuthenticPixels() queues a mutable pixel region. If the region is successfully intialized a pointer to a PixelPacket array representing the region is returned, otherwise NULL is returned. The returned pointer may point to a temporary working buffer for the pixels or it may point to the final location of the pixels in memory.</p></ol>
461
462<p>Write-only access means that any existing pixel values corresponding to the region are ignored. This is useful if the initial image is being created from scratch, or if the existing pixel values are to be completely replaced without need to refer to their pre-existing values. The application is free to read and write the pixel buffer returned by QueueAuthenticPixels() any way it pleases. QueueAuthenticPixels() does not initialize the pixel array values. Initializing pixel array values is the application's responsibility.</p></ol>
463
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]464<p>Performance is maximized if the selected region is part of one row, or one or more full rows, since then there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file. The returned pointer must *never* be deallocated by the user.</p></ol>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]465
466<p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket. If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to obtain the black color component or the colormap indexes (of type IndexPacket) corresponding to the region. Once the PixelPacket (and/or IndexPacket) array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p></ol>
467
468<p>The format of the QueueAuthenticPixels() method is:</p>
469
470<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]471 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
472 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]473 ExceptionInfo *exception)
474</pre>
475
476<p>A description of each parameter follows:</p></ol>
477
478<h5>image</h5>
479<ol><p>the image.</p></ol>
480
481<h5>x,y,columns,rows</h5>
482<ol><p>These values define the perimeter of a region of pixels.</p></ol>
483
484<h5>exception</h5>
485<ol><p>return any errors or warnings in this structure.</p></ol>
486
487 </div>
488<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
489_8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
490<div class="doc-section">
491
492<p>SetPixelCacheVirtualMethod() sets the "virtual pixels" method for the pixel cache and returns the previous setting. A virtual pixel is any pixel access that is outside the boundaries of the image cache.</p></ol>
493
494<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
495
496<pre class="code">
497 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
498 const VirtualPixelMethod virtual_pixel_method)
499</pre>
500
501<p>A description of each parameter follows:</p></ol>
502
503<h5>image</h5>
504<ol><p>the image.</p></ol>
505
506<h5>virtual_pixel_method</h5>
507<ol><p>choose the type of virtual pixel.</p></ol>
508
509 </div>
510<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
511_8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
512<div class="doc-section">
513
514<p>SyncAuthenticPixels() saves the image pixels to the in-memory or disk cache. The method returns MagickTrue if the pixel region is flushed, otherwise MagickFalse.</p></ol>
515
516<p>The format of the SyncAuthenticPixels() method is:</p>
517
518<pre class="code">
519 MagickBooleanType SyncAuthenticPixels(Image *image,
520 ExceptionInfo *exception)
521</pre>
522
523<p>A description of each parameter follows:</p></ol>
524
525<h5>image</h5>
526<ol><p>the image.</p></ol>
527
528<h5>exception</h5>
529<ol><p>return any errors or warnings in this structure.</p></ol>
530
531 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]532
533</div>
534
535<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]536 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]537 <span id="linkbar-center">
538 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]539 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]540 </span>
541 <span id="linkbar-east">&nbsp;</span>
542 </div>
543 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]544 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]545 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
546 </div>
547 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]548 <script type="text/javascript">
549 var _gaq = _gaq || [];
550 _gaq.push(['_setAccount', 'UA-17690367-1']);
551 _gaq.push(['_trackPageview']);
552
553 (function() {
554 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
555 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
556 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
557 })();
558 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]559</body>
560</html>