Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 0293af1156aec0320715965cd84653d752de1f38 / . / www / Magick++ / Pixels.html
blob: bd64c4c02f164453a444b977a19c235fb7ee3573 [file] [log] [blame]
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2<html>
3<head>
4
5 <meta http-equiv="CONTENT-TYPE" content="text/html; charset=ibm437">
6 <title>Magick::Pixels Class</title>
7
8 <meta name="GENERATOR" content="OpenOffice.org 1.0 (Win32)">
9
10 <meta name="AUTHOR" content="Bob Friesenhahn">
11
12 <meta name="CREATED" content="20020805;15302080">
13
14 <meta name="CHANGEDBY" content="Bob Friesenhahn">
15
16 <meta name="CHANGED" content="20020805;15341200">
17
18 <meta name="DESCRIPTION" content="Class to access raw image pixels.">
19
20 <meta name="KEYWORDS" content="ImageMagick,Pixel,Magick++">
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]21<link rel=stylesheet type=text/css href="magick.css">
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]22
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]23</head>
24<body lang="en-US" text="#000000" link="#0000ff" vlink="#ff0000"
25 bgcolor="#ffffff">
26<h1 align="center">Magick::Pixels</h1>
27<p>The <i>Pixels</i> class provides efficient access to raw image
28pixels. Image pixels (of type <a href="PixelPacket.html"><i>PixelPacket</i></a>)
29may be accessed directly via the <i>Image Pixel Cache</i>. The image
30pixel cache is a rectangular window (a view) into the actual image
31pixels (which may be in memory, memory-mapped from a disk file, or
32entirely on disk). Obtain existing image pixels via <i>get()</i>.
33Create a new pixel region using <i>set().</i> </p>
34<p>Depending on the capabilities of the operating system, and the
35relationship of the window to the image, the pixel cache may be a copy
36of the pixels in the selected window, or it may be the actual image
37pixels. In any case calling <i>sync()</i> insures that the base image
38is updated with the contents of the modified pixel cache. The method <i>decode()</i>supports
39copying foreign pixel data formats into the pixel cache according to
40the <i>QuantumTypes</i>. The method <i>encode()</i> supports copying
41the pixels in the cache to a foreign pixel representation according to
42the format specified by <i>QuantumTypes</i>. </p>
43<p>Setting a view using the Pixels class does not cause the number of
44references to the underlying image to be reduced to one. Therefore, in
45order to ensure that only the current generation of the image is
46modified, the Image's <a href="Image.html#modifyImage">modifyImage()</a>
47method should be invoked to reduce the reference count on the underlying
48image to one. If this is not done, then it is possible for a previous
49generation of the image to be modified due to the use of reference
50counting when copying or constructing an Image. </p>
51<p>The <i>PixelPacket</i>* returned by the <i>set</i> and <i>get</i>
52methods, and the <i>IndexPacket</i>* returned by the <i>indexes</i>
53method point to pixel data managed by the <i>Pixels</i> class. The <i>Pixels</i>
54class is responsible for releasing resources associated with the pixel
55view. This means that the pointer should never be passed to delete() or
56free(). </p>
57<p style="margin-bottom: 0cm;">The pixel view is a small image in which
58the pixels may be accessed, addressed, and updated, as shown in the
59following example, which produces an image similar to the one on the
60right (minus lines and text): <br>
61<br>
62</p>
63<table width="100%" border="0" cellpadding="2" cellspacing="2">
64 <tbody>
65 <tr>
66 <td>
67 <p><font size="2"><font face="Courier New, Courier"><font
68 color="#000099">   </font><font color="#ff0000">// Create base image</font></font></font>
69 <br>
70 <font size="2"><font face="Courier New, Courier"><font
71 color="#000099">   Image image(Geometry(254,218), "white");</font></font></font>
72 </p>
73
74 <p><font size="2"></font></p>
75 <p>   <font face="Courier New,Courier"><font color="#ff0000"><font
76 size="-1">  // Set the image type to TrueColor DirectClass
77representation.</font></font></font><br>
78 <font size="-1"><span
79 style="color: rgb(0, 0, 153); font-family: courier new,courier,monospace;"> 
80 image.type(TrueColorType</span></font><font size="-1"><span
81 style="color: rgb(0, 0, 153); font-family: courier new,courier,monospace;">);</span></font><br>
82 </p>
83
84 <p><font size="2"><font face="Courier New, Courier">   <font
85 color="#ff0000">// Ensure that there is only one reference to
86underlying image</font></font></font> <br>
87 <font size="2"><font face="Courier New, Courier"><font
88 color="#ff0000">   // If this is not done, then image pixels will
89not be modified.</font></font></font><br>
90 <font size="2"><font face="Courier New, Courier">   <font
91 color="#000099">image.modifyImage();<br>
92 </font></font></font></p>
93 <p><font size="2"><font face="Courier New, Courier"><font
94 color="#000099">  </font><font color="#ff0000"> // Allocate pixel
95view</font></font></font> <br>
96 <font size="2"><font face="Courier New, Courier"><font
97 color="#000099">   Pixels view(image);</font></font></font> </p>
98
99 <p><font size="2"><font face="Courier New, Courier"><font
100 color="#000099">  </font><font color="#ff0000"> // Set all pixels
101in region anchored at 38x36, with size 160x230 to green.</font></font></font> <br>
102 <font size="2"><font face="Courier New, Courier"><font
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]103 color="#000099">   size_t columns = 196; size_t rows =
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]104162;</font></font></font> <br>
105 <font size="2"><font face="Courier New, Courier"><font
106 color="#000099">   Color green("green");</font></font></font> <br>
107 <font size="2"><font face="Courier New, Courier"><font
108 color="#000099">   PixelPacket *pixels =
109view.get(38,36,columns,rows);</font></font></font> <br>
110 <font size="2"><font face="Courier New, Courier"><font
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]111 color="#000099">   for ( ssize_t row = 0; row &lt; rows ; ++row )</font></font></font>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]112 <br>
113 <font size="2"><font face="Courier New, Courier"><font
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]114 color="#000099">     for ( ssize_t column = 0; column &lt; columns ;
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]115++column )</font></font></font> <br>
116 <font size="2"><font face="Courier New, Courier"><font
117 color="#000099">       *pixels++=green;</font></font></font> </p>
118 <p><font size="2"><font face="Courier New, Courier"><font
119 color="#000099">  </font><font color="#ff0000"> // Save changes to
120image.<br>
121 </font></font></font><font size="2"></font><font size="2"><font
122 face="Courier New, Courier"><font color="#000099">   view.sync();</font></font></font>
123 </p>
124
125 <p><font size="2"><font face="Courier New, Courier"><font
126 color="#000099">  </font><font color="#ff0000"> // Set all pixels
127in region anchored at 86x72, with size 108x67 to yellow.</font></font></font> <br>
128 <font size="2"><font face="Courier New, Courier"><font
129 color="#000099">   columns = 108; rows = 67;</font></font></font> <br>
130 <font size="2"><font face="Courier New, Courier"><font
131 color="#000099">   Color yellow("yellow");</font></font></font> <br>
132 <font size="2"><font face="Courier New, Courier"><font
133 color="#000099">   pixels = view.get(86,72,columns,rows);</font></font></font> <br>
134 <font size="2"><font face="Courier New, Courier"><font
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]135 color="#000099">   for ( ssize_t row = 0; row &lt; rows ; ++row )</font></font></font>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]136 <br>
137 <font size="2"><font face="Courier New, Courier"><font
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]138 color="#000099">      for ( ssize_t column = 0; column &lt; columns ;
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]139++column )</font></font></font> <br>
140 <font size="2"><font face="Courier New, Courier"><font
141 color="#000099">         *pixels++=yellow;</font></font></font> <br>
142 <font size="2"><font face="Courier New, Courier"><font
143 color="#000099">    view.sync();</font></font></font> </p>
144
145 <p><font size="2"><font face="Courier New, Courier"><font
146 color="#000099">  </font><font color="#ff0000"> // Set pixel at
147position 108,94 to red</font></font></font> <br>
148 <font size="2"><font face="Courier New, Courier"><font
149 color="#000099">   *(view.get(108,94,1,1)) = Color("red");</font></font></font> </p>
150 <p><font size="2"><font face="Courier New, Courier"><font
151 color="#000099">  </font><font color="#ff0000"> // Save changes to
152image.<br>
153 </font></font></font><font size="2"><font
154 face="Courier New, Courier"><font color="#000099">   view.sync();<br>
155 <br>
156 </font></font></font></p>
157 </td>
158 <td>
159 <p><img src="Cache.png" name="Graphic1" align="bottom" width="254"
160 height="218" border="0"></p>
161 </td>
162 </tr>
163 </tbody>
164</table>
165<p style="margin-bottom: 0cm;"><i>Pixels</i> supports the following
166methods: <br>
167<br>
168</p>
169<p align="center" style="margin-bottom: 0cm;"><b>Pixel Cache Methods</b></p>
170<table width="100%" border="1" cellpadding="2" cellspacing="2">
171 <tbody>
172 <tr>
173 <td>
174 <p align="center"><b>Method</b></p>
175 </td>
176 <td>
177 <p align="center"><b>Returns</b></p>
178 </td>
179 <td>
180 <p align="center"><b>Signature</b></p>
181 </td>
182 <td>
183 <p align="center"><b>Description</b></p>
184 </td>
185 </tr>
186 <tr>
187 <td>
188 <p align="center"><a name="get"></a><font size="2">get</font></p>
189 </td>
190 <td>
191 <p><font size="2"><a href="PixelPacket.html">PixelPacket</a>*</font></p>
192 </td>
193 <td>
cristy72da67d2013-02-24 21:40:48 +0000[diff] [blame]194 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
195columns_, const size_t rows_</font></p>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]196 </td>
197 <td>
198 <p><font size="2">Transfers read-write pixels from the image to
199the pixel cache as defined by the specified rectangular region.
200 Modified pixels may be subsequently transferred back to the image
201 via <i>sync</i>. The value returned is intended for pixel access
202 only. It should never be deallocated.</font></p>
203 </td>
204 </tr>
205 <tr>
206 <td>
207 <p align="center"><a name="getConst"></a><font size="2">getConst</font></p>
208 </td>
209 <td>
210 <p><font size="2">const <a href="PixelPacket.html">PixelPacket</a>*</font></p>
211 </td>
212 <td>
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]213 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
214 columns_, const size_t rows_</font></p>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]215 </td>
216 <td>
217 <p><font size="2">Transfers read-only pixels from the image to
218the pixel cache as defined by the specified rectangular region.</font></p>
219 </td>
220 </tr>
221 <tr>
222 <td>
223 <p align="center"><a name="set"></a><font size="2">set</font></p>
224 </td>
225 <td>
226 <p><font size="2"><a href="PixelPacket.html">PixelPacket</a>*</font></p>
227 </td>
228 <td>
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]229 <p><font size="2">const ssize_t x_, const ssize_t y_, const size_t
230 columns_, const size_t rows_</font></p>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]231 </td>
232 <td>
233 <p><font size="2">Allocates a pixel cache region to store image
234 pixels as defined by the region rectangle.  This area is
235 subsequently transferred from the pixel cache to the image via <i>sync</i>.
236The value returned is intended for pixel access only. It should
237never be deallocated.</font></p>
238 </td>
239 </tr>
240 <tr>
241 <td>
242 <p align="center"><a name="sync"></a><font size="2">sync</font></p>
243 </td>
244 <td>
245 <p><font size="2">void</font></p>
246 </td>
247 <td>
248 <p><font size="2">void</font></p>
249 </td>
250 <td>
251 <p><font size="2">Transfers the image cache pixels to the image.</font></p>
252 </td>
253 </tr>
254 <tr>
255 <td>
256 <p align="center"><a name="indexes"></a><font size="2">indexes</font></p>
257 </td>
258 <td>
259 <p><font size="2">IndexPacket*</font></p>
260 </td>
261 <td>
262 <p><font size="2">void</font></p>
263 </td>
264 <td>
265 <p><font size="2">Returns the PsuedoColor pixel indexes
cristy72da67d2013-02-24 21:40:48 +0000[diff] [blame]266 corresponding to the pixel region defined by the last <a href="Pixels.html#get">get</a>
267 , <a href="Pixels.html#getConst">getConst</a>, or <a href="Pixels.html#set">set</a>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]268 call. Only valid for PseudoColor and CMYKA images. The pixel
269 indexes (an array of type <i>IndexPacket</i>, which is typedef <i>Quantum</i>,
270which is itself typedef <i>unsigned char</i>, or <i>unsigned short</i>,
271depending on the value of the <i>QuantumDepth </i>define) provide
272the <span lang="en-US">colormap</span> index (see <a
273 href="Image.html#colorMap">colorMap</a>) for each pixel in the
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]274image. For CMYKA images, the indexes represent the black
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]275channel. The value returned is intended for pixel access only. It
276should never be deallocated.</font></p>
277 </td>
278 </tr>
279 <tr>
280 <td>
281 <p align="center"><a name="x"></a><font size="2">x</font></p>
282 </td>
283 <td>
284 <p><font size="2">int</font></p>
285 </td>
286 <td>
287 <p><font size="2">void</font></p>
288 </td>
289 <td>
290 <p><font size="2">Left ordinate of view</font></p>
291 </td>
292 </tr>
293 <tr>
294 <td>
295 <p align="center"><a name="y"></a><font size="2">y</font></p>
296 </td>
297 <td>
298 <p><font size="2">int</font></p>
299 </td>
300 <td>
301 <p><font size="2">void</font></p>
302 </td>
303 <td>
304 <p><font size="2">Top ordinate of view</font></p>
305 </td>
306 </tr>
307 <tr>
308 <td>
309 <p align="center"><a name="columns"></a><font size="2">columns</font></p>
310 </td>
311 <td>
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]312 <p><font size="2">size_t</font></p>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]313 </td>
314 <td>
315 <p><font size="2">void</font></p>
316 </td>
317 <td>
318 <p><font size="2">Width of view</font></p>
319 </td>
320 </tr>
321 <tr>
322 <td>
323 <p align="center"><a name="rows"></a><font size="2">rows</font></p>
324 </td>
325 <td>
cristyd99b0962010-05-29 23:14:26 +0000[diff] [blame]326 <p><font size="2">size_t</font></p>
cristy3ed852e2009-09-05 21:47:34 +0000[diff] [blame]327 </td>
328 <td>
329 <p><font size="2">void</font></p>
330 </td>
331 <td>
332 <p><font size="2">Height of view</font></p>
333 </td>
334 </tr>
335 </tbody>
336</table>
337<p><br>
338<br>
339</p>
340</body>
341</html>