SDL_RWops

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

Contents

SDL_RWops

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

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

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

(write me.)

Hidden Union