blob: f029df87544c400053f9bab128a2b88a7515def2 [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]"
cristy52923442011-01-15 22:54:31 +000053 style="margin-top: 42px; border: 0px; float: left;" /></a>
cristy3eaa0ef2010-03-06 20:35:26 +000054<a href="http://www.imagemagick.org/discourse-server/">
55 <img src="../../images/logo.jpg" alt=""
cristy178edaf2011-01-23 03:42:39 +000056 style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
cristy3eaa0ef2010-03-06 20:35:26 +000057<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">
cristy52923442011-01-15 22:54:31 +0000129 <a title="Search" href="../../www/search.html">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">
cristy178edaf2011-01-23 03:42:39 +0000143<div class="sponsor">
144 <a title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201106010240 -->
145</div>
cristyec6b4752011-01-08 03:16:23 +0000146<div class="sponsor">
cristy52923442011-01-15 22:54:31 +0000147 <a title="Sponsor: Web Hosting" href="http://www.bodhost.com/hosting.shtml">Web Hosting</a><!-- 201104010090 -->
cristy7d52cd62010-10-01 17:26:59 +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">
cristy178edaf2011-01-23 03:42:39 +0000156 <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
157</div>
158<div class="sponsor">
cristyf7964272011-01-30 03:49:12 +0000159 <a title="Sponsor: Custom T-Shirts" href="http://www.ooshirts.com">Custom T-Shirts</a><!-- 2011050100030 ooshirts.com-->
cristyec6b4752011-01-08 03:16:23 +0000160</div>
cristy3ed852e2009-09-05 21:47:34 +0000161</div>
162</div>
cristyce69bb02010-07-27 19:49:46 +0000163</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000164
cristyce69bb02010-07-27 19:49:46 +0000165<div class="eastbar">
166 <script type="text/javascript">
167 <!--
168 google_ad_client = "pub-3129977114552745";
cristyce69bb02010-07-27 19:49:46 +0000169 google_ad_slot = "0574824969";
170 google_ad_width = 160;
171 google_ad_height = 600;
172 //-->
173 </script>
174 <script type="text/javascript"
175 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
176 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000177</div>
178
179<div class="main">
180
cristy307ba182010-12-25 01:00:34 +0000181<h1>Module cache
182 Methods</h1>
cristy3ed852e2009-09-05 21:47:34 +0000183<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>
184
cristy7a40ba82011-01-08 20:31:18 +0000185<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
186_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000187<div class="doc-section">
188
cristy7a40ba82011-01-08 20:31:18 +0000189<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000190
191<p>The format of the AcquirePixelCacheNexus method is:</p>
192
193<pre class="code">
cristybb503372010-05-27 20:51:26 +0000194 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
cristy3ed852e2009-09-05 21:47:34 +0000195</pre>
196
cristy7a40ba82011-01-08 20:31:18 +0000197<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000198
199<h5>number_threads</h5>
cristy7a40ba82011-01-08 20:31:18 +0000200<p>the number of nexus threads.</p>
cristy3ed852e2009-09-05 21:47:34 +0000201
202 </div>
cristy7a40ba82011-01-08 20:31:18 +0000203<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
204_8c.html" id="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000205<div class="doc-section">
206
cristy7a40ba82011-01-08 20:31:18 +0000207<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 +0000208
209<p>The format of the GetAuthenticIndexQueue() method is:</p>
210
211<pre class="code">
212 IndexPacket *GetAuthenticIndexQueue(const Image *image)
213</pre>
214
cristy7a40ba82011-01-08 20:31:18 +0000215<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000216
217<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000218<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000219
220 </div>
cristy7a40ba82011-01-08 20:31:18 +0000221<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
222_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000223<div class="doc-section">
224
cristy7a40ba82011-01-08 20:31:18 +0000225<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p>
cristy3ed852e2009-09-05 21:47:34 +0000226
227<p>The format of the GetAuthenticPixelQueue() method is:</p>
228
229<pre class="code">
230 PixelPacket *GetAuthenticPixelQueue(const Image image)
231</pre>
232
cristy7a40ba82011-01-08 20:31:18 +0000233<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000234
235<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000236<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000237
238 </div>
cristy7a40ba82011-01-08 20:31:18 +0000239<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
240_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000241<div class="doc-section">
242
cristy7a40ba82011-01-08 20:31:18 +0000243<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 +0000244
cristy7a40ba82011-01-08 20:31:18 +0000245<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 +0000246
cristy7a40ba82011-01-08 20:31:18 +0000247<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 +0000248
249<p>The format of the GetAuthenticPixels() method is:</p>
250
251<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000252 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
253 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000254 ExceptionInfo *exception)
255</pre>
256
cristy7a40ba82011-01-08 20:31:18 +0000257<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000258
259<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000260<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000261
262<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000263<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000264
265<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000266<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000267
268 </div>
cristy7a40ba82011-01-08 20:31:18 +0000269<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
270_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000271<div class="doc-section">
272
cristy7a40ba82011-01-08 20:31:18 +0000273<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 +0000274
275<p>The format of the GetOneAuthenticPixel() method is:</p>
276
277<pre class="code">
cristybb503372010-05-27 20:51:26 +0000278 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
279 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
cristy3ed852e2009-09-05 21:47:34 +0000280</pre>
281
cristy7a40ba82011-01-08 20:31:18 +0000282<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000283
284<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000285<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000286
287<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000288<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000289
290<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000291<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000292
293<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000294<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000295
296 </div>
cristy7a40ba82011-01-08 20:31:18 +0000297<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
298_8c.html" id="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000299<div class="doc-section">
300
cristy7a40ba82011-01-08 20:31:18 +0000301<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 +0000302
303<p>The format of the GetOneVirtualMagickPixel() method is:</p>
304
305<pre class="code">
306 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000307 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
cristy3ed852e2009-09-05 21:47:34 +0000308 ExceptionInfo exception)
309</pre>
310
cristy7a40ba82011-01-08 20:31:18 +0000311<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000312
313<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000314<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000315
316<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000317<p>these values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000318
319<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000320<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000321
322<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000323<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000324
325 </div>
cristy7a40ba82011-01-08 20:31:18 +0000326<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
327_8c.html" id="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000328<div class="doc-section">
329
cristy7a40ba82011-01-08 20:31:18 +0000330<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 +0000331
332<p>The format of the GetOneVirtualMethodPixel() method is:</p>
333
334<pre class="code">
335 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
cristybb503372010-05-27 20:51:26 +0000336 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
337 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000338</pre>
339
cristy7a40ba82011-01-08 20:31:18 +0000340<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000341
342<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000343<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000344
345<h5>virtual_pixel_method</h5>
cristy7a40ba82011-01-08 20:31:18 +0000346<p>the virtual pixel method.</p>
cristy3ed852e2009-09-05 21:47:34 +0000347
348<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000349<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000350
351<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000352<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000353
354<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000355<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000356
357 </div>
cristy7a40ba82011-01-08 20:31:18 +0000358<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
359_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000360<div class="doc-section">
361
cristy7a40ba82011-01-08 20:31:18 +0000362<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 +0000363
364<p>The format of the GetOneVirtualPixel() method is:</p>
365
366<pre class="code">
cristybb503372010-05-27 20:51:26 +0000367 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
368 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
cristy3ed852e2009-09-05 21:47:34 +0000369</pre>
370
cristy7a40ba82011-01-08 20:31:18 +0000371<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000372
373<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000374<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000375
376<h5>x,y</h5>
cristy7a40ba82011-01-08 20:31:18 +0000377<p>These values define the location of the pixel to return.</p>
cristy3ed852e2009-09-05 21:47:34 +0000378
379<h5>pixel</h5>
cristy7a40ba82011-01-08 20:31:18 +0000380<p>return a pixel at the specified (x,y) location.</p>
cristy3ed852e2009-09-05 21:47:34 +0000381
382<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000383<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000384
385 </div>
cristy7a40ba82011-01-08 20:31:18 +0000386<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
387_8c.html" id="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000388<div class="doc-section">
389
cristy7a40ba82011-01-08 20:31:18 +0000390<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 +0000391
392<p>The format of the GetVirtualIndexQueue() method is:</p>
393
394<pre class="code">
395 const IndexPacket *GetVirtualIndexQueue(const Image *image)
396</pre>
397
cristy7a40ba82011-01-08 20:31:18 +0000398<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000399
400<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000401<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000402
403 </div>
cristy7a40ba82011-01-08 20:31:18 +0000404<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
405_8c.html" id="VirtualPixelModulo">VirtualPixelModulo</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000406<div class="doc-section">
407
408<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>
409 </div>
cristy7a40ba82011-01-08 20:31:18 +0000410<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
411_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000412<div class="doc-section">
413
cristy7a40ba82011-01-08 20:31:18 +0000414<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p>
cristy3ed852e2009-09-05 21:47:34 +0000415
416<p>The format of the GetVirtualPixelQueue() method is:</p>
417
418<pre class="code">
419 const PixelPacket *GetVirtualPixelQueue(const Image image)
420</pre>
421
cristy7a40ba82011-01-08 20:31:18 +0000422<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000423
424<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000425<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000426
427 </div>
cristy7a40ba82011-01-08 20:31:18 +0000428<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
429_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000430<div class="doc-section">
431
cristy7a40ba82011-01-08 20:31:18 +0000432<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 +0000433
cristy7a40ba82011-01-08 20:31:18 +0000434<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 +0000435
cristy7a40ba82011-01-08 20:31:18 +0000436<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p>
cristy3ed852e2009-09-05 21:47:34 +0000437
cristy7a40ba82011-01-08 20:31:18 +0000438<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 +0000439
440<p>The format of the GetVirtualPixels() method is:</p>
441
442<pre class="code">
cristybb503372010-05-27 20:51:26 +0000443 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
444 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000445 ExceptionInfo *exception)
446</pre>
447
cristy7a40ba82011-01-08 20:31:18 +0000448<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000449
450<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000451<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000452
453<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000454<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000455
456<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000457<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000458
459 </div>
cristy7a40ba82011-01-08 20:31:18 +0000460<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
461_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000462<div class="doc-section">
463
cristy7a40ba82011-01-08 20:31:18 +0000464<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 +0000465
cristy7a40ba82011-01-08 20:31:18 +0000466<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 +0000467
cristy7a40ba82011-01-08 20:31:18 +0000468<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 +0000469
cristy7a40ba82011-01-08 20:31:18 +0000470<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 +0000471
472<p>The format of the QueueAuthenticPixels() method is:</p>
473
474<pre class="code">
cristyeaedf062010-05-29 22:36:02 +0000475 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
476 const ssize_t y,const size_t columns,const size_t rows,
cristy3ed852e2009-09-05 21:47:34 +0000477 ExceptionInfo *exception)
478</pre>
479
cristy7a40ba82011-01-08 20:31:18 +0000480<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000481
482<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000483<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000484
485<h5>x,y,columns,rows</h5>
cristy7a40ba82011-01-08 20:31:18 +0000486<p>These values define the perimeter of a region of pixels.</p>
cristy3ed852e2009-09-05 21:47:34 +0000487
488<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000489<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000490
491 </div>
cristy7a40ba82011-01-08 20:31:18 +0000492<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
493_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000494<div class="doc-section">
495
cristy7a40ba82011-01-08 20:31:18 +0000496<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 +0000497
498<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
499
500<pre class="code">
501 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
502 const VirtualPixelMethod virtual_pixel_method)
503</pre>
504
cristy7a40ba82011-01-08 20:31:18 +0000505<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000506
507<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000508<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000509
510<h5>virtual_pixel_method</h5>
cristy7a40ba82011-01-08 20:31:18 +0000511<p>choose the type of virtual pixel.</p>
cristy3ed852e2009-09-05 21:47:34 +0000512
513 </div>
cristy7a40ba82011-01-08 20:31:18 +0000514<h2><a href="http://www.wizards-toolkit.org/api/MagickCore/cache
515_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
cristy3ed852e2009-09-05 21:47:34 +0000516<div class="doc-section">
517
cristy7a40ba82011-01-08 20:31:18 +0000518<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 +0000519
520<p>The format of the SyncAuthenticPixels() method is:</p>
521
522<pre class="code">
523 MagickBooleanType SyncAuthenticPixels(Image *image,
524 ExceptionInfo *exception)
525</pre>
526
cristy7a40ba82011-01-08 20:31:18 +0000527<p>A description of each parameter follows:</p>
cristy3ed852e2009-09-05 21:47:34 +0000528
529<h5>image</h5>
cristy7a40ba82011-01-08 20:31:18 +0000530<p>the image.</p>
cristy3ed852e2009-09-05 21:47:34 +0000531
532<h5>exception</h5>
cristy7a40ba82011-01-08 20:31:18 +0000533<p>return any errors or warnings in this structure.</p>
cristy3ed852e2009-09-05 21:47:34 +0000534
535 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000536
537</div>
538
539<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000540 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000541 <span id="linkbar-center">
542 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000543 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000544 </span>
545 <span id="linkbar-east">&nbsp;</span>
546 </div>
547 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000548 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000549 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
550 </div>
551 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000552 <script type="text/javascript">
553 var _gaq = _gaq || [];
554 _gaq.push(['_setAccount', 'UA-17690367-1']);
555 _gaq.push(['_trackPageview']);
556
557 (function() {
558 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
559 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
560 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
561 })();
562 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000563</body>
564</html>