Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / a890294753108889ed477181e5dd0ff5fc605f43 / . / www / api / cache.html
blob: 3164e022c1cce8a1299f882dec2b7ef4a78ce9bf [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">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]127 <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]128</div>
129<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]130 <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
cristy35aca9a2010-03-04 20:32:46 +0000[diff] [blame]131</div>
132<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]133 <a title="Sponsor: Deko.net" href="http://www.deko.net">Deko.net</a><!-- 201101010600 Peterssen-->
cristy1f9e1ed2009-11-18 04:09:38 +0000[diff] [blame]134</div>
135<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]136 <a title="Sponsor: Druckerei" href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
cristyc1c61662009-09-30 14:04:37 +0000[diff] [blame]137</div>
138<div class="sponsor">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]139 <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]140</div>
cristyd6dfc0d2010-06-27 19:30:49 +0000[diff] [blame]141<div class="sponsor">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]142 <a title="Sponsor: Free Catalogs" href="http://www.who-sells-it.com/">Free Catalogs</a><!-- 20120801000600 -->
cristyd6dfc0d2010-06-27 19:30:49 +0000[diff] [blame]143</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]144</div>
145</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]146</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]147
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]148<div class="eastbar">
149 <script type="text/javascript">
150 <!--
151 google_ad_client = "pub-3129977114552745";
152 /* 160x600, created 7/27/10 */
153 google_ad_slot = "0574824969";
154 google_ad_width = 160;
155 google_ad_height = 600;
156 //-->
157 </script>
158 <script type="text/javascript"
159 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
160 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]161</div>
162
163<div class="main">
164
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]165<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>
166
167<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
168_8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
169<div class="doc-section">
170
171<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
172
173<p>The format of the AcquirePixelCacheNexus method is:</p>
174
175<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]176 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]177</pre>
178
179<p>A description of each parameter follows:</p></ol>
180
181<h5>number_threads</h5>
182<ol><p>the number of nexus threads.</p></ol>
183
184 </div>
185<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
186_8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
187<div class="doc-section">
188
189<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>
190
191<p>The format of the GetAuthenticIndexQueue() method is:</p>
192
193<pre class="code">
194 IndexPacket *GetAuthenticIndexQueue(const Image *image)
195</pre>
196
197<p>A description of each parameter follows:</p></ol>
198
199<h5>image</h5>
200<ol><p>the image.</p></ol>
201
202 </div>
203<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
204_8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
205<div class="doc-section">
206
207<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
208
209<p>The format of the GetAuthenticPixelQueue() method is:</p>
210
211<pre class="code">
212 PixelPacket *GetAuthenticPixelQueue(const Image image)
213</pre>
214
215<p>A description of each parameter follows:</p></ol>
216
217<h5>image</h5>
218<ol><p>the image.</p></ol>
219
220 </div>
221<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
222_8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
223<div class="doc-section">
224
225<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>
226
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]227<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]228
229<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>
230
231<p>The format of the GetAuthenticPixels() method is:</p>
232
233<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]234 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
235 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]236 ExceptionInfo *exception)
237</pre>
238
239<p>A description of each parameter follows:</p></ol>
240
241<h5>image</h5>
242<ol><p>the image.</p></ol>
243
244<h5>x,y,columns,rows</h5>
245<ol><p>These values define the perimeter of a region of pixels.</p></ol>
246
247<h5>exception</h5>
248<ol><p>return any errors or warnings in this structure.</p></ol>
249
250 </div>
251<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
252_8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
253<div class="doc-section">
254
255<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p></ol>
256
257<p>The format of the GetOneAuthenticPixel() method is:</p>
258
259<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]260 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
261 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]262</pre>
263
264<p>A description of each parameter follows:</p></ol>
265
266<h5>image</h5>
267<ol><p>the image.</p></ol>
268
269<h5>x,y</h5>
270<ol><p>These values define the location of the pixel to return.</p></ol>
271
272<h5>pixel</h5>
273<ol><p>return a pixel at the specified (x,y) location.</p></ol>
274
275<h5>exception</h5>
276<ol><p>return any errors or warnings in this structure.</p></ol>
277
278 </div>
279<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
280_8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
281<div class="doc-section">
282
283<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>
284
285<p>The format of the GetOneVirtualMagickPixel() method is:</p>
286
287<pre class="code">
288 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]289 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]290 ExceptionInfo exception)
291</pre>
292
293<p>A description of each parameter follows:</p></ol>
294
295<h5>image</h5>
296<ol><p>the image.</p></ol>
297
298<h5>x,y</h5>
299<ol><p>these values define the location of the pixel to return.</p></ol>
300
301<h5>pixel</h5>
302<ol><p>return a pixel at the specified (x,y) location.</p></ol>
303
304<h5>exception</h5>
305<ol><p>return any errors or warnings in this structure.</p></ol>
306
307 </div>
308<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
309_8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
310<div class="doc-section">
311
312<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>
313
314<p>The format of the GetOneVirtualMethodPixel() method is:</p>
315
316<pre class="code">
317 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]318 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
319 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]320</pre>
321
322<p>A description of each parameter follows:</p></ol>
323
324<h5>image</h5>
325<ol><p>the image.</p></ol>
326
327<h5>virtual_pixel_method</h5>
328<ol><p>the virtual pixel method.</p></ol>
329
330<h5>x,y</h5>
331<ol><p>These values define the location of the pixel to return.</p></ol>
332
333<h5>pixel</h5>
334<ol><p>return a pixel at the specified (x,y) location.</p></ol>
335
336<h5>exception</h5>
337<ol><p>return any errors or warnings in this structure.</p></ol>
338
339 </div>
340<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
341_8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
342<div class="doc-section">
343
344<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>
345
346<p>The format of the GetOneVirtualPixel() method is:</p>
347
348<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]349 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
350 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]351</pre>
352
353<p>A description of each parameter follows:</p></ol>
354
355<h5>image</h5>
356<ol><p>the image.</p></ol>
357
358<h5>x,y</h5>
359<ol><p>These values define the location of the pixel to return.</p></ol>
360
361<h5>pixel</h5>
362<ol><p>return a pixel at the specified (x,y) location.</p></ol>
363
364<h5>exception</h5>
365<ol><p>return any errors or warnings in this structure.</p></ol>
366
367 </div>
368<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
369_8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
370<div class="doc-section">
371
372<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>
373
374<p>The format of the GetVirtualIndexQueue() method is:</p>
375
376<pre class="code">
377 const IndexPacket *GetVirtualIndexQueue(const Image *image)
378</pre>
379
380<p>A description of each parameter follows:</p></ol>
381
382<h5>image</h5>
383<ol><p>the image.</p></ol>
384
385 </div>
386<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
387_8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
388<div class="doc-section">
389
390<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>
391 </div>
392<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
393_8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
394<div class="doc-section">
395
396<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
397
398<p>The format of the GetVirtualPixelQueue() method is:</p>
399
400<pre class="code">
401 const PixelPacket *GetVirtualPixelQueue(const Image image)
402</pre>
403
404<p>A description of each parameter follows:</p></ol>
405
406<h5>image</h5>
407<ol><p>the image.</p></ol>
408
409 </div>
410<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
411_8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
412<div class="doc-section">
413
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]414<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]415
416<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>
417
418<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
419
420<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
421
422<p>The format of the GetVirtualPixels() method is:</p>
423
424<pre class="code">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]425 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
426 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]427 ExceptionInfo *exception)
428</pre>
429
430<p>A description of each parameter follows:</p></ol>
431
432<h5>image</h5>
433<ol><p>the image.</p></ol>
434
435<h5>x,y,columns,rows</h5>
436<ol><p>These values define the perimeter of a region of pixels.</p></ol>
437
438<h5>exception</h5>
439<ol><p>return any errors or warnings in this structure.</p></ol>
440
441 </div>
442<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
443_8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
444<div class="doc-section">
445
446<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>
447
448<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>
449
cristy16ff93c2010-01-13 23:18:07 +0000[diff] [blame]450<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]451
452<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>
453
454<p>The format of the QueueAuthenticPixels() method is:</p>
455
456<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000[diff] [blame]457 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
458 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]459 ExceptionInfo *exception)
460</pre>
461
462<p>A description of each parameter follows:</p></ol>
463
464<h5>image</h5>
465<ol><p>the image.</p></ol>
466
467<h5>x,y,columns,rows</h5>
468<ol><p>These values define the perimeter of a region of pixels.</p></ol>
469
470<h5>exception</h5>
471<ol><p>return any errors or warnings in this structure.</p></ol>
472
473 </div>
474<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
475_8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
476<div class="doc-section">
477
478<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>
479
480<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
481
482<pre class="code">
483 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
484 const VirtualPixelMethod virtual_pixel_method)
485</pre>
486
487<p>A description of each parameter follows:</p></ol>
488
489<h5>image</h5>
490<ol><p>the image.</p></ol>
491
492<h5>virtual_pixel_method</h5>
493<ol><p>choose the type of virtual pixel.</p></ol>
494
495 </div>
496<h2><a href="http://www.imagemagick.org/api/MagickCore/cache
497_8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
498<div class="doc-section">
499
500<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>
501
502<p>The format of the SyncAuthenticPixels() method is:</p>
503
504<pre class="code">
505 MagickBooleanType SyncAuthenticPixels(Image *image,
506 ExceptionInfo *exception)
507</pre>
508
509<p>A description of each parameter follows:</p></ol>
510
511<h5>image</h5>
512<ol><p>the image.</p></ol>
513
514<h5>exception</h5>
515<ol><p>return any errors or warnings in this structure.</p></ol>
516
517 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]518
519</div>
520
521<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]522 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]523 <span id="linkbar-center">
524 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame^]525 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]526 </span>
527 <span id="linkbar-east">&nbsp;</span>
528 </div>
529 <div class="footer">
530 <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>
531 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
532 </div>
533 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame^]534 <script type="text/javascript">
535 var _gaq = _gaq || [];
536 _gaq.push(['_setAccount', 'UA-17690367-1']);
537 _gaq.push(['_trackPageview']);
538
539 (function() {
540 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
541 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
542 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
543 })();
544 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]545</body>
546</html>