jpeg pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=36b0bca4aa01fb99d540164130f984fd0d3b76de
commit 36b0bca4aa01fb99d540164130f984fd0d3b76de
Author: Jean-Philippe Andre <jp.an...@samsung.com>
Date: Tue Feb 11 15:56:31 2014 +0900
Evas filters: Add the reference documentation (script language)
In Doxygen format, write the reference documentation for the filters.
It will contain a few examples only, should serve more as a reference
just like edcref.
This is for the script language itself, not for the Eo APIs or the
internal APIs (those are already documented).
---
src/lib/evas/Evas_Eo.h | 24 +-
src/lib/evas/filters/evas_filter.c | 2 +-
src/lib/evas/filters/evas_filter_curve.c | 4 +-
src/lib/evas/filters/evas_filter_parser.c | 607 ++++++++++++++++++++++++++----
4 files changed, 561 insertions(+), 76 deletions(-)
diff --git a/src/lib/evas/Evas_Eo.h b/src/lib/evas/Evas_Eo.h
index 69878f5..fcd6e0c 100644
--- a/src/lib/evas/Evas_Eo.h
+++ b/src/lib/evas/Evas_Eo.h
@@ -2275,21 +2275,35 @@ enum
/**
* @def evas_obj_text_filter_program_set
+ *
+ * Set an Evas filter program on this Text Object.
+ * If the program fails to compile (syntax error, invalid buffer name, etc...),
+ * the standard text effects will be applied instead (SHADOW, etc...).
+ *
+ * @param[in] program The program code, as defined by the @ref evasfiltersref
+ * "Evas filters script language". Pass NULL to remove the former program and
+ * switch back to the standard text effects.
+ *
* @since 1.9
- * @note EXPERIMENTAL code
+ * @note EXPERIMENTAL FEATURE. This is an unstable API, please use only for
testing purposes.
+ * @see @ref evasfiltersref "Evas filters reference"
*/
-#define evas_obj_text_filter_program_set(str)
EVAS_OBJ_TEXT_ID(EVAS_OBJ_TEXT_SUB_ID_FILTER_PROGRAM_SET), EO_TYPECHECK(const
char *, str)
+#define evas_obj_text_filter_program_set(program)
EVAS_OBJ_TEXT_ID(EVAS_OBJ_TEXT_SUB_ID_FILTER_PROGRAM_SET), EO_TYPECHECK(const
char *, program)
/**
+ * @def evas_obj_text_filter_source_set
*
- * Bind an object to use as a mask or texture in special filter
+ * Bind an object to use as a mask or texture with Evas Filters. This will
+ * create automatically a new RGBA buffer containing the source object's
+ * pixels (as it is rendered).
*
* @param[in] name Object name as used in the program code
* @param[in] obj Eo object to use through proxy rendering
*
* @see evas_obj_text_filter_program_set
- *
- * @note EXPERIMENTAL FEATURE.
+ * @since 1.9
+ * @note EXPERIMENTAL FEATURE. This is an unstable API, please use only for
testing purposes.
+ * @see @ref evasfiltersref "Evas filters reference"
*/
#define evas_obj_text_filter_source_set(name, obj)
EVAS_OBJ_TEXT_ID(EVAS_OBJ_TEXT_SUB_ID_FILTER_SOURCE_SET), EO_TYPECHECK(const
char *, name), EO_TYPECHECK(Eo *, obj)
diff --git a/src/lib/evas/filters/evas_filter.c
b/src/lib/evas/filters/evas_filter.c
index f2016a2..d2a3dcd 100644
--- a/src/lib/evas/filters/evas_filter.c
+++ b/src/lib/evas/filters/evas_filter.c
@@ -712,7 +712,7 @@ _command_del(Evas_Filter_Context *ctx, Evas_Filter_Command
*cmd)
ctx->commands = eina_inlist_remove(ctx->commands, EINA_INLIST_GET(cmd));
switch (cmd->mode)
{
- case EVAS_FILTER_MODE_CURVE: free(cmd->curve.data);
+ case EVAS_FILTER_MODE_CURVE: free(cmd->curve.data); break;
default: break;
}
free(cmd);
diff --git a/src/lib/evas/filters/evas_filter_curve.c
b/src/lib/evas/filters/evas_filter_curve.c
index 2f5df07..a88dbc8 100644
--- a/src/lib/evas/filters/evas_filter_curve.c
+++ b/src/lib/evas/filters/evas_filter_curve.c
@@ -41,7 +41,7 @@ _filter_curve_cpu_rgba(Evas_Filter_Command *cmd)
return EINA_FALSE;
}
- // One channel
+ // One channel (R, G or B)
if (offset >= 0)
{
for (k = len; k; k--, dst++, src++)
@@ -49,7 +49,7 @@ _filter_curve_cpu_rgba(Evas_Filter_Command *cmd)
return EINA_TRUE;
}
- // RGB
+ // All RGB channels
if (cmd->curve.channel == EVAS_FILTER_CHANNEL_RGB)
{
#ifndef WORDS_BIGENDIAN
diff --git a/src/lib/evas/filters/evas_filter_parser.c
b/src/lib/evas/filters/evas_filter_parser.c
index 5968eb6..4790e33 100644
--- a/src/lib/evas/filters/evas_filter_parser.c
+++ b/src/lib/evas/filters/evas_filter_parser.c
@@ -3,6 +3,217 @@
#define EVAS_FILTER_MODE_GROW (EVAS_FILTER_MODE_LAST+1)
+/* Note on the documentation:
+ * To keep it simple, I'm not using any fancy features, only <ul>/<li> lists
+ * and @a, @b, @c flags from Doxygen.
+ * Let's keep it that way.
+ *
+ * This is a REFERENCE documentation, not supposed to contain tons of examples,
+ * but each filter command should have one simple copy and pasteable example.
+ */
+
+/**
+ @page evasfiltersref Evas filters reference
+
+ The Evas filters are a combination of filters used to apply specific effects
+ to an @ref Evas_Object "Evas Object". For the moment, these effects are
+ specific to the @ref Evas_Object_Text "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 @ref Evas_Object_Text "Text Object",
+ an alpha-only @c input buffer is created, where the text is rendered, and
+ an RGBA @c 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:
+ <ul>
+ <li> @ref sec_syntax "Syntax" </li>
+ <li> @ref sec_buffers "Buffer management" </li>
+ <ul>
+ <li> @ref sec_buffers_cspace "Colorspaces" </li>
+ <li> @ref sec_buffers_auto "Automatic buffers" </li>
+ <li> @ref sec_buffers_cmd "BUFFER command" </li>
+ </ul>
+ <li> @ref sec_commands "Commands" </li>
+ <ul>
+ <li> @ref sec_commands_blend "BLEND command"</li>
+ <li> @ref sec_commands_blur "BLUR command"</li>
+ <li> @ref sec_commands_grow "GROW command"</li>
+ <li> @ref sec_commands_curve "CURVE command"</li>
+ <li> @ref sec_commands_fill "FILL command"</li>
+ <li> @ref sec_commands_mask "MASK command"</li>
+ <li> @ref sec_commands_bump "BUMP command"</li>
+ <li> @ref sec_commands_displace "DISPLACE command"</li>
+ <li> @ref sec_commands_transform "TRANSFORM command"</li>
+ </ul>
+ </ul>
+
+ All the examples in this page can (should) be directly used in
+ @ref 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.
+ */
+
+/**
+ @page evasfiltersref
+ @section sec_syntax Syntax
+
+ Here is a simple example illustrating the syntax:
+
+ @code
+ buffer : fat (alpha);
+ grow (5, dst = fat);
+ blur (8, src = fat, color = darkblue);
+ blur (4, color = cyan);
+ blend ();
+ @endcode
+
+ 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:
+ <ul>
+ <li>All whitespaces are discarded</li>
+ <li>All commands are case-insensitive, except for the buffer and source
names</li>
+ <li>All dimensions are in pixels</li>
+ <li>The commands will be executed in sequential order</li>
+ <li>All commands must be terminated by a semicolon ';'</li>
+ <li>Most commands have default values</li>
+ <li>A command argument can either be set by name, or sequentially omitting
the name (similarily to Python)</li>
+ <li>Boolean values can be either 1/0, on/off, yes/no, enabled/disabled,
true/false</li>
+ </ul>
+
+ Since the spaces are discarded, the above code is equivalent to:
+ @code
+
buffer:fat(alpha);grow(5,dst=fat);blur(8,src=fat,color=darkblue);blur(4,color=cyan);blend();
+ @endcode
+
+ <h3>Special keywords and their values</h3>
+
+ Some options accept a certain set of values (like enums):
+ <ul>
+ <li>Booleans</li>
+ <ul>
+ <li>1/0, on/off, yes/no, enabled/disabled, true/false</li>
+ </ul>
+ @anchor evasfilters_color
+ <li>Color</li>
+ <ul>
+ <li>Hexademical values: @c #RRGGBB, @c #RRGGBBAA, @c #RGB, @c #RGBA</li>
+ <li>white: @c #FFFFFF</li>
+ <li>black: @c #000000</li>
+ <li>red: @c #FF0000</li>
+ <li>green: @c #008000</li>
+ <li>blue: @c #0000FF</li>
+ <li>darkblue: @c #0000A0</li>
+ <li>yellow: @c #FFFF00</li>
+ <li>magenta: @c #FF00FF</li>
+ <li>cyan: @c #00FFFF</li>
+ <li>orange: @c #FFA500</li>
+ <li>purple: @c #800080</li>
+ <li>brown: @c #A52A2A</li>
+ <li>maroon: @c #800000</li>
+ <li>lime: @c #00FF00</li>
+ <li>gray: @c #808080</li>
+ <li>grey: @c #808080</li>
+ <li>silver: @c #C0C0C0</li>
+ <li>olive: @c #808000</li>
+ <li>invisible, transparent: @c #0000 (alpha is zero)</li>
+ </ul>
+ <li>Fillmode</li>
+ <ul>
+ <li>none</li>
+ <li>stretch_x</li>
+ <li>stretch_y</li>
+ <li>repeat_x</li>
+ <li>repeat_y</li>
+ <li>repeat_x_stretch_y, stretch_y_repeat_x</li>
+ <li>repeat_y_stretch_x, stretch_x_repeat_y</li>
+ <li>repeat, repeat_xy</li>
+ <li>stretch, stretch_xy</li>
+ </ul>
+ </ul>
+ */
+
+/**
+ @page evasfiltersref
+ @section sec_buffers 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).
+
+ @subsection sec_buffers_cspace 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.
+
+
+ @subsection sec_buffers_auto 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 @ref Evas_Object_Text "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
+ @ref sec_buffers_cmd "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.
+
+
+ @subsection sec_buffers_cmd Buffer command
+
+ @code
+ buffer : name;
+ buffer : name (alpha);
+ buffer : name (rgba);
+ buffer : name (src = partname);
+ @endcode
+
+ The "buffer" instruction is a @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.
+
+ @param name An alpha-numerical name, starting with a letter (a-z, A-Z).
+ Can not be @c input or @c output, as these are reserved
names.
+ Must be unique.
+
+ @param (args) [alpha] OR [rgba] OR [src = partname] <br>
+ Create a new named buffer, specify its colorspace or source. Possible
options:
+ @li @c alpha: Create an alpha-only buffer (1 channel, no color)
+ @li @c rgba: Create an RGBA buffer (4 channels, full color)
+ @li <tt>src = partname</tt>: Use another <tt>Evas Object</tt> 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 evas_obj_text_filter_source_set
+
+ @since 1.9
+ */
+
// Map of the most common HTML color names
static struct
{
@@ -735,6 +946,44 @@ _blend_padding_update(Evas_Filter_Program *pgm,
Evas_Filter_Instruction *instr,
if (padb) *padb = b;
}
+/**
+ @page evasfiltersref
+ @section sec_commands Filter commands
+ @page evasfiltersref
+
+ This section will present the various filter instructions, their syntax
+ and their effects.
+ */
+
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_blend 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
+ blend (src = input, dst = output, ox = 0, oy = 0, color = white, fillmode
= none);
+ @endcode
+
+ @param src Source buffer to blend.
+ @param dst Destination buffer for blending.
+ @param ox X offset. Moves the buffer to the right (ox > 0) or to the left
(ox < 0) by N pixels.
+ @param oy Y offset. Moves the buffer to the bottom (oy > 0) or to the top
(oy < 0) by N pixels.
+ @param color A color to use as multiplier. See @ref evasfilters_color
"colors". <br>
+ If the input is an alpha buffer and the output is RGBA, this
will
+ draw the buffer in this color.
+ @param fillmode @c NONE, @c STRETCH, @c REPEAT <br>
+ Map the input onto the whole surface of the output by
stretching or
+ repeating it.
+
+ If @a src is an alpha buffer and @a dst is an RGBA buffer, then the @a color
option should be set.
+
+ @since 1.9
+ */
+
static Eina_Bool
_blend_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -742,10 +991,6 @@ _blend_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "blend"),
EINA_FALSE);
- /*
- * blend [src=BUFFER] [dst=BUFFER] [ox=INT] [oy=INT] (color=COLOR)
- */
-
instr->type = EVAS_FILTER_MODE_BLEND;
instr->pad.update = _blend_padding_update;
_instruction_param_seq_add(instr, "src", VT_BUFFER, "input");
@@ -813,6 +1058,39 @@ _blur_padding_update(Evas_Filter_Program *pgm,
Evas_Filter_Instruction *instr,
}
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_blur Blur
+
+ Apply blur effect on a buffer (box or gaussian).
+
+ @code
+ blur (rx = 3, ry = -1, type = default, ox = 0, oy = 0, color = white, src
= input, dst = output);
+ @endcode
+
+ @param rx X radius. Specifies the radius of the blurring kernel (X
direction).
+ @param ry Y radius. Specifies the radius of the blurring kernel (Y
direction). If -1 is used, then @a ry = @a rx.
+ @param type Blur type to apply. One of @c default, @c box or @c gaussian.
@c default is an alias for @c gaussian.
+ @param ox X offset. Moves the buffer to the right (@a ox > 0) or to the
left (@a ox < 0) by N pixels.
+ @param oy Y offset. Moves the buffer to the bottom (@a oy > 0) or to the
top (@a oy < 0) by N pixels.
+ @param color A color to use as multiplier. See @ref evasfilters_color
"colors". <br>
+ If the input is an alpha buffer and the output is RGBA, this
will
+ draw the buffer in this color.
+ @param src Source buffer to blur.
+ @param dst Destination buffer for blending.
+
+ If @a src is an alpha buffer and @a dst is an RGBA buffer, then the color
option should be set.
+
+ @a ox and @a oy can be used to move the blurry output by a few pixels, like
a drop shadow. Example:
+ @code
+ blur (10, color = black, oy = 5, ox = 5);
+ blend ();
+ @endcode
+
+ @since 1.9
+ */
+
static Eina_Bool
_blur_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -820,11 +1098,6 @@ _blur_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "blur"),
EINA_FALSE);
- /*
- * blur [rx=]REAL [ry=REAL] [type=STRING] [ox=INT] [oy=INT] \
- * (color=COLOR) (src=BUFFER) (dst=BUFFER)
- */
-
instr->type = EVAS_FILTER_MODE_BLUR;
instr->pad.update = _blur_padding_update;
_instruction_param_seq_add(instr, "rx", VT_INT, 3);
@@ -839,6 +1112,46 @@ _blur_instruction_prepare(Evas_Filter_Instruction *instr)
return EINA_TRUE;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_bump 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.
+
+ @code
+ 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);
+ @endcode
+
+ @param map An alpha buffer treated like a Z map for the light effect
(bump map). Must be specified.
+ @param 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.
+ @param 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.
+ @param depth The depth of the object in an arbitrary unit. More depth
means the shadows will be stronger. Default is 8.0.
+ @param specular An arbitrary unit for the specular light effect. Default
is 0.0, but a common value would be 40.0.
+ @param color The main color of the object if src is an alpha buffer.
This represents the light's normal color. See @ref evasfilters_color "colors".
+ @param 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.
+ @param src Source buffer. This should be an alpha buffer.
+ @param dst Destination buffer. This should be an RGBA buffer
(although alpha is supported). Must be of the same size as @a src.
+ @param black The shadows' color. Usually this will be black (@c #000).
+ @param white The specular light's color. Usually this will be white (@c
#FFF).
+ @param fillmode This specifies how to handle @a map when its dimensions
don't match those of @a src and @a dst. Default is to @c repeat.
+
+ @note As of 2014/02/11, the ALPHA to RGBA support is of much better quality
than ALPHA only, but @b very slow. RGBA sources are not supported yet.
+
+ Here is a full example for a size 100 font, of a very simple bevel effect:
+ @code
+ buffer : a (alpha);
+ blur (5, dst = a);
+ bump (map = a, compensate = yes, color = cyan, specular = 10.0);
+ @endcode
+
+ @since 1.9
+ */
+
static Eina_Bool
_bump_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -846,12 +1159,6 @@ _bump_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "bump"),
EINA_FALSE);
- /*
- * bump [map=]ABUFFER [azimuth=REAL] [elevation=REAL] [depth=REAL] \
- * [specular-factor=REAL] (color=COLOR) (compensate=BOOL) \
- * (src=BUFFER) (dst=BUFFER) (black=COLOR) (white=COLOR);
- */
-
instr->type = EVAS_FILTER_MODE_BUMP;
_instruction_param_seq_add(instr, "map", VT_BUFFER, NULL);
_instruction_param_seq_add(instr, "azimuth", VT_REAL, 135.0);
@@ -869,6 +1176,52 @@ _bump_instruction_prepare(Evas_Filter_Instruction *instr)
return EINA_TRUE;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_curve Curve
+
+ Apply a color curve to a specific channel in a buffer.
+
+ @code
+ curve (points, interpolation = linear, channel = rgb, src = input, dst =
output);
+ @endcode
+
+ Modify the colors of a buffer. This applies a color curve y = f(x) to every
pixel.
+
+ @param points The color curve to apply. See below for the syntax.
+ @param interpolation How to interpolate between points. One of @c linear (y
= ax + b) or @c none (y = Yk).
+ @param channel Target channel for the color modification. One of @c
R(ed), @c G(reen), @c B(lue), @c A(lpha), @c RGB and @c RGBA. If @a src is an
alpha buffer, this parameter will be ignored.
+ @param src Source buffer.
+ @param dst Destination buffer, must be of same dimensions and
color space as @a src.
+
+ The @a points argument contains a list of (X,Y) points in the range 0..255,
+ describing a function <tt>f(x) = y</tt> to apply to all pixel values.
+
+ The syntax of this @a points string is <tt>x1:y1 - x2:y2 - x3:y3 - ... -
xn:yn</tt>
+ (remember that all spaces are discarded).
+ The points @c xn are in @a increasing order: <tt>x1 < x2 < x3 < ... <
xn</tt>,
+ and all values @c xn or @c yn are within the range 0..255.
+
+ The identity curve is then described as <tt>0:0-255:255</tt>, with linear
interpolation:
+ @code
+ curve(points = 0:0 - 255:255, interpolation = linear);
+ @endcode
+ 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:
+ @code
+ buffer : a (alpha);
+ blur (4, dst = a);
+ curve (0:0 - 20:0 - 60:255 - 160:255 - 200:0 - 255:0, src = a, dst = a);
+ blend(src = a, color = black);
+ @endcode
+
+ The curve command can be used to alter the output of a blur operation.
+
+ @since 1.9
+ */
+
static Eina_Bool
_curve_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -878,20 +1231,6 @@ _curve_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "curve"),
EINA_FALSE);
- /*
- * curve [points=]INTERPSTR [interpolation=]STRING (src=BUFFER) (dst=BUFFER)
- *
- * INTERPSTR is a STRING of the following format:
- * "x1:y1-x2:y2-x3:y3...xn:yn"
- * Where xk and yk are all numbers in [0-255] and xk are in increasing order
- *
- * The interpolation STRING can be one of:
- * - none: y = yk in [xk,xk+1] (staircase effect)
- * - linear: linear interpolation y = ax + b
- * - cubic: cubic interpolation y = ax^3 + bx^2 + cx + d
- * Invalid values default to linear
- */
-
instr->type = EVAS_FILTER_MODE_CURVE;
_instruction_param_seq_add(instr, "points", VT_STRING, NULL);
@@ -941,6 +1280,53 @@ _displace_padding_update(Evas_Filter_Program *pgm,
if (padb) *padb = b;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_displace Displace
+
+ Apply a displacement map on a buffer.
+
+ @code
+ displace (map, intensity = 10, flags = 0, src = input, dst = output,
fillmode = repeat);
+ @endcode
+
+ @param map An RGBA buffer containing a displacement map. See below for
more details.
+ @param intensity Maximum distance for the displacement.
+ This means 0 and 255 will represent a displacement of @c
intensity pixels.
+ @param flags One of @c default, @c nearest, @c smooth, @c
nearest_stretch or @c smooth_stretch.
+ This defines how pixels should be treated when going out of
the @a src image bounds.
+ @c default is equivalent to @c smooth_stretch.
+ @param src Source buffer
+ @param dst Destination buffer. Must be of same color format and size
as @a src.
+ @param fillmode Defines how to handle cases where the map has a different
size from @a src and @a dst. It should most likely be @c stretch or @c repeat.
+
+ <h3>Displacement map</h3>
+
+ The @a map buffer is an RGBA image containing displacement and alpha values.
+ Its size can be different from @c src or @c dst.
+
+ The @b red channel is used for X displacements while the @b 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 <tt>signed char</tt> is used instead of <tt>unsigned char</tt> to
represent
+ these R and G values, then < 0 means displace top/left while > 0 means
bottom/right.
+
+ The @c alpha channel is used as an alpha multiplier for blending.
+
+ Considering <tt>I(x, y)</tt> represents the pixel at position (x, y) in the
+ image I, then here is how the displacement is applied to @a dst:
+ @code
+ D = map (x, y)
+ dst (x, y) += D.alpha * src (D.red * intensity / 128, D.green * intensity
/ 128)
+ @endcode
+ Of course, the real algorithm takes into account interpolation between
pixels as well.
+
+ @since 1.9
+ */
+
static Eina_Bool
_displace_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -948,16 +1334,6 @@ _displace_instruction_prepare(Evas_Filter_Instruction
*instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "displace"),
EINA_FALSE);
- /*
- * displace [map=]BUFFER [intensity=]INT [flags=]STRING \
- * [src=BUFFER] [dst=BUFFER]
- *
- * flags can be: (FIXME TBD)
- * alpha
- * RG/redgreen
- * XY
- */
-
instr->type = EVAS_FILTER_MODE_DISPLACE;
instr->pad.update = _displace_padding_update;
_instruction_param_seq_add(instr, "map", VT_BUFFER, NULL);
@@ -970,6 +1346,34 @@ _displace_instruction_prepare(Evas_Filter_Instruction
*instr)
return EINA_TRUE;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_fill Fill
+
+ Fill a buffer with a specific color.
+ Not blending, can be used to clear a buffer.
+
+ @code
+ fill (dst = output, color = transparent, l = 0, r = 0, t = 0, b = 0);
+ @endcode
+
+ @param dst Target buffer to fill with @a color.
+ @param color The color used to fill the buffer. All pixels within the
fill area will be reset to this value. See @ref evasfilters_color "colors".
+ @param l Left padding: skip @a l pixels from the left border of the
buffer
+ @param r Right padding: skip @a r pixels from the right border of
the buffer
+ @param t Top padding: skip @a t pixels from the top border of the
buffer
+ @param b Bottom padding: skip @a b pixels from the bottom border of
the buffer
+
+ This function should generally not be used, except for:
+ <ul>
+ <li>@a Testing an effect over a specific background color</li>
+ <li>Clearing out a buffer with either white or transparent color</li>
+ </ul>
+
+ @since 1.9
+ */
+
static Eina_Bool
_fill_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -977,16 +1381,6 @@ _fill_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "fill"),
EINA_FALSE);
- /*
- * fill [dst=BUFFER] [color=COLOR] (l=INT) (r=INT) (t=INT) (b=INT)
- *
- * Works with both Alpha and RGBA.
- *
- * The geometry is defined by l, r, t, b, offsets from the edges of the
buffer
- * These offsets always go INWARDS, which means b > 0 goes UP, while t > 0
- * goes DOWN.
- */
-
instr->type = EVAS_FILTER_MODE_FILL;
_instruction_param_seq_add(instr, "dst", VT_BUFFER, "output");
_instruction_param_seq_add(instr, "color", VT_COLOR, 0x0);
@@ -1034,6 +1428,37 @@ _grow_padding_update(Evas_Filter_Program *pgm,
Evas_Filter_Instruction *instr,
if (out->pad.b < b) out->pad.b = b;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_grow Grow
+
+ Grow or shrink a buffer's contents. This is not a zoom effect.
+
+ @code
+ grow (radius, smooth = true, src = input, dst = output);
+ @endcode
+
+ @param radius The radius of the grow kernel.
+ If a negative value is specified, the contents will shrink
rather than grow.
+ @param smooth If @c true, use a smooth transitions between black and white
(smooth blur and smoother curve).
+ @param src Source buffer to blur.
+ @param dst Destination buffer for blending. This must be of same size
and colorspace as @a src.
+
+ Example:
+ @code
+ buffer : fat (alpha);
+ grow (4, dst = fat);
+ blend (src = fat, color = black);
+ blend (color = white);
+ @endcode
+ This will first grow the letters in the buffer @c input by 4px, and then draw
+ this buffer in black in the background. Blending white on top of that will
+ give a simple impression of stroked text.
+
+ @since 1.9
+ */
+
static Eina_Bool
_grow_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -1041,10 +1466,6 @@ _grow_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "grow"),
EINA_FALSE);
- /*
- * grow [radius=]INT (smooth=BOOL) (src=BUFFER) (dst=BUFFER)
- */
-
instr->type = EVAS_FILTER_MODE_GROW;
instr->pad.update = _grow_padding_update;
_instruction_param_seq_add(instr, "radius", VT_INT, 0);
@@ -1055,6 +1476,38 @@ _grow_instruction_prepare(Evas_Filter_Instruction *instr)
return EINA_TRUE;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_mask Mask
+
+ Blend two buffers into a destination.
+
+ @code
+ mask (mask, src = input, dst = output, color = white, fillmode = none);
+ @endcode
+
+ @param mask A mask or texture to blend with the input @a src into the
target @a dst.
+ @param src Source buffer. This can also be thought of a mask if @a src
is alpha and @a mask is RGBA.
+ @param dst Destination buffer for blending. This must be of same size
and colorspace as @a src.
+ @param color A color to use as multiplier for the blend operation. White
means no change. See @ref evasfilters_color "colors".
+ @param fillmode Defines whether to stretch or repeat the @a mask if its size
that of @src. Should be set when masking with external textures. Default is
none.
+
+ Note that @a src and @a mask are interchangeable, if they have the same
dimensions.
+
+ Example:
+ @code
+ buffer: a (alpha);
+ blur(5, dst = a);
+ curve(points = 0:255 - 128:255 - 255:0, src = a, dst = a);
+ blend(color = black);
+ mask(mask = a, color = cyan);
+ @endcode
+ This will create a simple cyan inner glow effect on black text.
+
+ @since 1.9
+ */
+
static Eina_Bool
_mask_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -1062,10 +1515,6 @@ _mask_instruction_prepare(Evas_Filter_Instruction *instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "mask"),
EINA_FALSE);
- /*
- * mask [mask=]BUFFER [src=BUFFER] [dst=BUFFER] [color=COLOR]
- */
-
instr->type = EVAS_FILTER_MODE_MASK;
_instruction_param_seq_add(instr, "mask", VT_BUFFER, NULL);
_instruction_param_seq_add(instr, "src", VT_BUFFER, "input");
@@ -1110,6 +1559,39 @@ _transform_padding_update(Evas_Filter_Program *pgm,
if (padb) *padb = b;
}
+/**
+ @page evasfiltersref
+
+ @subsection sec_commands_transform Transform
+
+ Apply a geometrical transformation to a buffer.
+
+ Right now, only <b>vertical flip</b> is implemented and available.
+
+ @code
+ transform (dst, op = vflip, src = input, oy = 0);
+ @endcode
+
+ @param dst Destination buffer. Must be of the same colorspace as @a
src. Must be specified.
+ @param op Must be @c vflip. There is no other operation yet.
+ @param src Source buffer to transform.
+ @param oy Y offset.
+
+ Example:
+ @code
+ buffer : t (alpha);
+ transform (oy = 20, dst = t);
+ blend (src = t, color = silver);
+ blend (color = white);
+ @endcode
+ This will create a mirrored text effect, for a font of 50px.
+
+ @note Because of the meaning of @a oy, this effect probably needs to be
+ customized for a single font size (FIXME).
+
+ @since 1.9
+ */
+
static Eina_Bool
_transform_instruction_prepare(Evas_Filter_Instruction *instr)
{
@@ -1117,10 +1599,6 @@ _transform_instruction_prepare(Evas_Filter_Instruction
*instr)
EINA_SAFETY_ON_NULL_RETURN_VAL(instr->name, EINA_FALSE);
EINA_SAFETY_ON_FALSE_RETURN_VAL(!strcasecmp(instr->name, "transform"),
EINA_FALSE);
- /*
- * mask [op=]STRING [input=BUFFER] [output=BUFFER] (oy=INT)
- */
-
instr->type = EVAS_FILTER_MODE_TRANSFORM;
instr->pad.update = _transform_padding_update;
_instruction_param_seq_add(instr, "dst", VT_BUFFER, NULL);
@@ -1209,13 +1687,6 @@ _instruction_buffer_parse(Evas_Filter_Program *pgm, char
*command)
Eina_Bool alpha = EINA_FALSE;
size_t sz;
- /** @internal
- * Parse a buffer instruction. Its syntax is:
- * buffer:a;
- * buffer:a(rgba);
- * buffer:a(alpha);
- */
-
tok = strchr(command, ':');
PARSE_CHECK(tok);
PARSE_CHECK(!strncasecmp("buffer:", command, tok - command));
--
