blob: 0080a5e2bff0c0b801049f7e33c85df118bddf31 [file] [log] [blame]
cristydcca3fa2010-12-29 21:50:07 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr">
cristy3eaa0ef2010-03-06 20:35:26 +00004<head>
cristy3c98a4f2010-08-13 20:09:41 +00005 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
6 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristyffb69ed2010-12-25 00:06:48 +00007 <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title>
cristy3ed852e2009-09-05 21:47:34 +00008 <meta http-equiv="Content-Language" content="en-US"/>
9 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
10 <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
cristy3c98a4f2010-08-13 20:09:41 +000011 <meta name="Application-name" content="ImageMagick"/>
cristydcca3fa2010-12-29 21:50:07 +000012 <meta name="Description" content="ImageMagick is a software suite to create, edit, compose, or convert bitmap images in a variety of formats. Use ImageMagick to scale, rotate, shear, distort and transform images."/>
cristy3c98a4f2010-08-13 20:09:41 +000013 <meta name="Application-url" content="http://www.imagemagick.org"/>
cristy3ed852e2009-09-05 21:47:34 +000014 <meta name="Generator" content="PHP"/>
15 <meta name="Keywords" content="magickcore, c, api, for, imagemagick:, get, or, set, image, pixels, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
cristy3ed852e2009-09-05 21:47:34 +000016 <meta name="Rating" content="GENERAL"/>
17 <meta name="Robots" content="INDEX, FOLLOW"/>
18 <meta name="Generator" content="ImageMagick Studio LLC"/>
19 <meta name="Author" content="ImageMagick Studio LLC"/>
20 <meta name="Revisit-after" content="2 DAYS"/>
21 <meta name="Resource-type" content="document"/>
cristy4103d562010-12-10 01:38:54 +000022 <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristy3ed852e2009-09-05 21:47:34 +000023 <meta name="Distribution" content="Global"/>
cristydcca3fa2010-12-29 21:50:07 +000024 <link rel="icon" href="../../images/wand.png"/>
cristy3c98a4f2010-08-13 20:09:41 +000025 <link rel="shortcut icon" href="../../images/wand.ico" type="images/x-icon"/>
26 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
cristy7a40ba82011-01-08 20:31:18 +000027 <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />
cristy3c98a4f2010-08-13 20:09:41 +000028 <style type="text/css" media="all">
29 @import url("../../www/magick.css");
30 </style>
cristydcca3fa2010-12-29 21:50:07 +000031 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
cristy361f4662010-12-31 23:02:52 +000032 <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
33 <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
34 <script type="text/javascript">
35 $(document).ready(function() {
36 $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
37 'transitionIn' : 'elastic',
38 'transitionOut' : 'elastic',
39 'overlayShow' : false,
40 'opacity' : true
41 });
42 });
43 </script>
cristy3eaa0ef2010-03-06 20:35:26 +000044</head>
45
46<body id="www-imagemagick-org">
47<div class="titlebar">
48<a href="../../index.html">
49 <img src="../../images/script.png" alt="[ImageMagick]"
50 style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
51<a href="http://www.networkredux.com">
52 <img src="../../images/networkredux.png" alt="[sponsor]"
53 style="margin: 45px auto; border: 0px; float: left;" /></a>
54<a href="http://www.imagemagick.org/discourse-server/">
55 <img src="../../images/logo.jpg" alt=""
56 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
57<a href="../../index.html">
58 <img src="../../images/sprite.jpg" alt=""
59 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
60</div>
61
cristyce69bb02010-07-27 19:49:46 +000062<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +000063
cristy3ed852e2009-09-05 21:47:34 +000064<div class="menu">
cristy83a272e2010-05-07 20:40:35 +000065 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +000066</div>
cristy3eaa0ef2010-03-06 20:35:26 +000067<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +000068<div class="menu">
cristybb503372010-05-27 20:51:26 +000069 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
70</div>
71<div class="sub">
72 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
73</div>
74<div class="sub">
75 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
76</div>
77<div class="sub">
78 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
79</div>
80<div class="sep"></div>
81<div class="menu">
cristy83a272e2010-05-07 20:40:35 +000082 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +000083</div>
84<div class="sub">
cristy83a272e2010-05-07 20:40:35 +000085 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristy3ed852e2009-09-05 21:47:34 +000086</div>
87<div class="sub">
cristy83a272e2010-05-07 20:40:35 +000088 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristy3ed852e2009-09-05 21:47:34 +000089</div>
90<div class="sub">
cristy83a272e2010-05-07 20:40:35 +000091 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +000092</div>
93<div class="menu">
cristy83a272e2010-05-07 20:40:35 +000094 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +000095</div>
96<div class="sub">
cristy83a272e2010-05-07 20:40:35 +000097 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristy3ed852e2009-09-05 21:47:34 +000098</div>
99<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000100 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
cristy3ed852e2009-09-05 21:47:34 +0000101</div>
102<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000103 <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000104</div>
105<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000106 <a title="Program Interface: Magick++" href="../../www/magick++.html">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000107</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000108<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000109<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000110 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristy3ed852e2009-09-05 21:47:34 +0000111</div>
112<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000113 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristy3ed852e2009-09-05 21:47:34 +0000114</div>
115<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000116 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000117 </div>
118<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000119 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000120</div>
cristybb503372010-05-27 20:51:26 +0000121<div class="menu">
122 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
123</div>
cristy3ed852e2009-09-05 21:47:34 +0000124<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000125 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000126</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000127<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000128<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000129 <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000130</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000131<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000132<div class="menu">
cristyffb69ed2010-12-25 00:06:48 +0000133 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000134</div>
135<div class="sub">
cristyffb69ed2010-12-25 00:06:48 +0000136 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000137</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000138<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000139<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000140 <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristy3ed852e2009-09-05 21:47:34 +0000141
142<div class="sponsbox">
cristyec6b4752011-01-08 03:16:23 +0000143<div class="sponsor">
144 <a title="Sponsor: Web Hosting" href="http://www.bodhost.com/hosting.html">Web Hosting</a><!-- 201104010090 -->
cristy7d52cd62010-10-01 17:26:59 +0000145</div>
146<div class="sponsor">
147 <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
cristy73fd1cd2010-09-12 19:14:25 +0000148</div>
149<div class="sponsor">
cristyc5baf4f2010-08-31 15:05:33 +0000150 <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
151</div>
152<div class="sponsor">
cristy851dbce2010-08-06 21:40:00 +0000153 <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
154</div>
cristyec6b4752011-01-08 03:16:23 +0000155<div class="sponsor">
cristy7a40ba82011-01-08 20:31:18 +0000156 <a title="Sponsor: Notebook Reparatur Berlin" href="http://www.notebook-reparaturen-berlin.de">Notebook Reparatur Berlin</a><!-- 2011050100025 gabi.schulze-->
cristyec6b4752011-01-08 03:16:23 +0000157</div>
cristy3ed852e2009-09-05 21:47:34 +0000158</div>
159</div>
cristyce69bb02010-07-27 19:49:46 +0000160</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000161
cristyce69bb02010-07-27 19:49:46 +0000162<div class="eastbar">
163 <script type="text/javascript">
164 <!--
165 google_ad_client = "pub-3129977114552745";
cristyce69bb02010-07-27 19:49:46 +0000166 google_ad_slot = "0574824969";
167 google_ad_width = 160;
168 google_ad_height = 600;
169 //-->
170 </script>
171 <script type="text/javascript"
172 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
173 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000174</div>
175
176<div class="main">
177
cristy307ba182010-12-25 01:00:34 +0000178<h1>Module cache
179 Methods</h1>
cristy3ed852e2009-09-05 21:47:34 +0000180<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>
181
cristy7a40ba82011-01-08 20:31:18 +0000182<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
183_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000184<div class="doc-section">
185
cristy7a40ba82011-01-08 20:31:18 +0000186<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000187
188<p>The format of the AcquirePixelCacheNexus method is:</p>
189
190<pre class="code">
cristybb503372010-05-27 20:51:26 +0000191 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000192</pre>
193
cristy7a40ba82011-01-08 20:31:18 +0000194<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000195
196<h5>number_threads</h5>
cristy7a40ba82011-01-08 20:31:18 +0000197<p>the number of nexus threads.</p>
cristy3ed852e2009-09-05 21:47:34 +0000198
199 </div>
cristy7a40ba82011-01-08 20:31:18 +0000200<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
201_8c.html" id="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000202<div class="doc-section">
203
cristy7a40ba82011-01-08 20:31:18 +0000204<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>
cristy3ed852e2009-09-05 21:47:34 +0000205
206<p>The format of the GetAuthenticIndexQueue() method is:</p>
207
208<pre class="code">
209 IndexPacket *GetAuthenticIndexQueue(const Image *image)
210</pre>
211
cristy7a40ba82011-01-08 20:31:18 +0000212<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000213
214<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000215<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000216
217 </div>
cristy7a40ba82011-01-08 20:31:18 +0000218<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
219_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000220<div class="doc-section">
221
cristy7a40ba82011-01-08 20:31:18 +0000222<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p>
cristy3ed852e2009-09-05 21:47:34 +0000223
224<p>The format of the GetAuthenticPixelQueue() method is:</p>
225
226<pre class="code">
227 PixelPacket *GetAuthenticPixelQueue(const Image image)
228</pre>
229
cristy7a40ba82011-01-08 20:31:18 +0000230<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000231
232<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000233<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000234
235 </div>
cristy7a40ba82011-01-08 20:31:18 +0000236<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
237_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000238<div class="doc-section">
239
cristy7a40ba82011-01-08 20:31:18 +0000240<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>
cristy3ed852e2009-09-05 21:47:34 +0000241
cristy7a40ba82011-01-08 20:31:18 +0000242<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>
cristy3ed852e2009-09-05 21:47:34 +0000243
cristy7a40ba82011-01-08 20:31:18 +0000244<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>
cristy3ed852e2009-09-05 21:47:34 +0000245
246<p>The format of the GetAuthenticPixels() method is:</p>
247
248<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000249 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
250 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000251 ExceptionInfo *exception)
252</pre>
253
cristy7a40ba82011-01-08 20:31:18 +0000254<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000255
256<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000257<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000258
259<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000260<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000261
262<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000263<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000264
265 </div>
cristy7a40ba82011-01-08 20:31:18 +0000266<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
267_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000268<div class="doc-section">
269
cristy7a40ba82011-01-08 20:31:18 +0000270<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p>
cristy3ed852e2009-09-05 21:47:34 +0000271
272<p>The format of the GetOneAuthenticPixel() method is:</p>
273
274<pre class="code">
cristybb503372010-05-27 20:51:26 +0000275 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
276 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000277</pre>
278
cristy7a40ba82011-01-08 20:31:18 +0000279<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000280
281<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000282<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000283
284<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000285<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000286
287<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000288<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000289
290<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000291<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000292
293 </div>
cristy7a40ba82011-01-08 20:31:18 +0000294<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
295_8c.html" id="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000296<div class="doc-section">
297
cristy7a40ba82011-01-08 20:31:18 +0000298<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>
cristy3ed852e2009-09-05 21:47:34 +0000299
300<p>The format of the GetOneVirtualMagickPixel() method is:</p>
301
302<pre class="code">
303 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000304 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000305 ExceptionInfo exception)
306</pre>
307
cristy7a40ba82011-01-08 20:31:18 +0000308<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000309
310<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000311<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000312
313<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000314<p>these values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000315
316<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000317<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000318
319<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000320<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000321
322 </div>
cristy7a40ba82011-01-08 20:31:18 +0000323<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
324_8c.html" id="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000325<div class="doc-section">
326
cristy7a40ba82011-01-08 20:31:18 +0000327<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>
cristy3ed852e2009-09-05 21:47:34 +0000328
329<p>The format of the GetOneVirtualMethodPixel() method is:</p>
330
331<pre class="code">
332 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000333 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
334 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000335</pre>
336
cristy7a40ba82011-01-08 20:31:18 +0000337<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000338
339<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000340<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000341
342<h5>virtual_pixel_method</h5>
cristy7a40ba82011-01-08 20:31:18 +0000343<p>the virtual pixel method.</p>
cristy3ed852e2009-09-05 21:47:34 +0000344
345<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000346<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000347
348<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000349<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000350
351<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000352<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000353
354 </div>
cristy7a40ba82011-01-08 20:31:18 +0000355<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
356_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000357<div class="doc-section">
358
cristy7a40ba82011-01-08 20:31:18 +0000359<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>
cristy3ed852e2009-09-05 21:47:34 +0000360
361<p>The format of the GetOneVirtualPixel() method is:</p>
362
363<pre class="code">
cristybb503372010-05-27 20:51:26 +0000364 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
365 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000366</pre>
367
cristy7a40ba82011-01-08 20:31:18 +0000368<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000369
370<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000371<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000372
373<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000374<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000375
376<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000377<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000378
379<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000380<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000381
382 </div>
cristy7a40ba82011-01-08 20:31:18 +0000383<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
384_8c.html" id="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000385<div class="doc-section">
386
cristy7a40ba82011-01-08 20:31:18 +0000387<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>
cristy3ed852e2009-09-05 21:47:34 +0000388
389<p>The format of the GetVirtualIndexQueue() method is:</p>
390
391<pre class="code">
392 const IndexPacket *GetVirtualIndexQueue(const Image *image)
393</pre>
394
cristy7a40ba82011-01-08 20:31:18 +0000395<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000396
397<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000398<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000399
400 </div>
cristy7a40ba82011-01-08 20:31:18 +0000401<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
402_8c.html" id="VirtualPixelModulo">VirtualPixelModulo</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000403<div class="doc-section">
404
405<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>
406 </div>
cristy7a40ba82011-01-08 20:31:18 +0000407<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
408_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000409<div class="doc-section">
410
cristy7a40ba82011-01-08 20:31:18 +0000411<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p>
cristy3ed852e2009-09-05 21:47:34 +0000412
413<p>The format of the GetVirtualPixelQueue() method is:</p>
414
415<pre class="code">
416 const PixelPacket *GetVirtualPixelQueue(const Image image)
417</pre>
418
cristy7a40ba82011-01-08 20:31:18 +0000419<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000420
421<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000422<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000423
424 </div>
cristy7a40ba82011-01-08 20:31:18 +0000425<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
426_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000427<div class="doc-section">
428
cristy7a40ba82011-01-08 20:31:18 +0000429<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>
cristy3ed852e2009-09-05 21:47:34 +0000430
cristy7a40ba82011-01-08 20:31:18 +0000431<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>
cristy3ed852e2009-09-05 21:47:34 +0000432
cristy7a40ba82011-01-08 20:31:18 +0000433<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p>
cristy3ed852e2009-09-05 21:47:34 +0000434
cristy7a40ba82011-01-08 20:31:18 +0000435<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p>
cristy3ed852e2009-09-05 21:47:34 +0000436
437<p>The format of the GetVirtualPixels() method is:</p>
438
439<pre class="code">
cristybb503372010-05-27 20:51:26 +0000440 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
441 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000442 ExceptionInfo *exception)
443</pre>
444
cristy7a40ba82011-01-08 20:31:18 +0000445<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000446
447<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000448<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000449
450<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000451<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000452
453<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000454<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000455
456 </div>
cristy7a40ba82011-01-08 20:31:18 +0000457<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
458_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000459<div class="doc-section">
460
cristy7a40ba82011-01-08 20:31:18 +0000461<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>
cristy3ed852e2009-09-05 21:47:34 +0000462
cristy7a40ba82011-01-08 20:31:18 +0000463<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>
cristy3ed852e2009-09-05 21:47:34 +0000464
cristy7a40ba82011-01-08 20:31:18 +0000465<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>
cristy3ed852e2009-09-05 21:47:34 +0000466
cristy7a40ba82011-01-08 20:31:18 +0000467<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>
cristy3ed852e2009-09-05 21:47:34 +0000468
469<p>The format of the QueueAuthenticPixels() method is:</p>
470
471<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000472 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
473 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000474 ExceptionInfo *exception)
475</pre>
476
cristy7a40ba82011-01-08 20:31:18 +0000477<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000478
479<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000480<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000481
482<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000483<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000484
485<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000486<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000487
488 </div>
cristy7a40ba82011-01-08 20:31:18 +0000489<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
490_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000491<div class="doc-section">
492
cristy7a40ba82011-01-08 20:31:18 +0000493<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>
cristy3ed852e2009-09-05 21:47:34 +0000494
495<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
496
497<pre class="code">
498 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
499 const VirtualPixelMethod virtual_pixel_method)
500</pre>
501
cristy7a40ba82011-01-08 20:31:18 +0000502<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000503
504<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000505<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000506
507<h5>virtual_pixel_method</h5>
cristy7a40ba82011-01-08 20:31:18 +0000508<p>choose the type of virtual pixel.</p>
cristy3ed852e2009-09-05 21:47:34 +0000509
510 </div>
cristy7a40ba82011-01-08 20:31:18 +0000511<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
512_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000513<div class="doc-section">
514
cristy7a40ba82011-01-08 20:31:18 +0000515<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>
cristy3ed852e2009-09-05 21:47:34 +0000516
517<p>The format of the SyncAuthenticPixels() method is:</p>
518
519<pre class="code">
520 MagickBooleanType SyncAuthenticPixels(Image *image,
521 ExceptionInfo *exception)
522</pre>
523
cristy7a40ba82011-01-08 20:31:18 +0000524<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000525
526<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000527<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000528
529<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000530<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000531
532 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000533
534</div>
535
536<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000537 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000538 <span id="linkbar-center">
539 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000540 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000541 </span>
542 <span id="linkbar-east">&nbsp;</span>
543 </div>
544 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000545 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000546 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
547 </div>
548 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000549 <script type="text/javascript">
550 var _gaq = _gaq || [];
551 _gaq.push(['_setAccount', 'UA-17690367-1']);
552 _gaq.push(['_trackPageview']);
553
554 (function() {
555 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
556 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
557 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
558 })();
559 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000560</body>
561</html>