SDL3 Main Callbacks

1int main(int, char**) {
2  AppInit();
3
4  bool IsRunning = true;
5  SDL_Event Event;
6  while (IsRunning) {
7    while (SDL_PollEvent(&Event)) {
8      AppEvent(Event);
9    }
10
11    AppIterate();
12  }
13
14  AppQuit();
15  return 0;
16}

If you want to follow along, we'll begin with the code from our previous lesson. It features a standard application loop in main.cpp that manages a World containing a single Goblin object.

Instead of us managing the application loop, the callback pattern involves us handing control over to SDL. We do this by defining the SDL_MAIN_USE_CALLBACKS macro before we #include SDL, and then we define 4 specific functions:

1. SDL_AppInit() for initialization
2. SDL_AppEvent() for event handling
3. SDL_AppIterate() for each iteration of our application loop
4. SDL_AppQuit() for shutting down

We'll cover each of these functions in this lesson but, as an overview, a basic main.cpp that implements the pattern might look something like this:

1#define SDL_MAIN_USE_CALLBACKS 1
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4
5SDL_AppResult SDL_AppInit(
6  void** AppState, int, char**
7) {
8  // ...
9  return SDL_APP_CONTINUE;
10}
11
12SDL_AppResult SDL_AppEvent(
13  void* AppState, SDL_Event* Event
14) {
15  // ...
16  return SDL_APP_CONTINUE;
17}
18
19SDL_AppResult SDL_AppIterate(void* AppState) {
20  // ...
21  return SDL_APP_CONTINUE;
22}
23
24void SDL_AppQuit(void* AppState, SDL_AppResult Result) {
25  // ...
26}

SDL will then take charge of our overall application flow, calling our functions at the appropriate moments in the application's lifecycle.

A key challenge with this pattern is sharing state between our different callback functions. Variables that were previously local to main() (like GameWindow, GameWorld, and the PreviousFrame timer) now need to be accessible across multiple, separate functions.

The standard solution is to bundle all this shared state into a single struct or class. SDL will dutifully pass this pointer through each of our callbacks, giving them access to the shared state.

Let's create a GameState struct to hold everything we need:

1#define SDL_MAIN_USE_CALLBACKS 1
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5#include "World.h"
6
7struct GameState {
8  Window GameWindow;
9  World GameWorld;
10  Uint64 PreviousFrame{0};
11};
12
13// ...

Next, let's add the four callback functions to our main.cpp.

This function is called once, at the very beginning of our program. Its job is to set up our game. AppInit() receives a void** argument which we can use to provide our GameState, in addition to the int and char** of a traditional main function.

It should also return an SDL_AppResult of SDL_APP_CONTINUE. We'll talk about this SDL_AppResult value in the next section.

1SDL_AppResult AppInit(void** AppState, int, char**) {
2  // ...
3
4  return SDL_APP_CONTINUE;
5}

Let's use this function body to initialize SDL as well as an instance of our GameState class. This broadly is the same content we had before our application loop in our main function.

This void** (ie, a pointer to a void pointer) argument is where we assign our GameState object, which SDL will then make available to our other callbacks.

We need our GameState to survive after AppInit() ends, so we dynamically allocate it using new:

1#define SDL_MAIN_USE_CALLBACKS 1
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5#include "World.h"
6
7struct GameState {
8  Window GameWindow;
9  World GameWorld;
10  bool IsRunning{true};
11  Uint64 PreviousFrame{0};
12};
13
14SDL_AppResult SDL_AppInit(
15  void** AppState, int, char**
16) {
17  SDL_Init(SDL_INIT_VIDEO);
18
19  GameState* State{new GameState()};
20  State->GameWorld.SpawnGoblin(
21    "Goblin Rogue", 100, 200
22  );
23  State->PreviousFrame = SDL_GetTicks();
24  *AppState = State;
25
26  return SDL_APP_CONTINUE;
27}
28
29// ...

The *AppState = State expression in this example may be confusing, as working with pointers-to-pointers can be difficult to understand.

Our AppState argument is a void** - a pointer to a void*. We're trying to assign our State pointer to the void* that this void** is pointing at.

To access the void* that the void** is pointing to, we need to dereference it, just like we would with any other pointer. Using the * operator on a pointer-to-a-pointer returns a pointer so, *AppState returns a void*:

1void* Ptr{*AppState};

We can then assign State to this void*. Remember, a void* is a pointer to anything and, in this case, State is a pointer to the GameState. Putting all of this together, *AppState = State is equivalent to this:

1void* Ptr{*AppState};
2Ptr = State;

The SDL_APP_RESULT Enum

Previously, we controlled when our application ended simply by returning from our main() function. In SDL's callback implementation, we instead control this using the SDL_AppResult values returned from our functions.

We can return one of three values from our callbacks:

• SDL_APP_CONTINUE, signalling our application should continue running
• SDL_APP_SUCCESS, signalling our application should quit because it completed successfully. This is equivalent to returning a 0 exit code from our main function.
• SDL_APP_FAILURE, signalling our application should quit because of an unrecoverable error. This is equivalent to returning a non-zero exit code from main.

As long as our callbacks keep returning SDL_APP_CONTINUE, our application will keep running. If any of them return SDL_APP_SUCCESS or SDL_APP_FAILURE, control will jump to our SDL_AppQuit() function, which we'll add later in this lesson.

SDL calls this function whenever a new event is available in the queue.

It receives the void* we set from AppInit() storing our state, and a pointer to the SDL_Event we need to react to. It should also return an SDL_APP_RESULT:

1SDL_APP_RESULT SDL_AppEvent(
2  void* AppState, SDL_Event* E
3) {
4  // ...
5  return SDL_APP_CONTINUE;
6}

Our job is simply to process that single event. We'll check if it's a quit event and update IsRunning accordingly. For all other events, we'll forward them to our World.

Note that SDL_AppEvent() receives the event as a pointer, whilst GameWorld expected the event to be delivered as a reference. We could update GameWorld to match this signature, or just convert the pointer to a reference using the * operator when forwarding it:

1// ...
2
3SDL_APP_RESULT SDL_AppEvent(
4  void* AppState, SDL_Event* E
5) {
6  GameState* State{
7    static_cast<GameState*>(AppState)
8  };
9
10  if (E->type == SDL_EVENT_QUIT) {
11    return SDL_APP_SUCCESS;
12  } else {
13    State->GameWorld.HandleEvent(*E);
14  }
15  
16  return SDL_APP_CONTINUE;
17}
18
19// ...

This is the heart of our application. SDL will call this function repeatedly in a loop. It's where we'll put our update and rendering logic. It receives the void* we set from AppInit() storing our latest state, and should also return an SDL_APP_RESULT:

1SDL_AppResult SDL_AppIterate(void* AppState) {
2  // ...
3
4  return SDL_APP_CONTINUE;
5}

We'll start by casting the void* back to a GameState* so we can access our objects. Then, we'll perform the same logic as our old while loop: calculate the time delta, tick the world, render, and update the window:

1// ...
2
3SDL_AppResult SDL_AppIterate(void* AppState) {
4  GameState* State{
5    static_cast<GameState*>(AppState)
6  };
7
8  Uint64 ThisFrame{SDL_GetTicks()};
9  Uint64 TimeDelta{
10    ThisFrame - State->PreviousFrame
11  };
12  State->PreviousFrame = ThisFrame;
13  State->GameWorld.Tick(TimeDelta / 1000.0f);
14
15  State->GameWindow.Render();
16  State->GameWorld.Render(
17    State->GameWindow.GetSurface()
18  );
19  State->GameWindow.Update();
20
21  return SDL_APP_CONTINUE;
22}
23
24// ...

This is the final callback, executed once the application loop has finished. It's where we clean up all the resources we allocated in AppInit(), and perform any other shutdown logic we need.

We're also provided with the SDL_AppResult that got us here if we need to implement different logic based on why we're quitting (SDL_APP_SUCCESS vs SDL_APP_FAILURE)

1// ...
2
3void SDL_AppQuit(
4  void* AppState, SDL_AppResult Result
5) {
6  delete AppState;
7}

SDL automatically calls SDL_Quit() when we're using the callback pattern, so we no longer need it, although it's safe to add if we want.

When we're using SDL_MAIN_USE_CALLBACKS, we should delete our old main() function to avoid any linker errors.

A complete version of our main.cpp is provided below:

1#define SDL_MAIN_USE_CALLBACKS 1
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5#include "World.h"
6
7struct GameState {
8  Window GameWindow;
9  World GameWorld;
10  bool IsRunning{true};
11  Uint64 PreviousFrame{0};
12};
13
14SDL_AppResult SDL_AppInit(
15  void** AppState, int, char**
16) {
17  SDL_Init(SDL_INIT_VIDEO);
18
19  GameState* State{new GameState()};
20  State->GameWorld.SpawnGoblin(
21    "Goblin Rogue", 100, 200
22  );
23  State->PreviousFrame = SDL_GetTicks();
24  *AppState = State;
25
26  return SDL_APP_CONTINUE;
27}
28
29SDL_AppResult SDL_AppEvent(
30  void* AppState, SDL_Event* Event
31) {
32  GameState* State{
33    static_cast<GameState*>(AppState)
34  };
35
36  if (Event->type == SDL_EVENT_QUIT) {
37    return SDL_APP_SUCCESS;
38  } else {
39    State->GameWorld.HandleEvent(*Event);
40  }
41  
42  return SDL_APP_CONTINUE;
43}
44
45SDL_AppResult SDL_AppIterate(void* AppState) {
46  GameState* State{
47    static_cast<GameState*>(AppState)
48  };
49
50  Uint64 ThisFrame{SDL_GetTicks()};
51  Uint64 TimeDelta{
52    ThisFrame - State->PreviousFrame
53  };
54  State->PreviousFrame = ThisFrame;
55  State->GameWorld.Tick(TimeDelta / 1000.0f);
56
57  State->GameWindow.Render();
58  State->GameWorld.Render(
59    State->GameWindow.GetSurface()
60  );
61  State->GameWindow.Update();
62
63  return SDL_APP_CONTINUE;
64}
65
66void SDL_AppQuit(
67  void* AppState, SDL_AppResult Result
68) {
69  delete AppState;
70}

This pattern offers a different way to structure an application, with some clear pros and cons.

Advantages

• Platform Compatibility: This is the primary reason for the callback pattern. Many platforms, especially mobile (iOS, Android) and web (Emscripten), have their own mandatory event loops. They don't let your application run its own loop. By breaking our logic into four specific callback functions, SDL can rearrange our logic to the format required by the target platform.
• Clear Structure: The code is naturally divided into distinct phases: initialization, event handling, updating, and cleanup. This can make the overall structure of the program easier to understand at a glance.

Disadvantages

• Loss of Control: You give up direct control over the main loop's timing and structure. Implementing more advanced loop patterns, like a fixed-timestep loop for physics, becomes much more difficult or impossible because you can't control when AppIterate() is called.
• State Management is Clumsier: Passing all shared state through a void* and casting it in every function is less elegant and less type-safe than having variables scoped within a single main() function.
• Less Common for Desktop: For applications that only target desktop platforms (Windows, macOS, Linux), the traditional while loop is often simpler, more flexible, and more familiar to C++ developers.

For the remainder of this course, we will return to the traditional while loop in main(). This approach gives us more direct control, which is beneficial for learning and for the desktop-focused projects we'll be building.

It's important to be aware that the callback pattern exists as an alternative to writing our own main function, and you should likely use it if you're targetting non-desktop platforms. But the traditional main function and application loop remains a perfectly valid and usually preferable choice for desktop development.

In this lesson, we explored SDL3's main callback pattern as an alternative to the traditional application loop.

• We refactored our project to use the four key callbacks: AppInit(), AppEvent(), AppIterate(), and AppQuit().
• We learned how to manage application state across these callbacks using a GameState struct, which SDL passes as void pointers.
• We discussed the primary advantage of this pattern: enhanced compatibility with platforms like mobile and web that have their own event loop requirements.
• We also covered the disadvantages, including a loss of fine-grained control over the loop and a more complex state management system.