SDL_RWops

A structure that provides an abstract interface to stream I/O.

Data Fields

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);
}

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.

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":

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 fucntion 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.

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

(write me.)

Related Functions

• SDL_AllocRW

• SDL_RWFromFile

• SDL_RWFromFP

• SDL_RWFromMem

• SDL_RWFromConstMem

• SDL_FreeRW

CategoryStruct, CategoryIO