SDLMixer (sdljava api)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

sdljava.mixer
Class SDLMixer

java.lang.Object
  sdljava.mixer.SDLMixer

public class SDLMixer
extends java.lang.Object
extends java.lang.Object

Binding to the SDL_mixer library.

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 $
Author:: Ivan Z. Ganza

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`

Constructor Summary
`SDLMixer()`

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(byte[] data)` Load music file to use.
`static MixMusic`	`loadMUS(java.nio.ByteBuffer buf)` Load music file to use.
`static MixMusic`	`loadMUS(java.io.InputStream in)` Load music file to use.
`static MixMusic`	`loadMUS(java.lang.String path)` Load music file to use.
`static MixMusic`	`loadMUS(java.net.URL url)` Load music file to use.
`static MixChunk`	`loadWAV(java.nio.Buffer buf)` Load file for use as a sample.
`static MixChunk`	`loadWAV(byte[] data)` Load file for use as a sample.
`static MixChunk`	`loadWAV(java.io.InputStream in)` Load file for use as a sample.
`static MixChunk`	`loadWAV(java.lang.String path)` Load file for use as a sample.
`static MixChunk`	`loadWAV(java.net.URL url)` 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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

AUDIO_U8

public static final int AUDIO_U8

See Also:: Constant Field Values

AUDIO_S8

public static final int AUDIO_S8

See Also:: Constant Field Values

AUDIO_U16LSB

public static final int AUDIO_U16LSB

See Also:: Constant Field Values

AUDIO_S16LSB

public static final int AUDIO_S16LSB

See Also:: Constant Field Values

AUDIO_U16MSB

public static final int AUDIO_U16MSB

See Also:: Constant Field Values

AUDIO_S16MSB

public static final int AUDIO_S16MSB

See Also:: Constant Field Values

AUDIO_U16

public static final int AUDIO_U16

See Also:: Constant Field Values

AUDIO_S16

public static final int AUDIO_S16

See Also:: Constant Field Values

AUDIO_S16SYS

public static final int AUDIO_S16SYS

See Also:: Constant Field Values

AUDIO_U16SYS

public static final int AUDIO_U16SYS

See Also:: Constant Field Values

Constructor Detail

SDLMixer

public SDLMixer()

Method Detail

openAudio

public static void openAudio(int frequency,
                             int format,
                             int channels,
                             int chunksize)
                      throws SDLException

Initialize the mixer API.

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:

AUDIO_U8
Unsigned 8-bit samples
AUDIO_S8
Signed 8-bit samples
AUDIO_U16LSB
Unsigned 16-bit samples, in little-endian byte order
AUDIO_S16LSB
Signed 16-bit samples, in little-endian byte order
AUDIO_U16MSB
Unsigned 16-bit samples, in big-endian byte order
AUDIO_S16MSB
Signed 16-bit samples, in big-endian byte order
AUDIO_U16
same as AUDIO_U16LSB (for backwards compatability probably)
AUDIO_S16
same as AUDIO_S16LSB (for backwards compatability probably)
AUDIO_U16SYS
Unsigned 16-bit samples, in system byte order
AUDIO_S16SYS
Signed 16-bit samples, in system byte order

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

close

public static void close()
                  throws SDLException

Shutdown and cleanup the mixer API. After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again. Note: This function doesn't do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

Throws:: SDLException - if an error occurs

querySpec

public static MixerSpec querySpec()
                           throws SDLException

Get the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to Mix_OpenAudio.

Returns:: The current audio settings
Throws:: SDLException - if an error occurs

loadWAV

public static MixChunk loadWAV(java.lang.String path)
                        throws SDLException

Load file for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC files. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Parameters:: The - path to the file to load
Returns:: The MixChunk
Throws:: SDLException - if an error occurs

loadWAV

public static MixChunk loadWAV(java.nio.Buffer buf)
                        throws SDLException

Parameters:: buf - a DIRECT Buffer with the Sample data
Returns:: The MixChunk
Throws:: SDLException - if an error occurs

loadWAV

public static MixChunk loadWAV(byte[] data)
                        throws SDLException

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

loadWAV

public static MixChunk loadWAV(java.net.URL url)
                        throws SDLException,
                               java.io.IOException,
                               java.net.MalformedURLException

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; java.io.IOException; java.net.MalformedURLException

loadWAV

public static MixChunk loadWAV(java.io.InputStream in)
                        throws SDLException,
                               java.io.IOException

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; java.io.IOException

volumeChunk

public static int volumeChunk(MixChunk chunk,
                              int volume)
                       throws SDLException

Set chunk->volume to volume. The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

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

freeChunk

public static void freeChunk(MixChunk chunk)
                      throws SDLException

Free the memory used in chunk, and free chunk itself as well. Do not use chunk after this without loading a new sample to it. Note: It's a bad idea to free a chunk that is still being played...

Parameters:: chunk - a MixChunk value
Throws:: SDLException - if an error occurs

allocateChannels

public static int allocateChannels(int count)
                            throws SDLException

Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though. If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

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

volume

public static int volume(int channel,
                         int volume)
                  throws SDLException

Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

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

playChannel

public static int playChannel(int channel,
                              MixChunk chunk,
                              int loops)
                       throws SDLException

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

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

playChannelTimed

public static int playChannelTimed(int channel,
                                   MixChunk chunk,
                                   int loops,
                                   int ticks)
                            throws SDLException

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as playChannel.

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

fadeInChannel

public static int fadeInChannel(int channel,
                                MixChunk chunk,
                                int loops,
                                int ms)
                         throws SDLException

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

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

fadeInChannelTimed

public static int fadeInChannelTimed(int channel,
                                     MixChunk chunk,
                                     int loops,
                                     int ms,
                                     int ticks)
                              throws SDLException

f the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_FadeInChannel.

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

pause

public static void pause(int channel)
                  throws SDLException

Pause channel, or all playing channels if -1 is passed in. You may still halt a paused channel.

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

resume

public static void resume(int channel)
                   throws SDLException

Unpause channel, or all playing and paused channels if -1 is passed in.

Parameters:: channel - Channel to resume playing, or -1 for all channels.
Throws:: SDLException - if an error occurs

haltChannel

public static void haltChannel(int channel)
                        throws SDLException

Halt channel playback, or all channels if -1 is passed in. Any callback set by Mix_ChannelFinished will be called.

Parameters:: channel - Channel to stop playing, or -1 for all channels.
Throws:: SDLException - if an error occurs

expireChannel

public static int expireChannel(int channel,
                                int ticks)
                         throws SDLException

Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

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

fadeOutChannel

public static int fadeOutChannel(int channel,
                                 int ms)
                          throws SDLException

Gradually fade out which channel over ms milliseconds starting from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels.

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

playing

public static int playing(int channel)
                   throws SDLException

Tells you if channel is playing, or not. Note: Does not check if the channel has been paused.

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

paused

public static int paused(int channel)
                  throws SDLException

Tells you if channel is paused, or not.

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

fadingChannel

public static Mix_Fading fadingChannel(int which)
                                throws SDLException

Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Parameters:: which - Channel to get the fade activity status from.
Returns:: the fading status
Throws:: SDLException - if an error occurs

getChunk

public static MixChunk getChunk(int channel)
                         throws SDLException

Get the most recent sample chunk pointer played on channel. This pointer may be currently playing, or just the last used.

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

reserveChannels

public static int reserveChannels(int num)
                           throws SDLException

Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to num-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

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

groupChannel

public static void groupChannel(int which,
                                int tag)
                         throws SDLException

Add which channel to group tag, or reset it's group to the default group tag (-1).

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

groupChannels

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

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.

groupCount

public static int groupCount(int tag)
                      throws SDLException

Count the number of channels in group tag.

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

groupAvailable

public static int groupAvailable(int tag)
                          throws SDLException

Find the first available (not playing) channel in group tag.

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

groupOldest

public static int groupOldest(int tag)
                       throws SDLException

Find the oldest actively playing channel in group tag.

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

groupNewer

public static int groupNewer(int tag)
                      throws SDLException

Find the newest, most recently started, actively playing channel in group tag.

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

fadeOutGroup

public static int fadeOutGroup(int tag,
                               int ms)
                        throws SDLException

Gradually fade out channels in group tag over ms milliseconds starting from now. The channels will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when each channel finishes fading out.

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

haltGroup

public static void haltGroup(int tag)
                      throws SDLException

Halt playback on all channels in group tag. Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

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

loadMUS

public static MixMusic loadMUS(java.lang.String path)
                        throws SDLException

Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Parameters:: path - The path to the music file
Returns:: A MixMusic instance
Throws:: SDLException - if an error occurs

loadMUS

public static MixMusic loadMUS(java.nio.ByteBuffer buf)
                        throws SDLException,
                               java.io.IOException

Parameters:: buf - a DIRECT Buffer value
Returns:: A MixMusic instance
Throws:: SDLException - if an error occurs; java.io.IOException

loadMUS

public static MixMusic loadMUS(byte[] data)
                        throws SDLException,
                               java.io.IOException

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; java.io.IOException

loadMUS

public static MixMusic loadMUS(java.net.URL url)
                        throws SDLException,
                               java.io.IOException,
                               java.net.MalformedURLException

Parameters:

url - an URL value

Returns:

A MixMusic instance

Throws:

SDLException - if an error occurs

java.io.IOException - if an error occurs

java.net.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.

loadMUS

public static MixMusic loadMUS(java.io.InputStream in)
                        throws SDLException,
                               java.io.IOException

Parameters:: in - an InputStream value
Returns:: A MixMusic instance
Throws:: SDLException - if an error occurs; java.io.IOException - if an error occurs
This method automatically creates the NIO Direct Buffer

freeMusic

public static void freeMusic(MixMusic music)
                      throws SDLException

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

Parameters:: music - a MixMusic value
Throws:: SDLException - if an error occurs

playMusic

public static void playMusic(MixMusic music,
                             int loops)
                      throws SDLException

Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.

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

fadeInMusic

public static void fadeInMusic(MixMusic music,
                               int loops,
                               int ms)
                        throws SDLException

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish. The fade in effect only applies to the first loop. Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete. This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).

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

fadeInMusicPos

public static void fadeInMusicPos(MixMusic music,
                                  int loops,
                                  int ms,
                                  double position)
                           throws SDLException

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish. The fade in effect only applies to the first loop. The first time the music is played, it posistion will be set to posistion, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that. Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete

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

volumeMusic

public static int volumeMusic(int volume)
                       throws SDLException

Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

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

pauseMusic

public static void pauseMusic()

Pause the music playback. You may halt paused music.

Note: Music can only be paused if it is actively playing.

resumeMusic

public static void resumeMusic()

Unpause the music. This is safe to use on halted, paused, and already playing music.

rewindMusic

public static void rewindMusic()

Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for these streams: MOD, OGG, MP3, Native MIDI.

setMusicPosition

public static boolean setMusicPosition(double position)
                                throws SDLException

Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the music sources listed below.

MOD
The double is cast to Uint16 and used for a pattern number in the module. Passing zero is similar to rewinding the song.
OGG
Jumps to position seconds from the beginning of the song.
MP3
Jumps to position seconds from the current position in the stream. So you may want to call Mix_RewindMusic before this. Does not go in reverse...negative values do nothing.

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

haltMusic

public static void haltMusic()
                      throws SDLException

Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Throws:: SDLException - if an error occurs

fadeOutMusic

public static void fadeOutMusic(int ms)
                         throws SDLException

Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Parameters:: ms - Milliseconds of time that the fade-out effect should take to go to silence, starting now.
Throws:: SDLException - if an error occurs

getMusicType

public static Mix_MusicType getMusicType(MixMusic music)
                                  throws SDLException

Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

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

playingMusic

public static boolean playingMusic()

Tells you if music is actively playing, or not.

Note: Does not check if the channel has been paused.

Returns:: if music is actively playing

pausedMusic

public static boolean pausedMusic()

Tells you if music is paused, or not.

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

fadingMusic

public static Mix_Fading fadingMusic()

Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns:: a Mix_Fading value

setPanning

public static void setPanning(int channel,
                              int left,
                              int right)
                       throws SDLException

This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume. This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.

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

setDistance

public static void setDistance(int channel,
                               int distance)
                        throws SDLException

This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.

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

setPosition

public static void setPosition(int channel,
                               int angle,
                               int distance)
                        throws SDLException

This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.

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.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
So you can see it goes clockwise starting at directly in front. This ends up being similar in effect to Mix_SetPanning.; distance - The distance from the listener, from 0(near/loud) to 255(far/quiet). This is the same as the Mix_SetDistance effect.
Throws:: SDLException - if an error occurs

getMixVersion

public static SDLVersion getMixVersion()

get a version structure with the compile-time version of the SDL_mixer library.

Returns:: the compile-time version of the SDL_mixer library.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

sdljava.mixer Class SDLMixer

AUDIO_U8

AUDIO_S8

AUDIO_U16LSB

AUDIO_S16LSB

AUDIO_U16MSB

AUDIO_S16MSB

AUDIO_U16

AUDIO_S16

AUDIO_S16SYS

AUDIO_U16SYS

SDLMixer

openAudio

close

querySpec

loadWAV

loadWAV

loadWAV

loadWAV

loadWAV

volumeChunk

freeChunk

allocateChannels

volume

playChannel

playChannelTimed

fadeInChannel

fadeInChannelTimed

pause

resume

haltChannel

expireChannel

fadeOutChannel

playing

paused

fadingChannel

getChunk

reserveChannels

groupChannel

groupChannels

groupCount

groupAvailable

groupOldest

groupNewer

fadeOutGroup

haltGroup

loadMUS

loadMUS

loadMUS

loadMUS

loadMUS

freeMusic

playMusic

fadeInMusic

fadeInMusicPos

volumeMusic

pauseMusic

resumeMusic

rewindMusic

setMusicPosition

haltMusic

fadeOutMusic

getMusicType

playingMusic

pausedMusic

fadingMusic

setPanning

setDistance

setPosition

getMixVersion

sdljava.mixer
Class SDLMixer