Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / ba1758d71797bef0cbb262ab2ae7f5c7589d4f4a / . / www / api / cache.html
blob: 7d066ede81600f49f73db0668b12e36c9df8b953 [file] [log] [blame]
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
cristy2bd2a982011-02-15 00:52:58 +0000[diff] [blame]3<html version="-//W3C//DTD XHTML 1.1//EN"
4 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
5 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6 xsi:schemaLocation="http://www.w3.org/1999/xhtml
7 http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]8<head>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]9 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
10 <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]11 <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]12 <meta http-equiv="Content-Language" content="en-US"/>
13 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
14 <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]15 <meta name="Application-name" content="ImageMagick"/>
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]16 <meta name="Description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats. In addition resize, rotate, shear, distort and transform images."/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]17 <meta name="Application-url" content="http://www.imagemagick.org"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]18 <meta name="Generator" content="PHP"/>
19 <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 +0000[diff] [blame]20 <meta name="Rating" content="GENERAL"/>
21 <meta name="Robots" content="INDEX, FOLLOW"/>
22 <meta name="Generator" content="ImageMagick Studio LLC"/>
23 <meta name="Author" content="ImageMagick Studio LLC"/>
24 <meta name="Revisit-after" content="2 DAYS"/>
25 <meta name="Resource-type" content="document"/>
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]26 <meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]27 <meta name="Distribution" content="Global"/>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]28 <link rel="icon" href="../../images/wand.png"/>
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]29 <link rel="shortcut icon" href="../../images/wand.ico" type="images/x-icon"/>
30 <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
cristy7a40ba82011-01-08 20:31:18 +0000[diff] [blame]31 <link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" />
cristy3c98a4f2010-08-13 20:09:41 +0000[diff] [blame]32 <style type="text/css" media="all">
33 @import url("../../www/magick.css");
34 </style>
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]35 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
cristy361f4662010-12-31 23:02:52 +0000[diff] [blame]36 <script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
37 <link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
38 <script type="text/javascript">
39 $(document).ready(function() {
40 $("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
41 'transitionIn' : 'elastic',
42 'transitionOut' : 'elastic',
43 'overlayShow' : false,
44 'opacity' : true
45 });
46 });
47 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]48</head>
49
50<body id="www-imagemagick-org">
51<div class="titlebar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]52<div style="margin: 17px auto; float: left;">
53 <script type="text/javascript">
54 <!--
55 google_ad_client = "pub-3129977114552745";
56 google_ad_slot = "5439289906";
57 google_ad_width = 728;
58 google_ad_height = 90;
59 //-->
60 </script>
61 <script type="text/javascript"
62 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
63 </script>
64</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]65<a href="http://www.imagemagick.org/discourse-server/">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]66 <img src="../../images/logo.jpg"
67 alt="ImageMagick Logo"
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]68 style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]69<a href="../../index.html">
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]70 <img src="../../images/sprite.jpg"
71 alt="ImageMagick Sprite"
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]72 style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
73</div>
74
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]75<div class="westbar">
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]76
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]77<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]78 <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]79</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]80<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]81<div class="menu">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]82 <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
83</div>
84<div class="sub">
85 <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
86</div>
87<div class="sub">
88 <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
89</div>
90<div class="sub">
cristyda16f162011-02-19 23:52:17 +0000[diff] [blame]91 <a title="Binary Release: iPhone" href="../../www/binary-releases.html#iPhone">iPhone</a>
92</div>
93<div class="sub">
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]94 <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
95</div>
96<div class="sep"></div>
97<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]98 <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]99</div>
100<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]101 <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]102</div>
103<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]104 <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]105</div>
106<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]107 <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]108</div>
109<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]110 <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]111</div>
112<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]113 <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]114</div>
115<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]116 <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</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="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]120</div>
121<div class="sub">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]122 <a title="Program Interface: Magick++" href="../../www/magick++.html">Magick++</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]123</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]124<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]125<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]126 <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]127</div>
128<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]129 <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]130</div>
131<div class="sub">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]132 <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]133 </div>
134<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]135 <a title="Resources" href="../../www/resources.html">Resources</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]136</div>
cristybb503372010-05-27 20:51:26 +0000[diff] [blame]137<div class="menu">
138 <a title="Architecture" href="../../www/architecture.html">Architecture</a>
139</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]140<div class="menu">
cristy83a272e2010-05-07 20:40:35 +0000[diff] [blame]141 <a title="Download" href="../../www/download.html">Download</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]142</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]143<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]144<div class="menu">
cristy52923442011-01-15 22:54:31 +0000[diff] [blame]145 <a title="Search" href="../../www/search.html">Search</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]146</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]147<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]148<div class="menu">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]149 <a title="Site Map" href="../../www/sitemap.html">Site Map</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]150</div>
151<div class="sub">
cristyffb69ed2010-12-25 00:06:48 +0000[diff] [blame]152 <a title="Site Map: Links" href="../../www/links.html">Links</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]153</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]154<div class="sep"></div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]155<div class="menu">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]156 <a rel="follow" title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]157
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]158<a href="http://www.networkredux.com">
159 <img src="../../images/networkredux.png" alt="[sponsor]"
160 style="margin-top: 4px; margin-left: 4px; border: 0px; float: left;" /></a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]161<div class="sponsbox">
cristy178edaf2011-01-23 03:42:39 +0000[diff] [blame]162<div class="sponsor">
cristyba1758d2011-06-03 01:29:12 +0000[diff] [blame^]163 <a rel="follow" title="Sponsor: Web Hosting Deals" href="http://www.webhostingdeals.org">Web Hosting Deals</a><!-- 201111010270 chee.hoa darin -->
164</div>
165<div class="sponsor">
166 <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingsecretrevealed.com">Web Hosting Secret Revealed</a><!-- 201204010540 iamchee jerry -->
167</div>
168<div class="sponsor">
169 <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
170</div>
171<div class="sponsor">
cristy4bf6e232011-05-21 01:43:33 +0000[diff] [blame]172 <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
cristy45dbd322011-03-27 16:40:38 +0000[diff] [blame]173</div>
174<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]175 <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
cristy4c54bbb2011-03-17 13:53:13 +0000[diff] [blame]176</div>
177<div class="sponsor">
cristy575d5ee2011-05-24 01:59:01 +0000[diff] [blame]178 <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201110010090 alexanian media -->
cristy4bf6e232011-05-21 01:43:33 +0000[diff] [blame]179</div>
180<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]181 <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
cristyaf8d6652011-02-04 21:57:45 +0000[diff] [blame]182</div>
183<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]184 <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
cristy7d52cd62010-10-01 17:26:59 +0000[diff] [blame]185</div>
186<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]187 <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
cristyee742642011-02-26 02:49:59 +0000[diff] [blame]188</div>
189<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]190 <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingmasters.com">Web Hosting Reviews</a><!-- 201107011500 affliatelabel -->
cristy851dbce2010-08-06 21:40:00 +0000[diff] [blame]191</div>
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]192<div class="sponsor">
cristy10549a12011-05-15 19:04:46 +0000[diff] [blame]193 <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
cristybaacd172011-04-30 23:11:03 +0000[diff] [blame]194</div>
195<div class="sponsor">
cristyba1758d2011-06-03 01:29:12 +0000[diff] [blame^]196 <a rel="follow" title="Sponsor: Notebook Reparatur" href="http://www.atlas-multimedia.de">Notebook Reparatur</a><!-- 2011090100025 atlas.multimedia-->
cristyec6b4752011-01-08 03:16:23 +0000[diff] [blame]197</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]198</div>
199</div>
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]200</div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]201
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]202<div class="eastbar">
cristyb52981c2011-03-19 17:09:31 +0000[diff] [blame]203
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]204</div>
205
206<div class="main">
207
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]208<h1>Module cache Methods</h1>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]209<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>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]210
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]211<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]212<div class="doc-section">
213
214<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p>
215
216<p>The format of the AcquirePixelCacheNexus method is:</p>
217
218<pre class="code">
219 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
220</pre>
221
222<p>A description of each parameter follows:</p>
223
224<h5>number_threads</h5>
225<p>the number of nexus threads.</p>
226
227 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]228<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]229<div class="doc-section">
230
231<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>
232
233<p>The format of the GetAuthenticIndexQueue() method is:</p>
234
235<pre class="code">
236 IndexPacket *GetAuthenticIndexQueue(const Image *image)
237</pre>
238
239<p>A description of each parameter follows:</p>
240
241<h5>image</h5>
242<p>the image.</p>
243
244 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]245<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]246<div class="doc-section">
247
248<p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p>
249
250<p>The format of the GetAuthenticPixelQueue() method is:</p>
251
252<pre class="code">
253 PixelPacket *GetAuthenticPixelQueue(const Image image)
254</pre>
255
256<p>A description of each parameter follows:</p>
257
258<h5>image</h5>
259<p>the image.</p>
260
261 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]262<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]263<div class="doc-section">
264
265<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>
266
267<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>
268
269<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>
270
271<p>The format of the GetAuthenticPixels() method is:</p>
272
273<pre class="code">
274 PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
275 const ssize_t y,const size_t columns,const size_t rows,
276 ExceptionInfo *exception)
277</pre>
278
279<p>A description of each parameter follows:</p>
280
281<h5>image</h5>
282<p>the image.</p>
283
284<h5>x,y,columns,rows</h5>
285<p>These values define the perimeter of a region of pixels.</p>
286
287<h5>exception</h5>
288<p>return any errors or warnings in this structure.</p>
289
290 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]291<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]292<div class="doc-section">
293
294<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p>
295
296<p>The format of the GetOneAuthenticPixel() method is:</p>
297
298<pre class="code">
299 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
300 const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
301</pre>
302
303<p>A description of each parameter follows:</p>
304
305<h5>image</h5>
306<p>the image.</p>
307
308<h5>x,y</h5>
309<p>These values define the location of the pixel to return.</p>
310
311<h5>pixel</h5>
312<p>return a pixel at the specified (x,y) location.</p>
313
314<h5>exception</h5>
315<p>return any errors or warnings in this structure.</p>
316
317 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]318<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]319<div class="doc-section">
320
321<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>
322
323<p>The format of the GetOneVirtualMagickPixel() method is:</p>
324
325<pre class="code">
326 MagickBooleanType GetOneVirtualMagickPixel(const Image image,
327 const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
328 ExceptionInfo exception)
329</pre>
330
331<p>A description of each parameter follows:</p>
332
333<h5>image</h5>
334<p>the image.</p>
335
336<h5>x,y</h5>
337<p>these values define the location of the pixel to return.</p>
338
339<h5>pixel</h5>
340<p>return a pixel at the specified (x,y) location.</p>
341
342<h5>exception</h5>
343<p>return any errors or warnings in this structure.</p>
344
345 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]346<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]347<div class="doc-section">
348
349<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>
350
351<p>The format of the GetOneVirtualMethodPixel() method is:</p>
352
353<pre class="code">
354 MagickBooleanType GetOneVirtualMethodPixel(const Image image,
355 const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
356 const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
357</pre>
358
359<p>A description of each parameter follows:</p>
360
361<h5>image</h5>
362<p>the image.</p>
363
364<h5>virtual_pixel_method</h5>
365<p>the virtual pixel method.</p>
366
367<h5>x,y</h5>
368<p>These values define the location of the pixel to return.</p>
369
370<h5>pixel</h5>
371<p>return a pixel at the specified (x,y) location.</p>
372
373<h5>exception</h5>
374<p>return any errors or warnings in this structure.</p>
375
376 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]377<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]378<div class="doc-section">
379
380<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>
381
382<p>The format of the GetOneVirtualPixel() method is:</p>
383
384<pre class="code">
385 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
386 const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
387</pre>
388
389<p>A description of each parameter follows:</p>
390
391<h5>image</h5>
392<p>the image.</p>
393
394<h5>x,y</h5>
395<p>These values define the location of the pixel to return.</p>
396
397<h5>pixel</h5>
398<p>return a pixel at the specified (x,y) location.</p>
399
400<h5>exception</h5>
401<p>return any errors or warnings in this structure.</p>
402
403 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]404<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]405<div class="doc-section">
406
407<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>
408
409<p>The format of the GetVirtualIndexQueue() method is:</p>
410
411<pre class="code">
412 const IndexPacket *GetVirtualIndexQueue(const Image *image)
413</pre>
414
415<p>A description of each parameter follows:</p>
416
417<h5>image</h5>
418<p>the image.</p>
419
420 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]421<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="VirtualPixelModulo">VirtualPixelModulo</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]422<div class="doc-section">
423
424<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>
425 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]426<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]427<div class="doc-section">
428
429<p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p>
430
431<p>The format of the GetVirtualPixelQueue() method is:</p>
432
433<pre class="code">
434 const PixelPacket *GetVirtualPixelQueue(const Image image)
435</pre>
436
437<p>A description of each parameter follows:</p>
438
439<h5>image</h5>
440<p>the image.</p>
441
442 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]443<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]444<div class="doc-section">
445
446<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>
447
448<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>
449
450<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p>
451
452<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p>
453
454<p>The format of the GetVirtualPixels() method is:</p>
455
456<pre class="code">
457 const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
458 const ssize_t y,const size_t columns,const size_t rows,
459 ExceptionInfo *exception)
460</pre>
461
462<p>A description of each parameter follows:</p>
463
464<h5>image</h5>
465<p>the image.</p>
466
467<h5>x,y,columns,rows</h5>
468<p>These values define the perimeter of a region of pixels.</p>
469
470<h5>exception</h5>
471<p>return any errors or warnings in this structure.</p>
472
473 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]474<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]475<div class="doc-section">
476
477<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>
478
479<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>
480
481<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>
482
483<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>
484
485<p>The format of the QueueAuthenticPixels() method is:</p>
486
487<pre class="code">
488 PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
489 const ssize_t y,const size_t columns,const size_t rows,
490 ExceptionInfo *exception)
491</pre>
492
493<p>A description of each parameter follows:</p>
494
495<h5>image</h5>
496<p>the image.</p>
497
498<h5>x,y,columns,rows</h5>
499<p>These values define the perimeter of a region of pixels.</p>
500
501<h5>exception</h5>
502<p>return any errors or warnings in this structure.</p>
503
504 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]505<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]506<div class="doc-section">
507
508<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>
509
510<p>The format of the SetPixelCacheVirtualMethod() method is:</p>
511
512<pre class="code">
513 VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
514 const VirtualPixelMethod virtual_pixel_method)
515</pre>
516
517<p>A description of each parameter follows:</p>
518
519<h5>image</h5>
520<p>the image.</p>
521
522<h5>virtual_pixel_method</h5>
523<p>choose the type of virtual pixel.</p>
524
525 </div>
cristy350dea42011-02-15 17:31:04 +0000[diff] [blame]526<h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
cristy6f77f692011-02-15 15:31:39 +0000[diff] [blame]527<div class="doc-section">
528
529<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>
530
531<p>The format of the SyncAuthenticPixels() method is:</p>
532
533<pre class="code">
534 MagickBooleanType SyncAuthenticPixels(Image *image,
535 ExceptionInfo *exception)
536</pre>
537
538<p>A description of each parameter follows:</p>
539
540<h5>image</h5>
541<p>the image.</p>
542
543<h5>exception</h5>
544<p>return any errors or warnings in this structure.</p>
545
546 </div>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]547
548</div>
549
550<div id="linkbar">
cristyce69bb02010-07-27 19:49:46 +0000[diff] [blame]551 <span id="linkbar-west">&nbsp;</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]552 <span id="linkbar-center">
553 <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]554 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]555 </span>
556 <span id="linkbar-east">&nbsp;</span>
557 </div>
558 <div class="footer">
cristy4103d562010-12-10 01:38:54 +0000[diff] [blame]559 <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]560 <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
561 </div>
562 <div style="clear: both; margin: 0; width: 100%; "></div>
cristya8902942010-07-30 00:49:52 +0000[diff] [blame]563 <script type="text/javascript">
564 var _gaq = _gaq || [];
565 _gaq.push(['_setAccount', 'UA-17690367-1']);
566 _gaq.push(['_trackPageview']);
567
568 (function() {
569 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
570 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
571 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
572 })();
573 </script>
cristy3eaa0ef2010-03-06 20:35:26 +0000[diff] [blame]574</body>
575</html>