SDL  2.0
SDL_rwops.h File Reference
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "begin_code.h"
#include "close_code.h"
+ Include dependency graph for SDL_rwops.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_RWops
 

Macros

#define SDL_RWOPS_UNKNOWN   0U
 
#define SDL_RWOPS_WINFILE   1U
 
#define SDL_RWOPS_STDFILE   2U
 
#define SDL_RWOPS_JNIFILE   3U
 
#define SDL_RWOPS_MEMORY   4U
 
#define SDL_RWOPS_MEMORY_RO   5U
 
#define RW_SEEK_SET   0
 
#define RW_SEEK_CUR   1
 
#define RW_SEEK_END   2
 

Functions

SDL_RWopsSDL_AllocRW (void)
 
void SDL_FreeRW (SDL_RWops *area)
 
Sint64 SDL_RWsize (SDL_RWops *context)
 
Sint64 SDL_RWseek (SDL_RWops *context, Sint64 offset, int whence)
 
Sint64 SDL_RWtell (SDL_RWops *context)
 
size_t SDL_RWread (SDL_RWops *context, void *ptr, size_t size, size_t maxnum)
 
size_t SDL_RWwrite (SDL_RWops *context, const void *ptr, size_t size, size_t num)
 
int SDL_RWclose (SDL_RWops *context)
 
void * SDL_LoadFile_RW (SDL_RWops *src, size_t *datasize, int freesrc)
 
void * SDL_LoadFile (const char *file, size_t *datasize)
 
RWFrom functions

Functions to create SDL_RWops structures from various data streams.

SDL_RWopsSDL_RWFromFile (const char *file, const char *mode)
 
SDL_RWopsSDL_RWFromFP (FILE *fp, SDL_bool autoclose)
 
SDL_RWopsSDL_RWFromMem (void *mem, int size)
 
SDL_RWopsSDL_RWFromConstMem (const void *mem, int size)
 
Read endian functions

Read an item of the specified endianness and return in native format.

Uint8 SDL_ReadU8 (SDL_RWops *src)
 
Uint16 SDL_ReadLE16 (SDL_RWops *src)
 
Uint16 SDL_ReadBE16 (SDL_RWops *src)
 
Uint32 SDL_ReadLE32 (SDL_RWops *src)
 
Uint32 SDL_ReadBE32 (SDL_RWops *src)
 
Uint64 SDL_ReadLE64 (SDL_RWops *src)
 
Uint64 SDL_ReadBE64 (SDL_RWops *src)
 
Write endian functions

Write an item of native format to the specified endianness.

size_t SDL_WriteU8 (SDL_RWops *dst, Uint8 value)
 
size_t SDL_WriteLE16 (SDL_RWops *dst, Uint16 value)
 
size_t SDL_WriteBE16 (SDL_RWops *dst, Uint16 value)
 
size_t SDL_WriteLE32 (SDL_RWops *dst, Uint32 value)
 
size_t SDL_WriteBE32 (SDL_RWops *dst, Uint32 value)
 
size_t SDL_WriteLE64 (SDL_RWops *dst, Uint64 value)
 
size_t SDL_WriteBE64 (SDL_RWops *dst, Uint64 value)
 

Detailed Description

This file provides a general interface for SDL to read and write data streams. It can easily be extended to files, memory, etc.

Definition in file SDL_rwops.h.

Macro Definition Documentation

◆ RW_SEEK_CUR

#define RW_SEEK_CUR   1

Seek relative to current read point

Definition at line 181 of file SDL_rwops.h.

◆ RW_SEEK_END

#define RW_SEEK_END   2

Seek relative to the end of data

Definition at line 182 of file SDL_rwops.h.

◆ RW_SEEK_SET

#define RW_SEEK_SET   0

Seek from the beginning of data

Definition at line 180 of file SDL_rwops.h.

◆ SDL_RWOPS_JNIFILE

#define SDL_RWOPS_JNIFILE   3U

Android asset

Definition at line 45 of file SDL_rwops.h.

◆ SDL_RWOPS_MEMORY

#define SDL_RWOPS_MEMORY   4U

Memory stream

Definition at line 46 of file SDL_rwops.h.

◆ SDL_RWOPS_MEMORY_RO

#define SDL_RWOPS_MEMORY_RO   5U

Read-Only memory stream

Definition at line 47 of file SDL_rwops.h.

◆ SDL_RWOPS_STDFILE

#define SDL_RWOPS_STDFILE   2U

Stdio file

Definition at line 44 of file SDL_rwops.h.

◆ SDL_RWOPS_UNKNOWN

#define SDL_RWOPS_UNKNOWN   0U

Unknown stream type

Definition at line 42 of file SDL_rwops.h.

◆ SDL_RWOPS_WINFILE

#define SDL_RWOPS_WINFILE   1U

Win32 file

Definition at line 43 of file SDL_rwops.h.

Function Documentation

◆ SDL_AllocRW()

SDL_RWops* SDL_AllocRW ( void  )

◆ SDL_FreeRW()

void SDL_FreeRW ( SDL_RWops area)

◆ SDL_LoadFile()

void* SDL_LoadFile ( const char *  file,
size_t datasize 
)

Load all the data from a file path.

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

The data should be freed with SDL_free().

Parameters
filethe path to read all available data from
datasizeif not NULL, will store the number of bytes read
Returns
the data, or NULL if there was an error.

◆ SDL_LoadFile_RW()

void* SDL_LoadFile_RW ( SDL_RWops src,
size_t datasize,
int  freesrc 
)

Load all the data from an SDL data stream.

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

The data should be freed with SDL_free().

Parameters
srcthe SDL_RWops to read all available data from
datasizeif not NULL, will store the number of bytes read
freesrcif non-zero, calls SDL_RWclose() on src before returning
Returns
the data, or NULL if there was an error.

◆ SDL_ReadBE16()

Uint16 SDL_ReadBE16 ( SDL_RWops src)

◆ SDL_ReadBE32()

Uint32 SDL_ReadBE32 ( SDL_RWops src)

◆ SDL_ReadBE64()

Uint64 SDL_ReadBE64 ( SDL_RWops src)

◆ SDL_ReadLE16()

Uint16 SDL_ReadLE16 ( SDL_RWops src)

◆ SDL_ReadLE32()

Uint32 SDL_ReadLE32 ( SDL_RWops src)

◆ SDL_ReadLE64()

Uint64 SDL_ReadLE64 ( SDL_RWops src)

◆ SDL_ReadU8()

Uint8 SDL_ReadU8 ( SDL_RWops src)

◆ SDL_RWclose()

int SDL_RWclose ( SDL_RWops context)

Close and free an allocated SDL_RWops structure.

SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any resources used by the stream and frees the SDL_RWops itself with SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream to disk, this function reports an error, but the SDL_RWops is still invalid once this function returns.

SDL_RWclose() is actually a macro that calls the SDL_RWops's close method appropriately, to simplify application development.

Parameters
contextSDL_RWops structure to close
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
See also
SDL_RWFromConstMem
SDL_RWFromFile
SDL_RWFromFP
SDL_RWFromMem
SDL_RWread
SDL_RWseek
SDL_RWwrite

◆ SDL_RWFromConstMem()

SDL_RWops* SDL_RWFromConstMem ( const void *  mem,
int  size 
)

◆ SDL_RWFromFile()

SDL_RWops* SDL_RWFromFile ( const char *  file,
const char *  mode 
)

◆ SDL_RWFromFP()

SDL_RWops* SDL_RWFromFP ( FILE *  fp,
SDL_bool  autoclose 
)

◆ SDL_RWFromMem()

SDL_RWops* SDL_RWFromMem ( void *  mem,
int  size 
)

◆ SDL_RWread()

size_t SDL_RWread ( SDL_RWops context,
void *  ptr,
size_t  size,
size_t  maxnum 
)

Read from a data source.

This function reads up to maxnum objects each of size size from the data source to the area pointed at by ptr. This function may read less objects than requested. It will return zero when there has been an error or the data stream is completely read.

SDL_RWread() is actually a function wrapper that calls the SDL_RWops's read method appropriately, to simplify application development.

Parameters
contexta pointer to an SDL_RWops structure
ptra pointer to a buffer to read data into
sizethe size of each object to read, in bytes
maxnumthe maximum number of objects to be read
Returns
the number of objects read, or 0 at error or end of file; call SDL_GetError() for more information.
See also
SDL_RWclose
SDL_RWFromConstMem
SDL_RWFromFile
SDL_RWFromFP
SDL_RWFromMem
SDL_RWseek
SDL_RWwrite

◆ SDL_RWseek()

Sint64 SDL_RWseek ( SDL_RWops context,
Sint64  offset,
int  whence 
)

Seek within an SDL_RWops data stream.

This function seeks to byte offset, relative to whence.

whence may be any of the following values:

  • RW_SEEK_SET: seek from the beginning of data
  • RW_SEEK_CUR: seek relative to current read point
  • RW_SEEK_END: seek relative to the end of data

If this stream can not seek, it will return -1.

SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's seek method appropriately, to simplify application development.

Parameters
contexta pointer to an SDL_RWops structure
offsetan offset in bytes, relative to whence location; can be negative
whenceany of RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
Returns
the final offset in the data stream after the seek or -1 on error.
See also
SDL_RWclose
SDL_RWFromConstMem
SDL_RWFromFile
SDL_RWFromFP
SDL_RWFromMem
SDL_RWread
SDL_RWtell
SDL_RWwrite

◆ SDL_RWsize()

Sint64 SDL_RWsize ( SDL_RWops context)

Use this macro to get the size of the data stream in an SDL_RWops.

Parameters
contextthe SDL_RWops to get the size of the data stream from
Returns
the size of the data stream in the SDL_RWops on success, -1 if unknown or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.

◆ SDL_RWtell()

Sint64 SDL_RWtell ( SDL_RWops context)

Determine the current read/write offset in an SDL_RWops data stream.

SDL_RWtell is actually a wrapper function that calls the SDL_RWops's seek method, with an offset of 0 bytes from RW_SEEK_CUR, to simplify application development.

Parameters
contexta SDL_RWops data stream object from which to get the current offset
Returns
the current offset in the stream, or -1 if the information can not be determined.
See also
SDL_RWclose
SDL_RWFromConstMem
SDL_RWFromFile
SDL_RWFromFP
SDL_RWFromMem
SDL_RWread
SDL_RWseek
SDL_RWwrite

◆ SDL_RWwrite()

size_t SDL_RWwrite ( SDL_RWops context,
const void *  ptr,
size_t  size,
size_t  num 
)

Write to an SDL_RWops data stream.

This function writes exactly num objects each of size size from the area pointed at by ptr to the stream. If this fails for any reason, it'll return less than num to demonstrate how far the write progressed. On success, it returns num.

SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's write method appropriately, to simplify application development.

Parameters
contexta pointer to an SDL_RWops structure
ptra pointer to a buffer containing data to write
sizethe size of an object to write, in bytes
numthe number of objects to write
Returns
the number of objects written, which will be less than num on error; call SDL_GetError() for more information.
See also
SDL_RWclose
SDL_RWFromConstMem
SDL_RWFromFile
SDL_RWFromFP
SDL_RWFromMem
SDL_RWread
SDL_RWseek

◆ SDL_WriteBE16()

size_t SDL_WriteBE16 ( SDL_RWops dst,
Uint16  value 
)

◆ SDL_WriteBE32()

size_t SDL_WriteBE32 ( SDL_RWops dst,
Uint32  value 
)

◆ SDL_WriteBE64()

size_t SDL_WriteBE64 ( SDL_RWops dst,
Uint64  value 
)

◆ SDL_WriteLE16()

size_t SDL_WriteLE16 ( SDL_RWops dst,
Uint16  value 
)

◆ SDL_WriteLE32()

size_t SDL_WriteLE32 ( SDL_RWops dst,
Uint32  value 
)

◆ SDL_WriteLE64()

size_t SDL_WriteLE64 ( SDL_RWops dst,
Uint64  value 
)

◆ SDL_WriteU8()

size_t SDL_WriteU8 ( SDL_RWops dst,
Uint8  value 
)