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">\r
   4 <head>\r
   5   <meta http-equiv="Content-Type" value="application/xhtml+xml" />\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.geschenke-elsen.de/" title="Lampe Berger">Lampe Berger</a><!-- 20106101000040 -->
 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.goyax.de">Börse</a><!-- 201004010240 Gewiese digital-finance.de -->
 146 </div>
 147 <div  class="sponsor">
 148    <a href="http://www.allesdruck.de">Druckerei Online</a><!-- 201012011200 allesdruck.de-->
 149 </div>
 150 </div>
 151 </div>
 152 \r
 153 \r
 154 </div>\r
 155 \r
 156 <div class="main">\r
 157 \r
 158 <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>
 159
 160 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 161 _8c.html" target="source" name="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
 162 <div class="doc-section">
 163
 164 <p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p></ol>
 165
 166 <p>The format of the AcquirePixelCacheNexus method is:</p>
 167
 168 <pre class="code">
 169   NexusInfo **AcquirePixelCacheNexus(const unsigned long number_threads)
 170 </pre>
 171
 172 <p>A description of each parameter follows:</p></ol>
 173
 174 <h5>number_threads</h5>
 175 <ol><p>the number of nexus threads.</p></ol>
 176
 177  </div>
 178 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 179 _8c.html" target="source" name="GetAuthenticIndexQueue">GetAuthenticIndexQueue</a></h2>
 180 <div class="doc-section">
 181
 182 <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>
 183
 184 <p>The format of the GetAuthenticIndexQueue() method is:</p>
 185
 186 <pre class="code">
 187   IndexPacket *GetAuthenticIndexQueue(const Image *image)
 188 </pre>
 189
 190 <p>A description of each parameter follows:</p></ol>
 191
 192 <h5>image</h5>
 193 <ol><p>the image.</p></ol>
 194
 195  </div>
 196 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 197 _8c.html" target="source" name="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
 198 <div class="doc-section">
 199
 200 <p>GetAuthenticPixelQueue() returns the authentic pixels associated with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p></ol>
 201
 202 <p>The format of the GetAuthenticPixelQueue() method is:</p>
 203
 204 <pre class="code">
 205   PixelPacket *GetAuthenticPixelQueue(const Image image)
 206 </pre>
 207
 208 <p>A description of each parameter follows:</p></ol>
 209
 210 <h5>image</h5>
 211 <ol><p>the image.</p></ol>
 212
 213  </div>
 214 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 215 _8c.html" target="source" name="GetAuthenticPixels">GetAuthenticPixels</a></h2>
 216 <div class="doc-section">
 217
 218 <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>
 219
 220 <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>
 221
 222 <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>
 223
 224 <p>The format of the GetAuthenticPixels() method is:</p>
 225
 226 <pre class="code">
 227   PixelPacket *GetAuthenticPixels(Image *image,const long x,const long y,
 228     const unsigned long columns,const unsigned long rows,
 229     ExceptionInfo *exception)
 230 </pre>
 231
 232 <p>A description of each parameter follows:</p></ol>
 233
 234 <h5>image</h5>
 235 <ol><p>the image.</p></ol>
 236
 237 <h5>x,y,columns,rows</h5>
 238 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 239
 240 <h5>exception</h5>
 241 <ol><p>return any errors or warnings in this structure.</p></ol>
 242
 243  </div>
 244 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 245 _8c.html" target="source" name="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
 246 <div class="doc-section">
 247
 248 <p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location.  The image background color is returned if an error occurs.</p></ol>
 249
 250 <p>The format of the GetOneAuthenticPixel() method is:</p>
 251
 252 <pre class="code">
 253   MagickBooleanType GetOneAuthenticPixel(const Image image,const long x,
 254     const long y,PixelPacket *pixel,ExceptionInfo *exception)
 255 </pre>
 256
 257 <p>A description of each parameter follows:</p></ol>
 258
 259 <h5>image</h5>
 260 <ol><p>the image.</p></ol>
 261
 262 <h5>x,y</h5>
 263 <ol><p>These values define the location of the pixel to return.</p></ol>
 264
 265 <h5>pixel</h5>
 266 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 267
 268 <h5>exception</h5>
 269 <ol><p>return any errors or warnings in this structure.</p></ol>
 270
 271  </div>
 272 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 273 _8c.html" target="source" name="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
 274 <div class="doc-section">
 275
 276 <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>
 277
 278 <p>The format of the GetOneVirtualMagickPixel() method is:</p>
 279
 280 <pre class="code">
 281   MagickBooleanType GetOneVirtualMagickPixel(const Image image,
 282     const long x,const long y,MagickPixelPacket *pixel,
 283     ExceptionInfo exception)
 284 </pre>
 285
 286 <p>A description of each parameter follows:</p></ol>
 287
 288 <h5>image</h5>
 289 <ol><p>the image.</p></ol>
 290
 291 <h5>x,y</h5>
 292 <ol><p>these values define the location of the pixel to return.</p></ol>
 293
 294 <h5>pixel</h5>
 295 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 296
 297 <h5>exception</h5>
 298 <ol><p>return any errors or warnings in this structure.</p></ol>
 299
 300  </div>
 301 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 302 _8c.html" target="source" name="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
 303 <div class="doc-section">
 304
 305 <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>
 306
 307 <p>The format of the GetOneVirtualMethodPixel() method is:</p>
 308
 309 <pre class="code">
 310   MagickBooleanType GetOneVirtualMethodPixel(const Image image,
 311     const VirtualPixelMethod virtual_pixel_method,const long x,
 312     const long y,Pixelpacket *pixel,ExceptionInfo exception)
 313 </pre>
 314
 315 <p>A description of each parameter follows:</p></ol>
 316
 317 <h5>image</h5>
 318 <ol><p>the image.</p></ol>
 319
 320 <h5>virtual_pixel_method</h5>
 321 <ol><p>the virtual pixel method.</p></ol>
 322
 323 <h5>x,y</h5>
 324 <ol><p>These values define the location of the pixel to return.</p></ol>
 325
 326 <h5>pixel</h5>
 327 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 328
 329 <h5>exception</h5>
 330 <ol><p>return any errors or warnings in this structure.</p></ol>
 331
 332  </div>
 333 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 334 _8c.html" target="source" name="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
 335 <div class="doc-section">
 336
 337 <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>
 338
 339 <p>The format of the GetOneVirtualPixel() method is:</p>
 340
 341 <pre class="code">
 342   MagickBooleanType GetOneVirtualPixel(const Image image,const long x,
 343     const long y,PixelPacket *pixel,ExceptionInfo exception)
 344 </pre>
 345
 346 <p>A description of each parameter follows:</p></ol>
 347
 348 <h5>image</h5>
 349 <ol><p>the image.</p></ol>
 350
 351 <h5>x,y</h5>
 352 <ol><p>These values define the location of the pixel to return.</p></ol>
 353
 354 <h5>pixel</h5>
 355 <ol><p>return a pixel at the specified (x,y) location.</p></ol>
 356
 357 <h5>exception</h5>
 358 <ol><p>return any errors or warnings in this structure.</p></ol>
 359
 360  </div>
 361 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 362 _8c.html" target="source" name="GetVirtualIndexQueue">GetVirtualIndexQueue</a></h2>
 363 <div class="doc-section">
 364
 365 <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>
 366
 367 <p>The format of the GetVirtualIndexQueue() method is:</p>
 368
 369 <pre class="code">
 370   const IndexPacket *GetVirtualIndexQueue(const Image *image)
 371 </pre>
 372
 373 <p>A description of each parameter follows:</p></ol>
 374
 375 <h5>image</h5>
 376 <ol><p>the image.</p></ol>
 377
 378  </div>
 379 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 380 _8c.html" target="source" name="VirtualPixelModulo">VirtualPixelModulo</a></h2>
 381 <div class="doc-section">
 382
 383 <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>
 384  </div>
 385 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 386 _8c.html" target="source" name="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
 387 <div class="doc-section">
 388
 389 <p>GetVirtualPixelQueue() returns the virtual pixels associated with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p></ol>
 390
 391 <p>The format of the GetVirtualPixelQueue() method is:</p>
 392
 393 <pre class="code">
 394   const PixelPacket *GetVirtualPixelQueue(const Image image)
 395 </pre>
 396
 397 <p>A description of each parameter follows:</p></ol>
 398
 399 <h5>image</h5>
 400 <ol><p>the image.</p></ol>
 401
 402  </div>
 403 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 404 _8c.html" target="source" name="GetVirtualPixels">GetVirtualPixels</a></h2>
 405 <div class="doc-section">
 406
 407 <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>
 408
 409 <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>
 410
 411 <p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p></ol>
 412
 413 <p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe.  In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p></ol>
 414
 415 <p>The format of the GetVirtualPixels() method is:</p>
 416
 417 <pre class="code">
 418   const PixelPacket *GetVirtualPixels(const Image *image,const long x,
 419     const long y,const unsigned long columns,const unsigned long rows,
 420     ExceptionInfo *exception)
 421 </pre>
 422
 423 <p>A description of each parameter follows:</p></ol>
 424
 425 <h5>image</h5>
 426 <ol><p>the image.</p></ol>
 427
 428 <h5>x,y,columns,rows</h5>
 429 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 430
 431 <h5>exception</h5>
 432 <ol><p>return any errors or warnings in this structure.</p></ol>
 433
 434  </div>
 435 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 436 _8c.html" target="source" name="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
 437 <div class="doc-section">
 438
 439 <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>
 440
 441 <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>
 442
 443 <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>
 444
 445 <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>
 446
 447 <p>The format of the QueueAuthenticPixels() method is:</p>
 448
 449 <pre class="code">
 450   PixelPacket *QueueAuthenticPixels(Image *image,const long x,const long y,
 451     const unsigned long columns,const unsigned long rows,
 452     ExceptionInfo *exception)
 453 </pre>
 454
 455 <p>A description of each parameter follows:</p></ol>
 456
 457 <h5>image</h5>
 458 <ol><p>the image.</p></ol>
 459
 460 <h5>x,y,columns,rows</h5>
 461 <ol><p>These values define the perimeter of a region of pixels.</p></ol>
 462
 463 <h5>exception</h5>
 464 <ol><p>return any errors or warnings in this structure.</p></ol>
 465
 466  </div>
 467 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 468 _8c.html" target="source" name="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
 469 <div class="doc-section">
 470
 471 <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>
 472
 473 <p>The format of the SetPixelCacheVirtualMethod() method is:</p>
 474
 475 <pre class="code">
 476   VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
 477     const VirtualPixelMethod virtual_pixel_method)
 478 </pre>
 479
 480 <p>A description of each parameter follows:</p></ol>
 481
 482 <h5>image</h5>
 483 <ol><p>the image.</p></ol>
 484
 485 <h5>virtual_pixel_method</h5>
 486 <ol><p>choose the type of virtual pixel.</p></ol>
 487
 488  </div>
 489 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache
 490 _8c.html" target="source" name="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
 491 <div class="doc-section">
 492
 493 <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>
 494
 495 <p>The format of the SyncAuthenticPixels() method is:</p>
 496
 497 <pre class="code">
 498   MagickBooleanType SyncAuthenticPixels(Image *image,
 499     ExceptionInfo *exception)
 500 </pre>
 501
 502 <p>A description of each parameter follows:</p></ol>
 503
 504 <h5>image</h5>
 505 <ol><p>the image.</p></ol>
 506
 507 <h5>exception</h5>
 508 <ol><p>return any errors or warnings in this structure.</p></ol>
 509
 510  </div>
 511 \r
 512 </div>\r
 513 \r
 514 <div id="linkbar">\r
 515  <!--    <span id="linkbar-west">&nbsp;</span>  -->\r
 516     <span id="linkbar-center">\r
 517       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 518     <a href="http://studio.webbyland.com/ImageMagick/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 519     </span>\r
 520     <span id="linkbar-east">&nbsp;</span>\r
 521   </div>\r
 522   <div class="footer">\r
 523     <span id="footer-west">&copy; 1999-2010 ImageMagick Studio LLC</span>\r
 524     <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 525   </div>\r
 526   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 527 </body>\r
 528 </html>\r