Updated list of demos and detailed info

[Daniel Monteiro]

Thank you for the thorough answer.

> I think simply creating tickets for when demos doesn't run would be a good start.

That's a great idea for a first action. I will compile a list and
create the issue.

I've also noticed that some of the demos expect a file for input. I
wonder if those were supposed to be copied into the build directory
when using the provided instructions. I'm taking note of those and
will devise a patch to fix it (if applicable).

> And some demos needs a non-trivial setup to use. I think the "osdemos" fall under that category, and might warrant better documentation.

It's been a while since I last built osmesa. I tried again over the
week and got lots of outdated recommendations over the web, but
thankfully I still got the command line I got to work (for Android).
Perhaps this could be a second step towards improving things.

> The vast majority of the OpenGL demos in our demos repository are not great examples of good OpenGL programming, simply due to being very dated. Some of them probably promote what's considered bad practice these days.

Let's not forget that some folks are quite happy to glBegin and glEnd;
Some simply need to visualize some mesh processing algorithms and
stuff. But I certainly get why this would not be the best approach for
efficient hardware usage.

In fact, while I use "modern GL" for my silly games, I don't want to
waste much time with shaders and buffers on my offline tools.

As for deciding what's recommended or not, I will certainly need some
input from you guys, after a first pass. Hopefully this will save you
some time when analyzing this.

> 1. Useful utilities / "smoke-tests". These are tools that should be packaged and by default installed, and include tools like (glx|egl|wgl|es2_)info and all the gears variants.

It would be interesting to select demos that highlight different
aspects of the system, so it could be useful for folks to quickly
troubleshoot/fine tune their setups based on the different things
being demoed.

> 2. Programming examples / tech demos. These are more questionable if should be installed by default, and we might want to put them under an installation tag[1] that doesn't get installed by default.

Splitting those two even opens the doors for a more elaborate set of
demos to be constructed, with different cataloguing criteria. Perhaps
even with famous demos from the demoscene?

I also add a third category, based on my original message: good demos
for folks that want to learn while also taking a peek under the hood.

> But all in all, I think it sounds like a good initiative. But yeah, probably very time consuming!

My intention is to use a breadth-first approach, so I can better sort
out what's worth looking more deeply for each demo, as well as fixing
major issues.

> We can host things on GitLab Pages - this is the same as we do for mesa3d.org and docs.mesa3d.org. We could set up e.g demos.mesa3d.org as a catalogue, and it would probably be beneficial to use Sphinx, the same documentation system as we use for docs.mesa3d.org for this. I'm the one who set that up, and can help with it if needed.

>From what I understand, I would need special permissions to fork the
docs repo and create MRs? Should I create an issue for that first?

> In addition, it would probably be a good idea if we could somewhat automatically generate and update the screenshots, otherwise they're doomed to go stale at some point. This would probably involve some scripting to set up a headless display server, run the demos for a bit and capture a screenshot of the window. There's a lot of details to be figured out here, I'm sure!

Not entirely familiar with it, but we could use Piglit for that? Tried
running it locally, but ran out of disk space!

One last thing to point out, that I've noticed while reading the code:
the licensing for some of the demos is a bit unclear to me (and
probably for other, more casual readers). I suppose there's a global
license that applies unless otherwise noted?

Once again, thank you for the detailed answer.
Best regards,

Daniel Monteiro