|
Oyranos Colour Management System API |
|
Data Structures | |
| struct | oyCMMapi_s |
| the basic API interface More... | |
| struct | oyCMMapi3_s |
| the API 3 to implement and set to provide low level ICC profile support More... | |
| struct | oyCMMapiFilter_s |
| the module API 4,6,7 interface base More... | |
| struct | oyCMMobjectType_s |
| custom object handler More... | |
| struct | oyCMMapi5_s |
| module or script loader More... | |
| struct | oyCMMapi7_s |
| data processing node More... | |
| struct | oyCMMapi6_s |
| context convertor More... | |
| struct | oyCMMui_s |
| the CMM API UI part More... | |
| struct | oyCMMapi4_s |
| context creator More... | |
| struct | oyCMMapi8_s |
| configuration handler More... | |
| struct | oyCMMapi9_s |
| graph policies More... | |
| struct | oyCMMapi10_s |
| generic data exchange More... | |
Typedefs | |
| typedef int(* | oyCMMapi5_s::oyCMMFilterSocket_MatchPlug_f )(oyFilterSocket_s *socket, oyFilterPlug_s *plug) |
| verify connectors matching each other | |
| typedef int(* | oyCMMapi_s::oyCMMCanHandle_f )(oyCMMQUERY_e type, uint32_t value) |
| CMM feature declaration function. | |
| typedef int(* | oyCMMapi_s::oyCMMInit_f )(oyStruct_s *filter) |
| optional CMM init function | |
| typedef int(* | oyCMMapi_s::oyCMMMessageFuncSet_f )(oyMessage_f message_func) |
| optionaly sets a CMM message function | |
| typedef oyOptions_s *(* | oyCMMapi5_s::oyCMMFilter_ValidateOptions_f )(oyFilterCore_s *filter, oyOptions_s *validate, int statical, uint32_t *result) |
| a function to check and validate options | |
| typedef int(* | oyCMMapi_s::oyCMMOptions_Check_f )(oyOptions_s *validate) |
| a function to check options | |
| typedef int(* | oyCMMuiGet_f )(oyOptions_s *options, char **ui_text, oyAlloc_f allocateFunc) |
| obtain a XFORMS ui descriptionThe structures can provide a XFORMS ui based on the modules own set of options. The options are in the property of the caller. | |
| 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 | |
| typedef const char *(* | oyCMMobjectType_s::oyCMMobjectGetText_f )(oyStruct_s *object, oyNAME_e type, int flags) |
| build a text string from a given object | |
| 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 | |
| typedef oyCMMapiFilter_s *(* | oyCMMapi5_s::oyCMMFilterLoad_f )(oyPointer data, size_t size, const char *file_name, oyOBJECT_e type, int num) |
| load a filter from a in memory data blob | |
| typedef int(* | oyCMMapi5_s::oyCMMFilterScan_f )(oyPointer data, size_t size, const char *file_name, oyOBJECT_e type, int num, char **registration, char **name, oyAlloc_f allocateFunc, oyCMMInfo_s **info, oyObject_s object) |
| load a filter from a in memory data blob | |
| typedef int(* | oyCMMapi7_s::oyCMMFilterPlug_Run_f )(oyFilterPlug_s *plug, oyPixelAccess_s *pixel_access) |
| get a pixel or channel from the previous filter | |
| typedef int(* | oyCMMapi6_s::oyModuleData_Convert_f )(oyPointer_s *data_in, oyPointer_s *data_out, oyFilterNode_s *node) |
| convert between data formats | |
| 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 | |
| typedef char *(* | oyCMMapi4_s::oyCMMFilterNode_GetText_f )(oyFilterNode_s *node, oyNAME_e type, oyAlloc_f allocateFunc) |
| describe a CMM filter context | |
| typedef int(* | oyCMMapi8_s::oyConfigs_FromPattern_f )(const char *registration, oyOptions_s *options, oyConfigs_s **configs) |
| return available configurations | |
| typedef int(* | oyCMMapi8_s::oyConfigs_Modify_f )(oyConfigs_s *configs, oyOptions_s *options) |
| enrich/manipulate existing configurations | |
| typedef int(* | oyCMMapi8_s::oyConfig_Rank_f )(oyConfig_s *config) |
| check for correctness | |
| typedef int(* | oyCMMapi9_s::oyConversion_Correct_f )(oyConversion_s *conversion, uint32_t flags, oyOptions_s *options) |
| check for correctly adhering to policies | |
| typedef int(* | oyCMMapi10_s::oyMOptions_Handle_f )(oyOptions_s *options, const char *command, oyOptions_s **result) |
| generic data exchange | |
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... | |
| enum | oyWIDGET_EVENT_e |
Functions | |
| OYAPI oyCMMapis_s *OYEXPORT | oyCMMapis_s::oyCMMapis_New (oyObject_s object) |
| allocate a new CMMapis list | |
| OYAPI oyCMMapis_s *OYEXPORT | oyCMMapis_s::oyCMMapis_Copy (oyCMMapis_s *obj, oyObject_s object) |
| copy or reference a CMMapis list | |
| OYAPI int OYEXPORT | oyCMMapis_s::oyCMMapis_Release (oyCMMapis_s **obj) |
| release and possibly deallocate a CMMapis list | |
| OYAPI int OYEXPORT | oyCMMapis_s::oyCMMapis_MoveIn (oyCMMapis_s *list, oyCMMapi_s **obj, int pos) |
| add a element to a CMMapis list | |
| OYAPI int OYEXPORT | oyCMMapis_s::oyCMMapis_ReleaseAt (oyCMMapis_s *list, int pos) |
| release a element from a CMMapis list | |
| OYAPI oyCMMapi_s *OYEXPORT | oyCMMapis_s::oyCMMapis_Get (oyCMMapis_s *list, int pos) |
| get a element of a CMMapis list | |
| OYAPI int OYEXPORT | oyCMMapis_s::oyCMMapis_Count (oyCMMapis_s *list) |
| count the elements in a CMMapis list | |
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 colour 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 API's. 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.
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 API deployes these modules.
oyCMMapi9_s can be used to plug in new object types, policy settings and a way to enforce the policies.
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.
Example: a complete module registration:
"shared/oyranos.org/imaging/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.
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:
"//imaging/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 "//imaging/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 int(* oyCMMCanHandle_f)(oyCMMQUERY_e type, uint32_t value) |
CMM feature declaration function.
typedef oyCMMCanHandle_f
| typedef oyOptions_s*(* oyCMMFilter_ValidateOptions_f)(oyFilterCore_s *filter, oyOptions_s *validate, int statical, uint32_t *result) |
a function to check and validate options
typedef oyCMMFilter_ValidateOptions_f
| [in] | filter | the filter |
| [in] | validate | to validate |
| [in] | statical | convert to a statical version |
| [out] | ret | 0 if nothing changed otherwise >=1 |
| typedef oyCMMapiFilter_s*(* oyCMMFilterLoad_f)(oyPointer data, size_t size, const char *file_name, oyOBJECT_e type, int num) |
load a filter from a in memory data blob
typedef oyCMMFilterLoad_f
| [in] | data | data blob |
| [in] | size | data size |
| 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.
| [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 |
| 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:
| 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
) {}; | [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 |
A requested context will be stored in oyFilterNode_s::backend_data.
| typedef int(* oyCMMFilterScan_f)(oyPointer data, size_t size, const char *file_name, oyOBJECT_e type, int num, char **registration, char **name, oyAlloc_f allocateFunc, oyCMMInfo_s **info, oyObject_s object) |
load a filter from a in memory data blob
typedef oyCMMFilterScan_f
| [in] | data | filter data blob |
| [in] | size | data size |
| [in] | file_name | the filter file for information or zero |
| [in] | type | filter type |
| [in] | num | number of filter |
| [out] | registration | filter registration string |
| [out] | name | filter name |
| [in] | allocateFunc | e.g. malloc |
| [out] | info | oyCMMInfo_s pointer to set |
| [in] | object | e.g. Oyranos object |
| typedef int(* oyCMMFilterSocket_MatchPlug_f)(oyFilterSocket_s *socket, oyFilterPlug_s *plug) |
verify connectors matching each other
typedef oyCMMFilterSocket_MatchPlugIn_f
A implementation for images is included in the core function oyFilterSocket_MatchImagePlug().
| socket | a filter socket |
| plug | a filter plug |
| 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:
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.
| [in] | object | the object, omit to get a general text |
| [out] | type | the string type |
| [in] | flags | for future use |
| 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
| [in] | buf_size | data size |
| [in] | buf | data blob |
| [in] | flags | for future use |
| [in] | object | the optional base |
| 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
| [in] | data | data blob |
| [in] | size | data size |
| [out] | registration | filter registration string |
| [out] | name | filter name |
| [in] | allocateFunc | e.g. malloc |
| typedef int(* oyCMMOptions_Check_f)(oyOptions_s *validate) |
a function to check options
typedef oyCMMOptions_Check_f
| [in] | options | the options |
| typedef int(* oyCMMuiGet_f)(oyOptions_s *options, char **ui_text, oyAlloc_f allocateFunc) |
obtain a XFORMS ui descriptionThe structures can provide a XFORMS ui based on the modules own set of options. The options are in the property of the caller.
typedef oyCMMuiGet_f
| [in] | options | the options to display |
| [out] | ui_text | the XFORMS string |
| [in] | allocateFunc | user allocator |
| 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.
| config | the to be checked configuration |
| typedef int(* oyConfigs_FromPattern_f)(const char *registration, oyOptions_s *options, oyConfigs_s **configs) |
return available configurations
typedef oyConfigs_FromPattern_f
| [in] | registration | a selection string marked with "///config" |
| [in] | options | the complete options from the user |
| [out] | configs | the returned configurations |
| typedef int(* oyConfigs_Modify_f)(oyConfigs_s *configs, oyOptions_s *options) |
enrich/manipulate existing configurations
typedef oyConfigs_Modify_f
| [in,out] | configs | the configurations |
| [in] | options | the complete options from the user |
| 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.
| conversion | the to be checked configuration | |
| [in] | flags | for inbuild defaults | oyOPTIONSOURCE_FILTER; for options marked as advanced | oyOPTIONATTRIBUTE_ADVANCED | OY_SELECT_FILTER | OY_SELECT_COMMON |
| options | options to the policy module |
| 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.
| 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.
| [in] | options | the input data; It is typical not changed. |
| [in] | command | a 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] | result | the created data |
| enum oyCMMQUERY_e |
CMM capabilities query enum.
| enum oyWIDGET_EVENT_e |
| OYAPI oyCMMapis_s *OYEXPORT oyCMMapis_Copy | ( | oyCMMapis_s * | obj, |
| oyObject_s | object | ||
| ) |
copy or reference a CMMapis list
Function oyCMMapis_Copy
| [in] | obj | struct object |
| object | the optional object |
References oyCMMapis_s::oy_.
Referenced by oyCMMapis_s::oyCMMapis_New().
| OYAPI int OYEXPORT oyCMMapis_Count | ( | oyCMMapis_s * | list | ) |
count the elements in a CMMapis list
Function oyCMMapis_Count
| [in,out] | list | the list |
References oyCMMapis_s::list_.
| OYAPI oyCMMapi_s *OYEXPORT oyCMMapis_Get | ( | oyCMMapis_s * | list, |
| int | pos | ||
| ) |
get a element of a CMMapis list
Function oyCMMapis_Get
| [in,out] | list | the list |
| pos | position |
References oyCMMapis_s::list_.
| OYAPI int OYEXPORT oyCMMapis_MoveIn | ( | oyCMMapis_s * | list, |
| oyCMMapi_s ** | obj, | ||
| int | pos | ||
| ) |
add a element to a CMMapis list
Function oyCMMapis_MoveIn
| [in] | list | list |
| [in,out] | obj | list element |
| pos | position |
References oyCMMapis_s::list_, oyCMMapis_s::oyCMMapis_New(), oyCMMapi_s::type, and oyCMMapis_s::type_.
| OYAPI oyCMMapis_s *OYEXPORT oyCMMapis_New | ( | oyObject_s | object | ) |
allocate a new CMMapis list
Function oyCMMapis_New
References oyCMMapis_s::oyCMMapis_Copy(), oyCMMapis_s::oyCMMapis_Release(), and oyCMMapis_s::release.
Referenced by oyCMMapis_s::oyCMMapis_MoveIn().
| OYAPI int OYEXPORT oyCMMapis_Release | ( | oyCMMapis_s ** | obj | ) |
release and possibly deallocate a CMMapis list
Function oyCMMapis_Release
| [in,out] | obj | struct object |
References oyCMMapis_s::list_, and oyCMMapis_s::oy_.
Referenced by oyCMMapis_s::oyCMMapis_New().
| OYAPI int OYEXPORT oyCMMapis_ReleaseAt | ( | oyCMMapis_s * | list, |
| int | pos | ||
| ) |
release a element from a CMMapis list
Function oyCMMapis_ReleaseAt
| [in,out] | list | the list |
| pos | position |
References oyCMMapis_s::list_, and oyCMMapis_s::type_.
Generated on Mon Dec 5 2011 09:49:02 for Oyranos by
1.7.5.1
Copyright © 2004-2009 Kai-Uwe Behrmann and others.
All Rights Reserved.