In this lesson, we'll introduce how to write data from our program to external sources. We'll focus on writing to files for now, but the techniques we cover lay the foundations for working with other data streams, such as network traffic.

As we might expect, SDL's mechanism for writing data shares much in common with its API for reading data. We'll rely on SDL_IOStream objects, and the functions we use will be familiar to what we learned in the previous lesson.

Like before, we'll start with a basic main function that initializes SDL, and calls Write() and Read() functions within an included File namespace.

Files

src

Select a file to view its content

Running our program, we should see an error output from our Read() function, as it's trying to read a file that we haven't created yet:

1Error loading file: Couldn't open output.txt

Using `SDL_IOFromFile()`

We introduced the SDL_IOFromFile() function in the previous lesson. It returns an SDL_IOStream object, which is SDL's standard interface for interacting with data streams, such as files.

In the previous lesson, we passed the file path and the "rb" open mode to read the file. We'll use the same technique here, except we'll pass "wb" as the open mode, as we want to write to the file. We cover open modes in more detail later in this lesson.

Let's update our File::Write() function to create an SDL_IOStream handle for outputting content. Similar to the previous lesson, we'll also add an error check, and we'll close the file using SDL_CloseIO() when we're done:

src/File.h

1// ...
2
3namespace File {
4// ...
5void Write(const std::string& Path) {
6  SDL_IOStream* Handle{
7    SDL_IOFromFile(Path.c_str(), "wb")};
8
9  if (!Handle) {
10    std::cout << "Error opening file: "
11      << SDL_GetError();
12  }
13
14  // Use file...
15
16  SDL_CloseIO(Handle);
17}
18}

The "wb" open mode will additionally cause SDL to create a file if it doesn't exist. Therefore, running our program, after these changes we should now see our Read() function can successfully open the file, although it has no content yet:

1Content:

Using `SDL_WriteIO()`

The SDL_WriteIO() function is one of the main ways we output a collection of objects or values to a file. Let's update our File::Write() function to use it to output the C-style string "Hello World".

We introduced SDL_ReadIO() in the previous lesson, and the arguments to SDL_WriteIO() follow a similar pattern. It accepts 3 arguments:

The SDL_IOStream handle to use.
A pointer to the memory address where the content we want to write begins. Remember, a C-style string is simply a location in memory containing a contiguous sequence of char values, represented by a pointer to the first character - a char*.
The total number of bytes to write. We can use the strlen() function to determine how many characters are in a C-style string, and since char is 1 byte, this gives us our total bytes.

Let's update our File::Write() function to make use of this:

src/File.h

1// ...
2
3namespace File {
4// ...
5void Write(const std::string& Path) {
6  SDL_IOStream* Handle{
7    SDL_IOFromFile(Path.c_str(), "wb")};
8
9  if (!Handle) {
10    std::cout << "Error opening file: "
11      << SDL_GetError();
12  }
13
14  const char* Content{"Hello World"};
15  SDL_WriteIO(Handle, Content, strlen(Content));
16
17  SDL_CloseIO(Handle);
18}
19}

1Content: Hello World

SDL_WriteIO() returns the number of bytes it wrote:

src/File.h

1// ...
2
3namespace File {
4// ...
5void Write(const std::string& Path) {
6  SDL_IOStream* Handle{
7    SDL_IOFromFile(Path.c_str(), "wb")
8  };
9
10  if (!Handle) {
11    std::cout << "Error opening file: "
12      << SDL_GetError();
13  }
14
15  const char* Content{"Hello World"};
16
17  size_t BytesWritten{SDL_WriteIO(
18    Handle, Content, strlen(Content)
19  )};
20
21  std::cout << BytesWritten
22    << " bytes written\n";
23
24  SDL_CloseIO(Handle);
25}
26}

111 bytes written
2Content: Hello World

We can add some simple error checking by comparing this return value to what we expected. As usual, we can call SDL_GetError() for information on errors detected by SDL:

src/File.h

1// ...
2
3namespace File {
4// ...
5void Write(const std::string& Path) {
6  SDL_IOStream* Handle{
7    SDL_IOFromFile(Path.c_str(), "wb")};
8
9  if (!Handle) {
10    std::cout << "Error opening file: "
11      << SDL_GetError();
12  }
13
14  const char* Content{"Hello World"};
15  size_t ContentLength{strlen(Content)};
16  size_t BytesWritten{SDL_WriteIO(
17    Handle, Content, ContentLength
18  )};
19
20  std::cout << BytesWritten
21    << " bytes written\n";
22
23  if (BytesWritten < ContentLength) {
24    std::cout << "Expected " << ContentLength
25      << " - Error: " << SDL_GetError() << '\n';
26  }
27
28  SDL_CloseIO(Handle);
29}
30}

File Open Modes

In the previous lesson, we passed the rb string, telling SDL (and ultimately the underlying platform) that we wanted to read from the file in binary mode. In this case, we're using wb , indicating we want to create a new file for writing in binary mode.

If a file with the same name already exists, it will be entirely replaced when using wb. We'll cover more open modes, including the ability to edit or add to an existing file later in this chapter.

Binary Mode vs Text Mode

Platforms typically offer two ways to read or write files. These are commonly called binary mode and text mode. Binary mode reads and writes data in the exact format provided. This is intended when the data is used to communicate between programs (or within the same program), where a consistent and predictable format is useful.

On the other hand, text mode performs some platform-specific transformations to format the file in a way that conforms to that platform's conventions.

For example, we use \n to represent new lines in this course, but some platforms use a two-byte sequence: \r\n. Text mode aims to handle those transformations. However, even if our program is writing data that is intended to be read by humans, that data is usually going to be read in some program that handles formatting, so binary mode is typically preferred even in that scenario.

As such, text mode is rarely useful, but can be used by removing the b character from open modes if needed:

1// Open a file for reading in text mode
2SDL_IOFromFile("input.txt", "r");
3
4// Open a file for writing in text mode
5SDL_IOFromFile("output.txt", "w");

Adding to Existing Files

As we've seen, opening a file in "write" mode (such as "wb") ensures we get a new file every time we create our handle. If a file with that name already exists, it will be replaced.

In contrast, we can open a file in an "append" mode, such as "ab":

1SDL_IOFromFile("some-file.txt", "ab");

This will also create the file if it doesn't exist yet. However, if it does exist, write operations will be done at the end of the existing file, preventing us from losing any of the existing data.

This is primarily useful for logging scenarios, where we want to keep track of the actions our program performed:

Files

src

Select a file to view its content

Three file handles were opened and closed during the execution of the program, and each write operation was appended to the previous output:

1Content: OneTwoThree

If we run our program again, the logging from the second execution will add more content to the file, without replacing the output of the previous execution:

1Content: OneTwoThreeOneTwoThree

Writing Comma-Separated Values

Often when working with data files, we want to store multiple related values in a structured format. Comma-separated values (CSV) files are a common choice for this.

Let's extend our File namespace to support writing multiple strings as CSV records. First, we'll create an overload of our Write() function that accepts a vector of strings:

src/File.h

1// ...
2
3namespace File {
4// ...
5void Write(
6  const std::string& Path,
7  const std::vector<std::string>& Values
8) {
9  SDL_IOStream* Handle{
10    SDL_IOFromFile(Path.c_str(), "wb")
11  };
12
13  if (!Handle) {
14    std::cout << "Error opening file: "
15      << SDL_GetError();
16    return;
17  }
18
19  for (size_t i = 0; i < Values.size(); ++i) {
20    const std::string& Value{Values[i]};
21    SDL_WriteIO(Handle, Value.c_str(), Value.length());
22
23    // Add comma between values, newline at end
24    if (i < Values.size() - 1) {
25      SDL_WriteIO(Handle, ",", 1);
26    } else {
27      SDL_WriteIO(Handle, "\n", 1);
28    }
29  }
30
31  SDL_CloseIO(Handle);
32}
33}

We can use this new function like so:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <vector>
4#include "File.h"
5
6int main(int, char**) {
7  SDL_Init(0);
8  std::vector<std::string> Record{
9    "John", "Doe", "42", "Engineer"
10  };
11  File::Write("data.csv", Record);
12  File::Read("data.csv");
13  return 0;
14}

This will create a file containing:

1Content: John,Doe,42,Engineer

Writing Numeric Types

While we've focused on writing string data so far, often we need to write numeric values to files.

Since SDL_WriteIO() works with raw memory, we'll need to convert our numbers to strings first if we want them to be human-readable. Here's a function that demonstrates this:

src/File.h

1// ...
2
3namespace File {
4// ...
5void WriteNumber(
6  const std::string& Path,
7  auto Number
8) {
9  SDL_IOStream* Handle{
10    SDL_IOFromFile(Path.c_str(), "wb")
11  };
12
13  if (!Handle) {
14    std::cout << "Error opening file: "
15      << SDL_GetError();
16    return;
17  }
18
19  // Convert number to string
20  std::string Str{std::to_string(Number)};
21
22  SDL_WriteIO(Handle, Str.c_str(), Str.length());
23
24  SDL_CloseIO(Handle);
25}
26}

Note that the auto type in our number parameter means WriteNumber() is a template function. We cover template functions in our advanced course but, for now, we can just note that it allows our function to be called with various numeric types:

1File::WriteNumber("integer.txt", 42);
2File::WriteNumber("float.txt", 3.14159f);
3File::WriteNumber("double.txt", 2.71828);

This approach of converting a number to a string ensures our data is stored in a human-readable format. When we read these files back into our program, we can use string parsing functions like std::stoi(), std::stof(), or std::stod() to convert these strings back to their numeric types like int, float and double respectively.

We covered how to read numeric data in more detail in our .

Serializing a Custom Object

Now that we know how to write strings and numbers to files, let's combine these techniques to serialize a simple class. We'll create a Player class that contains both text and numeric data:

src/Player.h

1#pragma once
2#include <string>
3
4class Player {
5public:
6  std::string Name;
7  int Level;
8  float Health;
9};

We can add serialization capabilities to this class within a SaveToFile() method, using the same techniques we covered earlier in the lesson:

src/Player.h

1#pragma once
2#include <string>
3#include <iostream> 
4#include <SDL3/SDL.h>
5
6class Player {
7public:
8  std::string Name;
9  int Level;
10  float Health;
11
12  // Serialize the player to a file
13  void SaveToFile(const std::string& Path) {
14    SDL_IOStream* Handle{
15      SDL_IOFromFile(Path.c_str(), "wb")
16    };
17
18    if (!Handle) {
19      std::cout << "Error opening file: "
20        << SDL_GetError();
21      return;
22    }
23
24    // Convert numeric values to strings
25    std::string LevelStr{std::to_string(Level)};
26    std::string HealthStr{std::to_string(Health)};
27
28    // Write each value followed by a comma
29    SDL_WriteIO(Handle, Name.c_str(), Name.length());
30    SDL_WriteIO(Handle, ",", 1);
31
32    SDL_WriteIO(
33      Handle, LevelStr.c_str(), LevelStr.length()
34    );
35    SDL_WriteIO(Handle, ",", 1);
36
37    SDL_WriteIO(
38      Handle, HealthStr.c_str(), HealthStr.length()
39    );
40
41    SDL_CloseIO(Handle);
42  }
43};

We can use this class like so:

1Player P1{"Hero", 5, 100.0f};
2P1.SaveToFile("player.txt");

This will create a text file containing:

1Hero,5,100.000000

Each piece of data is stored in a human-readable format, separated by commas. This makes the file easy to read and edit manually if needed.

A complete example of this class, including a corresponding LoadFromFile() function using techniques we covered previously, might look like this:

Files

src

Select a file to view its content

1Roderick has been loaded

Serialization Libraries

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

However, once we understand the low-level details and considerations, it's extremely common to offload that heavy, manual work to a library. Just as SDL makes window management and input handling easier than it otherwise would be, libraries like cereal or boost::serialization exist that make serialization and deserialization easier.

Our Player class has almost 100 lines of manual serialization and deserialization code. However, once we build or adopt a library to standardize how we handle serialization across our project, we could add the exact same capability with just a few lines:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Player {
6public:
7  std::string Name;
8  int Level;
9  float Health;
10
11private:
12  friend class cereal::access;
13  template <class Archive>
14  void serialize(Archive& Data) const {
15    Data(Name, Level, Health);
16  }
17};

Additionally, in larger projects, we have to deal with situations that include:

Inheritance: How do we serialize objects that are instances of multiple classes?
Reference Types: How do we serialize objects that include references or pointers to other objects - for example, a Character holding a Weapon* member?
Polymorphic Types: If we have a pointer or reference to a base class, how do we serialize that object if it has a 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?

Most serialization libraries like Cereal also have mechanisms to take care of these problems for us. We cover Cereal in detail in our .

Summary

In this lesson, we explored writing data to files using SDL3. We learned how to:

Create and open files using SDL_IOFromFile()
Write data to files with SDL_WriteIO()
Understand different file open modes, including binary and text modes
Append data to existing files
Handle potential errors during file operations

We also built a complete, round-trip example, in the form of a Player class that can save its current state to disk, and reload itself back to that state later.

These skills form the foundation for more advanced file I/O operations, which we'll build on through the rest of this chapter.

Writing Data to Files

Files

Using `SDL_IOFromFile()`

src/File.h

Using `SDL_WriteIO()`

src/File.h

src/File.h

src/File.h

File Open Modes

Binary Mode vs Text Mode

Adding to Existing Files

Files

Writing Comma-Separated Values

src/File.h

Writing Numeric Types

src/File.h

Serializing a Custom Object

src/Player.h

src/Player.h

Files

Serialization Libraries

Summary

Numeric and Binary Data

Game Development with SDL3

Writing Data to Files

Files

Using SDL_IOFromFile()

src/File.h

Using SDL_WriteIO()

src/File.h

src/File.h

src/File.h

File Open Modes

Binary Mode vs Text Mode

Adding to Existing Files

Files

Writing Comma-Separated Values

src/File.h

Writing Numeric Types

src/File.h

Serializing a Custom Object

src/Player.h

src/Player.h

Files

Serialization Libraries

Summary

Numeric and Binary Data

Using `SDL_IOFromFile()`

Using `SDL_WriteIO()`