0
# File I/O and Resource Loading
1

2
File I/O abstraction layer supporting files, memory buffers, and custom data sources through SDL_RWops. This system provides a unified interface for reading and writing data from various sources including files, memory, and network streams.
3

4
## Capabilities
5

6
### RWops Creation
7

8
Functions for creating SDL_RWops objects from different data sources.
9

10
```python { .api }
11
def SDL_RWFromFile(file: bytes, mode: bytes) -> SDL_RWops:
12
    """
13
    Create an SDL_RWops structure from a file.
14
    
15
    Parameters:
16
    - file: file path as bytes
17
    - mode: file mode ("rb", "wb", "ab", etc.) as bytes
18
    
19
    Returns:
20
    SDL_RWops object or None on failure
21
    """
22

23
def SDL_RWFromMem(mem: bytes, size: int) -> SDL_RWops:
24
    """
25
    Create an SDL_RWops structure from a memory buffer (read/write).
26
    
27
    Parameters:
28
    - mem: memory buffer
29
    - size: buffer size in bytes
30
    
31
    Returns:
32
    SDL_RWops object or None on failure
33
    """
34

35
def SDL_RWFromConstMem(mem: bytes, size: int) -> SDL_RWops:
36
    """
37
    Create an SDL_RWops structure from a read-only memory buffer.
38
    
39
    Parameters:
40
    - mem: read-only memory buffer
41
    - size: buffer size in bytes
42
    
43
    Returns:
44
    SDL_RWops object or None on failure
45
    """
46

47
def SDL_AllocRW() -> SDL_RWops:
48
    """Allocate an empty, unpopulated SDL_RWops structure."""
49

50
def SDL_FreeRW(area: SDL_RWops) -> None:
51
    """Free an SDL_RWops structure allocated by SDL_AllocRW."""
52
```
53

54
### File Operations
55

56
Core file I/O operations for reading, writing, and seeking.
57

58
```python { .api }
59
def SDL_RWread(context: SDL_RWops, ptr: bytes, size: int, num: int) -> int:
60
    """
61
    Read from an SDL_RWops data source.
62
    
63
    Parameters:
64
    - context: SDL_RWops to read from
65
    - ptr: buffer to read data into
66
    - size: size of each data element
67
    - num: number of elements to read
68
    
69
    Returns:
70
    Number of elements read (may be less than requested on error/EOF)
71
    """
72

73
def SDL_RWwrite(context: SDL_RWops, ptr: bytes, size: int, num: int) -> int:
74
    """
75
    Write to an SDL_RWops data source.
76
    
77
    Parameters:
78
    - context: SDL_RWops to write to
79
    - ptr: buffer containing data to write
80
    - size: size of each data element  
81
    - num: number of elements to write
82
    
83
    Returns:
84
    Number of elements written
85
    """
86

87
def SDL_RWseek(context: SDL_RWops, offset: int, whence: int) -> int:
88
    """
89
    Seek to a position in an SDL_RWops data source.
90
    
91
    Parameters:
92
    - context: SDL_RWops to seek in
93
    - offset: byte offset from whence position
94
    - whence: seek reference point (RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END)
95
    
96
    Returns:
97
    Final position in data source, or -1 on error
98
    """
99

100
def SDL_RWtell(context: SDL_RWops) -> int:
101
    """Get current position in SDL_RWops data source."""
102

103
def SDL_RWsize(context: SDL_RWops) -> int:
104
    """Get the size of the data source for an SDL_RWops."""
105

106
def SDL_RWclose(context: SDL_RWops) -> int:
107
    """
108
    Close and free an SDL_RWops structure.
109
    
110
    Parameters:
111
    - context: SDL_RWops to close
112
    
113
    Returns:
114
    0 on success, negative on error
115
    """
116
```
117

118
### Endian-Aware Reading
119

120
Functions for reading data with specific byte order handling.
121

122
```python { .api }
123
def SDL_ReadU8(src: SDL_RWops) -> int:
124
    """Read an unsigned 8-bit integer from SDL_RWops."""
125

126
def SDL_ReadLE16(src: SDL_RWops) -> int:
127
    """Read an unsigned 16-bit integer in little-endian format."""
128

129
def SDL_ReadBE16(src: SDL_RWops) -> int:
130
    """Read an unsigned 16-bit integer in big-endian format."""
131

132
def SDL_ReadLE32(src: SDL_RWops) -> int:
133
    """Read an unsigned 32-bit integer in little-endian format."""
134

135
def SDL_ReadBE32(src: SDL_RWops) -> int:
136
    """Read an unsigned 32-bit integer in big-endian format."""
137

138
def SDL_ReadLE64(src: SDL_RWops) -> int:
139
    """Read an unsigned 64-bit integer in little-endian format."""
140

141
def SDL_ReadBE64(src: SDL_RWops) -> int:
142
    """Read an unsigned 64-bit integer in big-endian format."""
143
```
144

145
### Endian-Aware Writing
146

147
Functions for writing data with specific byte order handling.
148

149
```python { .api }
150
def SDL_WriteU8(dst: SDL_RWops, value: int) -> int:
151
    """Write an unsigned 8-bit integer to SDL_RWops."""
152

153
def SDL_WriteLE16(dst: SDL_RWops, value: int) -> int:
154
    """Write an unsigned 16-bit integer in little-endian format."""
155

156
def SDL_WriteBE16(dst: SDL_RWops, value: int) -> int:
157
    """Write an unsigned 16-bit integer in big-endian format."""
158

159
def SDL_WriteLE32(dst: SDL_RWops, value: int) -> int:
160
    """Write an unsigned 32-bit integer in little-endian format."""
161

162
def SDL_WriteBE32(dst: SDL_RWops, value: int) -> int:
163
    """Write an unsigned 32-bit integer in big-endian format."""
164

165
def SDL_WriteLE64(dst: SDL_RWops, value: int) -> int:
166
    """Write an unsigned 64-bit integer in little-endian format."""
167

168
def SDL_WriteBE64(dst: SDL_RWops, value: int) -> int:
169
    """Write an unsigned 64-bit integer in big-endian format."""
170
```
171

172
### Utility Functions
173

174
```python { .api }
175
def SDL_LoadFile_RW(src: SDL_RWops, datasize: int, freesrc: int) -> bytes:
176
    """
177
    Load all data from an SDL_RWops data source.
178
    
179
    Parameters:
180
    - src: SDL_RWops to read from
181
    - datasize: pointer to store data size
182
    - freesrc: if non-zero, src is closed after loading
183
    
184
    Returns:
185
    Loaded data as bytes, or None on error
186
    """
187
```
188

189
### Constants
190

191
```python { .api }
192
# Seek reference points
193
RW_SEEK_SET = 0  # Seek from beginning of data
194
RW_SEEK_CUR = 1  # Seek relative to current position  
195
RW_SEEK_END = 2  # Seek relative to end of data
196

197
# RWops types
198
SDL_RWOPS_UNKNOWN = 0
199
SDL_RWOPS_WINFILE = 1
200
SDL_RWOPS_STDFILE = 2
201
SDL_RWOPS_JNIFILE = 3
202
SDL_RWOPS_MEMORY = 4
203
SDL_RWOPS_MEMORY_RO = 5
204
```
205

206
## Usage Examples
207

208
### Reading from Files
209

210
```python
211
import sdl2
212

213
# Open file for reading
214
rw = sdl2.SDL_RWFromFile(b"data.bin", b"rb")
215
if rw:
216
    # Get file size
217
    file_size = sdl2.SDL_RWsize(rw)
218
    print(f"File size: {file_size} bytes")
219
    
220
    # Read data
221
    buffer = bytearray(file_size)
222
    bytes_read = sdl2.SDL_RWread(rw, buffer, 1, file_size)
223
    
224
    if bytes_read == file_size:
225
        print(f"Successfully read {bytes_read} bytes")
226
    
227
    # Close file
228
    sdl2.SDL_RWclose(rw)
229
```
230

231
### Writing to Files
232

233
```python
234
import sdl2
235

236
# Open file for writing
237
rw = sdl2.SDL_RWFromFile(b"output.bin", b"wb")
238
if rw:
239
    # Write data
240
    data = b"Hello, SDL2!"
241
    bytes_written = sdl2.SDL_RWwrite(rw, data, 1, len(data))
242
    
243
    if bytes_written == len(data):
244
        print(f"Successfully wrote {bytes_written} bytes")
245
    
246
    # Close file
247
    sdl2.SDL_RWclose(rw)
248
```
249

250
### Memory Buffers
251

252
```python
253
import sdl2
254

255
# Create RWops from memory buffer
256
data = b"Sample data in memory"
257
rw = sdl2.SDL_RWFromConstMem(data, len(data))
258

259
if rw:
260
    # Read from memory buffer
261
    buffer = bytearray(10)
262
    bytes_read = sdl2.SDL_RWread(rw, buffer, 1, 10)
263
    
264
    print(f"Read from memory: {buffer[:bytes_read]}")
265
    
266
    # Seek to different position
267
    sdl2.SDL_RWseek(rw, 7, sdl2.RW_SEEK_SET)
268
    
269
    # Read more data
270
    buffer2 = bytearray(4)
271
    bytes_read2 = sdl2.SDL_RWread(rw, buffer2, 1, 4)
272
    print(f"Read after seek: {buffer2[:bytes_read2]}")
273
    
274
    # Close RWops
275
    sdl2.SDL_RWclose(rw)
276
```
277

278
### Endian-Aware Data Reading
279

280
```python
281
import sdl2
282

283
# Open binary file containing numeric data
284
rw = sdl2.SDL_RWFromFile(b"numbers.dat", b"rb")
285
if rw:
286
    # Read various integer types
287
    byte_val = sdl2.SDL_ReadU8(rw)
288
    short_le = sdl2.SDL_ReadLE16(rw)  # Little-endian 16-bit
289
    int_be = sdl2.SDL_ReadBE32(rw)    # Big-endian 32-bit
290
    long_le = sdl2.SDL_ReadLE64(rw)   # Little-endian 64-bit
291
    
292
    print(f"Byte: {byte_val}")
293
    print(f"Short (LE): {short_le}")
294
    print(f"Int (BE): {int_be}")
295
    print(f"Long (LE): {long_le}")
296
    
297
    sdl2.SDL_RWclose(rw)
298
```
299

300
### Loading Complete Files
301

302
```python
303
import sdl2
304
from ctypes import c_size_t, pointer
305

306
# Load entire file into memory
307
rw = sdl2.SDL_RWFromFile(b"config.txt", b"rb")
308
if rw:
309
    # Load all data at once
310
    size = c_size_t()
311
    data = sdl2.SDL_LoadFile_RW(rw, pointer(size), 1)  # 1 = close RWops after loading
312
    
313
    if data:
314
        print(f"Loaded {size.value} bytes")
315
        # Process data...
316
        # Note: Remember to free the data when done
317
```
318

319
## Types
320

321
```python { .api }
322
class SDL_RWops:
323
    """
324
    File I/O abstraction structure for reading/writing data.
325
    
326
    Provides a unified interface for various data sources including
327
    files, memory buffers, and custom data streams.
328
    """
329
```