Binary vs. Text Mode

When you open a file using SDL_RWFromFile(), you can specify whether to open it in text mode or binary mode. The difference between these modes lies in how they handle special characters, particularly newline characters.

Text Mode ("w" or "r"):

Newline Translation: In text mode, the operating system may translate newline characters to ensure that text files are stored in a format compatible with the system's conventions.

For example, on Windows, newline characters are typically represented by a carriage return followed by a line feed (\r\n), while on Linux and macOS, they are represented by a single line feed (\n).

When you write a \n character in text mode, the operating system might automatically convert it to \r\n on Windows. Conversely, when you read a \r\n sequence, it might be translated back to a single \n.

Character Encoding: Text mode also assumes that the file contains text encoded using a specific character encoding (e.g., UTF-8, ASCII). The operating system might perform some character encoding conversions when reading or writing data.

Binary Mode ("wb" or "rb"):

No Translation: In binary mode, no translation or conversion is performed. Data is read and written exactly as it is, byte for byte. Newline characters and other special characters are treated like any other byte of data.

Raw Data: Binary mode is suitable for handling any type of data, not just text. You can use it to read and write images, audio files, executable files, or any other type of file where you need to preserve the exact byte sequence.

Importance of Binary Mode

In most cases, including the high score example in this lesson, we're storing an integer value (or an array of integers) in the file. Integers are not text; they are binary data. If we were to open the file in text mode, the following problems could occur:

Corruption of Data: When we write the integer to the file, the operating system might try to interpret it as text and perform newline translations or character encoding conversions.

This would corrupt the binary representation of the integer, making it unreadable when we try to load it back into the program.

Incorrect Interpretation: When we read the integer back from the file, the operating system might again try to interpret it as text, potentially translating newline sequences or performing character encoding conversions.

This would result in an incorrect integer value being read.

Example

Consider the following code:

1#include <SDL.h>
2#include <iostream>
3
4int main() {
5  int32_t Score{12345};
6
7  // Write in text mode
8  SDL_RWops* TextFile{SDL_RWFromFile(
9    "text_mode.dat", "w")};
10  SDL_RWwrite(
11    TextFile, &Score, sizeof(int32_t), 1);
12  SDL_RWclose(TextFile);
13
14  // Write in binary mode
15  SDL_RWops* BinaryFile{SDL_RWFromFile(
16    "binary_mode.dat", "wb")};
17  SDL_RWwrite(
18    BinaryFile, &Score, sizeof(int32_t), 1);
19  SDL_RWclose(BinaryFile);
20
21  return 0;
22}

If you were to open text_mode.dat in a hex editor, you might see unexpected bytes due to newline translations or character encoding issues.

On the other hand, binary_mode.dat would contain the exact binary representation of the integer 12345.

Therefore, it's crucial to use binary mode in the high score example (and in most cases where you're not specifically dealing with text files) to ensure that the data is written and read correctly without any unintended modifications.