283 lines
9.4 KiB
HTML
283 lines
9.4 KiB
HTML
<?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>
|