341 lines
13 KiB
HTML
341 lines
13 KiB
HTML
<!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++">
|
||
<link rel=stylesheet type=text/css href="magick.css">
|
||
|
||
</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"> size_t columns = 196; size_t 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 ( ssize_t row = 0; row < rows ; ++row )</font></font></font>
|
||
<br>
|
||
<font size="2"><font face="Courier New, Courier"><font
|
||
color="#000099"> for ( ssize_t 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 ( ssize_t row = 0; row < rows ; ++row )</font></font></font>
|
||
<br>
|
||
<font size="2"><font face="Courier New, Courier"><font
|
||
color="#000099"> for ( ssize_t 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 ssize_t x_, const ssize_t y_, const unsigned
|
||
const int 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="#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">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>
|
||
<p><br>
|
||
<br>
|
||
</p>
|
||
</body>
|
||
</html>
|