Package evas :: Module c_evas :: Class Image

Class Image

object --+    
         |    
    Object --+
             |
            Image

Known Subclasses:

FilledImage

Image from file or buffer.

Introduction

Image will consider the object's geometry as the area to paint with tiles as described by fill_set() and the real pixels (image data) will be stored as described by image_size. This can be tricky to understand at first, but gives flexibility to do everything.

If an image is loaded from file, it will have image_size set to its original size, unless some other size was set with load_size_set(), load_dpi_set() or load_scale_down_set().

Pixels will be scaled to match size specified by fill_set() using either sampled or smooth methods, these can be specified with smooth_scale_set(). The scale will consider borders as specified by border_set() and border_center_fill_set(), while the former specify the border dimensions (top and bottom will scale horizontally, while right and left will do vertically, corners are kept unscaled), the latter says whenever the center of the image will be used (useful to create frames).

Contents will be tiled using fill_set() information in order to paint geometry, so if you want an image to be drawn just once, you should match every geometry_set(x, y, w, h) by a call to fill_set(0, 0, w, h). FilledImage does that for you.

Pixel data and buffer API

Images implement the Python Buffer API, so it's possible to use it where buffers are expected (ie: file.write()). Available data will depend on alpha, colorspace and image_size, lines should be considered multiple of stride, with the following considerations about colorspace:

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_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 31 are used, 31 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;
```

Note: if an image is resized it will tile it's contents respecting geometry set by fill_set(), so if you want the contents to be scaled you need to call fill_set() with x=0, y=0, w=new_width, h=new_height, or you should use FilledImage instead.

Instance Methods

[hide private]

__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

a new object with type S, a subtype of T

__new__(T, S, ...)

_set_common_params(...)
Set common parameters in one go.

tuple of str

file_get(...)

file_set(...)
Set the image to display a file.

tuple of int

fill_get(...)

fill_set(...)
Sets the rectangle that the image will be drawn to.

tuple of int

image_size_get(...)
Returns the original size of the image being displayed.

image_size_set(...)
Sets the size of the image to be displayed.

int

load_error_get(...)

on_image_preloaded_add(...)
Same as event_callback_add(EVAS_CALLBACK_IMAGE_PRELOADED, ...)

on_image_preloaded_del(...)
Same as event_callback_del(EVAS_CALLBACK_IMAGE_PRELOADED, ...)

preload(...)
Preload image data asynchronously.

reload(...)
Force reload of image data.

rotate(...)

save(...)
Save image to file.

bool

smooth_scale_get(...)

smooth_scale_set(...)
Enable or disalbe smooth scaling.

int

stride_get(...)
Get the row stride (in pixels) being used to draw this image.

Inherited from Object: __repr__, __str__, clipees_get, evas_get, name_get, name_set, on_changed_size_hints_add, on_changed_size_hints_del, on_del_add, on_del_del, parent_get, size_hint_align_get, size_hint_align_set, size_hint_aspect_get, size_hint_aspect_set, size_hint_max_get, size_hint_max_set, size_hint_min_get, size_hint_min_set, size_hint_padding_get, size_hint_padding_set, size_hint_request_get, size_hint_request_set, size_hint_weight_get, size_hint_weight_set, type_get

Inherited from Object (private): _set_evas

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Border settings

bool

border_center_fill_get(...)

border_center_fill_set(...)
Sets if the center part of an image (not the border) should be drawn

tuple of int

border_get(...)

border_set(...)
Sets how much of each border is not to be scaled.

Load settings

float

load_dpi_get(...)

load_dpi_set(...)
Set dots-per-inch to be used at image load time.

int

load_scale_down_get(...)

load_scale_down_set(...)
Set scale down loaded image by the given amount.

tuple of int

load_size_get(...)

load_size_set(...)
Set size you want image loaded.

Often unused

bool

alpha_get(...)

alpha_set(...)
Enable or disable alpha channel.

int

colorspace_get(...)

colorspace_set(...)
Set the colorspace of image data (pixels).

image_data_set(...)
Sets the raw image data.

image_data_update_add(...)
Mark a sub-region of the image to be redrawn.

bool

pixels_dirty_get(...)

pixels_dirty_set(...)
Mark or unmark pixels as dirty.

Inherited from Object: anti_alias_get, anti_alias_set, color_interpolation_get, color_interpolation_set, pointer_mode_get, pointer_mode_set, render_op_get, render_op_set

State manipulation

Inherited from Object: clip_get, clip_set, clip_unset, color_get, color_set, delete, hide, is_deleted, show, visible_get, visible_set

Positioning

Inherited from Object: bottom_left_get, bottom_left_set, bottom_right_get, bottom_right_set, center_get, center_set, geometry_get, geometry_set, move, move_relative, pos_get, pos_set, resize, size_get, size_set, top_left_get, top_left_set, top_right_get, top_right_set

Layer & Stack manipulation

Inherited from Object: above_get, below_get, bottom_get, layer_get, layer_set, lower, raise_, stack_above, stack_below, top_get

Event processing control

Inherited from Object: focus_get, focus_set, pass_events_get, pass_events_set, propagate_events_get, propagate_events_set, repeat_events_get, repeat_events_set

Event callbacks

Inherited from Object: event_callback_add, event_callback_del, on_focus_in_add, on_focus_in_del, on_focus_out_add, on_focus_out_del, on_free_add, on_free_del, on_hide_add, on_hide_del, on_hold_add, on_hold_del, on_key_down_add, on_key_down_del, on_key_up_add, on_key_up_del, on_mouse_down_add, on_mouse_down_del, on_mouse_in_add, on_mouse_in_del, on_mouse_move_add, on_mouse_move_del, on_mouse_out_add, on_mouse_out_del, on_mouse_up_add, on_mouse_up_del, on_mouse_wheel_add, on_mouse_wheel_del, on_move_add, on_move_del, on_resize_add, on_resize_del, on_restack_add, on_restack_del, on_show_add, on_show_del

Instance Variables

[hide private]

Inherited from Object: clipees, data, evas, name, parent, rect, type

Often unused

Inherited from Object: anti_alias, color_interpolation, pointer_mode, render_op

State manipulation

Inherited from Object: clip, color, visible

Positioning

Inherited from Object: bottom_left, bottom_right, center, geometry, pos, size, top_left, top_right

Layer & Stack manipulation

Inherited from Object: above, below, layer

Event processing control

Inherited from Object: focus, pass_events, propagate_events, repeat_events

Properties

[hide private]

file

fill

image_size

load_error

smooth_scale

stride

Inherited from Object: size_hint_align, size_hint_aspect, size_hint_max, size_hint_min, size_hint_padding, size_hint_request, size_hint_weight

Inherited from object: __class__

Border settings

border

border_center_fill

Load settings

load_dpi

load_scale_down

load_size

Often unused

alpha

colorspace

pixels_dirty

Method Details

[hide private]

init(...)
(Constructor)

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__

new(T, S, ...)

Returns: a new object with type S, a subtype of T
Overrides: object.__new__

_set_common_params(...)

Set common parameters in one go.

Overrides: Object._set_common_params: (inherited documentation)

border_center_fill_set(...)

Sets if the center part of an image (not the border) should be drawn

See Also: border_set()

When rendering, the image may be scaled to fit the size of the image object. This function sets if the center part of the scaled image is to be drawn or left completely blank. Very useful for frames and decorations.

border_set(...)

Sets how much of each border is not to be scaled.

When rendering, the image may be scaled to fit the size of the image object. This function sets what area around the border of the image is not to be scaled. This sort of function is useful for widget theming, where, for example, buttons may be of varying sizes, but the border size must remain constant.

colorspace_set(...)

Set the colorspace of image data (pixels).

May be one of (subject to engine implementation):

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 poitned 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 poitned 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.

file_set(...)

Set the image to display a file.

Raises:

EvasLoadError - on load error.

fill_set(...)

Sets the rectangle that the image will be drawn to.

Note that the image will be tiled around this one rectangle. To have only one copy of the image drawn, x and y must be 0 and w and h need to be the width and height of the object respectively.

The default values for the fill parameters is x = 0, y = 0, w = 1 and h = 1.

image_data_set(...)

Sets the raw image data.

The given buffer will be copied, so it's safe to give it a temporary object.

Note: that the raw data must be of the same size and colorspace of the image. If data is None the current image data will be freed.

image_data_update_add(...)

Mark a sub-region of the image to be redrawn.

This function schedules a particular rectangular region to be updated (redrawn) at the next render.

image_size_set(...)

Sets the size of the image to be displayed.

This function will scale down or crop the image so that it is treated as if it were at the given size. If the size given is smaller than the image, it will be cropped. If the size given is larger, then the image will be treated as if it were in the upper left hand corner of a larger image that is otherwise transparent.

This method will force pixels to be allocated if they weren't, so you should use this before accessing the image as a buffer in order to allocate the pixels.

This method will recalculate stride (stride_get()) based on width and the colorspace.

load_size_set(...)

Set size you want image loaded.

Loads image to the desired size, saving memory when loading large files.

preload(...)

Preload image data asynchronously.

This will request Evas to create a thread to load image data from file, decompress and convert to pre-multiplied format used internally.

This will emit EVAS_CALLBACK_IMAGE_PRELOADED event callback when it is done, see on_image_preloaded_add().

If one calls this function with cancel=True, then preload will be canceled and load will hapen when image is made visible.

If image is required before preload is done (ie: pixels are retrieved by user or when drawing), then it will be automatically canceled and load will be synchronous.

See Also: on_image_preloaded_add

stride_get(...)

Get the row stride (in pixels) being used to draw this image.

While image have logical dimension of width and height set by image_size_set(), the line can be a bit larger than width to improve memory alignment.

The amount of bytes will change based on colorspace, while using ARGB8888 it will be multiple of 4 bytes, with colors being laid out interleaved, RGB565_A5P will have the first part being RGB data using stride in multiple of 2 bytes and after that an alpha plane with data using stride in multiple of 1 byte.

Returns: int

Notes:

This value can change after image_size_set().
Unit is pixels, not bytes.

Class Image

Introduction

Pixel data and buffer API

__init__(...) (Constructor)

__new__(T, S, ...)

_set_common_params(...)

border_center_fill_set(...)

border_set(...)

colorspace_set(...)

file_set(...)

fill_set(...)

image_data_set(...)

image_data_update_add(...)

image_size_set(...)

load_size_set(...)

preload(...)

stride_get(...)

init(...)
(Constructor)

new(T, S, ...)