sdljava.mixer
public class SDLMixer extends Object
Please see the documentation here.
This library wraps all the functionality provided, however, no support for callbacks is currently implemented.
All audio data currently lives at the C layer and is never copied or deal with at the java side.
Version: $Id: SDLMixer.java,v 1.18 2005/02/19 02:26:02 ivan_ganza Exp $
Field Summary | |
---|---|
static int | AUDIO_S16 |
static int | AUDIO_S16LSB |
static int | AUDIO_S16MSB |
static int | AUDIO_S16SYS |
static int | AUDIO_S8 |
static int | AUDIO_U16 |
static int | AUDIO_U16LSB |
static int | AUDIO_U16MSB |
static int | AUDIO_U16SYS |
static int | AUDIO_U8 |
Method Summary | |
---|---|
static int | allocateChannels(int count)
Set the number of channels being mixed. |
static void | close()
Shutdown and cleanup the mixer API. |
static int | expireChannel(int channel, int ticks)
Halt channel playback, or all channels if -1 is passed in,
after ticks milliseconds. |
static int | fadeInChannel(int channel, MixChunk chunk, int loops, int ms)
Play chunk on channel, or if channel is -1, pick the first free
unreserved channel. |
static int | fadeInChannelTimed(int channel, MixChunk chunk, int loops, int ms, int ticks)
f the sample is long enough and has enough loops then the
sample will stop after ticks milliseconds. |
static void | fadeInMusic(MixMusic music, int loops, int ms)
Fade in over ms milliseconds of time, the loaded music, playing
it loop times through from start to finish. |
static void | fadeInMusicPos(MixMusic music, int loops, int ms, double position)
Fade in over ms milliseconds of time, the loaded music, playing
it loop times through from start to finish. |
static int | fadeOutChannel(int channel, int ms)
Gradually fade out which channel over ms milliseconds starting
from now. |
static int | fadeOutGroup(int tag, int ms)
Gradually fade out channels in group tag over ms milliseconds
starting from now. |
static void | fadeOutMusic(int ms)
Gradually fade out the music over ms milliseconds starting from
now. |
static Mix_Fading | fadingChannel(int which)
Tells you if which channel is fading in, out, or not. |
static Mix_Fading | fadingMusic()
Tells you if music is fading in, out, or not at all. |
static void | freeChunk(MixChunk chunk)
Free the memory used in chunk, and free chunk itself as
well. |
static void | freeMusic(MixMusic music)
Free the loaded music. |
static MixChunk | getChunk(int channel)
Get the most recent sample chunk pointer played on
channel. |
static SDLVersion | getMixVersion()
get a version structure with the compile-time version of the SDL_mixer library.
|
static Mix_MusicType | getMusicType(MixMusic music)
Tells you the file format encoding of the music. |
static int | groupAvailable(int tag)
Find the first available (not playing) channel in group tag.
|
static void | groupChannel(int which, int tag)
Add which channel to group tag, or reset it's group to the default group tag (-1).
|
static int | groupChannels(int from, int to, int tag)
Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).
|
static int | groupCount(int tag)
Count the number of channels in group tag.
|
static int | groupNewer(int tag)
Find the newest, most recently started, actively playing channel in group tag.
|
static int | groupOldest(int tag)
Find the oldest actively playing channel in group tag.
|
static void | haltChannel(int channel)
Halt channel playback, or all channels if -1 is passed in.
|
static void | haltGroup(int tag)
Halt playback on all channels in group tag.
|
static void | haltMusic()
Halt playback of music. |
static MixMusic | loadMUS(String path)
Load music file to use. |
static MixMusic | loadMUS(ByteBuffer buf)
Load music file to use. |
static MixMusic | loadMUS(byte[] data)
Load music file to use. |
static MixMusic | loadMUS(URL url)
Load music file to use. |
static MixMusic | loadMUS(InputStream in)
Load music file to use. |
static MixChunk | loadWAV(String path)
Load file for use as a sample. |
static MixChunk | loadWAV(Buffer buf)
Load file for use as a sample. |
static MixChunk | loadWAV(byte[] data)
Load file for use as a sample. |
static MixChunk | loadWAV(URL url)
Load file for use as a sample. |
static MixChunk | loadWAV(InputStream in)
Load file for use as a sample. |
static void | openAudio(int frequency, int format, int channels, int chunksize)
Initialize the mixer API.
|
static void | pause(int channel)
Pause channel, or all playing channels if -1 is passed in. |
static int | paused(int channel)
Tells you if channel is paused, or not.
|
static boolean | pausedMusic()
Tells you if music is paused, or not.
|
static void | pauseMusic()
Pause the music playback. |
static int | playChannel(int channel, MixChunk chunk, int loops)
Play chunk on channel, or if channel is -1, pick the first free
unreserved channel. |
static int | playChannelTimed(int channel, MixChunk chunk, int loops, int ticks)
If the sample is long enough and has enough loops then the
sample will stop after ticks milliseconds. |
static int | playing(int channel)
Tells you if channel is playing, or not. |
static boolean | playingMusic()
Tells you if music is actively playing, or not.
|
static void | playMusic(MixMusic music, int loops)
Play the loaded music loop times through from start to
finish. |
static MixerSpec | querySpec()
Get the actual audio format in use by the opened audio
device. |
static int | reserveChannels(int num)
Reserve num channels from being used when playing samples when
passing in -1 as a channel number to playback functions. |
static void | resume(int channel)
Unpause channel, or all playing and paused channels if -1 is passed in.
|
static void | resumeMusic()
Unpause the music. |
static void | rewindMusic()
Rewind the music to the start. |
static void | setDistance(int channel, int distance)
This effect simulates a simple attenuation of volume due to
distance. |
static boolean | setMusicPosition(double position)
Set the position of the currently playing music. |
static void | setPanning(int channel, int left, int right)
This effect will only work on stereo audio. |
static void | setPosition(int channel, int angle, int distance)
This effect emulates a simple 3D audio effect. |
static int | volume(int channel, int volume)
Set the volume for any allocated channel. |
static int | volumeChunk(MixChunk chunk, int volume)
Set chunk->volume to volume. |
static int | volumeMusic(int volume)
Set the volume to volume, if it is 0 or greater, and return the
previous volume setting. |
Never fails...but a high number of channels can segfault if you run out of memory. We're talking REALLY high!
Parameters: count Number of channels to allocate for mixing. A negative number will not do anything, it will tell you how many channels are currently allocated.
Returns: The number of channels allocated.
Throws: SDLException if an error occurs
Throws: SDLException if an error occurs
Parameters: channel Channel to stop playing, or -1 for all channels. ticks Millisecons until channel(s) halt playback.
Returns: Number of channels set to expire. Whether or not they are active.
Throws: SDLException if an error occurs
Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.
Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ms Milliseconds of time that the fade-in effect should take to go from silence to full volume.
Returns: the channel the sample is played on
Throws: SDLException if an error occurs
Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ms Milliseconds of time that the fade-in effect should take to go from silence to full volume. ticks Millisecond limit to play sample, at most. If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs. -1 means play forever.
Returns: the channel the sample is played on
Throws: SDLException if an error occurs
Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that) ms Milliseconds for the fade-in effect to complete.
Throws: SDLException if an error occurs
Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that) ms Milliseconds for the fade-in effect to complete. position Posistion to play from, see setMusicPosition for meaning.
Throws: SDLException if an error occurs
Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.
Parameters: channel Channel to fade out, or -1 to fade all channels out. ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.
Returns: The number of channels set to fade out.
Throws: SDLException if an error occurs
Parameters: tag Group to fade out. NOTE: -1 will NOT fade all channels out. Use Mix_FadeOutChannel(-1) for that instead. ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.
Returns: The number of channels set to fade out.
Throws: SDLException if an error occurs
Parameters: ms Milliseconds of time that the fade-out effect should take to go to silence, starting now.
Throws: SDLException if an error occurs
Parameters: which Channel to get the fade activity status from.
Returns: the fading status
Throws: SDLException if an error occurs
Returns: a Mix_Fading
value
Parameters: chunk a MixChunk
value
Throws: SDLException if an error occurs
Parameters: music a MixMusic
value
Throws: SDLException if an error occurs
Note: The actual chunk may have been freed, so this may not be valid anymore.
Parameters: channel Channel to get the current Mix_Chunk playing. -1 is not valid
Returns: a MixChunk
value
Throws: SDLException if an error occurs
Returns: the compile-time version of the SDL_mixer library.
Parameters: music The music to get the type of. NULL will get the currently playing music type.
Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing
Throws: SDLException if an error occurs
Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.
Returns: The channel found on success. -1 is returned when no channels in the group are available.
Throws: SDLException if an error occurs
Parameters: which Channel number of channels to assign tag to. tag A group number Any positive numbers (including zero). -1 is the default group. Use -1 to remove a group tag essentially.
Throws: SDLException if an error occurs
Parameters: from First Channel number of channels to assign tag to. Must be less or equal to to. to Last Channel number of channels to assign tag to. Must be greater or equal to from. tag A group number. Any positive numbers (including zero). -1 is the default group. Use -1 to remove a group tag essentially.
Returns: The number of tagged channels on success. If that number is less than to-from+1 then some channels were no tagged because they didn't exist.
Parameters: tag A group number Any positive numbers (including zero). -1 will count ALL channels.
Returns: The number of channels found in the group. This function never fails.
Throws: SDLException if an error occurs
Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.
Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.
Throws: SDLException if an error occurs
Parameters: tag A group number Any positive numbers (including zero). -1 will search ALL channels.
Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty
Throws: SDLException if an error occurs
Parameters: channel Channel to stop playing, or -1 for all channels.
Throws: SDLException if an error occurs
Parameters: tag Group to fade out. NOTE: -1 will NOT halt all channels. Use Mix_HaltChannel(-1) for that instead.
Throws: SDLException if an error occurs
Throws: SDLException if an error occurs
Parameters: path The path to the music file
Returns: A MixMusic instance
Throws: SDLException if an error occurs
Parameters: buf a DIRECT Buffer
value
Returns: A MixMusic instance
Throws: SDLException if an error occurs
Parameters: data a byte[]
value
Returns: A MixMusic instance
Throws: SDLException if an error occurs
This method automatically creates the NIO Direct Buffer from the given byte array
Parameters: url an URL
value
Returns: A MixMusic instance
Throws: SDLException if an error occurs IOException if an error occurs MalformedURLException if an error occurs
This method automatically creates the NIO Direct Buffer from the given byte array
NOTE: for now this method downloads the url and saves the data in a temporary file
then invokes the standard loadMUS(String path) method to load it, deleting
the file afterwards. Once we move to Mixer 1.2.6 this will not longer be necessary.
Parameters: in an InputStream
value
Returns: A MixMusic instance
Throws: SDLException if an error occurs IOException if an error occurs
This method automatically creates the NIO Direct Buffer
Parameters: The path to the file to load
Returns: The MixChunk
Throws: SDLException if an error occurs
Parameters: buf a DIRECT Buffer
with the Sample data
Returns: The MixChunk
Throws: SDLException if an error occurs
This method automatically creates the NIO Direct Buffer from the given byte array
Parameters: data a byte[]
value
Returns: The MixChunk
Throws: SDLException if an error occurs
This method automatically creates the NIO Direct Buffer from the given byte array
Parameters: url The URL to fetch the data from
Returns: The MixChunk
Throws: SDLException if an error occurs
This method automatically creates the NIO Direct Buffer
Parameters: url The URL to fetch the data from
Returns: The MixChunk
Throws: SDLException if an error occurs
This must be called before using other functions in this library. SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls. So you will have to close all the way before trying to open with different format parameters. format is based on SDL audio support, see SDL_audio.h. Here are the values listed there:
MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.
Parameters: frequency Output sampling frequency in samples per second (Hz). format Output sample format. channels Number of sound channels in output. Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels. chunksize Bytes used per output sample.
Throws: SDLException if an error occurs
Note: Only channels which are actively playing will be paused.
Parameters: channel Channel to pause playing, or -1 for all channels.
Throws: SDLException if an error occurs
Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.
Parameters: channel Channel to test whether it is paused or not. -1 will tell you how many channels are paused.
Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.
Throws: SDLException if an error occurs
Note: Does not check if the music was been halted after it was paused, which may seem a little weird.
Returns: if music is paused
Note: Music can only be paused if it is actively playing.
Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.
Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop).
Returns: the channel the sample is played on
Throws: SDLException if an error occurs
Parameters: channel Channel to play on, or -1 for the first free unreserved channel. chunk Sample to play loops Number of loops, -1 is infinite loops. Passing one here plays the sample twice (1 loop). ticks Millisecond limit to play sample, at most. If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs. -1 means play forever.
Returns: the channel the sample is played on
Throws: SDLException if an error occurs
Parameters: channel Channel to test whether it is playing or not. -1 will tell you how many channels are playing.
Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing
Throws: SDLException if an error occurs
Note: Does not check if the channel has been paused.
Returns: if music is actively playing
Parameters: music Music to play loops number of times to play through the music. 0 plays the music zero times... -1 plays the music forever (or as close as it can get to that)
Throws: SDLException if an error occurs
Returns: The current audio settings
Throws: SDLException if an error occurs
The following functions are affected by this setting:
Mix_PlayChannel
Mix_PlayChannelTimed
Mix_FadeInChannel
Mix_FadeInChannelTimed
Parameters: num Number of channels to reserve from default mixing. Zero removes all reservations.
Returns: The number of channels reserved. Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.
Throws: SDLException if an error occurs
Parameters: channel Channel to resume playing, or -1 for all channels.
Throws: SDLException if an error occurs
This function only works for these streams: MOD, OGG, MP3, Native MIDI.
NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
Parameters: channel Channel number to register this effect on. Use MIX_CHANNEL_POST to process the postmix stream. distance Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).
Throws: SDLException if an error occurs
Parameters: position Position to play from
Returns: true on success, -1 if the codec doesn't support this function
Throws: SDLException if an error occurs
NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.
Parameters: channel Channel number to register this effect on. Use MIX_CHANNEL_POST to process the postmix stream. left Volume for the left channel, range is 0(silence) to 255(loud) right Volume for the left channel, range is 0(silence) to 255(loud)
Throws: SDLException if an error occurs
NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
Parameters: channel Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream. angle Direction in relation to forward from 0 to 360 degrees.
Larger angles will be reduced to this range using angles % 360.
So you can see it goes clockwise starting at directly in front.
This ends up being similar in effect to Mix_SetPanning.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
Throws: SDLException if an error occurs
Parameters: Channel to set mix volume for. -1 will set the volume for all allocated channels. volume The volume to use from 0 to MIX_MAX_VOLUME(128). If greater than MIX_MAX_VOLUME, then it will be set to MIX_MAX_VOLUME. If less than 0 then the volume will not be set.
Returns: current volume of the channel. If channel is -1, the average volume is returned.
Throws: SDLException if an error occurs
Parameters: The chunk to set the volume in The volume to use from 0 to MIX_MAX_VOLUME(128). If greater than MIX_MAX_VOLUME, then it will be set to MIX_MAX_VOLUME. If less than 0 then chunk->volume will not be set.
Returns: previous chunk->volume setting. if you passed a negative value for volume then this volume is still the current volume for the chunk
Throws: SDLException if an error occurs
Parameters: volume Music volume, from 0 to MIX_MAX_VOLUME(128). Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME. -1 does not set the volume, but does return the current volume setting.
Returns: The previous volume setting.
Throws: SDLException if an error occurs