| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| <html> |
| <head> |
| |
| <meta http-equiv="CONTENT-TYPE" content="text/html; charset=ibm437"> |
| <title>Magick::Pixels Class</title> |
| |
| <meta name="GENERATOR" content="OpenOffice.org 1.0 (Win32)"> |
| |
| <meta name="AUTHOR" content="Bob Friesenhahn"> |
| |
| <meta name="CREATED" content="20020805;15302080"> |
| |
| <meta name="CHANGEDBY" content="Bob Friesenhahn"> |
| |
| <meta name="CHANGED" content="20020805;15341200"> |
| |
| <meta name="DESCRIPTION" content="Class to access raw image pixels."> |
| |
| <meta name="KEYWORDS" content="ImageMagick,Pixel,Magick++"> |
| |
| <style> |
| <!-- |
| TD P { color: #000000 } |
| H1 { color: #000000 } |
| P { color: #000000 } |
| A:link { color: #0000ff } |
| A:visited { color: #ff0000 } |
| --> |
| </style> |
| </head> |
| <body lang="en-US" text="#000000" link="#0000ff" vlink="#ff0000" |
| bgcolor="#ffffff"> |
| <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): <br> |
| <br> |
| </p> |
| <table width="100%" border="0" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td> |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000">// Create base image</font></font></font> |
| <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> Image image(Geometry(254,218), "white");</font></font></font> |
| </p> |
| |
| <p><font size="2"></font></p> |
| <p> <font face="Courier New,Courier"><font color="#ff0000"><font |
| size="-1"> // Set the image type to TrueColor DirectClass |
| representation.</font></font></font><br> |
| <font size="-1"><span |
| style="color: rgb(0, 0, 153); font-family: courier new,courier,monospace;"> |
| image.type(TrueColorType</span></font><font size="-1"><span |
| style="color: rgb(0, 0, 153); font-family: courier new,courier,monospace;">);</span></font><br> |
| </p> |
| |
| <p><font size="2"><font face="Courier New, Courier"> <font |
| color="#ff0000">// Ensure that there is only one reference to |
| underlying image</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#ff0000"> // If this is not done, then image pixels will |
| not be modified.</font></font></font><br> |
| <font size="2"><font face="Courier New, Courier"> <font |
| color="#000099">image.modifyImage();<br> |
| </font></font></font></p> |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Allocate pixel |
| view</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> Pixels view(image);</font></font></font> </p> |
| |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Set all pixels |
| in region anchored at 38x36, with size 160x230 to green.</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> unsigned int columns = 196; unsigned int rows = |
| 162;</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> Color green("green");</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> PixelPacket *pixels = |
| view.get(38,36,columns,rows);</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> for ( int row = 0; row < rows ; ++row )</font></font></font> |
| <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> for ( int column = 0; column < columns ; |
| ++column )</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> *pixels++=green;</font></font></font> </p> |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Save changes to |
| image.<br> |
| </font></font></font><font size="2"></font><font size="2"><font |
| face="Courier New, Courier"><font color="#000099"> view.sync();</font></font></font> |
| </p> |
| |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Set all pixels |
| in region anchored at 86x72, with size 108x67 to yellow.</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> columns = 108; rows = 67;</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> Color yellow("yellow");</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> pixels = view.get(86,72,columns,rows);</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> for ( int row = 0; row < rows ; ++row )</font></font></font> |
| <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> for ( int column = 0; column < columns ; |
| ++column )</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> *pixels++=yellow;</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> view.sync();</font></font></font> </p> |
| |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Set pixel at |
| position 108,94 to red</font></font></font> <br> |
| <font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> *(view.get(108,94,1,1)) = Color("red");</font></font></font> </p> |
| <p><font size="2"><font face="Courier New, Courier"><font |
| color="#000099"> </font><font color="#ff0000"> // Save changes to |
| image.<br> |
| </font></font></font><font size="2"><font |
| face="Courier New, Courier"><font color="#000099"> view.sync();<br> |
| <br> |
| </font></font></font></p> |
| </td> |
| <td> |
| <p><img src="Cache.png" name="Graphic1" align="bottom" width="254" |
| height="218" border="0"></p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <p style="margin-bottom: 0cm;"><i>Pixels</i> supports the following |
| methods: <br> |
| <br> |
| </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 int x_, const int y_, const unsigned |
| const int columns_, const unsigned int 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 int x_, const int y_, const unsigned int |
| columns_, const unsigned int 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 int x_, const int y_, const unsigned int |
| columns_, const unsigned int 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="#get">get</a> |
| , <a href="#getConst">getConst</a>, or <a href="#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">unsigned int</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">unsigned int</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> |
| <p><br> |
| <br> |
| </p> |
| </body> |
| </html> |