The SDL3 Examples Megathread

[icculus]

The Idea

I've just added an "examples" directory to SDL3.

Things in here are intended to be official example code that we endorse.

As an added bonus, things in here automatically go to the web on each commit! Like this:

https://github.com/libsdl-org/SDL/blob/main/examples/renderer/01-clear/renderer-clear.c

...shows up here automatically, as a runnable web app, with the syntax-highlighted (and wiki-linked!) source code below it:

https://examples.libsdl.org/SDL3/renderer/01-clear/

Read the docs here:

https://github.com/libsdl-org/SDL/tree/main/examples

There is a lot to be done, so I'll be updating this checklist, but the short of it is currently:

• [x] Make the web output pretty
• [ ] Make the parent directories pretty, and/or add a toplevel navigation page.
• [ ] Add more examples
• [ ] Mark some examples and not-web-friendly (a Vulkan example will never work, etc).

Examples wishlist:

Audio:

• [ ] binding multiple streams
• [ ] recording audio
• [ ] adjust audio gain example
• [ ] adjust audio frequency example
• [ ] channel map example (reverse left/right stereo channels)
• [ ] Postmix calback example

Video:

• [ ] Fullscreen example
• [ ] Surface blitting example

Render:

• [x] Clear the screen
• [x] Generic primitives
• [x] Lines
• [x] Points
• [x] Rectangles
• [x] Static textures
• [x] Streaming textures
• [x] Rotating textures
• [x] Scaling textures
• [x] Geometry
• [x] Color mods
• [ ] Blending
• [x] Scaling
• [x] Viewport
• [x] Cliprect
• [ ] Render targets
• [ ] Logical presentation
• [ ] Read pixels
• [ ] Tiled textures
• [ ] 9grid textures

Camera:

• [x] Simple camera playback example.

Joystick:

• [ ] A simple light-up-the-buttons thing.

Gamepad:

• [ ] A simple light-up-the-buttons-on-a-gamepad-image thing.
• [ ] A simple rumble thing (will this work on the web?)

Keyboard:

• [ ] Show them the keycode/scancode/name as keys are pressed.

Message box:

• [ ] Just walk them through some message box examples.

Mouse:

• [ ] Cycle through some cursors as they click specific rectangles on the screen.
• [ ] Show relative mouse mode with some infinite scrolling thing.

Touch:

• [ ] Something that requires the user to multitouch points on the screen.

Events:

• [ ] ???

IOStream:

• [ ] ???

Thread:

• [ ] Show how to spin a thread
• [ ] Show how a mutex (etc) works.

Pen:

• [x] draw lines with pressure

OpenGL and Vulkan:

• [ ] a spinning cube (steal it right from testgl.c)
• [ ] a simple shader?

GPU API:

• [ ] Ethan and his team have this under control already, once we merge the API itself.

Games:

• [ ] Slightly more (BUT NOT MUCH MORE) complicated examples that make a real game, like Snake or whatnot. Ideas welcome!

Help wanted

If people have ideas for specific examples, big or small, please add a comment. General feedback is welcome, too.

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

[icculus]

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.

[Semphriss]

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

Hi!

[icculus]

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

[icculus]

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

[icculus]

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

[flibitijibibo]

Our examples for the GPU API:

https://github.com/TheSpydog/SDL_gpu_examples

[icculus]

We'll definitely pull those in with GPU work.

[Semphriss]

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

[icculus]

Right here is perfect!

[Semphriss]

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.

[icculus]

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.

[slouken]

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?

[icculus]

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

[Semphriss]

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.

[Semphriss]

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.

[slouken]

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

[smcv]

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

[flibitijibibo]

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.

[slouken]

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?

[flibitijibibo]

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.

[slouken]

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.

[icculus]

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

[icculus]

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.

[madebr]

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.

[smcv]

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.

[Semphriss]

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.

I've made another template: Screencast from 2024-07-28 04:26:15 PM.webm

I've kept the tabs separated, but I can combine them into one single tab if necessary. I can also rearrange the tabs, or make pretty much any other modification as wanted.

I can check to make sure the console output works once the template is chosen.

[slouken]

I like that! Can we put the source code on the left and the console on the right and make the tabs larger?

[Semphriss]

I wasn't sure if larger tabs implied larger fonts, so I did that as well. It's easy to undo if the font size was already correct.

[icculus]

I love this.

[icculus]

Anyhow, point me towards the html/css/js when you're ready and I'll integrate it, and we can work out of revision control after that.

[Semphriss]

Anyhow, point me towards the html/css/js when you're ready and I'll integrate it, and we can work out of revision control after that.

Is it fine if I open a PR?

I can also just drop the file here, it's not very big.

[icculus]

Either is fine; this is examples/template.html in the source code if you want to do a PR.

[Semphriss]

@icculus I've opened #10424 with the template :slightly_smiling_face:

[icculus]

Merged! Now the examples look like this: https://examples.libsdl.org/SDL3/renderer/01-clear/

Looks good!

[slouken]

Just a little feedback:

• I expected the tabs to toggle the panels, it took me a minute to realize I had to click off of them to close the tabs
• It would be nice for the console to show behind the source code tab so you can easily go back and forth.
• Overall this looks great, thank you!

[slouken]

Also, @icculus, do we want some kind of intro or description or something for each example?

[icculus]

We could just have the build script put the first comment in the source code at the top of the page...

[icculus]

I added a thing to show a description in 6a25e94472291e77d3b00d32899f21fdd1f1c9d7. Not sure if I like it, but it works:

https://examples.libsdl.org/SDL3/renderer/02-primitives/

[slouken]

I added a thing to show a description in 6a25e94. Not sure if I like it, but it works:

https://examples.libsdl.org/SDL3/renderer/02-primitives/

I'm not sure I like it either. I was thinking maybe a simple title, centered or in the upper left?

[icculus]

I moved it up there in 69a2d7960cef29d1cda4283c9744c6d349e5e0b3, but currently the canvas is covering it. I'll let someone else fix the CSS on this one.

[Semphriss]

@icculus I opened #10429 with the fixes :)

[icculus]

I've updated the original comment with wishlists of examples worth building. Some are super vague and not all of them are necessarily worth doing. There are still gaps (in some cases because they aren't web-friendly, but that shouldn't stop us from writing them). Please bring in ideas for little examples that I've missed!

I'm probably not writing all of these examples myself, if others want to jump in, and I have an SDL3 work backlog, so I can't really get focused on this right away in any case.

[Semphriss]

Would it be relevant to have some "Default SDL template with example of all standard functions" kind of example? I'm thinking of features like SDL_SetAppMetadata that would be useful to know and (possibly?) to be used more in apps, but that I didn't know about because I just never thought of looking for that and I didn't see it anywhere in other apps.

Just the most basic introduction to the different available features would be enough, so that people know what SDL provides that may be relevant for them but that isn't easy to discover by randomly browsing the documentation.

[slouken]

Do we want to reach out to 8Observer8 and include any of his examples?

[icculus]

I'm not aware of 8Observer8's examples, is there a link I can look at?

[icculus]

Would it be relevant to have some "Default SDL template with example of all standard functions" kind of example?

I think so. I've been avoiding putting this in to keep the code as small as possible, but we should definitely do an example that does app metadata.

[slouken]

I'm not aware of 8Observer8's examples, is there a link I can look at?

There are a bunch of SDL3 web demos here: https://8observer8.github.io/index.html

[smcv]

Would it be relevant to have some "Default SDL template with example of all standard functions" kind of example? I'm thinking of features like SDL_SetAppMetadata that would be useful to know and (possibly?) to be used more in apps, but that I didn't know about because I just never thought of looking for that and I didn't see it anywhere in other apps.

If we expect game developers to be adding this sort of thing when they port to SDL3, then I think an example that does it would be good. It might also be good to have a "New features that every game should consider using" section in README.migration.

Perhaps the recently-added Snake game could be a good place to put this sort of thing, as the only one (so far) that is a complete playable game that is integrated with all the subsystems that make sense for it, rather than just an example of a single feature?

In particular, increasingly many features on Linux (or more specifically the X11, Wayland, D-Bus, freedesktop.org ecosystem) want every app to have a unique reversed-domain-name app ID and will not work otherwise - so I think that should be a recommendation when porting games that can run on Linux to SDL3. In example code, I think it should be more like com.example.Snake rather than org.libsdl.Snake, to avoid game developers mistakenly getting the idea that they ought to be calling their game something like org.libsdl.Doom (we saw this in the early history of D-Bus, where most of the early APIs were part of freedesktop.org, so some app developers got the idea that they should be claiming pieces of freedesktop.org's namespace for themselves, instead of correctly using their own domain names).

[DarkKapla]

I think it should be more like com.example.Snake rather than org.libsdl.Snake, to avoid game developers mistakenly getting the idea that they ought to be calling their game something like org.libsdl.Doom

maybe com.libsdl-example.Snake? ;D

Also, I've just play that snake game and I thought the food cells were too dark blue. I suggest brightening the color up so to better see the cells on the black background.

[smcv]

maybe com.libsdl-example.Snake?

Not unless you happen to own libsdl-example.com, which you don't (at least according to whois).