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