[Openicc] Gsoc2010 - oyranos API stabilization project

[Kai-Uwe Behrmann]

Am 01.04.10, 19:08 +0300 schrieb Yiannis Belias:
> Hi,
>
> OK, so here is a list of the Modules and the proposed actions to be taken:
> o Miscellaneous->Generic Objects
> o Miscellaneous->Values Handling
> o Module APIs
> o Device API
> o Profile API
> o Named Colour API
>
> (a) Simplify the interconnections of objects.

Objects in Oyranos are currently used with intime knowledge. This 
is often tricky and not easy to understand. Objects should, IMO, typical 
expose only the oyStruct_s structure members [1].
E.g. the complicated oyConfig_s structure[2] would be exposed with the 
oyStruct_s members only, but still typed as oyConfig_s. The oyConfig_s_ 
internal structure will be visible only in its own file, say 
oyranos_config_s.c . Access to the private members is possible 
through the to be exposed functions with a oyConfig_s * object 
argument[3].
Possibly a oyConfig_s flawor of type oyDevice_s would be a useful add[4].
The generic struct members of oyStruct_s still allow to handle the data 
in lists or other data structures. E.g. the caching code does not need 
to know about internals of cached objects. oyStruct_s members are enough.
[5]


In case where a interface is appropriate, say in the module vtables, it 
would suffice to expose only the common parts of a interface and hide more
specialised members.
Say the oyCMMui_s[6] can, beside oyStruct_s, expose a version member and 
say some simple string API, which is useful in a module selection UI. The 
real options and XFORMS style stuff is private and APIs to oyCMMui_s can 
be added later. This allowes now for static UIs convincing for instance 
the SANE module. More complex structures based on oyCMMui_s with callbacks 
for interaction and validation can be designed later. Or in other words 
SANEs oyCMMui_s object would still be compatible with newer extented 
oyCMMui_s objects. The real structures would then eigther be called 
oyCMMui1_s, oyCMMui2_s or the oyCMMui_s objects version[7] does change.

What this code reorganisation would aim is
* a object oriented C API with compile time safety (API and ABI wise)
* enough transparency for common debuggers as it is provided now and new
* flexibility for further development
* ... (not shure what else might be important to keep in mind)

> (b) Change the implementation code of objects to use an internal and public
>   API by using the code generator. Copy the rest of the already existing code to new object.
> (c) Create test cases.
> (d) Write documentation.
>
> (a) seems a little fuzzy right now, it probably needs some conceptual work first
> to reorganize the object dependencies.

Heartedly agreed. Clearing some of the fuzzyness from the Oyranos code 
base is a big part of that GSoC project ;-)
I would love to see the dependencies to minimise during reorganisation.


To the list readers, last years work of students during GSoC on the 
device modules was a great experience. They helped during that project a 
lot by pointing out weaknesses and ambiguities in the APIs and 
documentation.


> So, I hope I'm getting this right. Any additions/modifications to this plan?
>
> Cheers,
> Yiannis


kind regards
Kai-Uwe Behrmann
-- 
developing for colour management 
www.behrmann.name + www.oyranos.org

[1] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_alpha.h;h=7e436439e3956fc587de1786c08e9da152f4f2f4;hb=master#l207
[2] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_alpha.h;h=7e436439e3956fc587de1786c08e9da152f4f2f4;hb=master#l1067
[3] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_alpha.h;h=7e436439e3956fc587de1786c08e9da152f4f2f4;hb=master#l1106
[4] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_alpha.h;h=7e436439e3956fc587de1786c08e9da152f4f2f4;hb=master#l1531
[5] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_alpha.h;h=7e436439e3956fc587de1786c08e9da152f4f2f4;hb=master#l535
[6] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_cmm.h;h=b1730e30aafe83068637b01e717592c78a3e0fc4;hb=master#l876
[7] http://www.oyranos.org/scm?p=oyranos.git;a=blob;f=oyranos_cmm.h;h=b1730e30aafe83068637b01e717592c78a3e0fc4;hb=master#l894