Backend Modules
Description: C source code API documentation for the Oyranos project.
Keywords: Oyranos,Color Management,Color Management,ICC,CMS,C,doxygen,API,documentation

| Oyranos Color Management System API - Version 0.9.6

Modules | Data Structures | Typedefs | Enumerations | Functions
Backend Modules

Write extensions that integrate with Oyranos front end APIs. More...

Collaboration diagram for Backend Modules:

## Modules
| Monitor Backend Modules
| Simple way to hook a display system into a Oyranos device config module.

## Data Structures
struct | oyIcon_s
| Icon data. More...
struct | oyCMMapi4_s
| Context creator. More...
struct | oyCMMapi7_s
| Data processing node. 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 | oyCMMapis_s
| A CMMapis list. More...
struct | oyCMMui_s
| The CMM API UI part. More...
struct | oyCMM_s
| The CMM API resources struct to implement and set by a CMM. More...

## Typedefs
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(* | oyCMMapi7_s::oyCMMFilterPlug_Run_f) (oyFilterPlug_s *plug, oyPixelAccess_s *pixel_access)
| get a pixel or channel from the previous filter 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(* | oyCMMui_s::oyCMMuiGet_f) (oyCMMapiFilter_s *module, oyOptions_s *options, char **ui_text, oyAlloc_f allocateFunc)
| obtain a XFORMS ui description More...
typedef int(* | oyCMMFilterSocket_MatchPlug_f) (oyFilterSocket_s *socket, oyFilterPlug_s *plug)
| verify connectors matching each other More...
typedef const char *(* | oyCMMapi_s::oyCMMGetText_f) (const char *select, oyNAME_e type, oyStruct_s *context)
| get strings from a CMM 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

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.

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

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

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

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

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

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 Device 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:

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

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 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 Concepts::Elektra_namespace on ColourWiki.

## Typedef Documentation

## ◆ oyCMMCanHandle_f

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

CMM feature declaration function.

typedef oyCMMCanHandle_f

## ◆ oyCMMFilterNode_ContextToMem_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] | node | access to the complete filter struct, most important to handle is the options and image members
  [out] | size | size in return
  | allocateFunc | memory 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

## ◆ oyCMMFilterNode_GetText_f

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

## ◆ oyCMMFilterPlug_Run_f

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] | plug | including the CMM's private data, connector is the requesting plug to obtain a handle for calling back
  [in] | pixel_access | processing 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

## ◆ oyCMMFilterSocket_MatchPlug_f

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

  socket | a filter socket
  plug | a 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

## ◆ oyCMMGetText_f

typedef const char*(* oyCMMGetText_f) (const char *select, oyNAME_e type, oyStruct_s *context)

get strings from a CMM

typedef oyCMMGetText_f

type:

- oyNAME_NICK: compact, e.g. "GPU"
- oyNAME_NAME: a short explanation, e.g. "Rendering with GPU"
- oyNAME_DESCRIPTION: a long explanation, e.g. "Accelerated calculations on a GPU"

Parameters

  select | one from "name", "manufacturer" or "copyright"
  type | select flavour
  context | the object to ask for a optional context This will typical be the object to which this function belongs, but can be stated otherwise.

Returns
  text string or zero

Version
  Oyranos: 0.3.0

Since
  2008/12/23 (Oyranos: 0.1.10)

Date
  2011/02/01

## ◆ oyCMMInit_f

typedef int(* oyCMMInit_f) (oyStruct_s *filter)

optional CMM init function

typedef oyCMMInit_f

## ◆ oyCMMMessageFuncSet_f

typedef int(* oyCMMMessageFuncSet_f) (oyMessage_f message_func)

optionaly sets a CMM message function

typedef oyCMMMessageFuncSet_f

## ◆ oyCMMuiGet_f

typedef int(* oyCMMuiGet_f) (oyCMMapiFilter_s *module, 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] | module | the owner
  [in] | options | the options to display
  [out] | ui_text | the XFORMS string
  [in] | allocateFunc | user allocator

Returns
  0 on success; error >= 1; -1 not understood; unknown < -1

Version
  Oyranos: 0.9.5

Date
  2014/01/08

Since
  2009/01/18 (Oyranos: 0.1.10)

Examples:
  oyranos_cmm_oJPG.c.

## Enumeration Type Documentation

## ◆ oyCMMQUERY_e

enum oyCMMQUERY_e

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

## ◆ oyPointer_Set()

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

Examples:
  oyranos_cmm_oJPG.c.