- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Evas filters reference

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:

- Syntax
- Buffer management
  - Colorspaces
  - Automatic buffers
  - BUFFER command
- Commands
  - BLEND command
  - BLUR command
  - GROW command
  - CURVE command
  - FILL command
  - MASK command
  - BUMP command
  - DISPLACE command
  - TRANSFORM command

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.

# Syntax

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:

- All whitespaces are discarded
- All commands are case-insensitive, except for the buffer and source names
- All dimensions are in pixels
- The commands will be executed in sequential order
- All commands must be terminated by a semicolon ';'
- Most commands have default values
- A command argument can either be set by name, or sequentially omitting the name (similarily to Python)
- Boolean values can be either 1/0, on/off, yes/no, enabled/disabled, true/false

Since the spaces are discarded, the above code is equivalent to:

buffer:fat(alpha);grow(5,dst=fat);blur(8,src=fat,color=darkblue);blur(4,color=cyan);blend();

### Special keywords and their values

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

- Booleans
  - 1/0, on/off, yes/no, enabled/disabled, true/false
- Color
  - Hexademical values: `#RRGGBB`, `#RRGGBBAA`, `#RGB`, `#RGBA`
  - 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.

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.

## Buffer command

buffer : name;
buffer : name (alpha);
buffer : name (rgba);
buffer : name (src = partname);

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.

Parameters

  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: `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.

See Also
  evas_obj_text_filter_source_set

Since
  1.9

# Filter commands

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

## 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

  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.

Since
  1.9

## Blur

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

blur (rx = 3, ry = -1, type = default, ox = 0, oy = 0, color = white, src = input, dst = output);

Parameters

  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:

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

  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.

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:

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

  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:

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:

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

  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.

### 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 (D.red * intensity / 128, D.green * intensity / 128)

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

  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:

- 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

  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.

Since
  1.9

## Mask

Blend two input buffers into a third (target).

mask (mask, src = input, dst = output, color = white, fillmode = none);

Parameters

  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.

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

  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.

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

Since
  1.9