os/graphics/graphicscomposition/openwfcompositionengine/common/include/owfimage.h
First public contribution.
1 /* Copyright (c) 2009 The Khronos Group Inc.
2 * Portions copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies)
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and/or associated documentation files (the
6 * "Materials"), to deal in the Materials without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Materials, and to
9 * permit persons to whom the Materials are furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be included
13 * in all copies or substantial portions of the Materials.
15 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
33 typedef void* OWF_DISPCTX;
36 #undef USE_FLOAT_PIXEL
39 * This is and always should be the only place where USE_FLOAT_PIXEL is
40 * defined so if #define USE_FLOAT_PIXEL is absent in owfimage.h then it
41 * can be assumed it is not defined elsewhere.
43 //#define USE_FLOAT_PIXEL
46 * internal pixel format
48 #ifdef USE_FLOAT_PIXEL
49 #define OWF_IMAGE_INTERNAL_PIXEL_IS_FLOAT
51 typedef OWFfloat OWFsubpixel; /* subpixel representation */
53 #define OWF_RED_MIN_VALUE 0.0f
54 #define OWF_RED_MAX_VALUE 1.0f
55 #define OWF_GREEN_MIN_VALUE 0.0f
56 #define OWF_GREEN_MAX_VALUE 1.0f
57 #define OWF_BLUE_MIN_VALUE 0.0f
58 #define OWF_BLUE_MAX_VALUE 1.0f
59 #define OWF_ALPHA_MIN_VALUE 0.0f
60 #define OWF_ALPHA_MAX_VALUE 1.0f
62 #define OWF_FULLY_OPAQUE OWF_ALPHA_MAX_VALUE
63 #define OWF_FULLY_TRANSPARENT OWF_ALPHA_MIN_VALUE
65 #define OWF_BYTE_MAX_VALUE 255.0f
66 #define OWF_BILINEAR_ROUNDING_VALUE 0.0f
67 #define OWF_BLEND_ROUNDING_VALUE 0.0f
68 #define OWF_PREMUL_ROUNDING_FACTOR 0.0f
69 #define OWF_SOURCE_CONVERSION_ROUNDING_VALUE 0.0f
72 #undef OWF_IMAGE_INTERNAL_PIXEL_IS_FLOAT
74 typedef OWFuint8 OWFsubpixel; /* subpixel representation */
76 #define OWF_RED_MIN_VALUE 0
77 #define OWF_RED_MAX_VALUE 255
78 #define OWF_GREEN_MIN_VALUE 0
79 #define OWF_GREEN_MAX_VALUE 255
80 #define OWF_BLUE_MIN_VALUE 0
81 #define OWF_BLUE_MAX_VALUE 255
82 #define OWF_ALPHA_MIN_VALUE 0
83 #define OWF_ALPHA_MAX_VALUE 255
84 #define OWF_FULLY_OPAQUE OWF_ALPHA_MAX_VALUE
85 #define OWF_FULLY_TRANSPARENT OWF_ALPHA_MIN_VALUE
87 #define OWF_BYTE_MAX_VALUE 255
89 #define OWF_BILINEAR_ROUNDING_VALUE 0.5f
90 #define OWF_SOURCE_CONVERSION_ROUNDING_VALUE 0.5f
91 #define OWF_BLEND_ROUNDING_VALUE (OWF_ALPHA_MAX_VALUE/2)
92 #define OWF_PREMUL_ROUNDING_FACTOR (OWF_ALPHA_MAX_VALUE/2)
97 * Byte order of different color formats
98 * these are used when converting from/to
102 #define ARGB8888_ALPHA_MASK 0xFF000000
103 #define ARGB8888_RED_MASK 0x00FF0000
104 #define ARGB8888_GREEN_MASK 0x0000FF00
105 #define ARGB8888_BLUE_MASK 0x000000FF
106 #define ARGB8888_ALPHA_SHIFT 24
107 #define ARGB8888_RED_SHIFT 16
108 #define ARGB8888_GREEN_SHIFT 8
109 #define ARGB8888_BLUE_SHIFT 0
111 #define RGB565_ALPHA_MASK 0xFFFF
112 #define RGB565_RED_MASK 0xF800
113 #define RGB565_GREEN_MASK 0x07E0
114 #define RGB565_BLUE_MASK 0x001F
116 /* These are used when converting from RGB565 to ARGB8888. */
117 #define RGB565_ALPHA_SHIFT 16
118 #define RGB565_RED_SHIFT 11
119 #define RGB565_GREEN_SHIFT 5
121 /* subpixels per pixel */
122 #define OWF_PIXEL_SIZE 4
124 /* subpixel in bytes */
125 #define OWF_SUBPIXEL_SIZE sizeof(OWFsubpixel)
126 #define OWF_BYTES_PER_PIXEL (OWF_PIXEL_SIZE * OWF_SUBPIXEL_SIZE)
128 #pragma pack(push, 1)
136 OWFsubpixel subpixel[OWF_PIXEL_SIZE];
137 OWFuint8 pixelbytes[OWF_BYTES_PER_PIXEL];
143 /* filters used in OWF_Image_Stretch */
145 OWF_FILTER_POINT_SAMPLING, /* nearest pixel */
146 OWF_FILTER_BILINEAR /* nearest 4 */
152 OWFint stride; /* number of bytes per line */
153 OWFint pixelSize; /* pixel size in bytes */
154 OWF_IMAGE_FORMAT format;
156 OWFint dataMax; /* data buffer max size */
160 /* This typedef denotes an owned OWF_IMAGE, as opposed to a temporary association.
161 * Owned instances must be destroyed when the containing object is destroyed.
163 typedef OWF_IMAGE* OWF_IMAGE_INST;
167 OWF_FLIP_VERTICALLY = 1,
168 OWF_FLIP_HORIZONTALLY = 2
169 } OWF_FLIP_DIRECTION;
173 OWF_ROTATION_90 = 90,
174 OWF_ROTATION_180 = 180,
175 OWF_ROTATION_270 = 270
179 OWF_TRANSPARENCY_NONE,
180 OWF_TRANSPARENCY_GLOBAL_ALPHA = (1 << 0),
181 OWF_TRANSPARENCY_SOURCE_ALPHA = (1 << 1),
182 OWF_TRANSPARENCY_MASK = (1 << 2),
183 OWF_TRANSPARENCY_COLOR_KEY = (1 << 3)
186 typedef struct _OWF_BLEND_INFO {
189 OWF_RECTANGLE* rectangle;
194 OWF_RECTANGLE* rectangle;
198 OWFsubpixel globalAlpha;
202 /*!---------------------------------------------------------------------------
203 * \brief Initialize image object
205 * \param image Image object to initialize
206 *----------------------------------------------------------------------------*/
208 OWF_Image_Init(OWF_IMAGE* image);
210 /*!---------------------------------------------------------------------------
211 * \brief Creates new reference counted image object
213 * \param width Image width (in pixels)
214 * \param height Image height (in pixels)
215 * \param format Image format (\see OWF_IMAGE_FORMAT)
216 * \param buffer Pointer to image pixel data. If NULL, then a new
217 * buffer is allocated for storing image pixel data.
218 * Allocated buffer is owned by the image. If non-NULL,
219 * then the image will be a "foreign" one, that doesn't
220 * own the pixel data but merely uses it.
221 * \param minimumStride Minimum number of bytes per scanline (may be zero)
224 * \return New image object or NULL if error occured.
225 *----------------------------------------------------------------------------*/
226 OWF_PUBLIC OWF_IMAGE*
227 OWF_Image_Create(OWFint width,
229 const OWF_IMAGE_FORMAT* format,
231 OWFint minimumStride);
233 /*!---------------------------------------------------------------------------
234 * \brief Destroy image object. Rather than actually destroying the image
235 * immediately, this decrements image's reference count by one and once the
236 * counter reaches zero, the actual deletion will occur.
238 * \param image Image to destroy
239 *----------------------------------------------------------------------------*/
241 OWF_Image_Destroy(OWF_IMAGE* image);
243 /*!---------------------------------------------------------------------------
244 * \brief Create a pixel-perfect copy (clone) of the image. The copy will be
245 * totally independent from the original image, i.e. doesn't share pixel
246 * buffers or anything.
248 * \param image Image to copy
250 * \param Copy of the image or NULL if error occured.
251 *----------------------------------------------------------------------------*/
252 OWF_API_CALL OWF_IMAGE*
253 OWF_Image_Copy(const OWF_IMAGE* image);
255 /*!---------------------------------------------------------------------------
256 * \brief Set image size. This doesn't modify the pixel data in anyway,
257 * merely just changes the image header. Mostly used for (recycling) foreign
258 * images that point to external pixel buffers.
260 * If the new pixel count (width * height) exceeds
261 * current values, the pixel buffer will NOT be resized, but the call will FAIL.
263 * \param image Image to resize
264 * \param width New width of the image
265 * \param height New height of the image
268 * \return Boolean value indicating success of the operation. In case of
269 * failure, no modifications are done to original image.
270 *----------------------------------------------------------------------------*/
271 OWF_API_CALL OWFboolean
272 OWF_Image_SetSize(OWF_IMAGE* image,
276 /*!---------------------------------------------------------------------------
277 * \brief Set internal mode flags. This doesn't modify the pixel data in anyway,
278 * merely just changes the image header. Mostly used for (recycling) foreign
279 * images that point to external pixel buffers.
282 * \param image Image to resize
283 * \param premultiply Image data is premultiplied
284 * \param linear Image colour data is linear
287 * \return Boolean value indicating success of the operation. In case of
288 * failure, no modifications are done to original image.
289 *----------------------------------------------------------------------------*/
291 OWF_Image_SetFlags(OWF_IMAGE* image,
292 OWFboolean premultiply,
295 /*!---------------------------------------------------------------------------
296 * \brief Set the pixel buffer to an alternate location.
297 * All other parameters remain the same.
299 * \param image Image to resize
300 * \param buffer Image data source to start using
302 *----------------------------------------------------------------------------*/
304 OWF_Image_SetPixelBuffer(OWF_IMAGE* image, void* buffer);
307 /*!---------------------------------------------------------------------------
308 * \brief Blit (1:1 copy) pixels from image to another w/ clipping.
310 * \param dst Destination image
311 * \param dstRect Destination rectangle
312 * \param src Source image
313 * \param srcRect Source rectangle
315 * \return Boolean value indicating whether pixels were copied or not. If not,
316 * it means that either of the rectangles is outside its respective image's
318 *----------------------------------------------------------------------------*/
319 OWF_API_CALL OWFboolean
320 OWF_Image_Blit(OWF_IMAGE* dst,
321 OWF_RECTANGLE const* dstRect,
322 OWF_IMAGE const* src,
323 OWF_RECTANGLE const* srcRect);
325 /*!---------------------------------------------------------------------------
326 * \brief Stretch-blit (scaled copy) pixels from image to another w/ clipping.
328 * \param dst Destination image
329 * \param dstRect Destination rectangle
330 * \param src Source image
331 * \param srcRect Source rectangle
333 * \return Boolean value indicating whether pixels were copied or not. If not,
334 * it means that either of the rectangles is outside its respective image's
336 *----------------------------------------------------------------------------*/
337 OWF_API_CALL OWFboolean
338 OWF_Image_Stretch(OWF_IMAGE* dst,
339 OWF_RECTANGLE* dstRect,
342 OWF_FILTERING filter);
344 /*!---------------------------------------------------------------------------
345 * \brief Multiply pixels' alpha value into rgb-color components.
346 * Multiplies only if image source image is non-premultiplied.
347 * \param image Image to convert to pre-multiplied domain.
348 *----------------------------------------------------------------------------*/
350 OWF_Image_PremultiplyAlpha(OWF_IMAGE* image);
352 /*!---------------------------------------------------------------------------
353 * \brief Divide pixels' rgb-color components by its alpha value.
355 * \param image Image to convert to nonpre-multiplied domain.
356 *----------------------------------------------------------------------------*/
358 OWF_Image_UnpremultiplyAlpha(OWF_IMAGE* image);
360 /*!---------------------------------------------------------------------------
361 * \brief Linearizes image pixel data
363 * \param image Image to convert to linear domain
364 *----------------------------------------------------------------------------*/
366 OWF_Image_LinearizeData(OWF_IMAGE* image);
368 /*!---------------------------------------------------------------------------
369 * \brief Non-linearizes image pixel data
371 * \param image Image to convert to non-linear domain
372 *----------------------------------------------------------------------------*/
374 OWF_Image_NonLinearizeData(OWF_IMAGE* image);
376 /*!---------------------------------------------------------------------------
377 * \brief Apply gamma correction to image pixel values
379 * \param image Image to operate on
380 * \param gamma Gamma value
381 *----------------------------------------------------------------------------*/
383 OWF_Image_Gamma(OWF_IMAGE* image, OWFfloat gamma);
385 /*!---------------------------------------------------------------------------
386 * \brief Flip (mirror) image about one or both of its center axes.
388 * \param image Image to flip
389 * \param dir Flip direction. Valid values are
390 * OWF_FLIP_NONE, OWF_FLIP_HORIZONTALLY,
391 * OWF_FLIP_VERTICALLY or any bitwise-or combination
393 *----------------------------------------------------------------------------*/
395 OWF_Image_Flip(OWF_IMAGE* image,
396 OWF_FLIP_DIRECTION dir);
398 /*!---------------------------------------------------------------------------
399 * \brief Rotate image n*90 degrees about its center
401 * \param dst Result (rotated) image.
402 * \param src Source image.
403 * \param rotation Rotation angle (OWF_ROTATION_0, OWF_ROTATION_90,
404 * OWF_ROTATION_180, or OWF_ROTATION_270)
405 *----------------------------------------------------------------------------*/
407 OWF_Image_Rotate(OWF_IMAGE* dst,
409 OWF_ROTATION rotation);
411 /*!---------------------------------------------------------------------------
417 *----------------------------------------------------------------------------*/
419 OWF_Image_Blend(OWF_BLEND_INFO* blend,
420 OWF_TRANSPARENCY transparency);
422 /*!---------------------------------------------------------------------------
428 *----------------------------------------------------------------------------*/
430 OWF_Image_Clear(OWF_IMAGE* image,
436 /*!---------------------------------------------------------------------------
437 * \brief Convert image data from internal color format to destination format
443 *----------------------------------------------------------------------------*/
444 OWF_API_CALL OWFboolean
445 OWF_Image_DestinationFormatConversion(OWF_IMAGE* dst,
447 /*!---------------------------------------------------------------------------
448 * \brief Test whether it will be possible to convert to destination format.
449 * Note, no IMAGE object yet extists. This is effectively a "static" member method.
450 * \param format proposed destination format
452 * \return boolean true if image lib can convert image data from internal color format
453 *----------------------------------------------------------------------------*/
454 OWF_API_CALL OWFboolean
455 OWF_Image_IsValidDestinationFormat(OWF_IMAGE_FORMAT* format);
457 /*!---------------------------------------------------------------------------
458 * \brief Convert image data from source format to internal format
464 *----------------------------------------------------------------------------*/
465 OWF_API_CALL OWFboolean
466 OWF_Image_SourceFormatConversion(OWF_IMAGE* dst,
469 /*!---------------------------------------------------------------------------
475 *----------------------------------------------------------------------------*/
477 OWF_Image_AllocData(OWF_DISPCTX dc, OWFint width,
479 OWF_PIXEL_FORMAT format);
482 /*!---------------------------------------------------------------------------
488 *----------------------------------------------------------------------------*/
490 OWF_Image_FreeData(OWF_DISPCTX dc, void** buffer);
492 /*!---------------------------------------------------------------------------
498 *----------------------------------------------------------------------------*/
500 OWF_Image_GetFormatPixelSize(OWF_PIXEL_FORMAT format);
503 /*!---------------------------------------------------------------------------
504 * \brief Return stride (aligned row size in bytes) calculated from image
505 * width and pixelSize. If pixelSize is negative image width must be divisible
508 * \param width Width of image
509 * \param pixelSize Size of single pixel in bytes. Negative size
510 * means value is a divisor (i.e. 1/pixelSize)
511 * \param padding Number of bits each row is padded to.
513 * \return Row size in bytes.
514 *----------------------------------------------------------------------------*/
516 OWF_Image_GetStride(OWFint width,
517 const OWF_IMAGE_FORMAT* format,OWFint minimumStride);
519 /*!---------------------------------------------------------------------------
525 *----------------------------------------------------------------------------*/
527 OWF_Image_GetFormatPadding(OWF_PIXEL_FORMAT format);
529 /*!---------------------------------------------------------------------------
530 * \brief Swap image width & height values in image header. Doesn't modify
533 * \param image Image to operate on.
534 *----------------------------------------------------------------------------*/
536 OWF_Image_SwapWidthAndHeight(OWF_IMAGE* image);
538 /*!---------------------------------------------------------------------------
539 * \brief Convert mask from external format to internal 8bpp format.
541 * \param output Result (converted) mask image
542 * \param input Input mask image to convert.
544 * \return Boolean value indicating operation success. OWF_FALSE means that
545 * input mask is either invalid or unsupported, or degenerate in some other
547 *----------------------------------------------------------------------------*/
548 OWF_API_CALL OWFboolean
549 OWF_Image_ConvertMask(OWF_IMAGE* output,
552 /*!---------------------------------------------------------------------------
553 * \brief Return pointer to given pixel in image.
556 * \param x X-coordinate of the pixel (0..width-1)
557 * \param y Y-coordinate of the pixel (0..height-1)
559 * The x & y coordinates will be clamped to [0..width-1, 0..height-1]
561 * \return Pointer to given pixel
562 *----------------------------------------------------------------------------*/
563 OWF_API_CALL OWFpixel*
564 OWF_Image_GetPixelPtr(OWF_IMAGE* image,
568 /*!---------------------------------------------------------------------------
569 * \brief Read single pixel from image
572 * \param x Pixel x coordinate
573 * \param y Pixel y coordinate
574 * \param pixel Where to store the pixel color value
576 * Coordinates are clamped to region (0..width-1, 0..height-1)
577 *----------------------------------------------------------------------------*/
579 OWF_Image_GetPixel(OWF_IMAGE* image,
584 /*!---------------------------------------------------------------------------
585 * \brief Write a pixel into image
588 * \param x Pixel x coordinate
589 * \param y Pixel y coordinate
590 * \param pixel Color of the pixel
592 * Coordinates are clamped to region (0..width-1, 0..height-1)
593 *----------------------------------------------------------------------------*/
595 OWF_Image_SetPixel(OWF_IMAGE* image,
598 OWFpixel const* pixel);