1SDL::RWOps(3) User Contributed Perl Documentation SDL::RWOps(3)
2
6 SDL::RWOps -- SDL Bindings to SDL_RWops
7
9 TODO, Core, Structure
10
12 # The following example will load several png's from a single file to an array of SDL::Surface's.
13 # Useful for e.g. levelfiles.
14 use SDL;
15 use SDL::Image;
16 use SDL::RWOps;
17 use SDL::Surface;
18 # the file contains a 32-byte header with lengths of data blocks, followed by the data blocks itself
20 my $file = '/path/to/file/containing_image_data.dat';
21 my $header = ''; # up to eight 32-bit integers specifying the length of the data blocks (images)
22 my @images = ''; # we push the surfaces to that array later
23 open(FH, "<$file") or die "Can't open file $file";
25 binmode(FH);
26 read(FH, $header, 32); # read 32 bytes of data
27 my @blocks = unpack( 'V*', $header ); # unpack the block sizes
29 foreach my $block_size (@blocks) {
31 if($block_size) {
32 my $image = '';
33 read(FH, $image, $block_size);
34 my $rw = SDL::RWOps->new_const_mem( $image );
35 push(@images, SDL::Image::load_PNG_rw( $rw );
36 }
37 }
38 close(FH);
39 # ... now do something with the surfaces
41 SDL::RWOps is an "undocumented" feature of SDL, allowing you to use
43 pointers to memory instead of files (though it can handle files too)
44 for things such as images or samples. The primary advantage of this
45 feature is that many libraries load files from the filesystem
46 themselves, leaving you a bit stuck if you want to implement your own
47 special file access, such as an archive format. Fortunately many
48 libraries, such as SDL_image, provide additional methods designed to
49 read from an SDL_RWops, so that you can provide the data in whatever
50 way you like.
51 An example usage would be to put a bunch of resources in a zip file and
53 use Zziplib to access them easily.
54
56 rw_from_file(file,mode)
57 rw_from_file creates a new SDL::RWOps structure for reading from and/or
58 writing to a named file. The mode string is treated the same as in a
59 call to the C library's fopen(). SDL::rw_from_file() returns a
60 SDL::RWOps structure on success or undef on failure.
61 Mode Strings:
63 "r" Open a file for reading. The file must exist.
65 "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.
67 "a" Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
69 "r+" Open a file for update both reading and writing. The file must exist.
71 "w+" Create an empty file for both reading and writing.
73 If a file with the same name already exists its content is erased and the file is treated as a new empty file.
74 "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.
76 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.
77 NOTE: In order to open a file as a binary file, a "b" character has to
79 be included in the mode string. This additional "b" character can
80 either be appended at the end of the string (thus making the following
81 compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted
82 between the letter and the "+" sign for the mixed modes ("rb+", "wb+",
83 "ab+"). Additional characters may follow the sequence, although they
84 should have no effect. For example, "t" is sometimes appended to make
85 explicit the file is a text file.
86 rw_from_fp(fp,autoclose)
88 SDL::rw_from_fp creates a new SDL::RWOps structure from a file pointer,
89 opened with stdio. If autoclose is nonzero, the file will be
90 automatically closed when the SDL::RWOps structure is closed. It
91 returns a SDL::RWOps on success or undef on error.
92 Note: This is not available under Win32, since files opened in an
94 application on that platform cannot be used by a dynamically linked
95 library.
96 rw_from_mem(mem,size)
98 SDL::rw_from_mem sets up a SDL::RWOps struct based on a chunk of memory
99 of a certain size. It returns a SDL::RWOps on success or undef on
100 error.
101 Note: If the memory is not writable, use SDL::rw_from_const_mem
103 instead.
104 from_const_mem
106 my $rw = SDL::RWOps->from_const_mem( $image_data );
107 my $rw = SDL::RWOps->from_const_mem( $image_data, $size );
108 "from_const_mem" sets up a SDL::RWOps object based on a memory area of
110 a certain size. The $size parameter is optional. It assumes the memory
111 area is not writable. It returns a SDL::RWOps on success or undef on
112 error.
113 alloc_rw()
115 alloc_rw allocates an empty, unpopulated SDL::RWOps structure. You must
116 fill out the fields yourself. It returns a SDL::RWOps structure on
117 success or undef on error.
118 Note: You must free any memory allocated with SDL::alloc_rw with
120 SDL::free_rw.
121 free_rw(context)
123 SDL::free_rw frees an SDL::RWOps structure previously allocated by
124 SDL::alloc_rw. Only use it on memory allocated by SDL::alloc_rw. It
125 doesn't returns anything.
126 rw_seek(ctx,offset,whence)
128 SDL::rw_seek calls the seek function pointer in an SDL::RWOps
129 structure. It takes the same 3 parameters as the function pointer:
130 1. A pointer to an SDL::RWOps structure
132 2. An offset in bytes. This can be a negative value.
133 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.
134 SDL::rw_seek returns the final offset in the data source.
136 rw_tell(ctx)
138 SDL::rw_tell performs a do-nothing seek to get the current offset in an
139 SDL::RWOps stream ctx. It takes one parameter, a pointer to an
140 SDL::RWOps structure. It returns the offset in the stream.
141 rw_read(ctx,ptr,size,n)
143 SDL_RWread calls the function pointed to by an SDL::RWOps structure's
144 read member. It takes the same 4 parameters as the function pointer:
145 1. A pointer to an SDL::RWOps structure
147 2. A pointer to an area of memory to read data into
148 3. The size of each block of memory to read
149 4. The maximum number of memory blocks to read(it may read less)
150 It returns the number of memory blocks read, or -1 if the read failed.
152 rw_write(ctx,ptr,size,n)
154 SDL_RWwrite calls the write function in an SDL::RWOps structure. It
155 takes the same parameters as the write function given in the SDL::RWOps
156 structure:
157 1. A pointer to an SDL::RWOps structure
159 2. A pointer to an area in memory to read data from
160 3. The size of the memory blocks to write
161 4. The exact number of memory blocks to write
162 0n success, it returns the number of memory blocks you told it to
164 write. If it couldn't write that exact number of blocks, or the write
165 didn't work at all, it returns -1.
166 rw_close(ctx)
168 SDL::rw_close calls the close function in an SDL::RWOps structure. It
169 only takes one parameter, an SDL::RWOps structure. Returns 0 on
170 success, -1 on error.
171
173 See "AUTHORS" in SDL.
174perl v5.34.0 2021-07-22 SDL::RWOps(3)