Oyranos Color Management System API
Public Types | Public Member Functions | Data Fields
oyCMMapi4_s Struct Reference

Context creator. More...

#include <oyCMMapi4_s.h>

Inheritance diagram for oyCMMapi4_s:
Inheritance graph
Collaboration diagram for oyCMMapi4_s:
Collaboration graph

Public Types

typedef oyPointer(* oyCMMFilterNode_ContextToMem_f) (oyFilterNode_s *node, size_t *size, oyAlloc_f allocateFunc)
 store a CMM filter context into a memory blob More...
 
typedef char *(* oyCMMFilterNode_GetText_f) (oyFilterNode_s *node, oyNAME_e type, oyAlloc_f allocateFunc)
 describe a CMM filter context More...
 
- Public Types inherited from oyCMMapi_s
typedef int(* oyCMMInit_f) (oyStruct_s *filter)
 optional CMM init function More...
 
typedef int(* oyCMMMessageFuncSet_f) (oyMessage_f message_func)
 optionaly sets a CMM message function More...
 
typedef int(* oyCMMCanHandle_f) (oyCMMQUERY_e type, uint32_t value)
 CMM feature declaration function. More...
 
typedef const char *(* oyCMMGetText_f) (const char *select, oyNAME_e type, oyStruct_s *context)
 get strings from a CMM More...
 

Public Member Functions

OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_New (oyObject_s object)
 allocate a new CMMapi4 object More...
 
OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_Copy (oyCMMapi4_s *cmmapi4, oyObject_s object)
 copy or reference a CMMapi4 object More...
 
OYAPI int OYEXPORT oyCMMapi4_Release (oyCMMapi4_s **cmmapi4)
 release and possibly deallocate a oyCMMapi4_s object More...
 
OYAPI int OYEXPORT oyCMMapi4_SetBackendContext (oyCMMapi4_s *api, oyPointer_s *ptr)
 set filter type specific runtime data More...
 
OYAPI oyPointer_s *OYEXPORT oyCMMapi4_GetBackendContext (oyCMMapi4_s *api)
 get filter type specific runtime data More...
 
OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_Create (oyCMMInit_f init, oyCMMMessageFuncSet_f msg_set, const char *registration, int32_t version[3], int32_t module_api[3], const char *context_type, oyCMMFilterNode_ContextToMem_f contextToMem, oyCMMFilterNode_GetText_f getText, oyCMMui_s *ui, oyObject_s object)
 Custom CMMapi4 constructor. More...
 
- Public Member Functions inherited from oyCMMapiFilter_s
OYAPI oyCMMapiFilter_s *OYEXPORT oyCMMapiFilter_New (oyObject_s object)
 allocate a new CMMapiFilter object More...
 
OYAPI oyCMMapiFilter_s *OYEXPORT oyCMMapiFilter_Copy (oyCMMapiFilter_s *cmmapifilter, oyObject_s object)
 copy or reference a CMMapiFilter object More...
 
OYAPI int OYEXPORT oyCMMapiFilter_Release (oyCMMapiFilter_s **cmmapifilter)
 release and possibly deallocate a oyCMMapiFilter_s object More...
 
OYAPI int OYEXPORT oyCMMapiFilter_SetBackendContext (oyCMMapiFilter_s *api, oyPointer_s *ptr)
 set filter type specific runtime data More...
 
OYAPI oyPointer_s *OYEXPORT oyCMMapiFilter_GetBackendContext (oyCMMapiFilter_s *api)
 get filter type specific runtime data More...
 
- Public Member Functions inherited from oyCMMapi_s
OYAPI oyCMMapi_s *OYEXPORT oyCMMapi_New (oyObject_s object)
 allocate a new CMMapi object More...
 
OYAPI oyCMMapi_s *OYEXPORT oyCMMapi_Copy (oyCMMapi_s *cmmapi, oyObject_s object)
 copy or reference a CMMapi object More...
 
OYAPI int OYEXPORT oyCMMapi_Release (oyCMMapi_s **cmmapi)
 release and possibly deallocate a oyCMMapi_s object More...
 
void oyCMMapi_Set (oyCMMapi_s *api, oyCMMInit_f init, oyCMMMessageFuncSet_f msg_set, const char *registration, int32_t version[3], int32_t module_api[3])
 CMMapi member setter. More...
 
void oyCMMapi_SetNext (oyCMMapi_s *api, oyCMMapi_s *next)
 chain CMMapi's More...
 
oyCMMapi_soyCMMapi_GetNext (oyCMMapi_s *api)
 get next CMMapi More...
 
- Public Member Functions inherited from oyStruct_s
const char * oyStruct_GetTextFromModule (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 get object infos from a module More...
 
const char * oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
 get a text dump More...
 

Data Fields

const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 
- Data Fields inherited from oyCMMapiFilter_s
const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 
- Data Fields inherited from oyCMMapi_s
const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 
- Data Fields inherited from oyStruct_s
const oyOBJECT_e type_
 Type of object. More...
 
oyStruct_Copy_f copy
 Copy function. More...
 
oyStruct_Release_f release
 Release function. More...
 
oyObject_s oy_
 Oyranos internal object. More...
 

Detailed Description

Context creator.

The structure contains functions to specify and prepare parameters or a context dedicated for a filter node class. UI elements can be included for manual settings. As per definition the result of this filter is serialised, and can therefore be cached by Oyranos' core.

Different filters have to provide this struct each one per filter.

The ::oyCMMFilterNode_ContextToMem

See also
oyCMMFilterNode_ContextToMem_f should be implemented in case the context_type is set to a context data type.
Todo:
in commit 5a2b7396 the connection descriptors where moved to oyCMMapi7_s. For a context, which must be created from the processing data this is not relyable, as the interpolator can not be shure that the context plug-in supports the same or larger set of connectors.
Version
Oyranos: 0.9.5
Since
2008/06/24 (Oyranos: 0.1.8)
Date
2013/06/09

Member Typedef Documentation

◆ 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]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

◆ 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

Member Function Documentation

◆ oyCMMapi4_Copy()

OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_Copy ( oyCMMapi4_s cmmapi4,
oyObject_s  object 
)

copy or reference a CMMapi4 object

Function oyCMMapi4_Copy

The function is for copying and for referencing. The reference is the most often used way, which saves resourcs and time.

Parameters
[in]cmmapi4CMMapi4 struct object
objectNULL - means reference, the optional object triggers a real copy

References oyOBJECT_CMM_API4_S.

Referenced by oyCMMapi4_Create().

◆ oyCMMapi4_Create()

OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_Create ( oyCMMInit_f  init,
oyCMMMessageFuncSet_f  msg_set,
const char *  registration,
int32_t  version[3],
int32_t  module_api[3],
const char *  context_type,
oyCMMFilterNode_ContextToMem_f  contextToMem,
oyCMMFilterNode_GetText_f  getText,
oyCMMui_s ui,
oyObject_s  object 
)

Custom CMMapi4 constructor.

Function oyCMMapi4_Create

Parameters
initcustom initialisation
msg_setmessage function setter
registrationthe modules registration string,
versionmodule version
  • 0: major - should be stable for the live time of a filter
  • 1: minor - mark new features
  • 2: patch version - correct errors
module_apitell compatibility with Oyranos API
  • 0: last major Oyranos version during development time, e.g. 0
  • 1: last minor Oyranos version during development time, e.g. 9
  • 2: last Oyranos patch version during development time, e.g. 5
context_typetell the context type, if any the data type of the context returned by oyCMMapi4_s::oyCMMFilterNode_ContextToMem_f, mandatory in case of a set oyCMMapi4_s::oyCMMFilterNode_ContextToMem e.g. oyCOLOR_ICC_DEVICE_LINK / "oyDL"
contextToMemonly mandatory for context producing filters, e.g. "//color/icc"
getTextoptionally set a oyCMMFilterNode_ContextToMem, used to override a Oyranos side hash creation
uia UI description provide a oyCMMapi4_s::ui->getText( select, type ) call. The "select" argument shall cover at least "name" and "help"
objecta optional object
Version
Oyranos: 0.9.5
Since
2013/06/09 (Oyranos: 0.9.5)
Date
2013/06/09

References oyCMMapi4_Copy(), oyCMMapi4_New(), oyCMMapi_s::oyCMMapi_Set(), and oyCMMui_s::oyCMMui_Copy().

◆ oyCMMapi4_GetBackendContext()

OYAPI oyPointer_s *OYEXPORT oyCMMapi4_GetBackendContext ( oyCMMapi4_s api)

get filter type specific runtime data

Runtime data can be used as context by a backend during execution.

That data is apart from a filter object, which can have lifetime data associated through a oyFilterNode_GetContext(). A filter connector can have its processing data associated through oyFilterNode_SetData().

Parameters
[in]apiapi object
Returns
the context needed to run the filter type
Version
Oyranos: 0.9.5
Date
2013/12/19
Since
2013/12/19 (Oyranos: 0.9.5)

References oyOBJECT_CMM_API4_S, oyOBJECT_CMM_API_MAX, and oyPointer_s::oyPointer_Copy().

Referenced by oyFilterCore_s::oyFilterCore_GetBackendContext().

◆ oyCMMapi4_New()

OYAPI oyCMMapi4_s *OYEXPORT oyCMMapi4_New ( oyObject_s  object)

allocate a new CMMapi4 object

Function oyCMMapi4_New

References oyOBJECT_OBJECT_S.

Referenced by oyCMMapi4_Create().

◆ oyCMMapi4_Release()

OYAPI int OYEXPORT oyCMMapi4_Release ( oyCMMapi4_s **  cmmapi4)

release and possibly deallocate a oyCMMapi4_s object

Function oyCMMapi4_Release

Parameters
[in,out]cmmapi4CMMapi4 struct object

References oyOBJECT_CMM_API4_S.

◆ oyCMMapi4_SetBackendContext()

OYAPI int OYEXPORT oyCMMapi4_SetBackendContext ( oyCMMapi4_s api,
oyPointer_s ptr 
)

set filter type specific runtime data

Runtime data can be used as context by a backend during execution. The data is typical set during backend load.

That data is apart from a filter object, which can have lifetime data associated through a oyFilterNode_GetContext(). A filter connector can have its processing data associated through oyFilterNode_SetData().

Parameters
[in,out]apiapi object
[in]ptrthe data needed to run the filter type
Returns
error
Version
Oyranos: 0.9.5
Date
2013/12/19
Since
2013/12/19 (Oyranos: 0.9.5)

References oyOBJECT_CMM_API4_S, oyOBJECT_CMM_API_MAX, oyPointer_s::oyPointer_Copy(), and oyPointer_s::oyPointer_Release().

Referenced by oyFilterCore_s::oyFilterCore_SetBackendContext().

Field Documentation

◆ copy

oyStruct_Copy_f oyCMMapi4_s::copy

Copy function.

◆ oy_

oyObject_s oyCMMapi4_s::oy_

Oyranos internal object.

Features name and hash. Do not change during object life time.

◆ release

oyStruct_Release_f oyCMMapi4_s::release

Release function.

◆ type_

const oyOBJECT_e oyCMMapi4_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.