/lib/pods/SDL/Mixer.pod

http://github.com/PerlGameDev/SDL · Unknown · 242 lines · 144 code · 98 blank · 0 comment · 0 complexity · e3d9c35526c03d121c4e986e75c3780f MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL::Mixer - Sound and music functions
  4. =head1 CATEGORY
  5. Mixer
  6. =head1 CONSTANTS
  7. The constants are exported by default. You can avoid this by doing:
  8. use SDL::Mixer ();
  9. and access them directly:
  10. SDL::Mixer::MIX_DEFAULT_FREQUENCY;
  11. or by choosing the export tags below:
  12. Export tag: ':init'
  13. MIX_INIT_FLAC
  14. MIX_INIT_MOD
  15. MIX_INIT_MP3
  16. MIX_INIT_OGG
  17. Export tag: ':defaults'
  18. MIX_CHANNELS
  19. MIX_DEFAULT_FORMAT
  20. MIX_DEFAULT_FREQUENCY
  21. MIX_DEFAULT_CHANNELS
  22. MIX_MAX_VOLUME
  23. MIX_CHANNEL_POST
  24. Export tag: ':fading'
  25. MIX_NO_FADING
  26. MIX_FADING_OUT
  27. MIX_FADING_IN
  28. Export tag: ':type'
  29. MUS_NONE
  30. MUS_CMD
  31. MUS_WAV
  32. MUS_MOD
  33. MUS_MID
  34. MUS_OGG
  35. MUS_MP3
  36. MUS_MP3_MAD
  37. MUS_MP3_FLAC
  38. Export tag: ':format'
  39. AUDIO_U8
  40. AUDIO_S8
  41. AUDIO_U16LSB
  42. AUDIO_S16LSB
  43. AUDIO_U16MSB
  44. AUDIO_S16MSB
  45. AUDIO_U16
  46. AUDIO_S16
  47. AUDIO_U16SYS
  48. AUDIO_S16SYS
  49. Export tag: ':status'
  50. SDL_AUDIO_STOPPED
  51. SDL_AUDIO_PLAYING
  52. SDL_AUDIO_PAUSED
  53. =head1 DESCRIPTION
  54. SDL::Mixer allows you to enable sound, alter music volume settings, and lets you play, pause and resume, as well as fading the sound and music
  55. in and out.
  56. =head2 Supported Formats
  57. The SDL Mixer library is a multi-channel audio mixer. It supports I<8 channels> of B<16 bit> stereo audio, and a I<single channel for music>.
  58. You can use the channels to load samples (i.e. sound effects) in the following formats:
  59. =over 4
  60. =item * Microsoft WAVE files (WAV)
  61. =item * Creative Labs VOC files (VOC)
  62. =item * MIDI files (if compiled with Timidity)
  63. =back
  64. If you use MIDI, you should note that the process of mixing MIDI files to wave output is very CPU-intensive, so if playing regular WAVE
  65. files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.
  66. The music channel can play the following formats:
  67. =over 4
  68. =item * AIFF
  69. =item * MOD (.mod .xm .s3m .669 .it .med and more - if compiled with libmikmod)
  70. =item * OggVorbis (.ogg - if compiled with ogg/vorbis libraries)
  71. =item * MP3 (if compiled with SMPEG or MAD libraries)
  72. =item * FLAC (if compiled with FLAC library)
  73. =back
  74. =head1 METHODS
  75. =head2 init
  76. my $init_flags = SDL::Mixer::init( $flags );
  77. Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together.
  78. It returns the flags successfully initialized, or 0 on failure.
  79. Example:
  80. use SDL::Mixer;
  81. my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
  82. print("We have MP3 support!\n") if $init_flags & MIX_INIT_MP3;
  83. print("We have MOD support!\n") if $init_flags & MIX_INIT_MOD;
  84. print("We have FLAC support!\n") if $init_flags & MIX_INIT_FLAC;
  85. print("We have OGG support!\n") if $init_flags & MIX_INIT_OGG;
  86. Flags:
  87. =over 4
  88. =item *
  89. MIX_INIT_MP3
  90. =item *
  91. MIX_INIT_MOD
  92. =item *
  93. MIX_INIT_FLAC
  94. =item *
  95. MIX_INIT_OGG
  96. =back
  97. B<Note>: Only available for SDL_mixer >= 1.2.10
  98. =head2 quit
  99. SDL::Mixer::quit();
  100. This function unloads the libraries previously loaded with L<init()|/init>.
  101. B<Note>: Only available for SDL_mixer >= 1.2.10
  102. =head2 linked_version
  103. $version = SDL::Mixer::linked_version();
  104. C<linked_version> gives you the major-, minor-, and patchlevel for SDL_mixer. This way you can check if e.g. L<init()|/init> and L<quit()|/quit>
  105. are available.
  106. Example:
  107. use SDL::Mixer;
  108. use SDL::Version;
  109. my $version = SDL::Mixer::linked_version();
  110. printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me
  111. =head2 open_audio
  112. my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
  113. C<open_audio> will initialize SDL_mixer if it is not yet initialized, see note. SDL_mixer may not be able to provide the exact specifications
  114. your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using
  115. L<query_spec>.
  116. Returns 0 on success, -1 on error.
  117. B<Note>: You must not use C<AUDIO_S16>, C<AUDIO_U16>, C<AUDIO_S16LSB>, or C<AUDIO_U16LSB.> They are not portable, and SDL will not return an
  118. error code when they fail. The result will be a horrible staticy noise. You can usually use C<AUDIO_S16SYS>, though not always. Future versions
  119. of SDL should take this parameter only as a hint, then read back the value that the OS (for example, OSS or ALSA) has chosen to use in case the
  120. desired audio type is not supported.
  121. B<Note>: When already initialized, this function will not re-initialize SDL_mixer, nor fail. It will merely increment the number of times
  122. L<SDL::Mixer::close_audio|SDL::Mixer/"close_audio"> must be called to actually get it to uninitialize. This serves as a very simplistic method for multiple application
  123. components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the
  124. latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting.
  125. Example:
  126. use SDL;
  127. use SDL::Mixer;
  128. printf("Error initializing SDL_mixer: %s\n", SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;
  129. =head2 close_audio
  130. SDL::Mixer::close_audio();
  131. Close the mixer and halting all playing audio. This function does not return anything.
  132. =head2 query_spec
  133. my @query_spec = @{ SDL::Mixer::query_spec() };
  134. Find out what the actual audio device parameters are.
  135. This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.
  136. Example:
  137. use SDL::Mixer;
  138. my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
  139. printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels);
  140. =head1 SEE ALSO
  141. L<perl>, L<SDL::Mixer::Channels>, L<SDL::Mixer::Effects>, L<SDL::Mixer::Groups>, L<SDL::Mixer::Music>.
  142. =head1 AUTHORS
  143. See L<SDL/AUTHORS>.
  144. =cut