Image Object Functions

Here are grouped together functions used to create and manipulate image objects. More...

Typedefs
typedef void(*	Evas_Object_Image_Pixels_Get_Cb )(void *data, Evas_Object *o)
typedef enum _Evas_Colorspace	Evas_Colorspace
	Colorspaces for pixel data supported by Evas. More...

Enumerations
enum	_Evas_Colorspace {   EVAS_COLORSPACE_ARGB8888,   EVAS_COLORSPACE_YCBCR422P601_PL,   EVAS_COLORSPACE_YCBCR422P709_PL,   EVAS_COLORSPACE_RGB565_A5P,   EVAS_COLORSPACE_GRY8,   EVAS_COLORSPACE_YCBCR422601_PL,   EVAS_COLORSPACE_YCBCR420NV12601_PL,   EVAS_COLORSPACE_YCBCR420TM12601_PL,   EVAS_COLORSPACE_AGRY88,   EVAS_COLORSPACE_ETC1,   EVAS_COLORSPACE_RGB8_ETC2,   EVAS_COLORSPACE_RGBA8_ETC2_EAC }
	Colorspaces for pixel data supported by Evas. More...

Functions
Eina_Bool	evas_object_image_extension_can_load_get (const char *file)
	Check if a file extension may be supported by Image Object Functions. More...
Eina_Bool	evas_object_image_extension_can_load_fast_get (const char *file)
	Check if a file extension may be supported by Image Object Functions. More...
Evas_Object *	evas_object_image_add (Evas *e)
	Creates a new image object on the given Evas e canvas. More...
Evas_Object *	evas_object_image_filled_add (Evas *e)
	Creates a new image object that automatically scales its bound image to the object's area, on both axis. More...
void	evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key)
	Sets the data for an image from memory to be loaded. More...
void	evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf)
	Set the native surface of a given image of the canvas. More...
void	evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel)
	Preload an image object's image data in the background. More...
Eina_Bool	evas_object_image_source_unset (Evas_Object *obj)
	Clear the source object on a proxy image object. More...
void	evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask)
	Enable an image to be used as an alpha mask. More...

Detailed Description

Here are grouped together functions used to create and manipulate image objects.

They are available to whichever occasion one needs complex imagery on a GUI that could not be achieved by the other Evas' primitive object types, or to make image manipulations.

Evas will support whichever image file types it was compiled with support to (its image loaders) – check your software packager for that information and see evas_object_image_extension_can_load_get().

Image object basics

The most common use of image objects – to display an image on the canvas – is achieved by a common function triplet:

img = evas_object_image_add(canvas);
evas_object_image_file_set(img, "path/to/img", NULL);
evas_object_image_fill_set(img, 0, 0, w, h);

The first function, naturally, is creating the image object. Then, one must set an source file on it, so that it knows where to fetch image data from. Next, one must set how to fill the image object's area with that given pixel data. One could use just a sub-region of the original image or even have it tiled repeatedly on the image object. For the common case of having the whole source image to be displayed on the image object, stretched to the destination's size, there's also a function helper, to be used instead of evas_object_image_fill_set():

evas_object_image_filled_set(img, EINA_TRUE);

See those functions' documentation for more details.

Scale and resizing

Resizing of image objects will scale their respective source images to their areas, if they are set to "fill" the object's area (evas_object_image_filled_set()). If the user wants any control on the aspect ratio of an image for different sizes, he/she has to take care of that themselves. There are functions to make images to get loaded scaled (up or down) in memory, already, if the user is going to use them at pre-determined sizes and wants to save computations.

Evas has even a scale cache, which will take care of caching scaled versions of images with more often usage/hits. Finally, one can have images being rescaled smoothly by Evas (more computationally expensive) or not.

Performance hints

When dealing with image objects, there are some tricks to boost the performance of your application, if it does intense image loading and/or manipulations, as in animations on a UI.

Load hints

In image viewer applications, for example, the user will be looking at a given image, at full size, and will desire that the navigation to the adjacent images on his/her album be fluid and fast. Thus, while displaying a given image, the program can be on the background loading the next and previous images already, so that displaying them on the sequence is just a matter of repainting the screen (and not decoding image data).

Evas addresses this issue with image pre-loading. The code for the situation above would be something like the following:

prev = evas_object_image_filled_add(canvas);
evas_object_image_file_set(prev, "/path/to/prev", NULL);
evas_object_image_preload(prev, EINA_TRUE);

next = evas_object_image_filled_add(canvas);
evas_object_image_file_set(next, "/path/to/next", NULL);
evas_object_image_preload(next, EINA_TRUE);

If you're loading images which are too big, consider setting previously it's loading size to something smaller, in case you won't expose them in real size. It may speed up the loading considerably:

//to load a scaled down version of the image in memory, if that's
//the size you'll be displaying it anyway
evas_object_image_load_scale_down_set(img, zoom);

//optional: if you know you'll be showing a sub-set of the image's
//pixels, you can avoid loading the complementary data
evas_object_image_load_region_set(img, x, y, w, h);

Refer to Elementary's Photocam widget for a high level (smart) object which does lots of loading speed-ups for you.

Animation hints

If you want to animate image objects on a UI (what you'd get by concomitant usage of other libraries, like Ecore and Edje), there are also some tips on how to boost the performance of your application. If the animation involves resizing of an image (thus, re-scaling), you'd better turn off smooth scaling on it during the animation, turning it back on afterwards, for less computations. Also, in this case you'd better flag the image object in question not to cache scaled versions of it:

evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC);

// resizing takes place in between

evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC);

Finally, movement of opaque images through the canvas is less expensive than of translucid ones, because of blending computations.

Borders

Evas provides facilities for one to specify an image's region to be treated specially – as "borders". This will make those regions be treated specially on resizing scales, by keeping their aspect. This makes setting frames around other objects on UIs easy. See the following figures for a visual explanation:
Full-size Full-size

Manipulating pixels

Evas image objects can be used to manipulate raw pixels in many ways. The meaning of the data in the pixel arrays will depend on the image's color space, be warned (see next section). You can set your own data as an image's pixel data, fetch an image's pixel data for saving/altering, convert images between different color spaces and even advanced operations like setting a native surface as image objects' data.

Color spaces

Image objects may return or accept "image data" in multiple formats. This is based on the color space of an object. Here is a rundown on formats:

• EVAS_COLORSPACE_ARGB8888: This pixel format is a linear block of pixels, starting at the top-left row by row until the bottom right of the image or pixel region. All pixels are 32-bit unsigned int's with the high-byte being alpha and the low byte being blue in the format ARGB. Alpha may or may not be used by evas depending on the alpha flag of the image, but if not used, should be set to 0xff anyway.
  
  This colorspace uses premultiplied alpha. That means that R, G and B cannot exceed A in value. The conversion from non-premultiplied colorspace is:
  
  R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
  
  So 50% transparent blue will be: 0x80000080. This will not be "dark" - just 50% transparent. Values are 0 == black, 255 == solid or full red, green or blue.

• EVAS_COLORSPACE_YCBCR422P601_PL: This is a pointer-list indirected set of YUV (YCbCr) pixel data. This means that the data returned or set is not actual pixel data, but pointers TO lines of pixel data. The list of pointers will first be N rows of pointers to the Y plane - pointing to the first pixel at the start of each row in the Y plane. N is the height of the image data in pixels. Each pixel in the Y, U and V planes is 1 byte exactly, packed. The next N / 2 pointers will point to rows in the U plane, and the next N / 2 pointers will point to the V plane rows. U and V planes are half the horizontal and vertical resolution of the Y plane.
  
  Row order is top to bottom and row pixels are stored left to right.
  
  There is a limitation that these images MUST be a multiple of 2 pixels in size horizontally or vertically. This is due to the U and V planes being half resolution. Also note that this assumes the itu601 YUV colorspace specification. This is defined for standard television and mpeg streams. HDTV may use the itu709 specification.
  
  Values are 0 to 255, indicating full or no signal in that plane respectively.

• EVAS_COLORSPACE_YCBCR422P709_PL: Not implemented yet.

• EVAS_COLORSPACE_RGB565_A5P: In the process of being implemented in 1 engine only. This may change.
  
  This is a pointer to image data for 16-bit half-word pixel data in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with the high-byte containing red and the low byte containing blue, per pixel. This data is packed row by row from the top-left to the bottom right.
  
  If the image has an alpha channel enabled there will be an extra alpha plane after the color pixel plane. If not, then this data will not exist and should not be accessed in any way. This plane is a set of pixels with 1 byte per pixel defining the alpha values of all pixels in the image from the top-left to the bottom right of the image, row by row. Even though the values of the alpha pixels can be 0 to 255, only values 0 through to 32 are used, 32 being solid and 0 being transparent.
  
  RGB values can be 0 to 31 for red and blue and 0 to 63 for green, with 0 being black and 31 or 63 being full red, green or blue respectively. This colorspace is also pre-multiplied like EVAS_COLORSPACE_ARGB8888 so:
  
  R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;

• EVAS_COLORSPACE_GRY8: The image is just a alpha mask (8 bit's per pixel). This is used for alpha masking.

Warning

We don't guarantee any proper results if you create a Image object without setting the evas engine.

Some examples on this group of functions can be found here.

Typedef Documentation

typedef enum _Evas_Colorspace Evas_Colorspace

Colorspaces for pixel data supported by Evas.

Colorspaces for pixel data supported by Evas

Enumeration Type Documentation

enum _Evas_Colorspace

Colorspaces for pixel data supported by Evas.

Enumerator
EVAS_COLORSPACE_ARGB8888	ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time.
EVAS_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
EVAS_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
EVAS_COLORSPACE_RGB565_A5P	16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte
EVAS_COLORSPACE_GRY8	8bit grayscale
EVAS_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
EVAS_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.
EVAS_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.
EVAS_COLORSPACE_AGRY88	AY 8bits Alpha and 8bits Grey, accessed 1 16bits at a time.
EVAS_COLORSPACE_ETC1	OpenGL ETC1 encoding of RGB texture (4 bit per pixel) Since 1.10
EVAS_COLORSPACE_RGB8_ETC2	OpenGL GL_COMPRESSED_RGB8_ETC2 texture compression format (4 bit per pixel) Since 1.10
EVAS_COLORSPACE_RGBA8_ETC2_EAC	OpenGL GL_COMPRESSED_RGBA8_ETC2_EAC texture compression format, supports alpha (8 bit per pixel) Since 1.10

Function Documentation

Eina_Bool evas_object_image_extension_can_load_get

(

const char *

file

)

Check if a file extension may be supported by Image Object Functions.

Parameters

file	The file to check

Returns

EINA_TRUE if we may be able to open it, EINA_FALSE if it's unlikely.

Since

1.1

If file is a Eina_Stringshare, use directly evas_object_image_extension_can_load_fast_get.

This functions is threadsafe.

References eina_stringshare_add(), and eina_stringshare_del().

Eina_Bool evas_object_image_extension_can_load_fast_get

(

const char *

file

)

Check if a file extension may be supported by Image Object Functions.

Parameters

file	The file to check, it should be an Eina_Stringshare.

Returns

EINA_TRUE if we may be able to open it, EINA_FALSE if it's unlikely.

Since

1.1

This functions is threadsafe.

Evas_Object* evas_object_image_add

(

Evas *

e

)

Creates a new image object on the given Evas e canvas.

Parameters

e	The given canvas.

Returns

The created image object handle.

Note

If you intend to display an image somehow in a GUI, besides binding it to a real image file/source (with evas_object_image_file_set(), for example), you'll have to tell this image object how to fill its space with the pixels it can get from the source. See evas_object_image_filled_add(), for a helper on the common case of scaling up an image source to the whole area of the image object.

See also

evas_object_image_fill_set()

Example:

img = evas_object_image_add(canvas);
evas_object_image_file_set(img, "/path/to/img", NULL);

Referenced by ecore_evas_cursor_set(), ecore_evas_ews_new(), ecore_evas_object_image_new(), and evas_object_image_filled_add().

Evas_Object* evas_object_image_filled_add

(

Evas *

e

)

Creates a new image object that automatically scales its bound image to the object's area, on both axis.

Parameters

e	The given canvas.

Returns

The created image object handle.

This is a helper function around evas_object_image_add() and evas_object_image_filled_set(). It has the same effect of applying those functions in sequence, which is a very common use case.

Note

Whenever this object gets resized, the bound image will be rescaled, too.

See also

evas_object_image_add()

evas_object_image_filled_set()

evas_object_image_fill_set()

Examples:

ecore_evas_buffer_example_02.c, edje-basic.c, edje-signals-messages.c, ephysics_logo.c, evas-aspect-hints.c, evas-box.c, evas-events.c, evas-hints.c, evas-images.c, evas-images2.c, evas-map-utils.c, evas-object-manipulation.c, evas-smart-interface.c, evas-smart-object.c, and evas-text.c.

References evas_object_image_add().

void evas_object_image_memfile_set	(	Evas_Object *	obj,
		void *	data,
		int	size,
		char *	format,
		char *	key
	)

Sets the data for an image from memory to be loaded.

This is the same as evas_object_image_file_set() but the file to be loaded may exist at an address in memory (the data for the file, not the filename itself). The data at the address is copied and stored for future use, so no data needs to be kept after this call is made. It will be managed and freed for you when no longer needed. The size is limited to 2 gigabytes in size, and must be greater than 0. A NULL data pointer is also invalid. Set the filename to NULL to reset to empty state and have the image file data freed from memory using evas_object_image_file_set().

The format is optional (pass NULL if you don't need/use it). It is used to help Evas guess better which loader to use for the data. It may simply be the "extension" of the file as it would normally be on disk such as "jpg" or "png" or "gif" etc.

Parameters

obj	The given image object.
data	The image file data address
size	The size of the image file data in bytes
format	The format of the file (optional), or NULL if not needed
key	The image key in file, or NULL.

References eina_file_close(), eina_file_virtualize(), and EINA_TRUE.

void evas_object_image_native_surface_set	(	Evas_Object *	obj,
		Evas_Native_Surface *	surf
	)

Set the native surface of a given image of the canvas.

Parameters

obj	The given canvas pointer.
surf	The new native surface.

This function sets a native surface of a given canvas image.

References EVAS_CALLBACK_DEL, evas_object_event_callback_add(), and evas_object_event_callback_del_full().

void evas_object_image_preload	(	Evas_Object *	obj,
		Eina_Bool	cancel
	)

Preload an image object's image data in the background.

Parameters

obj	The given image object.
cancel	EINA_FALSE will add it the preloading work queue, EINA_TRUE will remove it (if it was issued before).

This function requests the preload of the data image in the background. The work is queued before being processed (because there might be other pending requests of this type).

Whenever the image data gets loaded, Evas will call EVAS_CALLBACK_IMAGE_PRELOADED registered callbacks on obj (what may be immediately, if the data was already preloaded before).

Use EINA_TRUE for cancel on scenarios where you don't need the image data preloaded anymore.

Note

Any evas_object_show() call after evas_object_image_preload() will make the latter to be cancelled, with the loading process now taking place synchronously (and, thus, blocking the return of the former until the image is loaded). It is highly advisable, then, that the user preload an image with it being hidden, just to be shown on the EVAS_CALLBACK_IMAGE_PRELOADED event's callback.

Examples:

evas-images2.c.

Eina_Bool evas_object_image_source_unset

(

Evas_Object *

obj

)

Clear the source object on a proxy image object.

Parameters

obj	Image object to clear source of.

Returns

EINA_TRUE on success, EINA_FALSE on error.

This is equivalent to calling evas_object_image_source_set() with a NULL source.

References EINA_FALSE.

void evas_object_image_alpha_mask_set	(	Evas_Object *	obj,
		Eina_Bool	ismask
	)

Enable an image to be used as an alpha mask.

This will set any flags, and discard any excess image data not used as an alpha mask.

Note there is little point in using a image as alpha mask unless it has an alpha channel.

Parameters

obj	Object to use as an alpha mask.
ismask	Use image as alphamask, must be true.