X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=effects%2FREADME;h=7cc34eb76d72f009dc6c06afec232c32b64ee00b;hb=ac8c99168f151e2f351043d13500741ce1ca8966;hp=89b83271615827f97983d4f8ad66578e1438a4c9;hpb=98ed961ae42ab3dc0676dc2b5a0da793207059b5;p=kdenlive

diff --git a/effects/README b/effects/README
index 89b83271..7cc34eb7 100644
--- a/effects/README
+++ b/effects/README
@@ -1,56 +1,139 @@
-Effects 
+================================
+------------EFFECTS-------------
+================================
 
-Kdenlive uses MLT for all video/audio effects. Effects in Kdenlive are now built using 
-xml files describing the effect and its parameters.
+==========
+Kdenlive uses MLT for all video/audio effects/filters.
+For filters that provide metadata the GUI can be generated automatically.
+If the generated GUI is not sufficient a custom one can be build using a XML
+file describing the effect and its parameters.
+==========
 
-Here is a sample effect file:
 
---------------------------------------------------------------------------------------
-
-1  <!DOCTYPE kpartgui>
-2  <effect tag="motion_est">
-3	<name>Auto Mask</name>
-4	<properties id="autotrack_rectangle" tag="autotrack_rectangle" />
-5	<parameter type="geometry" name="geometry" default="100,100:100x100">
-6		<name>Geometry</name>
-7	</parameter>
-8	<parameter type="bool" name="debug" default="1">
-9		<name>Debug</name>
-10	</parameter>
-11	<parameter type="bool" name="obscure" default="0">
-12		<name>Obscure</name>
-13	</parameter>
-14 </effect>
 
+==========
+The basic structure of a XML filter description:
+--------------------------------------------------------------------------------------
+01 <!DOCTYPE kpartgui>
+02 <effect tag="mlt_filter" id="mlt_filter_custom1">
+03      <name>Filter name</name>
+04      <description>Filter the image</description>
+05      <author>Anon</author>
+06      <parameter type="constant" name="amount" default="10" min="0" max="1000" factor="1000">
+07              <name>Amount of filtering</name>
+08      </parameter>
+09      <parameter type="bool" name="enable" default="0">
+10              <name>Enable</name>
+11      </parameter>
+15 </effect>
 --------------------------------------------------------------------------------------
 
+Line 1:
+    - required to make strings used in the effect translatable
+Line 2:
+    - tag: MLT ("mlt_service") name of the effect
+    - id: internal kdenlive id, can be anything, but must be unique for each effect
+    - type: (default = "video") whether effect modifies video or audio (use "audio" then)
+    - unique: (default = "0") this effect cannot be attached multiple times to one clip (speed, fades, ...)
+    - version: (optional) minimum version of the effect required to be available (works only if the MLT filter provides the necessary metadata)
+Line 3:
+    - name of the effect that will appear to the user
+Line 4:
+    - Short description of the effect to be shown in the effect list
+    - Additionally a <full> part can be added inside. It's content will be available in the effect stack (see frei0r_lightgraffiti.xml for an example):
+        - supports HTML formatting (requires the use of CDATA)
+Line 5:
+    - name of the author(s) of the filter (not of the XML file ;))
+The rest:
+    - list of effect parameters:
+        - tag "name": visible name of the parameter (depending on the GUI this parameter uses)
+        - tag "comment": (optional) description of the parameter (support HTML formatting) (not yet supported by all widgets)
+        - attribute "name": MLT filter parameter name
+        - attribute "paramprefix": a string to be prepended to the parameter value before passing it to MLT
+        - attribute "default": initial value, format depends on parameter type
+        - attribute "type": widget (GUI) to use
+            - "fixed":
+                - sets a (MLT filter) parameter, but does not expose it to the user (no GUI)
+            - "constant":
+                - number
+                - represented by a slider
+                - additional parameter attributes:
+                    - "factor": (optional) values coming from MLT will be multiplied with factor
+                    - "offset": (optional) will be added to values coming from MLT after "factor" is applied
+                    - "min": smallest value possible (after multiplying with "factor")
+                    - "max": largest value possible (after multiplying with "factor")
+                    - "suffix": (optional) displayed unit of the values
+            - "double":
+                - synonym for "constant"
+            - "bool": 
+                - true/false
+                - represented by a checkbox
+            - "list":
+                - multiple choice
+                - represented by a drop-down menu
+                - additional parameter attribute:
+                    - "paramlist": list of possible values separated by semicolon (no whitespaces!)
+                - addtional tag:
+                    - "paramlistdisplay": (optional) list of names to use for the values separated by comma
+            - "position":
+                - time stored as frame number
+                - represented by a slider
+            - "color":
+                - color value, similar to representation HTML ("#rrggbb"/"#aarrggbb" or "0xrrggbbaa")
+                - represented by a button opening the KDE color dialog + a color picker button
+                - additional attributes:
+                    - "alpha": (default = "0") use to enable alpha support
+            - "keyframe":
+                - keyframable number
+                - keyframes are opt-in (only one keyframe by default -> should be prefered over "constant" whenever possible)
+                - works with MLT filters that utilize start/end values
+                - same attributes as "constant"
+                - additional attributes:
+                    - "intimeline": (default = "0") parameter to preselect for editing in the timeline (only one parameter can have "1")
+                    - "widget": (optional) GUI based on the standard keyframe GUI (possible values: "corners")
+            - "simplekeyframe":
+                - works with MLT filters that use mlt_geometry for keyframe support (includes all frei0r filters)
+                - same attributes as "keyframe"
+            - "geometry":
+                - a rectangle: postion + dimension + additional value
+                - works with MLT filters using mlt_geometry
+                - the rect can be edited on the project monitor
+                - additional attributes:
+                    - "fixed": (default = "0") use to disable keyframe support
+                    - "showrotation": (default = "0") use to enable support to 3 axis rotation
+                    - "opacity": (default = "true") use to disable support of the opacity setting
+            - "url":
+                - url/path
+                - represented by button to open "file open" dialog
+            - "wipe":
+                - special GUI for the wipe transition makes it possible to select a direction of a slide
+            - "addedgeometry":
+                - parameter linked to a "geometry" parameter
+            - "curve":
+                - cubic curve editor for the frei0r color curves filter (old version)
+            - "bezier_spline":
+                - cubic Bézier spline editor for the frei0r color curves filter (new version, might be reused for other filters)
+            - "roto-spline":
+                - GUI for the rotoscoping filter (spline on the monitor)
+            - "keywords":
+                - Text entry with a selection of possible keywords to be inserted in the text.
+                - additional tags:
+                    - "keywords": list of possible keyword values separated by semicolon
+                    - "keywordsdisplay": list of names to use for the values separated by semicolon
+            - "fontfamily":
+                - Font typeface entry
+==========
 
-Line 1 is required to have the effect and parameter names added to the translation files
-In line 2, the "tag" is the name of the mlt filter
-Line 3 is the name of the effect that will appear to the user
-Line 4 holds several effect parameters:
-	id is an internal kdenlive id, can be anything, but must be unique for each effect
-	tag is the "mlt_service" name of the effect
-	type defines if the effect is "audio" or "video". If omitted, effect is considered as video
-
-Then, you have the parameter definitions.
-The parameter entry has the following attributes:
-	type is used by Kdenlive to build the UI for this effect.
-		allowed types are: 
-		- constant = a number, represented by a slider
-		- bool = boolean value, represented as a checkbox
-		- color = a color value, represented by a selectable color button
-		- list = a combobox listing different strings
-		- geometry = 4 different sliders for x, y, width and height values that will end up as x,y:wxh
-		- position = a frame number that can be obtained from current cursor position
-		- double = a number with keyframes
-		- complex = only used in obscure effect, has x, y, width, height and pixellation values
-
-		The integer values can have max, min and default values defined, see effect files in this folder for more examples
-	the "name" parameter is the name that will be passed to MLT
-
-The "name" tag gives the parameter name as it will appear to the user
+==========
+Effects can be blacklisted in kdenlive/data/blacklisted_effects.txt
+All effects with a custom XML GUI need to be blacklisted.
+==========
 
-Kdenlive parses the effect folder at each startup, so that if you have an xml file describing a new effect, just copy it in your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.
+==========
+Effects can be assigned to an effect category in kdenlive/data/kdenliveeffectscategory.rc.
+==========
 
-Effects need to be blacklisted in the file kdenlive/data/blacklisted_effects.txt if they use a custom (i.e. non-default) XML GUI from this directory.
\ No newline at end of file
+==========
+Kdenlive parses the effect folder at each startup, so that if you have an XML file describing a new effect,
+just copy it to your ~/.kde/share/apps/kdenlive/effects/ folder and restart Kdenlive to enable the new effect.
+==========