SDL Event Timestamp Field

The timestamp field, present in most SDL_Event subtypes (like SDL_MouseMotionEvent, SDL_MouseButtonEvent, SDL_KeyboardEvent, etc.), records the time when the event was generated.

Units and Reference Point

• Units: The timestamp is measured in milliseconds.
• Reference Point: It represents the number of milliseconds that had elapsed since the SDL library was initialized (i.e., since your program called SDL_Init()).

How It's Used

While not always necessary for basic input handling, the timestamp can be valuable in several scenarios:

Event Ordering and Timing: If you need to know the precise order or timing difference between multiple events, the timestamp provides this information. For example, calculating the time between a mouse button press (SDL_MOUSEBUTTONDOWN) and its release (SDL_MOUSEBUTTONUP) to measure click duration.

1Uint32 pressTimestamp = 0;
2
3// Inside event loop
4if (event.type == SDL_MOUSEBUTTONDOWN) {
5  pressTimestamp = event.button.timestamp;
6} else if (event.type == SDL_MOUSEBUTTONUP) {
7  if (pressTimestamp != 0) {
8    Uint32 clickDuration = event.button.timestamp - pressTimestamp;
9    std::cout << "Click duration: " << clickDuration << "ms\n";
10    pressTimestamp = 0; // Reset for next click
11  }
12}

Input Sequencing: In complex input scenarios, like detecting specific gesture patterns or chorded key presses, the timestamps help determine if inputs occurred close enough together in time.

Debugging: Timestamps can be logged alongside events to help debug input issues, understand event sequences, or diagnose performance problems related to event handling.

Network Synchronization (Advanced): In networked multiplayer games, event timestamps might be sent over the network (potentially adjusted for latency) to help synchronize input actions across clients.

Getting Current Time

If you need the current time relative to SDL initialization outside of an event structure, you can use the SDL_GetTicks() function (or SDL_GetTicks64() for a 64-bit value less prone to wrapping around after ~49 days).

1Uint32 currentTime = SDL_GetTicks();
2std::cout << "Time since SDL_Init: " << currentTime << "ms\n";

The event timestamp essentially captures the value of SDL_GetTicks() at the moment the operating system reported the input event to SDL.