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__ */ |