Updated list of demos and detailed info

[Erik Faye-Lund]

On Tue, 2025-07-08 at 21:19 +0100, Daniel Monteiro wrote:
> Hello everyone,
> 
> As part of my effort to become a better OpenGL and Vulkan developer,
> I've been reading through (and experimenting with) the Mesa Demos.
> 
> During this process, I noticed that some of the demos don't run under
> certain conditions. I'd like to catalogue these cases and, if
> possible, document the requirements and runtime conditions for each
> demo.
> 
> Would there be interest in such a catalogue?

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

Some of the demos might simply be targets for removal, because they
might be using no longer supported features. I've cleaned out a few
such examples lately, for instance demos using GL_ARB_imaging, which
was removed from Mesa back in 2010.

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

> I could also include
> screenshots where appropriate.
> 
> I'm aware this is a large task (I counted 531 binaries after
> building), and I'm doing it regardless. But if there's interest in
> hosting or linking to this documentation, I’d be happy to put in
> extra
> effort and be more thorough.
> 

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.

I've been meaning to go through and sort things a bit, and I'm happy to
hear that there's someone else who's interested in this.

My thought are that we really have two kinds of demos, which IMO should
be treated a bit differently:

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.

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.

This is pretty much the same as I explain here:
https://gitlab.freedesktop.org/mesa/demos/-/issues/46#note_2553971

With all of that in mind, I'm not sure if I would go ahead and
catalogue *everything* right away. Some stuff might be better to just
go away, or be left uncatalogued.

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

> PS: Regardless of hosting, do you have any suggestions on how I
> should
> approach this? I'd really appreciate any advice.

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.

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!

[1]: https://mesonbuild.com/Installing.html#installation-tags