SDL3pp
A slim C++ wrapper for SDL3
|
The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level (in SDL's case, this sits on top of the [Filesystem](CategoryFilesystem) and [IOStream](CategoryIOStream) subsystems). More...
Classes | |
struct | SDL::StorageRef |
An abstract interface for filesystem access. More... | |
struct | SDL::Storage |
Handle to an owned storage. More... | |
struct | SDL::StorageUnsafe |
Unsafe Handle to storage. More... | |
Typedefs | |
using | SDL::StorageShared = ResourceShared< Storage > |
Handle to a shared storage. | |
using | SDL::StorageWeak = ResourceWeak< Storage > |
Weak handle to a shared storage. | |
using | SDL::StorageInterface = SDL_StorageInterface |
Function interface for Storage. | |
Functions | |
StorageShared | SDL::Storage::share () |
Move this storage into a StorageShared. | |
It is significantly more restrictive than a typical filesystem API, for a number of reasons:
Consider the following example:
Going over the bullet points again:
Due to these assumptions, the filesystem code is not portable and will fail under these common scenarios:
When using Storage, these types of problems are virtually impossible to trip over:
Note the improvements that Storage makes:
The result is an application that is significantly more robust against the increasing demands of platforms and their filesystems!
A publicly available example of an Storage backend is the Steam Cloud backend - you can initialize Steamworks when starting the program, and then SDL will recognize that Steamworks is initialized and automatically use ISteamRemoteStorage when the application opens user storage. More importantly, when you open storage it knows to begin a "batch" of filesystem operations, and when you close storage it knows to end and flush the batch. This is used by Steam to support Dynamic Cloud Sync ; users can save data on one PC, put the device to sleep, and then continue playing on another PC (and vice versa) with the save data fully synchronized across all devices, allowing for a seamless experience without having to do full restarts of the program.
All paths in the Storage API use Unix-style path separators ('/'). Using a different path separator will not work, even if the underlying platform would otherwise accept it. This is to keep code using the Storage API portable between platforms and Storage implementations and simplify app code.
Paths with relative directories ("." and "..") are forbidden by the Storage API.
All valid UTF-8 strings (discounting the nullptr terminator character and the '/' path separator) are usable for filenames, however, an underlying Storage implementation may not support particularly strange sequences and refuse to create files with those names, etc.
using SDL::StorageInterface = typedef SDL_StorageInterface |
Apps that want to supply a custom implementation of Storage will fill in all the functions in this struct, and then pass it to Storage.Open to create a custom Storage object.
It is not usually necessary to do this; SDL provides standard implementations for many things you might expect to do with an Storage.
This structure should be initialized using SDL_INIT_INTERFACE()
using SDL::StorageShared = typedef ResourceShared<Storage> |
using SDL::StorageWeak = typedef ResourceWeak<Storage> |