Updated list of demos and detailed info

[Erik Faye-Lund]

On Sun, 2025-07-20 at 17:11 +0100, Daniel Monteiro wrote:
> 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).

Yeah, so there's a bit of complexity here. Demos that depends on data-
files will generally look them up relative to $DEMOS_DATA_DIR, which is
a compile-time define.

This define will usually be set to one of two values... "../data/", or 
"{PREFIX}/{DATADIR}/mesa-demos".

The latter is the installed directory of the data-files, and will
depend on us running "meson install" before we can see the files.

The former is a relative directory, so it depends on the current
directory when running. If you run using "meson devenv", you can pass
something like "meson devenv -C <build-dir> -w <source-dir>/src/demos
<build-dir>/src/demos/teapot"

...yeah, that's quite a mouthful, but it at least works. And it's
completely undocumented, which makes it hard to guess.

A much better way would IMO be:

1. Add and use a wrapper function to get the the file-path relative to
the datadir

2. Add an environment variable that can override the build-time
DEMOS_DATA_DIR setting to that wrapper

3. Add that environment variable to the meson devenv, so we don't have
to specify anything

...that way we could just do "meson devenv -C <build-dir>
src/demos/teapot" etc to run the demos.

I've been kinda meaning to get around to this, but never did.

> 
> > 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.
> 

I wasn't really trying to editorialize what is and what isn't good
practice, just pointing out that very dated demos might do things that
isn't considered good practice any more.

There's certainly a trade-off to be made here between being practical
and understandable, and being for instance efficient. I would mostly
lean more towards the former than the latter here - these aren't really
benchmarks anyway.

So yeah, no clear input here, other than the vague warning that some of
these programs are literally 25+ years old programs that has *just*
gotten enough maintenance to still compile and *maybe* run on modern
systems.

> > 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.
> 

I would start with two splits at first, but adding additional splits
with time might make sense if we're adding new demos here. Apart from
vkgears (the vulkan port of gears), I don't think many demos has been
added in a good while, and I wouldn't expect that to change much TBH.

> > 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?
> 

I think we can do it from the mesa/demos repo, we'd just set up a docs
folder there and add the appropriate CI magic etc to get GitLab pages
to light up.

As I said before, I can help out with this if needed, so it's just a
matter of creating rst-files and writing text.

> > 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!

I don't think piglit would be the right tool for this, no. Piglit is
made to run its own set of tests, not to run and screenshot other
programs.

Don't worry too much about this point. While it would be nice, it's
certainly no requirement to sort out right away.

> 
> 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?
> 

Yeah, the licensing is a bit of a mess. Most demos either have a
license-header or an SPDX-identifier that identifies the license
clearly, but there are some that have some vague statement, and
probably a few where we'd need to ask the author for clarification.

That's not something that's going to be fixed in a swoop, though.