granicus.if.org Git - imagemagick/blob - www/api/cache.html

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