|
|
<?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="Quantum.html"><i>Quantum</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>Quantum</i>* returned by the <i>set</i> and <i>get</i>
|
|
|
methods, and the <i>void</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">
|
|
|
#include <Magick++.h>
|
|
|
#include <iostream>
|
|
|
|
|
|
using namespace std;
|
|
|
using namespace Magick;
|
|
|
int main(int argc,char **argv)
|
|
|
{
|
|
|
InitializeMagick(*argv);
|
|
|
|
|
|
// 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");
|
|
|
Quantum *pixels = view.get(38,36,columns,rows);
|
|
|
for ( ssize_t row = 0; row < rows ; ++row )
|
|
|
for ( ssize_t column = 0; column < columns ; ++column )
|
|
|
{
|
|
|
*pixels++=QuantumRange*green.quantumRed();
|
|
|
*pixels++=QuantumRange*green.quantumGreen();
|
|
|
*pixels++=QuantumRange*green.quantumBlue();
|
|
|
}
|
|
|
|
|
|
// 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++=QuantumRange*yellow.quantumRed();
|
|
|
*pixels++=QuantumRange*yellow.quantumGreen();
|
|
|
*pixels++=QuantumRange*yellow.quantumBlue();
|
|
|
}
|
|
|
view.sync();
|
|
|
|
|
|
// Set pixel at position 108,94 to red
|
|
|
Color red("red");
|
|
|
pixels = view.get(108,94,1,1);
|
|
|
*pixels++=QuantumRange*red.quantumRed();
|
|
|
*pixels++=QuantumRange*red.quantumGreen();
|
|
|
*pixels++=QuantumRange*red.quantumBlue();
|
|
|
|
|
|
// Save changes to image.
|
|
|
view.sync();
|
|
|
image.write( "logo.png" );
|
|
|
}
|
|
|
</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="Quantum.html">Quantum</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="Quantum.html">Quantum</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="Quantum.html">Quantum</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">void*</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>void</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>
|
