1 #ifndef EMILE_IMAGE_H 2 #define EMILE_IMAGE_H 3 4 /** 5 * @defgroup Emile_Image_Group Top level functions 6 * @ingroup Emile 7 * Function that allow reading/saving image. 8 * 9 * @{ 10 */ 11 12 /** 13 * @typedef Emile_Colorspace 14 * 15 * Flags that describe all colorspace known by EFL. Some routine may not know all of them. 16 * All the value from below enum should be the same as in Evas_Loader.h 17 * 18 * @see Evas_Colorspace 19 * @see Eet_Colorspace 20 * 21 * @since 1.14 22 */ 23 typedef enum _Emile_Colorspace 24 { 25 EMILE_COLORSPACE_ARGB8888,/**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */ 26 EMILE_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */ 27 EMILE_COLORSPACE_YCBCR422P709_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */ 28 EMILE_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */ 29 EMILE_COLORSPACE_GRY8 = 4, 30 EMILE_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */ 31 EMILE_COLORSPACE_YCBCR420NV12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb,Cr rows. */ 32 EMILE_COLORSPACE_YCBCR420TM12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of tiled row pointer, pointing to the Y rows, then the Cb,Cr rows. */ 33 EMILE_COLORSPACE_AGRY88 = 8, /**< AY 8bits Alpha and 8bits Grey, accessed 1 16bits at a time */ 34 EMILE_COLORSPACE_ETC1 = 9, /**< OpenGL ETC1 encoding of RGB texture (4 bit per pixel) @since 1.10 */ 35 EMILE_COLORSPACE_RGB8_ETC2 = 10, /**< OpenGL GL_COMPRESSED_RGB8_ETC2 texture compression format (4 bit per pixel) @since 1.10 */ 36 EMILE_COLORSPACE_RGBA8_ETC2_EAC = 11, /**< OpenGL GL_COMPRESSED_RGBA8_ETC2_EAC texture compression format, supports alpha (8 bit per pixel) @since 1.10 */ 37 EMILE_COLORSPACE_ETC1_ALPHA = 12, /**< ETC1 with alpha support using two planes: ETC1 RGB and ETC1 grey for alpha @since 1.11 */ 38 EMILE_COLORSPACE_RGB_S3TC_DXT1 = 13, /**< OpenGL COMPRESSED_RGB_S3TC_DXT1_EXT format with RGB only. @since 1.11 */ 39 EMILE_COLORSPACE_RGBA_S3TC_DXT1 = 14, /**< OpenGL COMPRESSED_RGBA_S3TC_DXT1_EXT format with RGBA punchthrough. @since 1.11 */ 40 EMILE_COLORSPACE_RGBA_S3TC_DXT2 = 15, /**< DirectDraw DXT2 format with premultiplied RGBA. Not supported by OpenGL itself. @since 1.11 */ 41 EMILE_COLORSPACE_RGBA_S3TC_DXT3 = 16, /**< OpenGL COMPRESSED_RGBA_S3TC_DXT3_EXT format with RGBA. @since 1.11 */ 42 EMILE_COLORSPACE_RGBA_S3TC_DXT4 = 17, /**< DirectDraw DXT4 format with premultiplied RGBA. Not supported by OpenGL itself. @since 1.11 */ 43 EMILE_COLORSPACE_RGBA_S3TC_DXT5 = 18 /**< OpenGL COMPRESSED_RGBA_S3TC_DXT5_EXT format with RGBA. @since 1.11 */ 44 } Emile_Colorspace; 45 46 /** 47 * @typedef Emile_Image_Encoding 48 * 49 * Flags that describe the supported encoding. Some routine may not know all of them. 50 * The value are the same as the one provided before in Eet.h 51 * 52 * @see Eet_Image_Encoding 53 * 54 * @since 1.14 55 */ 56 typedef enum _Emile_Image_Encoding 57 { 58 EMILE_IMAGE_LOSSLESS = 0, 59 EMILE_IMAGE_JPEG = 1, 60 EMILE_IMAGE_ETC1 = 2, 61 EMILE_IMAGE_ETC2_RGB = 3, 62 EMILE_IMAGE_ETC2_RGBA = 4, 63 EMILE_IMAGE_ETC1_ALPHA = 5 64 } Emile_Image_Encoding; 65 66 /** 67 * @typedef Emile_Image_Scale_Hint 68 * 69 * Flags that describe the scale hint used by the loader infrastructure. 70 * 71 * @see Evas_Image_Scale_Hint 72 * 73 * @since 1.14 74 */ 75 typedef enum _Emile_Image_Scale_Hint 76 { 77 EMILE_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */ 78 EMILE_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */ 79 EMILE_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */ 80 } Emile_Image_Scale_Hint; 81 82 /** 83 * @typedef Emile_Image_Animated_Loop_Hint 84 * 85 * Flags describing the behavior of animation from a loaded image. 86 * 87 * @see Evas_Image_Animated_Loop_Hint 88 * 89 * @since 1.14 90 */ 91 typedef enum _Emile_Image_Animated_Loop_Hint 92 { 93 EMILE_IMAGE_ANIMATED_HINT_NONE = 0, 94 EMILE_IMAGE_ANIMATED_HINT_LOOP = 1, 95 EMILE_IMAGE_ANIMATED_HINT_PINGPONG = 2 96 } Emile_Image_Animated_Loop_Hint; 97 98 /** 99 * @typedef Emile_Image_Load_Error 100 * 101 * Flags describing error state as discovered by an image loader. 102 * 103 * @see Evas_Load_Error 104 * 105 * @since 1.14 106 */ 107 typedef enum _Emile_Image_Load_Error 108 { 109 EMILE_IMAGE_LOAD_ERROR_NONE = 0, /**< No error on load */ 110 EMILE_IMAGE_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */ 111 EMILE_IMAGE_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */ 112 EMILE_IMAGE_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission denied to an existing file (or path) */ 113 EMILE_IMAGE_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */ 114 EMILE_IMAGE_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but was detected as a known format) */ 115 EMILE_IMAGE_LOAD_ERROR_UNKNOWN_FORMAT = 6, /**< File is not a known format */ 116 EMILE_IMAGE_LOAD_ERROR_CANCELLED = 7 /**< File loading has been cancelled */ 117 } Emile_Image_Load_Error; /**< Emile image load error codes one can get - see emile_load_error_str() too. */ 118 119 /** 120 * @typedef Emile_Image 121 * 122 * Internal type representing an opened image. 123 * 124 * @since 1.14 125 */ 126 typedef struct _Emile_Image Emile_Image; 127 128 /** 129 * @typedef Emile_Image_Load_Opts 130 * 131 * Description of the possible load option. 132 * 133 * @since 1.14 134 */ 135 typedef struct _Emile_Image_Load_Opts Emile_Image_Load_Opts; 136 137 /** 138 * @typedef Emile_Image_Animated 139 * 140 * Description animation. 141 * 142 * @since 1.14 143 */ 144 typedef struct _Emile_Image_Animated Emile_Image_Animated; 145 146 /** 147 * @typedef Emile_Image_Property 148 * 149 * Description of a loaded image property. 150 * 151 * @since 1.14 152 */ 153 typedef struct _Emile_Image_Property Emile_Image_Property; 154 155 /** 156 * @enum _Emile_Action 157 * @typedef Emile_Action 158 * What action emile is referring to. 159 * @since 1.19 160 */ 161 typedef enum _Emile_Action 162 { 163 EMILE_ACTION_NONE = 0, 164 EMILE_ACTION_CANCELLED = 1 165 } Emile_Action; 166 167 /** 168 * @typedef Emile_Action_Cb 169 * A callback triggered by emile to learn what to do about a specific action. 170 * @since 1.19 171 */ 172 typedef Eina_Bool (*Emile_Action_Cb)(void *data, Emile_Image *image, Emile_Action action); 173 174 struct _Emile_Image_Property 175 { 176 struct 177 { 178 unsigned char l, r, t, b; 179 } borders; 180 181 const Emile_Colorspace *cspaces; 182 Emile_Colorspace cspace; 183 184 Emile_Image_Encoding encoding; 185 186 unsigned int w; 187 unsigned int h; 188 unsigned int row_stride; 189 190 unsigned char scale; 191 192 Eina_Bool rotated; 193 Eina_Bool alpha; 194 Eina_Bool premul; 195 Eina_Bool alpha_sparse; 196 197 Eina_Bool flipped; 198 Eina_Bool comp; 199 }; 200 201 struct _Emile_Image_Animated 202 { 203 Eina_List *frames; 204 205 Emile_Image_Animated_Loop_Hint loop_hint; 206 207 int frame_count; 208 int loop_count; 209 int cur_frame; 210 211 Eina_Bool animated; 212 }; 213 214 struct _Emile_Image_Load_Opts 215 { 216 Eina_Rectangle region; 217 struct 218 { 219 int src_x, src_y, src_w, src_h; 220 int dst_w, dst_h; 221 int smooth; 222 223 /* This should have never been part of this structure, but we keep it 224 for ABI/API compatibility with Evas_Loader */ 225 Emile_Image_Scale_Hint scale_hint; 226 } scale_load; 227 double dpi; 228 unsigned int w, h; 229 unsigned int degree; 230 int scale_down_by; 231 232 Eina_Bool orientation; 233 }; 234 235 // FIXME: should we set region at load time, instead of head time 236 // FIXME: should we regive the animated structure for head and data ? 237 238 /** 239 * Open a TGV image from memory. 240 * 241 * @param source The Eina_Binbuf with TGV image in it. 242 * @param opts Load option for the image to open (it can be @c NULL). 243 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL) 244 * @param error Contain a valid error code if the function return @c NULL. 245 * @return a handler of the image if successfully opened, otherwise @c NULL. 246 * 247 * @since 1.14 248 */ 249 EAPI Emile_Image *emile_image_tgv_memory_open(Eina_Binbuf * source, Emile_Image_Load_Opts * opts, Emile_Image_Animated * animated, Emile_Image_Load_Error * error); 250 251 /** 252 * Open a TGV image from a file. 253 * 254 * @param source The Eina_File with TGV image in it. 255 * @param opts Load option for the image to open (it can be @c NULL). 256 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL) 257 * @param error Contain a valid error code if the function return @c NULL. 258 * @return a handler of the image if successfully opened, otherwise @c NULL. 259 * 260 * @since 1.14 261 */ 262 EAPI Emile_Image *emile_image_tgv_file_open(Eina_File * source, Emile_Image_Load_Opts * opts, Emile_Image_Animated * animated, Emile_Image_Load_Error * error); 263 264 265 /** 266 * Open a JPEG image from memory. 267 * 268 * @param source The Eina_Binbuf with JPEG image in it. 269 * @param opts Load option for the image to open (it can be @c NULL). 270 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL) 271 * @param error Contain a valid error code if the function return @c NULL. 272 * @return a handler of the image if successfully opened, otherwise @c NULL. 273 * 274 * @since 1.14 275 */ 276 EAPI Emile_Image *emile_image_jpeg_memory_open(Eina_Binbuf * source, Emile_Image_Load_Opts * opts, Emile_Image_Animated * animated, Emile_Image_Load_Error * error); 277 278 /** 279 * Open a JPEG image from file. 280 * 281 * @param source The Eina_File with JPEG image in it. 282 * @param opts Load option for the image to open (it can be @c NULL). 283 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL) 284 * @param error Contain a valid error code if the function return @c NULL. 285 * @return a handler of the image if successfully opened, otherwise @c NULL. 286 * 287 * @since 1.14 288 */ 289 EAPI Emile_Image *emile_image_jpeg_file_open(Eina_File * source, Emile_Image_Load_Opts * opts, Emile_Image_Animated * animated, Emile_Image_Load_Error * error); 290 291 /** 292 * Read the header of an image to fill Emile_Image_Property. 293 * 294 * @param image The Emile_Image handler. 295 * @param prop The Emile_Image_Property to be filled. 296 * @param property_size The size of the Emile_Image_Property as known during compilation. 297 * @param error Contain a valid error code if the function return @c NULL. 298 * @return @c EINA_TRUE if the header was successfully readed and prop properly filled. 299 * 300 * @since 1.14 301 */ 302 EAPI Eina_Bool emile_image_head(Emile_Image * image, Emile_Image_Property * prop, unsigned int property_size, Emile_Image_Load_Error * error); 303 304 /** 305 * Read the pixels from an image file. 306 * 307 * @param image The Emile_Image handler. 308 * @param prop The property to respect while reading this pixels. 309 * @param property_size The size of the Emile_Image_Property as known during compilation. 310 * @param pixels The actual pointer to the already allocated pixels buffer to fill. 311 * @param error Contain a valid error code if the function return @c NULL. 312 * @return @c EINA_TRUE if the data was successfully read and the pixels correctly filled. 313 * 314 * @since 1.14 315 */ 316 EAPI Eina_Bool emile_image_data(Emile_Image * image, Emile_Image_Property * prop, unsigned int property_size, void *pixels, Emile_Image_Load_Error * error); 317 318 /** 319 * Register a callback for emile to ask what to do during the processing of an image 320 * 321 * @param image The Emile_Image handler to register on. 322 * @param callback The callback to use 323 * @param action The action this callback is triggered on. 324 * @since 1.19 325 */ 326 EAPI void emile_image_callback_set(Emile_Image *image, Emile_Action_Cb callback, Emile_Action action, const void *data); 327 328 /** 329 * Close an opened image handler. 330 * 331 * @param source The handler to close. 332 * 333 * @since 1.14 334 */ 335 EAPI void emile_image_close(Emile_Image * source); 336 337 /** 338 * Convert an error code related to an image handler into a meaningful string. 339 * 340 * @param source The handler related to the error (can be @c NULL). 341 * @param error The error code to get a message from. 342 * @return a string that will be owned by Emile, either by the handler if it is not @c NULL or by the library directly if it is. 343 * 344 * @since 1.14 345 */ 346 EAPI const char *emile_load_error_str(Emile_Image * source, Emile_Image_Load_Error error); 347 348 /** 349 * @} 350 */ 351 352 #endif 353