Readme: Switch to Markdown, add a diagram

[Vanuan]

Let's switch from *.txt to markdown and add some nice diagrams.

[Vanuan]

Here's a larger version if needed:

I can provide access to sources on request

[ggabbiani]

Hi John,
good to move to md, as for your picture: while Quarter was (and still should be) meant for final client application, GUI components are still the base for all the ivexamples and SoGuiExamples, being critical for testing the correct Open Inventor implementation under Coin.

I attach a picture made some time ago for clarification

So my proposal is to change the label for GUI components from 'Deprecated' to 'Legacy'.

Regards
Giampiero

[Vanuan]

Oh, so SoGtk/SoQt/SoWin/SoXt are part of Open Inventor API? But the core Coin library doesn't include them. Probably should add a note about that.

[Vanuan]

How about this?

[ggabbiani]

That's fine for me.

Coin / Open Inventor 'history':

• SGI published Open Inventor with only one GUI component: SoXt;
• SIM implemented the Open Inventor 3D Toolkit with Coin;
• SIM extended the [GUI] component library with So{Gtk,Qt,Win} taking SoXt as reference 'model';
• SIM added one integration library for MacOs called Sc21;
• Later again SIM focused OS platform coverage through Quarter leveraging Qt, that in the meanwile extended the supported platform to the same OSs.

Do not take this as 'gold' ... is just my uderstanding of the long - and glorious - Open Inventor history :)

Cheers
Giampiero

[Vanuan]

@ggabbiani done

[veelo]

Hi Vanuan,

This looks nice. Just a few comments:

1. C++ is under language bindings, whereas it is not really a binding. Most of Coin3D is simply C++.
2. I interpret the orange "Coin3D" bar to mean that everything to the left of that constitutes Coin3D, which is not entirely correct IMO. Firstly, Qt is not part of Coin3D (but SoGUI is, yet is at the same "level" as Qt). Secondly, the SGI implementation is at the same level as Coin, but has nothing to do with Coin3D (Coin is a clean-room implementation modelled after the SGI documentation).
3. I am not sure how much of the OpenGL parts and implementations is actually utilized by Coin (ES, EGL, GLX, CGL and WGL). Did you check?

So I'm not exactly sure whether this diagram increases or decreases the correct understanding of the coverage of the Coin3D suite of libraries. Giampiero's overview does not have this problem. Maybe it is worth extending this instead? Where is it currently included?

Best regards,
Bastiaan.

[veelo]

Also for diagrams in general, I'd like to see them use editable formats, so that they can easily be adjusted in the future. Would SVG work well?

[Vanuan]

1. Fair. Strictly speaking pivy is the only official binding so far (if you don't count other thirdparty bindings). C++ can be considered a binding only because libraries usually only have a C interface. That is you can't use plain C as an interface to coin (unless you know how name mangling works).
2. Yeap, Qt is more like at the level of Gtk/WINAPI/Motif which aren't shown here. SGI implementation is only shown to demonstrate that Coin3D is meant to be binary compatible with SGI according to README. Which might not be the case anymore.
3. ES is a subset of full OpenGL, so it is fair to say that it is used. GLX, CGL and WGL are used by corresponding GUI bindings. EGL should be used to support Wayland. I'm not sure whether Quarter - Qt glue provides EGL (Wayland) support. Also, SuperGLU which is a fork of SGI GLU is not shown here, it is used as an abstraction on top of OpenGL. I didn't want to overload already quite a heavy diagram. Let's follow up here: https://groups.google.com/g/coin3d-discuss/c/osGzMf4RW80

Regarding Giampiero's picture, I think it has a lot more details than a newbie might want to know. Newcomers are only expected to be familiar with OpenGL, GUI and language bindings. So only terms that are introduced in the diagram is Open Inventor API and its implementation. Giampiero's picture focuses more on the coverage of Open Inventor API by Coin version and the extended API it provides. That can be included as well but only as an elaboration of the Coin implementation and its dependencies.

I'd like to see them use editable formats, so that they can easily be adjusted in the future. Would SVG work well?

SVG is great for scalability and consumption, but not so much for editing. I can export in SVG, but it would not be editable, as I didn't use SVG editor to create it. I used Figma. Do you want me to add you to the Figma project where I created this diagram? https://www.figma.com/file/MF5ULt44QAihMOh3cv4YoM/Content?node-id=17%3A0

I've incorporated your suggestions:

[luzpaz]

bump

[veelo]

Another point: a newby may conclude from this diagram that applications must interface with Coin through Python, which is not the case. The text under * says these modules are part of the OI API, yet they are not positioned under the OI bar, and it is unclear in what way they are "treated separately" (I don't think they are).

Diagrams like these can perfectly well be coded in SVG by hand, it is a programming language after all. On the other hand, the structure of Coin is not likely to change, so once we agree on a diagram then the format is not a big deal.

I still think the diagram is not good, but I don't want to block this if other maintainers think it is a net benefit.

If you split the port to Markdown into its own PR, I'll happily merge that.

[Vanuan]

@veelo could you incorporate suggested modifications? You can either create figma account and make a copy or "well code it in SVG"

I already removed C++ from language binding and now you request to bring it back. It's confusing.

[veelo]

Sorry for the confusion, and for being a nag. As you requested: #444.

[veelo]

Thanks for your efforts, your changes to readme.md were merged as part of #444.

[luzpaz]

Thank you @Vanuan. It's a great improvement!