pages/SDL-RWOps.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   5 <ul><li><a href="#NAME">NAME</a></li>
   6 <li><a href="#CATEGORY">CATEGORY</a></li>
   7 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
   8 <li><a href="#METHODS">METHODS</a>
   9 <ul><li><a href="#rw_from_file_file_mode">rw_from_file(file,mode) </a></li>
  10 <li><a href="#rw_from_fp_fp_autoclose">rw_from_fp(fp,autoclose)</a></li>
  11 <li><a href="#rw_from_mem_mem_size">rw_from_mem(mem,size)</a></li>
  12 <li><a href="#rw_from_const_mem_mem_size">rw_from_const_mem(mem,size)</a></li>
  13 <li><a href="#alloc_rw">alloc_rw()</a></li>
  14 <li><a href="#free_rw_context">free_rw(context)</a></li>
  15 <li><a href="#rw_seek_ctx_offset_whence">rw_seek(ctx,offset,whence)</a></li>
  16 <li><a href="#rw_tell_ctx">rw_tell(ctx)</a></li>
  17 <li><a href="#rw_read_ctx_ptr_size_n">rw_read(ctx,ptr,size,n)</a></li>
  18 <li><a href="#rw_write_ctx_ptr_size_n">rw_write(ctx,ptr,size,n)</a></li>
  19 <li><a href="#rw_close_ctx">rw_close(ctx)</a></li>
  20 </ul>
  21 </li>
  22 <li><a href="#AUTHORS">AUTHORS</a>
  23 </li>
  24 </ul><hr />
  25 <!-- INDEX END -->
  26
  27 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  28 <div id="NAME_CONTENT">
  29 <p>SDL::RWOps -- SDL Bindings to SDL_RWOPs</p>
  30
  31 </div>
  32 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
  33 <div id="CATEGORY_CONTENT">
  34 <p>TODO, Core, Structure</p>
  35
  36
  37
  38
  39
  40 </div>
  41 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  42 <div id="SYNOPSIS_CONTENT">
  43 <p>use SDL::RW;</p>
  44
  45
  46
  47
  48 <p>SDL::RWOps is an &quot;undocumented&quot; feature of SDL, allowing you to use pointers to memory instead of files (though it can handle files too) for things such as images or samples. The primary advantage of this feature is that many libraries load files from the filesystem themselves, leaving you a bit stuck if you want to implement your own special file access, such as an archive format. Fortunately many libraries, such as SDL_image, provide additional methods designed to read from an SDL_RWops, so that you can provide the data in whatever way you like.</p>
  49 <p>An example usage would be to put a bunch of resources in a zip file and use Zziplib to access them easily.</p>
  50
  51
  52
  53
  54
  55 </div>
  56 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  57 <div id="METHODS_CONTENT">
  58
  59
  60
  61
  62
  63 </div>
  64 <h2 id="rw_from_file_file_mode">rw_from_file(file,mode) </h2>
  65 <div id="rw_from_file_file_mode_CONTENT">
  66 <p>rw_from_file creates a new SDL::RWops structure for reading from and/or writing to a named file.
  67 The mode string is treated the same as in a call to the C library's fopen().
  68 SDL::rw_from_file() returns a SDL::RWops structure on succÃ©s or undef on failure. </p>
  69 <pre>   Mode Strings:
  70
  71         &quot;r&quot;   Open a file for reading. The file must exist.
  72
  73         &quot;w&quot;   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.
  74
  75         &quot;a&quot;   Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
  76
  77         &quot;r+&quot;  Open a file for update both reading and writing. The file must exist.
  78
  79         &quot;w+&quot;  Create an empty file for both reading and writing.
  80                 If a file with the same name already exists its content is erased and the file is treated as a new empty file.
  81
  82         &quot;a+&quot;  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.
  83                 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.
  84
  85
  86
  87
  88 </pre>
  89 <p>NOTE: In order to open a file as a binary file, a &quot;b&quot; character has to be included in the mode string.
  90 This additional &quot;b&quot; character can either be appended at the end of the string (thus making the following compound modes: &quot;rb&quot;, &quot;wb&quot;, &quot;ab&quot;, &quot;r+b&quot;, &quot;w+b&quot;, &quot;a+b&quot;) or be inserted between the letter and the &quot;+&quot; sign for the mixed modes (&quot;rb+&quot;, &quot;wb+&quot;, &quot;ab+&quot;). Additional characters may follow the sequence, although they should have no effect. For example, &quot;t&quot; is sometimes appended to make explicit the file is a text file.</p>
  91
  92
  93
  94
  95
  96
  97
  98
  99 </div>
 100 <h2 id="rw_from_fp_fp_autoclose">rw_from_fp(fp,autoclose)</h2>
 101 <div id="rw_from_fp_fp_autoclose_CONTENT">
 102 <p>SDL::rw_from_fp creates a new SDL::RWops structure from a file pointer, opened with stdio. If autoclose is nonzero, the file will be automatically closed when the SDL::RWops structure is closed.
 103 It returns a SDL::RWops on succÃ©s or undef on error.</p>
 104 <p>Note: This is not available under Win32, since files opened in an application on that platform cannot be used by a dynamically linked library. </p>
 105
 106
 107
 108
 109
 110 </div>
 111 <h2 id="rw_from_mem_mem_size">rw_from_mem(mem,size)</h2>
 112 <div id="rw_from_mem_mem_size_CONTENT">
 113 <p>SDL::rw_from_mem sets up a SDL::RWops struct based on a chunk of memory of a certain size.
 114 It returns a SDL::Rwops on succÃ©s or undef on error. </p>
 115 <p>Note: If the memory is not writable, use SDL::rw_from_const_mem instead. </p>
 116
 117
 118
 119
 120
 121 </div>
 122 <h2 id="rw_from_const_mem_mem_size">rw_from_const_mem(mem,size)</h2>
 123 <div id="rw_from_const_mem_mem_size_CONTENT">
 124 <p>rw_from_const_mem sets up a SDL::RWops struct based on a memory area of a certain size. It assumes the memory area is not writable.
 125 It returns a SDL::RWops on succÃ©s on undef on error.</p>
 126
 127 </div>
 128 <h2 id="alloc_rw">alloc_rw()</h2>
 129 <div id="alloc_rw_CONTENT">
 130 <p>alloc_rw allocates an empty, unpopulated SDL::RWops structure. You must fill out the fields yourself.
 131 It returns a SDL::RWops structure on succÃ©s or undef on error. </p>
 132 <p>Note: You must free any memory allocated with SDL::alloc_rw with SDL::free_rw.</p>
 133
 134
 135
 136
 137
 138 </div>
 139 <h2 id="free_rw_context">free_rw(context)</h2>
 140 <div id="free_rw_context_CONTENT">
 141 <p>SDL::free_rw frees an SDL::RWops structure previously allocated by SDL::alloc_rw. Only use it on memory allocated by SDL::alloc_rw.
 142 It doesn't returns anything.</p>
 143
 144
 145
 146
 147
 148 </div>
 149 <h2 id="rw_seek_ctx_offset_whence">rw_seek(ctx,offset,whence)</h2>
 150 <div id="rw_seek_ctx_offset_whence_CONTENT">
 151 <p>SDL::rw_seek calls the seek function pointer in an SDL::RWOps structure. It takes the same 3 parameters as the function pointer:</p>
 152 <pre>   1. A pointer to an SDL::rwops structure
 153         2. An offset in bytes. This can be a negative value.
 154         3.SEEK_SET, SEEK_CUR, or SEEK_END. SEEK_SET seeks from the beginning of the file, SEEK_CUR from the current position, and SEEK_END from the end of the file.
 155
 156 </pre>
 157 <p>SDL::rw_seek returns the final offset in the data source.</p>
 158
 159 </div>
 160 <h2 id="rw_tell_ctx">rw_tell(ctx)</h2>
 161 <div id="rw_tell_ctx_CONTENT">
 162 <p>SDL::rw_tell performs a do-nothing seek to get the current offset in an SDL::RWOps stream ctx. It takes one parameter, a pointer to an SDL::RWOps structure.
 163 It returns the offset in the stream. </p>
 164
 165 </div>
 166 <h2 id="rw_read_ctx_ptr_size_n">rw_read(ctx,ptr,size,n)</h2>
 167 <div id="rw_read_ctx_ptr_size_n_CONTENT">
 168 <p>SDL_RWread calls the function pointed to by an SDL::RWOps structure's read member. It takes the same 4 parameters as the function pointer:</p>
 169 <pre>   1. A pointer to an SDL::RWOps structure
 170    2. A pointer to an area of memory to read data into
 171    3. The size of each block of memory to read
 172    4. The maxinum number of memory blocks to read(it may read less)
 173
 174 </pre>
 175 <p>It returns the number of memory blocks read, or -1 if the read failed. </p>
 176
 177
 178
 179
 180
 181 </div>
 182 <h2 id="rw_write_ctx_ptr_size_n">rw_write(ctx,ptr,size,n)</h2>
 183 <div id="rw_write_ctx_ptr_size_n_CONTENT">
 184 <p>SDL_RWwrite calls the write function in an SDL::RWOps structure. It takes the same parameters as the write function given in the SDL::RWOps structure:</p>
 185 <pre>   1. A pointer to an SDL::RWOps structure
 186    2. A pointer to an area in memory to read data from
 187    3. The size of the memory blocks to write
 188    4. The exact number of memory blocks to write
 189
 190 </pre>
 191 <p>0n success, it returns the number of memory blocks you told it to write.
 192 If it couldn't write that exact number of blocks, or the write didn't work at all, it returns -1.</p>
 193
 194
 195
 196
 197
 198 </div>
 199 <h2 id="rw_close_ctx">rw_close(ctx)</h2>
 200 <div id="rw_close_ctx_CONTENT">
 201 <p>SDL::rw_close calls the close function in an SDL::RWOps structure. It only takes one parameter, an  SDL::RWOps structure.
 202 Returns 0 on success, -1 on error. </p>
 203
 204 </div>
 205 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 206 <div id="AUTHORS_CONTENT">
 207 <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
 208
 209
 210
 211
 212
 213 </div>
 214 </div>