Evas filters reference

This section will present the various filter instructions, their syntax and their effects.

Apply inverse color TODO: write down more information.

Remove color information from buffer's contents and leave only grayscale TODO: write down more information.

Warning
A new online documentation is available on the Wiki under EFL Graphics Filters. The documentation below is mostly still valid but incomplete. This page may be removed in the future.

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 and Image Objects.

The filters can be applied to an object using simple Lua scripts. A script will contain a series of buffer declarations and filter commands to apply to these buffers. The Lua programming language reference can be found here.

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 being Lua, it respects the usual Lua syntax and concepts. As these are simple filters, the scripts should be kept as small and simple as possible.

Note: Lua has been used since 1.10. The previous filters syntax is not guaranteed to be compatible with 1.10 and newer versions.

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 (embedded devices in mind).

Syntax

Here is a simple example illustrating the syntax:

fat = buffer ('alpha')
grow ({ 8, dst = fat })
blur ({ 12, src = fat, color = 'darkblue' })
blur ({ 4, color = 'cyan' })
blend ()

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:

  • All dimensions are in pixels
  • The commands will be executed in sequential order
  • Most commands have default values
  • A command argument can either be set by name, or sequentially omitting the name. So that:
    function (arg1, arg2, arg3) 
  • is equivalent to:
    function ({ arg1, arg2, arg2 }) 
  • or even (considering opt1, opt2 and opt3 are the first 3 arguments):
    function ({ opt1 = arg1, opt2 = arg2, opt3 = arg3 }) 
  • and since this is Lua, we can also write it as:
    function { arg1, opt3 = arg3, opt2 = arg2 } 
  • Boolean values are true/false but 1/0 and special string values are also accepted: 'yes'/'no', 'enabled'/'disabled'

Special keywords and their values

Some options accept a certain set of values (like enums):

  • color
    • Colors can be referred to by strings or integers:
    • An integer can refer to any RGB or ARGB values: 0xRRGGBB or 0xAARRGGBB. If alpha is zero, the color will be opaque (alpha = 0xFF), unless R=G=B=0 (invisible). These colors are not premultiplied.
    • Hexadecimal values: '#RRGGBB', '#RRGGBBAA', '#RGB', '#RGBA'
    • The following string values are also accepted:
      • 'white' == '#FFFFFF'
      • 'black' == '#000000'
      • 'red' == '#FF0000'
      • 'green' == '#008000'
      • 'blue' == '#0000FF'
      • 'darkblue' == '#0000A0'
      • 'yellow' == '#FFFF00'
      • 'magenta' == '#FF00FF'
      • 'cyan' == '#00FFFF'
      • 'orange' == '#FFA500'
      • 'purple' == '#800080'
      • 'brown' == '#A52A2A'
      • 'maroon' == '#800000'
      • 'lime' == '#00FF00'
      • 'gray' == '#808080'
      • 'grey' == '#808080'
      • 'silver' == '#C0C0C0'
      • 'olive' == '#808000'
      • 'invisible', 'transparent' == '#0000' – (alpha is zero)
  • fillmode
    • 'none'
    • 'stretch_x'
    • 'stretch_y'
    • 'repeat_x'
    • 'repeat_y'
    • 'repeat_x_stretch_y', 'stretch_y_repeat_x'
    • 'repeat_y_stretch_x', 'stretch_x_repeat_y'
    • 'repeat', 'repeat_xy'
    • 'stretch', 'stretch_xy'

Buffer management

The Evas filters subsystem is based on the concept of using various buffers as image layers and drawing or applying filters to these buffers. Think of it as how image drawing tools like The Gimp can combine multiple layers and apply operations on them.

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

Colorspaces and size

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.

Automatic buffers

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.

Since
1.9

Buffer command

Create a new buffer.

name1 = buffer()
name2 = buffer("alpha")
name3 = buffer("rgba")
name4 = buffer({ type = "rgba" })
name5 = buffer({ src = "partname" })
Parameters
typeBuffer type: rgba (default) or alpha
srcAn optional source. If set, type will be rgba.
Returns
A new buffer. This value must not be saved to a variable.

This creates a new named buffer, specify its colorspace or source. Possible options:

  • alpha: Create an alpha-only buffer (1 channel, no color)
  • rgba: Create an RGBA buffer (4 channels, full color)
  • {src = "partname"}: Use another Evas Object as source for this buffer's pixels. The name can either be an Edje part name or the one specified in evas_obj_text_filter_source_set.

If no option is given, an RGBA buffer will be created. All buffers have the same size, unless they are based on an external source.

See also
evas_obj_text_filter_source_set
Since
1.10

Filter commands

Blend

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.

blend ({ src = input, dst = output, ox = 0, oy = 0, color = 'white', fillmode = 'none' })
Parameters
srcSource buffer to blend.
dstDestination buffer for blending.
oxX offset. Moves the buffer to the right (ox > 0) or to the left (ox < 0) by N pixels.
oyY offset. Moves the buffer to the bottom (oy > 0) or to the top (oy < 0) by N pixels.
colorA 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.
fillmodeMap the input onto the whole surface of the output by stretching or repeating it. See fillmodes.
alphaonlyIf true, this means all RGBA->Alpha conversions discard the RGB components entirely, and only use the Alpha channel. False by default, which means RGB is used as Grey color level.

If src is an alpha buffer and dst is an RGBA buffer, then the color option should be set.

blend ({ color = '#3399FF' })
Since
1.9

Blur

Apply blur effect on a buffer (box or gaussian).

blur ({ rx = 3, ry = nil, type = 'default', ox = 0, oy = 0, color = 'white', src = input, dst = output })
Parameters
rxX radius. Specifies the radius of the blurring kernel (X direction).
ryY radius. Specifies the radius of the blurring kernel (Y direction). If -1 is used, then ry = rx.
typeBlur type to apply. One of default, box or gaussian. See below for details about default.
oxX offset. Moves the buffer to the right (ox > 0) or to the left (ox < 0) by N pixels.
oyY offset. Moves the buffer to the bottom (oy > 0) or to the top (oy < 0) by N pixels.
colorA 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.
srcSource buffer to blur.
dstDestination buffer for blending.
countNumber of times to repeat the blur. Only valid with box blur. Valid range is: 1 to 6.

The blur type default is recommended in all situations as it will select the smoothest and fastest operation possible depending on the kernel size. Instead of running a real gaussian blur, 2 or 3 box blurs may be chained to produce a similar effect at a much higher speed. The value count can be set to a value from 1 to 6 if blur type box has been specified.

The speedups of box over gaussian are of orders of 4x to more than 20x faster.

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:

blur ({ 10, color = 'black', oy = 5, ox = 5 })
blend ({ color = '#3399FF' })
Since
1.9

Bump

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.

bump ({ map, azimuth = 135.0, elevation = 45.0, depth = 8.0, specular = 0.0,
        color = 'white', compensate = false, src = input, dst = output,
        black = 'black', white = 'white', fillmode = 'repeat' })
Parameters
mapAn alpha buffer treated like a Z map for the light effect (bump map). Must be specified.
azimuthThe 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.
elevationThe 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.
depthThe depth of the object in an arbitrary unit. More depth means the shadows will be stronger. Default is 8.0.
specularAn arbitrary unit for the specular light effect. Default is 0.0, but a common value would be 40.0.
colorThe main color of the object if src is an alpha buffer. This represents the light's normal color. See colors.
compensateIf set to true, compensate for whitening or darkening on flat surfaces. Default is false but it is recommended if specular light is wanted.
srcSource buffer. This should be an alpha buffer.
dstDestination buffer. This should be an RGBA buffer (although alpha is supported). Must be of the same size as src.
blackThe shadows' color. Usually this will be black (#000).
whiteThe specular light's color. Usually this will be white (#FFF).
fillmodeThis specifies how to handle map when its dimensions don't match those of src and dst. Default is to repeat. See fillmodes.
Note
As of 2014/02/11, the ALPHA to RGBA support is of much better quality than ALPHA only, but very slow. RGBA sources are not supported yet.

Here is a full example of a very simple bevel effect:

a = buffer ('alpha')
blur ({ 5, dst = a })
bump ({ map = a, compensate = true, color = '#3399FF', specular = 10.0 })
Since
1.9

Curve

Apply a color curve to a specific channel in a buffer.

curve ({ points, interpolation = 'linear', channel = 'rgb', src = input, dst = output })

Modify the colors of a buffer. This applies a color curve y = f(x) to every pixel.

Parameters
pointsThe color curve to apply. See below for the syntax.
interpolationHow to interpolate between points. One of linear (y = ax + b) or none (y = Yk).
channelTarget 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.
srcSource buffer.
dstDestination 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:

curve ({ points = '0:0 - 255:255', interpolation = linear })

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:

a = buffer ('alpha')
blur ({ 4, dst = a })
curve ({ points = '0:0 - 20:0 - 60:255 - 160:255 - 200:0 - 255:0', src = a, dst = a })
blend ({ src = a, color = 'black' })

The curve command can be used to alter the output of a blur operation.

Since
1.9

Displace

Apply a displacement map on a buffer.

displace ({ map, intensity = 10, flags = 0, src = input, dst = output, fillmode = 'repeat' })
Parameters
mapAn RGBA buffer containing a displacement map. See below for more details.
intensityMaximum distance for the displacement. This means 0 and 255 will represent a displacement of intensity pixels.
flagsOne 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.
srcSource buffer
dstDestination buffer. Must be of same color format and size as src.
fillmodeDefines 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.

Displacement map

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:

D = map (x, y)
dst (x, y) = D.alpha * src (x + (D.red - 128) * intensity / 128, y + (D.green - 128) * intensity / 128) / 255 + (255 - D.alpha) * dst (x, y) / 255

Of course, the real algorithm takes into account interpolation between pixels as well.

Since
1.9

Fill

Fill a buffer with a specific color. Not blending, can be used to clear a buffer.

fill ({ dst = output, color = 'transparent', l = 0, r = 0, t = 0, b = 0 })
Parameters
dstTarget buffer to fill with color.
colorThe color used to fill the buffer. All pixels within the fill area will be reset to this value. See colors.
lLeft padding: skip l pixels from the left border of the buffer
rRight padding: skip r pixels from the right border of the buffer
tTop padding: skip t pixels from the top border of the buffer
bBottom padding: skip b pixels from the bottom border of the buffer

This function should generally not be used, except for:

  • Testing an effect over a specific background color
  • Clearing out a buffer with either white or transparent color
Since
1.9

Grow

Grow or shrink a buffer's contents. This is not a zoom effect.

grow ({ radius, smooth = true, src = input, dst = output })
Parameters
radiusThe radius of the grow kernel. If a negative value is specified, the contents will shrink rather than grow.
smoothIf true, use a smooth transitions between black and white (smooth blur and smoother curve).
srcSource buffer to blur.
dstDestination buffer for blending. This must be of same size and colorspace as src.

Example:

fat = buffer ('alpha')
grow ({ 8, dst = fat })
blend ({ src = fat, color = 'black' })
blend ({ color = '#3399FF' })

This will first grow the letters in the buffer input by a few pixels, and then draw this buffer in black in the background.

Since
1.9

Mask

Blend two input buffers into a third (target).

mask ({ mask, src = input, dst = output, color = 'white', fillmode = 'repeat' })
Parameters
maskA mask or texture to blend with the input src into the target dst.
srcSource buffer. This can also be thought of a mask if src is alpha and mask is RGBA.
dstDestination buffer for blending. This must be of same size and colorspace as src.
colorA 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.
fillmodeDefines whether to stretch or repeat the mask if its size that of src. Should be set when masking with external textures. Default is repeat. See fillmodes.

Note that src and mask are interchangeable, if they have the same dimensions.

Example:

a = buffer ('alpha')
blur ({ 6, dst = a })
curve ({ points = '0:255 - 128:255 - 255:0', src = a, dst = a })
blend ({ color = 'yellow' })
mask ({ mask = a, color = 'black' })

This will create an inner shadow effect.

Since
1.9

Transform

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.

transform ({ dst, op = 'vflip', src = input, oy = 0 })
Parameters
dstDestination buffer. Must be of the same colorspace as src. Must be specified.
opMust be 'vflip'. There is no other operation yet.
srcSource buffer to transform.
oyY offset.

Example:

t = buffer ('alpha')
transform ({ oy = 20, dst = t })
blend ({ src = t, color = 'silver' })
blend ({ color = 'black' })

This will create a mirrored text effect, for a font of 50px.

Note
Because of the meaning of oy, this effect probably needs to be customized for a single font size (FIXME).
Since
1.9

Padding_Set

Forcily set a specific padding for this filter.

padding_set ({ l, r = [l], t = [r], b = [t] })
Parameters
lPadding on the left side in pixels.
rPadding on the right side in pixels. If unset, defaults to l.
tPadding on the top in pixels. If unset, defaults to r.
bPadding on the bottom in pixels. If unset, defaults to t.

All values must be >= 0. When filtering 'filled' images, some values may be too high and would result in completely hiding the image.

It is not possible to set only one of those without forcing the others as well. A common use case will be when changing a blur size during an animation, or when applying a mask that will hide most of the (blurred) text.

Example (the fill command is used for illustration purposes):

fat = buffer ('alpha')
padding_set ({ l = 10, r = 20, t = 15, b = 25 })
fill ({ color = 'black' })
fill ({ color = 'darkblue', l = 2, r = 2, t = 2, b = 2 })
grow ({ 30, dst = fat })
blur ({ 40, src = fat, color = 'white' })
blend ({ color = 'darkblue' })

This will set the left, right, top and bottom paddings to their respective values, and some effects may look like they've been "clipped" out.

Since
1.10