Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kImage.h
Go to the documentation of this file.
1 /**
2 * @file kImage.h
3 * @brief Declares the kImage class.
4 *
5 * @internal
6 * Copyright (C) 2003-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_IMAGE_H
11 #define K_API_IMAGE_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kImage
19 * @extends kObject
20 * @ingroup kApi-Data
21 * @brief Represents a 2D collection of pixels.
22 *
23 * The kImage class is similar to the kArray2 class, but has some important differences:
24 * - By default, image memory is allocated such that rows are aligned to 8-byte boundaries.
25 * - Pixels are limited to value types.
26 * - Image indices/dimensions are given in (column, row) rather than (row, column) order.
27 * - kImage contains additional image-specific attributes (e.g. color filter array type).
28 *
29 * In particular, the row-alignment behaviour means that image memory should typically be accessed
30 * by getting a pointer to the beginning of a row, and then iterating over pixels. E.g.
31 *
32 * @code
33 * kSize height = kImage_Height(image);
34 * kSize width = kImage_Width(image);
35 * kSize i, j;
36 * k32u sum = 0;
37 *
38 * kAssert(kImage_PixelType(image, kTypeOf(k8u)));
39 *
40 * for (i = 0; i < height; ++i)
41 * {
42 * k8u* row = kImage_RowAt(image, i);
43 *
44 * for (j = 0; j < width; ++j)
45 * {
46 * sum += row[j];
47 * }
48 * }
49 *
50 * @endcode
51 */
52 //typedef kObject kImage; --forward-declared in kApiDef.x.h
53
54 /**
55 * Constructs a kImage object.
56 *
57 * @public @memberof kImage
58 * @param image Receives the constructed image object.
59 * @param pixelType Pixel type (must be a value type).
60 * @param width Image width.
61 * @param height Image height.
62 * @param allocator Memory allocator.
63 * @return Operation status.
64 */
65 kFx(kStatus) kImage_Construct(kImage* image, kType pixelType, kSize width, kSize height, kAlloc allocator);
66
67 /**
68 * Loads an image from file.
69 *
70 * The file extension is used to determine to image format. Currently, only the BMP (.bmp) format is supported.
71 *
72 * @public @memberof kImage
73 * @param image Receives the constructed image object.
74 * @param fileName File path.
75 * @param allocator Memory allocator (or kNULL for default).
76 * @return Operation status.
77 */
78 kFx(kStatus) kImage_Import(kImage *image, const char* fileName, kAlloc allocator);
79
80 /**
81 * Saves an image to file.
82 *
83 * The file extension is used to determine to image format. Currently, only the BMP (.bmp) format is supported.
84 *
85 * @public @memberof kImage
86 * @param image Image object.
87 * @param fileName File path.
88 * @return Operation status.
89 */
90 kFx(kStatus) kImage_Export(kImage image, const char* fileName);
91
92 /**
93 * Reallocates the internal pixel buffer.
94 *
95 * @public @memberof kImage
96 * @param image Image object.
97 * @param pixelType Type of pixel (values types only).
98 * @param width Image width, in pixels.
99 * @param height Image height, in pixels.
100 * @return Operation status.
101 */
102 kFx(kStatus) kImage_Allocate(kImage image, kType pixelType, kSize width, kSize height);
103
104 /**
105 * Attaches the image to an external pixel buffer.
106 *
107 * Attached pixel buffers are not freed when the image is destroyed.
108 *
109 * @public @memberof kImage
110 * @param image Image object.
111 * @param pixels Pointer to external pixel buffer.
112 * @param pixelType Type of pixel (values types only).
113 * @param width Image width, in pixels.
114 * @param height Image height, in pixels.
115 * @param stride Image stride (row size), in bytes.
116 * @return Operation status.
117 */
118 kFx(kStatus) kImage_Attach(kImage image, void* pixels, kType pixelType, kSize width, kSize height, kSize stride);
119
120 /**
121 * Copies a given source image into this image.
122 *
123 * @public @memberof kImage
124 * @param image Image object.
125 * @param source Source image to be copied.
126 * @return Operation status.
127 */
128 kFx(kStatus) kImage_Assign(kImage image, kImage source);
129
130 /**
131 * Sets all pixel bits to zero.
132 *
133 * @public @memberof kImage
134 * @param image Image object.
135 * @return Operation status.
136 */
137 kFx(kStatus) kImage_Zero(kImage image);
138
139 /**
140 * Sets the optional pixel format descriptor associated with this image.
141 *
142 * @public @memberof kImage
143 * @param image Image object.
144 * @param format Pixel format.
145 * @return Operation status.
146 */
147 kFx(kStatus) kImage_SetPixelFormat(kImage image, kPixelFormat format);
148
149 /**
150 * Gets the optional pixel format descriptor associated with this image.
151 *
152 * @public @memberof kImage
153 * @param image Image object.
154 * @return Pixel format.
155 */
156 kFx(kPixelFormat) kImage_PixelFormat(kImage image);
157
158 /**
159 * Sets the color filter array type associated with this image.
160 *
161 * @public @memberof kImage
162 * @param image Image object.
163 * @param cfa Color filter array type.
164 * @return Operation status.
165 */
166 kFx(kStatus) kImage_SetCfa(kImage image, kCfa cfa);
167
168 /**
169 * Gets the color filter array type associated with this image.
170 *
171 * @public @memberof kImage
172 * @param image Image object.
173 * @return Color filter array type.
174 */
175 kFx(kCfa) kImage_Cfa(kImage image);
176
177 /**
178 * Sets the value of a pixel.
179 *
180 * This method is convenient in some contexts, but is not an efficient method to manipulate
181 * many pixels. In performance-critical code, use kImage_RowAt to directly access the pixel buffer.
182 *
183 * @public @memberof kImage
184 * @param image Image object.
185 * @param x Column index.
186 * @param y Row index.
187 * @param pixel Pointer to pixel value that will be copied into the image.
188 * @return Operation status.
189 */
190 kFx(kStatus) kImage_SetPixel(kImage image, kSize x, kSize y, const void* pixel);
191
192 /**
193 * Gets the value of a pixel.
194 *
195 * This method is convenient in some contexts, but is not an efficient method to access
196 * many pixels. In performance-critical code, use kImage_RowAt to directly access the pixel buffer.
197 *
198 * @public @memberof kImage
199 * @param image Image object.
200 * @param x Column index.
201 * @param y Row index.
202 * @param pixel Destination for pixel copied from the image.
203 * @return Operation status.
204 */
205 kFx(kStatus) kImage_Pixel(kImage image, kSize x, kSize y, void* pixel);
206
207 /**
208 * Returns a pointer to the first row in the pixel buffer.
209 *
210 * @public @memberof kImage
211 * @param image Image object.
212 * @return Pointer to pixel buffer.
213 */
214 kFx(void*) kImage_Data(kImage image);
215
216 /**
217 * Reports the size, in bytes, of the pixel buffer.
218 *
219 * @public @memberof kImage
220 * @param image Image object.
221 * @return Size of pixel buffer (bytes).
222 */
223 kFx(kSize) kImage_DataSize(kImage image);
224
225 /**
226 * Returns a pointer to the specified pixel in the pixel buffer.
227 *
228 * @public @memberof kImage
229 * @param image Image object.
230 * @param x Column index.
231 * @param y Row index.
232 * @return Pointer to pixel.
233 */
234 kFx(void*) kImage_At(kImage image, kSize x, kSize y);
235
236 /**
237 * Returns a pointer to the specified row in the pixel buffer.
238 *
239 * @public @memberof kImage
240 * @param image Image object.
241 * @param y Row index.
242 * @return Pointer to first pixel in row.
243 */
244 kFx(void*) kImage_RowAt(kImage image, kSize y);
245
246 /**
247 * Returns the pixel type.
248 *
249 * @public @memberof kImage
250 * @param image Image object.
251 * @return Pixel type.
252 */
253 kFx(kType) kImage_PixelType(kImage image);
254
255 /**
256 * Returns the pixel size.
257 *
258 * @public @memberof kImage
259 * @param image Image object.
260 * @return Pixel size, in bytes.
261 */
262 kFx(kSize) kImage_PixelSize(kImage image);
263
264 /**
265 * Returns the width of the image, in pixels.
266 *
267 * @public @memberof kImage
268 * @param image Image object.
269 * @return Image width (pixels).
270 */
271 kFx(kSize) kImage_Width(kImage image);
272
273 /**
274 * Returns the height of the image, in pixels.
275 *
276 * @public @memberof kImage
277 * @param image Image object.
278 * @return Image height (pixels).
279 */
280 kFx(kSize) kImage_Height(kImage image);
281
282 /**
283 * Returns the area of the image, in pixels.
284 *
285 * Image area is the product of image width and image height.
286 *
287 * @public @memberof kImage
288 * @param image Image object.
289 * @return Image area (pixels).
290 */
291 kFx(kSize) kImage_Area(kImage image);
292
293 /**
294 * Returns the size of an image row, including alignment padding bytes, in bytes.
295 *
296 * @public @memberof kImage
297 * @param image Image object.
298 * @return Image stride (bytes).
299 */
300 kFx(kSize) kImage_Stride(kImage image);
301
302 #define kImage_Data_(IMAGE) kxImage_Data_(IMAGE) ///< Macro version of kImage_Data.
303 #define kImage_DataSize_(IMAGE) kxImage_DataSize_(IMAGE) ///< Macro version of kImage_DataSize.
304 #define kImage_At_(IMAGE, X, Y) kxImage_At_(IMAGE, X, Y) ///< Macro version of kImage_At.
305 #define kImage_RowAt_(IMAGE, Y) kxImage_RowAt_(IMAGE, Y) ///< Macro version of kImage_RowAt.
306 #define kImage_PixelType_(IMAGE) kxImage_PixelType_(IMAGE) ///< Macro version of kImage_PixelType.
307 #define kImage_PixelSize_(IMAGE) kxImage_PixelSize_(IMAGE) ///< Macro version of kImage_PixelSize.
308 #define kImage_Width_(IMAGE) kxImage_Width_(IMAGE) ///< Macro version of kImage_Width.
309 #define kImage_Height_(IMAGE) kxImage_Height_(IMAGE) ///< Macro version of kImage_Height.
310 #define kImage_Area_(IMAGE) kxImage_Area_(IMAGE) ///< Macro version of kImage_Area.
311 #define kImage_Stride_(IMAGE) kxImage_Stride_(IMAGE) ///< Macro version of kImage_Stride.
312 #define kImage_PixelFormat_(IMAGE) kxImage_PixelFormat_(IMAGE) ///< Macro version of kImage_PixelFormat.
313 #define kImage_Cfa_(IMAGE) kxImage_Cfa_(IMAGE) ///< Macro version of kImage_Cfa.
314
315 /** Accesses a pixel at the specified location, and casts the value to the specified type. */
316 #define kImage_As_(IMAGE, X, Y, TYPE) kxImage_As_(IMAGE, X, Y, TYPE)
317
318 kEndHeader()
319
320 #include <kApi/Data/kImage.x.h>
321
322 #endif
kImage::kImage_PixelFormat
kPixelFormat kImage_PixelFormat(kImage image)
Gets the optional pixel format descriptor associated with this image.
kImage::kImage_Height
kSize kImage_Height(kImage image)
Returns the height of the image, in pixels.
kImage::kImage_Allocate
kStatus kImage_Allocate(kImage image, kType pixelType, kSize width, kSize height)
Reallocates the internal pixel buffer.
kImage::kImage_Construct
kStatus kImage_Construct(kImage *image, kType pixelType, kSize width, kSize height, kAlloc allocator)
Constructs a kImage object.
kImage::kImage_SetCfa
kStatus kImage_SetCfa(kImage image, kCfa cfa)
Sets the color filter array type associated with this image.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kImage::kImage_Area
kSize kImage_Area(kImage image)
Returns the area of the image, in pixels.
kImage::kImage_Attach
kStatus kImage_Attach(kImage image, void *pixels, kType pixelType, kSize width, kSize height, kSize stride)
Attaches the image to an external pixel buffer.
kImage::kImage_SetPixelFormat
kStatus kImage_SetPixelFormat(kImage image, kPixelFormat format)
Sets the optional pixel format descriptor associated with this image.
kImage::kImage_Import
kStatus kImage_Import(kImage *image, const char *fileName, kAlloc allocator)
Loads an image from file.
kImage::kImage_Width
kSize kImage_Width(kImage image)
Returns the width of the image, in pixels.
kImage::kImage_SetPixel
kStatus kImage_SetPixel(kImage image, kSize x, kSize y, const void *pixel)
Sets the value of a pixel.
kPixelFormat
Pixel format descriptor enumeration.
kImage::kImage_Export
kStatus kImage_Export(kImage image, const char *fileName)
Saves an image to file.
kImage::kImage_RowAt
void * kImage_RowAt(kImage image, kSize y)
Returns a pointer to the specified row in the pixel buffer.
kImage::kImage_Pixel
kStatus kImage_Pixel(kImage image, kSize x, kSize y, void *pixel)
Gets the value of a pixel.
kImage::kImage_Zero
kStatus kImage_Zero(kImage image)
Sets all pixel bits to zero.
kApiDef.h
Essential API declarations.
kImage::kImage_Assign
kStatus kImage_Assign(kImage image, kImage source)
Copies a given source image into this image.
kImage::kImage_At
void * kImage_At(kImage image, kSize x, kSize y)
Returns a pointer to the specified pixel in the pixel buffer.
kType
Represents metadata about a type (class, interface, or value).
kImage::kImage_Cfa
kCfa kImage_Cfa(kImage image)
Gets the color filter array type associated with this image.
kImage
Represents a 2D collection of pixels.
kStatus
Represents an enumeration of error codes.
kImage::kImage_Data
void * kImage_Data(kImage image)
Returns a pointer to the first row in the pixel buffer.
kCfa
Image color filter array enumeration.
kImage::kImage_Stride
kSize kImage_Stride(kImage image)
Returns the size of an image row, including alignment padding bytes, in bytes.
kImage::kImage_PixelSize
kSize kImage_PixelSize(kImage image)
Returns the pixel size.
kImage::kImage_PixelType
kType kImage_PixelType(kImage image)
Returns the pixel type.
kImage::kImage_DataSize
kSize kImage_DataSize(kImage image)
Reports the size, in bytes, of the pixel buffer.