This lesson focuses on two essential functions for working with SDL_IOStream: SDL_TellIO() and SDL_SeekIO().

SDL_TellIO() provides the current read/write offset
SDL_SeekIO() lets you modify it

This gives us fine-grained control over stream interactions. We'll examine how these functions work together and apply them to a practical example of managing a game's high score.

Read/Write Offsets

Behind the scenes, SDL_IOStream objects maintain a simple integer value that gets updated as we perform read and write operations. This value is sometimes called the read/write position, cursor, or offset.

Its purpose is to keep track of the data we've already read, or already written. For example, the following program is reading a file containing 10 characters - HelloWorld.

When we read 5 characters using SDL_ReadIO(), the internal offset of the SDL_IOStream object we're using is updated, such that the next read begins where we left off:

Files

[output]

src

Select a file to view its content

1First Read: Hello
2Second Read: World

Using `SDL_TellIO()`

We can retrieve the current offset of an SDL_IOStream object by passing it to the SDL_TellIO() function. When we first create an SDL_IOStream, we expect its offset to be 0, but this will change as we interact with the stream:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6int main(int, char**) {
7  std::string Base{SDL_GetBasePath()};
8  SDL_IOStream* File{SDL_IOFromFile(
9    (Base + "content.txt").c_str(),
10    "rb"
11  )};
12
13  char Content[6];
14  Content[5] = '\0';
15
16  std::cout << "Read/Write Offset: "
17    << SDL_TellIO(File);
18  SDL_ReadIO(File, Content, 5);
19  std::cout << "\nFirst Read: " << Content;
20
21  std::cout << "\nRead/Write Offset: "
22    << SDL_TellIO(File);
23  SDL_ReadIO(File, Content, 5);
24  std::cout << "\nSecond Read: " << Content;
25
26  std::cout << "\nRead/Write Offset: "
27    << SDL_TellIO(File);
28
29  SDL_CloseIO(File);
30  return 0;
31}

1Read/Write Offset: 0
2First Read: Hello
3Read/Write Offset: 5
4Second Read: World
5Read/Write Offset: 10

Handling Errors from `SDL_TellIO()`

The SDL_TellIO() function can sometimes fail. When this happens, it will return a negative error code. We can check for this outcome and react to it as needed. We can also call SDL_GetError() for more information on what went wrong:

1if (SDL_TellIO(File) < 0) {
2  std::cout << "Couldn't determine read/write "
3    "offset: " << SDL_GetError();
4}

Using `SDL_SeekIO()`

We can manipulate the read/write offset of an SDL_IOStream object using the SDL_SeekIO() function. This function requires three arguments:

The stream: the pointer to the SDL_IOStream object whose read/write offset we want to update
The seek value: an integer representing by how many bytes we want the offset to move, relative to the anchor. This can be a negative value if we want to move the offset backwards, or a positive value to move it forward
The anchor: where we want to offset to move from

The second and third arguments work together to determine where the offset should be after our call to SDL_SeekIO(). The possible values for the third argument are:

SDL_IO_SEEK_SET: Our seek value sets the offset relative to the start of the stream. We should provide a positive seek value in this context.
SDL_IO_SEEK_CUR: Our seek value moves the offset relative to the current position of the offset. Our seek value can be positive or negative in this context.
SDL_IO_SEEK_END: Our seek value sets the offset relative to the end of the stream. Our seek value should be negative in this context.

Here's an example:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6int main(int, char**) {
7  std::string Base{SDL_GetBasePath()};
8  SDL_IOStream* File{SDL_IOFromFile(
9    (Base + "content.txt").c_str(),
10    "rb"
11  )};
12
13  char Content[6];
14  Content[5] = '\0';
15
16  std::cout << "Read/Write Offset: "
17    << SDL_TellIO(File);
18
19  SDL_SeekIO(File, 5, SDL_IO_SEEK_SET);
20
21  std::cout << "\nRead/Write Offset: "
22    << SDL_TellIO(File);
23
24  SDL_ReadIO(File, Content, 5);
25  std::cout << "\nFirst Read: " << Content;
26
27  SDL_CloseIO(File);
28  return 0;
29}

1Read/Write Offset: 0
2Read/Write Offset: 5
3First Read: World

Return Value

The SDL_SeekIO() function returns the new offset of the SDL_IOStream object, relative to the beginning of the stream:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6int main(int, char**) {
7  std::string Base{SDL_GetBasePath()};
8  SDL_IOStream* File{SDL_IOFromFile(
9    (Base + "content.txt").c_str(),
10    "rb"
11  )};
12
13  std::cout << "Read/Write Offset: "
14    << SDL_TellIO(File);
15
16  std::cout << "\nRead/Write Offset: "
17    << SDL_SeekIO(File, -3, SDL_IO_SEEK_END);
18
19  SDL_CloseIO(File);
20  return 0;
21}

1Read/Write Offset: 0
2Read/Write Offset: 7

Handling Errors from `SDL_SeekIO()`

The SDL_SeekIO() function can sometimes fail. When this happens, it will return -1. We can check for this outcome and react to it as needed. We can also call SDL_GetError() for more information on what went wrong:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6int main(int, char**) {
7  SDL_IOStream* File{SDL_IOFromFile(
8    "does-not-exist.txt",
9    "rb"
10  )};
11
12  if (SDL_SeekIO(File, 5, SDL_IO_SEEK_SET) < 0) {
13    std::cout << "Error seeking: "
14      << SDL_GetError();
15  }
16
17  SDL_CloseIO(File);
18
19  return 0;
20}

1Error seeking: Parameter 'context' is invalid

Example: Tracking High Score

In this section, we'll create a simple example where we keep track of the player's highest score as a 32-bit integer serialized in a highscore.dat file on their hard drive.

Every time the player gets a new score, we'll compare it to the score in that file and, if it's higher, we'll update the file.

Let's handle the initial case first. The first time we call UpdateHighScore(), the highscore.dat file will not exist. So, we'll call CreateAndInitializeFile() to create it, and initialize it with the score the player received:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6void CreateAndInitializeFile(
7  const char* Path, int32_t InitialScore
8) {
9  std::string Base{SDL_GetBasePath()};
10  SDL_IOStream* File{SDL_IOFromFile(
11    (Base + Path).c_str(),
12    "wb" // Write in binary mode
13  )};
14  if (!File) {
15    // Handle errors
16    return;
17  }
18
19  SDL_WriteIO(File, &InitialScore, sizeof(int32_t));
20  SDL_CloseIO(File);
21}
22
23void UpdateHighScore(
24  const char* Path, int32_t NewScore
25) {
26  std::string Base{SDL_GetBasePath()};
27  SDL_IOStream* File{SDL_IOFromFile(
28    (Base + Path).c_str(),
29    "r+b" // Read and write in binary mode
30  )};
31  if (!File) {
32    CreateAndInitializeFile(Path, NewScore);
33    return;
34  }
35
36  // TODO
37
38  SDL_CloseIO(File);
39}
40
41int main(int, char**) {
42  UpdateHighScore("highscore.dat", 5000);
43  return 0;
44}

On subsequent calls to UpdateHighScore(), there will be a highscore.dat file available. We'll open that file for reading and writing, and retrieve the current high score.

If our new score is higher than what is currently in the file, we'll rewind our read/write offset to the beginning of the file using SDL_SeekIO(), and overwrite that integer with our higher score:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3/SDL_iostream.h>
4#include <iostream>
5
6void CreateAndInitializeFile(
7  const char* Path, int32_t InitialScore
8) {
9  std::string Base{SDL_GetBasePath()};
10  SDL_IOStream* File{SDL_IOFromFile(
11    (Base + Path).c_str(),
12    "wb"
13  )};
14  if (!File) {
15    return;
16  }
17
18  SDL_WriteIO(File, &InitialScore, sizeof(int32_t));
19  SDL_CloseIO(File);
20}
21
22void UpdateHighScore(
23  const char* Path, int32_t NewScore
24) {
25  std::string Base{SDL_GetBasePath()};
26  SDL_IOStream* File{SDL_IOFromFile(
27    (Base + Path).c_str(),
28    "r+b"
29  )};
30  if (!File) {
31    CreateAndInitializeFile(Path, NewScore);
32    return;
33  }
34
35  int32_t CurrentScore{0};
36  SDL_ReadIO(File, &CurrentScore, sizeof(int32_t));
37
38  std::cout << "Current High Score: "
39    << CurrentScore << "\n";
40
41  if (NewScore > CurrentScore) {
42    std::cout << NewScore << " is a new high score!"
43      " Updating file\n";
44    SDL_SeekIO(File, 0, SDL_IO_SEEK_SET);
45    SDL_WriteIO(File, &NewScore, sizeof(int32_t));
46  } else {
47    std::cout << NewScore << " isn't better :(\n";
48  }
49
50  SDL_CloseIO(File);
51}
52
53int main(int, char**) {
54  // New high score
55  UpdateHighScore("highscore.dat", 5500);
56  return 0;
57}

If we run our program, we should see it read our previous score, and update it with our new record:

1Current High Score: 5000
25500 is a new high Score! Updating file

But if we run the program again and get the same score or lower:

1Current High Score: 5500
25500 isn't better :(

Advanced Serialization

The examples in this chapter have focused on slow, manual implementations of serialization and deserialization so we can build a deeper understanding of what is going on.

In larger projects, we typically want to make it as easy as possible to add serialization and deserialization capabilities to the classes and structs we define. Additionally, we have to deal with more complex situations that include:

Inheritance: How do we handle objects that include inherited members?
Reference Types: How do we handle objects that include references or pointers to other objects - for example, a Character with a Weapon* member?
Polymorphic Types: If we have a pointer or reference to a polymorphic type, how do we serialize that object including data members from its more derived type?
Versioning: When we update our game, how do we ensure saved files based on previous versions are still usable, even if we updated, added, or removed class variables?

Fortunately, these are largely solved problems. We have a wide range of open-source serialization libraries that we can add to our project for free.

Many of these libraries, like Cereal, also include support for serializing standard library types like std::string and std::vector, further reducing the amount of code we need to write. We cover Cereal in detail in our .

Summary

In this lesson, we explored the vital concept of the read/write offset in SDL_IOStream, learning how to use SDL_TellIO() to get the current position and SDL_SeekIO() to move to different locations within a stream. Here are the key points:

The read/write offset tracks the current position within an SDL_IOStream stream.
SDL_TellIO() returns the current offset.
SDL_SeekIO() allows you to move the offset to a specific location.
SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, and SDL_IO_SEEK_END define the anchor for seeking.
We can detect and react to errors when using SDL_TellIO() and SDL_SeekIO().

Read/Write Offsets and Seeking

Read/Write Offsets

Files

Using `SDL_TellIO()`

src/main.cpp

Handling Errors from `SDL_TellIO()`

Using `SDL_SeekIO()`

src/main.cpp

Return Value

src/main.cpp

Handling Errors from `SDL_SeekIO()`

src/main.cpp

Example: Tracking High Score

src/main.cpp

src/main.cpp

Advanced Serialization

Summary

Game Development with SDL3

Read/Write Offsets and Seeking

Read/Write Offsets

Files

Using SDL_TellIO()

src/main.cpp

Handling Errors from SDL_TellIO()

Using SDL_SeekIO()

src/main.cpp

Return Value

src/main.cpp

Handling Errors from SDL_SeekIO()

src/main.cpp

Example: Tracking High Score

src/main.cpp

src/main.cpp

Advanced Serialization

Summary

Using `SDL_TellIO()`

Handling Errors from `SDL_TellIO()`

Using `SDL_SeekIO()`

Handling Errors from `SDL_SeekIO()`