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   <link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf" />\r
   8   <style type="text/css" media="screen,projection"><!--\r
   9     @import url("../../www/magick.css");\r
  10   --></style>\r
  11   <link rel="shortcut icon" href="../../images/wand.ico"  type="images/vnd.microsoft.icon"/>
  12   <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title>
  13   <meta http-equiv="Content-Language" content="en-US"/>
  14   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  15   <meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
  16   <meta name="Generator" content="PHP"/>
  17   <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"/>
  18   <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."/>
  19   <meta name="Rating" content="GENERAL"/>
  20   <meta name="Robots" content="INDEX, FOLLOW"/>
  21   <meta name="Generator" content="ImageMagick Studio LLC"/>
  22   <meta name="Author" content="ImageMagick Studio LLC"/>
  23   <meta name="Revisit-after" content="2 DAYS"/>
  24   <meta name="Resource-type" content="document"/>
  25   <meta name="Copyright" content="Copyright (c) 1999-2010 ImageMagick Studio LLC"/>
  26   <meta name="Distribution" content="Global"/>
  27 </head>\r
  28 \r
  29 <body id="www-imagemagick-org">\r
  30 <div class="titlebar">\r
  31 <a href="../../index.html">\r
  32   <img src="../../images/script.png" alt="[ImageMagick]"\r
  33   style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>\r
  34 <a href="http://www.networkredux.com">\r
  35   <img src="../../images/networkredux.png" alt="[sponsor]"\r
  36   style="margin: 45px auto; border: 0px; float: left;" /></a>\r
  37 <a href="http://www.imagemagick.org/discourse-server/">\r
  38   <img src="../../images/logo.jpg" alt=""\r
  39   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  40 <a href="../../index.html">\r
  41   <img src="../../images/sprite.jpg" alt=""\r
  42   style="width: 114px; height: 118px; border: 0px; float: right;" /></a>\r
  43 </div>\r
  44 \r
  45 <div class="eastbar">\r
  46 \r
  47 <div class="menu">
  48   <a href="../../index.html">About ImageMagick</a>
  49 </div>
  50 <div class="sep"></div>\r
  51 <div class="menu">
  52   <a href="../../www/command-line-tools.html">Command-line Tools</a>
  53 </div>
  54 <div class="sub">
  55     <a href="../../www/command-line-processing.html">Processing</a>
  56 </div>
  57 <div class="sub">
  58     <a href="../../www/command-line-options.html">Options</a>
  59 </div>
  60 <div class="sub">
  61     <a href="http://www.imagemagick.org/Usage/">Usage</a>
  62 </div>
  63 <div class="menu">
  64   <a href="../../www/api.html">Program Interfaces</a>
  65 </div>
  66 <div class="sub">
  67     <a href="../../www/magick-wand.html">MagickWand</a>
  68 </div>
  69 <div class="sub">
  70     <a href="../../www/magick-core.html">MagickCore</a>
  71 </div>
  72 <div class="sub">
  73     <a href="../../www/perl-magick.html">PerlMagick</a>
  74 </div>
  75 <div class="sub">
  76     <a href="../../Magick++/">Magick++</a>
  77 </div>
  78 <div class="menu">
  79   <a href="../../www/architecture.html">Architecture</a>
  80 </div>
  81 <div class="sep"></div>\r
  82 <div  class="menu">
  83    <a href="../../www/install-source.html">Install from Source</a>
  84 </div>
  85 <div class="sub">
  86     <a href="../../www/install-source.html#unix">Unix</a>
  87 </div>
  88 <div class="sub">
  89     <a href="../../www/install-source.html#windows">Windows</a>
  90  </div>
  91 <div class="menu">
  92   <a href="../../www/binary-releases.html">Binary Releases</a>
  93 </div>
  94 <div class="sub">
  95     <a href="../../www/binary-releases.html#unix">Unix</a>
  96 </div>
  97 <div class="sub">
  98     <a href="../../www/binary-releases.html#macosx">Mac OS X</a>
  99 </div>
 100 <div class="sub">
 101     <a href="../../www/binary-releases.html#windows">Windows</a>
 102 </div>
 103 <div class="menu">
 104   <a href="../../www/resources.html">Resources</a>
 105 </div>
 106 <div class="sep"></div>\r
 107 <div class="menu">
 108   <a href="../../www/download.html">Download</a>
 109 </div>
 110 <div class="sep"></div>\r
 111 <div class="menu">
 112   <a href="../http://www.imagemagick.org/script/search.php">Search</a>
 113 </div>
 114 <div class="sep"></div>\r
 115 <div class="menu">
 116   <a href="../../www/sitemap.html">Site Map</a>
 117 </div>
 118 <div  class="sub">
 119     <a href="../../www/links.html">Links</a>
 120 </div>
 121 <div class="sep"></div>\r
 122 <div  class="menu">
 123   <a href="../../www/sponsors.html">Sponsors:</a>
 124
 125 <div class="sponsbox">
 126 <div  class="sponsor">
 127    <a href="http://www.abi-stoff.de/abizeitung/" title="Abibuch">Abizeitung</a><!-- 20101101000200 -->
 128 </div>
 129 <div  class="sponsor">
 130   <a href="http://www.deko.net">Deko.net</a><!-- 201101010600 Peterssen-->
 131 </div>
 132 <div  class="sponsor">
 133   <a href="http://www.tomsgutscheine.de">Tom's Gutscheine</a><!-- 201005010360 invendio.de-->
 134 </div>
 135 <div  class="sponsor">
 136   <a href="http://www.online-kredit-index.de">Kredit</a><!-- 201007010120 Buchhorn -->
 137 </div>
 138 <div  class="sponsor">
 139   <a href="http://www.blumenversender.com">Blumenversand</a><!-- 201005010120 -->
 140 </div>
 141 <div  class="sponsor">
 142   <a href="http://www.print24.de/">Druckerei</a><!-- 201009010720 -->
 143 </div>
 144 <div  class="sponsor">
 145    <a href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 146 </div>
 147 </div>
 148 </div>
 149 \r
 150 \r
 151 </div>\r
 152 \r
 153 <div class="main">\r
 154 \r
 155 <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>
 156
 157 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 158 _8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
 159 <div class="doc-section">
 160
 161 <p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
 162
 163 <p>The format of the AcquirePixelCacheNexus method is:</p>
 164
 165 <pre class="code">
 166   NexusInfo **AcquirePixelCacheNexus(const unsigned long number_threads)
 167 </pre>
 168
 169 <p>A description of each parameter follows:</p></ol>
 170
 171 <h5>number_threads</h5>
 172 <ol><p>the number of nexus threads.</p></ol>
 173
 174  </div>
 175 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 176 _8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
 177 <div class="doc-section">
 178
 179 <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>
 180
 181 <p>The format of the GetAuthenticIndexQueue() method is:</p>
 182
 183 <pre class="code">
 184   IndexPacket *GetAuthenticIndexQueue(const Image *image)
 185 </pre>
 186
 187 <p>A description of each parameter follows:</p></ol>
 188
 189 <h5>image</h5>
 190 <ol><p>the image.</p></ol>
 191
 192  </div>
 193 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 194 _8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
 195 <div class="doc-section">
 196
 197 <p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
 198
 199 <p>The format of the GetAuthenticPixelQueue() method is:</p>
 200
 201 <pre class="code">
 202   PixelPacket *GetAuthenticPixelQueue(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="GetAuthenticPixels">GetAuthenticPixels</a></h2>
 213 <div class="doc-section">
 214
 215 <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>
 216
 217 <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>
 218
 219 <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>
 220
 221 <p>The format of the GetAuthenticPixels() method is:</p>
 222
 223 <pre class="code">
 224   PixelPacket *GetAuthenticPixels(Image *image,const long x,const long y,
 225     const unsigned long columns,const unsigned long rows,
 226     ExceptionInfo *exception)
 227 </pre>
 228
 229 <p>A description of each parameter follows:</p></ol>
 230
 231 <h5>image</h5>
 232 <ol><p>the image.</p></ol>
 233
 234 <h5>x,y,columns,rows</h5>
 235 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 236
 237 <h5>exception</h5>
 238 <ol><p>return any errors or warnings in this structure.</p></ol>
 239
 240  </div>
 241 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 242 _8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
 243 <div class="doc-section">
 244
 245 <p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location.  The image background color is returned if an error occurs.</p></ol>
 246
 247 <p>The format of the GetOneAuthenticPixel() method is:</p>
 248
 249 <pre class="code">
 250   MagickBooleanType GetOneAuthenticPixel(const Image image,const long x,
 251     const long y,PixelPacket *pixel,ExceptionInfo *exception)
 252 </pre>
 253
 254 <p>A description of each parameter follows:</p></ol>
 255
 256 <h5>image</h5>
 257 <ol><p>the image.</p></ol>
 258
 259 <h5>x,y</h5>
 260 <ol><p>These values define the location of the pixel to return.</p></ol>
 261
 262 <h5>pixel</h5>
 263 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 264
 265 <h5>exception</h5>
 266 <ol><p>return any errors or warnings in this structure.</p></ol>
 267
 268  </div>
 269 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 270 _8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
 271 <div class="doc-section">
 272
 273 <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>
 274
 275 <p>The format of the GetOneVirtualMagickPixel() method is:</p>
 276
 277 <pre class="code">
 278   MagickBooleanType GetOneVirtualMagickPixel(const Image image,
 279     const long x,const long y,MagickPixelPacket *pixel,
 280     ExceptionInfo exception)
 281 </pre>
 282
 283 <p>A description of each parameter follows:</p></ol>
 284
 285 <h5>image</h5>
 286 <ol><p>the image.</p></ol>
 287
 288 <h5>x,y</h5>
 289 <ol><p>these values define the location of the pixel to return.</p></ol>
 290
 291 <h5>pixel</h5>
 292 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 293
 294 <h5>exception</h5>
 295 <ol><p>return any errors or warnings in this structure.</p></ol>
 296
 297  </div>
 298 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 299 _8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
 300 <div class="doc-section">
 301
 302 <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>
 303
 304 <p>The format of the GetOneVirtualMethodPixel() method is:</p>
 305
 306 <pre class="code">
 307   MagickBooleanType GetOneVirtualMethodPixel(const Image image,
 308     const VirtualPixelMethod virtual_pixel_method,const long x,
 309     const long y,Pixelpacket *pixel,ExceptionInfo exception)
 310 </pre>
 311
 312 <p>A description of each parameter follows:</p></ol>
 313
 314 <h5>image</h5>
 315 <ol><p>the image.</p></ol>
 316
 317 <h5>virtual_pixel_method</h5>
 318 <ol><p>the virtual pixel method.</p></ol>
 319
 320 <h5>x,y</h5>
 321 <ol><p>These values define the location of the pixel to return.</p></ol>
 322
 323 <h5>pixel</h5>
 324 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 325
 326 <h5>exception</h5>
 327 <ol><p>return any errors or warnings in this structure.</p></ol>
 328
 329  </div>
 330 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 331 _8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
 332 <div class="doc-section">
 333
 334 <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>
 335
 336 <p>The format of the GetOneVirtualPixel() method is:</p>
 337
 338 <pre class="code">
 339   MagickBooleanType GetOneVirtualPixel(const Image image,const long x,
 340     const long y,PixelPacket *pixel,ExceptionInfo exception)
 341 </pre>
 342
 343 <p>A description of each parameter follows:</p></ol>
 344
 345 <h5>image</h5>
 346 <ol><p>the image.</p></ol>
 347
 348 <h5>x,y</h5>
 349 <ol><p>These values define the location of the pixel to return.</p></ol>
 350
 351 <h5>pixel</h5>
 352 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 353
 354 <h5>exception</h5>
 355 <ol><p>return any errors or warnings in this structure.</p></ol>
 356
 357  </div>
 358 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 359 _8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
 360 <div class="doc-section">
 361
 362 <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>
 363
 364 <p>The format of the GetVirtualIndexQueue() method is:</p>
 365
 366 <pre class="code">
 367   const IndexPacket *GetVirtualIndexQueue(const Image *image)
 368 </pre>
 369
 370 <p>A description of each parameter follows:</p></ol>
 371
 372 <h5>image</h5>
 373 <ol><p>the image.</p></ol>
 374
 375  </div>
 376 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 377 _8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
 378 <div class="doc-section">
 379
 380 <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>
 381  </div>
 382 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 383 _8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
 384 <div class="doc-section">
 385
 386 <p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
 387
 388 <p>The format of the GetVirtualPixelQueue() method is:</p>
 389
 390 <pre class="code">
 391   const PixelPacket *GetVirtualPixelQueue(const Image image)
 392 </pre>
 393
 394 <p>A description of each parameter follows:</p></ol>
 395
 396 <h5>image</h5>
 397 <ol><p>the image.</p></ol>
 398
 399  </div>
 400 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 401 _8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
 402 <div class="doc-section">
 403
 404 <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>
 405
 406 <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>
 407
 408 <p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
 409
 410 <p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe.  In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
 411
 412 <p>The format of the GetVirtualPixels() method is:</p>
 413
 414 <pre class="code">
 415   const PixelPacket *GetVirtualPixels(const Image *image,const long x,
 416     const long y,const unsigned long columns,const unsigned long rows,
 417     ExceptionInfo *exception)
 418 </pre>
 419
 420 <p>A description of each parameter follows:</p></ol>
 421
 422 <h5>image</h5>
 423 <ol><p>the image.</p></ol>
 424
 425 <h5>x,y,columns,rows</h5>
 426 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 427
 428 <h5>exception</h5>
 429 <ol><p>return any errors or warnings in this structure.</p></ol>
 430
 431  </div>
 432 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 433 _8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
 434 <div class="doc-section">
 435
 436 <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>
 437
 438 <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>
 439
 440 <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>
 441
 442 <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>
 443
 444 <p>The format of the QueueAuthenticPixels() method is:</p>
 445
 446 <pre class="code">
 447   PixelPacket *QueueAuthenticPixels(Image *image,const long x,const long y,
 448     const unsigned long columns,const unsigned long rows,
 449     ExceptionInfo *exception)
 450 </pre>
 451
 452 <p>A description of each parameter follows:</p></ol>
 453
 454 <h5>image</h5>
 455 <ol><p>the image.</p></ol>
 456
 457 <h5>x,y,columns,rows</h5>
 458 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 459
 460 <h5>exception</h5>
 461 <ol><p>return any errors or warnings in this structure.</p></ol>
 462
 463  </div>
 464 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 465 _8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
 466 <div class="doc-section">
 467
 468 <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>
 469
 470 <p>The format of the SetPixelCacheVirtualMethod() method is:</p>
 471
 472 <pre class="code">
 473   VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
 474     const VirtualPixelMethod virtual_pixel_method)
 475 </pre>
 476
 477 <p>A description of each parameter follows:</p></ol>
 478
 479 <h5>image</h5>
 480 <ol><p>the image.</p></ol>
 481
 482 <h5>virtual_pixel_method</h5>
 483 <ol><p>choose the type of virtual pixel.</p></ol>
 484
 485  </div>
 486 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 487 _8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
 488 <div class="doc-section">
 489
 490 <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>
 491
 492 <p>The format of the SyncAuthenticPixels() method is:</p>
 493
 494 <pre class="code">
 495   MagickBooleanType SyncAuthenticPixels(Image *image,
 496     ExceptionInfo *exception)
 497 </pre>
 498
 499 <p>A description of each parameter follows:</p></ol>
 500
 501 <h5>image</h5>
 502 <ol><p>the image.</p></ol>
 503
 504 <h5>exception</h5>
 505 <ol><p>return any errors or warnings in this structure.</p></ol>
 506
 507  </div>
 508 \r
 509 </div>\r
 510 \r
 511 <div id="linkbar">\r
 512  <!--    <span id="linkbar-west">&nbsp;</span>  -->\r
 513     <span id="linkbar-center">\r
 514       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 515     <a href="http://studio.webbyland.com/ImageMagick/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 516     </span>\r
 517     <span id="linkbar-east">&nbsp;</span>\r
 518   </div>\r
 519   <div class="footer">\r
 520     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 521     <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 522   </div>\r
 523   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 524 </body>\r
 525 </html>\r