SDL_RWops
A structure that provides an abstract interface to stream I/O. Applications can generally ignore the specifics of this structure's internals and treat them as opaque pointers. The details are important to lower-level code that might need to implement one of these, however.
Contents
Data Fields
Sint64 (*)(SDL_RWops *) |
size |
callback that reports stream size; see Remarks |
Sint64 (*)(SDL_RWops *, Sint64, int) |
seek |
callback that seeks in stream; see Remarks |
size_t (*)(SDL_RWops *, void *, size_t, size_t) |
read |
callback that reads from the stream; see Remarks |
size_t (*)(SDL_RWops *, const void *, size_t, size_t) |
write |
callback that writes to the stream; see Remarks |
int (*)(SDL_RWops *) |
close |
callback that closes the stream; see Remarks |
Uint32 |
type |
type of stream; see Remarks |
union |
hidden |
type-specific data; see Remarks |
Code Examples
SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL) {
char name[256];
if (io->read(io, name, sizeof (name), 1) > 0) {
printf("Hello, %s!\n", name);
}
io->close(io);
}
The following is functionally identical to the above example, but uses the recommended macro interface.
SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL) {
char name[256];
if (SDL_RWread(io, name, sizeof (name), 1) > 0) {
printf("Hello, %s!\n", name);
}
SDL_RWclose(io);
}
Remarks
SDL_RWops is an abstraction over I/O. It provides interfaces to read, write and seek data in a stream, without the caller needing to know where the data is coming from.
For example, a RWops might be fed by a memory buffer, or a file on disk, or a connection to a web server, without any changes to how the caller consumes the data.
SDL provides some internal methods for reading from common stream types, like files and memory buffers, but this structure can be used by the application or third party libraries to implement whatever type of stream it pleases.
Most of the fields of this structure are function pointers that are used as callbacks to implement the stream interface. All of them use SDLCALL calling convention.
Please note that many of these function pointers used ints in SDL 1.2; to give them a better range, they have become Sint64 in SDL 2.0.
Applications shouldn't have to care about the internals of this structure. They can treat it as an opaque data pointer and use the SDL_RWread(), SDL_RWwrite(), SDL_RWseek(), SDL_RWtell() and SDL_RWclose() functions on them. Applications almost never create or modify these structures either, instead favoring creation functions like SDL_RWFromFile(), SDL_RWFromMem(), etc.
Third-party libraries and special, low-level code may need to know how to properly implement this struct, however.
Size Function
size is a function pointer that reports the stream's total size in bytes. If the stream size can't be determined (either because it doesn't make sense for the stream type, or there was an error), this function returns -1.
Seek Function
seek is a function pointer that positions the next read/write operation in the stream. This seeks in byte offsets. If the stream can not seek (either because it doesn't make sense for the stream type, or there was an error), this function returns -1, otherwise it returns the new position. Seeking zero bytes from RW_SEEK_CUR is a common way to determine the current stream position.
The final argument works like the standard fseek() "whence":
Identifier |
Value |
Explanation |
RW_SEEK_SET |
0 |
Seek from the beginning of data |
RW_SEEK_CUR |
1 |
Seek relative to current read point |
RW_SEEK_END |
2 |
Seek relative to the end of data |
Read Function
read is a function pointer that reads from the stream. It reads up to num objects each of size bytes into the buffer pointer to by ptr. Returns the number of objects read, which may be less than requested. Returns 0 on error or EOF.
Write Function
write is a function pointer that writes to the stream. It writes exactly num objects each of size bytes from the buffer pointer to by ptr. Returns the number of objects written, which will be less than requested on error.
Close Function
close is a function pointer that cleans up the stream. It should release any resources used by the stream and free the SDL_RWops itself with SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to flush to disk (or whereever). The SDL_RWops is no longer valid after this call, even if flushing the stream failed.
Stream Type
The type field is currently one of these values. An application can usually ignore this information.
Identifier |
Value |
Description |
SDL_RWOPS_UNKNOWN |
0 |
Unknown stream type or application-defined |
SDL_RWOPS_WINFILE |
1 |
Win32 file handle |
SDL_RWOPS_STDFILE |
2 |
stdio.h FILE* |
SDL_RWOPS_JNIFILE |
3 |
Android asset |
SDL_RWOPS_MEMORY |
4 |
Memory stream (read/write) |
SDL_RWOPS_MEMORY_RO |
5 |
Memory stream (read-only) |
Applications and libraries rolling their own RWops implementations should use SDL_RWOPS_UNKNOWN. All other values are currently reserved for SDL's internal use.
Hidden Union
Applications can ignore this union completely. All of the fields in this union are platform-specific and off-limits, used internally by SDL, with one exception. You may use the unknown struct to store your own RWops implementation's data, possibly cleaning it up during the close method. If your data doesn't fit in two pointers, use these pointers to hold an allocated structure that contains the real data.
