File I/O Abstraction

SDL provides the RWops interface for reading from and writing to various types of data streams.

class csdl2.SDL_RWops

Provides an abstract interface to stream I/O.

This structure cannot be initiated directly. Instead, use SDL_AllocRW(), SDL_RWFromFile(), SDL_RWFromFP(), SDL_RWFromMem() or SDL_RWFromConstMem() to create an instance of this structure.

Applications shouldn’t have to care about the specifics of this structure. They should treat this as an opaque object and use the SDL_RWsize(), SDL_RWseek(), SDL_RWtell(), SDL_RWread(), SDL_RWwrite() and SDL_RWclose() functions on them.

type

The type of stream. It is currently one of these values, though applications can usually ignore this information:

Identifier Description
SDL_RWOPS_UNKNOWN Unknown stream type or application defined.
SDL_RWOPS_WINFILE Win32 file handle.
SDL_RWOPS_STDFILE stdio FILE*
SDL_RWOPS_JNIFILE Android asset
SDL_RWOPS_MEMORY Memory stream (read/write)
SDL_RWOPS_MEMORY_RO Memory stream (read-only)

Applications and libraries rolling their own implementations should use SDL_RWOPS_UNKNOWN. All other values are currently reserved for SDL’s internal use.

size

A function that reports the stream’s total size in bytes. It must the same function signature as SDL_RWsize().

seek

A function that positions the next read/write operation in the stream. It must have the same function signature as SDL_RWseek().

read

A function that reads from the stream. It must have the same function signature as SDL_RWread().

write

A function that writes to the stream. It must have the same function signature as SDL_RWwrite().

close

A function that cleans up the stream. It must release any resources used by the stream and free the SDL_RWops itself with SDL_FreeRW(). It must have the same function signature as SDL_RWclose().

csdl2.SDL_RWOPS_UNKNOWN

Unknown stream type.

csdl2.SDL_RWOPS_WINFILE

Win32 file.

csdl2.SDL_RWOPS_STDFILE

Stdio file.

csdl2.SDL_RWOPS_JNIFILE

Android asset.

csdl2.SDL_RWOPS_MEMORY

Memory stream.

csdl2.SDL_RWOPS_MEMORY_RO

Read-only memory stream.

csdl2.SDL_RWFromFile(file: str, mode: str) → SDL_RWops

Creates and returns a SDL_RWops structure for reading from and/or writing to the file with name file.

mode is one of the following:

mode Behavior
r Open a file for reading. The file must exist.
w Create an empty file for writing. If a file with the same name already exists, its contents are erased and the file is treated as a new empty file.
a Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
r+ Open a file for both reading and writing. The file must exist.
w+ Create an empty file for both reading and writing. If a file with the same name already exists its contents are erased and the file is treated as a new empty file.
a+ Open a file for reading and appending. All writing operations are performed at the end of the file. You can seek the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of the file. The file is created if it does not exist.
Parameters:
  • file (str) – File path
  • mode (str) – File open mode
Returns:

A new SDL_RWops structure
csdl2.SDL_AllocRW() → SDL_RWops

Allocates a new SDL_RWops structure and returns it.

Applications do not need to use this function unless they are providing their own RWops implementation. You should use the built-in implementations in SDL, like SDL_RWFromFile(), SDL_RWFromMem() etc.

Returns:A new SDL_RWops structure
csdl2.SDL_FreeRW(area: SDL_RWops) → None

Frees the SDL_RWops structure allocated by SDL_AllocRW().

Applications do not need to use this function unless they are providing their own SDL_RWops.close implementation. When using the built-in implementations of SDL_RWops (e.g. through SDL_RWFromFile(), SDL_RWFromMem() etc.), you just need to call SDL_RWclose() with the SDL_RWops object, as the built-in implementations of SDL_RWops.close will call SDL_FreeRW() internally.

Parameters:area (SDL_RWops) – The SDL_RWops structure allocated with SDL_AllocRW().
csdl2.SDL_RWsize(context: SDL_RWops) → int

Returns the size of the data stream in the SDL_RWops.

Parameters:context (SDL_RWops) – The SDL_RWops stream to get the size of.
Returns:Size of the data stream in bytes.
csdl2.SDL_RWseek(context: SDL_RWops, offset: int, whence: int) → int

Seeks to offset relative to whence.

Parameters:
Returns:

New offset, measured in bytes, from the start of the stream.
csdl2.RW_SEEK_SET

Seek from the beginning of data.

csdl2.RW_SEEK_CUR

Seek relative to current read point.

csdl2.RW_SEEK_END

Seek relative to the end of data.

csdl2.SDL_RWread(context: SDL_RWops, ptr: buffer, size: int, maxnum: int) → int

Reads up to maxnum objects, each of size size bytes, from the data source to the buffer ptr.

Parameters:
  • context (SDL_RWops) – Data stream to read from.
  • ptr (buffer) – Buffer to read data into. It must be exactly size * maxnum bytes.
  • size (int) – The size of each object to read, in bytes.
  • maxnum (int) – The maximum number of objects to be read.
Returns:

The number of objects read. This function may read less objects than requested.
csdl2.SDL_RWwrite(context: SDL_RWops, ptr: buffer, size: int, num: int) → int

Writes exactly num objects, each size bytes, from the buffer ptr to the stream.

Parameters:
  • context (SDL_RWops) – Data stream to write to.
  • ptr (buffer) – Buffer containing the data to write to the stream. It must be exactly size * num bytes.
  • size (int) – The size of each object to write, in bytes.
  • maxnum (int) – The number of objects to write.
Returns:

The number of objects written, which can be less than num on error or when the end of file has been reached.
csdl2.SDL_RWclose(context: SDL_RWops) → None

Closes and cleans up the data stream. The SDL_RWops object will be freed.

Parameters:context (SDL_RWops) – Data stream to close.

Note

The SDL_RWops object will still be freed even when an exception occurs while closing the stream.