--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/imageml-plugin/imageml-plugin.rst Tue Aug 10 14:29:28 2010 +0300
@@ -0,0 +1,214 @@
+User guide for ImageML Plugin usage in ConE
+===========================================
+
+Introduction
+------------
+This page describes how to use the ConE ImageML plug-in.
+The plug-in defines the ImageML Implementation Markup Language, which provides
+image conversion from BMP to MBM and SVG to MIF using the ``mifconv`` and
+``bmconv`` tools.
+
+XML namespace and file extension
+--------------------------------
+
+- Namespace: ``http://www.s60.com/xml/imageml/1``
+- File extension: ``imageml``
+
+ImageML elements
+----------------
+
+The ImageML XML element model is drawn out as a UML class diagram below:
+
+ .. image:: imageml.jpg
+
+output
+^^^^^^
+
+The ``output`` element defines an output file for image conversion. A single
+ImageML implementation may contain multiple ``output`` elements.
+
+**Attributes**
+
+ * *file* - Output file location, for example ``resource/apps/image.mbm``.
+ The output tool used to perform the conversion is deduced from the file
+ extension: bmconv for .mbm and mifconv for .mif. The file location can
+ also come from a ConfML setting using the ``${}`` notation.
+ * *tool* - Override for the path to the tool to use. This is mainly useful
+ for testing, in production use the bmconv and mifconv tools should be in PATH.
+ * *palette* - Specifies a .pal file to use for MBM conversion.
+ * *tooldir* - Override for the location of the bmconv and mifconv tools.
+ This is mainly useful for testing, in production use the bmconv and mifconv
+ tools should be in PATH.
+ * *extraparams* - Optional attribute that can be used to pass extra parameters
+ for tool. For details see bmconv and mifconv documentation. E.g. "/V3" defines
+ for mifconv the format version of SVG binary conversion. If not defined value
+ forces Svgtbinencode to use the default platform specific value.
+ Options for mifconv /V parameter are:
+
+.. list-table::
+
+ - - *Value*
+ - *Format type*
+ - - /V1
+ - BGR / float encoding
+ - - /V2
+ - BGR / fixed point encoding
+ - - /V3
+ - RGB / fixed point encoding
+ - - /V4
+ - RGB / float encoding
+ - - /V5
+ - NVG encoding
+
+
+**Example**
+
+.. code-block:: xml
+
+ <output file="resource/apps/startup.mbm">
+
+ <output file="resource/apps/startup.mif">
+
+ <!--
+ The drive letter is automatically stripped, and the output location
+ is the same as in the example above
+ -->
+ <output file="Z:\\resource\\apps\\startup.mif">
+
+ <output file="${StartupSettings.StartupAnimationPath}">
+
+
+input
+^^^^^
+
+The ``input`` element defines a single input file for image conversion, or a
+directory from which input files are selected based on regular expression
+patterns. One ``output`` element may contain multiple ``input`` elements.
+
+An input element must specify a file using the ``file`` attribute or a directory
+using the ``dir`` attribute, but not both.
+
+**Attributes**
+
+ * *file* - Input file from the configuration project content. Can also be
+ a ConfML setting reference using the ``${}`` notation.
+ * *dir* - Directory for input files from the configuration project content.
+ Can also be a ConfML setting reference using the ``${}`` notation.
+ * *depth* - Color depth switch passed to bmconv for the file(s) specified by
+ the current ``input`` element, does nothing if mifconv is used.
+ Can also be a ConfML setting reference using the ``${}`` notation.
+ * *optional* - If ``true``, then the input dir or file may be empty and
+ no error is reported. Can be used to e.g. specify an optional mask bitmap.
+
+**Examples**
+
+.. code-block:: xml
+
+ <input file="images/icon.svg"/>
+
+ <input file="images/image.bmp" depth="c24"/>
+
+ <input file="images/image_mask.bmp" depth="c1" optional="true"/>
+
+ <input file="${TestFeature.BmpFile.localPath}" depth="${TestFeature.BmpDepth}"/>
+
+ <input dir="images/svg_files/">
+ <include pattern="svg$"/>
+ <exclude pattern=".svn"/>
+ </input>
+
+
+include and exclude
+^^^^^^^^^^^^^^^^^^^
+
+The ``include`` and ``exclude`` elements specify regular expressions for
+selecting input files from an input directory.
+
+**Attributes**
+
+ * *pattern* - The regular expression used to include or exclude files
+
+**Examples**
+
+.. code-block:: xml
+
+ <include pattern="svg$"/>
+ <include pattern="bmp$"/>
+ <exclude pattern=".svn"/>
+
+Setting references
+------------------
+
+The setting references that an ImageML implementation uses are determined as
+follows:
+
+ * If any ``input`` elements contain setting references in their ``file``
+ or ``dir`` attributes, those are the setting references used by the
+ ImageML implementation.
+ * If there are no setting references in those attributes, setting references
+ are considered to be irrelevant, and the implementation is always run
+ regardless of setting reference filtering.
+
+See the examples in the section below.
+
+ImageML examples
+----------------
+
+All the examples shown in this section can also be downloaded:
+
+ * :download:`imageml-example-project.zip`
+
+You need to have bmconv and mifconv somewhere in your path for generation to
+work. To generate output from the project simply run::
+
+ > cone generate -p imageml-example-project.zip
+
+Or unzip (e.g. to ``imageml-example-project``) and run::
+
+ > cd imageml-example-project
+ imageml-example-project\> cone generate
+
+
+Simple image conversion using a single input file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: examples/simple.imageml
+ :language: xml
+
+Setting references of this implementation: None (irrelevant)
+
+Simple image conversion with ConfML setting references
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: examples/with_refs.imageml
+ :language: xml
+
+Setting references of this implementation:
+
+ - ``TestSettings.ConeInputBmp.localPath``
+ - ``TestSettings.IconInputSvg.localPath``
+
+MBM conversion using multiple input files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: examples/multi_input.imageml
+ :language: xml
+
+Setting references of this implementation: None (irrelevant)
+
+MBM conversion using an optional mask file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: examples/bmp_and_optional_mask.imageml
+ :language: xml
+
+Setting references of this implementation:
+
+ - ``TestSettings.ConeInputBmp.localPath``
+ - ``TestSettings.ConeInputBmpMask.localPath``
+
+FAQ
+---
+
+This will be updated based on the questions.
+