🛠️🐜 Antkeeper superbuild with dependencies included https://antkeeper.com
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

841 lines
27 KiB

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