| <?xml version="1.0" encoding="utf-8" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>Magick++ API: Working with Pixels </title> |
| <link rel="stylesheet" href="magick.css" type="text/css" /> |
| </head> |
| <body> |
| <div class="doc-section"> |
| <h1 align="center">Magick::Pixels</h1> |
| <p>The <i>Pixels</i> class provides efficient access to raw image |
| pixels. Image pixels (of type <a href="PixelPacket.html"><i>PixelPacket</i></a>) |
| may be accessed directly via the <i>Image Pixel Cache</i>. The image |
| pixel cache is a rectangular window (a view) into the actual image |
| pixels (which may be in memory, memory-mapped from a disk file, or |
| entirely on disk). Obtain existing image pixels via <i>get()</i>. |
| Create a new pixel region using <i>set().</i> </p> |
| <p>Depending on the capabilities of the operating system, and the |
| relationship of the window to the image, the pixel cache may be a copy |
| of the pixels in the selected window, or it may be the actual image |
| pixels. In any case calling <i>sync()</i> insures that the base image |
| is updated with the contents of the modified pixel cache. The method <i>decode()</i>supports |
| copying foreign pixel data formats into the pixel cache according to |
| the <i>QuantumTypes</i>. The method <i>encode()</i> supports copying |
| the pixels in the cache to a foreign pixel representation according to |
| the format specified by <i>QuantumTypes</i>. </p> |
| <p>Setting a view using the Pixels class does not cause the number of |
| references to the underlying image to be reduced to one. Therefore, in |
| order to ensure that only the current generation of the image is |
| modified, the Image's <a href="Image++.html#modifyImage">modifyImage()</a> |
| method should be invoked to reduce the reference count on the underlying |
| image to one. If this is not done, then it is possible for a previous |
| generation of the image to be modified due to the use of reference |
| counting when copying or constructing an Image. </p> |
| <p>The <i>PixelPacket</i>* returned by the <i>set</i> and <i>get</i> |
| methods, and the <i>IndexPacket</i>* returned by the <i>indexes</i> |
| method point to pixel data managed by the <i>Pixels</i> class. The <i>Pixels</i> |
| class is responsible for releasing resources associated with the pixel |
| view. This means that the pointer should never be passed to delete() or |
| free(). </p> |
| <p style="margin-bottom: 0cm;">The pixel view is a small image in which |
| the pixels may be accessed, addressed, and updated, as shown in the |
| following example, which produces an image similar to the one on the |
| right (minus lines and text): </p> |
| <p class="image"><img class="icon" src="Cache.png" name="Graphic1" align="bottom" width="254" border="0" /></p> |
| <div class="viewport"> |
| // Create base image |
| Image image(Geometry(254,218), "white"); |
| |
| |
| // Set the image type to TrueColor DirectClass representation. |
| image.type(TrueColorType); |
| // Ensure that there is only one reference to underlying image |
| // If this is not done, then image pixels will not be modified. |
| image.modifyImage(); |
| |
| // Allocate pixel view |
| Pixels view(image); |
| |
| // Set all pixels in region anchored at 38x36, with size 160x230 to green. |
| size_t columns = 196; size_t rows = 162; |
| Color green("green"); |
| PixelPacket *pixels = view.get(38,36,columns,rows); |
| for ( ssize_t row = 0; row < rows ; ++row ) |
| for ( ssize_t column = 0; column < columns ; ++column ) |
| *pixels++=green; |
| |
| // Save changes to image. |
| view.sync(); |
| |
| // Set all pixels in region anchored at 86x72, with size 108x67 to yellow. |
| columns = 108; rows = 67; |
| Color yellow("yellow"); |
| pixels = view.get(86,72,columns,rows); |
| for ( ssize_t row = 0; row < rows ; ++row ) |
| for ( ssize_t column = 0; column < columns ; ++column ) |
| *pixels++=yellow; |
| view.sync(); |
| |
| // Set pixel at position 108,94 to red |
| *(view.get(108,94,1,1)) = Color("red"); |
| |
| // Save changes to image. |
| view.sync(); |
| </div> |
| <p style="margin-bottom: 0cm;"><i>Pixels</i> supports the following |
| methods: </p> |
| <p align="center" style="margin-bottom: 0cm;"><b>Pixel Cache Methods</b></p> |
| <table width="100%" border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td> |
| <p align="center"><b>Method</b></p> |
| </td> |
| <td> |
| <p align="center"><b>Returns</b></p> |
| </td> |
| <td> |
| <p align="center"><b>Signature</b></p> |
| </td> |
| <td> |
| <p align="center"><b>Description</b></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="get"></a><font size="2">get</font></p> |
| </td> |
| <td> |
| <p><font size="2"><a href="PixelPacket.html">PixelPacket</a>*</font></p> |
| </td> |
| <td> |
| <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t |
| columns_, const size_t rows_</font></p> |
| </td> |
| <td> |
| <p><font size="2">Transfers read-write pixels from the image to |
| the pixel cache as defined by the specified rectangular region. |
| Modified pixels may be subsequently transferred back to the image |
| via <i>sync</i>. The value returned is intended for pixel access |
| only. It should never be deallocated.</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="getConst"></a><font size="2">getConst</font></p> |
| </td> |
| <td> |
| <p><font size="2">const <a href="PixelPacket.html">PixelPacket</a>*</font></p> |
| </td> |
| <td> |
| <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t |
| columns_, const size_t rows_</font></p> |
| </td> |
| <td> |
| <p><font size="2">Transfers read-only pixels from the image to |
| the pixel cache as defined by the specified rectangular region.</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="set"></a><font size="2">set</font></p> |
| </td> |
| <td> |
| <p><font size="2"><a href="PixelPacket.html">PixelPacket</a>*</font></p> |
| </td> |
| <td> |
| <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t |
| columns_, const size_t rows_</font></p> |
| </td> |
| <td> |
| <p><font size="2">Allocates a pixel cache region to store image |
| pixels as defined by the region rectangle. This area is |
| subsequently transferred from the pixel cache to the image via <i>sync</i>. |
| The value returned is intended for pixel access only. It should |
| never be deallocated.</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="sync"></a><font size="2">sync</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Transfers the image cache pixels to the image.</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="indexes"></a><font size="2">indexes</font></p> |
| </td> |
| <td> |
| <p><font size="2">IndexPacket*</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Returns the PsuedoColor pixel indexes |
| corresponding to the pixel region defined by the last <a href="Pixels.html#get">get</a> |
| , <a href="Pixels.html#getConst">getConst</a>, or <a href="Pixels.html#set">set</a> |
| call. Only valid for PseudoColor and CMYKA images. The pixel |
| indexes (an array of type <i>IndexPacket</i>, which is typedef <i>Quantum</i>, |
| which is itself typedef <i>unsigned char</i>, or <i>unsigned short</i>, |
| depending on the value of the <i>QuantumDepth </i>define) provide |
| the <span lang="en-US">colormap</span> index (see <a |
| href="Image++.html#colorMap">colorMap</a>) for each pixel in the |
| image. For CMYKA images, the indexes represent the black |
| channel. The value returned is intended for pixel access only. It |
| should never be deallocated.</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="x"></a><font size="2">x</font></p> |
| </td> |
| <td> |
| <p><font size="2">int</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Left ordinate of view</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="y"></a><font size="2">y</font></p> |
| </td> |
| <td> |
| <p><font size="2">int</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Top ordinate of view</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="columns"></a><font size="2">columns</font></p> |
| </td> |
| <td> |
| <p><font size="2">size_t</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Width of view</font></p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p align="center"><a name="rows"></a><font size="2">rows</font></p> |
| </td> |
| <td> |
| <p><font size="2">size_t</font></p> |
| </td> |
| <td> |
| <p><font size="2">void</font></p> |
| </td> |
| <td> |
| <p><font size="2">Height of view</font></p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </body> |
| </html> |
