dep/sdl/include/SDL_rwops.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
   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 /**
  23  *  \file SDL_rwops.h
  24  *
  25  *  This file provides a general interface for SDL to read and write
  26  *  data streams.  It can easily be extended to files, memory, etc.
  27  */
  28
  29 #ifndef SDL_rwops_h_
  30 #define SDL_rwops_h_
  31
  32 #include "SDL_stdinc.h"
  33 #include "SDL_error.h"
  34
  35 #include "begin_code.h"
  36 /* Set up for C function definitions, even when using C++ */
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /* RWops Types */
  42 #define SDL_RWOPS_UNKNOWN   0U  /**< Unknown stream type */
  43 #define SDL_RWOPS_WINFILE   1U  /**< Win32 file */
  44 #define SDL_RWOPS_STDFILE   2U  /**< Stdio file */
  45 #define SDL_RWOPS_JNIFILE   3U  /**< Android asset */
  46 #define SDL_RWOPS_MEMORY    4U  /**< Memory stream */
  47 #define SDL_RWOPS_MEMORY_RO 5U  /**< Read-Only memory stream */
  48
  49 /**
  50  * This is the read/write operation structure -- very basic.
  51  */
  52 typedef struct SDL_RWops
  53 {
  54     /**
  55      *  Return the size of the file in this rwops, or -1 if unknown
  56      */
  57     Sint64 (SDLCALL * size) (struct SDL_RWops * context);
  58
  59     /**
  60      *  Seek to \c offset relative to \c whence, one of stdio's whence values:
  61      *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
  62      *
  63      *  \return the final offset in the data stream, or -1 on error.
  64      */
  65     Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
  66                              int whence);
  67
  68     /**
  69      *  Read up to \c maxnum objects each of size \c size from the data
  70      *  stream to the area pointed at by \c ptr.
  71      *
  72      *  \return the number of objects read, or 0 at error or end of file.
  73      */
  74     size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
  75                              size_t size, size_t maxnum);
  76
  77     /**
  78      *  Write exactly \c num objects each of size \c size from the area
  79      *  pointed at by \c ptr to data stream.
  80      *
  81      *  \return the number of objects written, or 0 at error or end of file.
  82      */
  83     size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
  84                               size_t size, size_t num);
  85
  86     /**
  87      *  Close and free an allocated SDL_RWops structure.
  88      *
  89      *  \return 0 if successful or -1 on write error when flushing data.
  90      */
  91     int (SDLCALL * close) (struct SDL_RWops * context);
  92
  93     Uint32 type;
  94     union
  95     {
  96 #if defined(__ANDROID__)
  97         struct
  98         {
  99             void *asset;
 100         } androidio;
 101 #elif defined(__WIN32__) || defined(__GDK__)
 102         struct
 103         {
 104             SDL_bool append;
 105             void *h;
 106             struct
 107             {
 108                 void *data;
 109                 size_t size;
 110                 size_t left;
 111             } buffer;
 112         } windowsio;
 113 #endif
 114
 115 #ifdef HAVE_STDIO_H
 116         struct
 117         {
 118             SDL_bool autoclose;
 119             FILE *fp;
 120         } stdio;
 121 #endif
 122         struct
 123         {
 124             Uint8 *base;
 125             Uint8 *here;
 126             Uint8 *stop;
 127         } mem;
 128         struct
 129         {
 130             void *data1;
 131             void *data2;
 132         } unknown;
 133     } hidden;
 134
 135 } SDL_RWops;
 136
 137
 138 /**
 139  *  \name RWFrom functions
 140  *
 141  *  Functions to create SDL_RWops structures from various data streams.
 142  */
 143 /* @{ */
 144
 145 /**
 146  * Use this function to create a new SDL_RWops structure for reading from
 147  * and/or writing to a named file.
 148  *
 149  * The `mode` string is treated roughly the same as in a call to the C
 150  * library's fopen(), even if SDL doesn't happen to use fopen() behind the
 151  * scenes.
 152  *
 153  * Available `mode` strings:
 154  *
 155  * - "r": Open a file for reading. The file must exist.
 156  * - "w": Create an empty file for writing. If a file with the same name
 157  *   already exists its content is erased and the file is treated as a new
 158  *   empty file.
 159  * - "a": Append to a file. Writing operations append data at the end of the
 160  *   file. The file is created if it does not exist.
 161  * - "r+": Open a file for update both reading and writing. The file must
 162  *   exist.
 163  * - "w+": Create an empty file for both reading and writing. If a file with
 164  *   the same name already exists its content is erased and the file is
 165  *   treated as a new empty file.
 166  * - "a+": Open a file for reading and appending. All writing operations are
 167  *   performed at the end of the file, protecting the previous content to be
 168  *   overwritten. You can reposition (fseek, rewind) the internal pointer to
 169  *   anywhere in the file for reading, but writing operations will move it
 170  *   back to the end of file. The file is created if it does not exist.
 171  *
 172  * **NOTE**: In order to open a file as a binary file, a "b" character has to
 173  * be included in the `mode` string. This additional "b" character can either
 174  * be appended at the end of the string (thus making the following compound
 175  * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the
 176  * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+").
 177  * Additional characters may follow the sequence, although they should have no
 178  * effect. For example, "t" is sometimes appended to make explicit the file is
 179  * a text file.
 180  *
 181  * This function supports Unicode filenames, but they must be encoded in UTF-8
 182  * format, regardless of the underlying operating system.
 183  *
 184  * As a fallback, SDL_RWFromFile() will transparently open a matching filename
 185  * in an Android app's `assets`.
 186  *
 187  * Closing the SDL_RWops will close the file handle SDL is holding internally.
 188  *
 189  * \param file a UTF-8 string representing the filename to open
 190  * \param mode an ASCII string representing the mode to be used for opening
 191  *             the file.
 192  * \returns a pointer to the SDL_RWops structure that is created, or NULL on
 193  *          failure; call SDL_GetError() for more information.
 194  *
 195  * \since This function is available since SDL 2.0.0.
 196  *
 197  * \sa SDL_RWclose
 198  * \sa SDL_RWFromConstMem
 199  * \sa SDL_RWFromFP
 200  * \sa SDL_RWFromMem
 201  * \sa SDL_RWread
 202  * \sa SDL_RWseek
 203  * \sa SDL_RWtell
 204  * \sa SDL_RWwrite
 205  */
 206 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFile(const char *file,
 207                                                   const char *mode);
 208
 209 #ifdef HAVE_STDIO_H
 210
 211 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose);
 212
 213 #else
 214
 215 /**
 216  * Use this function to create an SDL_RWops structure from a standard I/O file
 217  * pointer (stdio.h's `FILE*`).
 218  *
 219  * This function is not available on Windows, since files opened in an
 220  * application on that platform cannot be used by a dynamically linked
 221  * library.
 222  *
 223  * On some platforms, the first parameter is a `void*`, on others, it's a
 224  * `FILE*`, depending on what system headers are available to SDL. It is
 225  * always intended to be the `FILE*` type from the C runtime's stdio.h.
 226  *
 227  * \param fp the `FILE*` that feeds the SDL_RWops stream
 228  * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops,
 229  *                  SDL_FALSE to leave the `FILE*` open when the RWops is
 230  *                  closed
 231  * \returns a pointer to the SDL_RWops structure that is created, or NULL on
 232  *          failure; call SDL_GetError() for more information.
 233  *
 234  * \since This function is available since SDL 2.0.0.
 235  *
 236  * \sa SDL_RWclose
 237  * \sa SDL_RWFromConstMem
 238  * \sa SDL_RWFromFile
 239  * \sa SDL_RWFromMem
 240  * \sa SDL_RWread
 241  * \sa SDL_RWseek
 242  * \sa SDL_RWtell
 243  * \sa SDL_RWwrite
 244  */
 245 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp,
 246                                                 SDL_bool autoclose);
 247 #endif
 248
 249 /**
 250  * Use this function to prepare a read-write memory buffer for use with
 251  * SDL_RWops.
 252  *
 253  * This function sets up an SDL_RWops struct based on a memory area of a
 254  * certain size, for both read and write access.
 255  *
 256  * This memory buffer is not copied by the RWops; the pointer you provide must
 257  * remain valid until you close the stream. Closing the stream will not free
 258  * the original buffer.
 259  *
 260  * If you need to make sure the RWops never writes to the memory buffer, you
 261  * should use SDL_RWFromConstMem() with a read-only buffer of memory instead.
 262  *
 263  * \param mem a pointer to a buffer to feed an SDL_RWops stream
 264  * \param size the buffer size, in bytes
 265  * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call
 266  *          SDL_GetError() for more information.
 267  *
 268  * \since This function is available since SDL 2.0.0.
 269  *
 270  * \sa SDL_RWclose
 271  * \sa SDL_RWFromConstMem
 272  * \sa SDL_RWFromFile
 273  * \sa SDL_RWFromFP
 274  * \sa SDL_RWFromMem
 275  * \sa SDL_RWread
 276  * \sa SDL_RWseek
 277  * \sa SDL_RWtell
 278  * \sa SDL_RWwrite
 279  */
 280 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size);
 281
 282 /**
 283  * Use this function to prepare a read-only memory buffer for use with RWops.
 284  *
 285  * This function sets up an SDL_RWops struct based on a memory area of a
 286  * certain size. It assumes the memory area is not writable.
 287  *
 288  * Attempting to write to this RWops stream will report an error without
 289  * writing to the memory buffer.
 290  *
 291  * This memory buffer is not copied by the RWops; the pointer you provide must
 292  * remain valid until you close the stream. Closing the stream will not free
 293  * the original buffer.
 294  *
 295  * If you need to write to a memory buffer, you should use SDL_RWFromMem()
 296  * with a writable buffer of memory instead.
 297  *
 298  * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream
 299  * \param size the buffer size, in bytes
 300  * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call
 301  *          SDL_GetError() for more information.
 302  *
 303  * \since This function is available since SDL 2.0.0.
 304  *
 305  * \sa SDL_RWclose
 306  * \sa SDL_RWFromConstMem
 307  * \sa SDL_RWFromFile
 308  * \sa SDL_RWFromFP
 309  * \sa SDL_RWFromMem
 310  * \sa SDL_RWread
 311  * \sa SDL_RWseek
 312  * \sa SDL_RWtell
 313  */
 314 extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromConstMem(const void *mem,
 315                                                       int size);
 316
 317 /* @} *//* RWFrom functions */
 318
 319
 320 /**
 321  * Use this function to allocate an empty, unpopulated SDL_RWops structure.
 322  *
 323  * Applications do not need to use this function unless they are providing
 324  * their own SDL_RWops implementation. If you just need a SDL_RWops to
 325  * read/write a common data source, you should use the built-in
 326  * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc.
 327  *
 328  * You must free the returned pointer with SDL_FreeRW(). Depending on your
 329  * operating system and compiler, there may be a difference between the
 330  * malloc() and free() your program uses and the versions SDL calls
 331  * internally. Trying to mix the two can cause crashing such as segmentation
 332  * faults. Since all SDL_RWops must free themselves when their **close**
 333  * method is called, all SDL_RWops must be allocated through this function, so
 334  * they can all be freed correctly with SDL_FreeRW().
 335  *
 336  * \returns a pointer to the allocated memory on success, or NULL on failure;
 337  *          call SDL_GetError() for more information.
 338  *
 339  * \since This function is available since SDL 2.0.0.
 340  *
 341  * \sa SDL_FreeRW
 342  */
 343 extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void);
 344
 345 /**
 346  * Use this function to free an SDL_RWops structure allocated by
 347  * SDL_AllocRW().
 348  *
 349  * Applications do not need to use this function unless they are providing
 350  * their own SDL_RWops implementation. If you just need a SDL_RWops to
 351  * read/write a common data source, you should use the built-in
 352  * implementations in SDL, like SDL_RWFromFile() or SDL_RWFromMem(), etc, and
 353  * call the **close** method on those SDL_RWops pointers when you are done
 354  * with them.
 355  *
 356  * Only use SDL_FreeRW() on pointers returned by SDL_AllocRW(). The pointer is
 357  * invalid as soon as this function returns. Any extra memory allocated during
 358  * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must
 359  * be responsible for managing that memory in their **close** method.
 360  *
 361  * \param area the SDL_RWops structure to be freed
 362  *
 363  * \since This function is available since SDL 2.0.0.
 364  *
 365  * \sa SDL_AllocRW
 366  */
 367 extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
 368
 369 #define RW_SEEK_SET 0       /**< Seek from the beginning of data */
 370 #define RW_SEEK_CUR 1       /**< Seek relative to current read point */
 371 #define RW_SEEK_END 2       /**< Seek relative to the end of data */
 372
 373 /**
 374  * Use this function to get the size of the data stream in an SDL_RWops.
 375  *
 376  * Prior to SDL 2.0.10, this function was a macro.
 377  *
 378  * \param context the SDL_RWops to get the size of the data stream from
 379  * \returns the size of the data stream in the SDL_RWops on success, -1 if
 380  *          unknown or a negative error code on failure; call SDL_GetError()
 381  *          for more information.
 382  *
 383  * \since This function is available since SDL 2.0.10.
 384  */
 385 extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
 386
 387 /**
 388  * Seek within an SDL_RWops data stream.
 389  *
 390  * This function seeks to byte `offset`, relative to `whence`.
 391  *
 392  * `whence` may be any of the following values:
 393  *
 394  * - `RW_SEEK_SET`: seek from the beginning of data
 395  * - `RW_SEEK_CUR`: seek relative to current read point
 396  * - `RW_SEEK_END`: seek relative to the end of data
 397  *
 398  * If this stream can not seek, it will return -1.
 399  *
 400  * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
 401  * `seek` method appropriately, to simplify application development.
 402  *
 403  * Prior to SDL 2.0.10, this function was a macro.
 404  *
 405  * \param context a pointer to an SDL_RWops structure
 406  * \param offset an offset in bytes, relative to **whence** location; can be
 407  *               negative
 408  * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
 409  * \returns the final offset in the data stream after the seek or -1 on error.
 410  *
 411  * \since This function is available since SDL 2.0.10.
 412  *
 413  * \sa SDL_RWclose
 414  * \sa SDL_RWFromConstMem
 415  * \sa SDL_RWFromFile
 416  * \sa SDL_RWFromFP
 417  * \sa SDL_RWFromMem
 418  * \sa SDL_RWread
 419  * \sa SDL_RWtell
 420  * \sa SDL_RWwrite
 421  */
 422 extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
 423                                           Sint64 offset, int whence);
 424
 425 /**
 426  * Determine the current read/write offset in an SDL_RWops data stream.
 427  *
 428  * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
 429  * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
 430  * application development.
 431  *
 432  * Prior to SDL 2.0.10, this function was a macro.
 433  *
 434  * \param context a SDL_RWops data stream object from which to get the current
 435  *                offset
 436  * \returns the current offset in the stream, or -1 if the information can not
 437  *          be determined.
 438  *
 439  * \since This function is available since SDL 2.0.10.
 440  *
 441  * \sa SDL_RWclose
 442  * \sa SDL_RWFromConstMem
 443  * \sa SDL_RWFromFile
 444  * \sa SDL_RWFromFP
 445  * \sa SDL_RWFromMem
 446  * \sa SDL_RWread
 447  * \sa SDL_RWseek
 448  * \sa SDL_RWwrite
 449  */
 450 extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
 451
 452 /**
 453  * Read from a data source.
 454  *
 455  * This function reads up to `maxnum` objects each of size `size` from the
 456  * data source to the area pointed at by `ptr`. This function may read less
 457  * objects than requested. It will return zero when there has been an error or
 458  * the data stream is completely read.
 459  *
 460  * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
 461  * `read` method appropriately, to simplify application development.
 462  *
 463  * Prior to SDL 2.0.10, this function was a macro.
 464  *
 465  * \param context a pointer to an SDL_RWops structure
 466  * \param ptr a pointer to a buffer to read data into
 467  * \param size the size of each object to read, in bytes
 468  * \param maxnum the maximum number of objects to be read
 469  * \returns the number of objects read, or 0 at error or end of file; call
 470  *          SDL_GetError() for more information.
 471  *
 472  * \since This function is available since SDL 2.0.10.
 473  *
 474  * \sa SDL_RWclose
 475  * \sa SDL_RWFromConstMem
 476  * \sa SDL_RWFromFile
 477  * \sa SDL_RWFromFP
 478  * \sa SDL_RWFromMem
 479  * \sa SDL_RWseek
 480  * \sa SDL_RWwrite
 481  */
 482 extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
 483                                           void *ptr, size_t size,
 484                                           size_t maxnum);
 485
 486 /**
 487  * Write to an SDL_RWops data stream.
 488  *
 489  * This function writes exactly `num` objects each of size `size` from the
 490  * area pointed at by `ptr` to the stream. If this fails for any reason, it'll
 491  * return less than `num` to demonstrate how far the write progressed. On
 492  * success, it returns `num`.
 493  *
 494  * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
 495  * `write` method appropriately, to simplify application development.
 496  *
 497  * Prior to SDL 2.0.10, this function was a macro.
 498  *
 499  * \param context a pointer to an SDL_RWops structure
 500  * \param ptr a pointer to a buffer containing data to write
 501  * \param size the size of an object to write, in bytes
 502  * \param num the number of objects to write
 503  * \returns the number of objects written, which will be less than **num** on
 504  *          error; call SDL_GetError() for more information.
 505  *
 506  * \since This function is available since SDL 2.0.10.
 507  *
 508  * \sa SDL_RWclose
 509  * \sa SDL_RWFromConstMem
 510  * \sa SDL_RWFromFile
 511  * \sa SDL_RWFromFP
 512  * \sa SDL_RWFromMem
 513  * \sa SDL_RWread
 514  * \sa SDL_RWseek
 515  */
 516 extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
 517                                            const void *ptr, size_t size,
 518                                            size_t num);
 519
 520 /**
 521  * Close and free an allocated SDL_RWops structure.
 522  *
 523  * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
 524  * resources used by the stream and frees the SDL_RWops itself with
 525  * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
 526  * flush to its output (e.g. to disk).
 527  *
 528  * Note that if this fails to flush the stream to disk, this function reports
 529  * an error, but the SDL_RWops is still invalid once this function returns.
 530  *
 531  * Prior to SDL 2.0.10, this function was a macro.
 532  *
 533  * \param context SDL_RWops structure to close
 534  * \returns 0 on success or a negative error code on failure; call
 535  *          SDL_GetError() for more information.
 536  *
 537  * \since This function is available since SDL 2.0.10.
 538  *
 539  * \sa SDL_RWFromConstMem
 540  * \sa SDL_RWFromFile
 541  * \sa SDL_RWFromFP
 542  * \sa SDL_RWFromMem
 543  * \sa SDL_RWread
 544  * \sa SDL_RWseek
 545  * \sa SDL_RWwrite
 546  */
 547 extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
 548
 549 /**
 550  * Load all the data from an SDL data stream.
 551  *
 552  * The data is allocated with a zero byte at the end (null terminated) for
 553  * convenience. This extra byte is not included in the value reported via
 554  * `datasize`.
 555  *
 556  * The data should be freed with SDL_free().
 557  *
 558  * \param src the SDL_RWops to read all available data from
 559  * \param datasize if not NULL, will store the number of bytes read
 560  * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
 561  * \returns the data, or NULL if there was an error.
 562  *
 563  * \since This function is available since SDL 2.0.6.
 564  */
 565 extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
 566                                               size_t *datasize,
 567                                               int freesrc);
 568
 569 /**
 570  * Load all the data from a file path.
 571  *
 572  * The data is allocated with a zero byte at the end (null terminated) for
 573  * convenience. This extra byte is not included in the value reported via
 574  * `datasize`.
 575  *
 576  * The data should be freed with SDL_free().
 577  *
 578  * Prior to SDL 2.0.10, this function was a macro wrapping around
 579  * SDL_LoadFile_RW.
 580  *
 581  * \param file the path to read all available data from
 582  * \param datasize if not NULL, will store the number of bytes read
 583  * \returns the data, or NULL if there was an error.
 584  *
 585  * \since This function is available since SDL 2.0.10.
 586  */
 587 extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
 588
 589 /**
 590  *  \name Read endian functions
 591  *
 592  *  Read an item of the specified endianness and return in native format.
 593  */
 594 /* @{ */
 595
 596 /**
 597  * Use this function to read a byte from an SDL_RWops.
 598  *
 599  * \param src the SDL_RWops to read from
 600  * \returns the read byte on success or 0 on failure; call SDL_GetError() for
 601  *          more information.
 602  *
 603  * \since This function is available since SDL 2.0.0.
 604  *
 605  * \sa SDL_WriteU8
 606  */
 607 extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src);
 608
 609 /**
 610  * Use this function to read 16 bits of little-endian data from an SDL_RWops
 611  * and return in native format.
 612  *
 613  * SDL byteswaps the data only if necessary, so the data returned will be in
 614  * the native byte order.
 615  *
 616  * \param src the stream from which to read data
 617  * \returns 16 bits of data in the native byte order of the platform.
 618  *
 619  * \since This function is available since SDL 2.0.0.
 620  *
 621  * \sa SDL_ReadBE16
 622  */
 623 extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src);
 624
 625 /**
 626  * Use this function to read 16 bits of big-endian data from an SDL_RWops and
 627  * return in native format.
 628  *
 629  * SDL byteswaps the data only if necessary, so the data returned will be in
 630  * the native byte order.
 631  *
 632  * \param src the stream from which to read data
 633  * \returns 16 bits of data in the native byte order of the platform.
 634  *
 635  * \since This function is available since SDL 2.0.0.
 636  *
 637  * \sa SDL_ReadLE16
 638  */
 639 extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src);
 640
 641 /**
 642  * Use this function to read 32 bits of little-endian data from an SDL_RWops
 643  * and return in native format.
 644  *
 645  * SDL byteswaps the data only if necessary, so the data returned will be in
 646  * the native byte order.
 647  *
 648  * \param src the stream from which to read data
 649  * \returns 32 bits of data in the native byte order of the platform.
 650  *
 651  * \since This function is available since SDL 2.0.0.
 652  *
 653  * \sa SDL_ReadBE32
 654  */
 655 extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src);
 656
 657 /**
 658  * Use this function to read 32 bits of big-endian data from an SDL_RWops and
 659  * return in native format.
 660  *
 661  * SDL byteswaps the data only if necessary, so the data returned will be in
 662  * the native byte order.
 663  *
 664  * \param src the stream from which to read data
 665  * \returns 32 bits of data in the native byte order of the platform.
 666  *
 667  * \since This function is available since SDL 2.0.0.
 668  *
 669  * \sa SDL_ReadLE32
 670  */
 671 extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src);
 672
 673 /**
 674  * Use this function to read 64 bits of little-endian data from an SDL_RWops
 675  * and return in native format.
 676  *
 677  * SDL byteswaps the data only if necessary, so the data returned will be in
 678  * the native byte order.
 679  *
 680  * \param src the stream from which to read data
 681  * \returns 64 bits of data in the native byte order of the platform.
 682  *
 683  * \since This function is available since SDL 2.0.0.
 684  *
 685  * \sa SDL_ReadBE64
 686  */
 687 extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src);
 688
 689 /**
 690  * Use this function to read 64 bits of big-endian data from an SDL_RWops and
 691  * return in native format.
 692  *
 693  * SDL byteswaps the data only if necessary, so the data returned will be in
 694  * the native byte order.
 695  *
 696  * \param src the stream from which to read data
 697  * \returns 64 bits of data in the native byte order of the platform.
 698  *
 699  * \since This function is available since SDL 2.0.0.
 700  *
 701  * \sa SDL_ReadLE64
 702  */
 703 extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src);
 704 /* @} *//* Read endian functions */
 705
 706 /**
 707  *  \name Write endian functions
 708  *
 709  *  Write an item of native format to the specified endianness.
 710  */
 711 /* @{ */
 712
 713 /**
 714  * Use this function to write a byte to an SDL_RWops.
 715  *
 716  * \param dst the SDL_RWops to write to
 717  * \param value the byte value to write
 718  * \returns 1 on success or 0 on failure; call SDL_GetError() for more
 719  *          information.
 720  *
 721  * \since This function is available since SDL 2.0.0.
 722  *
 723  * \sa SDL_ReadU8
 724  */
 725 extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 value);
 726
 727 /**
 728  * Use this function to write 16 bits in native format to a SDL_RWops as
 729  * little-endian data.
 730  *
 731  * SDL byteswaps the data only if necessary, so the application always
 732  * specifies native format, and the data written will be in little-endian
 733  * format.
 734  *
 735  * \param dst the stream to which data will be written
 736  * \param value the data to be written, in native format
 737  * \returns 1 on successful write, 0 on error.
 738  *
 739  * \since This function is available since SDL 2.0.0.
 740  *
 741  * \sa SDL_WriteBE16
 742  */
 743 extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value);
 744
 745 /**
 746  * Use this function to write 16 bits in native format to a SDL_RWops as
 747  * big-endian data.
 748  *
 749  * SDL byteswaps the data only if necessary, so the application always
 750  * specifies native format, and the data written will be in big-endian format.
 751  *
 752  * \param dst the stream to which data will be written
 753  * \param value the data to be written, in native format
 754  * \returns 1 on successful write, 0 on error.
 755  *
 756  * \since This function is available since SDL 2.0.0.
 757  *
 758  * \sa SDL_WriteLE16
 759  */
 760 extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 value);
 761
 762 /**
 763  * Use this function to write 32 bits in native format to a SDL_RWops as
 764  * little-endian data.
 765  *
 766  * SDL byteswaps the data only if necessary, so the application always
 767  * specifies native format, and the data written will be in little-endian
 768  * format.
 769  *
 770  * \param dst the stream to which data will be written
 771  * \param value the data to be written, in native format
 772  * \returns 1 on successful write, 0 on error.
 773  *
 774  * \since This function is available since SDL 2.0.0.
 775  *
 776  * \sa SDL_WriteBE32
 777  */
 778 extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value);
 779
 780 /**
 781  * Use this function to write 32 bits in native format to a SDL_RWops as
 782  * big-endian data.
 783  *
 784  * SDL byteswaps the data only if necessary, so the application always
 785  * specifies native format, and the data written will be in big-endian format.
 786  *
 787  * \param dst the stream to which data will be written
 788  * \param value the data to be written, in native format
 789  * \returns 1 on successful write, 0 on error.
 790  *
 791  * \since This function is available since SDL 2.0.0.
 792  *
 793  * \sa SDL_WriteLE32
 794  */
 795 extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 value);
 796
 797 /**
 798  * Use this function to write 64 bits in native format to a SDL_RWops as
 799  * little-endian data.
 800  *
 801  * SDL byteswaps the data only if necessary, so the application always
 802  * specifies native format, and the data written will be in little-endian
 803  * format.
 804  *
 805  * \param dst the stream to which data will be written
 806  * \param value the data to be written, in native format
 807  * \returns 1 on successful write, 0 on error.
 808  *
 809  * \since This function is available since SDL 2.0.0.
 810  *
 811  * \sa SDL_WriteBE64
 812  */
 813 extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value);
 814
 815 /**
 816  * Use this function to write 64 bits in native format to a SDL_RWops as
 817  * big-endian data.
 818  *
 819  * SDL byteswaps the data only if necessary, so the application always
 820  * specifies native format, and the data written will be in big-endian format.
 821  *
 822  * \param dst the stream to which data will be written
 823  * \param value the data to be written, in native format
 824  * \returns 1 on successful write, 0 on error.
 825  *
 826  * \since This function is available since SDL 2.0.0.
 827  *
 828  * \sa SDL_WriteLE64
 829  */
 830 extern DECLSPEC size_t SDLCALL SDL_WriteBE64(SDL_RWops * dst, Uint64 value);
 831 /* @} *//* Write endian functions */
 832
 833 /* Ends C function definitions when using C++ */
 834 #ifdef __cplusplus
 835 }
 836 #endif
 837 #include "close_code.h"
 838
 839 #endif /* SDL_rwops_h_ */
 840
 841 /* vi: set ts=4 sw=4 expandtab: */