/** @page install_current Installation

    @section install Installation
    Oyranos depends on following libraries:\n

    <ul>
    <li> libxml2 - http://www.xmlsoft.org/ </li>
    <li> icc-profiles-openicc s needed as default ICC profiles - http://sourceforge.net/projects/openicc/files/OpenICC-Profiles/i </li>
    <li> icc-profiles-basiccolor-printing is needed as default ICC profiles - http://sourceforge.net/projects/openicc/files/basICColor-Profiles/ </li>
    <li> libXinerama, libXrandr, libXfixes and libXxf86vm for X11 support - http://www.x.org </li>
    <li> littleCMS lcms2 API and optionally lcms1 for color conversions - http://www.littlecms.com </li>
    <li> libpng for PNG image support - http://sourceforge.net/projects/libpng/files/ </li>
    </ul>
    Optional:
    <ul>
    <li> Yajl, a JSON parser, is required and included. A externaly installed version is detected automatically. - http://lloyd.github.com/yajl </li>
    <li> libOpenICC, a JSON configuration DB API, is required and included. A externaly installed version is detected automatically. - https://github.com/OpenICC/config </li>
    <li> Elektra is a configuration DB API emitting D-Bus messages, currently version 0.8.+ - http://freedesktop.org/wiki/Software/Elektra </li>
    <li> libXcm for X11 and Quarz monitor support, is required and included. A externaly installed version is detected automatically. - http://www.oyranos.org/libxcm </li>
    <li> FLTK for various example code, version >= 1.3.0 is recommended - http://www.fltk.org </li>
    <li> Qt for QCmsEvents - http://qt-project.org/ </li>
    <li> Xcalib for loading a given  VideoCardGammaTag from profile to a running XFree86/Xorg session (optionally) - http://www.etg.e-technik.uni-erlangen.de/web/doe/xcalib/ </li>
    <li> CUPS for printing support - http://www.cups.org/ </li>
    <li> libraw for CamerRAW support - http://www.libraw.org/ </li>
    </ul>\n
    For building unpack the tgz file and type: make; make install.\n\n
    Optionally you can specifiy an other than the default prefix /opt/local by typing:\n
    configure.sh --prefix=/what/you/like\n
    make\n
    make install   (optionally)\n
 */

/** @page environment Environment Variables

    @section path_vars Path Variables
    The XDG variables affect Oyranos' profile search. Oyranos searches under
    each provided paths color/icc directory, 
    e.g. XDG_DATA_HOME=~/.local/share results in a additional search in
    ~/.local/share/color/icc. More details can be found in <a href="http://www.oyranos.org/wiki/index.php?title=OpenIccDirectoryProposal">OpenIccDirectoryProposal at ColourWiki</a>.

    @section i18n_vars Internationalisation Variables
    OY_LOCALEDIR is described together with the internal ::oy_domain_codeset.

    @section runtime_vars Runtime Variables
    OY_MODULE_PATH can contain paths to meta and normal modules together.
    The given paths are scanned recursively to find the modules.

    @section debug_vars Debugging Variables
    OY_DEBUG influences the internal ::oy_debug variable. Its value
    changes the output level. See as well oyranos_debug.[h,c] . The configure
    switch --enable-debug enables most of the available output. \n
    OY_DEBUG_MEMORY sets the internal ::oy_debug_memory variable on and
    helps somewhat in detecting memory leaks. This variable is dangerous and 
    should not to be run for production use. \n
    OY_DEBUG_OBJECTS is used to frequently print infos 
    about objects on stderr. The value of OY_DEBUG_OBJECTS can be a
    - Object ID or a
    - type name like "oyImage_s","Image" to track all oyImage_s type objects or
    - "1" to print track informations about all trackable objects.
    - "-1" to omit printing track informations.
 
    OY_DEBUG_SIGNALS sets the internal ::oy_debug_signals variable on and
    helps in tracing signals. This variable is dangerous and 
    should not to be run for production use. \n
    OY_DEBUG_WRITE together with OY_DEBUG is used to tell, that a file output
    is appreciated. Writing files will usually slow down debugging. \n
    OY_BACKTRACE can be set to a debug message string and will then place
    a backtrace text from gdb into the console. That needs the debug message
    to be visible.
 */

/** @page extending_oyranos Extending Oyranos

    @section oyranos_modules_writing Oyranos modules writing

    Note known object types, like oyCMM_s or oyCMMapi4_s, are linked to their 
    according documention. All others are still internal data structures, 
    which might get exported in future versions of Oyranos.

    @subsection write_modules Writing C Modules for Oyranos
    Oyranos modules can be filters, plug-ins, backends, CMMs or meta modules.
    The API design can be seen in the @ref module_api page. To start with a 
    module use the example code from the
    src/examples/oyranos_cmm_dFil.c file.
    Change the header, e.g. "My name" string. Select a four byte identifier for
    the new module and define it in CMM_NICK. The comment above CMM_NICK
    describes how the module library and the xxxx_cmm_module data structure 
    (vtable) interact. Oyranos will search the appropriate
    path for libraries and will try to dlopen the oyCMM_s xxxx_cmm_module data 
    structure. It therefore parses the library file name and takes the four 
    bytes before "_cmm_module" as the modules identifier. The "xxxx_cmm_module"
    symbol will be searched and if found the information form there will be used
    to access the module functions and data. E.G. Oyranos will on Linux dlopen 
    a module library name of "liboyranos_lcm2_cmm_module.so" and search for a 
    "lcm2_cmm_module" symbol. CMM_NICK is defined as "lcm2" in this module. \n
    \n
    If you choose your four byte identifier, substitute every occurence of
    "dFil" with the new identifier. \n
    \n
    In the OY_DUMMY_FILTER_REGISTRATION macro the "my_filter" name should be
    changed to something appropriate for the new module. Oyranos users will use
    primarily this name to select the module. A description on how a module 
    @ref registration string is to be build and how it works can be found at the end
    of the Detailed Description section on @ref module_api. All occurences
    of "my_filter" in the file should be substituted accordingly. \n
    \n
    The old function dFilGetText should be adapted to provide the new 
    appropriate names, copyrights and a help texts on how to use the module.
    Go through all functions and adapt them to the filter needs. The
    dFilFilterPlug_MyFilterRun function is the core of the module. It contains
    the processing part or algorythm. Typically a filter contains two
    connectors, a plug and a socket. The connectors describe their capabilities
    and according to this Oyranos can check in advance if two filters fit each
    to the other. \n
    \n
    The oyCMMapi4_s holds most static informations of the module. It can be used
    to provide a processing context. A context is use in case it is very 
    expensive to compute such a context like in ICC CMMs for color conversions
    and the context shall be chached by Oyranos. The oyCMMapi7_s holds the 
    dFilFilterPlug_MyFilterRun function and the plugs and sockets. \n
    \n
    Compile and install the module library to see if Oyranos detects it 
    correctly. Use the test2 application therefore. It is in the source tree
    compiled through the "make check" shell command. The shell command to run is
    "test2 'CMMS list'". The test run will list all detected meta modules and
    the modules loaded by a meta module. The filters are sorted by their 
    provided APIs. The test2 command might be substituted by a dedicated module
    utility in the future. As external checker use oyranos-xforms-modules -l.

    @subsection write_device_modules Writing Device Modules for Oyranos
    For monitor devices exist a simple abstraction layer to hook a display
    system in. Please read @ref monitor_hooks_api.

    To start with a module use the src/examples/oyranos_cmm_dDev.c 
    file and modify it. Please follow the @ref write_modules subsection.
    The parts which differ are that instead of oyCMMapi4_s the oyCMMapi8_s
    will be implemented. The dDevConfigs_FromPattern 
    (oyCMMapi8_s::oyConfigs_FromPattern) is a function to
    call into the device module and create new oyConfig_s object(s).
    The dDevConfigs_Modify (oyCMMapi8_s::oyConfigs_Modify) function can use the
    same protocol with the difference, that it works on existing oyConfig_s 
    object(s). The "device_name" option should be ignored by dDevConfigs_Modify.
    The dDev_rank_map (oyCMMapi8_s::rank_map) tells how each option shall
    be wighted by Oyranos to select a profile from the Oyranos DB independent 
    from the device module. The calls into dDevConfigs_FromPattern and
    oyConfigs_Modify are string based. The option "command" will contain the 
    command name the device module shall act upon. \n
    \n
    The oyCMMapi8_s::registration string needs in its oyFILTER_REG_APPLICATION
    section a starting "config.icc_profile." followed by the
    device class name and separated by point '.' the the module nick. This
    convention shall enshure a proper mechanism is available to select the
    desired config domains from several ones. \n
    \n
    All "dDev" occurences in the source code need to be substituted by the 
    modules own four byte identifier. \n
    \n
    To test the device module use oyDeviceAskProfile(), oyDeviceGetInfo() and
    oyDeviceGet():
    @code
    oyConfig_s * device = 0; /* initialise with zero to avoid errors */
    oyProfile_s * profile = 0;
    oyOptions_s * options = 0;  /* not used in this example */
    char * text = 0;

    /* Call into the device modules oyCMMapi8_s::oyConfigs_FromPattern
     * function with the "list" command.
     * "monitor" is to be exchanged by the actual device class and
     * ":0.0" by the actual device nick name.
     */
    int error = oyDeviceGet( 0, "monitor", ":0.0", options, &device );

    /* obtain a expensive list of key/value pairs from the device module */
    error = oyDeviceGetInfo( device, oyNAME_DESCRIPTION, 0, &text,
                                     malloc );

    /* assign a profile to the device/driver */
    error = oyDeviceSetProfile( device, "some_real_profile_in_your_path.icc" );

    /* Ask Oyranos to lookup its DB for a matching profile. It is only useful
     * if a profile is already set for the devices keys. The set devices can be
     * viewed at the command line with:
     * kdb ls user/org/freedesktop/openicc/device/config.icc_profile.*
     */
    error = oyDeviceAskProfile( device, &profile );
    @endcode
    It is useful to step through the code. Oyranos provides the --enable-debug
    configure option to aid debugging and stepping through. To build the module
    add the -g compiler option.

    The protocal on how the modules communicate with the core and the front end
    is described in the @ref device_protocol_1.
 */


/** @page links References
    @section links Links
    - cross platform color information exchange standard, called ICC - http://www.color.org
    - OpenICC: http://www.freedesktop.org/wiki/OpenIcc
    - Email list: https://lists.sourceforge.net/lists/listinfo/oyranos-devel
    - Bug reports: https://github.com/oyranos-cms/oyranos/issues
    - Oyranos project page: http://www.oyranos.org/wiki/index.php?title=Oyranos
    - ColourWiki: http://www.oyranos.org/wiki
    - Elektra, configuration engine used on Linux - http://freedesktop.org/wiki/Software/Elektra
    - littleCMS, color conversion engine - http://www.littlecms.com
    - Xcalib, a vcgt to window server uploader - http://www.etg.e-technik.uni-erlangen.de/web/doe/xcalib/
    - Directory paths for color profiles and other configuration data <a href="http://www.oyranos.org/wiki/index.php?title=OpenIccDirectoryProposal">OpenIccDirectoryProposal at ColourWiki</a>
    - X11 Requirements http://www.oyranos.org/wiki/index.php?title=Oyranos_X11_Requirements
 */

/** @file oyranos.h
    @brief The API header for general users to include in your application.
    
    This file contains all functions and structs available in the Oyranos API.\n
    For further macros see @file oyranos_definitions.h\n
    For the Oyranos Monitor API see @file oyranos_monitor.h
*/

/** @file oyranos_definitions.h
    @brief The macro header to include in your application without using any Oyranos function.
    
    This file contains all macros which are relevant to the Oyranos API using
    the Elektra library as configuration engine.\n
    For the Oyranos API see @file oyranos.h\n
    @see <a href="http://freedesktop.org/wiki/Software/Elektra">Elektra</a>
*/

/** @file oyranos_monitor.h
    @brief The Monitor API header to include in your application.
    
    This file contains all functions and structs available in the Oyranos Monitor API.\n
    @see oyranos_definitions.h for Elektra macros\n
    @see oyranos.h for the Oyranos API
*/

/** @file oyranos_config.h
    @brief The API header for adminitrative users to include in configuration 
           dialogs.
    
    @see oyranos.h for the non administrative Oyranos API
*/

/** @file oyranos.c
    @brief The API implementation
    
    This file contains functions implementing the Oyranos API.\n
    For the Oyranos API see @file oyranos.h
*/

/** @file oyranos_monitor.c
    @brief The Monitor API implementation
    
    This file contains functions implementing the Oyranos Monitor API.\n
    For the Oyranos Monitor API see @file oyranos_monitor.h\n
    For the Oyranos API see @file oyranos.h
*/

/** @file oyranos_gamma.c
    @brief A small helper for setting up Oyranos at the window server
           start time.
    
    This helper searches for the appropriate monitor profile in the Oyranos 
    Deviceprofiles database. If found it tells the window server about it and
    loads a possibly available VideoCardGammaTable tag into the running session.
    It uses the Oyranos Monitor API from @file oyranos_monitor.h
*/


/** \addtogroup color Color
 *
 *  Oyranos is based one the well established ICC standard and various other specifications for color characterisation and processing. Defaults configuration and storage are provided. Oyranos covers a Color Matching Module (CMM) framework for color processing. Color devices settings, Named Color interfaces and some common calculations are provided.
 *
 *  @{
 */

/** \addtogroup devices_handling Device Handling
 *
 *  Device Handling inside Oyranos is based on a key/value set, which
 *  describes a device and the associated profile. An additional matching set,
 *  allows Oyranos to compare different device configurations with a given
 *  devices key/value set. If accepted a new device will be added to the proper
 *  device key namespace and is permanently stored on disk in a config DB. 
 *  In case of erasure the key set is removed from the config DB.
 *
 *  The soft matching approach is used in order to compare devices across
 *  different ports and computers. The highest match wins and it's profile
 *  is assigned. This approach allows to match oven remote profiles like
 *  ones from online DB's.
 *
 *  For direct work with the low level key/value matching use oyDeviceFromJSON(),
 *  oyRankMapFromJSON() and oyConfig_SetRankMap() API's.
 *
 *  Include the oyranos_devices.h header file to use the interfaces.
 *
 *  @{ */
/** @} *//* devices_handling */

/** \addtogroup defaults_apis Defaults Handling
 *  @{ */
/** @} *//* defaults_apis */

/** \addtogroup objects_profile
 *  @{ */
/** @} *//* objects_profile */


/** \addtogroup objects_single_color Named Colors
 *  @brief High level color objects
 *
 *  A Named Color is a single color capsulated in a object with rich
 *  information about that color. They are useful for palettes, measurements
 *  and other color samples. For colors in pixel images use the oyImage_s object.

 *  @{
 */

/** @} *//* objects_single_color */

/** @} *//* color */



/** \addtogroup objects_conversion Conversion
 *  \details Conversion front end API's.
 *  Data processing is organised by structures called acyclic graphs. A graph
 *  combines several processing elements and their according stages into one
 *  process model. A very simple graph will link elements just one by one to
 *  form a chain. More complex graphs are possible by branching and rejoining of
 *  data processing arms.
 *  Datas are requested always from the end. This makes it simple to create
 *  views at data. A observer tells the to be viewed plugin that it wants
 *  to connect and can request the data stream.
 *  In the other direction plug-ins can send events along the pipe through
 *  callbacks, e.g. for reporting errors or requesting updating of parameters.
 *  The @ref module_api explains how to create modules to plug into Oyranos.
 *
 *  \b About \b Graphs: \n
 *  The top object a user will handle is of type oyConversion_s. This 
 *  contains oyFilterNode_s objects, which describe the connections of each
 *  processing element, such as images with attached data and profile, and the
 *  filters. The Oyranos node connection concept is splitted into various
 *  structures.
 \dot
digraph G {
  bgcolor="transparent";
  rankdir=LR
  graph [fontname=Helvetica, fontsize=12];
  node [shape=record, fontname=Helvetica, fontsize=10, style="rounded,filled"];
  edge [fontname=Helvetica, fontsize=10];

  a [ label="{<plug> 0| Filter Node 1 == Input |<socket>}"];
  b [ label="{<plug> 1| Filter Node 2 |<socket>}"];
  c [ label="{<plug> 1| Filter Node 3 |<socket>}"];
  d [ label="{<plug> 2| Filter Node 4 == Output |<socket>}"];

  subgraph cluster_0 {
    label="Oyranos Filter Graph";
    color=gray;

    a:socket -> b:plug;
    b:socket -> d:plug;
    a:socket -> c:plug;
    c:socket -> d:plug;
  }
}
 \enddot
 *
 *  \b Connectors \b have \b tree \b missions:
 *  - The first is to tell others to about the 
 *  filters intention to provide a connection endity. This is done by the pure
 *  existence of the oyConnector_s inside the module filter structure
 *  (oyCMMapi4_s) and the oyFilterNode_s::sockets and 
 *  oyFilterNode_s::plugs members. \n
 *  - The second is to tell about the connectors capabilities, to allow for 
 *  automatic checking for fittness to other connectors. \n
 *  - The thierd task of this struct is to differenciate between \a input or
 *  \a plug and \a output or \a socket. This is delegated to the
 *  oyFilterSocket_s and oyFilterPlug_s structures.
 *
 *  \b Routing: \n
 *  The connector output, called socket, side is primarily passive. The data
 *  stream is requested or viewed by the input side, called plug. 
 *  Changes are propagated by events. This turns the acyclic graph into a 
 *  dual one. The events use the same graph just in the other direction.
 *  Events and data requests are distinct.
 *  A \a plug local to the filter or filter node can be connected to a remote
 *  \a socket connector and vice versa.
 \dot
digraph G {
  bgcolor="transparent";
  node[ shape=plaintext, fontname=Helvetica, fontsize=10 ];
  edge[ fontname=Helvetica, fontsize=10 ];
  rankdir=LR
  a [label=<
<table border="0" cellborder="1" cellspacing="4">
  <tr> <td>Filter Node A</td>
      <td bgcolor="red" width="10" port="s"> socket </td>
  </tr>
</table>>
  ]
  b [label=< 
<table border="0" cellborder="1" cellspacing="4">
  <tr><td bgcolor="lightblue" width="10" port="p"> plug </td>
      <td>Filter Node B</td>
  </tr>
</table>>
  ]
  subgraph { rank=min a }

  b:p->a:s [label=request];
} 
 \enddot
 * Status information can be passed from the input side to the output side by
 * callbacks.
 \dot
digraph G {
  bgcolor="transparent";
  node[ shape=plaintext, fontname=Helvetica, fontsize=10 ];
  edge[ fontname=Helvetica, fontsize=10 ];
  rankdir=LR
  a [label=<
<table border="0" cellborder="1" cellspacing="4">
  <tr> <td>Filter Node A</td>
      <td bgcolor="red" width="10" port="s"> socket </td>
  </tr>
</table>>
  ]
  b [label=< 
<table border="0" cellborder="1" cellspacing="4">
  <tr><td bgcolor="lightblue" width="10" port="p"> plug </td>
      <td>Filter Node B</td>
  </tr>
</table>>
  ]
  subgraph { rank=min a }

  b:p->a:s [dir=back, label=callback];
} 
 \enddot
 *
 * The data flows from the socket to the plug.
 \dot
digraph G {
  bgcolor="transparent";
  node[ shape=plaintext, fontname=Helvetica, fontsize=10 ];
  edge[ fontname=Helvetica, fontsize=10 ];
  rankdir=LR
  a [label=<
<table border="0" cellborder="1" cellspacing="4">
  <tr> <td>Filter Node A</td>
      <td bgcolor="red" width="10" port="s"> socket </td>
  </tr>
</table>>
  ]
  b [label=< 
<table border="0" cellborder="1" cellspacing="4">
  <tr><td bgcolor="lightblue" width="10" port="p"> plug </td>
      <td>Filter Node B</td>
  </tr>
</table>>
  ]
  subgraph { rank=min a }

  b:p->a:s [dir=back, label=data];
} 
 \enddot
 *
 * A oyFilterNode_s can have various oyFilterPlug_s ' to obtain data from
 * different sources. The required number is described in the oyCMMapi4_s 
 * structure, which is part of oyFilterCore_s. But each plug can only connect to
 * one socket.
 \dot
digraph G {
  bgcolor="transparent";
  rankdir=LR
  node [shape=record, fontname=Helvetica, fontsize=10, style="rounded"];
  edge [fontname=Helvetica, fontsize=10];

  b [ label="{<plug> | Filter Node 2 |<socket>}"];
  c [ label="{<plug> | Filter Node 3 |<socket>}"];
  d [ label="{<plug> 2| Filter Node 4 |<socket>}"];

  b:socket -> d:plug [dir=back];
  c:socket -> d:plug [dir=back];
}
 \enddot
 *
 * oyFilterSocket_s is designed to accept arbitrary numbers of connections 
 * to allow for viewing on a filters data output or observe its state changes.
 \dot
digraph G {
  bgcolor="transparent";
  rankdir=LR
  node [shape=record, fontname=Helvetica, fontsize=10, style="rounded"];
  edge [fontname=Helvetica, fontsize=10];

  a [ label="{<plug> | Filter Node 1 |<socket>}"];
  b [ label="{<plug> 1| Filter Node 2 |<socket>}"];
  c [ label="{<plug> 1| Filter Node 3 |<socket>}"];
  d [ label="{<plug> 1| Filter Node 4 |<socket>}"];
  e [ label="{<plug> 1| Filter Node 5 |<socket>}"];

  a:socket -> b:plug [dir=back];
  a:socket -> c:plug [dir=back];
  a:socket -> d:plug [dir=back];
  a:socket -> e:plug [dir=back];
}
 \enddot

 *  @{
 */

/** \addtogroup objects_image
 *  @{
 */

/** @} objects_image */

/** @} objects_conversion */



/** \addtogroup misc
 *  @{ */
/** @} *//* misc */



/** \addtogroup module_api Backend Modules
 *  @brief Write extensions that integrate with Oyranos front end APIs
 *
 * Oyranos C modules provide support for data formats, data processing and
 *  process control, as well as configuration.
 *
 *  The module architecture covers three basic layers. There are the Module 
 *  APIs for the real stuff, the Meta Module APIs for language support and the
 *  final Oyranos objects with their User APIs.\n
 *  @dot
digraph Modules {
  bgcolor="transparent";
  nodesep=.1;
  ranksep=1.;
  //rankdir=LR;
  graph [fontname=Helvetica, fontsize=14];
  node [shape=record,fontname=Helvetica, fontsize=11, width=.1];

  subgraph cluster_0 {
    label="Oyranos Module Framework";
    color=white;
    clusterrank=global;

      node [width = 1.5, style=filled];
      i [URL="structoyCMMapi5__s.html#_details", label="Module Importer\n oyCMMapi5_s"];

      p [ label="Filter nodes / Graph handling APIs\n oyFilterNode_s"];


      api4_A [URL="structoyCMMapi4__s.html#_details",label="Context Module + UI\n oyCMMapi4_s"];
      api6_A [URL="structoyCMMapi6__s.html#_details",label="Context Converter\n oyCMMapi6_s"];
      api7_A [URL="structoyCMMapi7__s.html#_details",label="Node Module\n oyCMMapi7_s"];

      m [URL="structoyCMMapi8__s.html#_details", label="Config (Device) Functions\n oyCMMapi8_s"];
      policy [URL="structoyCMMapi9__s.html#_details", label="Policy Functions\n oyCMMapi9_s"];


      subgraph cluster_1 {
        color=gray;
        label="Module APIs"

        subgraph cluster_2 {
          rank=max;
          color=red;
         style=dashed;
          node [style="filled"];
          api4_A; api6_A; api7_A;
          label="Graph Modules and Helpers";
        }

        subgraph cluster_6 {
          color=green;
          style=dashed;
          m;
          label="Device Modules";
        }

        subgraph cluster_9 {
          color=blue;
          style=dashed;
          policy;
          label="Policy Modules";
        }

      }

      subgraph cluster_10 {
        color=gray;
        node [style="filled"];
        i;
        label="Meta Module API";
      }

      subgraph cluster_11 {
        color=gray;
        node [style="filled"];
        p;
        label="User APIs";
      }

      p -> i [arrowhead="open", color=gray];
      i -> api4_A [arrowhead="open", color=red];
      i -> api6_A [arrowhead="open", color=red];
      i -> api7_A [arrowhead="open", color=red];
      i -> m [arrowhead="open", color=green];
      i -> policy [arrowhead="open", color=blue];
  }
} @enddot
 *
 * \b User \b API:
 *  The user API allowes to contruct a filter or configuration
 *  object. Filters can be chained to directed acyclic graphs (DAGs) and data
 *  can be processed through graphs or they are deployed by higher level APIs,
 *  like named color API.
 *
 *  \b Meta \b Modules:
 *  The modules are loaded into Oyranos by meta modules. A Meta module can
 *  support different formats of modules. The basic format are the native C
 *  structures and function declarations, which allow very detailed access and 
 *  control of Oyranos objects. These C data structures for building a module
 *  are complex and need some expertise to handle. However the meta module 
 *  interface allows to write support for modules which might be written even
 *  in scripting languages. Such filters should then be loadable as normal
 *  modules and are, depending on the choosen language, very easy to understand
 *  and to write.
 *  Beside reduced access to Oyranos native C data types, script filters might
 *  become highly interchangeable outside of Oyranos.
 *
 *  \b Module \b APIs:
 *  Several interfaces allow to write different module types. They can have
 *  access to Oyranos' configuration system, build data dependent contexts,
 *  provide access to user defined data types, create custom UIs via XFORMS and
 *  possibly SVG, simply process data and connect as node into a Oyranos DAG or
 *  expose to users as policy tool for a DAG. Different module APIs expose as
 *  different user APIs.
 *  Most module authors will want to write for one of these interfaces.
 *
 *  \b High \b Abstraction: Most module interfaces have no idea themselve about
 *  what kind of data they handle. They follow very generic and abstract ideas
 *  and rules on how to do data processing in a directed acyclic graph. 
 *  The overal idea of Oyranos' graphs can be read in the 
 *  @ref objects_conversion. 
 *  The module interfaces can implement different processing stages and tell 
 *  how to combine them in a graph by Oyranos. E.g. it is possible for on module
 *  to build a cacheable context, which can be used by different modules to
 *  process data.
 *  Most of the processing logic is inside Oyranos's core. But for efficiency
 *  and flexibility modules have access to their connected neighbour plug-ins.
 *  For instance they have to call their forerunner to request for data.
 *
 *  \b Examples: For learning how modules can
 *  do useful work see the delivered modules like the lcms and oyIM ones in
 *  files like "oyranos_cmm_xxxx.c". They are linked as libraries and are
 *  installed in the "$cmmdir" and "$libdir/oyranos" paths. These paths are
 *  shown during the configuration process or through te provided oyranos-config
 *  tool. Some more coding details can be found on the @ref extending_oyranos 
 *  page.
 *
 *  The Filter API's are subdivided to allow for automatical combining of 
 *  preprocessing and processing stages. Especially in the case of expensive
 *  preprocessing data, like in CMM's, it makes sense to provide the means for
 *  combining general purpose libraries with hardware accelerated modules.
 *  This architecture allowes for combining by just providing enough interface
 *  information about their supported data formats.
 *  The following paragraphs provide a overview.
 *
 *  The oyCMMapi5_s module structure defines a meta module to load modules,
 *  from a to be defined directory with to be defined naming criterias. The 
 *  meta module loads or constructs all parts of a module, oyCMMapi4_s,
 *  oyCMMapi7_s, oyCMMapi6_s, oyCMMapi8_s and oyCMMapi9_s.
 *
 *  oyCMMapi7_s eighter deploys the context created in a oyCMMapi4_s filter, or
 *  simply processes the data of a oyFilterNode_s graph element. It is 
 *  responsible to request data from the graph and process them.
 *  Members are responsible to describe the filters capabilities for connecting
 *  to other filters in the graph. Modules can describe their own UI in 
 *  oyCMMapi4_s.
 *  oyCMMapi7_s is mandatory.
 *
 *  The oyCMMapi4_s is a structure to create a context for a oyCMMapi7_s
 *  processor. This context is a intermediate processing stage for all of the
 *  context data influencing options and input datas. The idea for tight 
 *  integration of the context functionality is to provide a well defined way
 *  of interaction for node modules with context modules. 
 *  The oyCMMapi4_s structure contains as well the GUI. oyCMMapi4_s is 
 *  mandatory because of its GUI parts.
 *  A oyCMMapi4_s without a oyCMMapi7_s is useless.
 *  oyCMMapi4_s must contain the same basic @ref registration string like the 
 *  according oyCMMapi7_s except some keywords in the application section. This
 *  is explained more below in detail.
 *  It is assumed that a generated context is worth to be cached. If Oyranos 
 *  obtains a serialised data blob from the context generator it can be
 *  automatically cached.
 *  @dot
digraph Anatomy_A {
  bgcolor="transparent";
  nodesep=.1;
  ranksep=1.;
  rankdir=LR;
  graph [fontname=Helvetica, fontsize=14];
  node [shape=record,fontname=Helvetica, fontsize=11, width=.1];

  subgraph cluster_7 {
    label="One Context - Different Data Processors";
    color=white;
    clusterrank=global;

      node [width = 2.5, style=filled];

      api4_A [label="lcms ICC color profile Module\n oyCMMapi4_s | <f>Context Creation \"oyDL\" | ... | XFORMS UI"];

      api6_A [label="lcms Context Converter\n oyCMMapi6_s\n \"oyDL\"-\>\"lcCC\" \(oyDL_lcCC\)"];
      api7_A [label="lcms color conversion Data Processor\n oyCMMapi7_s\n C implementation needs \"lcCC\" context" width = 3.5];

      api6_C [label="ctl Context Converter\n oyCMMapi6_s\n \"oyDL\"-\>\"oCTL\" \(oyDL_oCTL\)"];
      api7_C [label="ctl color conversion Data Processor\n oyCMMapi7_s\n LLVM implementation needs \"oCTL\" context" width = 3.5];

      api4_A; api6_A; api7_A;
      api7_C; api6_C;

      api4_A:f -> api6_A -> api7_A [arrowhead="open", color=black];
      api4_A:f -> api6_C -> api7_C [arrowhead="open", color=black];
  }
} @enddot
 *
 * In case a oyCMMapi7_s function can not handle a certain provided context
 *  data format, Oyranos will try to convert it for the oyCMMapi7_s API through
 *  a fitting oyCMMapi6_s data convertor. oyCMMapi6_s is only required for 
 *  filters, which request incompatible contexts from a oyCMMapi4_s structure.
 *
 *  The oyCMMapi8_s handles configurations, like external module data
 *  and options. The @ref devices_handling deployes these modules.
 *
 *  oyCMMapi9_s can be used to plug in new object types, policy settings and
 *  a way to enforce the policies.
 *
 *  @section registration Registration
 *  Each filter API provides a \b registration member string.
 *  The registration member provides the means to later successfully select 
 *  the according filter. The string is separated into sections by a slash'/'.
 *  The sections can be subdivided by point'.' for additional attributes as 
 *  needed. This pattern follows the scheme of directories with attributes or
 *  XML elements with attributes.
 *  The sections are to be filled as follows:
 *  - top, e.g. OY_TOP_SHARED (::oyFILTER_REG_TOP)
 *  - vendor, e.g. OY_DOMAIN_STD (::oyFILTER_REG_DOMAIN)
 *  - filter type, e.g. OY_TYPE_STD
 *    (::oyFILTER_REG_TYPE)
 *  - filter name, e.g. "icc.lcms._NOACCEL._CPU" (::oyFILTER_REG_APPLICATION)
 *
 *  After that the options section follows (::oyFILTER_REG_OPTION).
 *
 *  The application registration string part should for general purpose modules
 *  contain a convention string. "icc" signals to process colors with the help
 *  of ICC style profiles, which can by convention be inserted into the options
 *  list.
 *
 *  @par Filter registration:
 *  A filter can add keywords but must omit the API number and the following
 *  matching rule sign. Recommended keywords for the application section are:
 *  - _ACCEL for acceleration, required
 *  - _NOACCEL for no acceleration or plain software, required
 *  - _GPU, _GLSL, _HLSL, _MMX, _SSE, _SSE2, _3DNow and so on for certain 
 *    hardware acceleration features \n
 *  
 *  \b Example: a complete module registration: \n
 *  "org/oyranos/openicc/icc.lcms._NOACCEL._CPU" registers a plain
 *  software CMM
 * 
 *  A underscore in front of a attribute makes the attribute optional during
 *  the matching process in oyFilterRegistrationMatch(). This is needed in case
 *  a registration string is used itself as a search pattern.
 *
 *  @par Registration search pattern:
 *  To explicitely select a different processor and context creator the
 *  according registration attribute must have a number and prefix,
 *  e.g. "4_lcms" "7_octl".
 *  A search pattern can add keywords.
 *  - a number followed by underscore, plus or minus signs the according API.
 *    The feature of interesst must then be appended, e.g. "7_GPU" preferes
 *    a GPU interpolator. This is useful to select a certain API of a module.
 *    - underscore '_' means preference
 *    - minus '-' means must skip
 *    - plus '+' means must have
 *  - "4[_,+,-]" - context+UI oyCMMapi4_s
 *  - "6[_,+,-]" - context convertor oyCMMapi6_s
 *  - "7[_,+,-]" - processor oyCMMapi7_s \n
 *  
 *  By default all attributes in a search pattern are considered mandatory.
 *  A level can be omitted, "//", or a attribute can be tagged by a '_'
 *  underscore in front for making it optional, or a '-' to indicate a 
 *  attibute must not match.
 *
 *  \b Example: a complete registration search pattern: \n
 *  "//openicc/4+icc.7+ACCEL.7_GPU.7_HLSL.7-GLSL" selects a accelerated CMM 
 *  interpolator with prefered GPU and HLSL but no GLSL support together with a
 *  ICC compliant context generator and options.
 *
 *  The oyFilterRegistrationToText() and oyFilterRegistrationMatch() functions
 *  might be useful for canonical processing Oyranos registration text strings.
 *  Many functions allow for passing a registration string. Matching can be 
 *  obtained by omitting sections like in the string "//openicc/icc", where the
 *  elements between slashes is omitted. This string would result in a match 
 *  for any ICC compliant color conversion filter.
 *
 *  The registration attributes ".front", ".advanced" and more are described in
 *  the objects_value::oyOPTIONATTRIBUTE_e enum.
 *
 *  See as well <a href="http://www.oyranos.org/wiki/index.php?title=Concepts#Elektra_namespace">Concepts#Elektra_namespace</a> on ColourWiki.
 *  @{
 */

/** @addtogroup monitor_hooks_api Monitor Backend Modules
 *  @brief      Simple way to hook a display system into a Oyranos device config module
 *
 *  The motivation for this API is to interface with Oyranos device
 *  configuration module system. The abstraction layer allows to code
 *  independently from Oyranos API's with a fairly simple API set.
 *  Additionally the resulting code can be used elsewehere independently.
 *
 *  The set of hooks is used by the oyranos_cmm_disp.c module family with
 *  some additional headers. As a example take the oyX1 module with its
 *  oyranos_monitor_hooks_x11.h header and the implementation in
 *  oyranos_monitor_x11.c . The oyX1 CMakeLists.txt section gives
 *  more details on how to build the according module in the source tree.
 *  Please do not hesitate to contact the developers on github or the mailing
 *  list for further help.
 *
 *  @{
 */
/** @} *//* monitor_hooks_api */
/** @} *//* module_api */

