![]() |
Oyranos
0.9.7
Oyranos is a full featured Color Management System
|
Write extensions that integrate with Oyranos front end APIs. More...
Modules | |
Data Processing Modules | |
Modules to configure, convert contexts and process data in a DAG. | |
Policy Modules | |
Modules to handle settings and register additional object types. | |
Device Modules | |
Modules to handle devices. | |
ICC Profil Tag i/o Modules | |
Adds extensible support of profile tag parsing and writing. | |
Miscellaneous Modules | |
Perform various task over a oyOptions_s transport mechanism. | |
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... | |
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.
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 colors with the help of ICC style profiles, which can by convention be inserted into the options list.
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.
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 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.
[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.
[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(* 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().
socket | a filter socket |
plug | a filter plug |
typedef const char*(* oyCMMGetText_f) (const char *select, oyNAME_e type, oyStruct_s *context) |
get strings from a CMM
typedef oyCMMGetText_f
type:
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. |
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 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.
[in] | module | the owner |
[in] | options | the options to display |
[out] | ui_text | the XFORMS string |
[in] | allocateFunc | user allocator |
enum oyCMMQUERY_e |
CMM capabilities query enum.
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.