efl.evas.Image
Class¶efl.evas.
Image
(Canvas canvas, file=None, **kwargs)¶Bases: efl.evas.Object
Introduction
Image will consider the object’s geometry
as the area to paint with tiles as described by fill
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
, load_dpi
or
load_scale_down
.
Pixels will be scaled to match size specified by fill
using
either sampled or smooth methods, these can be specified with
smooth_scale
. The scale will consider borders as specified by
border
and border_center_fill
, 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
information in order to paint
geometry
, so if you want an image to be drawn
just once, you should match every geometry
= x, y, w, h by a
call to fill
= 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:
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.
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
, so if you want the contents to be
scaled you need to call fill
with x=0, y=0, w=new_width,
h=new_height
, or you should use FilledImage
instead.
Parameters: |
|
---|
alpha
¶Enable or disable alpha channel.
Type: | bool |
---|
alpha_get
()¶alpha_mask
¶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.
Type: | bool |
---|
alpha_mask_set
(ismask)¶alpha_set
(value)¶animated
¶Check if an image object can be animated (have multiple frames)
Type: | bool |
---|
This returns if the image file of an image object is capable of animation such as an animated gif file might. This is only useful to be called once the image object file has been set.
Example:
obj = Image(mycanvas, file="my_animated_file.gif")
if obj.animated:
print("This image has %d frames" % (obj.animated_frame_count,))
print("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer." % (obj.animated_frame_duration_get(1, 0)))
print("Loop count is %d. You had better run loop %d times." % (obj.loop_count, obj.loop_count))
loop_type = obj.animated_loop_type
if loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP:
print("You had better set frame like 1->2->3->1->2->3...")
elif loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG:
print("You had better set frame like 1->2->3->2->1->2...")
else:
print("Unknown loop type.")
obj.animated_frame = 1
print("You set image objects frame to 1. You can see frame 1.")
animated_frame
¶Set the frame to current frame of an image object
Type: | int |
---|
This set image object’s current frame to frame_num with 1 being the first frame.
animated_frame_count
¶Get the total number of frames of the image object.
Type: | int |
---|
This returns total number of frames the image object supports (if animated)
animated_frame_count_get
()¶animated_frame_duration_get
(start_frame, fram_num)¶Get the duration of a sequence of frames.
Parameters: |
|
---|---|
Returns: | The duration of a sequence of frames. |
Return type: | double |
This returns total duration that the specified sequence of frames should take in seconds.
If you set start_frame to 1 and frame_num 0, you get frame 1’s duration If you set start_frame to 1 and frame_num 1, you get frame 1’s duration + frame2’s duration
animated_frame_set
(frame_num)¶animated_get
()¶animated_loop_count
¶Get the number times the animation of the object loops.
Type: | int |
---|
This returns loop count of image. The loop count is the number of times the animation will play fully from first to last frame until the animation should stop (at the final frame).
If 0 is returned, then looping should happen indefinitely (no limit to the number of times it loops).
animated_loop_count_get
()¶animated_loop_type
¶Get the kind of looping the image object does.
Type: | Evas_Image_Animated_Loop_Hint |
---|
This returns the kind of looping the image object wants to do.
If it returns EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like: 1->2->3->1->2->3->1... If it returns EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to display frames in a sequence like: 1->2->3->2->1->2->3->1...
The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP.
animated_loop_type_get
()¶border
¶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 property reflects what area around the border of the image is not to be scaled. This is useful for widget theming, where, for example, buttons may be of varying sizes, but the border size must remain constant.
Type: | (int l, int r, int t, int b) |
---|
border_center_fill
¶If the center part of an image (not the border) should be drawn
See also
When rendering, the image may be scaled to fit the size of the image object. This property reflects if the center part of the scaled image is to be drawn or left completely blank. Very useful for frames and decorations.
Type: | bool |
---|
border_center_fill_get
()¶border_center_fill_set
(value)¶border_get
()¶border_scale
¶The scaling factor (multiplier) for the borders of an image object.
Default is 1.0 - i.e. no scaling
Type: | double |
---|---|
See: | border |
border_scale_get
()¶border_scale_set
(scale)¶border_set
(left, right, top, bottom)¶colorspace
¶The colorspace of image data (pixels).
May be one of (subject to engine implementation):
Alpha, accessed 1 32bit word at a time.
Type: | Evas_Colorspace |
---|
colorspace_get
()¶colorspace_set
(value)¶content_hint
¶The content hint value of the given image of the canvas.
For example, if you’re on the GL engine and your driver implementation
supports it, setting this hint to EVAS_IMAGE_CONTENT_HINT_DYNAMIC
will
make it need zero copies at texture upload time, which is an “expensive”
operation.
Type: | Evas_Image_Content_Hint |
---|
content_hint_get
()¶content_hint_set
(hint)¶file
¶Set the image to display a file.
Type: | unicode filename or (unicode filename, unicode key) |
---|---|
Raises EvasLoadError: | |
on load error. |
file_get
()¶file_set
(filename, key=None)¶fill
¶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.
Type: | (int x, int y, int w, int h) |
---|
fill_get
()¶fill_set
(x, y, w, h)¶fill_spread
¶The tiling mode for the given evas image object’s fill.
One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT, EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
Type: | Evas_Fill_Spread |
---|
fill_spread_get
()¶fill_spread_set
(spread)¶filled
¶Whether the image object’s fill property should track the object’s size.
If True, then every efl.evas.Object.resize()
will
automatically assign a value to fill
with the that new size (and 0, 0
as source image’s origin),
so the bound image will fill the whole object’s area.
Type: | bool |
---|
See also
filled_get
()¶filled_set
(setting)¶image_data_set
(buf)¶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.
Parameters: | buf – The buffer |
---|
image_data_update_add
(x, y, w, h)¶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.
Parameters: |
|
---|
image_size
¶The size of the image to be displayed.
Assigning to this property 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 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 will recalculate stride
based on
width and the colorspace.
Type: | (int w, int h) |
---|
image_size_get
()¶image_size_set
(w, h)¶load_dpi
¶Dots-per-inch to be used at image load time.
Type: | double |
---|
load_dpi_get
()¶load_dpi_set
(value)¶load_error
¶The load error.
Type: | int |
---|
load_error_get
()¶load_orientation
¶Define if the orientation information in the image file should be honored.
Type: | bool |
---|
load_orientation_get
()¶load_orientation_set
(enable)¶load_region
¶Inform a given image object to load a selective region of its source image.
Type: | (int x, int y, int w, int h) |
---|
This is useful when one is not showing all of an image’s area on its image object.
Note
The image loader for the image format in question has to support selective region loading in order to this function to take effect.
load_region_get
()¶load_region_set
(x, y, w, h)¶load_scale_down
¶Scale down loaded image by the given amount.
Type: | int |
---|
load_scale_down_get
()¶load_scale_down_set
(value)¶load_size
¶The size you want image loaded.
Loads image to the desired size, saving memory when loading large files.
Type: | (int w, int h) |
---|
load_size_get
()¶load_size_set
(w, h)¶on_image_preloaded_add
(func, *a, **k)¶Same as event_callback_add(EVAS_CALLBACK_IMAGE_PRELOADED, ...)
on_image_preloaded_del
(func)¶Same as event_callback_del(EVAS_CALLBACK_IMAGE_PRELOADED, ...)
on_image_unloaded_add
(func, *a, **k)¶Same as event_callback_add(EVAS_CALLBACK_IMAGE_UNLOADED, ...)
on_image_unloaded_del
(func)¶Same as event_callback_del(EVAS_CALLBACK_IMAGE_UNLOADED, ...)
orient
¶The image orientation.
This allows to rotate or flip the image.
Type: | Evas_Image_Orient |
---|
New in version 1.14.
orient_get
()¶orient_set
(orient)¶pixels_dirty
¶Mark or unmark pixels as dirty.
Type: | bool |
---|
pixels_dirty_get
()¶pixels_dirty_set
(value)¶preload
(cancel=0)¶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 happen 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.
Parameters: | cancel (bool) – if True, will cancel preload request. |
---|
region_support
¶Region support state
Type: | bool |
---|
region_support_get
()¶reload
()¶Force reload of image data.
save
(filename, key=None, flags=None)¶Save image to file.
Parameters: |
|
---|
scale_hint
¶The scale hint value of the image object in the canvas, which will affect how Evas is to cache scaled versions of its original source image.
Type: | Evas_Image_Scale_Hint |
---|
scale_hint_get
()¶scale_hint_set
(hint)¶smooth_scale
¶Enable or disable smooth scaling.
Type: | bool |
---|
smooth_scale_get
()¶smooth_scale_set
(value)¶source
¶The source object on an image object to used as a proxy.
If an image object is set to behave as a proxy, it will mirror the rendering contents of a given source object in its drawing region, without affecting that source in any way. The source must be another valid Evas object. Other effects may be applied to the proxy, such as a map (see evas_object_map_set()) to create a reflection of the original object (for example).
Any existing source object on obj
will be removed after this
call. Setting src
to NULL
clears the proxy object (not in
“proxy state” anymore).
Type: | Object |
---|---|
Raises RuntimeError: | |
if source could not be (un)set. |
Warning
You cannot set a proxy as another proxy’s source.
See also
source_events
¶Whether an Evas object is to repeat events to source.
If True, it will make events on the object to also be repeated for the source object. When the object and source geometries are different, the event position will be transformed to the source object’s space.
If False, events occurring on the object will be processed only on it.
Type: | bool |
---|
See also
New in version 1.8.
source_events_get
()¶source_events_set
(source)¶source_get
()¶source_set
(src)¶source_unset
()¶source_visible
¶Whether the source object is visible or not.
If set to False, the source object of the proxy will be invisible.
This API works differently to show()
and
hide()
. Once source object is hidden by
hide()
then the proxy object will be hidden as
well. Actually in this case both objects are excluded from the Evas
internal update circle.
By this API, instead, one can toggle the visibility of a proxy’s source object remaining the proxy visibility untouched.
Type: | bool |
---|
Warning
If the all of proxies are deleted, then the source visibility of the source object will be cancelled.
See also
New in version 1.8.
source_visible_get
()¶source_visible_set
(visible)¶stride
¶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
, 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.
Note
This value can change after setting image_size
.
Note
Unit is pixels, not bytes.
Type: | int |
---|
stride_get
()¶efl.evas.FilledImage
Class¶efl.evas.
FilledImage
(Canvas canvas, **kargs)¶Bases: efl.evas.Image
This Image
subclass already calls Image.fill
on resize so it will match and so be scaled to fill the whole area.
Parameters: |
|
---|
fill_set
(x, y, w, h)¶Not available for this class.