Atlas - SDL_iostream.h
Home / ext / SDL / include / SDL3 Lines: 4 | Size: 53548 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2026 Sam Lantinga <[email protected]> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20*/ 21 22/* WIKI CATEGORY: IOStream */ 23 24/** 25 * # CategoryIOStream 26 * 27 * SDL provides an abstract interface for reading and writing data streams. It 28 * offers implementations for files, memory, etc, and the app can provide 29 * their own implementations, too. 30 * 31 * SDL_IOStream is not related to the standard C++ iostream class, other than 32 * both are abstract interfaces to read/write data. 33 */ 34 35#ifndef SDL_iostream_h_ 36#define SDL_iostream_h_ 37 38#include <SDL3/SDL_stdinc.h> 39#include <SDL3/SDL_error.h> 40#include <SDL3/SDL_properties.h> 41 42#include <SDL3/SDL_begin_code.h> 43/* Set up for C function definitions, even when using C++ */ 44#ifdef __cplusplus 45extern "C" { 46#endif 47 48/** 49 * SDL_IOStream status, set by a read or write operation. 50 * 51 * \since This enum is available since SDL 3.2.0. 52 */ 53typedef enum SDL_IOStatus 54{ 55 SDL_IO_STATUS_READY, /**< Everything is ready (no errors and not EOF). */ 56 SDL_IO_STATUS_ERROR, /**< Read or write I/O error */ 57 SDL_IO_STATUS_EOF, /**< End of file */ 58 SDL_IO_STATUS_NOT_READY, /**< Non blocking I/O, not ready */ 59 SDL_IO_STATUS_READONLY, /**< Tried to write a read-only buffer */ 60 SDL_IO_STATUS_WRITEONLY /**< Tried to read a write-only buffer */ 61} SDL_IOStatus; 62 63/** 64 * Possible `whence` values for SDL_IOStream seeking. 65 * 66 * These map to the same "whence" concept that `fseek` or `lseek` use in the 67 * standard C runtime. 68 * 69 * \since This enum is available since SDL 3.2.0. 70 */ 71typedef enum SDL_IOWhence 72{ 73 SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ 74 SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ 75 SDL_IO_SEEK_END /**< Seek relative to the end of data */ 76} SDL_IOWhence; 77 78/** 79 * The function pointers that drive an SDL_IOStream. 80 * 81 * Applications can provide this struct to SDL_OpenIO() to create their own 82 * implementation of SDL_IOStream. This is not necessarily required, as SDL 83 * already offers several common types of I/O streams, via functions like 84 * SDL_IOFromFile() and SDL_IOFromMem(). 85 * 86 * This structure should be initialized using SDL_INIT_INTERFACE() 87 * 88 * \since This struct is available since SDL 3.2.0. 89 * 90 * \sa SDL_INIT_INTERFACE 91 */ 92typedef struct SDL_IOStreamInterface 93{ 94 /* The version of this interface */ 95 Uint32 version; 96 97 /** 98 * Return the number of bytes in this SDL_IOStream 99 * 100 * \return the total size of the data stream, or -1 on error. 101 */ 102 Sint64 (SDLCALL *size)(void *userdata); 103 104 /** 105 * Seek to `offset` relative to `whence`, one of stdio's whence values: 106 * SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END 107 * 108 * \return the final offset in the data stream, or -1 on error. 109 */ 110 Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence); 111 112 /** 113 * Read up to `size` bytes from the data stream to the area pointed 114 * at by `ptr`. `size` will always be > 0. 115 * 116 * On an incomplete read, you should set `*status` to a value from the 117 * SDL_IOStatus enum. You do not have to explicitly set this on 118 * a complete, successful read. 119 * 120 * \return the number of bytes read 121 */ 122 size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status); 123 124 /** 125 * Write exactly `size` bytes from the area pointed at by `ptr` 126 * to data stream. `size` will always be > 0. 127 * 128 * On an incomplete write, you should set `*status` to a value from the 129 * SDL_IOStatus enum. You do not have to explicitly set this on 130 * a complete, successful write. 131 * 132 * \return the number of bytes written 133 */ 134 size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); 135 136 /** 137 * If the stream is buffering, make sure the data is written out. 138 * 139 * On failure, you should set `*status` to a value from the 140 * SDL_IOStatus enum. You do not have to explicitly set this on 141 * a successful flush. 142 * 143 * \return true if successful or false on write error when flushing data. 144 */ 145 bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); 146 147 /** 148 * Close and free any allocated resources. 149 * 150 * This does not guarantee file writes will sync to physical media; they 151 * can be in the system's file cache, waiting to go to disk. 152 * 153 * The SDL_IOStream is still destroyed even if this fails, so clean up anything 154 * even if flushing buffers, etc, returns an error. 155 * 156 * \return true if successful or false on write error when flushing data. 157 */ 158 bool (SDLCALL *close)(void *userdata); 159 160} SDL_IOStreamInterface; 161 162/* Check the size of SDL_IOStreamInterface 163 * 164 * If this assert fails, either the compiler is padding to an unexpected size, 165 * or the interface has been updated and this should be updated to match and 166 * the code using this interface should be updated to handle the old version. 167 */ 168SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, 169 (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || 170 (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); 171 172/** 173 * The read/write operation structure. 174 * 175 * This operates as an opaque handle. There are several APIs to create various 176 * types of I/O streams, or an app can supply an SDL_IOStreamInterface to 177 * SDL_OpenIO() to provide their own stream implementation behind this 178 * struct's abstract interface. 179 * 180 * \since This struct is available since SDL 3.2.0. 181 */ 182typedef struct SDL_IOStream SDL_IOStream; 183 184 185/** 186 * \name IOFrom functions 187 * 188 * Functions to create SDL_IOStream structures from various data streams. 189 */ 190/* @{ */ 191 192/** 193 * Use this function to create a new SDL_IOStream structure for reading from 194 * and/or writing to a named file. 195 * 196 * The `mode` string is treated roughly the same as in a call to the C 197 * library's fopen(), even if SDL doesn't happen to use fopen() behind the 198 * scenes. 199 * 200 * Available `mode` strings: 201 * 202 * - "r": Open a file for reading. The file must exist. 203 * - "w": Create an empty file for writing. If a file with the same name 204 * already exists its content is erased and the file is treated as a new 205 * empty file. 206 * - "wx": Create an empty file for writing. If a file with the same name 207 * already exists, the call fails. 208 * - "a": Append to a file. Writing operations append data at the end of the 209 * file. The file is created if it does not exist. 210 * - "r+": Open a file for update both reading and writing. The file must 211 * exist. 212 * - "w+": Create an empty file for both reading and writing. If a file with 213 * the same name already exists its content is erased and the file is 214 * treated as a new empty file. 215 * - "w+x": Create an empty file for both reading and writing. If a file with 216 * the same name already exists, the call fails. 217 * - "a+": Open a file for reading and appending. All writing operations are 218 * performed at the end of the file, protecting the previous content to be 219 * overwritten. You can reposition (fseek, rewind) the internal pointer to 220 * anywhere in the file for reading, but writing operations will move it 221 * back to the end of file. The file is created if it does not exist. 222 * 223 * **NOTE**: In order to open a file as a binary file, a "b" character has to 224 * be included in the `mode` string. This additional "b" character can either 225 * be appended at the end of the string (thus making the following compound 226 * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the 227 * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). 228 * Additional characters may follow the sequence, although they should have no 229 * effect. For example, "t" is sometimes appended to make explicit the file is 230 * a text file. 231 * 232 * This function supports Unicode filenames, but they must be encoded in UTF-8 233 * format, regardless of the underlying operating system. 234 * 235 * In Android, SDL_IOFromFile() can be used to open content:// URIs. As a 236 * fallback, SDL_IOFromFile() will transparently open a matching filename in 237 * the app's `assets`. 238 * 239 * Closing the SDL_IOStream will close SDL's internal file handle. 240 * 241 * The following properties may be set at creation time by SDL: 242 * 243 * - `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`: a pointer, that can be cast 244 * to a win32 `HANDLE`, that this SDL_IOStream is using to access the 245 * filesystem. If the program isn't running on Windows, or SDL used some 246 * other method to access the filesystem, this property will not be set. 247 * - `SDL_PROP_IOSTREAM_STDIO_FILE_POINTER`: a pointer, that can be cast to a 248 * stdio `FILE *`, that this SDL_IOStream is using to access the filesystem. 249 * If SDL used some other method to access the filesystem, this property 250 * will not be set. PLEASE NOTE that if SDL is using a different C runtime 251 * than your app, trying to use this pointer will almost certainly result in 252 * a crash! This is mostly a problem on Windows; make sure you build SDL and 253 * your app with the same compiler and settings to avoid it. 254 * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this 255 * SDL_IOStream is using to access the filesystem. 256 * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast 257 * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access 258 * the filesystem. If SDL used some other method to access the filesystem, 259 * this property will not be set. 260 * 261 * \param file a UTF-8 string representing the filename to open. 262 * \param mode an ASCII string representing the mode to be used for opening 263 * the file. 264 * \returns a pointer to the SDL_IOStream structure that is created or NULL on 265 * failure; call SDL_GetError() for more information. 266 * 267 * \threadsafety It is safe to call this function from any thread. 268 * 269 * \since This function is available since SDL 3.2.0. 270 * 271 * \sa SDL_CloseIO 272 * \sa SDL_FlushIO 273 * \sa SDL_ReadIO 274 * \sa SDL_SeekIO 275 * \sa SDL_TellIO 276 * \sa SDL_WriteIO 277 */ 278extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, const char *mode); 279 280#define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" 281#define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" 282#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" 283#define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" 284 285/** 286 * Use this function to prepare a read-write memory buffer for use with 287 * SDL_IOStream. 288 * 289 * This function sets up an SDL_IOStream struct based on a memory area of a 290 * certain size, for both read and write access. 291 * 292 * This memory buffer is not copied by the SDL_IOStream; the pointer you 293 * provide must remain valid until you close the stream. 294 * 295 * If you need to make sure the SDL_IOStream never writes to the memory 296 * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of 297 * memory instead. 298 * 299 * The following properties will be set at creation time by SDL: 300 * 301 * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that 302 * was passed to this function. 303 * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter 304 * that was passed to this function. 305 * 306 * Additionally, the following properties are recognized: 307 * 308 * - `SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER`: if this property is set to 309 * a non-NULL value it will be interpreted as a function of SDL_free_func 310 * type and called with the passed `mem` pointer when closing the stream. By 311 * default it is unset, i.e., the memory will not be freed. 312 * 313 * \param mem a pointer to a buffer to feed an SDL_IOStream stream. 314 * \param size the buffer size, in bytes. 315 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call 316 * SDL_GetError() for more information. 317 * 318 * \threadsafety It is safe to call this function from any thread. 319 * 320 * \since This function is available since SDL 3.2.0. 321 * 322 * \sa SDL_IOFromConstMem 323 * \sa SDL_CloseIO 324 * \sa SDL_FlushIO 325 * \sa SDL_ReadIO 326 * \sa SDL_SeekIO 327 * \sa SDL_TellIO 328 * \sa SDL_WriteIO 329 */ 330extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); 331 332#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" 333#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" 334#define SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER "SDL.iostream.memory.free" 335 336/** 337 * Use this function to prepare a read-only memory buffer for use with 338 * SDL_IOStream. 339 * 340 * This function sets up an SDL_IOStream struct based on a memory area of a 341 * certain size. It assumes the memory area is not writable. 342 * 343 * Attempting to write to this SDL_IOStream stream will report an error 344 * without writing to the memory buffer. 345 * 346 * This memory buffer is not copied by the SDL_IOStream; the pointer you 347 * provide must remain valid until you close the stream. 348 * 349 * If you need to write to a memory buffer, you should use SDL_IOFromMem() 350 * with a writable buffer of memory instead. 351 * 352 * The following properties will be set at creation time by SDL: 353 * 354 * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that 355 * was passed to this function. 356 * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter 357 * that was passed to this function. 358 * 359 * Additionally, the following properties are recognized: 360 * 361 * - `SDL_PROP_IOSTREAM_MEMORY_FREE_FUNC_POINTER`: if this property is set to 362 * a non-NULL value it will be interpreted as a function of SDL_free_func 363 * type and called with the passed `mem` pointer when closing the stream. By 364 * default it is unset, i.e., the memory will not be freed. 365 * 366 * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. 367 * \param size the buffer size, in bytes. 368 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call 369 * SDL_GetError() for more information. 370 * 371 * \threadsafety It is safe to call this function from any thread. 372 * 373 * \since This function is available since SDL 3.2.0. 374 * 375 * \sa SDL_IOFromMem 376 * \sa SDL_CloseIO 377 * \sa SDL_ReadIO 378 * \sa SDL_SeekIO 379 * \sa SDL_TellIO 380 */ 381extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, size_t size); 382 383/** 384 * Use this function to create an SDL_IOStream that is backed by dynamically 385 * allocated memory. 386 * 387 * This supports the following properties to provide access to the memory and 388 * control over allocations: 389 * 390 * - `SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER`: a pointer to the internal 391 * memory of the stream. This can be set to NULL to transfer ownership of 392 * the memory to the application, which should free the memory with 393 * SDL_free(). If this is done, the next operation on the stream must be 394 * SDL_CloseIO(). 395 * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in 396 * multiples of this size, defaulting to 1024. 397 * 398 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call 399 * SDL_GetError() for more information. 400 * 401 * \threadsafety It is safe to call this function from any thread. 402 * 403 * \since This function is available since SDL 3.2.0. 404 * 405 * \sa SDL_CloseIO 406 * \sa SDL_ReadIO 407 * \sa SDL_SeekIO 408 * \sa SDL_TellIO 409 * \sa SDL_WriteIO 410 */ 411extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); 412 413#define SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER "SDL.iostream.dynamic.memory" 414#define SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER "SDL.iostream.dynamic.chunksize" 415 416/* @} *//* IOFrom functions */ 417 418 419/** 420 * Create a custom SDL_IOStream. 421 * 422 * Applications do not need to use this function unless they are providing 423 * their own SDL_IOStream implementation. If you just need an SDL_IOStream to 424 * read/write a common data source, you should use the built-in 425 * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. 426 * 427 * This function makes a copy of `iface` and the caller does not need to keep 428 * it around after this call. 429 * 430 * \param iface the interface that implements this SDL_IOStream, initialized 431 * using SDL_INIT_INTERFACE(). 432 * \param userdata the pointer that will be passed to the interface functions. 433 * \returns a pointer to the allocated memory on success or NULL on failure; 434 * call SDL_GetError() for more information. 435 * 436 * \threadsafety It is safe to call this function from any thread. 437 * 438 * \since This function is available since SDL 3.2.0. 439 * 440 * \sa SDL_CloseIO 441 * \sa SDL_INIT_INTERFACE 442 * \sa SDL_IOFromConstMem 443 * \sa SDL_IOFromFile 444 * \sa SDL_IOFromMem 445 */ 446extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata); 447 448/** 449 * Close and free an allocated SDL_IOStream structure. 450 * 451 * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any 452 * resources used by the stream and frees the SDL_IOStream itself. This 453 * returns true on success, or false if the stream failed to flush to its 454 * output (e.g. to disk). 455 * 456 * Note that if this fails to flush the stream for any reason, this function 457 * reports an error, but the SDL_IOStream is still invalid once this function 458 * returns. 459 * 460 * This call flushes any buffered writes to the operating system, but there 461 * are no guarantees that those writes have gone to physical media; they might 462 * be in the OS's file cache, waiting to go to disk later. If it's absolutely 463 * crucial that writes go to disk immediately, so they are definitely stored 464 * even if the power fails before the file cache would have caught up, one 465 * should call SDL_FlushIO() before closing. Note that flushing takes time and 466 * makes the system and your app operate less efficiently, so do so sparingly. 467 * 468 * \param context SDL_IOStream structure to close. 469 * \returns true on success or false on failure; call SDL_GetError() for more 470 * information. 471 * 472 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 473 * 474 * \since This function is available since SDL 3.2.0. 475 * 476 * \sa SDL_OpenIO 477 */ 478extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); 479 480/** 481 * Get the properties associated with an SDL_IOStream. 482 * 483 * \param context a pointer to an SDL_IOStream structure. 484 * \returns a valid property ID on success or 0 on failure; call 485 * SDL_GetError() for more information. 486 * 487 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 488 * 489 * \since This function is available since SDL 3.2.0. 490 */ 491extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); 492 493/** 494 * Query the stream status of an SDL_IOStream. 495 * 496 * This information can be useful to decide if a short read or write was due 497 * to an error, an EOF, or a non-blocking operation that isn't yet ready to 498 * complete. 499 * 500 * An SDL_IOStream's status is only expected to change after a SDL_ReadIO or 501 * SDL_WriteIO call; don't expect it to change if you just call this query 502 * function in a tight loop. 503 * 504 * \param context the SDL_IOStream to query. 505 * \returns an SDL_IOStatus enum with the current state. 506 * 507 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 508 * 509 * \since This function is available since SDL 3.2.0. 510 */ 511extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); 512 513/** 514 * Use this function to get the size of the data stream in an SDL_IOStream. 515 * 516 * \param context the SDL_IOStream to get the size of the data stream from. 517 * \returns the size of the data stream in the SDL_IOStream on success or a 518 * negative error code on failure; call SDL_GetError() for more 519 * information. 520 * 521 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 522 * 523 * \since This function is available since SDL 3.2.0. 524 */ 525extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); 526 527/** 528 * Seek within an SDL_IOStream data stream. 529 * 530 * This function seeks to byte `offset`, relative to `whence`. 531 * 532 * `whence` may be any of the following values: 533 * 534 * - `SDL_IO_SEEK_SET`: seek from the beginning of data 535 * - `SDL_IO_SEEK_CUR`: seek relative to current read point 536 * - `SDL_IO_SEEK_END`: seek relative to the end of data 537 * 538 * If this stream can not seek, it will return -1. 539 * 540 * \param context a pointer to an SDL_IOStream structure. 541 * \param offset an offset in bytes, relative to `whence` location; can be 542 * negative. 543 * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, 544 * `SDL_IO_SEEK_END`. 545 * \returns the final offset in the data stream after the seek or -1 on 546 * failure; call SDL_GetError() for more information. 547 * 548 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 549 * 550 * \since This function is available since SDL 3.2.0. 551 * 552 * \sa SDL_TellIO 553 */ 554extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence); 555 556/** 557 * Determine the current read/write offset in an SDL_IOStream data stream. 558 * 559 * SDL_TellIO is actually a wrapper function that calls the SDL_IOStream's 560 * `seek` method, with an offset of 0 bytes from `SDL_IO_SEEK_CUR`, to 561 * simplify application development. 562 * 563 * \param context an SDL_IOStream data stream object from which to get the 564 * current offset. 565 * \returns the current offset in the stream, or -1 if the information can not 566 * be determined. 567 * 568 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 569 * 570 * \since This function is available since SDL 3.2.0. 571 * 572 * \sa SDL_SeekIO 573 */ 574extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); 575 576/** 577 * Read from a data source. 578 * 579 * This function reads up `size` bytes from the data source to the area 580 * pointed at by `ptr`. This function may read less bytes than requested. 581 * 582 * This function will return zero when the data stream is completely read, and 583 * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and 584 * the stream is not at EOF, SDL_GetIOStatus() will return a different error 585 * value and SDL_GetError() will offer a human-readable message. 586 * 587 * A request for zero bytes on a valid stream will return zero immediately 588 * without accessing the stream, so the stream status (EOF, err, etc) will not 589 * change. 590 * 591 * \param context a pointer to an SDL_IOStream structure. 592 * \param ptr a pointer to a buffer to read data into. 593 * \param size the number of bytes to read from the data source. 594 * \returns the number of bytes read, or 0 on end of file or other failure; 595 * call SDL_GetError() for more information. 596 * 597 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 598 * 599 * \since This function is available since SDL 3.2.0. 600 * 601 * \sa SDL_WriteIO 602 * \sa SDL_GetIOStatus 603 */ 604extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size); 605 606/** 607 * Write to an SDL_IOStream data stream. 608 * 609 * This function writes exactly `size` bytes from the area pointed at by `ptr` 610 * to the stream. If this fails for any reason, it'll return less than `size` 611 * to demonstrate how far the write progressed. On success, it returns `size`. 612 * 613 * On error, this function still attempts to write as much as possible, so it 614 * might return a positive value less than the requested write size. 615 * 616 * The caller can use SDL_GetIOStatus() to determine if the problem is 617 * recoverable, such as a non-blocking write that can simply be retried later, 618 * or a fatal error. 619 * 620 * A request for zero bytes on a valid stream will return zero immediately 621 * without accessing the stream, so the stream status (EOF, err, etc) will not 622 * change. 623 * 624 * \param context a pointer to an SDL_IOStream structure. 625 * \param ptr a pointer to a buffer containing data to write. 626 * \param size the number of bytes to write. 627 * \returns the number of bytes written, which will be less than `size` on 628 * failure; call SDL_GetError() for more information. 629 * 630 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 631 * 632 * \since This function is available since SDL 3.2.0. 633 * 634 * \sa SDL_IOprintf 635 * \sa SDL_ReadIO 636 * \sa SDL_SeekIO 637 * \sa SDL_FlushIO 638 * \sa SDL_GetIOStatus 639 */ 640extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); 641 642/** 643 * Print to an SDL_IOStream data stream. 644 * 645 * This function does formatted printing to the stream. 646 * 647 * \param context a pointer to an SDL_IOStream structure. 648 * \param fmt a printf() style format string. 649 * \param ... additional parameters matching % tokens in the `fmt` string, if 650 * any. 651 * \returns the number of bytes written or 0 on failure; call SDL_GetError() 652 * for more information. 653 * 654 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 655 * 656 * \since This function is available since SDL 3.2.0. 657 * 658 * \sa SDL_IOvprintf 659 * \sa SDL_WriteIO 660 */ 661extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); 662 663/** 664 * Print to an SDL_IOStream data stream. 665 * 666 * This function does formatted printing to the stream. 667 * 668 * \param context a pointer to an SDL_IOStream structure. 669 * \param fmt a printf() style format string. 670 * \param ap a variable argument list. 671 * \returns the number of bytes written or 0 on failure; call SDL_GetError() 672 * for more information. 673 * 674 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 675 * 676 * \since This function is available since SDL 3.2.0. 677 * 678 * \sa SDL_IOprintf 679 * \sa SDL_WriteIO 680 */ 681extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); 682 683/** 684 * Flush any buffered data in the stream. 685 * 686 * This function makes sure that any buffered data is written to the stream. 687 * Normally this isn't necessary but if the stream is a pipe or socket it 688 * guarantees that any pending data is sent. 689 * 690 * \param context SDL_IOStream structure to flush. 691 * \returns true on success or false on failure; call SDL_GetError() for more 692 * information. 693 * 694 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 695 * 696 * \since This function is available since SDL 3.2.0. 697 * 698 * \sa SDL_OpenIO 699 * \sa SDL_WriteIO 700 */ 701extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); 702 703/** 704 * Load all the data from an SDL data stream. 705 * 706 * The data is allocated with a zero byte at the end (null terminated) for 707 * convenience. This extra byte is not included in the value reported via 708 * `datasize`. 709 * 710 * The data should be freed with SDL_free(). 711 * 712 * \param src the SDL_IOStream to read all available data from. 713 * \param datasize a pointer filled in with the number of bytes read, may be 714 * NULL. 715 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even 716 * in the case of an error. 717 * \returns the data or NULL on failure; call SDL_GetError() for more 718 * information. 719 * 720 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 721 * 722 * \since This function is available since SDL 3.2.0. 723 * 724 * \sa SDL_LoadFile 725 * \sa SDL_SaveFile_IO 726 */ 727extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); 728 729/** 730 * Load all the data from a file path. 731 * 732 * The data is allocated with a zero byte at the end (null terminated) for 733 * convenience. This extra byte is not included in the value reported via 734 * `datasize`. 735 * 736 * The data should be freed with SDL_free(). 737 * 738 * \param file the path to read all available data from. 739 * \param datasize if not NULL, will store the number of bytes read. 740 * \returns the data or NULL on failure; call SDL_GetError() for more 741 * information. 742 * 743 * \threadsafety It is safe to call this function from any thread. 744 * 745 * \since This function is available since SDL 3.2.0. 746 * 747 * \sa SDL_LoadFile_IO 748 * \sa SDL_SaveFile 749 */ 750extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); 751 752/** 753 * Save all the data into an SDL data stream. 754 * 755 * \param src the SDL_IOStream to write all data to. 756 * \param data the data to be written. If datasize is 0, may be NULL or a 757 * invalid pointer. 758 * \param datasize the number of bytes to be written. 759 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even 760 * in the case of an error. 761 * \returns true on success or false on failure; call SDL_GetError() for more 762 * information. 763 * 764 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 765 * 766 * \since This function is available since SDL 3.2.0. 767 * 768 * \sa SDL_SaveFile 769 * \sa SDL_LoadFile_IO 770 */ 771extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); 772 773/** 774 * Save all the data into a file path. 775 * 776 * \param file the path to write all available data into. 777 * \param data the data to be written. If datasize is 0, may be NULL or a 778 * invalid pointer. 779 * \param datasize the number of bytes to be written. 780 * \returns true on success or false on failure; call SDL_GetError() for more 781 * information. 782 * 783 * \threadsafety It is safe to call this function from any thread. 784 * 785 * \since This function is available since SDL 3.2.0. 786 * 787 * \sa SDL_SaveFile_IO 788 * \sa SDL_LoadFile 789 */ 790extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); 791 792/** 793 * \name Read endian functions 794 * 795 * Read an item of the specified endianness and return in native format. 796 */ 797/* @{ */ 798 799/** 800 * Use this function to read a byte from an SDL_IOStream. 801 * 802 * This function will return false when the data stream is completely read, 803 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 804 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 805 * error value and SDL_GetError() will offer a human-readable message. 806 * 807 * \param src the SDL_IOStream to read from. 808 * \param value a pointer filled in with the data read. 809 * \returns true on success or false on failure or EOF; call SDL_GetError() 810 * for more information. 811 * 812 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 813 * 814 * \since This function is available since SDL 3.2.0. 815 */ 816extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); 817 818/** 819 * Use this function to read a signed byte from an SDL_IOStream. 820 * 821 * This function will return false when the data stream is completely read, 822 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 823 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 824 * error value and SDL_GetError() will offer a human-readable message. 825 * 826 * \param src the SDL_IOStream to read from. 827 * \param value a pointer filled in with the data read. 828 * \returns true on success or false on failure; call SDL_GetError() for more 829 * information. 830 * 831 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 832 * 833 * \since This function is available since SDL 3.2.0. 834 */ 835extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); 836 837/** 838 * Use this function to read 16 bits of little-endian data from an 839 * SDL_IOStream and return in native format. 840 * 841 * SDL byteswaps the data only if necessary, so the data returned will be in 842 * the native byte order. 843 * 844 * This function will return false when the data stream is completely read, 845 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 846 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 847 * error value and SDL_GetError() will offer a human-readable message. 848 * 849 * \param src the stream from which to read data. 850 * \param value a pointer filled in with the data read. 851 * \returns true on successful read or false on failure; call SDL_GetError() 852 * for more information. 853 * 854 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 855 * 856 * \since This function is available since SDL 3.2.0. 857 */ 858extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); 859 860/** 861 * Use this function to read 16 bits of little-endian data from an 862 * SDL_IOStream and return in native format. 863 * 864 * SDL byteswaps the data only if necessary, so the data returned will be in 865 * the native byte order. 866 * 867 * This function will return false when the data stream is completely read, 868 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 869 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 870 * error value and SDL_GetError() will offer a human-readable message. 871 * 872 * \param src the stream from which to read data. 873 * \param value a pointer filled in with the data read. 874 * \returns true on successful read or false on failure; call SDL_GetError() 875 * for more information. 876 * 877 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 878 * 879 * \since This function is available since SDL 3.2.0. 880 */ 881extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); 882 883/** 884 * Use this function to read 16 bits of big-endian data from an SDL_IOStream 885 * and return in native format. 886 * 887 * SDL byteswaps the data only if necessary, so the data returned will be in 888 * the native byte order. 889 * 890 * This function will return false when the data stream is completely read, 891 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 892 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 893 * error value and SDL_GetError() will offer a human-readable message. 894 * 895 * \param src the stream from which to read data. 896 * \param value a pointer filled in with the data read. 897 * \returns true on successful read or false on failure; call SDL_GetError() 898 * for more information. 899 * 900 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 901 * 902 * \since This function is available since SDL 3.2.0. 903 */ 904extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); 905 906/** 907 * Use this function to read 16 bits of big-endian data from an SDL_IOStream 908 * and return in native format. 909 * 910 * SDL byteswaps the data only if necessary, so the data returned will be in 911 * the native byte order. 912 * 913 * This function will return false when the data stream is completely read, 914 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 915 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 916 * error value and SDL_GetError() will offer a human-readable message. 917 * 918 * \param src the stream from which to read data. 919 * \param value a pointer filled in with the data read. 920 * \returns true on successful read or false on failure; call SDL_GetError() 921 * for more information. 922 * 923 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 924 * 925 * \since This function is available since SDL 3.2.0. 926 */ 927extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); 928 929/** 930 * Use this function to read 32 bits of little-endian data from an 931 * SDL_IOStream and return in native format. 932 * 933 * SDL byteswaps the data only if necessary, so the data returned will be in 934 * the native byte order. 935 * 936 * This function will return false when the data stream is completely read, 937 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 938 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 939 * error value and SDL_GetError() will offer a human-readable message. 940 * 941 * \param src the stream from which to read data. 942 * \param value a pointer filled in with the data read. 943 * \returns true on successful read or false on failure; call SDL_GetError() 944 * for more information. 945 * 946 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 947 * 948 * \since This function is available since SDL 3.2.0. 949 */ 950extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); 951 952/** 953 * Use this function to read 32 bits of little-endian data from an 954 * SDL_IOStream and return in native format. 955 * 956 * SDL byteswaps the data only if necessary, so the data returned will be in 957 * the native byte order. 958 * 959 * This function will return false when the data stream is completely read, 960 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 961 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 962 * error value and SDL_GetError() will offer a human-readable message. 963 * 964 * \param src the stream from which to read data. 965 * \param value a pointer filled in with the data read. 966 * \returns true on successful read or false on failure; call SDL_GetError() 967 * for more information. 968 * 969 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 970 * 971 * \since This function is available since SDL 3.2.0. 972 */ 973extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); 974 975/** 976 * Use this function to read 32 bits of big-endian data from an SDL_IOStream 977 * and return in native format. 978 * 979 * SDL byteswaps the data only if necessary, so the data returned will be in 980 * the native byte order. 981 * 982 * This function will return false when the data stream is completely read, 983 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 984 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 985 * error value and SDL_GetError() will offer a human-readable message. 986 * 987 * \param src the stream from which to read data. 988 * \param value a pointer filled in with the data read. 989 * \returns true on successful read or false on failure; call SDL_GetError() 990 * for more information. 991 * 992 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 993 * 994 * \since This function is available since SDL 3.2.0. 995 */ 996extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); 997 998/** 999 * Use this function to read 32 bits of big-endian data from an SDL_IOStream 1000 * and return in native format. 1001 * 1002 * SDL byteswaps the data only if necessary, so the data returned will be in 1003 * the native byte order. 1004 * 1005 * This function will return false when the data stream is completely read, 1006 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 1007 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 1008 * error value and SDL_GetError() will offer a human-readable message. 1009 * 1010 * \param src the stream from which to read data. 1011 * \param value a pointer filled in with the data read. 1012 * \returns true on successful read or false on failure; call SDL_GetError() 1013 * for more information. 1014 * 1015 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1016 * 1017 * \since This function is available since SDL 3.2.0. 1018 */ 1019extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); 1020 1021/** 1022 * Use this function to read 64 bits of little-endian data from an 1023 * SDL_IOStream and return in native format. 1024 * 1025 * SDL byteswaps the data only if necessary, so the data returned will be in 1026 * the native byte order. 1027 * 1028 * This function will return false when the data stream is completely read, 1029 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 1030 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 1031 * error value and SDL_GetError() will offer a human-readable message. 1032 * 1033 * \param src the stream from which to read data. 1034 * \param value a pointer filled in with the data read. 1035 * \returns true on successful read or false on failure; call SDL_GetError() 1036 * for more information. 1037 * 1038 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1039 * 1040 * \since This function is available since SDL 3.2.0. 1041 */ 1042extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); 1043 1044/** 1045 * Use this function to read 64 bits of little-endian data from an 1046 * SDL_IOStream and return in native format. 1047 * 1048 * SDL byteswaps the data only if necessary, so the data returned will be in 1049 * the native byte order. 1050 * 1051 * This function will return false when the data stream is completely read, 1052 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 1053 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 1054 * error value and SDL_GetError() will offer a human-readable message. 1055 * 1056 * \param src the stream from which to read data. 1057 * \param value a pointer filled in with the data read. 1058 * \returns true on successful read or false on failure; call SDL_GetError() 1059 * for more information. 1060 * 1061 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1062 * 1063 * \since This function is available since SDL 3.2.0. 1064 */ 1065extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); 1066 1067/** 1068 * Use this function to read 64 bits of big-endian data from an SDL_IOStream 1069 * and return in native format. 1070 * 1071 * SDL byteswaps the data only if necessary, so the data returned will be in 1072 * the native byte order. 1073 * 1074 * This function will return false when the data stream is completely read, 1075 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 1076 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 1077 * error value and SDL_GetError() will offer a human-readable message. 1078 * 1079 * \param src the stream from which to read data. 1080 * \param value a pointer filled in with the data read. 1081 * \returns true on successful read or false on failure; call SDL_GetError() 1082 * for more information. 1083 * 1084 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1085 * 1086 * \since This function is available since SDL 3.2.0. 1087 */ 1088extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); 1089 1090/** 1091 * Use this function to read 64 bits of big-endian data from an SDL_IOStream 1092 * and return in native format. 1093 * 1094 * SDL byteswaps the data only if necessary, so the data returned will be in 1095 * the native byte order. 1096 * 1097 * This function will return false when the data stream is completely read, 1098 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned 1099 * and the stream is not at EOF, SDL_GetIOStatus() will return a different 1100 * error value and SDL_GetError() will offer a human-readable message. 1101 * 1102 * \param src the stream from which to read data. 1103 * \param value a pointer filled in with the data read. 1104 * \returns true on successful read or false on failure; call SDL_GetError() 1105 * for more information. 1106 * 1107 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1108 * 1109 * \since This function is available since SDL 3.2.0. 1110 */ 1111extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); 1112/* @} *//* Read endian functions */ 1113 1114/** 1115 * \name Write endian functions 1116 * 1117 * Write an item of native format to the specified endianness. 1118 */ 1119/* @{ */ 1120 1121/** 1122 * Use this function to write a byte to an SDL_IOStream. 1123 * 1124 * \param dst the SDL_IOStream to write to. 1125 * \param value the byte value to write. 1126 * \returns true on successful write or false on failure; call SDL_GetError() 1127 * for more information. 1128 * 1129 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1130 * 1131 * \since This function is available since SDL 3.2.0. 1132 */ 1133extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); 1134 1135/** 1136 * Use this function to write a signed byte to an SDL_IOStream. 1137 * 1138 * \param dst the SDL_IOStream to write to. 1139 * \param value the byte value to write. 1140 * \returns true on successful write or false on failure; call SDL_GetError() 1141 * for more information. 1142 * 1143 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1144 * 1145 * \since This function is available since SDL 3.2.0. 1146 */ 1147extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); 1148 1149/** 1150 * Use this function to write 16 bits in native format to an SDL_IOStream as 1151 * little-endian data. 1152 * 1153 * SDL byteswaps the data only if necessary, so the application always 1154 * specifies native format, and the data written will be in little-endian 1155 * format. 1156 * 1157 * \param dst the stream to which data will be written. 1158 * \param value the data to be written, in native format. 1159 * \returns true on successful write or false on failure; call SDL_GetError() 1160 * for more information. 1161 * 1162 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1163 * 1164 * \since This function is available since SDL 3.2.0. 1165 */ 1166extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); 1167 1168/** 1169 * Use this function to write 16 bits in native format to an SDL_IOStream as 1170 * little-endian data. 1171 * 1172 * SDL byteswaps the data only if necessary, so the application always 1173 * specifies native format, and the data written will be in little-endian 1174 * format. 1175 * 1176 * \param dst the stream to which data will be written. 1177 * \param value the data to be written, in native format. 1178 * \returns true on successful write or false on failure; call SDL_GetError() 1179 * for more information. 1180 * 1181 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1182 * 1183 * \since This function is available since SDL 3.2.0. 1184 */ 1185extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); 1186 1187/** 1188 * Use this function to write 16 bits in native format to an SDL_IOStream as 1189 * big-endian data. 1190 * 1191 * SDL byteswaps the data only if necessary, so the application always 1192 * specifies native format, and the data written will be in big-endian format. 1193 * 1194 * \param dst the stream to which data will be written. 1195 * \param value the data to be written, in native format. 1196 * \returns true on successful write or false on failure; call SDL_GetError() 1197 * for more information. 1198 * 1199 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1200 * 1201 * \since This function is available since SDL 3.2.0. 1202 */ 1203extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); 1204 1205/** 1206 * Use this function to write 16 bits in native format to an SDL_IOStream as 1207 * big-endian data. 1208 * 1209 * SDL byteswaps the data only if necessary, so the application always 1210 * specifies native format, and the data written will be in big-endian format. 1211 * 1212 * \param dst the stream to which data will be written. 1213 * \param value the data to be written, in native format. 1214 * \returns true on successful write or false on failure; call SDL_GetError() 1215 * for more information. 1216 * 1217 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1218 * 1219 * \since This function is available since SDL 3.2.0. 1220 */ 1221extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); 1222 1223/** 1224 * Use this function to write 32 bits in native format to an SDL_IOStream as 1225 * little-endian data. 1226 * 1227 * SDL byteswaps the data only if necessary, so the application always 1228 * specifies native format, and the data written will be in little-endian 1229 * format. 1230 * 1231 * \param dst the stream to which data will be written. 1232 * \param value the data to be written, in native format. 1233 * \returns true on successful write or false on failure; call SDL_GetError() 1234 * for more information. 1235 * 1236 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1237 * 1238 * \since This function is available since SDL 3.2.0. 1239 */ 1240extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); 1241 1242/** 1243 * Use this function to write 32 bits in native format to an SDL_IOStream as 1244 * little-endian data. 1245 * 1246 * SDL byteswaps the data only if necessary, so the application always 1247 * specifies native format, and the data written will be in little-endian 1248 * format. 1249 * 1250 * \param dst the stream to which data will be written. 1251 * \param value the data to be written, in native format. 1252 * \returns true on successful write or false on failure; call SDL_GetError() 1253 * for more information. 1254 * 1255 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1256 * 1257 * \since This function is available since SDL 3.2.0. 1258 */ 1259extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); 1260 1261/** 1262 * Use this function to write 32 bits in native format to an SDL_IOStream as 1263 * big-endian data. 1264 * 1265 * SDL byteswaps the data only if necessary, so the application always 1266 * specifies native format, and the data written will be in big-endian format. 1267 * 1268 * \param dst the stream to which data will be written. 1269 * \param value the data to be written, in native format. 1270 * \returns true on successful write or false on failure; call SDL_GetError() 1271 * for more information. 1272 * 1273 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1274 * 1275 * \since This function is available since SDL 3.2.0. 1276 */ 1277extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); 1278 1279/** 1280 * Use this function to write 32 bits in native format to an SDL_IOStream as 1281 * big-endian data. 1282 * 1283 * SDL byteswaps the data only if necessary, so the application always 1284 * specifies native format, and the data written will be in big-endian format. 1285 * 1286 * \param dst the stream to which data will be written. 1287 * \param value the data to be written, in native format. 1288 * \returns true on successful write or false on failure; call SDL_GetError() 1289 * for more information. 1290 * 1291 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1292 * 1293 * \since This function is available since SDL 3.2.0. 1294 */ 1295extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); 1296 1297/** 1298 * Use this function to write 64 bits in native format to an SDL_IOStream as 1299 * little-endian data. 1300 * 1301 * SDL byteswaps the data only if necessary, so the application always 1302 * specifies native format, and the data written will be in little-endian 1303 * format. 1304 * 1305 * \param dst the stream to which data will be written. 1306 * \param value the data to be written, in native format. 1307 * \returns true on successful write or false on failure; call SDL_GetError() 1308 * for more information. 1309 * 1310 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1311 * 1312 * \since This function is available since SDL 3.2.0. 1313 */ 1314extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); 1315 1316/** 1317 * Use this function to write 64 bits in native format to an SDL_IOStream as 1318 * little-endian data. 1319 * 1320 * SDL byteswaps the data only if necessary, so the application always 1321 * specifies native format, and the data written will be in little-endian 1322 * format. 1323 * 1324 * \param dst the stream to which data will be written. 1325 * \param value the data to be written, in native format. 1326 * \returns true on successful write or false on failure; call SDL_GetError() 1327 * for more information. 1328 * 1329 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1330 * 1331 * \since This function is available since SDL 3.2.0. 1332 */ 1333extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); 1334 1335/** 1336 * Use this function to write 64 bits in native format to an SDL_IOStream as 1337 * big-endian data. 1338 * 1339 * SDL byteswaps the data only if necessary, so the application always 1340 * specifies native format, and the data written will be in big-endian format. 1341 * 1342 * \param dst the stream to which data will be written. 1343 * \param value the data to be written, in native format. 1344 * \returns true on successful write or false on failure; call SDL_GetError() 1345 * for more information. 1346 * 1347 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1348 * 1349 * \since This function is available since SDL 3.2.0. 1350 */ 1351extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); 1352 1353/** 1354 * Use this function to write 64 bits in native format to an SDL_IOStream as 1355 * big-endian data. 1356 * 1357 * SDL byteswaps the data only if necessary, so the application always 1358 * specifies native format, and the data written will be in big-endian format. 1359 * 1360 * \param dst the stream to which data will be written. 1361 * \param value the data to be written, in native format. 1362 * \returns true on successful write or false on failure; call SDL_GetError() 1363 * for more information. 1364 * 1365 * \threadsafety Do not use the same SDL_IOStream from two threads at once. 1366 * 1367 * \since This function is available since SDL 3.2.0. 1368 */ 1369extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); 1370 1371/* @} *//* Write endian functions */ 1372 1373/* Ends C function definitions when using C++ */ 1374#ifdef __cplusplus 1375} 1376#endif 1377#include <SDL3/SDL_close_code.h> 1378 1379#endif /* SDL_iostream_h_ */ 1380[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.