1 2 3 4 5<!DOCTYPE html> 6<html lang="en"> 7<head> 8 <meta charset="utf-8" /> 9 <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no" /> 10 <title>ImageMagick - MagickCore, C API: Get or Set Image Pixels</title> 11 <meta name="application-name" content="ImageMagick" /> 12 <meta name="description" content="Use ImageMagick® to create, edit, compose, and convert bitmap images. Resize an image, crop it, change its shades and colors, add captions, and more." /> 13 <meta name="application-url" content="https://imagemagick.org" /> 14 <meta name="generator" content="PHP" /> 15 <meta name="keywords" content="magickcore, c, api:, get, or, set, image, pixels, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert" /> 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-2020 ImageMagick Studio LLC" /> 23 <meta name="distribution" content="Global" /> 24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" /> 25 <meta property='og:url' content='../../' /> 26 <meta property='og:title' content='ImageMagick' /> 27 <meta property='og:image' content='../../images/logo.png' /> 28 <meta property='og:type' content='website' /> 29 <meta property='og:site_name' content='ImageMagick' /> 30 <meta property='og:description' content="Convert, Edit, or Compose Bitmap Images" /> 31 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" /> 32 <link href="../../api/cache.html" rel="canonical" /> 33 <link href="../images/wand.png" rel="icon" /> 34 <link href="../images/wand.ico" rel="shortcut icon" /> 35 <link href="assets/magick.css" rel="stylesheet" /> 36</head> 37<body> 38 <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark"> 39 <a class="navbar-brand" href="../index.html"><img class="d-block" id="icon" alt="ImageMagick" width="32" height="32" src="../images/wand.ico"/></a> 40 <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsMagick" aria-controls="navbarsMagick" aria-expanded="false" aria-label="Toggle navigation"> 41 <span class="navbar-toggler-icon"></span> 42 </button> 43 44 <div class="navbar-collapse collapse" id="navbarsMagick" style=""> 45 <ul class="navbar-nav mr-auto"> 46 <li class="nav-item "> 47 <a class="nav-link" href="../index.html">Home <span class="sr-only">(current)</span></a> 48 </li> 49 <li class="nav-item "> 50 <a class="nav-link" href="../www/download.html">Download</a> 51 </li> 52 <li class="nav-item "> 53 <a class="nav-link" href="../www/command-line-tools.html">Tools</a> 54 </li> 55 <li class="nav-item "> 56 <a class="nav-link" href="../www/command-line-processing.html">Command-line</a> 57 </li> 58 <li class="nav-item "> 59 <a class="nav-link" href="../www/resources.html">Resources</a> 60 </li> 61 <li class="nav-item "> 62 <a class="nav-link" href="../www/develop.html">Develop</a> 63 </li> 64 <li class="nav-item"> 65 <a class="nav-link" target="_blank" href="https://imagemagick.org/discourse-server/">Community</a> 66 </li> 67 </ul> 68 <form class="form-inline my-2 my-lg-0" action="../https://imagemagick.org/script/search.php"> 69 <input class="form-control mr-sm-2" type="text" name="q" placeholder="Search" aria-label="Search"> 70 <button class="btn btn-outline-success my-2 my-sm-0" type="submit" name="sa">Search</button> 71 </form> 72 </div> 73 </nav> 74 <div class="container"> 75 <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle" 76 style="display:block" 77 data-ad-client="ca-pub-3129977114552745" 78 data-ad-slot="6345125851" 79 data-full-width-responsive="true" 80 data-ad-format="horizontal"></ins> 81 <script> 82 (adsbygoogle = window.adsbygoogle || []).push({}); 83 </script> 84 85 </div> 86 87 <main class="container"> 88 <div class="magick-template"> 89<div class="magick-header"> 90<p class="text-center"><a href="cache.html#AcquirePixelCacheNexus">AcquirePixelCacheNexus</a> • <a href="cache.html#AcquirePixelCachePixels">AcquirePixelCachePixels</a> • <a href="cache.html#GetAuthenticMetacontent">GetAuthenticMetacontent</a> • <a href="cache.html#GetAuthenticPixelQueue">GetAuthenticPixelQueue</a> • <a href="cache.html#GetAuthenticPixels">GetAuthenticPixels</a> • <a href="cache.html#GetOneAuthenticPixel">GetOneAuthenticPixel</a> • <a href="cache.html#GetOneVirtualPixel">GetOneVirtualPixel</a> • <a href="cache.html#GetOneVirtualPixelInfo">GetOneVirtualPixelInfo</a> • <a href="cache.html#GetVirtualMetacontent">GetVirtualMetacontent</a> • <a href="cache.html#GetVirtualPixelQueue">GetVirtualPixelQueue</a> • <a href="cache.html#GetVirtualPixels">GetVirtualPixels</a> • <a href="cache.html#QueueAuthenticPixels">QueueAuthenticPixels</a> • <a href="cache.html#SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a> • <a href="cache.html#SyncAuthenticPixels">SyncAuthenticPixels</a></p> 91 92<h2><a href="../../api/MagickCore/cache_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2> 93 94<p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p> 95 96<p>The format of the AcquirePixelCacheNexus method is:</p> 97 98<pre class="text"> 99NexusInfo **AcquirePixelCacheNexus(const size_t number_threads) 100</pre> 101 102<p>A description of each parameter follows:</p> 103 104<dd> 105</dd> 106 107<dd> </dd> 108<dl class="dl-horizontal"> 109<dt>number_threads</dt> 110<dd>the number of nexus threads. </dd> 111 112<dd> </dd> 113</dl> 114<h2><a href="../../api/MagickCore/cache_8c.html" id="AcquirePixelCachePixels">AcquirePixelCachePixels</a></h2> 115 116<p>AcquirePixelCachePixels() returns the pixels associated with the specified image.</p> 117 118<p>The format of the AcquirePixelCachePixels() method is:</p> 119 120<pre class="text"> 121void *AcquirePixelCachePixels(const Image *image,size_t *length, 122 ExceptionInfo *exception) 123</pre> 124 125<p>A description of each parameter follows:</p> 126 127<dd> 128</dd> 129 130<dd> </dd> 131<dl class="dl-horizontal"> 132<dt>image</dt> 133<dd>the image. </dd> 134 135<dd> </dd> 136<dt>length</dt> 137<dd>the pixel cache length. </dd> 138 139<dd> </dd> 140<dt>exception</dt> 141<dd>return any errors or warnings in this structure. </dd> 142 143<dd> </dd> 144</dl> 145<h2><a href="../../api/MagickCore/cache_8c.html" id="GetAuthenticMetacontent">GetAuthenticMetacontent</a></h2> 146 147<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> 148 149<p>The format of the GetAuthenticMetacontent() method is:</p> 150 151<pre class="text"> 152void *GetAuthenticMetacontent(const Image *image) 153</pre> 154 155<p>A description of each parameter follows:</p> 156 157<dd> 158</dd> 159 160<dd> </dd> 161<dl class="dl-horizontal"> 162<dt>image</dt> 163<dd>the image. </dd> 164 165<dd> </dd> 166</dl> 167<h2><a href="../../api/MagickCore/cache_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2> 168 169<p>GetAuthenticPixelQueue() returns the authentic pixels associated corresponding with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p> 170 171<p>The format of the GetAuthenticPixelQueue() method is:</p> 172 173<pre class="text"> 174Quantum *GetAuthenticPixelQueue(const Image image) 175</pre> 176 177<p>A description of each parameter follows:</p> 178 179<dd> 180</dd> 181 182<dd> </dd> 183<dl class="dl-horizontal"> 184<dt>image</dt> 185<dd>the image. </dd> 186 187<dd> </dd> 188</dl> 189<h2><a href="../../api/MagickCore/cache_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2> 190 191<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> 192 193<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> 194 195<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> 196 197<p>The format of the GetAuthenticPixels() method is:</p> 198 199<pre class="text"> 200Quantum *GetAuthenticPixels(Image *image,const ssize_t x, 201 const ssize_t y,const size_t columns,const size_t rows, 202 ExceptionInfo *exception) 203</pre> 204 205<p>A description of each parameter follows:</p> 206 207<dd> 208</dd> 209 210<dd> </dd> 211<dl class="dl-horizontal"> 212<dt>image</dt> 213<dd>the image. </dd> 214 215<dd> </dd> 216<dt>x,y,columns,rows</dt> 217<dd> These values define the perimeter of a region of pixels. </dd> 218 219<dd> </dd> 220<dt>exception</dt> 221<dd>return any errors or warnings in this structure. </dd> 222 223<dd> </dd> 224</dl> 225<h2><a href="../../api/MagickCore/cache_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2> 226 227<p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p> 228 229<p>The format of the GetOneAuthenticPixel() method is:</p> 230 231<pre class="text"> 232MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x, 233 const ssize_t y,Quantum *pixel,ExceptionInfo *exception) 234</pre> 235 236<p>A description of each parameter follows:</p> 237 238<dd> 239</dd> 240 241<dd> </dd> 242<dl class="dl-horizontal"> 243<dt>image</dt> 244<dd>the image. </dd> 245 246<dd> </dd> 247<dt>x,y</dt> 248<dd> These values define the location of the pixel to return. </dd> 249 250<dd> </dd> 251<dt>pixel</dt> 252<dd>return a pixel at the specified (x,y) location. </dd> 253 254<dd> </dd> 255<dt>exception</dt> 256<dd>return any errors or warnings in this structure. </dd> 257 258<dd> </dd> 259</dl> 260<h2><a href="../../api/MagickCore/cache_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2> 261 262<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> 263 264<p>The format of the GetOneVirtualPixel() method is:</p> 265 266<pre class="text"> 267MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x, 268 const ssize_t y,Quantum *pixel,ExceptionInfo exception) 269</pre> 270 271<p>A description of each parameter follows:</p> 272 273<dd> 274</dd> 275 276<dd> </dd> 277<dl class="dl-horizontal"> 278<dt>image</dt> 279<dd>the image. </dd> 280 281<dd> </dd> 282<dt>x,y</dt> 283<dd> These values define the location of the pixel to return. </dd> 284 285<dd> </dd> 286<dt>pixel</dt> 287<dd>return a pixel at the specified (x,y) location. </dd> 288 289<dd> </dd> 290<dt>exception</dt> 291<dd>return any errors or warnings in this structure. </dd> 292 293<dd> </dd> 294</dl> 295<h2><a href="../../api/MagickCore/cache_8c.html" id="GetOneVirtualPixelInfo">GetOneVirtualPixelInfo</a></h2> 296 297<p>GetOneVirtualPixelInfo() 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> 298 299<p>The format of the GetOneVirtualPixelInfo() method is:</p> 300 301<pre class="text"> 302MagickBooleanType GetOneVirtualPixelInfo(const Image image, 303 const VirtualPixelMethod virtual_pixel_method,const ssize_t x, 304 const ssize_t y,PixelInfo *pixel,ExceptionInfo exception) 305</pre> 306 307<p>A description of each parameter follows:</p> 308 309<dd> 310</dd> 311 312<dd> </dd> 313<dl class="dl-horizontal"> 314<dt>image</dt> 315<dd>the image. </dd> 316 317<dd> </dd> 318<dt>virtual_pixel_method</dt> 319<dd>the virtual pixel method. </dd> 320 321<dd> </dd> 322<dt>x,y</dt> 323<dd> these values define the location of the pixel to return. </dd> 324 325<dd> </dd> 326<dt>pixel</dt> 327<dd>return a pixel at the specified (x,y) location. </dd> 328 329<dd> </dd> 330<dt>exception</dt> 331<dd>return any errors or warnings in this structure. </dd> 332 333<dd> </dd> 334</dl> 335<h2><a href="../../api/MagickCore/cache_8c.html" id="GetVirtualMetacontent">GetVirtualMetacontent</a></h2> 336 337<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> 338 339<p>The format of the GetVirtualMetacontent() method is:</p> 340 341<pre class="text"> 342const void *GetVirtualMetacontent(const Image *image) 343</pre> 344 345<p>A description of each parameter follows:</p> 346 347<dd> 348</dd> 349 350<dd> </dd> 351<dl class="dl-horizontal"> 352<dt>image</dt> 353<dd>the image. </dd> 354 355<dd> </dd> 356</dl> 357<h2><a href="../../api/MagickCore/cache_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2> 358 359<p>GetVirtualPixelQueue() returns the virtual pixels associated corresponding with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p> 360 361<p>The format of the GetVirtualPixelQueue() method is:</p> 362 363<pre class="text"> 364const Quantum *GetVirtualPixelQueue(const Image image) 365</pre> 366 367<p>A description of each parameter follows:</p> 368 369<dd> 370</dd> 371 372<dd> </dd> 373<dl class="dl-horizontal"> 374<dt>image</dt> 375<dd>the image. </dd> 376 377<dd> </dd> 378</dl> 379<h2><a href="../../api/MagickCore/cache_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2> 380 381<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> 382 383<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> 384 385<p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p> 386 387<p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p> 388 389<p>The format of the GetVirtualPixels() method is:</p> 390 391<pre class="text"> 392const Quantum *GetVirtualPixels(const Image *image,const ssize_t x, 393 const ssize_t y,const size_t columns,const size_t rows, 394 ExceptionInfo *exception) 395</pre> 396 397<p>A description of each parameter follows:</p> 398 399<dd> 400</dd> 401 402<dd> </dd> 403<dl class="dl-horizontal"> 404<dt>image</dt> 405<dd>the image. </dd> 406 407<dd> </dd> 408<dt>x,y,columns,rows</dt> 409<dd> These values define the perimeter of a region of pixels. </dd> 410 411<dd> </dd> 412<dt>exception</dt> 413<dd>return any errors or warnings in this structure. </dd> 414 415<dd> </dd> 416</dl> 417<h2><a href="../../api/MagickCore/cache_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2> 418 419<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> 420 421<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> 422 423<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> 424 425<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> 426 427<p>The format of the QueueAuthenticPixels() method is:</p> 428 429<pre class="text"> 430Quantum *QueueAuthenticPixels(Image *image,const ssize_t x, 431 const ssize_t y,const size_t columns,const size_t rows, 432 ExceptionInfo *exception) 433</pre> 434 435<p>A description of each parameter follows:</p> 436 437<dd> 438</dd> 439 440<dd> </dd> 441<dl class="dl-horizontal"> 442<dt>image</dt> 443<dd>the image. </dd> 444 445<dd> </dd> 446<dt>x,y,columns,rows</dt> 447<dd> These values define the perimeter of a region of pixels. </dd> 448 449<dd> </dd> 450<dt>exception</dt> 451<dd>return any errors or warnings in this structure. </dd> 452 453<dd> </dd> 454</dl> 455<h2><a href="../../api/MagickCore/cache_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2> 456 457<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> 458 459<p>The format of the SetPixelCacheVirtualMethod() method is:</p> 460 461<pre class="text"> 462VirtualPixelMethod SetPixelCacheVirtualMethod(Image *image, 463 const VirtualPixelMethod virtual_pixel_method,ExceptionInfo *exception) 464</pre> 465 466<p>A description of each parameter follows:</p> 467 468<dd> 469</dd> 470 471<dd> </dd> 472<dl class="dl-horizontal"> 473<dt>image</dt> 474<dd>the image. </dd> 475 476<dd> </dd> 477<dt>virtual_pixel_method</dt> 478<dd>choose the type of virtual pixel. </dd> 479 480<dd> </dd> 481<dt>exception</dt> 482<dd>return any errors or warnings in this structure. </dd> 483 484<dd> </dd> 485</dl> 486<h2><a href="../../api/MagickCore/cache_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2> 487 488<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> 489 490<p>The format of the SyncAuthenticPixels() method is:</p> 491 492<pre class="text"> 493MagickBooleanType SyncAuthenticPixels(Image *image, 494 ExceptionInfo *exception) 495</pre> 496 497<p>A description of each parameter follows:</p> 498 499<dd> 500</dd> 501 502<dd> </dd> 503<dl class="dl-horizontal"> 504<dt>image</dt> 505<dd>the image. </dd> 506 507<dd> </dd> 508<dt>exception</dt> 509<dd>return any errors or warnings in this structure. </dd> 510 511<dd> </dd> 512</dl> 513</div> 514 </div> 515 </main><!-- /.container --> 516 <footer class="magick-footer"> 517 <p><a href="../www/security-policy.html">Security</a> • 518 <a href="../www/architecture.html">Architecture</a> 519 520 <a href="cache.html#"><img class="d-inline" id="wand" alt="And Now a Touch of Magick" width="16" height="16" src="../images/wand.ico"/></a> 521 522 <a href="../www/links.html">Related</a> • 523 <a href="../www/sitemap.html">Sitemap</a> 524 <br/> 525 <a href="../www/support.html">Donate</a> • 526 <a href="http://pgp.mit.edu/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> • 527 <a href="../www/contact.html">Contact Us</a> 528 <br/> 529 <small>© 1999-2020 ImageMagick Studio LLC</small></p> 530 </footer> 531 532 <!-- Javascript assets --> 533 <script src="assets/magick.js" crossorigin="anonymous"></script> 534 <script>window.jQuery || document.write('<script src="https://localhost/ajax/libs/jquery/3.4.1/jquery.min.js"><\/script>')</script> 535</body> 536</html> 537<!-- Magick Cache 29th December 2019 22:53 -->
