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 their API for reading data. We'll rely on SDL_RWops 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.

1// main.cpp
2#include <SDL.h>
3#include "File.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(0);
7  File::Write("output.txt");
8  File::Read("output.txt");
9  return 0;
10}

Our Read() function logs out the file's contents, using techniques we covered in the previous lesson. In this lesson, we'll work on the Write() function, which is currently empty:

1// File.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5
6namespace File {
7  void Read(const std::string& Path) {
8    char* Content{static_cast<char*>(
9      SDL_LoadFile(Path.c_str(), nullptr)
10    )};
11    
12    if (Content) {
13      std::cout << "Content: " << Content;
14    } else {
15      std::cout << "Error loading file: "
16        << SDL_GetError();
17    }
18    
19    SDL_free(Content);
20  }
21  
22  void Write(const std::string& Path) {
23    // ...
24  }
25
26}

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: Parameter 'src' is invalid

Using `SDL_RWFromFile()`

We introduced the SDL_RWFromFile() function in the previous lesson. It returns an SDL_RWops 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_RWops handle for outputting content. Similar to the previous lesson, we'll also add an error check, and we'll close the file using SDL_RWclose() when we're done:

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

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_RWwrite()`

The SDL_RWwrite() 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_RWread() in the previous lesson, and the arguments to SDL_RWwrite() follow a similar pattern. It accepts 4 arguments:

The SDL_RWops 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 size of each object in bytes. In this example, we're writing char values, and a char is 1 byte. We could simply pass 1 as the argument, but we'll use sizeof(char) as it clarifies what the 1 represents.
The quantity of objects to write. We can use the strlen() function to determine how many characters are in a C-style string

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

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

1Content: Hello World

SDL_RWFromFile() returns an integer, representing how many objects it wrote:

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(const std::string& Path) {
7  SDL_RWops* Handle{
8    SDL_RWFromFile(Path.c_str(), "wb")};
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 ValuesWritten{SDL_RWwrite(
18    Handle, Content,
19    sizeof(char), strlen(Content)
20  )};
21  
22  std::cout << ValuesWritten
23    << " values written\n";
24
25  SDL_RWclose(Handle);
26}
27}

111 values 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:

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

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_RWFromFile("input.txt", "r")}
3
4// Open a file for writing in text mode
5SDL_RWFromFile("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_RWFromFile("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:

1// main.cpp
2#include <SDL.h>
3#include "File.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(0);
7  File::Write("logs.txt", "One");
8  File::Write("logs.txt", "Two");
9  File::Write("logs.txt", "Three");
10  File::Read("logs.txt");
11  return 0;
12}

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(
7  const std::string& Path,
8  const char* Content
9) {
10  SDL_RWops* Handle{
11    SDL_RWFromFile(Path.c_str(), "ab")};
12
13  if (!Handle) {
14    std::cout << "Error opening file: "
15      << SDL_GetError();
16  }
17
18  SDL_RWwrite(
19    Handle, Content,
20    sizeof(char), strlen(Content)
21  );
22
23  SDL_RWclose(Handle);
24}
25}

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:

1void Write(
2  const std::string& path,
3  const std::vector<std::string>& values
4) {
5  SDL_RWops* Handle{
6    SDL_RWFromFile(path.c_str(), "wb")
7  };
8
9  if (!Handle) {
10    std::cout << "Error opening file: "
11      << SDL_GetError();
12    return;
13  }
14
15  for (size_t i = 0; i < values.size(); ++i) {
16    const std::string& value = values[i];
17    SDL_RWwrite(Handle, value.c_str(),
18      sizeof(char), value.length());
19  
20    // Add comma between values, newline at end
21    if (i < values.size() - 1) {
22      SDL_RWwrite(Handle, ",", sizeof(char), 1);
23    } else {
24      SDL_RWwrite(Handle, "\n", sizeof(char), 1);
25    }
26  }
27
28  SDL_RWclose(Handle);
29}

We can use this new function like so:

1std::vector<std::string> record{
2  "John", "Doe", "42", "Engineer"
3};
4File::Write("data.csv", record);

This will create a file containing:

1John,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_RWwrite() 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:

1void WriteNumber(
2  const std::string& path,
3  auto number
4) {
5  SDL_RWops* Handle{
6    SDL_RWFromFile(path.c_str(), "wb")
7  };
8
9  if (!Handle) {
10    std::cout << "Error opening file: "
11      << SDL_GetError();
12    return;
13  }
14
15  // Convert number to string
16  std::string str = std::to_string(number);
17  
18  SDL_RWwrite(Handle, str.c_str(),
19    sizeof(char), str.length());
20
21  SDL_RWclose(Handle);
22}

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 previous lesson:

Reading Data from Files

Learn how to read and parse game data stored in external files using SDL_RWops

View Related Lesson

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:

1class Player {
2public:
3  std::string name;
4  int level;
5  float health;
6};

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

1class Player {
2public:
3  std::string name;
4  int level;
5  float health;
6
7  // Serialize the player to a file
8  void SaveToFile(const std::string& path) {
9    SDL_RWops* Handle{
10      SDL_RWFromFile(path.c_str(), "wb")
11    };
12
13    if (!Handle) {
14      std::cout << "Error opening file: "
15        << SDL_GetError();
16      return;
17    }
18
19    // Convert numeric values to strings
20    std::string levelStr = 
21      std::to_string(level);
22    std::string healthStr = 
23      std::to_string(health);
24
25    // Write each value followed by a comma
26    SDL_RWwrite(Handle, name.c_str(),
27      sizeof(char), name.length());
28    SDL_RWwrite(Handle, ",",
29      sizeof(char), 1);
30      
31    SDL_RWwrite(Handle, levelStr.c_str(),
32      sizeof(char), levelStr.length());
33    SDL_RWwrite(Handle, ",",
34      sizeof(char), 1);
35      
36    SDL_RWwrite(Handle, healthStr.c_str(),
37      sizeof(char), healthStr.length());
38
39    SDL_RWclose(Handle);
40  }
41};

We can use this class like so:

1Player player{"Hero", 5, 100.0f};
2player.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 approach makes the file easy to read and edit manually if needed.

A corresponding LoadFromFile() function for this Player class could look like this:

1class Player {
2public:
3  // ...
4
5  bool LoadFromFile(const std::string& path) {
6    // Load the entire file as a string
7    char* content{static_cast<char*>(
8      SDL_LoadFile(path.c_str(), nullptr)
9    )};
10
11    if (!content) {
12      std::cout << "Error loading file: "
13        << SDL_GetError();
14      return false;
15    }
16
17    // Convert to a std::string for easier parsing
18    std::string data{content};
19    SDL_free(content);
20
21    // Find positions of commas
22    size_t firstComma = data.find(',');
23    size_t secondComma = data.find(',', 
24      firstComma + 1);
25
26    if (firstComma == std::string::npos ||
27        secondComma == std::string::npos) {
28      std::cout << "Invalid file format\n";
29      return false;
30    }
31
32    // Extract and parse values
33    name = data.substr(0, firstComma);
34    
35    std::string levelStr = data.substr(
36      firstComma + 1,
37      secondComma - firstComma - 1
38    );
39    
40    std::string healthStr = data.substr(
41      secondComma + 1
42    );
43
44    try {
45      level = std::stoi(levelStr);
46      health = std::stof(healthStr);
47    } catch (const std::exception& e) {
48      std::cout << "Error parsing values: "
49        << e.what() << '\n';
50      return false;
51    }
52
53    return true;
54  }
55};

Preview

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 with 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 our updated, added, or removed class variables?

Most serialization libraries like Cereal also take care of these problems for us. 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.

View Related Lesson

Summary

In this lesson, we explored writing data to files using SDL2 in C++. We learned how to:

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

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

Writing Data to Files

Using `SDL_RWFromFile()`

Using `SDL_RWwrite()`

File Open Modes

Binary Mode vs Text Mode

Adding to Existing Files

Writing Comma-Separated Values

Writing Numeric Types

Reading Data from Files

Serializing a Custom Object

Summary

Numeric and Binary Data

Game Development with SDL2

Questions & Answers

Writing Data to Files

Using SDL_RWFromFile()

Using SDL_RWwrite()

File Open Modes

Binary Mode vs Text Mode

Adding to Existing Files

Writing Comma-Separated Values

Writing Numeric Types

Reading Data from Files

Serializing a Custom Object

Summary

Numeric and Binary Data

Questions & Answers

Using `SDL_RWFromFile()`

Using `SDL_RWwrite()`