Add documentation about evas filters
Big commit squash from a local dokuwiki
This commit is contained in:
Admin
Jean-Philippe Andre
parent
9e17fdff4d
commit
04e58440e4
|
|
@ -0,0 +1,24 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== 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.
|
||||
|
||||
<code Lua>
|
||||
blend ({ src = input, dst = output, ox = 0, oy = 0, color = 'white', fillmode = 'none' })
|
||||
</code>
|
||||
|
||||
== 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 multiply the colors. |
|
||||
| ''fillmode'' |Map the input onto the whole surface of the output by stretching or repeating it. See [[fillmodes]]. |
|
||||
|
||||
== Example ==
|
||||
|
||||
<code Lua>
|
||||
blend ({ color = '#fff8' })
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-blend.png|}}
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Blur ====
|
||||
|
||||
Applies a [[https://en.wikipedia.org/wiki/Gaussian_blur|gaussian blur]] or [[https://en.wikipedia.org/wiki/Box_blur|box blur]] filter to a buffer and blends it onto a destination buffer.
|
||||
|
||||
Blurs can be used to create **drop shadows** and **glow** effects.
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
blur ({ rx = 3, ry = nil, type = 'default', ox = 0, oy = 0, color = 'white', src = input, dst = output })
|
||||
</code>
|
||||
|
||||
== 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. See below for details about default. |
|
||||
|''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. |
|
||||
|''count'' |Number of times to repeat the blur. Only valid with box blur. Valid range is: 1 to 6 |
|
||||
|
||||
== Notes ==
|
||||
|
||||
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 (very slow), 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.
|
||||
|
||||
== Examples ==
|
||||
|
||||
<code Lua blur.lua>
|
||||
blur { 15 }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-blur.png|}}
|
||||
|
||||
<code Lua dropshadow.lua>
|
||||
blur { 10, ox = 5, oy = 5, color = 'black' }
|
||||
blend {}
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-dropshadow.png|}}
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Buffer ====
|
||||
|
||||
Apart from the predefined buffers ''input'' and ''output'', buffers can also be created using the ''buffer'' command, and their contents will either be transparency (all pixels are ''rgba(0,0,0,0)'') or they will reflect the contents of another [[Evas.Object]]. The latter case can be used to import external images and textures into a filter.
|
||||
|
||||
All buffers have the same size unless they come from an external source, in which case their size is equal to the geometry of the [[Evas.Object]].
|
||||
|
||||
Buffers are either Alpha surfaces (8 bit, values in the range 0-255) or full RGBA bitmaps (32 bits).
|
||||
|
||||
Various buffers can be combined together with commands such as [[:docs:efl:advanced:eflgfxfilter:blend|blend]], [[:docs:efl:advanced:eflgfxfilter:blur|blur]], [[:docs:efl:advanced:eflgfxfilter:mask|mask]], etc...
|
||||
|
||||
== Syntax ==
|
||||
|
||||
<code Lua>
|
||||
buffer ({ type = 'rgba', src = nil })
|
||||
</code>
|
||||
|
||||
== Parameters ==
|
||||
|''type'' |Can be either ''"alpha"'' or ''"rgba"'' |
|
||||
|''src'' |A source name, specified in [[Efl.Gfx.Filter.source.set]] or in EDC with ''filter.source: "srcname";'' |
|
||||
|
||||
|
||||
== Examples ==
|
||||
<code Lua>
|
||||
-- create a buffer (RGBA)
|
||||
name1 = buffer()
|
||||
-- create an Alpha buffer
|
||||
name2 = buffer("alpha")
|
||||
-- create an RGBA buffer
|
||||
name3 = buffer("rgba")
|
||||
name4 = buffer({ type = "rgba" })
|
||||
|
||||
-- create a proxy buffer whose pixels come from an external object
|
||||
name5 = buffer({ src = "partname" })
|
||||
</code>
|
||||
|
||||
''partname'' above is either:
|
||||
* The argument to [[Efl.Gfx.Filter.source.set]];
|
||||
* The binding name set in EDC with the syntax:
|
||||
<code EDC>
|
||||
filter.source: "/edje/part/name" "partname";
|
||||
filter.source: "partname";
|
||||
</code>
|
||||
|
||||
== Temporary buffers ==
|
||||
|
||||
Some commands might require the creation of internal buffers, which the script can not use directly, and that serve only as intermediate image processing surfaces.
|
||||
|
||||
This means that the memory usage of a filter operation might be larger than just that of the ''input'' and ''output'' buffers.
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Bump mapping ====
|
||||
|
||||
The bump effect is based on the concept of [[https://en.wikipedia.org/wiki/Bump_mapping|bump mapping]]. It basically consists in casting a light source onto the object, and using a bump map as a relief information.
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
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' })
|
||||
</code>
|
||||
|
||||
== Parameters ==
|
||||
|''map'' |An alpha buffer treated like a Z map for the light effect (bump map). Must be specified. |
|
||||
|''azimuth'' |The angle in degrees 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'' (i.e. disabled), 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 to set it to ''true'' 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' [[colors|color]]. Usually this will be black (''"#000"''). |
|
||||
|''white'' |The specular light's [[colors|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]]. |
|
||||
|
||||
|
||||
== Example ==
|
||||
|
||||
In the following example, the bump map is constructed from the input image. For text, this means we can create 3d looks on the characters by casting specular light and shadows.
|
||||
|
||||
<code Lua bump.lua>
|
||||
a = buffer { 'alpha' } -- this will be our bump map
|
||||
grow { 5, dst = a }
|
||||
blur { 6, src = a , dst = a }
|
||||
bump { map = a, color = '#f60', specular = 1, compensate = true }
|
||||
</code>
|
||||
^ Input ^ Bump map ^ Output ^
|
||||
| {{ :docs:efl:advanced:filter-input-bg.png |}} | {{ :docs:efl:advanced:filter-bumpmap.png |}} | {{ :docs:efl:advanced:filter-bump.png |}} |
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Colors ====
|
||||
|
||||
Many filter operations will take one (or more) color arguments. \\ Since EFL 1.15, the supported syntax to create colors has expanded using Lua class appropriately named ''color''.
|
||||
|
||||
<note tip>The color values used in [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]] are **not** premultiplied and range from 0 to 255.</note>
|
||||
|
||||
<note important>If alpha is not specified or 0 (in the form '#rgba'), then the color will be opaque (i.e. alpha = 255), **unless** the color is ''invisible'' or '#0000'.</note>
|
||||
|
||||
== Syntax ==
|
||||
|
||||
<code Lua>
|
||||
-- default is black
|
||||
color()
|
||||
color(nil)
|
||||
|
||||
-- with r,g,b,a integers in the range [0-255]
|
||||
color(r,g,b)
|
||||
color(r,g,b,a)
|
||||
color({r = 0, g = 255, b = 128, a = 64})
|
||||
|
||||
-- with r,g,b,a hexadecimal values [0-F]
|
||||
color('#rgb')
|
||||
color('#rgba')
|
||||
color('#rrggbb')
|
||||
color('#rrggbbaa')
|
||||
|
||||
-- predefined colors
|
||||
color('red')
|
||||
</code>
|
||||
|
||||
== Predefined colors ==
|
||||
|
||||
Here is the list of predefined colors, based on their equivalent HTML names.
|
||||
|
||||
^ Name ^ Value ^ Example ^
|
||||
| 'white' | '#FFFFFF' | {{ :docs:efl:advanced:filter-color-white.png |}} |
|
||||
| 'black' | '#000000' | {{ :docs:efl:advanced:filter-color-black.png |}} |
|
||||
| 'red' | '#FF0000' | {{ :docs:efl:advanced:filter-color-red.png |}} |
|
||||
| 'green' | '#008000' | {{ :docs:efl:advanced:filter-color-green.png |}} |
|
||||
| 'blue' | '#0000FF' | {{ :docs:efl:advanced:filter-color-blue.png |}} |
|
||||
| 'darkblue' | '#0000A0' | {{ :docs:efl:advanced:filter-color-darkblue.png |}} |
|
||||
| 'yellow' | '#FFFF00' | {{ :docs:efl:advanced:filter-color-yellow.png |}} |
|
||||
| 'magenta' | '#FF00FF' | {{ :docs:efl:advanced:filter-color-magenta.png |}} |
|
||||
| 'cyan' | '#00FFFF' | {{ :docs:efl:advanced:filter-color-cyan.png |}} |
|
||||
| 'orange' | '#FFA500' | {{ :docs:efl:advanced:filter-color-orange.png |}} |
|
||||
| 'purple' | '#800080' | {{ :docs:efl:advanced:filter-color-purple.png |}} |
|
||||
| 'brown' | '#A52A2A' | {{ :docs:efl:advanced:filter-color-brown.png |}} |
|
||||
| 'maroon' | '#800000' | {{ :docs:efl:advanced:filter-color-maroon.png |}} |
|
||||
| 'lime' | '#00FF00' | {{ :docs:efl:advanced:filter-color-lime.png |}} |
|
||||
| 'gray' \\ 'grey' | '#808080' | {{ :docs:efl:advanced:filter-color-gray.png |}} |
|
||||
| 'silver' | '#C0C0C0' | {{ :docs:efl:advanced:filter-color-silver.png |}} |
|
||||
| 'olive' | '#808000' | {{ :docs:efl:advanced:filter-color-olive.png |}} |
|
||||
| 'invisible' \\ 'transparent' | '#0000' | {{ :docs:efl:advanced:filter-color-invisible.png |}} |
|
||||
|
||||
== Usage examples ==
|
||||
|
||||
<code Lua>
|
||||
blur { 15, color = color('yellow') }
|
||||
blur { 5, color = '#f0f8' }
|
||||
blur { 2, color = state.color }
|
||||
blend { color = 'white' }
|
||||
</code>
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
=== Color curves ===
|
||||
|
||||
The color curve function is based on the classic [[https://en.wikipedia.org/wiki/Curve_%28tonality%29|curve]] image filtering operation. It works by remapping one or more color channels (R, G, B, A, or RGB together) by applying a function over the range [0-255]. A table can also be passed in, containing a series of key points to be interpolated.
|
||||
|
||||
== Syntax ==
|
||||
|
||||
<code Lua>
|
||||
curve ({ points, interpolation = 'linear', channel = 'rgb', src = input, dst = output })
|
||||
</code>
|
||||
|
||||
== 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''. |
|
||||
|
||||
|
||||
== Specifying the curve ==
|
||||
|
||||
The ''points'' argument is a function or table taking input values from 0 to 255 and mapping those to the same range 0 to 255. //The old string-based syntax is still supported but not recommended.//
|
||||
|
||||
The easiest way to specify a curve is to create a sparse table with keys and values from 0 to 255 (//yes, the table starts at 0 and not 1 as is usual in Lua//):
|
||||
|
||||
<code Lua>
|
||||
-- color invert
|
||||
p = {}
|
||||
p[0] = 255
|
||||
p[255] = 0
|
||||
curve ({ points = p })
|
||||
</code>
|
||||
|
||||
Another solution is to pass in a function ''f(x)'' that will output values in the 0-255 range. For example:
|
||||
|
||||
<code Lua>
|
||||
p = function(x)
|
||||
return 255 * math.sin(x / 255 * math.pi)
|
||||
end
|
||||
curve ({ points = p })
|
||||
</code>
|
||||
== Examples ==
|
||||
|
||||
<code Lua filter_curve.lua>
|
||||
a = buffer ('alpha')
|
||||
b = buffer ('alpha')
|
||||
blur { 6, dst = a }
|
||||
|
||||
c = {}
|
||||
c[0] = 0
|
||||
c[50] = 255
|
||||
c[100] = 0
|
||||
c[150] = 255
|
||||
c[200] = 0
|
||||
c[255] = 255
|
||||
|
||||
curve { src = a, points = c, dst = b }
|
||||
blend {src = b }
|
||||
</code>
|
||||
|
||||
^ Input ^ Color curve function ^ Output ^
|
||||
| {{ :docs:efl:advanced:filter-blur6.png |}} | {{ :docs:efl:advanced:filter-colorcurve.png |}} | {{ :docs:efl:advanced:filter-curve.png |}} |
|
||||
| {{ :docs:efl:advanced:filter-blur6.png |}} | {{ :docs:efl:advanced:filter-colorcurve2.png |}} | {{ :docs:efl:advanced:filter-curve-1.png |}} |
|
||||
|
||||
Color curves can thus be used to draw contours of text characters:
|
||||
|
||||
<code Lua contour.lua>
|
||||
a = buffer ('alpha')
|
||||
blur ({ 4, dst = a })
|
||||
|
||||
p = {}
|
||||
p[0] = 0
|
||||
p[20] = 0
|
||||
p[60] = 255
|
||||
p[160] = 255
|
||||
p[200] = 0
|
||||
p[255] = 0
|
||||
|
||||
curve ({ points = p, src = a, dst = a })
|
||||
blend ({ src = a, color = 'white' })
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-curve-3.png|}}
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Displacement mapping ====
|
||||
|
||||
Apply a [[https://en.wikipedia.org/wiki/Displacement_mapping|displacement map]] on a buffer. This has the effect of moving the input pixels based on the values of the corresponding pixels in the displacement buffer.
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
displace ({ map, intensity = 10, flags = 0, src = input, dst = output, fillmode = 'repeat' })
|
||||
</code>
|
||||
|
||||
== Parameters ==
|
||||
|''map'' |An RGBA buffer containing a displacement map. See below for more details. |
|
||||
|''intensity'' |Maximum distance for the displacement. The value 255 in the displacement map will then represent a displacement of ''intensity'' pixels. |
|
||||
|''flags'' |This defines how pixels should be treated when going out of the source image bounds. \\ Must be one of ''"default"'', ''"nearest"'', ''"smooth"'', ''"nearest_stretch"'' or ''"smooth_stretch"''. ''"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.
|
||||
* The alpha channel is used as an alpha multiplier for blending.
|
||||
* The blue channel is ignored.
|
||||
|
||||
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:
|
||||
|
||||
<code Lua>
|
||||
D = map (x, y)
|
||||
dst (x, y) = D.alpha / 255 * src (x + (D.red - 128) * intensity / 128,
|
||||
y + (D.green - 128) * intensity / 128)
|
||||
+ (255 - D.alpha) / 255 * dst (x, y)
|
||||
</code>
|
||||
|
||||
Of course, the real algorithm takes into account interpolation between pixels as well.
|
||||
|
||||
== Example ==
|
||||
|
||||
<code Lua>
|
||||
a = buffer { 'alpha' }
|
||||
displace { 'image1', intensity = 20, fillmode = 'stretch', dst = a }
|
||||
blend { a }
|
||||
</code>
|
||||
^ Displacement map ^ Output ^
|
||||
| {{ :docs:efl:advanced:filter-texture.png |}} | {{ :docs:efl:advanced:filter-displace.png |}} |
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Fill ====
|
||||
|
||||
Fill a buffer with a specific color. Does not blend, can be used to clear a buffer.
|
||||
|
||||
<note tip>This function should preferrably be used only for debugging purposes.</note>
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
fill ({ dst = output, color = 'transparent', l = 0, r = 0, t = 0, b = 0 })
|
||||
</code>
|
||||
|
||||
== 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. |
|
||||
|
||||
== Examples ==
|
||||
<code Lua>
|
||||
fill { color = 'darkblue' }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-fill.png|}}
|
||||
|
||||
<code Lua>
|
||||
padding_set(20)
|
||||
fill { output, 'blue', 5, 10, 20, 50 }
|
||||
blend { color = 'silver' }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-fillpad.png|}}
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Fill modes ====
|
||||
|
||||
Similar to [[Evas.Fill_Mode]], the [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]] fill modes specify how to use an input buffer to paint in a buffer of different size, by stretching or repeating the image.
|
||||
|
||||
Here is the list of all accepted fill modes that can be passed as value for ''fillmode'' arguments (in ''mask'', ''blend'', etc...).
|
||||
|
||||
^ Value ^ Meaning ^ Effect ^
|
||||
| 'none' | Does not stretch or tile | {{:docs:efl:advanced:filter-fillmode-none.png|}} |
|
||||
| 'stretch_x' | Stretch horizontally only | {{:docs:efl:advanced:filter-fillmode-sx.png|}} |
|
||||
| 'stretch_y' | Stretch vertically only | {{:docs:efl:advanced:filter-fillmode-sy.png|}} |
|
||||
| 'stretch' \\ 'stretch_xy' | Stretch in both directions | {{:docs:efl:advanced:filter-fillmode-sxy.png|}} |
|
||||
| 'repeat_x' | Tile horizontally only | {{:docs:efl:advanced:filter-fillmode-rx.png|}} |
|
||||
| 'repeat_y' | Tile vertically only | {{:docs:efl:advanced:filter-fillmode-ry.png|}} |
|
||||
| 'repeat' \\ 'repeat_xy' | Tile in both directions | {{:docs:efl:advanced:filter-fillmode-rxy.png|}} |
|
||||
| 'stretch_x_repeat_y' \\ 'repeat_y_stretch_x' | Stretch horizontally, repeat vertically | {{:docs:efl:advanced:filter-fillmode-sxry.png|}} |
|
||||
| 'repeat_x_stretch_y' \\ 'stretch_y_repeat_x' | Stretch vertically, repeat horizontally | {{:docs:efl:advanced:filter-fillmode-rxsy.png|}} |
|
||||
|
||||
== Example ==
|
||||
|
||||
The above images have been generated with the following filter code:
|
||||
<code Lua>
|
||||
b = buffer{ src = 'image2' }
|
||||
padding_set(20)
|
||||
fill { color = white }
|
||||
blend { src = b, fillmode = 'none' }
|
||||
</code>
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Grow and shrink ====
|
||||
|
||||
The ''grow'' function is used to apply [[https://en.wikipedia.org/wiki/Mathematical_morphology|morphology]] filters to a buffer.
|
||||
|
||||
<note>At the moment, ''grow'' is implemented with a combinaison of ''blur'' and ''curve'' instead of a classical structuring element, which means that the growing and shrinking effects are not exactly the same as the mathematical dilation or erosion.</note>
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
grow ({ radius, smooth = true, src = input, dst = output })
|
||||
</code>
|
||||
|
||||
== 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''. |
|
||||
|
||||
== Examples ==
|
||||
<code Lua>
|
||||
a = buffer { 'rgba' }
|
||||
blend { dst = a }
|
||||
grow { 6, src = a }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-grow.png|}}
|
||||
|
||||
<code Lua>
|
||||
a = buffer { 'rgba' }
|
||||
blend { dst = a }
|
||||
grow { -4, src = a }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-shrink.png|}}
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Masking and texturing ====
|
||||
|
||||
The ''mask'' function is used to blend together 3 buffers instead of just two. As such this means input ''A'' can be masked by input ''B'' and blended on target ''C''.
|
||||
|
||||
''mask'' can be used to apply textures to text characters or apply alpha masks to RGBA buffers.
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
mask ({ mask, src = input, dst = output, color = 'white', fillmode = 'repeat' })
|
||||
</code>
|
||||
|
||||
== 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 differs from the ''input'' size. \\ Should be set when masking with external textures. Default is ''"repeat"''. See [[fillmodes]]. |
|
||||
|
||||
== Examples ==
|
||||
This example requires an external object named ''"image1"'':
|
||||
<code Lua texturing.lua>
|
||||
mask { mask = 'image1', fillmode = 'stretch' }
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-mask.png|}}
|
||||
|
||||
The following example does not require any external texture:
|
||||
<code Lua innershadow.lua>
|
||||
a = buffer ('alpha')
|
||||
blur ({ 6, dst = a })
|
||||
p = {}
|
||||
p[0] = 255
|
||||
p[128] = 255
|
||||
p[255] = 0
|
||||
curve ({ points = p, src = a, dst = a })
|
||||
blend ({ color = 'black' })
|
||||
mask ({ mask = a, color = 'cyan' })
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-innershadow.png|}}
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Padding ====
|
||||
|
||||
The function ''padding_set'' can be used to forcily set a specific padding for this filter, regardless of the other operations.
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
padding_set ({ l, r = [l], t = [r], b = [t] })
|
||||
</code>
|
||||
|
||||
== Parameters ==
|
||||
|''l'' |Padding on the left side in pixels. |
|
||||
|''r'' |Padding on the right side in pixels. If unset, defaults to ''l''. |
|
||||
|''t'' |Padding on the top in pixels. If unset, defaults to ''r''. |
|
||||
|''b'' |Padding 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 ==
|
||||
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.
|
||||
<code Lua padding_set.lua>
|
||||
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' })
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-padding.png|}}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
Go back to [[:docs:efl:advanced:eflgfxfilters|Efl.Gfx.Filter]].
|
||||
|
||||
==== Transformations ====
|
||||
|
||||
Apply a geometrical transformation to a buffer.
|
||||
|
||||
<note warning>For the moment, only vertical flip is implemented and available.
|
||||
|
||||
This operation does not blend and assumes the destination buffer is empty.</note>
|
||||
|
||||
== Syntax ==
|
||||
<code Lua>
|
||||
transform ({ dst, op = 'vflip', src = input, oy = 0 })
|
||||
</code>
|
||||
|
||||
== 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.
|
||||
<code Lua mirror.lua>
|
||||
t = buffer ('alpha')
|
||||
transform ({ oy = 20, dst = t })
|
||||
blend ({ src = t, color = '#fff8' })
|
||||
blend ({ color = 'white' })
|
||||
</code>
|
||||
{{:docs:efl:advanced:filter-mirror.png|}}
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
====== EFL Graphics Filters ======
|
||||
|
||||
<note warning>The APIs and features described here are still under heavy development and may not be stable yet. The documentation below applies to EFL 1.15+ (to be released in August 2015). While the Eo-based API is not final yet, the EDC syntax can be considered stable.
|
||||
|
||||
The old reference documentation for the filters scripting syntax is [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/evasfiltersref.html|here]].
|
||||
</note>
|
||||
|
||||
This page presents an overview of [[Efl.Gfx.Filter]] used for advanced text effects and basic image filtering.
|
||||
|
||||
===== Functions =====
|
||||
Summary of the supported filtering functions:
|
||||
*[[:docs:efl:advanced:eflgfxfilter:blend|blend]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:blur|blur]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:grow|grow]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:curve|curve]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:fill|fill]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:mask|mask]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:bump|bump]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:displace|displace]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:transform|transform]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:transform|buffer]]
|
||||
*[[:docs:efl:advanced:eflgfxfilter:transform|padding_set]]
|
||||
|
||||
===== 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 [[:docs:efl:advanced:eflgfxfilter:buffer|buffer]] function.
|
||||
|
||||
Read more [[:docs: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 [[:docs: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 ^
|
||||
| [[:docs:efl:advanced:eflgfxfilter:blend|Blend]] | ''blend'' | {{ :docs:efl:advanced:filter-blend.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:blur|Blurs, glows and shadows]] | ''blur'' | {{ :docs:efl:advanced:filter-blur.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:grow|Grow and shrink]] | ''grow'' | {{ :docs:efl:advanced:filter-grow.png |}} {{ :docs:efl:advanced:filter-shrink.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:curve|Color curves]] | ''curve'' | {{ :docs:efl:advanced:filter-curve.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:fill|Solid color fill]] | ''fill'' | {{ :docs:efl:advanced:filter-fill.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:mask|Masking and texturing]] | ''mask'' | {{ :docs:efl:advanced:filter-mask.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:bump|Bump maps]] | ''bump'' | {{ :docs:efl:advanced:filter-bump.png |}} |
|
||||
| [[:docs:efl:advanced:eflgfxfilter:displace|Displacement maps]] | ''displace'' | {{ :docs:efl:advanced:filter-displace.png |}} |
|
||||
| [[:docs: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 ''blend'' functions:
|
||||
|
||||
<code Lua filter1.lua>
|
||||
blur { 10, color = '#009' }
|
||||
blur { 4, color = '#f00' }
|
||||
grow { -4 }
|
||||
</code>
|
||||
|
||||
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:
|
||||
|
||||
<code Lua filter2.lua>
|
||||
a = buffer { 'alpha' } -- step 1
|
||||
grow { 6, dst = a } -- step 2
|
||||
blur { 4, src = a, color = '#009' } -- step 3
|
||||
blend { src = input } -- step 4
|
||||
</code>
|
||||
|
||||
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 |}} |
|
||||
|
|
@ -6,6 +6,7 @@
|
|||
These are some more advanced topics for developers, once they have gotten up to speed with the [[/docs/efl/start|getting started]] documentation.
|
||||
|
||||
* [[dnd|DND (Drag and Drop)]]
|
||||
* [[eflgfxfilters|EFL Graphics Filters]]: Advanced text effects and image filters
|
||||
|
||||
----
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue