FILE COMPARISON
Produced: 2/18/2011 1:22:16 AM
   
Mode:  All Lines  
Left base folder: C:\Documents and Settings\krollins\My Documents\Admin\OpenSource\eRCP\eSWT\eSWT-1.2.orig  
Right base folder: C:\Documents and Settings\krollins\My Documents\Admin\OpenSource\eRCP\eSWT\eSWT-1.2.today  
   
File: org.eclipse.ercp.swt.core.win\common-native\api\Image.h  
1 /******************************************************************************* = 1 /*******************************************************************************
2 * Copyright (c) 2000, 2005 IBM Corporation and others.   2 * Copyright (c) 2000, 2005 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials   3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0   4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at   5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html   6 * http://www.eclipse.org/legal/epl-v10.html
7 *   7 *
8 * Contributors:   8 * Contributors:
9 *     IBM Corporation - initial API and implementation   9 *     IBM Corporation - initial API and implementation
10 *******************************************************************************/   10 *******************************************************************************/
11     11  
    <> 12 /*******************************************************************************
      13 * Additions/modifications to this source file by Oracle America, Inc. 2011
      14 *******************************************************************************/
      15  
12 #ifndef __UGL_IMAGE_H__ = 16 #ifndef __UGL_IMAGE_H__
13 #define __UGL_IMAGE_H__   17 #define __UGL_IMAGE_H__
14     18  
15 #include "UGL_Error.h"   19 #include "UGL_Error.h"
16 #include "UGLTypes.h"   20 #include "UGLTypes.h"
17     21  
18 #ifdef __cplusplus   22 #ifdef __cplusplus
19 extern "C" {   23 extern "C" {
20 #endif   24 #endif
21     25  
22     26  
23 /**   27 /**
24 * Frees the platform resources associated with the image identified by   28 * Frees the platform resources associated with the image identified by
25 * <code>handle</code>.   29 * <code>handle</code>.
26 *   30 *
27 * @ingroup Image   31 * @ingroup Image
28 *   32 *
29 * @param handle image handle   33 * @param handle image handle
30 * @param error the error status of the call   34 * @param error the error status of the call
31 */   35 */
32 void Image_Dispose(UGL_Int handle, UGL_Error error);   36 void Image_Dispose(UGL_Int handle, UGL_Error error);
33     37  
34 /**   38 /**
35 * Returns the position and size of the image identified by <code>handle</code>.   39 * Returns the position and size of the image identified by <code>handle</code>.
36 *   40 *
37 * @ingroup Image   41 * @ingroup Image
38 *   42 *
39 * @param handle image handle   43 * @param handle image handle
40 * @param returnX (out) the x component of the rect   44 * @param returnX (out) the x component of the rect
41 * @param returnY (out) the y component of the rect   45 * @param returnY (out) the y component of the rect
42 * @param returnWidth (out) the width component of the rect   46 * @param returnWidth (out) the width component of the rect
43 * @param returnHeight (out) the height component of the rect   47 * @param returnHeight (out) the height component of the rect
44 * @param error the error status of the call   48 * @param error the error status of the call
45 */   49 */
46 void Image_GetBounds(UGL_Int handle, UGL_Int* returnX, UGL_Int* returnY, UGL_Int* returnWidth, UGL_Int* returnHeight, UGL_Error error);   50 void Image_GetBounds(UGL_Int handle, UGL_Int* returnX, UGL_Int* returnY, UGL_Int* returnWidth, UGL_Int* returnHeight, UGL_Error error);
47     51  
48 /**   52 /**
49 * Returns the color depth of the image identified by <code>handle</code>.   53 * Returns the color depth of the image identified by <code>handle</code>.
50 * The supported color depths are 1, 2, 4, 8, 16, 24 and 32 bit. The   54 * The supported color depths are 1, 2, 4, 8, 16, 24 and 32 bit. The
51 * returned depth must be one of the values supported by UGL. In the case   55 * returned depth must be one of the values supported by UGL. In the case
52 * of 3, 5, 6 or 7 bit GIFs the returned depth should reflect the actual   56 * of 3, 5, 6 or 7 bit GIFs the returned depth should reflect the actual
53 * "color resolution" as defined in the GIF89a spec.   57 * "color resolution" as defined in the GIF89a spec.
54 *   58 *
55 * @ingroup Image   59 * @ingroup Image
56 *   60 *
57 * @param handle image handle   61 * @param handle image handle
58 * @param error the error status of the call   62 * @param error the error status of the call
59 *   63 *
60 * @return color depth in bits per pixel   64 * @return color depth in bits per pixel
61 */   65 */
62 UGL_Int Image_GetDepth(UGL_Int handle, UGL_Error error);   66 UGL_Int Image_GetDepth(UGL_Int handle, UGL_Error error);
63     67  
64 /**   68 /**
65 * Creates a new image from the supplied pixel data. Each pixel is an   69 * Creates a new image from the supplied pixel data. Each pixel is an
66 * index into a color palette. The color palette is supplied in the   70 * index into a color palette. The color palette is supplied in the
67 * indexed color arrays. The palette may not use all possible color   71 * indexed color arrays. The palette may not use all possible color
68 * values . In other words the number of elements may be less than   72 * values . In other words the number of elements may be less than
69 * (2^depth). Supported color depths are 1, 2, 4 and 8 bits per pixel.   73 * (2^depth). Supported color depths are 1, 2, 4 and 8 bits per pixel.
70 * <p>   74 * <p>
71 * May result in the following errors:   75 * May result in the following errors:
72 * <ul>   76 * <ul>
73 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   77 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
74 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>   78 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>
75 * </ul>   79 * </ul>
76 * </p>   80 * </p>
77 *   81 *
78 * @ingroup Image   82 * @ingroup Image
79 *   83 *
80 * @see Image_GetDepth   84 * @see Image_GetDepth
81 *   85 *
82 * @param deviceHandle the device handle   86 * @param deviceHandle the device handle
83 * @param width width of the new image in pixels   87 * @param width width of the new image in pixels
84 * @param height height of the new image   88 * @param height height of the new image
85 * @param imageData the pixel data. Each byte holds one or more pixels. An   89 * @param imageData the pixel data. Each byte holds one or more pixels. An
86 *                  8 bit per pixel image has one pixel per byte, a 4 bpp image has exactly   90 *                  8 bit per pixel image has one pixel per byte, a 4 bpp image has exactly
87 *                  2 pixels per byte etc. The most significant bit of each byte corresponds   91 *                  2 pixels per byte etc. The most significant bit of each byte corresponds
88 *                  to the leftmost pixel on a scanline. A scanline may have unused bits if   92 *                  to the leftmost pixel on a scanline. A scanline may have unused bits if
89 *                  the color depth is less than 8 bpp.   93 *                  the color depth is less than 8 bpp.
90 * @param bytesPerLine length in bytes of a scan line. The number of bytes   94 * @param bytesPerLine length in bytes of a scan line. The number of bytes
91 *                     per scan line may be greater than required for the actual number of   95 *                     per scan line may be greater than required for the actual number of
92 *                     pixels. Excess bytes are unused.   96 *                     pixels. Excess bytes are unused.
93 * @param depth color depth of the image data, in number of bits per pixel.   97 * @param depth color depth of the image data, in number of bits per pixel.
94 *              One of 1, 2, 4, 8. It is acceptable for an implementation to create an   98 *              One of 1, 2, 4, 8. It is acceptable for an implementation to create an
95 *              image with a different depth if platform limitations do not allow the   99 *              image with a different depth if platform limitations do not allow the
96 *              original color depth. The depth has to remain the same throughout the   100 *              original color depth. The depth has to remain the same throughout the
97 *              life of the image.   101 *              life of the image.
98 * @param indexedReds red components of indexed color palette.   102 * @param indexedReds red components of indexed color palette.
99 * @param indexedGreens green components of indexed color palette.   103 * @param indexedGreens green components of indexed color palette.
100 * @param indexedBlues blue components of indexed color palette.   104 * @param indexedBlues blue components of indexed color palette.
101 * @param paletteSize number of entries in the color palette arrays. This   105 * @param paletteSize number of entries in the color palette arrays. This
102 *                    may be less than the maximum number allowed by the color depth.   106 *                    may be less than the maximum number allowed by the color depth.
103 * @param transparentPixel palette index of the transparent pixel. Value of   107 * @param transparentPixel palette index of the transparent pixel. Value of
104 *                         <code>-1</code> means no transparency.   108 *                         <code>-1</code> means no transparency.
105 * @param error the error status of the call   109 * @param error the error status of the call
106 *   110 *
107 * @return handle to the new image. 0 if no image could be created using the   111 * @return handle to the new image. 0 if no image could be created using the
108 *         supplied parameters.   112 *         supplied parameters.
109 */   113 */
110 UGL_Int Image_NewFromByteData(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_ByteArray imageData, UGL_Int bytesPerLine, UGL_Int depth, UGL_ByteArray indexedReds, UGL_ByteArray indexedGreens, UGL_ByteArray indexedBlues, UGL_Int paletteSize, UGL_Int transparentPixel, UGL_Error error);   114 UGL_Int Image_NewFromByteData(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_ByteArray imageData, UGL_Int bytesPerLine, UGL_Int depth, UGL_ByteArray indexedReds, UGL_ByteArray indexedGreens, UGL_ByteArray indexedBlues, UGL_Int paletteSize, UGL_Int transparentPixel, UGL_Error error);
111     115  
112 /**   116 /**
113 * Creates a new image using the supplied raw data.   117 * Creates a new image using the supplied raw data.
114 * <p>   118 * <p>
115 * May result in the following errors:   119 * May result in the following errors:
116 * <ul>   120 * <ul>
117 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   121 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
118 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>   122 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>
119 * </ul>   123 * </ul>
120 * </p>   124 * </p>
121 *   125 *
122 * @ingroup Image   126 * @ingroup Image
123 *   127 *
124 * @param deviceHandle the device/display handle   128 * @param deviceHandle the device/display handle
125 * @param data the raw image data, including image header   129 * @param data the raw image data, including image header
126 * @param length number of bytes in the data array   130 * @param length number of bytes in the data array
127 * @param error the error status of the call   131 * @param error the error status of the call
128 *   132 *
129 * @return handle to the new image or 0 if no image could be created   133 * @return handle to the new image or 0 if no image could be created
130 *         from the supplied data.   134 *         from the supplied data.
131 */   135 */
132 UGL_Int Image_NewFromFileData(UGL_Int deviceHandle, UGL_ByteArray data, UGL_Int length, UGL_Error error);   136 UGL_Int Image_NewFromFileData(UGL_Int deviceHandle, UGL_ByteArray data, UGL_Int length, UGL_Error error);
133     137  
134 /**   138 /**
135 * Creates a new image from the supplied pixel data. Each pixel is a direct   139 * Creates a new image from the supplied pixel data. Each pixel is a direct
136 * color RGB value. Supported color depths are 16, 24 and 32 bits per pixel.   140 * color RGB value. Supported color depths are 16, 24 and 32 bits per pixel.
137 * For 16 bit depth the RGB bits are layed out as 5-6-5 bits for red, green   141 * For 16 bit depth the RGB bits are layed out as 5-6-5 bits for red, green
138 * and blue respectively, 24 bit depth uses 8-8-8 bits and no alpha channel.   142 * and blue respectively, 24 bit depth uses 8-8-8 bits and no alpha channel.
139 * 32 bit color depth uses 8-8-8 bits and the most significant byte for the   143 * 32 bit color depth uses 8-8-8 bits and the most significant byte for the
140 * alpha channel for an ARGB pixel layout. For 32 bit pixel data the alpha   144 * alpha channel for an ARGB pixel layout. For 32 bit pixel data the alpha
141 * channel byte is ignored if either one of the   145 * channel byte is ignored if either one of the
142 * <code>transparentColor</code>, <code>globalAlpha</code> or   146 * <code>transparentColor</code>, <code>globalAlpha</code> or
143 * <code>alphaData</code> is specified. Only one of the three transparency/   147 * <code>alphaData</code> is specified. Only one of the three transparency/
144 * alpha arguments may be specified at a time.   148 * alpha arguments may be specified at a time.
145 * <p>   149 * <p>
146 * May result in the following errors:   150 * May result in the following errors:
147 * <ul>   151 * <ul>
148 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   152 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
149 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>   153 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>
150 * </ul>   154 * </ul>
151 * </p>   155 * </p>
152 *   156 *
153 * @ingroup Image   157 * @ingroup Image
154 *   158 *
155 * @param deviceHandle the device handle   159 * @param deviceHandle the device handle
156 * @param width width of the new image in pixels   160 * @param width width of the new image in pixels
157 * @param height height of the new image   161 * @param height height of the new image
158 * @param imageData pixel data. Each int contains one pixel regardless of   162 * @param imageData pixel data. Each int contains one pixel regardless of
159 *                  color depth. E.g., a 16 bit pixel is packed in the two least   163 *                  color depth. E.g., a 16 bit pixel is packed in the two least
160 *                  significant bytes of each int.   164 *                  significant bytes of each int.
161 * @param depth color depth of the image data, in number of bits per pixel.   165 * @param depth color depth of the image data, in number of bits per pixel.
162 *              One of 16, 24, 32. It is acceptable for an implementation to create an   166 *              One of 16, 24, 32. It is acceptable for an implementation to create an
163 *              image with a different depth if platform limitations do not allow the   167 *              image with a different depth if platform limitations do not allow the
164 *              original color depth. The depth has to remain the same throughout the   168 *              original color depth. The depth has to remain the same throughout the
165 *              life of the image.   169 *              life of the image.
166 * @param transparentColor value of the transparent color. The transparent   170 * @param transparentColor value of the transparent color. The transparent
167 *                         color is specified in the same bit format as the image data. Value of   171 *                         color is specified in the same bit format as the image data. Value of
168 *                         <code>-1</code> means no transparency.   172 *                         <code>-1</code> means no transparency.
169 * @param globalAlpha global alpha value. Each pixel will be blended using   173 * @param globalAlpha global alpha value. Each pixel will be blended using
170 *                    this alpha value. Value of <code>-1</code> means no global alpha value.   174 *                    this alpha value. Value of <code>-1</code> means no global alpha value.
171 * @param alphaData alpha data of the image. Each pixel may have an alpha   175 * @param alphaData alpha data of the image. Each pixel may have an alpha
172 *                  value ranging from 0 to 255. 0 means fully transparent, 255 means fully   176 *                  value ranging from 0 to 255. 0 means fully transparent, 255 means fully
173 *                  opaque. May be <code>null</code>.   177 *                  opaque. May be <code>null</code>.
174 * @param error the error status of the call   178 * @param error the error status of the call
175 *   179 *
176 * @return handle to the new image. 0 if no image could be created using the   180 * @return handle to the new image. 0 if no image could be created using the
177 *         supplied parameters.   181 *         supplied parameters.
178 */   182 */
179 UGL_Int Image_NewFromIntData(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_IntArray imageData, UGL_Int depth, UGL_Int transparentColor, UGL_Int globalAlpha, UGL_ByteArray alphaData, UGL_Error error);   183 UGL_Int Image_NewFromIntData(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_IntArray imageData, UGL_Int depth, UGL_Int transparentColor, UGL_Int globalAlpha, UGL_ByteArray alphaData, UGL_Error error);
180     184  
181 /**   185 /**
182 * Creates a new, empty image with the given dimensions.   186 * Creates a new, empty image with the given dimensions.
183 * <p>   187 * <p>
184 * Image will be filled with the provided fill color which   188 * Image will be filled with the provided fill color which
185 * is in 0xAARRGGBB format.   189 * is in 0xAARRGGBB format.
186 * </p>   190 * </p>
187 *   191 *
188 * @ingroup Image   192 * @ingroup Image
189 *   193 *
190 * @param deviceHandle the device/display handle   194 * @param deviceHandle the device/display handle
191 * @param width width of the new image   195 * @param width width of the new image
192 * @param height height of the new image   196 * @param height height of the new image
193 * @param fillColor value with which to fill the image in 0xAARRGGBB format.   197 * @param fillColor value with which to fill the image in 0xAARRGGBB format.
194 * @param error the error status of the call   198 * @param error the error status of the call
195 *   199 *
196 * @return handle to the new image   200 * @return handle to the new image
197 */   201 */
198 UGL_Int Image_NewFromSize(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_Int fillColor, UGL_Error error);   202 UGL_Int Image_NewFromSize(UGL_Int deviceHandle, UGL_Int width, UGL_Int height, UGL_Int fillColor, UGL_Error error);
199     203  
    <> 204  
      205 UGL_Int Image_NewFromSystemResource(UGL_Int deviceHandle, UGL_Int identifier, UGL_Error uglError);
      206  
200 /** = 207 /**
201 * Creates a new graphics context on the image identified by   208 * Creates a new graphics context on the image identified by
202 * <code>handle</code>   209 * <code>handle</code>
203 *   210 *
204 * @ingroup Image   211 * @ingroup Image
205 *   212 *
206 * @param handle image handle   213 * @param handle image handle
207 * @param error the error status of the call   214 * @param error the error status of the call
208 *   215 *
209 * @return handle to the new graphics context   216 * @return handle to the new graphics context
210 */   217 */
211 UGL_Int Image_NewGraphics(UGL_Int handle, UGL_Error error);   218 UGL_Int Image_NewGraphics(UGL_Int handle, UGL_Error error);
212     219  
213     220  
214     221  
215 /**   222 /**
216 * Returns the direct color model masks of the image identified by   223 * Returns the direct color model masks of the image identified by
217 * <code>handle</code>.   224 * <code>handle</code>.
218 * <p>   225 * <p>
219 * Color masks are used to access individual color components of a   226 * Color masks are used to access individual color components of a
220 * direct color pixel. There is one mask for each of the red, green,   227 * direct color pixel. There is one mask for each of the red, green,
221 * blue and alpha component of a pixel. The masks for a 32 bit   228 * blue and alpha component of a pixel. The masks for a 32 bit
222 * per pixel image for example might be red=0xFF, green=0x00FF,   229 * per pixel image for example might be red=0xFF, green=0x00FF,
223 * blue=0x0000FF, alpha=0x000000FF.   230 * blue=0x0000FF, alpha=0x000000FF.
224 * </p>   231 * </p>
225 * <p>   232 * <p>
226 * Example: Given a pixel value, <code>int pixel</code>, returned by   233 * Example: Given a pixel value, <code>int pixel</code>, returned by
227 * <code>Image_GetPixelsHighColor()</code> the red color component can be extracted   234 * <code>Image_GetPixelsHighColor()</code> the red color component can be extracted
228 * as follows.   235 * as follows.
229 * <pre>   236 * <pre>
230 * int[] masks = Image_GetDirectPaletteMasks(imageHandle);   237 * int[] masks = Image_GetDirectPaletteMasks(imageHandle);
231 * int redMask = masks[OS.PALETTE_MASK_RED];   238 * int redMask = masks[OS.PALETTE_MASK_RED];
232 * int redShift = getMaskShift(redMask);   239 * int redShift = getMaskShift(redMask);
233 * int red = (pixel & redMask) >>> redShift;   240 * int red = (pixel & redMask) >>> redShift;
234 * </pre>   241 * </pre>
235 * Where getMaskShift is defined separately to return the bit shift   242 * Where getMaskShift is defined separately to return the bit shift
236 * necessary to shift the masked bits to the low order bits.   243 * necessary to shift the masked bits to the low order bits.
237 * <pre>   244 * <pre>
238 * int getMaskShift(int colorMask) {   245 * int getMaskShift(int colorMask) {
239 * int shiftCount = 0;   246 * int shiftCount = 0;
240 * if (mask == 0) return 0;   247 * if (mask == 0) return 0;
241 * while (((mask >> shiftCount) & 0x1) == 0) {   248 * while (((mask >> shiftCount) & 0x1) == 0) {
242 * shiftCount++;   249 * shiftCount++;
243 * }   250 * }
244 * return shiftCount;   251 * return shiftCount;
245 * }   252 * }
246 * </pre>   253 * </pre>
247 * </p>   254 * </p>
248 * <p>   255 * <p>
249 * May result in the following error:   256 * May result in the following error:
250 * <ul>   257 * <ul>
251 * <li>ERROR_UNSUPPORTED_DEPTH - direct palette not supported for this color depth</li>   258 * <li>ERROR_UNSUPPORTED_DEPTH - direct palette not supported for this color depth</li>
252 * </ul>   259 * </ul>
253 * </p>   260 * </p>
254 *   261 *
255 * @ingroup Image   262 * @ingroup Image
256 *   263 *
257 * @see Image_IsDirect   264 * @see Image_IsDirect
258 *   265 *
259 * @param handle image handle   266 * @param handle image handle
260 * @param returnRedMask (out) the red component of the palette mask   267 * @param returnRedMask (out) the red component of the palette mask
261 * @param returnGreenMask (out) the green component of the palette mask   268 * @param returnGreenMask (out) the green component of the palette mask
262 * @param returnBlueMask (out) the blue component of the palette mask   269 * @param returnBlueMask (out) the blue component of the palette mask
263 * @param returnAlphaMask (out) the alpha component of the palette mask   270 * @param returnAlphaMask (out) the alpha component of the palette mask
264 * @param error the error status of the call   271 * @param error the error status of the call
265 */   272 */
266 void Image_GetDirectPaletteMasks(UGL_Int handle, UGL_Int* returnRedMask, UGL_Int* returnGreenMask, UGL_Int* returnBlueMask, UGL_Int* returnAlphaMask, UGL_Error error);   273 void Image_GetDirectPaletteMasks(UGL_Int handle, UGL_Int* returnRedMask, UGL_Int* returnGreenMask, UGL_Int* returnBlueMask, UGL_Int* returnAlphaMask, UGL_Error error);
267     274  
268 /**   275 /**
269 * Returns the indexed palette of the image identified by <code>handle</code>.   276 * Returns the indexed palette of the image identified by <code>handle</code>.
270 * The red, green and blue arrays must be big enough to hold all color   277 * The red, green and blue arrays must be big enough to hold all color
271 * indices for the image's color depth.   278 * indices for the image's color depth.
272 * <p>   279 * <p>
273 * May result in the following error:   280 * May result in the following error:
274 * <ul>   281 * <ul>
275 * <li>ERROR_UNSUPPORTED_DEPTH - indexed palette not supported for this color depth</li>   282 * <li>ERROR_UNSUPPORTED_DEPTH - indexed palette not supported for this color depth</li>
276 * </ul>   283 * </ul>
277 * </p>   284 * </p>
278 *   285 *
279 * @ingroup Image   286 * @ingroup Image
280 *   287 *
281 * @see Image_IsDirect   288 * @see Image_IsDirect
282 *   289 *
283 * @param handle image handle   290 * @param handle image handle
284 * @param red red component of palette colors   291 * @param red red component of palette colors
285 * @param green green component of palette colors   292 * @param green green component of palette colors
286 * @param blue blue component of palette colors   293 * @param blue blue component of palette colors
287 * @param error the error status of the call   294 * @param error the error status of the call
288 */   295 */
289 void Image_GetIndexedPalette(UGL_Int handle, UGL_ByteArray red, UGL_ByteArray green, UGL_ByteArray blue, UGL_Error error);   296 void Image_GetIndexedPalette(UGL_Int handle, UGL_ByteArray red, UGL_ByteArray green, UGL_ByteArray blue, UGL_Error error);
290     297  
291 /**   298 /**
292 * Returns pixel data for images with more than 8 bit per pixel color depth.   299 * Returns pixel data for images with more than 8 bit per pixel color depth.
293 * Each int array element holds exactly one pixel, compatible with the image's   300 * Each int array element holds exactly one pixel, compatible with the image's
294 * color model. The color components of each pixel are layed out to match the   301 * color model. The color components of each pixel are layed out to match the
295 * direct palette masks returned by <code>Image_GetDirectPaletteMasks()</code>.   302 * direct palette masks returned by <code>Image_GetDirectPaletteMasks()</code>.
296 * <p>   303 * <p>
297 * There is no scanline pad. Therefore, the size of the returned array equals   304 * There is no scanline pad. Therefore, the size of the returned array equals
298 * the image width multiplied with the image height.   305 * the image width multiplied with the image height.
299 * </p>   306 * </p>
300 * <p>   307 * <p>
301 * May result in the following error:   308 * May result in the following error:
302 * <ul>   309 * <ul>
303 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   310 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
304 * </ul>    311 * </ul> 
305 * </p>   312 * </p>
306 *   313 *
307 * @param handle image handle   314 * @param handle image handle
308 * @param pixels pixel data of entire image   315 * @param pixels pixel data of entire image
309 * @param length size, in pixels, of the <code>pixels</code> argument   316 * @param length size, in pixels, of the <code>pixels</code> argument
310 * @param uglError the error status of the call   317 * @param uglError the error status of the call
311 * @see #Image_GetDirectPaletteMasks()   318 * @see #Image_GetDirectPaletteMasks()
312 */   319 */
313 void Image_GetPixelsHighColor(UGL_Int handle, UGL_IntArray pixels, UGL_Int length, UGL_Error uglError);   320 void Image_GetPixelsHighColor(UGL_Int handle, UGL_IntArray pixels, UGL_Int length, UGL_Error uglError);
314     321  
315 /**   322 /**
316 * Returns pixel data for images with 8 bit per pixel color depth or less.   323 * Returns pixel data for images with 8 bit per pixel color depth or less.
317 * Each byte array element holds one or more pixels but it never holds   324 * Each byte array element holds one or more pixels but it never holds
318 * pixels of two different scanlines. An 8 bpp image has one pixel per byte,   325 * pixels of two different scanlines. An 8 bpp image has one pixel per byte,
319 * a 4 bpp image has up to 2 pixels per byte etc. Each pixel is an index   326 * a 4 bpp image has up to 2 pixels per byte etc. Each pixel is an index
320 * into the image's indexed color palette (Image_GetIndexedPalette).   327 * into the image's indexed color palette (Image_GetIndexedPalette).
321 * <p>   328 * <p>
322 * The most significant bit of each scanline in the returned buffer   329 * The most significant bit of each scanline in the returned buffer
323 * corresponds to the leftmost pixel on the displayed scanline. Each   330 * corresponds to the leftmost pixel on the displayed scanline. Each
324 * scanline in the returned buffer may have unused bits, depending on color   331 * scanline in the returned buffer may have unused bits, depending on color
325 * depth and image width. For example in a 3x3 image with 4 bpp color depth   332 * depth and image width. For example in a 3x3 image with 4 bpp color depth
326 * the 4 least significant bits of the last byte on each scanline will be   333 * the 4 least significant bits of the last byte on each scanline will be
327 * unused. In addition, each scanline may be padded with unused bytes. The   334 * unused. In addition, each scanline may be padded with unused bytes. The
328 * number of bytes per scanline is determined by dividing the image size   335 * number of bytes per scanline is determined by dividing the image size
329 * (the size of the returned array) by the number of scanlines (height    336 * (the size of the returned array) by the number of scanlines (height 
330 * returned by Image_GetBounds()).   337 * returned by Image_GetBounds()).
331 * </p>   338 * </p>
332 * <p>   339 * <p>
333 * May result in the following error:   340 * May result in the following error:
334 * <ul>   341 * <ul>
335 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   342 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
336 * </ul>   343 * </ul>
337 * </p>   344 * </p>
338 *   345 *
339 * @param handle image handle   346 * @param handle image handle
340 * @param pixels pixel data of entire image   347 * @param pixels pixel data of entire image
341 * @param length size, in bytes, of the <code>pixels</code> argument   348 * @param length size, in bytes, of the <code>pixels</code> argument
342 * @param uglError the error status of the call   349 * @param uglError the error status of the call
343 * @see #Image_GetIndexedPalette()   350 * @see #Image_GetIndexedPalette()
344 * @see #Image_GetSize()   351 * @see #Image_GetSize()
345 */   352 */
346 void Image_GetPixelsLowColor(UGL_Int handle, UGL_ByteArray pixels, UGL_Int length, UGL_Error uglError);   353 void Image_GetPixelsLowColor(UGL_Int handle, UGL_ByteArray pixels, UGL_Int length, UGL_Error uglError);
347     354  
348 /**   355 /**
349 * Returns the size in bytes needed to store all pixels of the image   356 * Returns the size in bytes needed to store all pixels of the image
350 * identified by <code>handle</code>. This should be the equivalent of   357 * identified by <code>handle</code>. This should be the equivalent of
351 * bytes per scanline * image height. The returned value must match the   358 * bytes per scanline * image height. The returned value must match the
352 * size of the byte array returned by <code>Image_GetPixelsLowColor</code>   359 * size of the byte array returned by <code>Image_GetPixelsLowColor</code>
353 * and the size of the int array returned by <code>Image_GetPixelsHighColor</code>.   360 * and the size of the int array returned by <code>Image_GetPixelsHighColor</code>.
354 * <p>   361 * <p>
355 * Note that a scanline may be padded with unused bytes as described in   362 * Note that a scanline may be padded with unused bytes as described in
356 * <code>Image_GetPixelsLowColor()</code>.   363 * <code>Image_GetPixelsLowColor()</code>.
357 * </p>   364 * </p>
358 *   365 *
359 * @param handle image handle   366 * @param handle image handle
360 * @param error the error status of the call   367 * @param error the error status of the call
361 * @return the size in bytes needed to store all pixels of the image.   368 * @return the size in bytes needed to store all pixels of the image.
362 * @see #Image_GetPixelsLowColor()   369 * @see #Image_GetPixelsLowColor()
363 * @see #Image_GetPixelsHighColor()   370 * @see #Image_GetPixelsHighColor()
364 */   371 */
365 UGL_Int Image_GetSize(UGL_Int handle, UGL_Error error);   372 UGL_Int Image_GetSize(UGL_Int handle, UGL_Error error);
366     373  
367 /**   374 /**
368 * Returns the transparent color of the image identified by   375 * Returns the transparent color of the image identified by
369 * <code>handle</code> or -1 if the image has no transparency.   376 * <code>handle</code> or -1 if the image has no transparency.
370 *   377 *
371 * @ingroup Image   378 * @ingroup Image
372 *   379 *
373 * @see Image_GetDirectPaletteMasks   380 * @see Image_GetDirectPaletteMasks
374 * @see Image_GetIndexedPalette   381 * @see Image_GetIndexedPalette
375 * @see Image_IsDirect   382 * @see Image_IsDirect
376 *   383 *
377 * @param handle image handle   384 * @param handle image handle
378 * @param error the error status of the call   385 * @param error the error status of the call
379 *   386 *
380 * @return the transparent color of the image. This is a palette index   387 * @return the transparent color of the image. This is a palette index
381 *         in the case of paletted images or an RGB color value for direct   388 *         in the case of paletted images or an RGB color value for direct
382 *         color images (Image_IsDirect). For RGB values the format matches   389 *         color images (Image_IsDirect). For RGB values the format matches
383 *         that returned by <code>Image_GetDirectPaletteMasks()</code>   390 *         that returned by <code>Image_GetDirectPaletteMasks()</code>
384 */   391 */
385 UGL_Int Image_GetTransparentColor(UGL_Int handle, UGL_Error error);   392 UGL_Int Image_GetTransparentColor(UGL_Int handle, UGL_Error error);
386     393  
387 /**   394 /**
388 * Returns whether the image identified by <code>handle</code> uses   395 * Returns whether the image identified by <code>handle</code> uses
389 * a direct color model or a paletted color model.   396 * a direct color model or a paletted color model.
390 *   397 *
391 * @ingroup Image   398 * @ingroup Image
392 *   399 *
393 * @see Image_GetDirectPaletteMasks   400 * @see Image_GetDirectPaletteMasks
394 * @see Image_GetIndexedPalette   401 * @see Image_GetIndexedPalette
395 *   402 *
396 * @param handle image handle   403 * @param handle image handle
397 * @param error the error status of the call   404 * @param error the error status of the call
398 *   405 *
399 * @return true - the image uses a direct color model. Pixel values are   406 * @return true - the image uses a direct color model. Pixel values are
400 *         RGB values (Red, Green, Blue) with optional alpha channel.   407 *         RGB values (Red, Green, Blue) with optional alpha channel.
401 *         false - the image uses a paletted color mode. Pixel values are indices   408 *         false - the image uses a paletted color mode. Pixel values are indices
402 *         into a color palette.   409 *         into a color palette.
403 */   410 */
404 UGL_Boolean Image_IsDirect(UGL_Int handle, UGL_Error error);   411 UGL_Boolean Image_IsDirect(UGL_Int handle, UGL_Error error);
405     412  
406 /**   413 /**
407 * Creates a new image loaded from the specified file.   414 * Creates a new image loaded from the specified file.
408 * <p>   415 * <p>
409 * May result in the following errors:   416 * May result in the following errors:
410 * <ul>   417 * <ul>
411 * <li>ERROR_IO - I/O error occurred opening or reading the image file</li>   418 * <li>ERROR_IO - I/O error occurred opening or reading the image file</li>
412 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>   419 * <li>ERROR_UNSUPPORTED_DEPTH - the color depth is not supported</li>
413 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>   420 * <li>ERROR_INVALID_IMAGE - an error has occurred while creating the image</li>
414 * </ul>   421 * </ul>
415 * </p>   422 * </p>
416 *   423 *
417 * @ingroup Image   424 * @ingroup Image
418 *   425 *
419 * @param deviceHandle the device/display handle   426 * @param deviceHandle the device/display handle
420 * @param fileName image file to load   427 * @param fileName image file to load
421 * @param error the error status of the call   428 * @param error the error status of the call
422 *   429 *
423 * @return handle to the new image loaded from the specified file.   430 * @return handle to the new image loaded from the specified file.
424 *         0 if the file could not be decoded as an image.   431 *         0 if the file could not be decoded as an image.
425 */   432 */
426 UGL_Int Image_NewFromFile(UGL_Int deviceHandle, UGL_String fileName, UGL_Error error);   433 UGL_Int Image_NewFromFile(UGL_Int deviceHandle, UGL_String fileName, UGL_Error error);
427     434  
428     435  
429     436  
430     437  
431     438  
432 /**   439 /**
433 * Copies the specified area from the image identified by <code>handle</code>   440 * Copies the specified area from the image identified by <code>handle</code>
434 * into the destination image. The area is copied from location <code>x</code>,   441 * into the destination image. The area is copied from location <code>x</code>,
435 * <code>y</code> in the source image to location 0, 0 in the destination   442 * <code>y</code> in the source image to location 0, 0 in the destination
436 * image.   443 * image.
437 *   444 *
438 * @ingroup Image   445 * @ingroup Image
439 *   446 *
440 * @param handle handle to the image to copy   447 * @param handle handle to the image to copy
441 * @param destImageHandle handle to the destination image   448 * @param destImageHandle handle to the destination image
442 * @param x x coordinate of the area to copy to the destination image.   449 * @param x x coordinate of the area to copy to the destination image.
443 *          Must be within the image's bounds.   450 *          Must be within the image's bounds.
444 * @param y y coordinate of the area to copy to the destination image.   451 * @param y y coordinate of the area to copy to the destination image.
445 *          Must be within the image's bounds.   452 *          Must be within the image's bounds.
446 * @param width width of the area to copy to the destination image.   453 * @param width width of the area to copy to the destination image.
447 *              Must be within the image's bounds.   454 *              Must be within the image's bounds.
448 * @param height height of the area to copy to the destination image.   455 * @param height height of the area to copy to the destination image.
449 *               Must be within the image's bounds.   456 *               Must be within the image's bounds.
450 * @param error the error status of the call   457 * @param error the error status of the call
451 */   458 */
452 void Image_CopyArea(UGL_Int handle, UGL_Int destImageHandle, UGL_Int x, UGL_Int y, UGL_Int width, UGL_Int height, UGL_Error error);   459 void Image_CopyArea(UGL_Int handle, UGL_Int destImageHandle, UGL_Int x, UGL_Int y, UGL_Int width, UGL_Int height, UGL_Error error);
453     460  
454     461  
455 #ifdef __cplusplus   462 #ifdef __cplusplus
456 }   463 }
457 #endif   464 #endif
458     465  
459 #endif /* __UGL_IMAGE_H__ */   466 #endif /* __UGL_IMAGE_H__ */