The Evas filters are a combination of filters used to apply specific effects to an Evas Object.
For the moment, these effects are specific to the Text Objects.
The filters can be applied to an object using a simple script language specifically designed for these effects. A script will contain a series of buffer declarations and filter commands to apply to these buffers.
Basically, when applying an effect to a Text Object, an alpha-only input
buffer is created, where the text is rendered, and an RGBA output
buffer is created, where the text with effects shall be finally rendered.
The script language is case insensitive, except for the buffer names. All spaces will be discarded during parsing.
Here are the available commands:
All the examples in this page can (should) be directly used in evas_obj_text_filter_program_set.
Note that most of the text effects work better with larger font sizes (> 50px), and so do the examples in this page.
Here is a simple example illustrating the syntax:
This example will display a cyan and dark blue glow surrounding the main text (its color depends on the object's theme).
The syntax is pretty simple and follows a small set of rules:
Since the spaces are discarded, the above code is equivalent to:
Some options accept a certain set of values (like enums):
#RRGGBB
, #RRGGBBAA
, #RGB
, #RGBA
#FFFFFF
#000000
#FF0000
#008000
#0000FF
#0000A0
#FFFF00
#FF00FF
#00FFFF
#FFA500
#800080
#A52A2A
#800000
#00FF00
#808080
#808080
#C0C0C0
#808000
#0000
(alpha is zero) The Evas filters subsystem is based on the concept of using various buffers as image layers and drawing or applying filters to these buffers.
Most of the buffers are allocated automatically at runtime, depending on the various inputs and commands used (eg. 2-D blur will require a temporary intermediate buffer).
The buffers' size will be automatically defined at runtime, based on the content of the input and the series of operations to apply (eg. blur adds some necessary margins).
The buffers can be either ALPHA (1 color channel only) or RGBA (full color). Some operations might require specifically an ALPHA buffer, some others RGBA.
Most buffers will have the same size, except those specified by an external source.
The two most important buffers, input and output, are statically defined and always present when running a filter. input is an ALPHA buffer, containing the Text Object's rendered text, and output is the final target on which to render as RGBA.
Some operations, like 2-D blur might require temporary intermediate buffers, that will be allocated automatically. Those buffers are internal only and can't be used from the script.
Finally, if a buffer is created using another Evas Object as source (see buffer for more details), its pixel data will be filled by rendering the Evas Object into this buffer. This is how it will be possible to load external images, textures and even animations into a buffer.
The "buffer" instruction is a special command used to declare a new buffer in the filters context. This buffer can be either ALPHA, RGBA or based on an other Evas Object (proxy source). If no option is given, an RGBA buffer will be created.
name | An alpha-numerical name, starting with a letter (a-z, A-Z). Can not be input or output , as these are reserved names. Must be unique. |
(args) | [alpha] OR [rgba] OR [src = partname] Create a new named buffer, specify its colorspace or source. Possible options:
|
This section will present the various filter instructions, their syntax and their effects.
Blend a buffer onto another. This is the simplest filter, as it just renders one buffer on another, potentially using a color, an offset and fill options.
src | Source buffer to blend. |
dst | Destination buffer for blending. |
ox | X offset. Moves the buffer to the right (ox > 0) or to the left (ox < 0) by N pixels. |
oy | Y offset. Moves the buffer to the bottom (oy > 0) or to the top (oy < 0) by N pixels. |
color | A color to use for alpha to RGBA conversion. See colors. If the input is an alpha buffer and the output is RGBA, this will draw the buffer in this color. If both buffers are RGBA, this will have no effect. |
fillmode | Map the input onto the whole surface of the output by stretching or repeating it. See fillmodes. |
If src is an alpha buffer and dst is an RGBA buffer, then the color option should be set.
Apply blur effect on a buffer (box or gaussian).
rx | X radius. Specifies the radius of the blurring kernel (X direction). |
ry | Y radius. Specifies the radius of the blurring kernel (Y direction). If -1 is used, then ry = rx. |
type | Blur type to apply. One of default , box or gaussian . default is an alias for gaussian . |
ox | X offset. Moves the buffer to the right (ox > 0) or to the left (ox < 0) by N pixels. |
oy | Y offset. Moves the buffer to the bottom (oy > 0) or to the top (oy < 0) by N pixels. |
color | A color to use for alpha to RGBA conversion. See colors. If the input is an alpha buffer and the output is RGBA, this will draw the buffer in this color. |
src | Source buffer to blur. |
dst | Destination buffer for blending. |
If src is an alpha buffer and dst is an RGBA buffer, then the color option should be set.
ox and oy can be used to move the blurry output by a few pixels, like a drop shadow. Example:
Apply a light effect (ambient light, specular reflection and shadows) based on a bump map.
This can be used to give a relief effect on the object.
map | An alpha buffer treated like a Z map for the light effect (bump map). Must be specified. |
azimuth | The angle between the light vector and the X axis in the XY plane (Z = 0). 135.0 means 45 degrees from the top-left. Counter-clockwise notation. |
elevation | The angle between the light vector and the Z axis. 45.0 means 45 degrees to the screen's plane. Ranges from 0 to 90 only. |
depth | The depth of the object in an arbitrary unit. More depth means the shadows will be stronger. Default is 8.0. |
specular | An arbitrary unit for the specular light effect. Default is 0.0, but a common value would be 40.0. |
color | The main color of the object if src is an alpha buffer. This represents the light's normal color. See colors. |
compensate | If set to true, compensate for whitening or darkening on flat surfaces. Default is false but it is recommended if specular light is wanted. |
src | Source buffer. This should be an alpha buffer. |
dst | Destination buffer. This should be an RGBA buffer (although alpha is supported). Must be of the same size as src. |
black | The shadows' color. Usually this will be black (#000 ). |
white | The specular light's color. Usually this will be white (#FFF ). |
fillmode | This specifies how to handle map when its dimensions don't match those of src and dst. Default is to repeat . See fillmodes. |
Here is a full example of a very simple bevel effect:
Apply a color curve to a specific channel in a buffer.
Modify the colors of a buffer. This applies a color curve y = f(x) to every pixel.
points | The color curve to apply. See below for the syntax. |
interpolation | How to interpolate between points. One of linear (y = ax + b) or none (y = Yk). |
channel | Target channel for the color modification. One of R(ed) , G(reen) , B(lue) , A(lpha) , RGB and RGBA . If src is an alpha buffer, this parameter will be ignored. |
src | Source buffer. |
dst | Destination buffer, must be of same dimensions and color space as src. |
The points argument contains a list of (X,Y) points in the range 0..255, describing a function f(x) = y
to apply to all pixel values.
The syntax of this points string is x1:y1 - x2:y2 - x3:y3 - ... - xn:yn
(remember that all spaces are discarded). The points xn
are in increasing order: x1 < x2 < x3 < ... < xn
, and all values xn
or yn
are within the range 0..255.
The identity curve is then described as 0:0-255:255
, with linear interpolation:
If ignored, y(x = 0) is 0 and y(x = 255) is 255.
The following example will generate a 4px thick stroke around text letters:
The curve command can be used to alter the output of a blur operation.
Apply a displacement map on a buffer.
map | An RGBA buffer containing a displacement map. See below for more details. |
intensity | Maximum distance for the displacement. This means 0 and 255 will represent a displacement of intensity pixels. |
flags | One of default , nearest , smooth , nearest_stretch or smooth_stretch . This defines how pixels should be treated when going out of the src image bounds. default is equivalent to smooth_stretch . |
src | Source buffer |
dst | Destination buffer. Must be of same color format and size as src. |
fillmode | Defines how to handle cases where the map has a different size from src and dst. It should be a combination of stretch or repeat: none is not supported. See fillmodes. |
The map buffer is an RGBA image containing displacement and alpha values. Its size can be different from src
or dst
.
The red channel is used for X displacements while the green channel is used for Y displacements. All subpixel values are in the range 0..255. A value of 128 means 0 displacement, lower means displace to the top/left and higher than 128 displace to the bottom/right.
If signed char
is used instead of unsigned char
to represent these R and G values, then < 0 means displace top/left while > 0 means bottom/right.
The alpha
channel is used as an alpha multiplier for blending.
Considering I(x, y)
represents the pixel at position (x, y) in the image I, then here is how the displacement is applied to dst:
Of course, the real algorithm takes into account interpolation between pixels as well.
Fill a buffer with a specific color. Not blending, can be used to clear a buffer.
dst | Target buffer to fill with color. |
color | The color used to fill the buffer. All pixels within the fill area will be reset to this value. See colors. |
l | Left padding: skip l pixels from the left border of the buffer |
r | Right padding: skip r pixels from the right border of the buffer |
t | Top padding: skip t pixels from the top border of the buffer |
b | Bottom padding: skip b pixels from the bottom border of the buffer |
This function should generally not be used, except for:
Grow or shrink a buffer's contents. This is not a zoom effect.
radius | The radius of the grow kernel. If a negative value is specified, the contents will shrink rather than grow. |
smooth | If true , use a smooth transitions between black and white (smooth blur and smoother curve). |
src | Source buffer to blur. |
dst | Destination buffer for blending. This must be of same size and colorspace as src. |
Example:
This will first grow the letters in the buffer input
by a few pixels, and then draw this buffer in black in the background.
Blend two input buffers into a third (target).
mask | A mask or texture to blend with the input src into the target dst. |
src | Source buffer. This can also be thought of a mask if src is alpha and mask is RGBA. |
dst | Destination buffer for blending. This must be of same size and colorspace as src. |
color | A color to use for alpha to RGBA conversion for the blend operations. White means no change. See colors. This will have no effect on RGBA sources. |
fillmode | Defines whether to stretch or repeat the mask if its size that of . Should be set when masking with external textures. Default is none. See fillmodes. |
Note that src and mask are interchangeable, if they have the same dimensions.
Example:
This will create an inner shadow effect.
Apply a geometrical transformation to a buffer.
Right now, only vertical flip is implemented and available. This operation does not blend and assumes the destination buffer is empty.
dst | Destination buffer. Must be of the same colorspace as src. Must be specified. |
op | Must be vflip . There is no other operation yet. |
src | Source buffer to transform. |
oy | Y offset. |
Example:
This will create a mirrored text effect, for a font of 50px.