packages/sdl2.nuget.2.0.22/build/native/include/SDL_rwops.h

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