====== EFL Graphics Filters ======
Supported since 1.15.
This page presents an overview of [[Efl.Gfx.Filter]] used for advanced text effects and basic image filtering.
Since 1.19 textblock also supports filters by using the "gfx_filter" format tag. Since 1.20 most filters have GL acceleration.
===== Functions =====
Summary of the supported filtering functions:
*[[:develop:efl:advanced:eflgfxfilter:blend|blend]]
*[[:develop:efl:advanced:eflgfxfilter:blur|blur]]
*[[:develop:efl:advanced:eflgfxfilter:grow|grow]]
*[[:develop:efl:advanced:eflgfxfilter:curve|curve]]
*[[:develop:efl:advanced:eflgfxfilter:fill|fill]]
*[[:develop:efl:advanced:eflgfxfilter:mask|mask]]
*[[:develop:efl:advanced:eflgfxfilter:bump|bump]]
*[[:develop:efl:advanced:eflgfxfilter:displace|displace]]
*[[:develop:efl:advanced:eflgfxfilter:transform|transform]]
*[[:develop:efl:advanced:eflgfxfilter:buffer|buffer]]
*[[:develop:efl:advanced:eflgfxfilter:padding_set|padding_set]]
*[[:develop:efl:advanced:eflgfxfilter:state|state]]
===== Core concepts =====
The Eo class [[Efl.Gfx.Filter]] provides an interface for Evas objects (currently only [[Evas.Text]] and [[Evas.Image]]) to alter their appearance by applying a series of filtering operations. Filtered objects will be rendered in internal surfaces and transformed before being drawn on the canvas. Objects without a filter are rendered directly on the canvas.
EFL provides a set of standard core filters that can be combined by using a simple script. Custom filters can be written in [[http://www.lua.org/|Lua (5.1)]] and can be a combinaison of any number of the base filters presented below.
==== Input, output and buffers ====
The filters work by taking an ''input'' buffer (or image), applying some effects on it, and drawing the result to an ''output'' buffer. This final image is rendered on the canvas.
Since [[Efl.Gfx.Filter]] works on both [[Evas.Image]] and [[Evas.Text]] objects, the ''input'' buffer can contain respectively a scaled copy of the source image (RGBA), or the text string rendered as an Alpha-only buffer, like this:
{{:docs:efl:advanced:filter-input.png|}}
=== Buffer management ===
It is also possible to manually create more buffers using the [[:develop:efl:advanced:eflgfxfilter:buffer|buffer]] function.
Read more [[:develop:efl:advanced:eflgfxfilter:buffer|here]].
=== Padding ===
Since the filters may modify pixels based on their neighbors (blur) or move pixels around (displace, transform), a filter ends up requiring the input buffer to be padded to avoid cropping of the effect. The filter engine will automatically compute the necessary padding for you, but this may be too much in some situations (eg. blur 10 + blur 20 will add a padding of 30 but most pixels will be blank).
You can set the padding to a fixed value with the [[:develop:efl:advanced:eflgfxfilter:padding|padding_set]] command.
==== Base filters ====
The following table lists all the core filter functions, applied to an [[Evas.Text]] object.
^ Feature ^ Function ^ Example ^
| [[:develop:efl:advanced:eflgfxfilter:blend|Blend]] | ''blend'' | {{ :docs:efl:advanced:filter-blend.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:blur|Blurs, glows and shadows]] | ''blur'' | {{ :docs:efl:advanced:filter-blur.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:grow|Grow and shrink]] | ''grow'' | {{ :docs:efl:advanced:filter-grow.png |}} {{ :docs:efl:advanced:filter-shrink.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:curve|Color curves]] | ''curve'' | {{ :docs:efl:advanced:filter-curve.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:fill|Solid color fill]] | ''fill'' | {{ :docs:efl:advanced:filter-fill.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:mask|Masking and texturing]] | ''mask'' | {{ :docs:efl:advanced:filter-mask.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:bump|Bump maps]] | ''bump'' | {{ :docs:efl:advanced:filter-bump.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:displace|Displacement maps]] | ''displace'' | {{ :docs:efl:advanced:filter-displace.png |}} |
| [[:develop:efl:advanced:eflgfxfilter:transform|Transformation]] | ''transform'' | {{ :docs:efl:advanced:filter-transform.png |}} |
==== Complex filters ====
Graphics filters in EFL can be described by short Lua scripts. Various graphics buffers can be combined and mixed together using other objects from the canvas as sources.
=== Example 1 ===
{{:docs:efl:advanced:filter1.png|}}
Here is an example of a very simple filter using only the ''blur'' and ''grow'' functions:
blur { 10, color = '#009' }
blur { 4, color = '#f00' }
grow { -4 }
Step by step, this is how Evas generates the final output.
- First, we ask Evas to blur the input by 10 pixels, and use the color ''#009'', which is equivalent to ''#000099'' or ''rgba(0, 0, 0x99, 0xff)''.
- Then we do the same operation with a 4-pixels radius and the red color.
- Finally we use a shrinking algorithm (grow with a negative radius) and blend on top with the default color (here, white).
^ Input ^ Step 1 ^ Step 2 ^ Step 3 ^
| {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter1-1.png |}} | {{ :docs:efl:advanced:filter1-2.png |}} | {{ :docs:efl:advanced:filter1.png |}} |
=== Example 2 ===
{{:docs:efl:advanced:filter2.png|}}
The Evas filter system is based around the use of various //"buffers"//, which can be either Alpha masks or full RGBA color images. The following example uses an intermediate buffer to store the output of the ''grow'' command, and use that as input for the ''blur'' command:
a = buffer { 'alpha' } -- step 1
grow { 6, dst = a } -- step 2
blur { 4, src = a, color = '#009' } -- step 3
blend { src = input } -- step 4
Step by step, this is what happens to the contents of our buffers.
^ Step ^ ''input'' ^ ''a'' ^ ''output'' ^
| Step 1 | {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter-bg-full.png |}} | {{ :docs:efl:advanced:filter-bg-full.png |}} |
| Step 2 | {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter2-a.png |}} | {{ :docs:efl:advanced:filter-bg-full.png |}} |
| Step 3 | {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter2-a.png |}} | {{ :docs:efl:advanced:filter2-3.png |}} |
| Step 4 | {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter2-a.png |}} | {{ :docs:efl:advanced:filter2.png |}} |