1SDL::RWOps(3)         User Contributed Perl Documentation        SDL::RWOps(3)
2
3
4

NAME

6       SDL::RWOps -- SDL Bindings to SDL_RWops
7

CATEGORY

9       TODO, Core, Structure
10

SYNOPSIS

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
19         # 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
24         open(FH, "<$file") or die "Can't open file $file";
25         binmode(FH);
26         read(FH, $header, 32); # read 32 bytes of data
27
28         my @blocks = unpack( 'V*', $header ); # unpack the block sizes
29
30         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
40         # ... now do something with the surfaces
41
42       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
52       An example usage would be to put a bunch of resources in a zip file and
53       use Zziplib to access them easily.
54

METHODS

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
62               Mode Strings:
63
64               "r"     Open a file for reading. The file must exist.
65
66               "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
68               "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
70               "r+"    Open a file for update both reading and writing. The file must exist.
71
72               "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
75               "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
78       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
87   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
93       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
97   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
102       Note: If the memory is not writable, use SDL::rw_from_const_mem
103       instead.
104
105   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
109       "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
114   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
119       Note: You must free any memory allocated with SDL::alloc_rw with
120       SDL::free_rw.
121
122   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
127   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
131               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
135       SDL::rw_seek returns the final offset in the data source.
136
137   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
142   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
146          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
151       It returns the number of memory blocks read, or -1 if the read failed.
152
153   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
158          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
163       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
167   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

AUTHORS

173       See "AUTHORS" in SDL.
174
175
176
177perl v5.36.0                      2022-07-22                     SDL::RWOps(3)
Impressum