Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / f41bcd129562336451b7b862b129b13f55ec5572 / . / www / Magick++ / Pixels.html
blob: 3b38b60c208aafa4235ec5485f09f6b7f61326d6 [file] [log] [blame]
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]4<head>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<title>Magick++ API: Working with Pixels </title>
Cristy3b0b58d2016-11-06 07:40:23 -0500[diff] [blame]7<link rel="stylesheet" href="https://www.imagemagick.org/Magick++/magick.css" type="text/css" />
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]8</head>
cristy8ee7f242013-06-20 16:08:44 +0000[diff] [blame]9<body>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]10<div class="doc-section">
11<h1 align="center">Magick::Pixels</h1>
12<p>The <i>Pixels</i> class provides efficient access to raw image
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]13pixels. Image pixels (of type <a href="https://www.imagemagick.org/Magick++/Quantum.html"><i>Quantum</i></a>)
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]14may be accessed directly via the <i>Image Pixel Cache</i>. The image
15pixel cache is a rectangular window (a view) into the actual image
16pixels (which may be in memory, memory-mapped from a disk file, or
17entirely on disk). Obtain existing image pixels via <i>get()</i>.
18Create a new pixel region using <i>set().</i> </p>
19<p>Depending on the capabilities of the operating system, and the
20relationship of the window to the image, the pixel cache may be a copy
21of the pixels in the selected window, or it may be the actual image
22pixels. In any case calling <i>sync()</i> insures that the base image
23is updated with the contents of the modified pixel cache. The method <i>decode()</i>supports
24copying foreign pixel data formats into the pixel cache according to
25the <i>QuantumTypes</i>. The method <i>encode()</i> supports copying
26the pixels in the cache to a foreign pixel representation according to
27the format specified by <i>QuantumTypes</i>. </p>
28<p>Setting a view using the Pixels class does not cause the number of
29references to the underlying image to be reduced to one. Therefore, in
30order to ensure that only the current generation of the image is
Cristy3b0b58d2016-11-06 07:40:23 -0500[diff] [blame]31modified, the Image's <a href="https://www.imagemagick.org/Magick++/Image++.html#modifyImage">modifyImage()</a>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]32method should be invoked to reduce the reference count on the underlying
33image to one. If this is not done, then it is possible for a previous
34generation of the image to be modified due to the use of reference
35counting when copying or constructing an Image. </p>
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]36<p>The <i>Quantum</i>* returned by the <i>set</i> and <i>get</i>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]37methods, and the <i>IndexPacket</i>* returned by the <i>indexes</i>
38method point to pixel data managed by the <i>Pixels</i> class. The <i>Pixels</i>
39class is responsible for releasing resources associated with the pixel
40view. This means that the pointer should never be passed to delete() or
41free(). </p>
42<p style="margin-bottom: 0cm;">The pixel view is a small image in which
43the pixels may be accessed, addressed, and updated, as shown in the
44following example, which produces an image similar to the one on the
45right (minus lines and text): </p>
cristy89cfbe92014-01-03 19:41:14 +0000[diff] [blame]46<p class="image"><img class="icon" src="Cache.png" name="Graphic1" align="bottom" width="254" border="0" /></p>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]47<div class="viewport">
48 // Create base image
49 Image image(Geometry(254,218), "white");
50
51
52 // Set the image type to TrueColor DirectClass representation.
53 image.type(TrueColorType);
54 // Ensure that there is only one reference to underlying image
55 // If this is not done, then image pixels will not be modified.
56 image.modifyImage();
57
58 // Allocate pixel view
59 Pixels view(image);
60
61 // Set all pixels in region anchored at 38x36, with size 160x230 to green.
62 size_t columns = 196; size_t rows = 162;
63 Color green("green");
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]64 Quantum *pixels = view.get(38,36,columns,rows);
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]65 for ( ssize_t row = 0; row &lt; rows ; ++row )
66 for ( ssize_t column = 0; column &lt; columns ; ++column )
67 *pixels++=green;
68
69 // Save changes to image.
70 view.sync();
71
72 // Set all pixels in region anchored at 86x72, with size 108x67 to yellow.
73 columns = 108; rows = 67;
74 Color yellow("yellow");
75 pixels = view.get(86,72,columns,rows);
76 for ( ssize_t row = 0; row &lt; rows ; ++row )
77 for ( ssize_t column = 0; column &lt; columns ; ++column )
78 *pixels++=yellow;
79 view.sync();
80
81 // Set pixel at position 108,94 to red
82 *(view.get(108,94,1,1)) = Color("red");
83
84 // Save changes to image.
85 view.sync();
86</div>
87<p style="margin-bottom: 0cm;"><i>Pixels</i> supports the following
88methods: </p>
89<p align="center" style="margin-bottom: 0cm;"><b>Pixel Cache Methods</b></p>
cristy89cfbe92014-01-03 19:41:14 +0000[diff] [blame]90<table width="100%" border="1" cellpadding="2" cellspacing="2">
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]91 <tbody>
92 <tr>
93 <td>
94 <p align="center"><b>Method</b></p>
95 </td>
96 <td>
97 <p align="center"><b>Returns</b></p>
98 </td>
99 <td>
100 <p align="center"><b>Signature</b></p>
101 </td>
102 <td>
103 <p align="center"><b>Description</b></p>
104 </td>
105 </tr>
106 <tr>
107 <td>
108 <p align="center"><a name="get"></a><font size="2">get</font></p>
109 </td>
110 <td>
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]111 <p><font size="2"><a href="https://www.imagemagick.org/Magick++/Quantum.html">Quantum</a>*</font></p>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]112 </td>
113 <td>
114 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
115columns_, const size_t rows_</font></p>
116 </td>
117 <td>
118 <p><font size="2">Transfers read-write pixels from the image to
119the pixel cache as defined by the specified rectangular region.
120 Modified pixels may be subsequently transferred back to the image
121 via <i>sync</i>. The value returned is intended for pixel access
122 only. It should never be deallocated.</font></p>
123 </td>
124 </tr>
125 <tr>
126 <td>
127 <p align="center"><a name="getConst"></a><font size="2">getConst</font></p>
128 </td>
129 <td>
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]130 <p><font size="2">const <a href="https://www.imagemagick.org/Magick++/Quantum.html">Quantum</a>*</font></p>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]131 </td>
132 <td>
133 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
134 columns_, const size_t rows_</font></p>
135 </td>
136 <td>
137 <p><font size="2">Transfers read-only pixels from the image to
138the pixel cache as defined by the specified rectangular region.</font></p>
139 </td>
140 </tr>
141 <tr>
142 <td>
143 <p align="center"><a name="set"></a><font size="2">set</font></p>
144 </td>
145 <td>
Cristyf41bcd12017-03-28 05:59:57 -0400[diff] [blame^]146 <p><font size="2"><a href="https://www.imagemagick.org/Magick++/Quantum.html">Quantum</a>*</font></p>
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]147 </td>
148 <td>
149 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
150 columns_, const size_t rows_</font></p>
151 </td>
152 <td>
153 <p><font size="2">Allocates a pixel cache region to store image
154 pixels as defined by the region rectangle.  This area is
155 subsequently transferred from the pixel cache to the image via <i>sync</i>.
156The value returned is intended for pixel access only. It should
157never be deallocated.</font></p>
158 </td>
159 </tr>
160 <tr>
161 <td>
162 <p align="center"><a name="sync"></a><font size="2">sync</font></p>
163 </td>
164 <td>
165 <p><font size="2">void</font></p>
166 </td>
167 <td>
168 <p><font size="2">void</font></p>
169 </td>
170 <td>
171 <p><font size="2">Transfers the image cache pixels to the image.</font></p>
172 </td>
173 </tr>
174 <tr>
175 <td>
176 <p align="center"><a name="indexes"></a><font size="2">indexes</font></p>
177 </td>
178 <td>
179 <p><font size="2">IndexPacket*</font></p>
180 </td>
181 <td>
182 <p><font size="2">void</font></p>
183 </td>
184 <td>
185 <p><font size="2">Returns the PsuedoColor pixel indexes
186 corresponding to the pixel region defined by the last <a href="Pixels.html#get">get</a>
187 , <a href="Pixels.html#getConst">getConst</a>, or <a href="Pixels.html#set">set</a>
188 call. Only valid for PseudoColor and CMYKA images. The pixel
189 indexes (an array of type <i>IndexPacket</i>, which is typedef <i>Quantum</i>,
190which is itself typedef <i>unsigned char</i>, or <i>unsigned short</i>,
191depending on the value of the <i>QuantumDepth </i>define) provide
192the <span lang="en-US">colormap</span> index (see <a
Cristy3b0b58d2016-11-06 07:40:23 -0500[diff] [blame]193 href="https://www.imagemagick.org/Magick++/Image++.html#colorMap">colorMap</a>) for each pixel in the
cristy417eeb12013-07-28 18:48:22 +0000[diff] [blame]194image. For CMYKA images, the indexes represent the black
195channel. The value returned is intended for pixel access only. It
196should never be deallocated.</font></p>
197 </td>
198 </tr>
199 <tr>
200 <td>
201 <p align="center"><a name="x"></a><font size="2">x</font></p>
202 </td>
203 <td>
204 <p><font size="2">int</font></p>
205 </td>
206 <td>
207 <p><font size="2">void</font></p>
208 </td>
209 <td>
210 <p><font size="2">Left ordinate of view</font></p>
211 </td>
212 </tr>
213 <tr>
214 <td>
215 <p align="center"><a name="y"></a><font size="2">y</font></p>
216 </td>
217 <td>
218 <p><font size="2">int</font></p>
219 </td>
220 <td>
221 <p><font size="2">void</font></p>
222 </td>
223 <td>
224 <p><font size="2">Top ordinate of view</font></p>
225 </td>
226 </tr>
227 <tr>
228 <td>
229 <p align="center"><a name="columns"></a><font size="2">columns</font></p>
230 </td>
231 <td>
232 <p><font size="2">size_t</font></p>
233 </td>
234 <td>
235 <p><font size="2">void</font></p>
236 </td>
237 <td>
238 <p><font size="2">Width of view</font></p>
239 </td>
240 </tr>
241 <tr>
242 <td>
243 <p align="center"><a name="rows"></a><font size="2">rows</font></p>
244 </td>
245 <td>
246 <p><font size="2">size_t</font></p>
247 </td>
248 <td>
249 <p><font size="2">void</font></p>
250 </td>
251 <td>
252 <p><font size="2">Height of view</font></p>
253 </td>
254 </tr>
255 </tbody>
cristy89cfbe92014-01-03 19:41:14 +0000[diff] [blame]256</table>
257</div>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]258</body>
259</html>