Class SoundSystem

java.lang.Object
com.blackrook.gloop.openal.util.system.SoundSystem
public class SoundSystem extends Object
The main sound system. This is a high-level implementation of OpenAL which performs a lot of out-of-the-box conveniences for sound playback.

If this class is used, do NOT use the OALSystem class for sound playback.

Author:
Matthew Tropiano

  • Constructor Details

    • SoundSystem

      public SoundSystem()
      Creates and initializes a new sound system.

    • SoundSystem

      public SoundSystem(int voices)
      Creates and initializes a new sound system.
      Parameters:
      voices - the total amount of voices to allocate.

    • SoundSystem

      public SoundSystem(int voices, int cacheSize)
      Creates and initializes a new sound system.
      Parameters:
      voices - the total amount of voices to allocate.
      cacheSize - the cache size for the sound clip cache.

  • Method Details

    • fileData

      public static SoundData fileData(File file)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, int limit)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      limit - the concurrent play limit until a cull or replace.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, boolean stream, int limit)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      stream - if true, the data is streamed, not loaded fully.
      limit - the concurrent play limit until a cull or replace.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, boolean stream, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      stream - if true, the data is streamed, not loaded fully.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, boolean stream, boolean replacesOldSounds, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      stream - if true, the data is streamed, not loaded fully.
      replacesOldSounds - if true, hitting the limit will replace a sound, not cull it.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • fileData

      public static SoundData fileData(File file, boolean stream, boolean replacesOldSounds, boolean alwaysPlayed, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      file - the file to load.
      stream - if true, the data is streamed, not loaded fully.
      replacesOldSounds - if true, hitting the limit will replace a sound, not cull it.
      alwaysPlayed - if true, must play once it is able to.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, int limit)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      limit - the concurrent play limit until a cull or replace.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, boolean stream, int limit)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      stream - if true, the data is streamed, not loaded fully.
      limit - the concurrent play limit until a cull or replace.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, boolean stream, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      stream - if true, the data is streamed, not loaded fully.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, boolean stream, boolean replacesOldSounds, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      stream - if true, the data is streamed, not loaded fully.
      replacesOldSounds - if true, hitting the limit will replace a sound, not cull it.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • resourceData

      public static SoundData resourceData(String resourcePath, boolean stream, boolean replacesOldSounds, boolean alwaysPlayed, int limit, float pitchVariance)
      Creates a new sound data type.
      Parameters:
      resourcePath - the path to the internal resource.
      stream - if true, the data is streamed, not loaded fully.
      replacesOldSounds - if true, hitting the limit will replace a sound, not cull it.
      alwaysPlayed - if true, must play once it is able to.
      limit - the concurrent play limit until a cull or replace.
      pitchVariance - the pitch variance scalar.
      Returns:
      a new category.

    • soundScape

      public static com.blackrook.gloop.openal.util.system.SoundSystem.SoundScape soundScape(SoundEchoType echoType, SoundReverbType reverbType, SoundOcclusionType occlusionType, float minEffectGain, float maxEffectDistance)
      Creates a new SoundScape.
      Parameters:
      echoType - the echo type.
      reverbType - the reverb type.
      occlusionType - the occlusion type.
      minEffectGain - the minimum effect gain at distance 0 (gain is 1.0 at max distance).
      maxEffectDistance - the distance in world units at which the effect gain is 1.0.
      Returns:
      a new soundscape.

    • group

      public static SoundSystem.SoundGroup group(boolean occludable, boolean twoDimensional, boolean zeroPosition, int maxVoices)
      Creates a new group type with defaults set, no parent.
      Parameters:
      occludable - if true, the sounds played from the this group are occludable.
      twoDimensional - if true, the sounds played from the this group are panned, not spacialized.
      zeroPosition - if true, the sounds played from the this group are always played from the observer and unattenuated.
      maxVoices - the maximum amount of voices for this group. 0 is unlimited.
      Returns:
      a new group.

    • group

      public static SoundSystem.SoundGroup group(SoundGroupType parent, boolean occludable, boolean twoDimensional, boolean zeroPosition, int maxVoices)
      Creates a new group type with defaults set.
      Parameters:
      parent - the parent group to accumulate from.
      occludable - if true, the sounds played from the this group are occludable.
      twoDimensional - if true, the sounds played from the this group are panned, not spacialized.
      zeroPosition - if true, the sounds played from the this group are always played from the observer and unattenuated.
      maxVoices - the maximum amount of voices for this group. 0 is unlimited.
      Returns:
      a new group.

    • category

      public static SoundCategoryType category(SoundRolloffType rolloff)
      Creates a new rolloff category type.
      Parameters:
      rolloff - the main rolloff.
      Returns:
      a new category.

    • category

      public static SoundCategoryType category(SoundRolloffType rolloff, SoundRolloffType rolloffConic)
      Creates a new rolloff category type.
      Parameters:
      rolloff - the main rolloff.
      rolloffConic - the conic gain rolloff.
      Returns:
      a new category.

    • category

      public static SoundCategoryType category(SoundRolloffType rolloff, SoundRolloffType rolloffLF, SoundRolloffType rolloffHF, SoundRolloffType rolloffConic)
      Creates a new rolloff category type.
      Parameters:
      rolloff - the main rolloff.
      rolloffLF - the low-pass gain rolloff.
      rolloffHF - the high-pass gain rolloff.
      rolloffConic - the conic gain rolloff.
      Returns:
      a new category.

    • rolloff

      public static SoundRolloffType rolloff(float minDistance, float maxDistance, SoundRolloffFunction rolloffFunction)
      Creates a new rolloff type instance.
      Parameters:
      minDistance - the minimum distance that attenuation starts occurring.
      maxDistance - the maximum distance that full attenuation happens.
      rolloffFunction - the rolloff function for the distance betweeen min and max.
      Returns:
      a new rolloff.

    • occlusion

      public static SoundOcclusionType occlusion(float maximumWidth, float gain, float lowPassGain, float highPassGain)
      Creates a new set of occlusion parameters.
      Parameters:
      maximumWidth - the maximum occlusion width for max occlusion.
      gain - the full gain attenuation.
      lowPassGain - the full low-pass gain attenuation.
      highPassGain - the full high-pass gain attenuation.
      Returns:
      a new occlusion.

    • location

      public static SoundLocation location(float x, float y, float z, float angle)
      Creates a new location instance.
      Parameters:
      x - the location x-coordinate, in world units.
      y - the location y-coordinate, in world units.
      z - the location z-coordinate, in world units.
      angle - the location angle, in degrees.
      Returns:
      a new location.

    • getVendorName

      public String getVendorName()
      Returns:
      the vendor name for this OpenAL implementation.

    • getVersionName

      public String getVersionName()
      Returns:
      the version name for this OpenAL implementation.

    • getRendererName

      public String getRendererName()
      Returns:
      the renderer name for this OpenAL implementation.

    • getExtensions

      public Set<String> getExtensions()
      Returns:
      the set of extensions for this OpenAL implementation.

    • addListener

      public void addListener(SoundSystem.Listener listener)
      Adds a listener to this sound system.
      Parameters:
      listener - the listener to add.

    • removeListener

      public void removeListener(SoundSystem.Listener listener)
      Adds a listener to this sound system.
      Parameters:
      listener - the listener to add.

    • setObserver

      public void setObserver(SoundLocation location)
      Sets the observer location.
      Parameters:
      location - the observer's location reference.

    • setSoundScape

      public void setSoundScape(SoundScapeType soundScape)
      Sets the soundscape to use.
      Parameters:
      soundScape - the new soundscape. Can be null.

    • setOcclusionFunction

      public void setOcclusionFunction(SoundSystem.OcclusionFunction occlusionFunction)
      Sets the occlusion function to use to calculate occlusion.
      Parameters:
      occlusionFunction - the function.

    • cacheSounds

      public void cacheSounds(SoundData... resources)
      Precaches a series of sound resources. Will NOT cache sounds if they designated as not cacheable or if they are streaming: instead, they are "primed" - which means that it is prebuffered and ready to be played later.
      Parameters:
      resources - the list of resources to cache.

    • play

      public void play(SoundData data, SoundGroupType group)
      Plays a sound. No virtual channel, location, nor rolloff.
      Parameters:
      data - the sound data.
      group - the sound group it plays under.

    • play

      public void play(SoundData data, SoundGroupType group, SoundLocation location)
      Plays a sound. No virtual channel, nor rolloff.
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      location - the sound location in the world.

    • play

      public void play(SoundData data, SoundGroupType group, SoundCategoryType category, SoundLocation location)
      Plays a sound. No virtual channel.
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      category - the sound rolloff category.
      location - the sound location in the world.

    • play

      public void play(SoundData data, SoundGroupType group, SoundCategoryType category, SoundLocation location, Integer channel)
      Plays a sound.
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      category - the sound rolloff category.
      location - the sound location in the world.
      channel - the virtual channel on the location.

    • playLooping

      public void playLooping(SoundData data, SoundGroupType group)
      Plays a looping sound. Be careful - you need to be able to stop this sound!
      Parameters:
      data - the sound data.
      group - the sound group it plays under.

    • playLooping

      public void playLooping(SoundData data, SoundGroupType group, SoundLocation location)
      Plays a looping sound. Be careful - you need to be able to stop this sound!
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      location - the sound location in the world.

    • playLooping

      public void playLooping(SoundData data, SoundGroupType group, SoundCategoryType category, SoundLocation location)
      Plays a looping sound. Be careful - you need to be able to stop this sound!
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      category - the sound rolloff category.
      location - the sound location in the world.

    • playLooping

      public void playLooping(SoundData data, SoundGroupType group, SoundCategoryType category, SoundLocation location, Integer channel)
      Plays a looping sound. Be careful - you need to be able to stop this sound!
      Parameters:
      data - the sound data.
      group - the sound group it plays under.
      category - the sound rolloff category.
      location - the sound location in the world.
      channel - the virtual channel on the location.

    • pauseGroup

      public void pauseGroup(SoundSystem.SoundGroup group)
      Pauses all instances of sounds playing in a group.
      Parameters:
      group - the group object.

    • pauseLocation

      public void pauseLocation(SoundLocation location)
      Pauses all instances of sounds playing on a location.
      Parameters:
      location - the location object.

    • resumeGroup

      public void resumeGroup(SoundSystem.SoundGroup group)
      Resumes all instances of sounds playing in a group.
      Parameters:
      group - the group object.

    • resumeLocation

      public void resumeLocation(SoundLocation location)
      Resumes all instances of sounds playing on a location.
      Parameters:
      location - the location object.

    • stopSound

      public void stopSound(SoundData data)
      Stops all instances of a sound playing.
      Parameters:
      data - the sound data.

    • stopGroup

      public void stopGroup(SoundSystem.SoundGroup group)
      Stops all sounds in a group.
      Parameters:
      group - the sound group.

    • stopLocation

      public void stopLocation(SoundLocation location, Integer channel)
      Stops all sounds on a location.
      Parameters:
      location - the location object.
      channel - the optional channel.

    • getUpdateVoiceNanos

      public long getUpdateVoiceNanos()
      Returns:
      the amount of time it took the voice update loop to update in nanoseconds.

    • getUpdateEventNanos

      public long getUpdateEventNanos()
      Returns:
      the amount of time it took the event loop to update in nanoseconds.

    • getAvailableVoiceCount

      public int getAvailableVoiceCount()
      Returns:
      the amount of available voices.

    • getUsedVoiceCount

      public int getUsedVoiceCount()
      Returns:
      the amount of used voices.

    • shutDown

      public void shutDown()
      Stops all threads, sounds, and deallocates everything.