PageRenderTime 31ms CodeModel.GetById 17ms app.highlight 6ms RepoModel.GetById 2ms app.codeStats 0ms

/lib/pods/SDLx/Music.pod

http://github.com/PerlGameDev/SDL
Unknown | 323 lines | 200 code | 123 blank | 0 comment | 0 complexity | 904df4b2372b35a3239b40bdfc1fccf8 MD5 | raw file
  1
  2=head1 NAME
  3
  4SDLx::Music - A powerful, convenient interface to C<SDL::Mixer::Music>
  5
  6=head1 CATEGORY
  7
  8Extension
  9
 10=head1 SYNOPSIS
 11
 12	use SDL;
 13	use SDLx::Music;
 14
 15	my $music = SDLx::Music->new;
 16
 17	#define music data with just a name and file path
 18	$music->data(
 19		fast => 'music/fast.ogg',
 20		slow => 'music/slow.ogg',
 21		magical => 'music/magic/cake.ogg',
 22	);
 23
 24	#define more the long way with a parameter hash
 25	$music->data(
 26		squelch => {
 27			file    => 'music/squelch.ogg',
 28			loops   => 3,
 29			fade_in => 0.5,
 30			volume  => 72,
 31		}
 32		splurge => {
 33			file     => 'music/splurge.ogg',
 34			finished => sub { print 'Splurged!' },
 35		},
 36	);
 37
 38	#instead, do it the short way with the help of defaults
 39
 40	#clobber everything
 41	$music->clear;
 42
 43	#specify the class-wide default for file extension
 44	SDLx::Music->default->ext('.ogg');
 45
 46	#specify the object-wide default for file directory
 47	$music->default->dir('music/');
 48
 49	#redefine squelch and splurge
 50	$music->data(
 51		squelch => {
 52			#file defaults to the data name, so the path becomes
 53			#'music/squelch.ogg', which is what we wanted
 54			loops   => 3,
 55			fade_in => 0.5,
 56			volume  => 72,
 57		}
 58		splurge => {
 59			finished => sub { print 'Splurged!' },
 60		},
 61	);
 62
 63	#and we can redefine the others like this
 64	$music->data_for(
 65		'fast',
 66		'slow',
 67	)->data(
 68		magical => 'magic/cake',
 69	);
 70
 71	#get to that named data
 72	my $splurge = $music->data('splurge');
 73
 74	#and add to/modify it without clobbering existing data
 75	$splurge
 76		->volume(55)
 77		->file('data/' . $splurge->file)
 78	;
 79
 80	#play it once, fading in for 2 seconds
 81	$music->play($splurge, loops => 1, fade_in => 2);
 82	#(it will be loaded automatically and played with its specified params)
 83
 84	sleep 5;
 85
 86	#pause it
 87	$music->pause if $music->playing;
 88
 89	#load everything else
 90	$music->load;
 91
 92	#resume playing it at a lower volume
 93	$music->volume(44);
 94	$music->play;
 95
 96	#get the names for all music
 97	my @names = keys %{ $music->data };
 98
 99	for my $name (@names) {
100		#play it in an infinite loop
101		$music->play($name, loops => 0);
102		warn "Cake!" if $music->playing eq "magical";
103		sleep 10;
104	}
105
106	#fade out the last song
107	$music->fade_out(5);
108
109	sleep 4;
110
111	die "CAKE!" if $music->fading->name eq "magical";
112	
113	sleep 1;
114
115=head1 DESCRIPTION
116
117This class provides a powerful and convenient interface to L<SDL::Mixer::Music>. The main goal was to make music code neater and clearer. Among the things that help this, this class provides class-wide and object-wide defaults and it automatically shares duplicate use of the same files.
118
119The following document is intended for reference. For a more beginner-friendly description of this class, see chapter X of the SDL Perl Manual (when it is written).
120
121B<Please note:> do not mix use of this class with L<SDL::Mixer::Music> if you want everything to work right.
122
123=head1 METHODS
124
125=head2 new
126
127	SDLx::Music->new;
128	#Option arguments showing the default parameters
129	SDLx::Music->new( freq => 44100, format => SDL::Audio::AUDIO_S16SYS, channels => 2, chunksize => 4096);
130
131	
132
133Creates the new music object. Inits audio with a call to L<SDLx::Mixer::init|SDLx::Mixer/init>, if it isn't already (if you want more precise control over what is initialized, make sure you call L<SDLx::Mixer::init|SDLx::Mixer/init> before you call this method). Creates an empty default data object for object-wide defaults. If arguments are supplied, calls L</data> with them to set up any initial data objects. Returns the new music object.
134
135=head2 data
136
137	$music->data;
138	$music->data( $name );
139	$music->data( $data );
140	$music->data( %args );
141
142With no arguments: returns a reference to the data hash. This hash has data names as keys and the associated data objects as values.
143
144With a name: creates the data name if it doesn't already exist. Does this with a call to L<SDLx::Music::Data->new|SDLx::Music::Data/new> with C<name => $name> and puts that new object in the data hash under the key of C<$name>. Returns the data object for that name.
145
146With a hash of arguments: for each pair, and returns a  L<SDLx::Music::Data>. Returns C<$music>.
147
148=head2 data_for
149
150	$music->data_for( @names_or_data_objects );
151
152Calls L</data> repeatedly, passing it one element of the list at a time, to initialise multiple empty names and/or add data objects. Returns C<$music>.
153
154=head2 has_data
155
156	$music->has_data;
157	$music->has_data( $name );
158	$music->has_data( $data );
159
160Without arguments: returns how many data objects the class has.
161
162With a name: returns the data object for C<$name>. If there is no data object for C<$name> it is not created and undef is returned instead.
163
164With a data object: does a (slowish) reverse of the data hash to see if the data object belongs to C<$music>. Returns it or undef.
165
166=head2 default
167
168	$music->default;
169	SDLx::Music->default;
170
171Returns the default data object belonging to C<$music> (created in L</new>), or to the class. See L<SDLx::Music::Data> for information on how defaults work.
172
173=head2 load
174
175	$music->load;
176	$music->load( @names_or_data_objects );
177	SDLx::Music->load( @data_objects );
178
179Without arguments: for every data object belonging to C<$music>, if the data object doesn't already have a L<loaded|SDLx::Music::Data/loaded> file, loads the file named by L<dir|SDLx::Music::Data/dir>, L<file|SDLx::Music::Data/file> and L<ext|SDLx::Music::Data/ext> if it hasn't been loaded already. Sets the data object's L<loaded|SDLx::Music::Data/loaded> parameter to this. Two or more objects that use the same file will use the same loaded file. Reference counting is respected, so if two data objects use the same loaded file it will be removed from memory only after both are destroyed. Returns <$music>.
180
181With arguments: does the same, but only for the names or data objects in the list. If there isn't a data object for any name, it will be created.
182
183=head2 unload
184
185	$music->unload;
186	$music->unload( @names_or_data_objects );
187	SDLx::Music->unload( @data_objects );
188
189Without arguments: clears the L<loaded|SDLx::Music::Data/loaded> parameter for all of the data objects in C<$music>. The loaded file is removed from memory if it loses its last reference to it. Returns <$music>.
190
191With arguments: does the same, but only for the names or data objects in the list. Doesn't create a data object for a name that doesn't exist.
192
193=head2 clear
194
195	$music->clear;
196	$music->clear( @names );
197
198Without arguments: empties C<$music>'s data hash of all of its objects. The objects will be destroyed only if the last reference to them is removed, and no parameters will be cleared if this is not the case. Returns C<$music>.
199
200With arguments: does the same, but only deletes the values of the data hash for the names in the list.
201
202=head2 real_clear
203
204	$music->real_clear;
205	$music->real_clear( @names_or_data_objects );
206	SDLx::Music->real_clear( @data_objects );
207
208The full, brute force version of L</clear>.
209
210Without arguments: empties out the parameters of every data object in C<$music> (including L</unload>ing them) and then removes them from the data hash. This may not remove the objects from memory if there are still remaining references to them, but it is the closest thing to it. Returns C<$music>.
211
212With arguments: does the same, but only clears out the names or data objects in the list.
213
214=head2 play
215
216	$music_or_class->play;
217	$music->play( $name, $params );
218	$music_or_class->play( $data, %params );
219
220Without arguments: resumes any paused music. Returns the object or class.
221
222With arguments: plays the sound found in C<$music>'s C<$name>, or in C<$data> (depending on which is specified). L</load>s it if it needs to be loaded (which in turn creates the name if it needs to be created). The C<%params> are all optional and, if defined, are used instead of the values returned by the data object's parameter methods. The accepted parameters here are:
223
224=over
225
226=item L<loops|SDLx::Music::Data/loops>
227
228Plays the music file C<loops> times. If C<loops> is 0, loops it infinitely.
229
230=item L<fade_in|SDLx::Music::Data/fade_in>
231
232Fades the music in for its first C<fade_in> milliseconds, if C<fade_in> is defined.
233
234=item L<vol|SDLx::Music::Data/vol>
235
236Sets the music volume to C<vol>.
237
238=item L<vol_portion|SDLx::Music::Data/vol_portion>
239
240Multiplies the C<vol> by C<vol_portion> (values from 0 to 1 are encouraged) before setting the volume.
241
242=item L<pos|SDLx::Music::Data/pos>
243
244Sets the music position to C<pos> if C<pos> is defined.
245
246=back
247
248Returns the object or class.
249
250=head2 pause
251
252	$music_or_class->pause;
253
254Pauses any playing music. Returns the object or class.
255
256=head2 stop
257
258	$music_or_class->stop;
259
260Stops any playing music. Returns the object or class.
261
262=head2 last_played
263
264	my $last_played = $music_or_class->last_played;
265
266Returns the data object that was L</play>ed last.
267
268=head2 playing
269
270	my $playing = $music->playing;
271
272If there is something playing, returns the data object that was L</play>ed last. Otherwise, returns undef.
273
274=head2 paused
275
276If there is something paused, returns the data object that was L</play>ed last. Otherwise, returns undef.
277
278=head2 fading
279
280If there is something fading, returns the data object that was L</play>ed last. Otherwise, returns undef.
281
282=head2 volume
283
284	my $volume = $music_or_class->volume;
285	$music_or_class->volume( $volume );
286
287Without arguments: returns the current music volume
288
289With arguments: Sets the music volume to C<$volume>. Returns the object or class.
290
291=head2 fade_out
292
293	$music_or_class->fade_out( $fade_out );
294
295Fades the music out for its next C<fade_in> milliseconds. Returns the object or class.
296
297=head2 rewind
298
299	$music_or_class->rewind;
300
301Rewinds the music to its start. Returns the object or class.
302	
303=head2 pos
304
305	$music_or_class->pos( $pos );
306
307Sets the music position to C<$pos> milliseconds. It does different things for different file types, so see L<SDL::Mixer::Music::set_music_position|SDL::Mixer::Music/set_music_position> for details. Note that this method divides C<$pos> by 1000 to pass it to that function, which uses seconds. Returns the object or class.
308
309=head1 SEE ALSO
310
311L<SDLx::Music::Data>
312L<SDLx::Mixer>
313L<SDL::Mixer::Music>
314L<SDL::Mixer>
315
316=head1 AUTHORS
317
318See L<SDL/AUTHORS>.
319
320=head1 COPYRIGHT & LICENSE
321
322This program is free software; you can redistribute it and/or modify it
323under the same terms as Perl itself.