The SDL3 Examples Megathread about sdl HOT 25 OPEN

Our examples for the GPU API:

https://github.com/TheSpydog/SDL_gpu_examples

from sdl.

I'm currently working on plugging this into CMake, so people can optionally build these like they do the tests. They are intended to work on anything SDL builds for, not just the web.

from sdl.

PEOPLE WITH HTML/CSS DESIGN EXPERIENCE ARE DEFINITELY NEEDED. Come say hi!

Hi!

from sdl.

We are wired into CMake and CI. Apologies to @madebr who is probably cringing at what I've done.

from sdl.

Hi!

Save us, @Semphriss! We definitely need the specific pages (like this one to not look like crud, but also literally anything would look nicer in the parent directories.

I can automate the generation of whatever page, I just need something that looks good to generate. :)

from sdl.

(What prompted this was https://www.raylib.com/examples.html but I'm not trying to exactly duplicate that.)

from sdl.

We'll definitely pull those in with GPU work.

from sdl.

@icculus I'm working on it, where would be the best place for me to ask questions and show my progress?

from sdl.

Right here is perfect!

from sdl.

Alright!

Some ideas I've had while working on the design:

• Having the window/canvas resize to fit the browser window size, if the example uses SDL_WINDOW_RESIZABLE? I've done something like that for the SuperTux project: https://supertux.semphris.com/play
• Having the console visible? For SuperTux, I made it show only on Debug builds, not sure if I have a Debug build running somewhere but I can make a quick example if the console might be interesting to have.

I'm not exactly sure what level of fancy is suitable for SDL, so I'm making a few different templates and I'll ask for feedback when ready so we can discuss the good and bad in each version.

from sdl.

So I hid the console because it's ugly by default and it was just sort of wedged in there, but it would be useful to have it, so we can have text dynamically show up while examples are running. If you can make it not suck, we can definitely turn it back on.

from sdl.

So I hid the console because it's ugly by default and it was just sort of wedged in there, but it would be useful to have it, so we can have text dynamically show up while examples are running. If you can make it not suck, we can definitely turn it back on.

That would be nice also so we can switch back to SDL_Log() for errors instead of popping a messagebox.

Would it be possible to have something auto-show if there's log output, but hidden otherwise?

from sdl.

Would it be possible to have something auto-show if there's log output, but hidden otherwise?

Yes, there's a Javascript function that gets called when there's console output, which we provide in our template.html; we can easily have it display only when there's output, but we still need the console to not suck first. :)

from sdl.

Here's an example of what I did with the console for SuperTux: https://supertux.semphris.com/play-debug/

I'd like to post screenshots to avoid the humongous download of the game, but my browser stubbornly refuses to load the game. If anybody can grab screenshots/a video of the console and could post it here, it would be appreciated.

It appears not to be working, nevermind.

from sdl.

I've made three templates to see which direction I should take next. Since I wasn't testing with an actual SDL example program, I made the canvas light blue. In all three versions, the canvas can be made to fill the size it can occupy (half the screen in the first template and the whole screen in the latter two).

A basic grid-cut interface (I can rearrange the grid as preferred, for example if the code needs more space and the canvas less):
Screencast from 2024-07-23 05:07:31 PM.webm

A more dynamic drawer-based template, probably best suited for interactive examples:
Screencast from 2024-07-23 05:07:45 PM.webm

A different drawer-based version; the code takes the place of the console, and the console is removed:
Screencast from 2024-07-23 05:08:06 PM.webm

Which ideas in there are good and which ones are bad? I'll make further templates based on feedback.

from sdl.

I think it's good to see the console output. Maybe a combination, where the code and console are tabs in the bottom area?

from sdl.

I'm currently working on plugging this into CMake, so people can optionally build these like they do the tests

Would it be OK for the build system to grow an option similar to SDL_INSTALL_TESTS to install the examples and their required resource files - perhaps into ${libexecdir}/installed-tests/SDL3 alongside the automated and manual tests, or into ${libexecdir}/SDL3-examples or something - so that distro packagers can easily use them as a smoke-test to confirm that an updated SDL still basically works?

I think it would be wrong to install the examples into the ${bindir} on Unixish systems, because they aren't namespaced (they have names like audio-load-wav rather than sdl3-example-audio-load-wav) and some of them want to load resource files from the directory containing the executable; but somewhere below ${libexecdir} seems appropriate.

(In the .deb packaging I'll probably include them in libsdl3-tests rather than introducing a separate package for examples, because every time we add a new .deb we have to go through a time-consuming review process. The sample programs in SDL_image and SDL_mixer are already packaged similarly to this.)

from sdl.

Planning on moving the SDL_GPU examples to the new folder soon - we do have one small issue, which is that we depend on stb_image to load HDR images for our tonemapping examples. Adding HDR support to SDL_image would just cause a circular dependency, so are there any preferences on how this is addressed?

We also use SDL_gpu_spirvcross.h at the moment but we could change that to be more like testgpu eventually.

from sdl.

Planning on moving the SDL_GPU examples to the new folder soon - we do have one small issue, which is that we depend on stb_image to load HDR images for our tonemapping examples. Adding HDR support to SDL_image would just cause a circular dependency, so are there any preferences on how this is addressed?

SDL_image already has HDR support for loading AVIF files, and can be extended to other formats if needed. Does that help?

from sdl.

It does a little bit; how do we address the build order though? It would have to be SDL -> Image -> Examples, which could be an issue for CI in particular.

from sdl.

Yeah, we probably don't want circular dependencies for anything in the main SDL build. There's an SDL test program that has an optional dependency on SDL_ttf, but can be built (or skipped) if that's not available. If you are already using stb_image.h, that seems fine to include in the examples in the SDL repo.

from sdl.

Would it be OK for the build system to grow an option similar to SDL_INSTALL_TESTS to install the examples and their required resource files

Would this be useful? Like a package maintainer gets a bug report and says "okay, can you run $X/audio-simple-playback and see if it makes any sound at all?" If so, sure, why not? But if not, I'd think it would just be junk taking up space, honestly.

(But also, yes, "sdl3-" file prefix or not, let's definitely not ever install these into a bindir that's in the $PATH!)

from sdl.

I think it's good to see the console output. Maybe a combination, where the code and console are tabs in the bottom area?

I think the third example looked best, if there is a nice way for the console and source to share that space.

Also, I was surprised to learn SDL_Log doesn't write to the Emscripten console (just the JavaScript console you can get at with F12). Stdout goes to the Emscripten console, SDL_Log should probably write to that in addition to the JavaScript console.

from sdl.

Would this be useful? Like a package maintainer gets a bug report and says "okay, can you run $X/audio-simple-playback and see if it makes any sound at all?" If so, sure, why not? But if not, I'd think it would just be junk taking up space, honestly.

Additionally, we can install the example source code to e.g. /usr/share/doc/SDL3/examples
I'm not sure people will find it.

from sdl.

Would this be useful? Like a package maintainer gets a bug report and says "okay, can you run $X/audio-simple-playback and see if it makes any sound at all?" If so, sure, why not? But if not, I'd think it would just be junk taking up space, honestly.

I'd only consider enabling installation of the examples (or the tests!) in distributions like Debian that normally split a source package (like SDL) into several installable binary packages (shared library, -dev, -doc, -tests, ...), in which case they don't take up any space on end user systems unless the user explicitly does an apt install libsdl3-tests or equivalent.

In distributions like Arch and Gentoo that usually don't split a source package like that, I wouldn't want to enable installation of examples or tests, because in those distributions they would be junk taking up space on end-user systems.

I'm less thinking about using the examples for diagnosis on end-user systems, and more thinking about using them as a smoke-test for the maintainer and contributors (for example porters on non-x86 architectures wanting to know whether SDL is successfully runnable on their architecture). With SDL 2, there are lots of games that I can use as a smoke-test ("can I still play OpenArena? if yes, ship it") but because SDL 3 doesn't have a stable API/ABI yet, I've found the manual tests to be a useful way to confirm that new snapshots are basically working as intended: for example, that they can still open an X11 or Wayland window and draw into it, they can still output sounds, they can still detect my gamepad and so on.

If the tests are intended to already cover basically all of the functionality that the examples do, then having the tests be installable is sufficient, and there's no real need for the examples to be installable as well.

from sdl.