Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 307ba18d4753632f19e873143d01e0b6ba2dbaad / . / www / api / cache.html
blob: 6227151d7adf7898dec7242b1047df58ccade7dc [file] [log] [blame]
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cristy2c839602010-04-03 02:32:08 +0000[diff] [blame]3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" 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"/>
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]12 <meta name="Description" content="ImageMagick is a software suite to create, edit, or compose 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"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]24 <link rel="icon" href="../../images/wand.png" sizes="32x32"/>
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>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]30</head>
31
32<body id="www-imagemagick-org">
33<div class="titlebar">
34<a href="../../index.html">
35 <img src="../../images/script.png" alt="[ImageMagick]"
36 style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
37<a href="http://www.networkredux.com">
38 <img src="../../images/networkredux.png" alt="[sponsor]"
39 style="margin: 45px auto; border: 0px; float: left;" /></a>
40<a href="http://www.imagemagick.org/discourse-server/">
41 <img src="../../images/logo.jpg" alt=""
42 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
43<a href="../../index.html">
44 <img src="../../images/sprite.jpg" alt=""
45 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
46</div>
47
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]48<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]49
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]50<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]51 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]52</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]53<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]54<div class="menu">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]55 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
56</div>
57<div class="sub">
58 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
59</div>
60<div class="sub">
61 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
62</div>
63<div class="sub">
64 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
65</div>
66<div class="sep"></div>
67<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]68 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]69</div>
70<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]71 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]72</div>
73<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]74 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]75</div>
76<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]77 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]78</div>
79<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]80 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]81</div>
82<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]83 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]84</div>
85<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]86 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]87</div>
88<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]89 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]90</div>
91<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]92 <a title="Program Interface: Magick++" href="../../Magick++/">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]93</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]94<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]95<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]96 <a title="Install from Source" href="../../www/install-source.html">Install from Source</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="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</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="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]103 </div>
104<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]105 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]106</div>
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]107<div class="menu">
108 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
109</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]110<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]111 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]112</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]113<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]114<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]115 <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]116</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]117<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]118<div class="menu">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]119 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]120</div>
121<div class="sub">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]122 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]123</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]124<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]125<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]126 <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]127
128<div class="sponsbox">
129<div class="sponsor">
cristy307ba182010-12-25 01:00:34 +0000[diff] [blame^]130 <a title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
cristy7d52cd62010-10-01 17:26:59 +0000[diff] [blame]131</div>
132<div class="sponsor">
133 <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
cristy73fd1cd2010-09-12 19:14:25 +0000[diff] [blame]134</div>
135<div class="sponsor">
cristyc5baf4f2010-08-31 15:05:33 +0000[diff] [blame]136 <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
137</div>
138<div class="sponsor">
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame]139 <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
140</div>
141<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]142 <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
cristyb36feb22010-03-26 16:54:37 +0000[diff] [blame]143</div>
144<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]145 <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
cristy35aca9a2010-03-04 20:32:46 +0000[diff] [blame]146</div>
147<div class="sponsor">
cristyc5baf4f2010-08-31 15:05:33 +0000[diff] [blame]148 <a title="Sponsor: Diamonds are a Girls Best Friend" href="http://www.schmuck.org">Diamonds are a Girls Best Friend</a><!-- 201101010600 Peterssen-->
cristyc1c61662009-09-30 14:04:37 +0000[diff] [blame]149</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]150</div>
151</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]152</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]153
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]154<div class="eastbar">
155 <script type="text/javascript">
156 <!--
157 google_ad_client = "pub-3129977114552745";
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]158 google_ad_slot = "0574824969";
159 google_ad_width = 160;
160 google_ad_height = 600;
161 //-->
162 </script>
163 <script type="text/javascript"
164 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
165 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]166</div>
167
168<div class="main">
169
cristy307ba182010-12-25 01:00:34 +0000[diff] [blame^]170<h1>Module cache
171 Methods</h1>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]172<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>
173
174<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
175_8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
176<div class="doc-section">
177
178<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
179
180<p>The format of the AcquirePixelCacheNexus method is:</p>
181
182<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]183 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]184</pre>
185
186<p>A description of each parameter follows:</p></ol>
187
188<h5>number_threads</h5>
189<ol><p>the number of nexus threads.</p></ol>
190
191 </div>
192<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
193_8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
194<div class="doc-section">
195
196<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>
197
198<p>The format of the GetAuthenticIndexQueue() method is:</p>
199
200<pre class="code">
201 IndexPacket *GetAuthenticIndexQueue(const Image *image)
202</pre>
203
204<p>A description of each parameter follows:</p></ol>
205
206<h5>image</h5>
207<ol><p>the image.</p></ol>
208
209 </div>
210<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
211_8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
212<div class="doc-section">
213
214<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
215
216<p>The format of the GetAuthenticPixelQueue() method is:</p>
217
218<pre class="code">
219 PixelPacket *GetAuthenticPixelQueue(const Image image)
220</pre>
221
222<p>A description of each parameter follows:</p></ol>
223
224<h5>image</h5>
225<ol><p>the image.</p></ol>
226
227 </div>
228<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
229_8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
230<div class="doc-section">
231
232<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>
233
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]234<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]235
236<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>
237
238<p>The format of the GetAuthenticPixels() method is:</p>
239
240<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]241 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
242 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]243 ExceptionInfo *exception)
244</pre>
245
246<p>A description of each parameter follows:</p></ol>
247
248<h5>image</h5>
249<ol><p>the image.</p></ol>
250
251<h5>x,y,columns,rows</h5>
252<ol><p>These values define the perimeter of a region of pixels.</p></ol>
253
254<h5>exception</h5>
255<ol><p>return any errors or warnings in this structure.</p></ol>
256
257 </div>
258<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
259_8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
260<div class="doc-section">
261
262<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p></ol>
263
264<p>The format of the GetOneAuthenticPixel() method is:</p>
265
266<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]267 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
268 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]269</pre>
270
271<p>A description of each parameter follows:</p></ol>
272
273<h5>image</h5>
274<ol><p>the image.</p></ol>
275
276<h5>x,y</h5>
277<ol><p>These values define the location of the pixel to return.</p></ol>
278
279<h5>pixel</h5>
280<ol><p>return a pixel at the specified (x,y) location.</p></ol>
281
282<h5>exception</h5>
283<ol><p>return any errors or warnings in this structure.</p></ol>
284
285 </div>
286<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
287_8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
288<div class="doc-section">
289
290<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>
291
292<p>The format of the GetOneVirtualMagickPixel() method is:</p>
293
294<pre class="code">
295 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]296 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]297 ExceptionInfo exception)
298</pre>
299
300<p>A description of each parameter follows:</p></ol>
301
302<h5>image</h5>
303<ol><p>the image.</p></ol>
304
305<h5>x,y</h5>
306<ol><p>these values define the location of the pixel to return.</p></ol>
307
308<h5>pixel</h5>
309<ol><p>return a pixel at the specified (x,y) location.</p></ol>
310
311<h5>exception</h5>
312<ol><p>return any errors or warnings in this structure.</p></ol>
313
314 </div>
315<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
316_8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
317<div class="doc-section">
318
319<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>
320
321<p>The format of the GetOneVirtualMethodPixel() method is:</p>
322
323<pre class="code">
324 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]325 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
326 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]327</pre>
328
329<p>A description of each parameter follows:</p></ol>
330
331<h5>image</h5>
332<ol><p>the image.</p></ol>
333
334<h5>virtual_pixel_method</h5>
335<ol><p>the virtual pixel method.</p></ol>
336
337<h5>x,y</h5>
338<ol><p>These values define the location of the pixel to return.</p></ol>
339
340<h5>pixel</h5>
341<ol><p>return a pixel at the specified (x,y) location.</p></ol>
342
343<h5>exception</h5>
344<ol><p>return any errors or warnings in this structure.</p></ol>
345
346 </div>
347<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
348_8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
349<div class="doc-section">
350
351<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>
352
353<p>The format of the GetOneVirtualPixel() method is:</p>
354
355<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]356 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
357 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]358</pre>
359
360<p>A description of each parameter follows:</p></ol>
361
362<h5>image</h5>
363<ol><p>the image.</p></ol>
364
365<h5>x,y</h5>
366<ol><p>These values define the location of the pixel to return.</p></ol>
367
368<h5>pixel</h5>
369<ol><p>return a pixel at the specified (x,y) location.</p></ol>
370
371<h5>exception</h5>
372<ol><p>return any errors or warnings in this structure.</p></ol>
373
374 </div>
375<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
376_8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
377<div class="doc-section">
378
379<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>
380
381<p>The format of the GetVirtualIndexQueue() method is:</p>
382
383<pre class="code">
384 const IndexPacket *GetVirtualIndexQueue(const Image *image)
385</pre>
386
387<p>A description of each parameter follows:</p></ol>
388
389<h5>image</h5>
390<ol><p>the image.</p></ol>
391
392 </div>
393<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
394_8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
395<div class="doc-section">
396
397<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>
398 </div>
399<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
400_8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
401<div class="doc-section">
402
403<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
404
405<p>The format of the GetVirtualPixelQueue() method is:</p>
406
407<pre class="code">
408 const PixelPacket *GetVirtualPixelQueue(const Image image)
409</pre>
410
411<p>A description of each parameter follows:</p></ol>
412
413<h5>image</h5>
414<ol><p>the image.</p></ol>
415
416 </div>
417<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
418_8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
419<div class="doc-section">
420
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]421<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]422
423<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>
424
425<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
426
427<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
428
429<p>The format of the GetVirtualPixels() method is:</p>
430
431<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]432 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
433 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]434 ExceptionInfo *exception)
435</pre>
436
437<p>A description of each parameter follows:</p></ol>
438
439<h5>image</h5>
440<ol><p>the image.</p></ol>
441
442<h5>x,y,columns,rows</h5>
443<ol><p>These values define the perimeter of a region of pixels.</p></ol>
444
445<h5>exception</h5>
446<ol><p>return any errors or warnings in this structure.</p></ol>
447
448 </div>
449<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
450_8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
451<div class="doc-section">
452
453<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>
454
455<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>
456
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]457<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]458
459<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>
460
461<p>The format of the QueueAuthenticPixels() method is:</p>
462
463<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]464 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
465 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]466 ExceptionInfo *exception)
467</pre>
468
469<p>A description of each parameter follows:</p></ol>
470
471<h5>image</h5>
472<ol><p>the image.</p></ol>
473
474<h5>x,y,columns,rows</h5>
475<ol><p>These values define the perimeter of a region of pixels.</p></ol>
476
477<h5>exception</h5>
478<ol><p>return any errors or warnings in this structure.</p></ol>
479
480 </div>
481<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
482_8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
483<div class="doc-section">
484
485<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>
486
487<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
488
489<pre class="code">
490 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
491 const VirtualPixelMethod virtual_pixel_method)
492</pre>
493
494<p>A description of each parameter follows:</p></ol>
495
496<h5>image</h5>
497<ol><p>the image.</p></ol>
498
499<h5>virtual_pixel_method</h5>
500<ol><p>choose the type of virtual pixel.</p></ol>
501
502 </div>
503<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
504_8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
505<div class="doc-section">
506
507<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>
508
509<p>The format of the SyncAuthenticPixels() method is:</p>
510
511<pre class="code">
512 MagickBooleanType SyncAuthenticPixels(Image *image,
513 ExceptionInfo *exception)
514</pre>
515
516<p>A description of each parameter follows:</p></ol>
517
518<h5>image</h5>
519<ol><p>the image.</p></ol>
520
521<h5>exception</h5>
522<ol><p>return any errors or warnings in this structure.</p></ol>
523
524 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]525
526</div>
527
528<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]529 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]530 <span id="linkbar-center">
531 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]532 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]533 </span>
534 <span id="linkbar-east">&nbsp;</span>
535 </div>
536 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]537 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]538 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
539 </div>
540 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]541 <script type="text/javascript">
542 var _gaq = _gaq || [];
543 _gaq.push(['_setAccount', 'UA-17690367-1']);
544 _gaq.push(['_trackPageview']);
545
546 (function() {
547 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
548 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
549 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
550 })();
551 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]552</body>
553</html>