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

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\r
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">\r
   4 <head>\r
   5   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>\r
   6   <meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\r
   7   <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title/>
   8   <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"/>
  11   <meta name="Application-name" content="ImageMagick"/>
  12   <meta name="Description" content="ImageMagick® is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (about 100) including GIF, JPEG, JPEG-2000, PNG, PDF, PhotoCD, TIFF, and DPX. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.  ImageMagick is free software delivered as a ready-to-run binary distribution or as source code that you can freely use, copy, modify, and distribute. Its license is compatible with the GPL. It runs on all major operating systems.  The functionality of ImageMagick is typically utilized from the command line or you can use the features from programs written in your favorite programming language. Choose from these interfaces: MagickCore (C), MagickWand (C), ChMagick (Ch), Magick++ (C++), JMagick (Java), L-Magick (Lisp), PascalMagick (Pascal), PerlMagick (Perl), MagickWand for PHP (PHP), PythonMagick (Python), RMagick (Ruby), or TclMagick (Tcl/TK). With a language interface, use ImageMagick to modify or create images automagically and dynamically."/>
  13   <meta name="Application-url" content="http://www.imagemagick.org"/>
  14   <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"/>
  16   <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"/>
  22   <meta name="Copyright" content="Copyright (c) 1999-2010 ImageMagick Studio LLC"/>
  23   <meta name="Distribution" content="Global"/>
  24   <link rel="icon" href="../../images/wand.png"  sizes="32x32"/>
  25   <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"/>\r
  27   <style type="text/css" media="all">\r
  28     @import url("../../www/magick.css");\r
  29   </style>\r
  30 </head>\r
  31 \r
  32 <body id="www-imagemagick-org">\r
  33 <div class="titlebar">\r
  34 <a href="../../index.html">\r
  35   <img src="../../images/script.png" alt="[ImageMagick]"\r
  36   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  37 <a href="http://www.networkredux.com">\r
  38   <img src="../../images/networkredux.png" alt="[sponsor]"\r
  39   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  40 <a href="http://www.imagemagick.org/discourse-server/">\r
  41   <img src="../../images/logo.jpg" alt=""\r
  42   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  43 <a href="../../index.html">\r
  44   <img src="../../images/sprite.jpg" alt=""\r
  45   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  46 </div>\r
  47 \r
  48 <div class="westbar">\r
  49 \r
  50 <div class="menu">
  51   <a title="About ImageMagick" href="../../index.html">About ImageMagick</a>
  52 </div>
  53 <div class="sep"></div>\r
  54 <div class="menu">
  55   <a title="Binary Releases" href="../../www/binary-releases.html">Binary Releases</a>
  56 </div>
  57 <div class="sub">
  58     <a title="Binary Release: Unix" href="../../www/binary-releases.html#unix">Unix</a>
  59 </div>
  60 <div class="sub">
  61     <a title="Binary Release: MacOS X" href="../../www/binary-releases.html#macosx">Mac OS X</a>
  62 </div>
  63 <div class="sub">
  64     <a title="Binary Release: Windows" href="../../www/binary-releases.html#windows">Windows</a>
  65 </div>
  66 <div class="sep"></div>\r
  67 <div class="menu">
  68   <a title="Command-line Tools" href="../../www/command-line-tools.html">Command-line Tools</a>
  69 </div>
  70 <div class="sub">
  71     <a title="Command-line Tools: Processing" href="../../www/command-line-processing.html">Processing</a>
  72 </div>
  73 <div class="sub">
  74     <a title="Command-line Tools: Options" href="../../www/command-line-options.html">Options</a>
  75 </div>
  76 <div class="sub">
  77     <a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
  78 </div>
  79 <div class="menu">
  80   <a title="Program Interfaces" href="../../www/api.html">Program Interfaces</a>
  81 </div>
  82 <div class="sub">
  83     <a title="Program Interface: MagickWand" href="../../www/magick-wand.html">MagickWand</a>
  84 </div>
  85 <div class="sub">
  86     <a title="Program Interface: MagickCore" href="../../www/magick-core.html">MagickCore</a>
  87 </div>
  88 <div class="sub">
  89     <a title="Program Interface: PerlMagick" href="../../www/perl-magick.html">PerlMagick</a>
  90 </div>
  91 <div class="sub">
  92     <a title="Program Interface: Magick++" href="../../Magick++/">Magick++</a>
  93 </div>
  94 <div class="sep"></div>\r
  95 <div  class="menu">
  96    <a title="Install from Source" href="../../www/install-source.html">Install from Source</a>
  97 </div>
  98 <div class="sub">
  99     <a title="Install from Source: Unix" href="../../www/install-source.html#unix">Unix</a>
 100 </div>
 101 <div class="sub">
 102     <a title="Install from Source: Windows" href="../../www/install-source.html#windows">Windows</a>
 103  </div>
 104 <div class="menu">
 105   <a title="Resources" href="../../www/resources.html">Resources</a>
 106 </div>
 107 <div class="menu">
 108   <a title="Architecture" href="../../www/architecture.html">Architecture</a>
 109 </div>
 110 <div class="menu">
 111   <a title="Download" href="../../www/download.html">Download</a>
 112 </div>
 113 <div class="sep"></div>\r
 114 <div class="menu">
 115   <a title="Search" href="../http://www.imagemagick.org/script/search.php">Search</a>
 116 </div>
 117 <div class="sep"></div>\r
 118 <div class="menu">
 119   <a title="Site Map"href="../../www/sitemap.html">Site Map</a>
 120 </div>
 121 <div  class="sub">
 122     <a title="Site Map: Links"href="../../www/links.html">Links</a>
 123 </div>
 124 <div class="sep"></div>\r
 125 <div  class="menu">
 126   <a title="Sponsors" href="../../www/sponsors.html">Sponsors:</a>
 127
 128 <div class="sponsbox">
 129 <div  class="sponsor">
 130    <a title="Sponsor: Online-Magazin" href="http://www.unkostenbeitrag.de/">Online-Magazin</a><!-- 20101101000200 -->
 131 </div>
 132 <div  class="sponsor">
 133   <a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 134 </div>
 135 <div  class="sponsor">
 136   <a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
 137 </div>
 138 <div  class="sponsor">
 139   <a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 140 </div>
 141 <div  class="sponsor">
 142   <a title="Sponsor: Webdesign Agentur" href="http://www.ventzke-partner.de">Webdesign Agentur</a><!-- 201101010480 invendio.de-->
 143 </div>
 144 <div  class="sponsor">
 145   <a title="Sponsor: LVM Versicherung" href="http://www.neu-reich.de">LVM Versicherung</a><!-- 201101010480 -->
 146 </div>
 147 <div  class="sponsor">
 148   <a title="Sponsor: Diamonds are a Girls Best Friend" href="http://www.schmuck.org">Diamonds are a Girls Best Friend</a><!-- 201101010600 Peterssen-->
 149 </div>
 150 <div  class="sponsor">
 151    <a title="Sponsor: Druckerei Online" href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 152 </div>
 153 </div>
 154 </div>
 155 </div>\r
 156 \r
 157 <div class="eastbar">\r
 158   <script type="text/javascript">\r
 159   <!--\r
 160     google_ad_client = "pub-3129977114552745";\r
 161     google_ad_slot = "0574824969";\r
 162     google_ad_width = 160;\r
 163     google_ad_height = 600;\r
 164   //-->\r
 165   </script>\r
 166   <script type="text/javascript"\r
 167     src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
 168   </script>\r
 169 </div>\r
 170 \r
 171 <div class="main">\r
 172 \r
 173 <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>
 174
 175 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 176 _8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
 177 <div class="doc-section">
 178
 179 <p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
 180
 181 <p>The format of the AcquirePixelCacheNexus method is:</p>
 182
 183 <pre class="code">
 184   NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
 185 </pre>
 186
 187 <p>A description of each parameter follows:</p></ol>
 188
 189 <h5>number_threads</h5>
 190 <ol><p>the number of nexus threads.</p></ol>
 191
 192  </div>
 193 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 194 _8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
 195 <div class="doc-section">
 196
 197 <p>GetAuthenticIndexQueue() returns the authentic black channel or the colormap indexes associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().  NULL is returned if the black channel or colormap indexes are not available.</p></ol>
 198
 199 <p>The format of the GetAuthenticIndexQueue() method is:</p>
 200
 201 <pre class="code">
 202   IndexPacket *GetAuthenticIndexQueue(const Image *image)
 203 </pre>
 204
 205 <p>A description of each parameter follows:</p></ol>
 206
 207 <h5>image</h5>
 208 <ol><p>the image.</p></ol>
 209
 210  </div>
 211 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 212 _8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
 213 <div class="doc-section">
 214
 215 <p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
 216
 217 <p>The format of the GetAuthenticPixelQueue() method is:</p>
 218
 219 <pre class="code">
 220   PixelPacket *GetAuthenticPixelQueue(const Image image)
 221 </pre>
 222
 223 <p>A description of each parameter follows:</p></ol>
 224
 225 <h5>image</h5>
 226 <ol><p>the image.</p></ol>
 227
 228  </div>
 229 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 230 _8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
 231 <div class="doc-section">
 232
 233 <p>GetAuthenticPixels() obtains a pixel region for read/write access. If the region is successfully accessed, a pointer to a PixelPacket array representing the region is returned, otherwise NULL is returned.</p></ol>
 234
 235 <p>The returned pointer may point to a temporary working copy of the pixels or it may point to the original pixels in memory. Performance is maximized if the selected region is part of one row, or one or more full rows, since then there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file. The returned pointer must *never* be deallocated by the user.</p></ol>
 236
 237 <p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket. If the image type is CMYK or if the storage class is PseduoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to obtain the black color component or colormap indexes (of type IndexPacket) corresponding to the region.  Once the PixelPacket (and/or IndexPacket) array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p></ol>
 238
 239 <p>The format of the GetAuthenticPixels() method is:</p>
 240
 241 <pre class="code">
 242   PixelPacket *GetAuthenticPixels(Image *image,const ssize_t x,
 243     const ssize_t y,const size_t columns,const size_t rows,
 244     ExceptionInfo *exception)
 245 </pre>
 246
 247 <p>A description of each parameter follows:</p></ol>
 248
 249 <h5>image</h5>
 250 <ol><p>the image.</p></ol>
 251
 252 <h5>x,y,columns,rows</h5>
 253 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 254
 255 <h5>exception</h5>
 256 <ol><p>return any errors or warnings in this structure.</p></ol>
 257
 258  </div>
 259 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 260 _8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
 261 <div class="doc-section">
 262
 263 <p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location.  The image background color is returned if an error occurs.</p></ol>
 264
 265 <p>The format of the GetOneAuthenticPixel() method is:</p>
 266
 267 <pre class="code">
 268   MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
 269     const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
 270 </pre>
 271
 272 <p>A description of each parameter follows:</p></ol>
 273
 274 <h5>image</h5>
 275 <ol><p>the image.</p></ol>
 276
 277 <h5>x,y</h5>
 278 <ol><p>These values define the location of the pixel to return.</p></ol>
 279
 280 <h5>pixel</h5>
 281 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 282
 283 <h5>exception</h5>
 284 <ol><p>return any errors or warnings in this structure.</p></ol>
 285
 286  </div>
 287 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 288 _8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
 289 <div class="doc-section">
 290
 291 <p>GetOneVirtualMagickPixel() returns a single pixel at the specified (x,y) location.  The image background color is returned if an error occurs.  If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
 292
 293 <p>The format of the GetOneVirtualMagickPixel() method is:</p>
 294
 295 <pre class="code">
 296   MagickBooleanType GetOneVirtualMagickPixel(const Image image,
 297     const ssize_t x,const ssize_t y,MagickPixelPacket *pixel,
 298     ExceptionInfo exception)
 299 </pre>
 300
 301 <p>A description of each parameter follows:</p></ol>
 302
 303 <h5>image</h5>
 304 <ol><p>the image.</p></ol>
 305
 306 <h5>x,y</h5>
 307 <ol><p>these values define the location of the pixel to return.</p></ol>
 308
 309 <h5>pixel</h5>
 310 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 311
 312 <h5>exception</h5>
 313 <ol><p>return any errors or warnings in this structure.</p></ol>
 314
 315  </div>
 316 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 317 _8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
 318 <div class="doc-section">
 319
 320 <p>GetOneVirtualMethodPixel() returns a single pixel at the specified (x,y) location as defined by specified pixel method.  The image background color is returned if an error occurs.  If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
 321
 322 <p>The format of the GetOneVirtualMethodPixel() method is:</p>
 323
 324 <pre class="code">
 325   MagickBooleanType GetOneVirtualMethodPixel(const Image image,
 326     const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
 327     const ssize_t y,Pixelpacket *pixel,ExceptionInfo exception)
 328 </pre>
 329
 330 <p>A description of each parameter follows:</p></ol>
 331
 332 <h5>image</h5>
 333 <ol><p>the image.</p></ol>
 334
 335 <h5>virtual_pixel_method</h5>
 336 <ol><p>the virtual pixel method.</p></ol>
 337
 338 <h5>x,y</h5>
 339 <ol><p>These values define the location of the pixel to return.</p></ol>
 340
 341 <h5>pixel</h5>
 342 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 343
 344 <h5>exception</h5>
 345 <ol><p>return any errors or warnings in this structure.</p></ol>
 346
 347  </div>
 348 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 349 _8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
 350 <div class="doc-section">
 351
 352 <p>GetOneVirtualPixel() returns a single virtual pixel at the specified (x,y) location.  The image background color is returned if an error occurs. If you plan to modify the pixel, use GetOneAuthenticPixel() instead.</p></ol>
 353
 354 <p>The format of the GetOneVirtualPixel() method is:</p>
 355
 356 <pre class="code">
 357   MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
 358     const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
 359 </pre>
 360
 361 <p>A description of each parameter follows:</p></ol>
 362
 363 <h5>image</h5>
 364 <ol><p>the image.</p></ol>
 365
 366 <h5>x,y</h5>
 367 <ol><p>These values define the location of the pixel to return.</p></ol>
 368
 369 <h5>pixel</h5>
 370 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 371
 372 <h5>exception</h5>
 373 <ol><p>return any errors or warnings in this structure.</p></ol>
 374
 375  </div>
 376 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 377 _8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
 378 <div class="doc-section">
 379
 380 <p>GetVirtualIndexQueue() returns the virtual black channel or the colormap indexes associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().  NULL is returned if the black channel or colormap indexes are not available.</p></ol>
 381
 382 <p>The format of the GetVirtualIndexQueue() method is:</p>
 383
 384 <pre class="code">
 385   const IndexPacket *GetVirtualIndexQueue(const Image *image)
 386 </pre>
 387
 388 <p>A description of each parameter follows:</p></ol>
 389
 390 <h5>image</h5>
 391 <ol><p>the image.</p></ol>
 392
 393  </div>
 394 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 395 _8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
 396 <div class="doc-section">
 397
 398 <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>
 399  </div>
 400 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 401 _8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
 402 <div class="doc-section">
 403
 404 <p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
 405
 406 <p>The format of the GetVirtualPixelQueue() method is:</p>
 407
 408 <pre class="code">
 409   const PixelPacket *GetVirtualPixelQueue(const Image image)
 410 </pre>
 411
 412 <p>A description of each parameter follows:</p></ol>
 413
 414 <h5>image</h5>
 415 <ol><p>the image.</p></ol>
 416
 417  </div>
 418 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 419 _8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
 420 <div class="doc-section">
 421
 422 <p>GetVirtualPixels() returns an immutable pixel region. If the region is successfully accessed, a pointer to it is returned, otherwise NULL is returned.  The returned pointer may point to a temporary working copy of the pixels or it may point to the original pixels in memory. Performance is maximized if the selected region is part of one row, or one or more full rows, since there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file.  The returned pointer must *never* be deallocated by the user.</p></ol>
 423
 424 <p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket.  If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to access the black color component or to obtain the colormap indexes (of type IndexPacket) corresponding to the region.</p></ol>
 425
 426 <p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
 427
 428 <p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe.  In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
 429
 430 <p>The format of the GetVirtualPixels() method is:</p>
 431
 432 <pre class="code">
 433   const PixelPacket *GetVirtualPixels(const Image *image,const ssize_t x,
 434     const ssize_t y,const size_t columns,const size_t rows,
 435     ExceptionInfo *exception)
 436 </pre>
 437
 438 <p>A description of each parameter follows:</p></ol>
 439
 440 <h5>image</h5>
 441 <ol><p>the image.</p></ol>
 442
 443 <h5>x,y,columns,rows</h5>
 444 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 445
 446 <h5>exception</h5>
 447 <ol><p>return any errors or warnings in this structure.</p></ol>
 448
 449  </div>
 450 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 451 _8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
 452 <div class="doc-section">
 453
 454 <p>QueueAuthenticPixels() queues a mutable pixel region.  If the region is successfully intialized a pointer to a PixelPacket array representing the region is returned, otherwise NULL is returned.  The returned pointer may point to a temporary working buffer for the pixels or it may point to the final location of the pixels in memory.</p></ol>
 455
 456 <p>Write-only access means that any existing pixel values corresponding to the region are ignored.  This is useful if the initial image is being created from scratch, or if the existing pixel values are to be completely replaced without need to refer to their pre-existing values. The application is free to read and write the pixel buffer returned by QueueAuthenticPixels() any way it pleases. QueueAuthenticPixels() does not initialize the pixel array values. Initializing pixel array values is the application's responsibility.</p></ol>
 457
 458 <p>Performance is maximized if the selected region is part of one row, or one or more full rows, since then there is opportunity to access the pixels in-place (without a copy) if the image is in memory, or in a memory-mapped file. The returned pointer must *never* be deallocated by the user.</p></ol>
 459
 460 <p>Pixels accessed via the returned pointer represent a simple array of type PixelPacket. If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticIndexQueue() after invoking GetAuthenticPixels() to obtain the black color component or the colormap indexes (of type IndexPacket) corresponding to the region.  Once the PixelPacket (and/or IndexPacket) array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p></ol>
 461
 462 <p>The format of the QueueAuthenticPixels() method is:</p>
 463
 464 <pre class="code">
 465   PixelPacket *QueueAuthenticPixels(Image *image,const ssize_t x,
 466     const ssize_t y,const size_t columns,const size_t rows,
 467     ExceptionInfo *exception)
 468 </pre>
 469
 470 <p>A description of each parameter follows:</p></ol>
 471
 472 <h5>image</h5>
 473 <ol><p>the image.</p></ol>
 474
 475 <h5>x,y,columns,rows</h5>
 476 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 477
 478 <h5>exception</h5>
 479 <ol><p>return any errors or warnings in this structure.</p></ol>
 480
 481  </div>
 482 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 483 _8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
 484 <div class="doc-section">
 485
 486 <p>SetPixelCacheVirtualMethod() sets the "virtual pixels" method for the pixel cache and returns the previous setting.  A virtual pixel is any pixel access that is outside the boundaries of the image cache.</p></ol>
 487
 488 <p>The format of the SetPixelCacheVirtualMethod() method is:</p>
 489
 490 <pre class="code">
 491   VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
 492     const VirtualPixelMethod virtual_pixel_method)
 493 </pre>
 494
 495 <p>A description of each parameter follows:</p></ol>
 496
 497 <h5>image</h5>
 498 <ol><p>the image.</p></ol>
 499
 500 <h5>virtual_pixel_method</h5>
 501 <ol><p>choose the type of virtual pixel.</p></ol>
 502
 503  </div>
 504 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 505 _8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
 506 <div class="doc-section">
 507
 508 <p>SyncAuthenticPixels() saves the image pixels to the in-memory or disk cache. The method returns MagickTrue if the pixel region is flushed, otherwise MagickFalse.</p></ol>
 509
 510 <p>The format of the SyncAuthenticPixels() method is:</p>
 511
 512 <pre class="code">
 513   MagickBooleanType SyncAuthenticPixels(Image *image,
 514     ExceptionInfo *exception)
 515 </pre>
 516
 517 <p>A description of each parameter follows:</p></ol>
 518
 519 <h5>image</h5>
 520 <ol><p>the image.</p></ol>
 521
 522 <h5>exception</h5>
 523 <ol><p>return any errors or warnings in this structure.</p></ol>
 524
 525  </div>
 526 \r
 527 </div>\r
 528 \r
 529 <div id="linkbar">\r
 530     <span id="linkbar-west">&nbsp;</span>\r
 531     <span id="linkbar-center">\r
 532       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 533       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 534     </span>\r
 535     <span id="linkbar-east">&nbsp;</span>\r
 536   </div>\r
 537   <div class="footer">\r
 538     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 539     <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 540   </div>\r
 541   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 542   <script type="text/javascript">\r
 543     var _gaq = _gaq || [];\r
 544     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 545     _gaq.push(['_trackPageview']);\r
 546 \r
 547     (function() {\r
 548       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 549       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 550       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 551     })();\r
 552   </script>\r
 553 </body>\r
 554 </html>\r