|
Size: 2908
Comment: update content for consistency - add SDL_GetError() to NULL RVs
|
Size: 2818
Comment: Rewritten
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT|| | |
| Line 6: | Line 5: |
| Use this function to *create a new SDL_RWops structure for reading from and/or writing to a named file*. | Use this function to create a new SDL_RWops structure for reading from and/or writing to a named file. |
| Line 17: | Line 16: |
| ||'''file'''||,,a pointer to ,,^the file containing the information to fill an SDL_RWops structure with^|| ||'''mode'''||,,a pointer to ,,^the mode to be used for/in the SDL_RWops structure^; see [[#Remarks|Remarks]] for details|| <<Color2(green,Are these exceptions to the 'pointer rule'?)>> |
||'''file'''||the filename to open, in UTF-8 encoding|| ||'''mode'''||an ASCII string representing the mode to be used for opening the file; see [[#Remarks|Remarks]] for details|| |
| Line 26: | Line 23: |
| *<<BR>> | |
| Line 28: | Line 24: |
| SDL_RWops *file; SDL_Surface *image; file = SDL_RWFromFile("myimage.bmp", "rb"); image = SDL_LoadBMP_RW(file, 1); // 1 means the file will be automatically closed. // Do something with image here. }}}<<BR>>* |
SDL_RWops *file = SDL_RWFromFile("myimage.bmp", "rb"); SDL_Surface *image = SDL_LoadBMP_RW(file, 1); /* 1 to automatically close the RWops. */ /* Do something with image here. */ }}} |
| Line 38: | Line 30: |
| *<<BR>>The '''mode''' string is treated the same as in a call to the C library's fopen(). | The '''mode''' string is treated roughly the same as in a call to the C library's fopen(), even if SDL doesn't happen to use fopen() behind the scenes. |
| Line 48: | Line 40: |
| NOTE: In order to open a file as a binary file, a "b" character has to be included in the '''mode''' string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file. <<BR>>* | NOTE: In order to open a file as a binary file, a "b" character has to be included in the '''mode''' string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file. Closing the [[SDL_RWops]] will close the file handle SDL is holding internally. |
| Line 51: | Line 45: |
| .[[SDL_RWFromConstMem]] ??? .[[SDL_RWFromFP]] ??? .[[SDL_RWFromMem]] ??? |
.[[SDL_RWFromConstMem]] .[[SDL_RWFromFP]] .[[SDL_RWFromMem]] |
SDL_RWFromFile
Use this function to create a new SDL_RWops structure for reading from and/or writing to a named file.
Contents
Syntax
SDL_RWops* SDL_RWFromFile(const char* file,
const char* mode)
Function Parameters
file |
the filename to open, in UTF-8 encoding |
mode |
an ASCII string representing the mode to be used for opening the file; see Remarks for details |
Return Value
Returns a pointer to the SDL_RWops structure that is created, or NULL on failure; call SDL_GetError() for more information.
Code Examples
SDL_RWops *file = SDL_RWFromFile("myimage.bmp", "rb");
SDL_Surface *image = SDL_LoadBMP_RW(file, 1); /* 1 to automatically close the RWops. */
/* Do something with image here. */
Remarks
The mode string is treated roughly the same as in a call to the C library's fopen(), even if SDL doesn't happen to use fopen() behind the scenes.
Available mode strings:
r |
Open a file for reading. The file must exist. |
w |
Create an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file. |
a |
Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist. |
r+ |
Open a file for update both reading and writing. The file must exist. |
w+ |
Create an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file. |
a+ |
Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous content to be overwritten. You can reposition (fseek, rewind) the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist. |
NOTE: In order to open a file as a binary file, a "b" character has to be included in the mode string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file.
Closing the SDL_RWops will close the file handle SDL is holding internally.
