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="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>\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="../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.4/jquery.min.js"></script>\r
  39   <script type="text/javascript" src="../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" 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: Web Hosting" href="http://www.micfo.com">Web Hosting</a><!-- 209901010090s golestan -->
 165 </div>
 166 <div  class="sponsor">
 167   <a rel="follow" title="Sponsor: Search engine optimisation" href="http://www.seomoves.com.au">Search engine optimisation</a><!-- 201110010090s jen@seo lowprofilelinks -->
 168 </div>
 169 <div  class="sponsor">
 170   <a rel="follow" title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
 171 </div>
 172 <div  class="sponsor">
 173   <a rel="follow" title="Sponsor: Web Hosting Deals" href="http://www.webhostingdeals.org">Web Hosting Deals</a><!-- 201111010270 chee.hoa darin -->
 174 </div>
 175 <div  class="sponsor">
 176   <a rel="follow" title="Sponsor: Web Hosting Reviews" href="http://www.webhostingsecretrevealed.com">Web Hosting Secret Revealed</a><!-- 201204010540 iamchee jerry -->
 177 </div>
 178 <div  class="sponsor">
 179   <a rel="follow" title="Sponsor: Web Hosting Break" href="http://www.webhostingbreak.com">Web Hosting Break</a><!-- 201109010090 ian@ian-m... -->
 180 </div>
 181 <div  class="sponsor">
 182   <a rel="follow" title="Sponsor: Druckerei" href="http://www.allesdruck.de">Druckerei</a><!-- 201303011500 r.leo -->
 183 </div>
 184 <div  class="sponsor">
 185   <a rel="follow" title="Sponsor: Website Hosting" href="http://www.hostreviewgeeks.com">Website Hosting</a><!-- 201110010090 alexanian media -->
 186 </div>
 187 <div  class="sponsor">
 188   <a rel="follow" title="Sponsor: Hotel München" href="http://www.messehotel-erb-muenchen.de">Hotel München</a><!-- 201111010450 cerb -->
 189 </div>
 190 <div  class="sponsor">
 191   <a rel="follow" title="Sponsor: Best Web Hosting" href="http://webhostinggeeks.com">Best Web Hosting</a><!-- 201110010720 -->
 192 </div>
 193 <div  class="sponsor">
 194   <a rel="follow" title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
 195 </div>
 196 <div  class="sponsor">
 197   <a rel="follow" title="Sponsor: Web Hosting Ratings" href="http://webhostingrating.com">Web Hosting Ratings</a><!-- 201110010720 -->
 198 </div>
 199 <div  class="sponsor">
 200    <a rel="follow" title="Sponsor: Notebook Reparatur" href="http://www.atlasmultimedia.de">Notebook Reparatur</a><!-- 2011100100025 atlas.multimedia-->
 201 </div>
 202 </div>
 203 </div>
 204 </div>\r
 205 \r
 206 <div class="eastbar">\r
 207 <div style="margin: 9pt 9pt 9pt 9pt;">\r
 208   <div class="g-plusone" data-size="standard" data-count="false"></div>\r
 209 </div>\r
 210 </div>\r
 211 \r
 212 <div class="main">\r
 213 \r
 214 <h1>Module cache Methods</h1>
 215 <p class="navigation-index">[<a href="#AcquirePixelCacheNexus">AcquirePixelCacheNexus</a> &bull; <a href="#GetAuthenticMetacontent">GetAuthenticMetacontent</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="#GetVirtualMetacontent">GetVirtualMetacontent</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>
 216
 217 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2>
 218 <div class="doc-section">
 219
 220 <p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p>
 221
 222 <p>The format of the AcquirePixelCacheNexus method is:</p>
 223
 224 <pre class="code">
 225   NexusInfo **AcquirePixelCacheNexus(const size_t number_threads)
 226 </pre>
 227
 228 <p>A description of each parameter follows:</p>
 229
 230 <h5>number_threads</h5>
 231 <p>the number of nexus threads.</p>
 232
 233  </div>
 234 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticMetacontent">GetAuthenticMetacontent</a></h2>
 235 <div class="doc-section">
 236
 237 <p>GetAuthenticMetacontent() returns the authentic metacontent corresponding with the last call to QueueAuthenticPixels() or GetVirtualPixels().  NULL is returned if the associated pixels are not available.</p>
 238
 239 <p>The format of the GetAuthenticMetacontent() method is:</p>
 240
 241 <pre class="code">
 242   void *GetAuthenticMetacontent(const Image *image)
 243 </pre>
 244
 245 <p>A description of each parameter follows:</p>
 246
 247 <h5>image</h5>
 248 <p>the image.</p>
 249
 250  </div>
 251 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2>
 252 <div class="doc-section">
 253
 254 <p>GetAuthenticPixelQueue() returns the authentic pixels associated corresponding with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p>
 255
 256 <p>The format of the GetAuthenticPixelQueue() method is:</p>
 257
 258 <pre class="code">
 259   Quantum *GetAuthenticPixelQueue(const Image image)
 260 </pre>
 261
 262 <p>A description of each parameter follows:</p>
 263
 264 <h5>image</h5>
 265 <p>the image.</p>
 266
 267  </div>
 268 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2>
 269 <div class="doc-section">
 270
 271 <p>GetAuthenticPixels() obtains a pixel region for read/write access. If the region is successfully accessed, a pointer to a Quantum array representing the region is returned, otherwise NULL is returned.</p>
 272
 273 <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>
 274
 275 <p>Pixels accessed via the returned pointer represent a simple array of type Quantum.  If the image has corresponding metacontent,call GetAuthenticMetacontent() after invoking GetAuthenticPixels() to obtain the meta-content corresponding to the region.  Once the Quantum array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p>
 276
 277 <p>The format of the GetAuthenticPixels() method is:</p>
 278
 279 <pre class="code">
 280   Quantum *GetAuthenticPixels(Image *image,const ssize_t x,
 281     const ssize_t y,const size_t columns,const size_t rows,
 282     ExceptionInfo *exception)
 283 </pre>
 284
 285 <p>A description of each parameter follows:</p>
 286
 287 <h5>image</h5>
 288 <p>the image.</p>
 289
 290 <h5>x,y,columns,rows</h5>
 291 <p>These values define the perimeter of a region of pixels.</p>
 292
 293 <h5>exception</h5>
 294 <p>return any errors or warnings in this structure.</p>
 295
 296  </div>
 297 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2>
 298 <div class="doc-section">
 299
 300 <p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location.  The image background color is returned if an error occurs.</p>
 301
 302 <p>The format of the GetOneAuthenticPixel() method is:</p>
 303
 304 <pre class="code">
 305   MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x,
 306     const ssize_t y,PixelPacket *pixel,ExceptionInfo *exception)
 307 </pre>
 308
 309 <p>A description of each parameter follows:</p>
 310
 311 <h5>image</h5>
 312 <p>the image.</p>
 313
 314 <h5>x,y</h5>
 315 <p>These values define the location of the pixel to return.</p>
 316
 317 <h5>pixel</h5>
 318 <p>return a pixel at the specified (x,y) location.</p>
 319
 320 <h5>exception</h5>
 321 <p>return any errors or warnings in this structure.</p>
 322
 323  </div>
 324 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualMagickPixel">GetOneVirtualMagickPixel</a></h2>
 325 <div class="doc-section">
 326
 327 <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>
 328
 329 <p>The format of the GetOneVirtualMagickPixel() method is:</p>
 330
 331 <pre class="code">
 332   MagickBooleanType GetOneVirtualMagickPixel(const Image image,
 333     const ssize_t x,const ssize_t y,PixelInfo *pixel,
 334     ExceptionInfo exception)
 335 </pre>
 336
 337 <p>A description of each parameter follows:</p>
 338
 339 <h5>image</h5>
 340 <p>the image.</p>
 341
 342 <h5>x,y</h5>
 343 <p>these values define the location of the pixel to return.</p>
 344
 345 <h5>pixel</h5>
 346 <p>return a pixel at the specified (x,y) location.</p>
 347
 348 <h5>exception</h5>
 349 <p>return any errors or warnings in this structure.</p>
 350
 351  </div>
 352 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualMethodPixel">GetOneVirtualMethodPixel</a></h2>
 353 <div class="doc-section">
 354
 355 <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>
 356
 357 <p>The format of the GetOneVirtualMethodPixel() method is:</p>
 358
 359 <pre class="code">
 360   MagickBooleanType GetOneVirtualMethodPixel(const Image image,
 361     const VirtualPixelMethod virtual_pixel_method,const ssize_t x,
 362     const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
 363 </pre>
 364
 365 <p>A description of each parameter follows:</p>
 366
 367 <h5>image</h5>
 368 <p>the image.</p>
 369
 370 <h5>virtual_pixel_method</h5>
 371 <p>the virtual pixel method.</p>
 372
 373 <h5>x,y</h5>
 374 <p>These values define the location of the pixel to return.</p>
 375
 376 <h5>pixel</h5>
 377 <p>return a pixel at the specified (x,y) location.</p>
 378
 379 <h5>exception</h5>
 380 <p>return any errors or warnings in this structure.</p>
 381
 382  </div>
 383 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2>
 384 <div class="doc-section">
 385
 386 <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>
 387
 388 <p>The format of the GetOneVirtualPixel() method is:</p>
 389
 390 <pre class="code">
 391   MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x,
 392     const ssize_t y,PixelPacket *pixel,ExceptionInfo exception)
 393 </pre>
 394
 395 <p>A description of each parameter follows:</p>
 396
 397 <h5>image</h5>
 398 <p>the image.</p>
 399
 400 <h5>x,y</h5>
 401 <p>These values define the location of the pixel to return.</p>
 402
 403 <h5>pixel</h5>
 404 <p>return a pixel at the specified (x,y) location.</p>
 405
 406 <h5>exception</h5>
 407 <p>return any errors or warnings in this structure.</p>
 408
 409  </div>
 410 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualMetacontent">GetVirtualMetacontent</a></h2>
 411 <div class="doc-section">
 412
 413 <p>GetVirtualMetacontent() returns the virtual metacontent corresponding with the last call to QueueAuthenticPixels() or GetVirtualPixels().  NULL is returned if the meta-content are not available.</p>
 414
 415 <p>The format of the GetVirtualMetacontent() method is:</p>
 416
 417 <pre class="code">
 418   const void *GetVirtualMetacontent(const Image *image)
 419 </pre>
 420
 421 <p>A description of each parameter follows:</p>
 422
 423 <h5>image</h5>
 424 <p>the image.</p>
 425
 426  </div>
 427 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="VirtualPixelModulo">VirtualPixelModulo</a></h2>
 428 <div class="doc-section">
 429
 430 <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>
 431  </div>
 432 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2>
 433 <div class="doc-section">
 434
 435 <p>GetVirtualPixelQueue() returns the virtual pixels associated corresponding with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p>
 436
 437 <p>The format of the GetVirtualPixelQueue() method is:</p>
 438
 439 <pre class="code">
 440   const Quantum *GetVirtualPixelQueue(const Image image)
 441 </pre>
 442
 443 <p>A description of each parameter follows:</p>
 444
 445 <h5>image</h5>
 446 <p>the image.</p>
 447
 448  </div>
 449 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2>
 450 <div class="doc-section">
 451
 452 <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>
 453
 454 <p>Pixels accessed via the returned pointer represent a simple array of type Quantum.  If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticMetacontent() after invoking GetAuthenticPixels() to access the meta-content (of type void) corresponding to the the region.</p>
 455
 456 <p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p>
 457
 458 <p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe.  In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p>
 459
 460 <p>The format of the GetVirtualPixels() method is:</p>
 461
 462 <pre class="code">
 463   const Quantum *GetVirtualPixels(const Image *image,const ssize_t x,
 464     const ssize_t y,const size_t columns,const size_t rows,
 465     ExceptionInfo *exception)
 466 </pre>
 467
 468 <p>A description of each parameter follows:</p>
 469
 470 <h5>image</h5>
 471 <p>the image.</p>
 472
 473 <h5>x,y,columns,rows</h5>
 474 <p>These values define the perimeter of a region of pixels.</p>
 475
 476 <h5>exception</h5>
 477 <p>return any errors or warnings in this structure.</p>
 478
 479  </div>
 480 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2>
 481 <div class="doc-section">
 482
 483 <p>QueueAuthenticPixels() queues a mutable pixel region.  If the region is successfully initialized a pointer to a Quantum 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>
 484
 485 <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>
 486
 487 <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>
 488
 489 <p>Pixels accessed via the returned pointer represent a simple array of type Quantum. If the image type is CMYK or the storage class is PseudoClass, call GetAuthenticMetacontent() after invoking GetAuthenticPixels() to obtain the meta-content (of type void) corresponding to the region. Once the Quantum (and/or Quantum) array has been updated, the changes must be saved back to the underlying image using SyncAuthenticPixels() or they may be lost.</p>
 490
 491 <p>The format of the QueueAuthenticPixels() method is:</p>
 492
 493 <pre class="code">
 494   Quantum *QueueAuthenticPixels(Image *image,const ssize_t x,
 495     const ssize_t y,const size_t columns,const size_t rows,
 496     ExceptionInfo *exception)
 497 </pre>
 498
 499 <p>A description of each parameter follows:</p>
 500
 501 <h5>image</h5>
 502 <p>the image.</p>
 503
 504 <h5>x,y,columns,rows</h5>
 505 <p>These values define the perimeter of a region of pixels.</p>
 506
 507 <h5>exception</h5>
 508 <p>return any errors or warnings in this structure.</p>
 509
 510  </div>
 511 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2>
 512 <div class="doc-section">
 513
 514 <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>
 515
 516 <p>The format of the SetPixelCacheVirtualMethod() method is:</p>
 517
 518 <pre class="code">
 519   VirtualPixelMethod SetPixelCacheVirtualMethod(const Image *image,
 520     const VirtualPixelMethod virtual_pixel_method)
 521 </pre>
 522
 523 <p>A description of each parameter follows:</p>
 524
 525 <h5>image</h5>
 526 <p>the image.</p>
 527
 528 <h5>virtual_pixel_method</h5>
 529 <p>choose the type of virtual pixel.</p>
 530
 531  </div>
 532 <h2><a href="http://www.imagemagick.org/api/MagickCore/cache_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2>
 533 <div class="doc-section">
 534
 535 <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>
 536
 537 <p>The format of the SyncAuthenticPixels() method is:</p>
 538
 539 <pre class="code">
 540   MagickBooleanType SyncAuthenticPixels(Image *image,
 541     ExceptionInfo *exception)
 542 </pre>
 543
 544 <p>A description of each parameter follows:</p>
 545
 546 <h5>image</h5>
 547 <p>the image.</p>
 548
 549 <h5>exception</h5>
 550 <p>return any errors or warnings in this structure.</p>
 551
 552  </div>
 553 \r
 554 </div>\r
 555 \r
 556 <div id="linkbar">\r
 557     <span id="linkbar-west">&nbsp;</span>\r
 558     <span id="linkbar-center">\r
 559       <a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> &bull;\r
 560       <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>\r
 561     </span>\r
 562     <span id="linkbar-east">&nbsp;</span>\r
 563   </div>\r
 564   <div class="footer">\r
 565     <span id="footer-west">&copy; 1999-2011 ImageMagick Studio LLC</span>\r
 566     <span id="footer-east"> <a href="../http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>\r
 567   </div>\r
 568   <div style="clear: both; margin: 0; width: 100%; "></div>\r
 569   <script type="text/javascript">\r
 570     var _gaq = _gaq || [];\r
 571     _gaq.push(['_setAccount', 'UA-17690367-1']);\r
 572     _gaq.push(['_trackPageview']);\r
 573 \r
 574     (function() {\r
 575       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;\r
 576       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';\r
 577       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\r
 578     })();\r
 579   </script>\r
 580 </body>\r
 581 </html>\r