1 2 3 4 5 <!DOCTYPE html> 6 <html lang="en"> 7 <head> 8 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" /> 9 <title>ImageMagick: MagickCore, C API for ImageMagick: Get or Set Image Pixels</title> 10 <meta http-equiv="content-type" content="text/html; charset=utf-8"/> 11 <meta name="application-name" content="ImageMagick"/> 12 <meta name="description" content="ImageMagick is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bzier curves."/> 13 <meta name="application-url" content="http://www.imagemagick.org"/> 14 <meta name="generator" content="PHP"/> 15 <meta name="keywords" content="magickcore, c, api, for, imagemagick:, get, or, set, image, pixels, ImageMagick, 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-2016 ImageMagick Studio LLC"/> 23 <meta name="distribution" content="Global"/> 24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1"/> 25 <link rel="icon" href="../image/wand.png"/> 26 <link rel="shortcut icon" href="../image/wand.ico"/> 27 <link rel="stylesheet" href="../css/magick.php"/> 28 </head> 29 <body> 30 <div class="main"> 31 <div class="magick-masthead"> 32 <div class="container"> 33 <script async="async" src="http://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle" 34 style="display:block" 35 data-ad-client="ca-pub-3129977114552745" 36 data-ad-slot="6345125851" 37 data-ad-format="auto"></ins> 38 <script> 39 (adsbygoogle = window.adsbygoogle || []).push({}); 40 </script> 41 <nav class="magick-nav"> 42 <a class="magick-nav-item " href="../index.php">Home</a> 43 <a class="magick-nav-item " href="../script/binary-releases.php">Download</a> 44 <a class="magick-nav-item " href="../script/command-line-tools.php">Tools</a> 45 <a class="magick-nav-item " href="../script/command-line-options.php">Options</a> 46 <a class="magick-nav-item " href="../script/resources.php">Resources</a> 47 <a class="magick-nav-item " href="../script/api.php">Develop</a> 48 <a class="magick-nav-item " href="../script/search.php">Search</a> 49 <a class="magick-nav-item pull-right" href="http://www.imagemagick.org/discourse-server/">Community</a> 50 </nav> 51 </div> 52 </div> 53 <div class="container"> 54 <div class="magick-header"> 55 <p class="text-center"><a href="cache.php#AcquirePixelCacheNexus">AcquirePixelCacheNexus</a> • <a href="cache.php#GetAuthenticMetacontent">GetAuthenticMetacontent</a> • <a href="cache.php#GetAuthenticPixelQueue">GetAuthenticPixelQueue</a> • <a href="cache.php#GetAuthenticPixels">GetAuthenticPixels</a> • <a href="cache.php#GetOneAuthenticPixel">GetOneAuthenticPixel</a> • <a href="cache.php#GetOneVirtualPixel">GetOneVirtualPixel</a> • <a href="cache.php#GetOneVirtualPixelInfo">GetOneVirtualPixelInfo</a> • <a href="cache.php#GetVirtualMetacontent">GetVirtualMetacontent</a> • <a href="cache.php#GetVirtualPixelQueue">GetVirtualPixelQueue</a> • <a href="cache.php#GetVirtualPixels">GetVirtualPixels</a> • <a href="cache.php#QueueAuthenticPixels">QueueAuthenticPixels</a> • <a href="cache.php#SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a> • <a href="cache.php#SyncAuthenticPixels">SyncAuthenticPixels</a></p> 56 57 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="AcquirePixelCacheNexus">AcquirePixelCacheNexus</a></h2> 58 59 <p>AcquirePixelCacheNexus() allocates the NexusInfo structure.</p> 60 61 <p>The format of the AcquirePixelCacheNexus method is:</p> 62 63 <pre class="text"> 64 NexusInfo **AcquirePixelCacheNexus(const size_t number_threads) 65 </pre> 66 67 <p>A description of each parameter follows:</p> 68 69 <dd> 70 </dd> 71 72 <dd> </dd> 73 <dl class="dl-horizontal"> 74 <dt>number_threads</dt> 75 <dd>the number of nexus threads. </dd> 76 77 <dd> </dd> 78 </dl> 79 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticMetacontent">GetAuthenticMetacontent</a></h2> 80 81 <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> 82 83 <p>The format of the GetAuthenticMetacontent() method is:</p> 84 85 <pre class="text"> 86 void *GetAuthenticMetacontent(const Image *image) 87 </pre> 88 89 <p>A description of each parameter follows:</p> 90 91 <dd> 92 </dd> 93 94 <dd> </dd> 95 <dl class="dl-horizontal"> 96 <dt>image</dt> 97 <dd>the image. </dd> 98 99 <dd> </dd> 100 </dl> 101 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixelQueue">GetAuthenticPixelQueue</a></h2> 102 103 <p>GetAuthenticPixelQueue() returns the authentic pixels associated corresponding with the last call to QueueAuthenticPixels() or GetAuthenticPixels().</p> 104 105 <p>The format of the GetAuthenticPixelQueue() method is:</p> 106 107 <pre class="text"> 108 Quantum *GetAuthenticPixelQueue(const Image image) 109 </pre> 110 111 <p>A description of each parameter follows:</p> 112 113 <dd> 114 </dd> 115 116 <dd> </dd> 117 <dl class="dl-horizontal"> 118 <dt>image</dt> 119 <dd>the image. </dd> 120 121 <dd> </dd> 122 </dl> 123 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetAuthenticPixels">GetAuthenticPixels</a></h2> 124 125 <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> 126 127 <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> 128 129 <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> 130 131 <p>The format of the GetAuthenticPixels() method is:</p> 132 133 <pre class="text"> 134 Quantum *GetAuthenticPixels(Image *image,const ssize_t x, 135 const ssize_t y,const size_t columns,const size_t rows, 136 ExceptionInfo *exception) 137 </pre> 138 139 <p>A description of each parameter follows:</p> 140 141 <dd> 142 </dd> 143 144 <dd> </dd> 145 <dl class="dl-horizontal"> 146 <dt>image</dt> 147 <dd>the image. </dd> 148 149 <dd> </dd> 150 <dt>x,y,columns,rows</dt> 151 <dd> These values define the perimeter of a region of pixels. </dd> 152 153 <dd> </dd> 154 <dt>exception</dt> 155 <dd>return any errors or warnings in this structure. </dd> 156 157 <dd> </dd> 158 </dl> 159 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneAuthenticPixel">GetOneAuthenticPixel</a></h2> 160 161 <p>GetOneAuthenticPixel() returns a single pixel at the specified (x,y) location. The image background color is returned if an error occurs.</p> 162 163 <p>The format of the GetOneAuthenticPixel() method is:</p> 164 165 <pre class="text"> 166 MagickBooleanType GetOneAuthenticPixel(const Image image,const ssize_t x, 167 const ssize_t y,Quantum *pixel,ExceptionInfo *exception) 168 </pre> 169 170 <p>A description of each parameter follows:</p> 171 172 <dd> 173 </dd> 174 175 <dd> </dd> 176 <dl class="dl-horizontal"> 177 <dt>image</dt> 178 <dd>the image. </dd> 179 180 <dd> </dd> 181 <dt>x,y</dt> 182 <dd> These values define the location of the pixel to return. </dd> 183 184 <dd> </dd> 185 <dt>pixel</dt> 186 <dd>return a pixel at the specified (x,y) location. </dd> 187 188 <dd> </dd> 189 <dt>exception</dt> 190 <dd>return any errors or warnings in this structure. </dd> 191 192 <dd> </dd> 193 </dl> 194 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualPixel">GetOneVirtualPixel</a></h2> 195 196 <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> 197 198 <p>The format of the GetOneVirtualPixel() method is:</p> 199 200 <pre class="text"> 201 MagickBooleanType GetOneVirtualPixel(const Image image,const ssize_t x, 202 const ssize_t y,Quantum *pixel,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</dt> 217 <dd> These values define the location of the pixel to return. </dd> 218 219 <dd> </dd> 220 <dt>pixel</dt> 221 <dd>return a pixel at the specified (x,y) location. </dd> 222 223 <dd> </dd> 224 <dt>exception</dt> 225 <dd>return any errors or warnings in this structure. </dd> 226 227 <dd> </dd> 228 </dl> 229 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetOneVirtualPixelInfo">GetOneVirtualPixelInfo</a></h2> 230 231 <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> 232 233 <p>The format of the GetOneVirtualPixelInfo() method is:</p> 234 235 <pre class="text"> 236 MagickBooleanType GetOneVirtualPixelInfo(const Image image, 237 const VirtualPixelMethod virtual_pixel_method,const ssize_t x, 238 const ssize_t y,PixelInfo *pixel,ExceptionInfo exception) 239 </pre> 240 241 <p>A description of each parameter follows:</p> 242 243 <dd> 244 </dd> 245 246 <dd> </dd> 247 <dl class="dl-horizontal"> 248 <dt>image</dt> 249 <dd>the image. </dd> 250 251 <dd> </dd> 252 <dt>virtual_pixel_method</dt> 253 <dd>the virtual pixel method. </dd> 254 255 <dd> </dd> 256 <dt>x,y</dt> 257 <dd> these values define the location of the pixel to return. </dd> 258 259 <dd> </dd> 260 <dt>pixel</dt> 261 <dd>return a pixel at the specified (x,y) location. </dd> 262 263 <dd> </dd> 264 <dt>exception</dt> 265 <dd>return any errors or warnings in this structure. </dd> 266 267 <dd> </dd> 268 </dl> 269 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualMetacontent">GetVirtualMetacontent</a></h2> 270 271 <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> 272 273 <p>The format of the GetVirtualMetacontent() method is:</p> 274 275 <pre class="text"> 276 const void *GetVirtualMetacontent(const Image *image) 277 </pre> 278 279 <p>A description of each parameter follows:</p> 280 281 <dd> 282 </dd> 283 284 <dd> </dd> 285 <dl class="dl-horizontal"> 286 <dt>image</dt> 287 <dd>the image. </dd> 288 289 <dd> </dd> 290 </dl> 291 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixelQueue">GetVirtualPixelQueue</a></h2> 292 293 <p>GetVirtualPixelQueue() returns the virtual pixels associated corresponding with the last call to QueueAuthenticPixels() or GetVirtualPixels().</p> 294 295 <p>The format of the GetVirtualPixelQueue() method is:</p> 296 297 <pre class="text"> 298 const Quantum *GetVirtualPixelQueue(const Image image) 299 </pre> 300 301 <p>A description of each parameter follows:</p> 302 303 <dd> 304 </dd> 305 306 <dd> </dd> 307 <dl class="dl-horizontal"> 308 <dt>image</dt> 309 <dd>the image. </dd> 310 311 <dd> </dd> 312 </dl> 313 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="GetVirtualPixels">GetVirtualPixels</a></h2> 314 315 <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> 316 317 <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> 318 319 <p>If you plan to modify the pixels, use GetAuthenticPixels() instead.</p> 320 321 <p>Note, the GetVirtualPixels() and GetAuthenticPixels() methods are not thread- safe. In a threaded environment, use GetCacheViewVirtualPixels() or GetCacheViewAuthenticPixels() instead.</p> 322 323 <p>The format of the GetVirtualPixels() method is:</p> 324 325 <pre class="text"> 326 const Quantum *GetVirtualPixels(const Image *image,const ssize_t x, 327 const ssize_t y,const size_t columns,const size_t rows, 328 ExceptionInfo *exception) 329 </pre> 330 331 <p>A description of each parameter follows:</p> 332 333 <dd> 334 </dd> 335 336 <dd> </dd> 337 <dl class="dl-horizontal"> 338 <dt>image</dt> 339 <dd>the image. </dd> 340 341 <dd> </dd> 342 <dt>x,y,columns,rows</dt> 343 <dd> These values define the perimeter of a region of pixels. </dd> 344 345 <dd> </dd> 346 <dt>exception</dt> 347 <dd>return any errors or warnings in this structure. </dd> 348 349 <dd> </dd> 350 </dl> 351 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="QueueAuthenticPixels">QueueAuthenticPixels</a></h2> 352 353 <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> 354 355 <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> 356 357 <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> 358 359 <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> 360 361 <p>The format of the QueueAuthenticPixels() method is:</p> 362 363 <pre class="text"> 364 Quantum *QueueAuthenticPixels(Image *image,const ssize_t x, 365 const ssize_t y,const size_t columns,const size_t rows, 366 ExceptionInfo *exception) 367 </pre> 368 369 <p>A description of each parameter follows:</p> 370 371 <dd> 372 </dd> 373 374 <dd> </dd> 375 <dl class="dl-horizontal"> 376 <dt>image</dt> 377 <dd>the image. </dd> 378 379 <dd> </dd> 380 <dt>x,y,columns,rows</dt> 381 <dd> These values define the perimeter of a region of pixels. </dd> 382 383 <dd> </dd> 384 <dt>exception</dt> 385 <dd>return any errors or warnings in this structure. </dd> 386 387 <dd> </dd> 388 </dl> 389 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="SetPixelCacheVirtualMethod">SetPixelCacheVirtualMethod</a></h2> 390 391 <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> 392 393 <p>The format of the SetPixelCacheVirtualMethod() method is:</p> 394 395 <pre class="text"> 396 VirtualPixelMethod SetPixelCacheVirtualMethod(Image *image, 397 const VirtualPixelMethod virtual_pixel_method,ExceptionInfo *exception) 398 </pre> 399 400 <p>A description of each parameter follows:</p> 401 402 <dd> 403 </dd> 404 405 <dd> </dd> 406 <dl class="dl-horizontal"> 407 <dt>image</dt> 408 <dd>the image. </dd> 409 410 <dd> </dd> 411 <dt>virtual_pixel_method</dt> 412 <dd>choose the type of virtual pixel. </dd> 413 414 <dd> </dd> 415 <dt>exception</dt> 416 <dd>return any errors or warnings in this structure. </dd> 417 418 <dd> </dd> 419 </dl> 420 <h2><a href="http://nextgen.imagemagick.org/api/MagickCore/cache_8c.html" id="SyncAuthenticPixels">SyncAuthenticPixels</a></h2> 421 422 <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> 423 424 <p>The format of the SyncAuthenticPixels() method is:</p> 425 426 <pre class="text"> 427 MagickBooleanType SyncAuthenticPixels(Image *image, 428 ExceptionInfo *exception) 429 </pre> 430 431 <p>A description of each parameter follows:</p> 432 433 <dd> 434 </dd> 435 436 <dd> </dd> 437 <dl class="dl-horizontal"> 438 <dt>image</dt> 439 <dd>the image. </dd> 440 441 <dd> </dd> 442 <dt>exception</dt> 443 <dd>return any errors or warnings in this structure. </dd> 444 445 <dd> </dd> 446 </dl> 447 </div> 448 <footer class="magick-footer"> 449 <p><a href="../script/support.php">Donate</a> 450 <a href="../script/sitemap.php">Sitemap</a> 451 <a href="../script/links.php">Related</a> 452 <a href="../script/architecture.php">Architecture</a> 453 </p> 454 <p><a href="cache.php#">Back to top</a> 455 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> 456 <a href="../script/contact.php">Contact Us</a></p> 457 <p><small> 1999-2016 ImageMagick Studio LLC</small></p> 458 </footer> 459 </div><!-- /.container --> 460 461 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> 462 <script src="http://nextgen.imagemagick.org/js/magick.php"></script> 463 </div> 464 </body> 465 </html> 466
