Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 851dbceb0a51cbcd3ed512f074e9f2d797b7cbc1 / . / www / api / cache.html
blob: 7630d1870aa09e5905c9df80b059f523975c8555 [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>
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]5 <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]6 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U=" />
7 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf" />
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]8 <style type="text/css" media="all">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]9 @import url("../../www/magick.css");
cristy3de29cc2010-04-15 02:34:44 +0000[diff] [blame]10 </style>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]11 <link rel="shortcut icon" href="../../images/wand.ico" type="images/vnd.microsoft.icon"/>
12 <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title>
13 <meta http-equiv="Content-Language" content="en-US"/>
14 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
15 <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
16 <meta name="Generator" content="PHP"/>
17 <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"/>
18 <meta name="Description" content="ImageMagick® is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (about 100) including GIF, JPEG, JPEG-2000, PNG, PDF, PhotoCD, TIFF, and DPX. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves. ImageMagick is free software delivered as a ready-to-run binary distribution or as source code that you can freely use, copy, modify, and distribute. Its license is compatible with the GPL. It runs on all major operating systems. The functionality of ImageMagick is typically utilized from the command line or you can use the features from programs written in your favorite programming language. Choose from these interfaces: MagickCore (C), MagickWand (C), ChMagick (Ch), Magick++ (C++), JMagick (Java), L-Magick (Lisp), PascalMagick (Pascal), PerlMagick (Perl), MagickWand for PHP (PHP), PythonMagick (Python), RMagick (Ruby), or TclMagick (Tcl/TK). With a language interface, use ImageMagick to modify or create images automagically and dynamically."/>
19 <meta name="Rating" content="GENERAL"/>
20 <meta name="Robots" content="INDEX, FOLLOW"/>
21 <meta name="Generator" content="ImageMagick Studio LLC"/>
22 <meta name="Author" content="ImageMagick Studio LLC"/>
23 <meta name="Revisit-after" content="2 DAYS"/>
24 <meta name="Resource-type" content="document"/>
cristy16af1cb2009-12-11 21:38:29 +0000[diff] [blame]25 <meta name="Copyright" content="Copyright (c) 1999-2010 ImageMagick Studio LLC"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]26 <meta name="Distribution" content="Global"/>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]27</head>
28
29<body id="www-imagemagick-org">
30<div class="titlebar">
31<a href="../../index.html">
32 <img src="../../images/script.png" alt="[ImageMagick]"
33 style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
34<a href="http://www.networkredux.com">
35 <img src="../../images/networkredux.png" alt="[sponsor]"
36 style="margin: 45px auto; border: 0px; float: left;" /></a>
37<a href="http://www.imagemagick.org/discourse-server/">
38 <img src="../../images/logo.jpg" alt=""
39 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
40<a href="../../index.html">
41 <img src="../../images/sprite.jpg" alt=""
42 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
43</div>
44
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]45<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]46
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]47<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]48 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]49</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]50<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]51<div class="menu">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]52 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
53</div>
54<div class="sub">
55 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
56</div>
57<div class="sub">
58 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
59</div>
60<div class="sub">
61 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
62</div>
63<div class="sep"></div>
64<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]65 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]66</div>
67<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]68 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</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: Options" href="../../www/command-line-options.html">Options</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: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]75</div>
76<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]77 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]78</div>
79<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]80 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</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: MagickCore" href="../../www/magick-core.html">MagickCore</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: PerlMagick" href="../../www/perl-magick.html">PerlMagick</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: Magick++" href="../../Magick++/">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]90</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]91<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]92<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]93 <a title="Install from Source" href="../../www/install-source.html">Install from Source</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="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</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: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]100 </div>
101<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]102 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]103</div>
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]104<div class="menu">
105 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
106</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]107<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]108 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]109</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]110<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]111<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]112 <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]113</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]114<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]115<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]116 <a title="Site Map"href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]117</div>
118<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]119 <a title="Site Map: Links"href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]120</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]121<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]122<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]123 <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]124
125<div class="sponsbox">
126<div class="sponsor">
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame^]127 <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
128</div>
129<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]130 <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]131</div>
132<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]133 <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
cristy35aca9a2010-03-04 20:32:46 +0000[diff] [blame]134</div>
135<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]136 <a title="Sponsor: Deko.net" href="http://www.deko.net">Deko.net</a><!-- 201101010600 Peterssen-->
cristy1f9e1ed2009-11-18 04:09:38 +0000[diff] [blame]137</div>
138<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]139 <a title="Sponsor: Druckerei" href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
cristyc1c61662009-09-30 14:04:37 +0000[diff] [blame]140</div>
141<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]142 <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
cristyb4c03bb2009-09-27 13:55:46 +0000[diff] [blame]143</div>
cristyd6dfc0d2010-06-27 19:30:49 +0000[diff] [blame]144<div class="sponsor">
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame^]145 <a title="Sponsor: Online-Magazin" href="http://www.unkostenbeitrag.de/">Online-Magazin</a><!-- 20101101000200 -->
cristyd6dfc0d2010-06-27 19:30:49 +0000[diff] [blame]146</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]147</div>
148</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]149</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]150
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]151<div class="eastbar">
152 <script type="text/javascript">
153 <!--
154 google_ad_client = "pub-3129977114552745";
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]155 google_ad_slot = "0574824969";
156 google_ad_width = 160;
157 google_ad_height = 600;
158 //-->
159 </script>
160 <script type="text/javascript"
161 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
162 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]163</div>
164
165<div class="main">
166
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]167<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>
168
169<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
170_8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
171<div class="doc-section">
172
173<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
174
175<p>The format of the AcquirePixelCacheNexus method is:</p>
176
177<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]178 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]179</pre>
180
181<p>A description of each parameter follows:</p></ol>
182
183<h5>number_threads</h5>
184<ol><p>the number of nexus threads.</p></ol>
185
186 </div>
187<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
188_8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
189<div class="doc-section">
190
191<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>
192
193<p>The format of the GetAuthenticIndexQueue() method is:</p>
194
195<pre class="code">
196 IndexPacket *GetAuthenticIndexQueue(const Image *image)
197</pre>
198
199<p>A description of each parameter follows:</p></ol>
200
201<h5>image</h5>
202<ol><p>the image.</p></ol>
203
204 </div>
205<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
206_8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
207<div class="doc-section">
208
209<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
210
211<p>The format of the GetAuthenticPixelQueue() method is:</p>
212
213<pre class="code">
214 PixelPacket *GetAuthenticPixelQueue(const Image image)
215</pre>
216
217<p>A description of each parameter follows:</p></ol>
218
219<h5>image</h5>
220<ol><p>the image.</p></ol>
221
222 </div>
223<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
224_8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
225<div class="doc-section">
226
227<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>
228
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]229<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]230
231<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>
232
233<p>The format of the GetAuthenticPixels() method is:</p>
234
235<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]236 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
237 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]238 ExceptionInfo *exception)
239</pre>
240
241<p>A description of each parameter follows:</p></ol>
242
243<h5>image</h5>
244<ol><p>the image.</p></ol>
245
246<h5>x,y,columns,rows</h5>
247<ol><p>These values define the perimeter of a region of pixels.</p></ol>
248
249<h5>exception</h5>
250<ol><p>return any errors or warnings in this structure.</p></ol>
251
252 </div>
253<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
254_8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
255<div class="doc-section">
256
257<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p></ol>
258
259<p>The format of the GetOneAuthenticPixel() method is:</p>
260
261<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]262 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
263 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]264</pre>
265
266<p>A description of each parameter follows:</p></ol>
267
268<h5>image</h5>
269<ol><p>the image.</p></ol>
270
271<h5>x,y</h5>
272<ol><p>These values define the location of the pixel to return.</p></ol>
273
274<h5>pixel</h5>
275<ol><p>return a pixel at the specified (x,y) location.</p></ol>
276
277<h5>exception</h5>
278<ol><p>return any errors or warnings in this structure.</p></ol>
279
280 </div>
281<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
282_8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
283<div class="doc-section">
284
285<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>
286
287<p>The format of the GetOneVirtualMagickPixel() method is:</p>
288
289<pre class="code">
290 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]291 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]292 ExceptionInfo exception)
293</pre>
294
295<p>A description of each parameter follows:</p></ol>
296
297<h5>image</h5>
298<ol><p>the image.</p></ol>
299
300<h5>x,y</h5>
301<ol><p>these values define the location of the pixel to return.</p></ol>
302
303<h5>pixel</h5>
304<ol><p>return a pixel at the specified (x,y) location.</p></ol>
305
306<h5>exception</h5>
307<ol><p>return any errors or warnings in this structure.</p></ol>
308
309 </div>
310<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
311_8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
312<div class="doc-section">
313
314<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>
315
316<p>The format of the GetOneVirtualMethodPixel() method is:</p>
317
318<pre class="code">
319 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]320 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
321 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]322</pre>
323
324<p>A description of each parameter follows:</p></ol>
325
326<h5>image</h5>
327<ol><p>the image.</p></ol>
328
329<h5>virtual_pixel_method</h5>
330<ol><p>the virtual pixel method.</p></ol>
331
332<h5>x,y</h5>
333<ol><p>These values define the location of the pixel to return.</p></ol>
334
335<h5>pixel</h5>
336<ol><p>return a pixel at the specified (x,y) location.</p></ol>
337
338<h5>exception</h5>
339<ol><p>return any errors or warnings in this structure.</p></ol>
340
341 </div>
342<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
343_8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
344<div class="doc-section">
345
346<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>
347
348<p>The format of the GetOneVirtualPixel() method is:</p>
349
350<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]351 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
352 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]353</pre>
354
355<p>A description of each parameter follows:</p></ol>
356
357<h5>image</h5>
358<ol><p>the image.</p></ol>
359
360<h5>x,y</h5>
361<ol><p>These values define the location of the pixel to return.</p></ol>
362
363<h5>pixel</h5>
364<ol><p>return a pixel at the specified (x,y) location.</p></ol>
365
366<h5>exception</h5>
367<ol><p>return any errors or warnings in this structure.</p></ol>
368
369 </div>
370<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
371_8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
372<div class="doc-section">
373
374<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>
375
376<p>The format of the GetVirtualIndexQueue() method is:</p>
377
378<pre class="code">
379 const IndexPacket *GetVirtualIndexQueue(const Image *image)
380</pre>
381
382<p>A description of each parameter follows:</p></ol>
383
384<h5>image</h5>
385<ol><p>the image.</p></ol>
386
387 </div>
388<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
389_8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
390<div class="doc-section">
391
392<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>
393 </div>
394<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
395_8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
396<div class="doc-section">
397
398<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
399
400<p>The format of the GetVirtualPixelQueue() method is:</p>
401
402<pre class="code">
403 const PixelPacket *GetVirtualPixelQueue(const Image image)
404</pre>
405
406<p>A description of each parameter follows:</p></ol>
407
408<h5>image</h5>
409<ol><p>the image.</p></ol>
410
411 </div>
412<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
413_8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
414<div class="doc-section">
415
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]416<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]417
418<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>
419
420<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
421
422<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
423
424<p>The format of the GetVirtualPixels() method is:</p>
425
426<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]427 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
428 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]429 ExceptionInfo *exception)
430</pre>
431
432<p>A description of each parameter follows:</p></ol>
433
434<h5>image</h5>
435<ol><p>the image.</p></ol>
436
437<h5>x,y,columns,rows</h5>
438<ol><p>These values define the perimeter of a region of pixels.</p></ol>
439
440<h5>exception</h5>
441<ol><p>return any errors or warnings in this structure.</p></ol>
442
443 </div>
444<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
445_8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
446<div class="doc-section">
447
448<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>
449
450<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>
451
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]452<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]453
454<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>
455
456<p>The format of the QueueAuthenticPixels() method is:</p>
457
458<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]459 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
460 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]461 ExceptionInfo *exception)
462</pre>
463
464<p>A description of each parameter follows:</p></ol>
465
466<h5>image</h5>
467<ol><p>the image.</p></ol>
468
469<h5>x,y,columns,rows</h5>
470<ol><p>These values define the perimeter of a region of pixels.</p></ol>
471
472<h5>exception</h5>
473<ol><p>return any errors or warnings in this structure.</p></ol>
474
475 </div>
476<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
477_8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
478<div class="doc-section">
479
480<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>
481
482<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
483
484<pre class="code">
485 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
486 const VirtualPixelMethod virtual_pixel_method)
487</pre>
488
489<p>A description of each parameter follows:</p></ol>
490
491<h5>image</h5>
492<ol><p>the image.</p></ol>
493
494<h5>virtual_pixel_method</h5>
495<ol><p>choose the type of virtual pixel.</p></ol>
496
497 </div>
498<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
499_8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
500<div class="doc-section">
501
502<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>
503
504<p>The format of the SyncAuthenticPixels() method is:</p>
505
506<pre class="code">
507 MagickBooleanType SyncAuthenticPixels(Image *image,
508 ExceptionInfo *exception)
509</pre>
510
511<p>A description of each parameter follows:</p></ol>
512
513<h5>image</h5>
514<ol><p>the image.</p></ol>
515
516<h5>exception</h5>
517<ol><p>return any errors or warnings in this structure.</p></ol>
518
519 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]520
521</div>
522
523<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]524 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]525 <span id="linkbar-center">
526 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]527 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]528 </span>
529 <span id="linkbar-east">&nbsp;</span>
530 </div>
531 <div class="footer">
532 <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>
533 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
534 </div>
535 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]536 <script type="text/javascript">
537 var _gaq = _gaq || [];
538 _gaq.push(['_setAccount', 'UA-17690367-1']);
539 _gaq.push(['_trackPageview']);
540
541 (function() {
542 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
543 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
544 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
545 })();
546 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]547</body>
548</html>