1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>cache - Get or Set Image Pixels</title>
<link rel="stylesheet" type="text/css" href="../magick.css">
</head>
<body marginheight="1" marginwidth="1" topmargin="1" leftmargin="1">
<a name="top"></a>
<table border="0" cellpadding="0" cellspacing="0" summary="Masthead" width="100%">
<tbody>
<tr>
<td bgcolor="#003399" width="25%" height="118" background="../../images/background.gif"><a href="http://www.imagemagick.org/"><img src="../../images/script.gif" width="278" height="118" border="0" alt="" /></a></td>
<td bgcolor="#003399" width="60%" height="118" background="../../images/background.gif"><a href="http://www.networkeleven.com/direct.php?magick_all"><img src="../../images/promote.png" border="0" width="186" height="52" vspace="29" alt="Powered by NetworkEleven" /></a></td>
<td bgcolor="#003399" width="114" height="118" align="right"><img src="../../images/sprite.png" width="114" height="118" alt="" /></td>
<td bgcolor="#003399" width="114" height="118" align="right"><a href="http://www.imagemagick.net"><img src="../../images/logo.png" width="114" height="118" border="0" alt="ImageMagick logo" /></a></td>
</tr></tbody></table>
<table align="left" border="0" cellpadding="2" cellspacing="2" summary="Navigation buttons" width="20%">
<tr>
<td>
<form target="_self" action="../../index.html"><input type="submit" title="ImageMagick Home" value=" Home" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td>
<td>
<form target="_self" action="../../www/apis.html"><input type="submit" title="ImageMagick API" value=" API " style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td>
<td>
<form target="_self" action="../../www/archives.html"><input type="submit" title="ImageMagick Download" value="Download" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold"></form></td></tr></table>
<div align="right" style="margin-top:3px; padding-right:4px">
<form action="http://studio.imagemagick.org/Sage/scripts/Sage.cgi"><input type="TEXT" name="query" size="32" maxlength="255"> <input type="SUBMIT" name="sa" value="Search" style="background-color: #1947A3; background-image:url('../../../images/background.gif'); bgcolor:#003399; color:#fbc713; font-weight:bold"></form></div>
<table align="left" border="0" cellpadding="10" cellspacing="0" style="margin-top:-17px" width="100%">
<tr>
<td>
<P><a name="__index__"></a></P>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#function_descriptions">FUNCTION DESCRIPTIONS</a></li>
<ul>
<li><a href="#acquireimagepixels">AcquireImagePixels</a></li>
<li><a href="#acquireonepixel">AcquireOnePixel</a></li>
<li><a href="#destroycacheinfo">DestroyCacheInfo</a></li>
<li><a href="#destroyimagepixels">DestroyImagePixels</a></li>
<li><a href="#getimagepixels">GetImagePixels</a></li>
<li><a href="#getimagevirtualpixelmethod">GetImageVirtualPixelMethod</a></li>
<li><a href="#getindexes">GetIndexes</a></li>
<li><a href="#getonepixel">GetOnePixel</a></li>
<li><a href="#getpixels">GetPixels</a></li>
<li><a href="#modifycache">ModifyCache</a></li>
<li><a href="#referencecache">ReferenceCache</a></li>
<li><a href="#setimagepixels">SetImagePixels</a></li>
<li><a href="#setimagevirtualpixelmethod">SetImageVirtualPixelMethod</a></li>
</ul>
</ul>
<!-- INDEX END -->
<hr />
<P>
</P>
<h1><a name="name">NAME</a></h1>
<P>cache - Get or Set Image Pixels</P>
<P>
</P>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<P>const PixelPacket * <strong>AcquireImagePixels</strong>( const Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows, ExceptionInfo *exception );</P>
<P>PixelPacket <strong>AcquireOnePixel</strong>( const Image image, const long x, const long y, ExceptionInfo exception );</P>
<P>void <strong>DestroyCacheInfo</strong>( Cache cache );</P>
<P>void <strong>DestroyImagePixels</strong>( Image *image );</P>
<P>PixelPacket * <strong>GetImagePixels</strong>( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );</P>
<P>VirtualPixelMethod <strong>GetImageVirtualPixelMethod</strong>( const Image *image );</P>
<P>IndexPacket * <strong>GetIndexes</strong>( const Image *image );</P>
<P>PixelPacket * <strong>GetOnePixel</strong>( const Image image, const long x, const long y );</P>
<P>PixelPacket * <strong>GetPixels</strong>( const Image image );</P>
<P>MagickBooleanType <strong>ModifyCache</strong>( Image *image, const unsigned long nexus );</P>
<P>Cache <strong>ReferenceCache</strong>( Cache cache_info );</P>
<P>PixelPacket * <strong>SetImagePixels</strong>( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );</P>
<P>MagickBooleanType <strong>SetImageVirtualPixelMethod</strong>( const Image *image, const VirtualPixelMethod method );</P>
<P>MagickBooleanType <strong>SyncImagePixels</strong>( Image *image );</P>
<P>
</P>
<hr />
<h1><a name="function_descriptions">FUNCTION DESCRIPTIONS</a></h1>
<P>
</P>
<h2><a name="acquireimagepixels">AcquireImagePixels</a></h2>
<blockquote>AcquireImagePixels() acquires pixels from the in-memory or disk pixel cache as defined by the geometry parameters. A pointer to the pixel is returned if the pixels are transferred, otherwise a NULL is returned. If you plan to modify the pixels, use GetImagePixels ( ) instead. </blockquote><blockquote>The format of the AcquireImagePixels() method is: </blockquote><blockquote>const <A HREF="types.html#PixelPacket">PixelPacket</A> *AcquireImagePixels ( const <A HREF="types.html#Image">Image</A> *image, const long x, const long y, const unsigned long columns, const unsigned long rows, <A HREF="types.html#ExceptionInfo">ExceptionInfo</A> *exception ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong><a name="item_o_image_3a">image:</a></strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong><a name="item_o_x_2cy_2ccolumns_2crows_3a">x,y,columns,rows:</a></strong><br />
</dt>
<DD>
These values define the perimeter of a region of pixels.
</dd>
<P></P>
<dt><strong><a name="item_o_exception_3a">exception:</a></strong><br />
</dt>
<DD>
Return any errors or warnings in this structure.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="acquireonepixel">AcquireOnePixel</a></h2>
<blockquote>AcquireOnePixel() returns a single pixel at the specified ( x, y ) location. The image background color is returned if an error occurs. If you plan to modify the pixel, use GetOnePixel ( ) instead. </blockquote><blockquote>The format of the AcquireOnePixel() method is: </blockquote><blockquote><A HREF="types.html#PixelPacket">PixelPacket</A> AcquireOnePixel ( const <A HREF="types.html#Image">Image</A> image, const long x, const long y, <A HREF="types.html#ExceptionInfo">ExceptionInfo</A> exception ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong><a name="item_o_pixels_3a">pixels:</a></strong><br />
</dt>
<DD>
<code>AcquireOnePixel()</code> returns a pixel at the specified (x,y) location.
</dd>
<P></P>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong><a name="item_o_x_2cy_3a">x,y:</a></strong><br />
</dt>
<DD>
These values define the location of the pixel to return.
</dd>
<P></P>
<dt><strong>exception:</strong><br />
</dt>
<DD>
Return any errors or warnings in this structure.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="destroycacheinfo">DestroyCacheInfo</a></h2>
<blockquote>DestroyCacheInfo() deallocates memory associated with the pixel cache. </blockquote><blockquote>The format of the DestroyCacheInfo() method is: </blockquote><blockquote>void DestroyCacheInfo ( <A HREF="types.html#Cache">Cache</A> cache ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong><a name="item_o_cache_3a">cache:</a></strong><br />
</dt>
<DD>
Specifies a pointer to a Cache structure.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="destroyimagepixels">DestroyImagePixels</a></h2>
<blockquote>DestroyImagePixels() deallocates memory associated with the pixel cache. </blockquote><blockquote>The format of the DestroyImagePixels() method is: </blockquote><blockquote>void DestroyImagePixels ( <A HREF="types.html#Image">Image</A> *image ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="getimagepixels">GetImagePixels</a></h2>
<blockquote>GetImagePixels() gets pixels from the in-memory or disk pixel cache as defined by the geometry parameters. A pointer to the pixels is returned if the pixels are transferred, otherwise a NULL is returned. </blockquote><blockquote>The format of the GetImagePixels() method is: </blockquote><blockquote><A HREF="types.html#PixelPacket">PixelPacket</A> *GetImagePixels ( <A HREF="types.html#Image">Image</A> *image, const long x, const long y, const unsigned long columns, const unsigned long rows ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong>x,y,columns,rows:</strong><br />
</dt>
<DD>
These values define the perimeter of a region of pixels.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="getimagevirtualpixelmethod">GetImageVirtualPixelMethod</a></h2>
<blockquote>GetImageVirtualPixelMethod() gets the "virtual pixels" method for the image. A virtual pixel is any pixel access that is outside the boundaries of the image cache. </blockquote><blockquote>The format of the GetImageVirtualPixelMethod() method is: </blockquote><blockquote><A HREF="types.html#VirtualPixelMethod">VirtualPixelMethod</A> GetImageVirtualPixelMethod ( const <A HREF="types.html#Image">Image</A> *image ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="getindexes">GetIndexes</a></h2>
<blockquote>GetIndexes() returns the indexes associated with the last call to SetImagePixels ( ) or GetImagePixels ( ) . </blockquote><blockquote>The format of the GetIndexes() method is: </blockquote><blockquote>IndexPacket *GetIndexes ( const <A HREF="types.html#Image">Image</A> *image ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong><a name="item_o_indexes_3a">indexes:</a></strong><br />
</dt>
<DD>
<code>GetIndexes()</code> returns the indexes associated with the last call to <code>SetImagePixels()</code> or GetImagePixels().
</dd>
<P></P>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="getonepixel">GetOnePixel</a></h2>
<blockquote>GetOnePixel() returns a single pixel at the specified ( x, y ) location. The image background color is returned if an error occurs. </blockquote><blockquote>The format of the GetOnePixel() method is: </blockquote><blockquote><A HREF="types.html#PixelPacket">PixelPacket</A> *GetOnePixel ( const <A HREF="types.html#Image">Image</A> image, const long x, const long y ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong>x,y:</strong><br />
</dt>
<DD>
These values define the location of the pixel to return.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="getpixels">GetPixels</a></h2>
<blockquote>GetPixels() returns the pixels associated with the last call to SetImagePixels ( ) or GetImagePixels ( ) . </blockquote><blockquote>The format of the GetPixels() method is: </blockquote><blockquote><A HREF="types.html#PixelPacket">PixelPacket</A> *GetPixels ( const <A HREF="types.html#Image">Image</A> image ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>pixels:</strong><br />
</dt>
<DD>
<code>GetPixels()</code> returns the pixels associated with the last call to <code>SetImagePixels()</code> or GetImagePixels().
</dd>
<P></P>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="modifycache">ModifyCache</a></h2>
<blockquote>ModifyCache() ensures that there is only a single reference to the pixel cache to be modified, updating the provided cache pointer to point to a clone of the original pixel cache if necessary. </blockquote><P>The format of the ModifyCache method is:</P>
<blockquote>MagickBooleanType ModifyCache ( <A HREF="types.html#Image">Image</A> *image, const unsigned long nexus ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong><a name="item_o_nexus_3a">nexus:</a></strong><br />
</dt>
<DD>
specifies which cache nexus to acquire.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="referencecache">ReferenceCache</a></h2>
<blockquote>ReferenceCache() increments the reference count associated with the pixel cache returning a pointer to the cache. </blockquote><P>The format of the ReferenceCache method is:</P>
<blockquote><A HREF="types.html#Cache">Cache</A> ReferenceCache ( <A HREF="types.html#Cache">Cache</A> cache_info ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong><a name="item_o_cache_info_3a">cache_info:</a></strong><br />
</dt>
<DD>
The cache_info.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="setimagepixels">SetImagePixels</a></h2>
<blockquote>SetImagePixels() allocates an area to store image pixels as defined by the region rectangle and returns a pointer to the area. This area is subsequently transferred from the pixel cache with SyncImagePixels ( ) . A pointer to the pixels is returned if the pixels are transferred, otherwise a NULL is returned. </blockquote><blockquote>The format of the SetImagePixels() method is: </blockquote><blockquote><A HREF="types.html#PixelPacket">PixelPacket</A> *SetImagePixels ( <A HREF="types.html#Image">Image</A> *image, const long x, const long y, const unsigned long columns, const unsigned long rows ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>pixels:</strong><br />
</dt>
<DD>
SetImagePixels returns a pointer to the pixels if they are transferred, otherwise a NULL is returned.
</dd>
<P></P>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong>x,y,columns,rows:</strong><br />
</dt>
<DD>
These values define the perimeter of a region of pixels.
</dd>
<P></P></dl>
<P>
</P>
<h2><a name="setimagevirtualpixelmethod">SetImageVirtualPixelMethod</a></h2>
<blockquote>SetImageVirtualPixelMethod() sets the "virtual pixels" method for the image. A virtual pixel is any pixel access that is outside the boundaries of the image cache. </blockquote><blockquote>The format of the SetImageVirtualPixelMethod() method is: </blockquote><blockquote>MagickBooleanType SetImageVirtualPixelMethod ( const <A HREF="types.html#Image">Image</A> *image, const <A HREF="types.html#VirtualPixelMethod">VirtualPixelMethod</A> method ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
<P></P>
<dt><strong><a name="item_o_method_3a">method:</a></strong><br />
</dt>
<DD>
choose from these access types:
</dd>
<P></P></dl>
<pre>
EdgeVirtualPixelMethod: the edge pixels of the image extend
infinitely. Any pixel outside the image is assigned the same value as
the pixel at the edge closest to it.
TileVirtualPixelMethod: the image extends periodically or tiled. The
pixels wrap around the edges of the image.
MirrorVirtualPixelMethod: mirror the image at the boundaries.
ConstantVirtualPixelMethod: every value outside the image is a
constant as defines by the pixel parameter.
=head2 SyncImagePixels</pre>
<blockquote>SyncImagePixels() saves the image pixels to the in-memory or disk cache. The method returns MagickTrue if the pixel region is synced, otherwise MagickFalse. </blockquote><blockquote>The format of the SyncImagePixels() method is: </blockquote><blockquote>MagickBooleanType SyncImagePixels ( <A HREF="types.html#Image">Image</A> *image ); </blockquote><P>A description of each parameter follows:</P>
<dl>
<dt><strong>image:</strong><br />
</dt>
<DD>
The image.
</dd>
</dl>
<HR>
<a href="#top"><img src="../../../images/top.gif" border=0 width=42 height=42 align="right" alt="Top of page"></a>
<form action="http://studio.imagemagick.org/magick/" style="margin-top:5px">
<input type="submit" title="Help!" value="Help!" style="background-image:url('../../../images/background.gif'); color:#fbc713; font-weight:bold">
<small>"Image manipulation software that works like magick"</small>
</form></td>
</tr></table>
</body>
</html>
|
