Oyranos Colour Management System API
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Typedefs | Enumerations | Functions
Module APIs
Collaboration diagram for Module APIs:

Data Structures

struct  oyCMMapi10_s
 Generic data exchange. More...
 
struct  oyCMMapi3_s
 The API 3 to implement and set to provide low level ICC profile support. More...
 
struct  oyCMMapi4_s
 Context creator. More...
 
struct  oyCMMapi5_s
 Module or script loader. More...
 
struct  oyCMMapi6_s
 Context convertor. More...
 
struct  oyCMMapi7_s
 Data processing node. More...
 
struct  oyCMMapi8_s
 Configuration handler. More...
 
struct  oyCMMapi9_s
 Graph policies. More...
 
struct  oyCMMapi_s
 the basic API interface More...
 
struct  oyCMMapiFilter_s
 the module API 4,6,7 interface base More...
 
struct  oyCMMapiFilters_s
 A CMMapiFilters list. More...
 
struct  oyCMMobjectType_s
 Custom object handler. More...
 
struct  oyCMMui_s
 The CMM API UI part. More...
 

Typedefs

typedef int(* oyCMMapi10_s::oyMOptions_Handle_f )(oyOptions_s *options, const char *command, oyOptions_s **result)
 generic data exchange More...
 
typedef oyPointer(* oyCMMapi4_s::oyCMMFilterNode_ContextToMem_f )(oyFilterNode_s *node, size_t *size, oyAlloc_f allocateFunc)
 store a CMM filter context into a memory blob More...
 
typedef char *(* oyCMMapi4_s::oyCMMFilterNode_GetText_f )(oyFilterNode_s *node, oyNAME_e type, oyAlloc_f allocateFunc)
 describe a CMM filter context More...
 
typedef int(* oyCMMapi6_s::oyModuleData_Convert_f )(oyPointer_s *data_in, oyPointer_s *data_out, oyFilterNode_s *node)
 convert between data formats More...
 
typedef int(* oyCMMapi7_s::oyCMMFilterPlug_Run_f )(oyFilterPlug_s *plug, oyPixelAccess_s *pixel_access)
 get a pixel or channel from the previous filter More...
 
typedef int(* oyCMMapi8_s::oyConfigs_FromPattern_f )(const char *registration, oyOptions_s *options, oyConfigs_s **configs)
 return available configurations More...
 
typedef int(* oyCMMapi8_s::oyConfigs_Modify_f )(oyConfigs_s *configs, oyOptions_s *options)
 enrich/manipulate existing configurations More...
 
typedef int(* oyCMMapi8_s::oyConfig_Rank_f )(oyConfig_s *config)
 check for correctness More...
 
typedef int(* oyCMMapi9_s::oyConversion_Correct_f )(oyConversion_s *conversion, uint32_t flags, oyOptions_s *options)
 Check for correctly adhering to policies. More...
 
typedef int(* oyCMMapi_s::oyCMMInit_f )(oyStruct_s *filter)
 optional CMM init function More...
 
typedef int(* oyCMMapi_s::oyCMMMessageFuncSet_f )(oyMessage_f message_func)
 optionaly sets a CMM message function More...
 
typedef int(* oyCMMapi_s::oyCMMCanHandle_f )(oyCMMQUERY_e type, uint32_t value)
 CMM feature declaration function. More...
 
typedef int(* oyCMMapi_s::oyCMMOptions_Check_f )(oyOptions_s *validate)
 a function to check options More...
 
typedef const char *(* oyCMMobjectType_s::oyCMMobjectGetText_f )(oyStruct_s *object, oyNAME_e type, int flags)
 build a text string from a given object More...
 
typedef oyStruct_s *(* oyCMMobjectType_s::oyCMMobjectLoadFromMem_f )(size_t buf_size, const oyPointer buf, uint32_t flags, oyObject_s object)
 load a filter object from a in memory data blob More...
 
typedef int(* oyCMMobjectType_s::oyCMMobjectScan_f )(oyPointer data, size_t size, char **registration, char **name, oyAlloc_f allocateFunc)
 load a filter object from a in memory data blob More...
 
typedef int(* oyCMMui_s::oyCMMuiGet_f )(oyOptions_s *options, char **ui_text, oyAlloc_f allocateFunc)
 obtain a XFORMS ui description More...
 
typedef int(* oyCMMapi5_s::oyCMMFilterSocket_MatchPlug_f )(oyFilterSocket_s *socket, oyFilterPlug_s *plug)
 verify connectors matching each other More...
 

Enumerations

enum  oyCMMQUERY_e { oyQUERY_OYRANOS_COMPATIBILITY, oyQUERY_PROFILE_FORMAT = 20, oyQUERY_PROFILE_TAG_TYPE_READ, oyQUERY_PROFILE_TAG_TYPE_WRITE }
 CMM capabilities query enum. More...
 

Functions

int oyPointer_s::oyPointer_Set (oyPointer_s *cmm_ptr, const char *lib_name, const char *resource, oyPointer ptr, const char *func_name, oyPointer_release_f ptrRelease)
 set a oyPointer_s More...
 

Detailed Description

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_inline_dotgraph_1.png
\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 colour 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.

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 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_inline_dotgraph_2.png
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.

Registration

Each filter API provides a 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:

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 colours with the help of ICC style profiles, which can by convention be inserted into the options list.

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
    Example: a complete module registration:
    "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.

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
    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.

Example: a complete registration search pattern:
"//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 o,itted. This string would result in a match for any ICC compliant colour conversion filter.

The registration attributes ".front", ".advanced" and more are described in the objects_value::oyOPTIONATTRIBUTE_e enum.

See as well Concepts::Elektra_namespace on ColourWiki.

Typedef Documentation

typedef int(* oyCMMCanHandle_f)(oyCMMQUERY_e type, uint32_t value)

CMM feature declaration function.

typedef oyCMMCanHandle_f

typedef oyPointer(* oyCMMFilterNode_ContextToMem_f)(oyFilterNode_s *node, size_t *size, oyAlloc_f allocateFunc)

store a CMM filter context into a memory blob

typedef oyCMMFilterNode_ContextToMem_f

The goal is to have a data blob for later reusing. It is as well used for exchange and analysis. A oyCMMapi4_s filter with context_type member set to something should implement this function and fill the data blob with the according context data for easy forwarding and on disk caching.

Parameters
[in,out]nodeaccess to the complete filter struct, most important to handle is the options and image members
[out]sizesize in return
allocateFuncmemory allocator for the returned data
Returns
the CMM memory blob, preferedly ICC
Version
Oyranos: 0.1.8
Since
2008/07/02 (Oyranos: 0.1.8)
Date
2008/07/02
typedef char*(* oyCMMFilterNode_GetText_f)(oyFilterNode_s *node, oyNAME_e type, oyAlloc_f allocateFunc)

describe a CMM filter context

typedef oyCMMFilterNode_GetText_f

For a oyNAME_NICK and oyNAME_NAME type argument, the function shall describe only those elements, which are relevant to the result of the context creation. The resulting string is CMM specific by intention.

Serialise into:

  • oyNAME_NICK: XML ID
  • oyNAME_NAME: XML
  • oyNAME_DESCRIPTION: ??
Version
Oyranos: 0.1.10
Since
2008/12/27 (Oyranos: 0.1.10)
Date
2008/12/27
typedef int(* oyCMMFilterPlug_Run_f)(oyFilterPlug_s *plug, oyPixelAccess_s *pixel_access)

get a pixel or channel from the previous filter

typedef oyCMMFilterPlug_Run_f

You have to call oyCMMFilter_CreateContext_t or oyCMMFilter_ContextFromMem_t first. The API provides flexible pixel access and cache configuration by the passed oyPixelAccess_s object. The filters internal precalculated data are passed by the filter object.

while (
error = oyCMMFilterSocket_GetNext( filter_plug, pixel_access ) == 0
) {}; 
Parameters
[in]plugincluding the CMM's private data, connector is the requesting plug to obtain a handle for calling back
[in]pixel_accessprocessing order instructions
Returns
-1 end; 0 on success; error > 1

A requested context will be stored in oyFilterNode_s::backend_data.

Version
Oyranos: 0.1.8
Since
2008/07/03 (Oyranos: 0.1.8)
Date
2008/07/28
typedef int(* oyCMMFilterSocket_MatchPlug_f)(oyFilterSocket_s *socket, oyFilterPlug_s *plug)

verify connectors matching each other

typedef oyCMMFilterSocket_MatchPlug_f

A implementation for images is included in the core function oyFilterSocket_MatchImagePlug().

Parameters
socketa filter socket
pluga filter plug
Returns
1 on success, otherwise 0
Version
Oyranos: 0.1.10
Since
2009/04/20 (Oyranos: 0.1.10)
Date
2009/04/20
typedef int(* oyCMMInit_f)(oyStruct_s *filter)

optional CMM init function

typedef oyCMMInit_f

typedef int(* oyCMMMessageFuncSet_f)(oyMessage_f message_func)

optionaly sets a CMM message function

typedef oyCMMMessageFuncSet_f

typedef const char*(* oyCMMobjectGetText_f)(oyStruct_s *object, oyNAME_e type, int flags)

build a text string from a given object

typedef oyCMMobjectGetText_f

Serialise a object into:

  • oyNAME_NICK: XML ID
  • oyNAME_NAME: XML
  • oyNAME_DESCRIPTION: ??

For type information the object argument is omitted. Then the function shall programatically tell in oyNAME_NICK about the object type, e.g. "oyProfile_s", in oyNAME_NAME translated about its intented usage, e.g. i18n("ICC profile") and give with oyNAME_DESCRIPTION some further long informations.

Note: Dynamically generated informations can be stored in the oyStruct_s::oy::name_ member and then returned by the function. Oyranos will typical look first at that oyObject_s member and then ask this function to get the information.

See Also
oyObject_SetName()
Parameters
[in]objectthe object, omit to get a general text
[out]typethe string type
[in]flagsfor future use
Returns
0 on success; error >= 1; unknown < 0
Version
Oyranos: 0.1.10
Since
2008/12/24 (Oyranos: 0.1.10)
Date
2009/09/14
typedef oyStruct_s*(* oyCMMobjectLoadFromMem_f)(size_t buf_size, const oyPointer buf, uint32_t flags, oyObject_s object)

load a filter object from a in memory data blob

typedef oyCMMobjectLoadFromMem_f

Parameters
[in]buf_sizedata size
[in]bufdata blob
[in]flagsfor future use
[in]objectthe optional base
Returns
the object
Version
Oyranos: 0.1.10
Since
2008/11/22 (Oyranos: 0.1.9)
Date
2009/09/14
typedef int(* oyCMMobjectScan_f)(oyPointer data, size_t size, char **registration, char **name, oyAlloc_f allocateFunc)

load a filter object from a in memory data blob

typedef oyCMMobjectScan_f

Parameters
[in]datadata blob
[in]sizedata size
[out]registrationfilter registration string
[out]namefilter name
[in]allocateFunce.g. malloc
Returns
0 on success; error >= 1; unknown < 0
Version
Oyranos: 0.1.10
Since
2008/11/22 (Oyranos: 0.1.9)
Date
2009/09/14
typedef int(* oyCMMOptions_Check_f)(oyOptions_s *validate)

a function to check options

typedef oyCMMOptions_Check_f

Parameters
[in]optionsthe options
Returns
0 - good, 1 - bad
Version
Oyranos: 0.1.10
Since
2009/07/15 (Oyranos: 0.1.10)
Date
2009/07/15
typedef int(* oyCMMuiGet_f)(oyOptions_s *options, char **ui_text, oyAlloc_f allocateFunc)

obtain a XFORMS ui description

typedef oyCMMuiGet_f

The structures can provide a XFORMS ui based on the modules own set of options. The options are in the property of the caller.

Parameters
[in]optionsthe options to display
[out]ui_textthe XFORMS string
[in]allocateFuncuser allocator
Returns
0 on success; error >= 1; -1 not understood; unknown < -1
Version
Oyranos: 0.1.10
Since
2009/01/18 (Oyranos: 0.1.10)
Date
2009/01/18
typedef int(* oyConfig_Rank_f)(oyConfig_s *config)

check for correctness

typedef oyConfig_Rank_f

The function is called in Oyranos' core to give a module a hook to check and accept a device. If the module does not find its previously set handles and can neigther open the device from the device_name then chances are good that it can't handle and should return zero otherwise one. Oyranos will then try an other module with this device.

Parameters
configthe to be checked configuration
Returns
- 0 - indifferent,
  • >= 1 - rank,
  • <= -1 error + a message should be sent
Version
Oyranos: 0.1.10
Since
2009/01/16 (Oyranos: 0.1.10)
Date
2009/01/26
typedef int(* oyConfigs_FromPattern_f)(const char *registration, oyOptions_s *options, oyConfigs_s **configs)

return available configurations

typedef oyConfigs_FromPattern_f

Parameters
[in]registrationa selection string marked with "///config"
[in]optionsthe complete options from the user
[out]configsthe returned configurations
Returns
0 - good, 1 <= error, -1 >= unknown issue, look for messages
Version
Oyranos: 0.1.10
Since
2009/01/18 (Oyranos: 0.1.10)
Date
2009/01/18
typedef int(* oyConfigs_Modify_f)(oyConfigs_s *configs, oyOptions_s *options)

enrich/manipulate existing configurations

typedef oyConfigs_Modify_f

Parameters
[in,out]configsthe configurations
[in]optionsthe complete options from the user
Returns
0 - good, 1 <= error, -1 >= unknown issue, look for messages
Version
Oyranos: 0.1.10
Since
2009/08/21 (Oyranos: 0.1.10)
Date
2009/08/21
typedef int(* oyConversion_Correct_f)(oyConversion_s *conversion, uint32_t flags, oyOptions_s *options)

Check for correctly adhering to policies.

typedef oyConversion_Correct_f

Without any options the module shall perform graph analysis and correct the graph.

See Also
oyConversion_Correct()
Typical Options:
  • "command"-"help" - a string option issuing a help text as message
  • "verbose" - reporting changes as message
Parameters
conversionthe to be checked configuration
[in]flagsfor inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON
optionsoptions to the policy module
Returns
0 - indifferent, >= 1 - error
  • a message should be sent
Version
Oyranos: 0.1.13
Since
2009/07/23 (Oyranos: 0.1.10)
Date
2010/11/27
typedef int(* oyModuleData_Convert_f)(oyPointer_s *data_in, oyPointer_s *data_out, oyFilterNode_s *node)

convert between data formats

typedef oyModuleData_Convert_f

The function might be used to provide a module specific context.

Version
Oyranos: 0.1.10
Since
2008/12/27 (Oyranos: 0.1.10)
Date
2008/12/27
typedef int(* oyMOptions_Handle_f)(oyOptions_s *options, const char *command, oyOptions_s **result)

generic data exchange

typedef oyMOptions_Handle_f

The provided data passed with oyOptions_s shall be processed according to the rules of a given command. The result is again a generic oyOptions_s object.

This module type works similiar to the device modules, which are defined in oyCMMapi8_s. While the module interface is simple it has minimal meaning to the intented work or data exchange. The rules are to be defined by the communicating parties, the host and the module. They use the plug-in mechanism only for their convinience.

For speed up the "can_handle.xxx" command must be implemented. "xxx" means in the previous command string the intented command to be performed. The "can_handle" command shall not produce any output in result, but shall indicate with zero that it could handle the request. This command is intented to lightwight select a capable module.

Parameters
[in]optionsthe input data; It is typical not changed.
[in]commanda string describing the intention of the caller; Allowed are alphanumerical signs. lower bar '_', minus '-', plus '+' and point '.' . other signs including white space must not occure. Strings are separated by point '.' . The first string is the actual command. The following strings are merely modifiers.
[out]resultthe created data
Returns
0 - indifferent, >= 1 - error, <= -1 - issue,
  • a message should be sent
Version
Oyranos: 0.1.10
Since
2009/12/11 (Oyranos: 0.1.10)
Date
2009/12/11

Enumeration Type Documentation

CMM capabilities query enum.

Since
: 0.1.8
Enumerator
oyQUERY_OYRANOS_COMPATIBILITY 

provides the Oyranos version and expects the CMM compiled or compatibility Oyranos version back

oyQUERY_PROFILE_FORMAT 

value 1 == ICC

oyQUERY_PROFILE_TAG_TYPE_READ 

value a icTagTypeSignature (ICC)

oyQUERY_PROFILE_TAG_TYPE_WRITE 

value a icTagTypeSignature (ICC)

Function Documentation

int oyPointer_Set ( oyPointer_s cmm_ptr,
const char *  lib_name,
const char *  resource,
oyPointer  ptr,
const char *  func_name,
oyPointer_release_f  ptrRelease 
)

set a oyPointer_s

Function oyPointer_Set

Use for initialising.

Version
Oyranos: 0.1.10
Since
2009/07/22 (Oyranos: 0.1.10)
Date
2009/08/16

Referenced by oyFilterNode_s::oyFilterNode_SetContext_().