![]() |
Oyranos Color Management System API - Version 0.9.6 |
Color device meta data and profile handling. More...
![]() |
Functions | |
OYAPI int OYEXPORT | oyDevicesGet (const char *device_type, const char *device_class, oyOptions_s *options, oyConfigs_s **devices) |
get all devices matching to a device class and type More... | |
OYAPI int OYEXPORT | oyDeviceGet (const char *device_type, const char *device_class, const char *device_name, oyOptions_s *options, oyConfig_s **device) |
ask a module for device informations or other direct calls More... | |
OYAPI int OYEXPORT | oyDeviceBackendCall (oyConfig_s *device, oyOptions_s *options) |
get device answere from options More... | |
OYAPI int OYEXPORT | oyDeviceSetup (oyConfig_s *device, oyOptions_s *options) |
activate the device using the stored configuration More... | |
int | oyDeviceUnset (oyConfig_s *device) |
unset the device profile More... | |
OYAPI int OYEXPORT | oyDeviceGetInfo (oyConfig_s *device, oyNAME_e type, oyOptions_s *options, char **info_text, oyAlloc_f allocateFunc) |
get all devices matching to a device class and type More... | |
OYAPI int OYEXPORT | oyDeviceGetProfile (oyConfig_s *device, oyOptions_s *options, oyProfile_s **profile) |
order a device profile More... | |
OYAPI int OYEXPORT | oyDeviceAskProfile2 (oyConfig_s *device, oyOptions_s *options, oyProfile_s **profile) |
ask for the device profile More... | |
int | oyDeviceSetProfile (oyConfig_s *device, oySCOPE_e scope, const char *profile_name) |
set the device profile More... | |
OYAPI int OYEXPORT | oyDeviceProfileFromDB (oyConfig_s *device, char **profile_name, oyAlloc_f allocateFunc) |
look up a profile of a device from DB More... | |
OYAPI int OYEXPORT | oyDeviceSelectSimiliar (oyConfig_s *pattern, oyConfigs_s *heap, uint32_t flags, oyConfigs_s **matched_devices) |
get similiar devices by a pattern from a list More... | |
OYAPI int OYEXPORT | oyDeviceFromJSON (const char *json_text, oyOptions_s *options, oyConfig_s **device) |
generate a device from a JSON device calibration More... | |
OYAPI int OYEXPORT | oyDeviceToJSON (oyConfig_s *device, oyOptions_s *options, char **json_text, oyAlloc_f allocateFunc) |
get JSON format device calibration text from a device More... | |
OYAPI int OYEXPORT | oyDevicesFromTaxiDB (oyConfig_s *device, oyOptions_s *options, oyConfigs_s **devices, oyObject_s obj) |
search a calibration state in the taxi DB for a device More... | |
Color device meta data and profile handling.
Device Handling inside Oyranos is based on a key/value set, which describes a device and the associated profile. An additional matching set, allows Oyranos to compare different device configurations with a given devices key/value set. If accepted a new device will be added to the proper device key namespace and is permanently stored on disk in a config DB. In case of erasure the key set is removed from the config DB.
The soft matching approach is used in order to compare devices across different ports and computers. The highest match wins and it's profile is assigned. This approach allows to match oven remote profiles like ones from online DB's.
For direct work with the low level key/value matching use oyDeviceFromJSON(), oyRankMapFromJSON() and oyConfig_SetRankMap() API's.
Include the oyranos_devices.h header file to use the interfaces.
Devices are a special form of configurations. Their access is grouped for effective performance. Known devices are queried with oyDevicesGet(). oyConfigDomainList() provides a list of known device modules. A single device can be obtained by oyDeviceGet(). The device_type argument defaults to OY_TYPE_STD and can be omitted for this group. The device_class argument specifies a subgroup, e.g. "monitor".
All other functions return a handle to the device. With this handle it is possible to get informations (oyDeviceGetInfo()), query it's current, possibly remote profile (oyDeviceAskProfile2()) or typical used get a profile with fallbacks including the DB through (oyDeviceGetProfile()), set the profile persistent (oyDeviceSetProfile()) or query the persistent stored profile (oyDeviceProfileFromDB()).
OYAPI int OYEXPORT oyDeviceAskProfile2 | ( | oyConfig_s * | device, |
oyOptions_s * | options, | ||
oyProfile_s ** | profile | ||
) |
ask for the device profile
Function oyDeviceAskProfile2 Ask for a profile associated with the device. A device capable to hold a profile. Only the held profile will be checked and returned. In case this profile is not found a "icc_profile" of oyVAL_STRUCT should be included.
The device might not be able to hold a profile, then just the DB profile will be returned from here without an issue. For interessted users, the source of the profile keeps transparent, as it can be checked if the device contains a "icc_profile" option which contains a oyProfile_s object.
[in] | device | the device |
[in] | options | additional options |
[out] | profile | the device's ICC profile |
References oyOBJECT_CONFIG_S, and oyOptions_s::oyOptions_New().
Referenced by oyDeviceGetProfile().
OYAPI int OYEXPORT oyDeviceBackendCall | ( | oyConfig_s * | device, |
oyOptions_s * | options | ||
) |
get device answere from options
Function oyDeviceBackendCall
[in] | device | the device |
[in] | options | options for the device |
References oyOBJECT_CONFIG_S.
OYAPI int OYEXPORT oyDeviceFromJSON | ( | const char * | json_text, |
oyOptions_s * | options, | ||
oyConfig_s ** | device | ||
) |
generate a device from a JSON device calibration
Function oyDeviceFromJSON
[in] | json_text | the device calibration |
[in] | options | optional
|
[out] | config | the device |
OYAPI int OYEXPORT oyDeviceGet | ( | const char * | device_type, |
const char * | device_class, | ||
const char * | device_name, | ||
oyOptions_s * | options, | ||
oyConfig_s ** | device | ||
) |
ask a module for device informations or other direct calls
Function oyDeviceGet
[in] | device_type | the device type, e.g. OY_TYPE_STD, defaults to OY_TYPE_STD (optional) |
[in] | device_class | registration oyFILTER_REG_APPLICATION part, e.g. "monitor", mandatory |
[in] | device_name | the device name as returned by oyConfigs_FromPattern_f, mandatory, oyFILTER_REG_OPTION |
[in] | options | options to pass to the module, for zero the verbose and expensive "properties" call is assumed |
[out] | device | the returned device |
OYAPI int OYEXPORT oyDeviceGetInfo | ( | oyConfig_s * | device, |
oyNAME_e | type, | ||
oyOptions_s * | options, | ||
char ** | info_text, | ||
oyAlloc_f | allocateFunc | ||
) |
get all devices matching to a device class and type
Function oyDeviceGetInfo
To obtain a certain single pice of information you do not need oyDeviceGetInfo. See the following example:
[in] | device | the device |
[in] | type | influences the info_text output
|
[in] | options | defaults to command=properties |
[out] | info_text | the text |
[in] | allocateFunc | the user allocator for info_text |
1.2 ask each module
1.2.1 add device_name to the string list
References oyNAME_DESCRIPTION, oyNAME_NICK, oyOBJECT_CONFIG_S, oyOptions_s::oyOptions_Count(), and oyOptions_s::oyOptions_FindString().
OYAPI int OYEXPORT oyDeviceGetProfile | ( | oyConfig_s * | device, |
oyOptions_s * | options, | ||
oyProfile_s ** | profile | ||
) |
order a device profile
Function oyDeviceGetProfile This function is designed to satisfy most users as it tries to deliver a profile all the time. Following code can almost allways expect some profile to go with. It tries hard to get a current profile or set the system up and retry or get at least one basic profile.
For a basic and thus weaker call to the device use oyDeviceAskProfile2() instead.
device | the device |
options | - options passed to the backend
|
profile | the device's ICC profile |
This function does a device setup in case no profile is delivered by the according module.
As a last means oyASSUMED_WEB is delivered.
References oyDeviceAskProfile2(), and oyOBJECT_CONFIG_S.
OYAPI int OYEXPORT oyDeviceProfileFromDB | ( | oyConfig_s * | device, |
char ** | profile_name, | ||
oyAlloc_f | allocateFunc | ||
) |
look up a profile of a device from DB
Function oyDeviceProfileFromDB The function asks the module for a detailed and possible expensive list of device information and tries to find a matching configuration in the DB. The device informations are the same as for saving to DB.
[in] | device | a device |
[in] | profile_name | profile's name in DB |
[in] | allocateFunc | user allocator |
Referenced by oyDeviceUnset().
OYAPI int OYEXPORT oyDeviceSelectSimiliar | ( | oyConfig_s * | pattern, |
oyConfigs_s * | heap, | ||
uint32_t | flags, | ||
oyConfigs_s ** | matched_devices | ||
) |
get similiar devices by a pattern from a list
Function oyDeviceSelectSimiliar The function takes a device and tries to find exact matches, which can be considered as belonging to the same device. The comparision can be influenced by the flags. The option "profile_name" is ignored during the comparision.
[in] | pattern | Pass a device used as reference. String options of this object are compared to the objects in the heap argument depending on the flags argument. "profile_name" and other options from heap objects are ignored. |
[in] | heap | a list of device objects |
[in] | flags | - 0 yields exact match
|
[out] | matched_devices | the devices selected from heap |
int oyDeviceSetProfile | ( | oyConfig_s * | device, |
oySCOPE_e | scope, | ||
const char * | profile_name | ||
) |
set the device profile
Function oyDeviceSetProfile The function will lookup the device in the Oyranos device database and stores the given profile there.
To set a new profile und update the device please call the following sequence:
device | the device |
scope | oySCOPE_USER and oySCOPE_SYS are possible |
profile_name | the device's ICC profile or zero to unset |
References oyOBJECT_CONFIG_S, and oyOptions_s::oyOptions_Count().
OYAPI int OYEXPORT oyDeviceSetup | ( | oyConfig_s * | device, |
oyOptions_s * | options | ||
) |
activate the device using the stored configuration
Function oyDeviceSetup
[in] | device | the device |
[in] | options | additional options,
|
We ignore a device, which already has its profile setup.
Warn on not found profile.
OYAPI int OYEXPORT oyDevicesFromTaxiDB | ( | oyConfig_s * | device, |
oyOptions_s * | options, | ||
oyConfigs_s ** | devices, | ||
oyObject_s | obj | ||
) |
search a calibration state in the taxi DB for a device
Function oyDevicesFromTaxiDB oyDevicesFromTaxiDB() needs a device containing the calibration state and gives you a list of found devices in Taxi DB. You can extract the device ID inside the "TAXI_id" string from the returned devices "db" options sets. Typical you want one entry in the profiles list assigned with that device. oyProfile_FromTaxiDB() can be used to download that and oyProfile_Install() helps installing it, while doing some consistency checks.
[in] | device | the device |
[in] | options | not used |
[out] | devices | the obtained device calibrations |
References oyOBJECT_CONFIG_S.
OYAPI int OYEXPORT oyDevicesGet | ( | const char * | device_type, |
const char * | device_class, | ||
oyOptions_s * | options, | ||
oyConfigs_s ** | devices | ||
) |
get all devices matching to a device class and type
Function oyDevicesGet
For obtaining expensive "properties" informations at once, add the according option.
[in] | device_type | the device type oyFILTER_REG_TYPE, defaults to OY_TYPE_STD (optional) |
[in] | device_class | the device class, e.g. "monitor", oyFILTER_REG_APPLICATION |
[in] | options | options for the device |
[out] | devices | the found devices |
OYAPI int OYEXPORT oyDeviceToJSON | ( | oyConfig_s * | device, |
oyOptions_s * | options, | ||
char ** | json_text, | ||
oyAlloc_f | allocateFunc | ||
) |
get JSON format device calibration text from a device
Function oyDeviceToJSON
[in] | config | the device |
[in] | options | "source" value is used for oyConfig_GetOptions() |
[out] | json_text | the device calibration |
[in] | allocateFunc | user allocator |
int oyDeviceUnset | ( | oyConfig_s * | device | ) |
unset the device profile
Function oyDeviceUnset The function solely calls unset in the module, e.g. unset graphic card luts and server stored profile. So pretty all device/server side informatin should go away.
device | the device |
References oyConfig_s::oyConfig_FindString(), oyDeviceProfileFromDB(), and oyOBJECT_CONFIG_S.