Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pods::SDLx::Music(3)  User Contributed Perl Documentation pods::SDLx::Music(3)

NAME
       SDLx::Music - A powerful, convenient interface to "SDL::Mixer::Music"

CATEGORY
       Extension

SYNOPSIS
	       use SDL;
	       use SDLx::Music;

	       my $music = SDLx::Music->new;

	       #define music data with just a name and file path
	       $music->data(
		       fast => 'music/fast.ogg',
		       slow => 'music/slow.ogg',
		       magical => 'music/magic/cake.ogg',
	       );

	       #define more the	long way with a	parameter hash
	       $music->data(
		       squelch => {
			       file    => 'music/squelch.ogg',
			       loops   => 3,
			       fade_in => 0.5,
			       volume  => 72,
		       }
		       splurge => {
			       file	=> 'music/splurge.ogg',
			       finished	=> sub { print 'Splurged!' },
		       },
	       );

	       #instead, do it the short way with the help of defaults

	       #clobber	everything
	       $music->clear;

	       #specify	the class-wide default for file	extension
	       SDLx::Music->default->ext('.ogg');

	       #specify	the object-wide	default	for file directory
	       $music->default->dir('music/');

	       #redefine squelch and splurge
	       $music->data(
		       squelch => {
			       #file defaults to the data name,	so the path becomes
			       #'music/squelch.ogg', which is what we wanted
			       loops   => 3,
			       fade_in => 0.5,
			       volume  => 72,
		       }
		       splurge => {
			       finished	=> sub { print 'Splurged!' },
		       },
	       );

	       #and we can redefine the	others like this
	       $music->data_for(
		       'fast',
		       'slow',
	       )->data(
		       magical => 'magic/cake',
	       );

	       #get to that named data
	       my $splurge = $music->data('splurge');

	       #and add	to/modify it without clobbering	existing data
	       $splurge
		       ->volume(55)
		       ->file('data/' .	$splurge->file)
	       ;

	       #play it	once, fading in	for 2 seconds
	       $music->play($splurge, loops => 1, fade_in => 2);
	       #(it will be loaded automatically and played with its specified params)

	       sleep 5;

	       #pause it
	       $music->pause if	$music->playing;

	       #load everything	else
	       $music->load;

	       #resume playing it at a lower volume
	       $music->volume(44);
	       $music->play;

	       #get the	names for all music
	       my @names = keys	%{ $music->data	};

	       for my $name (@names) {
		       #play it	in an infinite loop
		       $music->play($name, loops => 0);
		       warn "Cake!" if $music->playing eq "magical";
		       sleep 10;
	       }

	       #fade out the last song
	       $music->fade_out(5);

	       sleep 4;

	       die "CAKE!" if $music->fading->name eq "magical";

	       sleep 1;

DESCRIPTION
       This class provides a powerful and convenient interface to
       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.

       The 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).

       Please note: do not mix use of this class with SDL::Mixer::Music	if you
       want everything to work right.

METHODS
   new
	       SDLx::Music->new;
	       #Option arguments showing the default parameters
	       SDLx::Music->new( freq => 44100,	format => SDL::Audio::AUDIO_S16SYS, channels =>	2, chunksize =>	4096);

       Creates the new music object. Inits audio with a	call to
       SDLx::Mixer::init, if it	isn't already (if you want more	precise
       control over what is initialized, make sure you call SDLx::Mixer::init
       before you call this method). Creates an	empty default data object for
       object-wide defaults. If	arguments are supplied,	calls "data" with them
       to set up any initial data objects. Returns the new music object.

   data
	       $music->data;
	       $music->data( $name );
	       $music->data( $data );
	       $music->data( %args );

       With no arguments: returns a reference to the data hash.	This hash has
       data names as keys and the associated data objects as values.

       With a name: creates the	data name if it	doesn't	already	exist. Does
       this with a call	to SDLx::Music::Data-new|SDLx::Music::Data/new>	with
       "name ="	$name> and puts	that new object	in the data hash under the key
       of $name. Returns the data object for that name.

       With a hash of arguments: for each pair,	and returns a
       SDLx::Music::Data. Returns $music.

   data_for
	       $music->data_for( @names_or_data_objects	);

       Calls "data" repeatedly,	passing	it one element of the list at a	time,
       to initialise multiple empty names and/or add data objects. Returns
       $music.

   has_data
	       $music->has_data;
	       $music->has_data( $name );
	       $music->has_data( $data );

       Without arguments: returns how many data	objects	the class has.

       With a name: returns the	data object for	$name. If there	is no data
       object for $name	it is not created and undef is returned	instead.

       With a data object: does	a (slowish) reverse of the data	hash to	see if
       the data	object belongs to $music. Returns it or	undef.

   default
	       $music->default;
	       SDLx::Music->default;

       Returns the default data	object belonging to $music (created in "new"),
       or to the class.	See SDLx::Music::Data for information on how defaults
       work.

   load
	       $music->load;
	       $music->load( @names_or_data_objects );
	       SDLx::Music->load( @data_objects	);

       Without arguments: for every data object	belonging to $music, if	the
       data object doesn't already have	a loaded file, loads the file named by
       dir, file and ext if it hasn't been loaded already. Sets	the data
       object's	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>.

       With 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.

   unload
	       $music->unload;
	       $music->unload( @names_or_data_objects );
	       SDLx::Music->unload( @data_objects );

       Without arguments: clears the loaded parameter for all of the data
       objects in $music. The loaded file is removed from memory if it loses
       its last	reference to it. Returns <$music>.

       With 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.

   clear
	       $music->clear;
	       $music->clear( @names );

       Without arguments: empties $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 $music.

       With arguments: does the	same, but only deletes the values of the data
       hash for	the names in the list.

   real_clear
	       $music->real_clear;
	       $music->real_clear( @names_or_data_objects );
	       SDLx::Music->real_clear(	@data_objects );

       The full, brute force version of	"clear".

       Without arguments: empties out the parameters of	every data object in
       $music (including "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 $music.

       With arguments: does the	same, but only clears out the names or data
       objects in the list.

   play
	       $music_or_class->play;
	       $music->play( $name, $params );
	       $music_or_class->play( $data, %params );

       Without arguments: resumes any paused music. Returns the	object or
       class.

       With arguments: plays the sound found in	$music's $name,	or in $data
       (depending on which is specified). "load"s it if	it needs to be loaded
       (which in turn creates the name if it needs to be created). The %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:

       loops
	   Plays the music file	"loops"	times. If "loops" is 0,	loops it
	   infinitely.

       fade_in
	   Fades the music in for its first "fade_in" milliseconds, if
	   "fade_in" is	defined.

       vol Sets	the music volume to "vol".

       vol_portion
	   Multiplies the "vol"	by "vol_portion" (values from 0	to 1 are
	   encouraged) before setting the volume.

       pos Sets	the music position to "pos" if "pos" is	defined.

       Returns the object or class.

   pause
	       $music_or_class->pause;

       Pauses any playing music. Returns the object or class.

   stop
	       $music_or_class->stop;

       Stops any playing music.	Returns	the object or class.

   last_played
	       my $last_played = $music_or_class->last_played;

       Returns the data	object that was	"play"ed last.

   playing
	       my $playing = $music->playing;

       If there	is something playing, returns the data object that was
       "play"ed	last. Otherwise, returns undef.

   paused
       If there	is something paused, returns the data object that was "play"ed
       last. Otherwise,	returns	undef.

   fading
       If there	is something fading, returns the data object that was "play"ed
       last. Otherwise,	returns	undef.

   volume
	       my $volume = $music_or_class->volume;
	       $music_or_class->volume(	$volume	);

       Without arguments: returns the current music volume

       With arguments: Sets the	music volume to	$volume. Returns the object or
       class.

   fade_out
	       $music_or_class->fade_out( $fade_out );

       Fades the music out for its next	"fade_in" milliseconds.	Returns	the
       object or class.

   rewind
	       $music_or_class->rewind;

       Rewinds the music to its	start. Returns the object or class.

   pos
	       $music_or_class->pos( $pos );

       Sets the	music position to $pos milliseconds. It	does different things
       for different file types, so see	SDL::Mixer::Music::set_music_position
       for details. Note that this method divides $pos by 1000 to pass it to
       that function, which uses seconds. Returns the object or	class.

SEE ALSO
       SDLx::Music::Data SDLx::Mixer SDL::Mixer::Music SDL::Mixer

AUTHORS
       See "AUTHORS" in	SDL.

COPYRIGHT & LICENSE
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2021-09-21		  pods::SDLx::Music(3)

NAME | CATEGORY | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHORS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pods::SDLx::Music&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help