Read/Write Offsets and Seeking

This lesson focuses on two essential functions for working with SDL_RWops: SDL_RWtell() and SDL_RWseek().

• SDL_RWtell() provides the current read/write offset
• SDL_RWseek() 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_RWops 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_RWread(), the internal offset of the RWOps object we’re using is updated, such that the next read begins where we left off:

1// content.txt
2HelloWorld

1#include <SDL.h>
2#include <iostream>
3
4int main(int, char**) {
5  SDL_RWops* File{SDL_RWFromFile(
6    "content.txt", "rb")};
7
8  // 5 bytes + 1 for null terminator
9  char Content[6];
10  Content[5] = '\0';
11
12  SDL_RWread(File, Content, 1, 5);
13  std::cout << "First Read: " << Content;
14
15  SDL_RWread(File, Content, 1, 5);
16  std::cout << "\nSecond Read: " << Content;
17
18  SDL_RWclose(File);
19  return 0;
20}

1First Read: Hello
2Second Read: World

SDL_RWtell()

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

1#include <SDL.h>
2#include <iostream>
3
4int main(int, char**) {
5  SDL_RWops* File{SDL_RWFromFile(
6    "content.txt", "rb")};
7
8  char Content[6];
9  Content[5] = '\0';
10
11  std::cout << "Read/Write Offset: "
12    << SDL_RWtell(File);
13  SDL_RWread(File, Content, 1, 5);
14  std::cout << "\nFirst Read: " << Content;
15
16  std::cout << "\nRead/Write Offset: "
17    << SDL_RWtell(File);
18  SDL_RWread(File, Content, 1, 5);
19  std::cout << "\nSecond Read: " << Content;
20
21  std::cout << "\nRead/Write Offset: "
22    << SDL_RWtell(File);
23
24  SDL_RWclose(File);
25  return 0;
26}

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

Error Handling

The SDL_RWtell() 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_RWtell(File) < 0) {
2  std::cout << "Couldn't determine read/write "
3    "offset: " << SDL_GetError();
4}

SDL_RWseek()

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

1. The stream: the pointer to the SDL_RWops object whose read/write offset we want to update
2. The seek value: an integer representing how far 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
3. 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_RWseek(). The possible values for the third argument are:

• RW_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.
• RW_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.
• RW_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:

1#include <SDL.h>
2#include <iostream>
3
4int main(int, char**) {
5  SDL_RWops* File{SDL_RWFromFile(
6    "content.txt", "rb")};
7
8  char Content[6];
9  Content[5] = '\0';
10
11  std::cout << "Read/Write Offset: "
12    << SDL_RWtell(File);
13
14  SDL_RWseek(File, 5, RW_SEEK_SET);
15
16  std::cout << "\nRead/Write Offset: "
17    << SDL_RWtell(File);
18
19  SDL_RWread(File, Content, 1, 5);
20  std::cout << "\nFirst Read: " << Content;
21
22  SDL_RWclose(File);
23  return 0;
24}

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

Return Value

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

1#include <SDL.h>
2#include <iostream>
3
4int main(int, char**) {
5  SDL_RWops* File{SDL_RWFromFile(
6    "content.txt", "rb")};
7
8  std::cout << "Read/Write Offset: "
9    << SDL_RWtell(File);
10
11  std::cout << "\nRead/Write Offset: "
12    << SDL_RWseek(File, -3, RW_SEEK_END);
13
14  SDL_RWclose(File);
15  return 0;
16}

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

Error Handling

The SDL_RWseek() 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:

1#include <SDL.h>
2#include <iostream>
3
4int main(int, char**) {
5  SDL_RWops* File{SDL_RWFromFile(
6    "content.txt", "rb")};
7
8  if (SDL_RWseek(File, -5, RW_SEEK_SET) < 0) {
9    std::cout << "Error seeking: "
10      << SDL_GetError();
11  }
12
13  SDL_RWclose(File);
14  return 0;
15}

1Error seeking: windows_file_seek: An attempt was made to move the file pointer before the beginning of the file.

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:

1#include <SDL.h>
2#include <iostream>
3
4void CreateAndInitializeFile(
5  const char* Path, int32_t InitialScore
6) {
7  SDL_RWops* File{SDL_RWFromFile(Path, "w+b")};
8  if (!File) {
9    // Handle errors
10    return;
11  }
12
13  SDL_RWwrite(File, &InitialScore, sizeof(int32_t), 1);
14  SDL_RWclose(File);
15}
16
17void UpdateHighScore(
18  const char* Path, int32_t NewScore
19) {
20  SDL_RWops* File{SDL_RWFromFile(Path, "r+b")};
21  if (!File) {
22    CreateAndInitializeFile(Path, NewScore);
23    return;
24  }
25  
26  // TODO
27
28  SDL_RWclose(File);
29}
30
31int main(int, char**) {
32  UpdateHighScore("highscore.dat", 5000);
33  return 0;
34}

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_RWseek(), and overwrite that integer with our higher score:

1#include <SDL.h>
2#include <iostream>
3
4void CreateAndInitializeFile(
5  const char* Path, int32_t InitialScore
6) {
7  SDL_RWops* File{SDL_RWFromFile(Path, "w+b")};
8  if (!File) {
9    return;
10  }
11
12  SDL_RWwrite(File, &InitialScore, sizeof(int32_t), 1);
13  SDL_RWclose(File);
14}
15
16void UpdateHighScore(
17  const char* Path, int32_t NewScore
18) {
19  SDL_RWops* File{SDL_RWFromFile(Path, "r+b")};
20  if (!File) {
21    CreateAndInitializeFile(Path, NewScore);
22    return;
23  }
24
25  int32_t CurrentScore{0};
26  SDL_RWread(File, &CurrentScore, sizeof(int32_t), 1);
27
28  std::cout << "Current High Score: "
29    << CurrentScore << "\n";
30
31  if (NewScore > CurrentScore) {
32    std::cout << NewScore << " is a new high score!"
33      " Updating file\n";
34    SDL_RWseek(File, 0, RW_SEEK_SET);
35    SDL_RWwrite(File, &NewScore, sizeof(int32_t), 1);
36  }
37
38  SDL_RWclose(File);
39}
40
41int main(int, char**) {
42  // New high score
43  UpdateHighScore("highscore.dat", 5500);
44  return 0;
45}

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

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 advanced course:

Binary Serialization using Cereal

A detailed and practical tutorial for binary serialization in modern C++ using the cereal library.

Summary

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

• The read/write offset tracks the current position within an SDL_RWops stream.
• SDL_RWtell() returns the current offset.
• SDL_RWseek() allows you to move the offset to a specific location.
• RW_SEEK_SET, RW_SEEK_CUR, and RW_SEEK_END define the anchor for seeking.
• We can detect and react to errors when using SDL_RWtell() and SDL_RWseek().

Next Lesson

Maths and Geometry Primer

Learn the basics of maths and geometry, so we can represent concepts like positions and distances between objects in our worlds.

ContinueView Course