summaryrefslogtreecommitdiff
path: root/src/lib/emile
diff options
context:
space:
mode:
authorCedric BAIL <cedric@osg.samsung.com>2015-03-17 08:50:35 +0100
committerCedric BAIL <cedric@osg.samsung.com>2015-03-17 09:58:19 +0100
commit97e3f55de543750c2bcb4cb4e50012ef35cb7d83 (patch)
tree3f9483707b46d7f9b4ad34753a9ce67ba6e3393f /src/lib/emile
parent8fd9770d95c32bad17af1963b9e1919888a5ab88 (diff)
emile: document Emile_Image.
Diffstat (limited to 'src/lib/emile')
-rw-r--r--src/lib/emile/emile_image.h254
1 files changed, 220 insertions, 34 deletions
diff --git a/src/lib/emile/emile_image.h b/src/lib/emile/emile_image.h
index ef62d316d1..dd353825d4 100644
--- a/src/lib/emile/emile_image.h
+++ b/src/lib/emile/emile_image.h
@@ -1,7 +1,25 @@
1#ifndef EMILE_IMAGE_H 1#ifndef EMILE_IMAGE_H
2#define EMILE_IMAGE_H 2#define EMILE_IMAGE_H
3 3
4/* All the value from below enum should be the same as in Evas_Loader.h */ 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 */
5typedef enum _Emile_Colorspace 23typedef enum _Emile_Colorspace
6{ 24{
7 EMILE_COLORSPACE_ARGB8888,/**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */ 25 EMILE_COLORSPACE_ARGB8888,/**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */
@@ -25,6 +43,16 @@ typedef enum _Emile_Colorspace
25 EMILE_COLORSPACE_RGBA_S3TC_DXT5 = 18 /**< OpenGL COMPRESSED_RGBA_S3TC_DXT5_EXT format with RGBA. @since 1.11 */ 43 EMILE_COLORSPACE_RGBA_S3TC_DXT5 = 18 /**< OpenGL COMPRESSED_RGBA_S3TC_DXT5_EXT format with RGBA. @since 1.11 */
26} Emile_Colorspace; 44} Emile_Colorspace;
27 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 */
28typedef enum _Emile_Image_Encoding 56typedef enum _Emile_Image_Encoding
29{ 57{
30 EMILE_IMAGE_LOSSLESS = 0, 58 EMILE_IMAGE_LOSSLESS = 0,
@@ -35,6 +63,15 @@ typedef enum _Emile_Image_Encoding
35 EMILE_IMAGE_ETC1_ALPHA = 5 63 EMILE_IMAGE_ETC1_ALPHA = 5
36} Emile_Image_Encoding; 64} Emile_Image_Encoding;
37 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 */
38typedef enum _Emile_Image_Scale_Hint 75typedef enum _Emile_Image_Scale_Hint
39{ 76{
40 EMILE_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */ 77 EMILE_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */
@@ -42,6 +79,15 @@ typedef enum _Emile_Image_Scale_Hint
42 EMILE_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on 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 */
43} Emile_Image_Scale_Hint; 80} Emile_Image_Scale_Hint;
44 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 */
45typedef enum _Emile_Image_Animated_Loop_Hint 91typedef enum _Emile_Image_Animated_Loop_Hint
46{ 92{
47 EMILE_IMAGE_ANIMATED_HINT_NONE = 0, 93 EMILE_IMAGE_ANIMATED_HINT_NONE = 0,
@@ -49,6 +95,15 @@ typedef enum _Emile_Image_Animated_Loop_Hint
49 EMILE_IMAGE_ANIMATED_HINT_PINGPONG = 2 95 EMILE_IMAGE_ANIMATED_HINT_PINGPONG = 2
50} Emile_Image_Animated_Loop_Hint; 96} Emile_Image_Animated_Loop_Hint;
51 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 */
52typedef enum _Emile_Image_Load_Error 107typedef enum _Emile_Image_Load_Error
53{ 108{
54 EMILE_IMAGE_LOAD_ERROR_NONE = 0, /**< No error on load */ 109 EMILE_IMAGE_LOAD_ERROR_NONE = 0, /**< No error on load */
@@ -60,11 +115,42 @@ typedef enum _Emile_Image_Load_Error
60 EMILE_IMAGE_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */ 115 EMILE_IMAGE_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */
61} Emile_Image_Load_Error; /**< Emile image load error codes one can get - see emile_load_error_str() too. */ 116} Emile_Image_Load_Error; /**< Emile image load error codes one can get - see emile_load_error_str() too. */
62 117
118/**
119 * @typedef Emile_Image
120 *
121 * Internal type representing an opened image.
122 *
123 * @since 1.14
124 */
63typedef struct _Emile_Image Emile_Image; 125typedef struct _Emile_Image Emile_Image;
64typedef struct _Emile_Image_Property Emile_Image_Property; 126
127/**
128 * @typedef Emile_Image_Load_Opts
129 *
130 * Description of the possible load option.
131 *
132 * @since 1.14
133 */
65typedef struct _Emile_Image_Load_Opts Emile_Image_Load_Opts; 134typedef struct _Emile_Image_Load_Opts Emile_Image_Load_Opts;
135
136/**
137 * @typedef Emile_Image_Animated
138 *
139 * Description animation.
140 *
141 * @since 1.14
142 */
66typedef struct _Emile_Image_Animated Emile_Image_Animated; 143typedef struct _Emile_Image_Animated Emile_Image_Animated;
67 144
145/**
146 * @typedef Emile_Image_Property
147 *
148 * Description of a loaded image property.
149 *
150 * @since 1.14
151 */
152typedef struct _Emile_Image_Property Emile_Image_Property;
153
68struct _Emile_Image_Property 154struct _Emile_Image_Property
69{ 155{
70 struct { 156 struct {
@@ -122,38 +208,138 @@ struct _Emile_Image_Load_Opts
122}; 208};
123 209
124// FIXME: should we set region at load time, instead of head time 210// FIXME: should we set region at load time, instead of head time
211// FIXME: should we regive the animated structure for head and data ?
212
213/**
214 * Open a TGV image from memory.
215 *
216 * @param source The Eina_Binbuf with TGV image in it.
217 * @param opts Load option for the image to open (it can be @c NULL).
218 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL)
219 * @param error Contain a valid error code if the function return @c NULL.
220 * @return a handler of the image if successfully opened, otherwise @c NULL.
221 *
222 * @since 1.14
223 */
224EAPI Emile_Image *
225emile_image_tgv_memory_open(Eina_Binbuf *source,
226 Emile_Image_Load_Opts *opts,
227 Emile_Image_Animated *animated,
228 Emile_Image_Load_Error *error);
229
230/**
231 * Open a TGV image from a file.
232 *
233 * @param source The Eina_File with TGV image in it.
234 * @param opts Load option for the image to open (it can be @c NULL).
235 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL)
236 * @param error Contain a valid error code if the function return @c NULL.
237 * @return a handler of the image if successfully opened, otherwise @c NULL.
238 *
239 * @since 1.14
240 */
241EAPI Emile_Image *
242emile_image_tgv_file_open(Eina_File *source,
243 Emile_Image_Load_Opts *opts,
244 Emile_Image_Animated *animated,
245 Emile_Image_Load_Error *error);
246
247
248/**
249 * Open a JPEG image from memory.
250 *
251 * @param source The Eina_Binbuf with JPEG image in it.
252 * @param opts Load option for the image to open (it can be @c NULL).
253 * @param animated Description of the image animation property, set during head reading and updated for each frame read by data (can be @c NULL)
254 * @param error Contain a valid error code if the function return @c NULL.
255 * @return a handler of the image if successfully opened, otherwise @c NULL.
256 *
257 * @since 1.14
258 */
259EAPI Emile_Image *
260emile_image_jpeg_memory_open(Eina_Binbuf *source,
261 Emile_Image_Load_Opts *opts,
262 Emile_Image_Animated *animated,
263 Emile_Image_Load_Error *error);
264
265/**
266 * Open a JPEG image from file.
267 *
268 * @param source The Eina_File 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 */
276EAPI Emile_Image *
277emile_image_jpeg_file_open(Eina_File *source,
278 Emile_Image_Load_Opts *opts,
279 Emile_Image_Animated *animated,
280 Emile_Image_Load_Error *error);
281
282/**
283 * Read the header of an image to fill Emile_Image_Property.
284 *
285 * @param image The Emile_Image handler.
286 * @param prop The Emile_Image_Property to be filled.
287 * @param property_size The size of the Emile_Image_Property as known during compilation.
288 * @param error Contain a valid error code if the function return @c NULL.
289 * @return @c EINA_TRUE if the header was successfully readed and prop properly filled.
290 *
291 * @since 1.14
292 */
293EAPI Eina_Bool
294emile_image_head(Emile_Image *image,
295 Emile_Image_Property *prop,
296 unsigned int property_size,
297 Emile_Image_Load_Error *error);
298
299/**
300 * Read the pixels from an image file.
301 *
302 * @param image The Emile_Image handler.
303 * @param prop The property to respect while reading this pixels.
304 * @param property_size The size of the Emile_Image_Property as known during compilation.
305 * @param pixels The actual pointer to the already allocated pixels buffer to fill.
306 * @param error Contain a valid error code if the function return @c NULL.
307 * @return @c EINA_TRUE if the data was successfully read and the pixels correctly filled.
308 *
309 * @since 1.14
310 */
311EAPI Eina_Bool
312emile_image_data(Emile_Image *image,
313 Emile_Image_Property *prop,
314 unsigned int property_size,
315 void *pixels,
316 Emile_Image_Load_Error *error);
317
318/**
319 * Close an opened image handler.
320 *
321 * @param source The handler to close.
322 *
323 * @since 1.14
324 */
325EAPI void
326emile_image_close(Emile_Image *source);
327
328/**
329 * Convert an error code related to an image handler into a meaningful string.
330 *
331 * @param source The handler related to the error (can be @c NULL).
332 * @param error The error code to get a message from.
333 * @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.
334 *
335 * @since 1.14
336 */
337EAPI const char *
338emile_load_error_str(Emile_Image *source,
339 Emile_Image_Load_Error error);
125 340
126EAPI Emile_Image *emile_image_tgv_memory_open(Eina_Binbuf *source, 341/**
127 Emile_Image_Load_Opts *opts, 342 * @}
128 Emile_Image_Animated *animated, 343 */
129 Emile_Image_Load_Error *error);
130EAPI Emile_Image *emile_image_tgv_file_open(Eina_File *source,
131 Emile_Image_Load_Opts *opts,
132 Emile_Image_Animated *animated,
133 Emile_Image_Load_Error *error);
134
135EAPI Emile_Image *emile_image_jpeg_memory_open(Eina_Binbuf *source,
136 Emile_Image_Load_Opts *opts,
137 Emile_Image_Animated *animated,
138 Emile_Image_Load_Error *error);
139EAPI Emile_Image *emile_image_jpeg_file_open(Eina_File *source,
140 Emile_Image_Load_Opts *opts,
141 Emile_Image_Animated *animated,
142 Emile_Image_Load_Error *error);
143
144EAPI Eina_Bool emile_image_head(Emile_Image *image,
145 Emile_Image_Property *prop,
146 unsigned int property_size,
147 Emile_Image_Load_Error *error);
148EAPI Eina_Bool emile_image_data(Emile_Image *image,
149 Emile_Image_Property *prop,
150 unsigned int property_size,
151 void *pixels,
152 Emile_Image_Load_Error *error);
153
154EAPI void emile_image_close(Emile_Image *source);
155
156EAPI const char *emile_load_error_str(Emile_Image *source,
157 Emile_Image_Load_Error error);
158 344
159#endif 345#endif