Package limn.sound

Record Class PlayOptions

java.lang.Object
java.lang.Record
limn.sound.PlayOptions
Record Components:
gain - volume in [0..1], multiplied by the bus and master gains
pitch - playback-rate multiplier in [0.25..4], where 1 is natural; the standard de-repetition trick is a small random variation
pan - stereo position in [-1..1] (left..right, 0 = center). Realized for MONO clips; stereo clips ignore it
loop - repeat until stopped
bus - the mixer bus this playback belongs to
priority - voice-steal class: when every voice is busy, lower-priority sounds are stolen first and a sound never steals a higher-priority voice; mark music/dialog PlayOptions.Priority.HIGH so an effects burst cannot silence it
position - world position for 3D attenuation/panning, or null for plain 2D playback. Mono clips only (OpenAL constraint); pair with Sounds.setListener(limn.math.Vec3, limn.math.Vec3, limn.math.Vec3). Overrides pan
public record PlayOptions(float gain, float pitch, float pan, boolean loop, AudioBus bus, PlayOptions.Priority priority, Vec3 position) extends Record
How to play a sound: volume, pitch, stereo pan or 3D position, looping, mixer bus and voice-steal PlayOptions.Priority. Immutable; start from DEFAULTS and derive with the with* methods (Transform3D-style): 

 Sounds.play(step, PlayOptions.DEFAULTS.withPitch(0.9f + random * 0.2f));
 Sounds.play(song, PlayOptions.DEFAULTS.withBus(AudioBus.MUSIC)
         .withPriority(PlayOptions.Priority.HIGH).withLoop(true));

  • Field Details

    • DEFAULTS

      public static final PlayOptions DEFAULTS
      Gain 1, pitch 1, centered, no loop, AudioBus.SFX, NORMAL priority, 2D.

  • Constructor Details

    • PlayOptions

      public PlayOptions(float gain, float pitch, float pan, boolean loop, AudioBus bus, PlayOptions.Priority priority, Vec3 position)
      Creates an instance of a PlayOptions record class.
      Parameters:
      gain - the value for the gain record component
      pitch - the value for the pitch record component
      pan - the value for the pan record component
      loop - the value for the loop record component
      bus - the value for the bus record component
      priority - the value for the priority record component
      position - the value for the position record component

  • Method Details

    • withGain

      public PlayOptions withGain(float newGain)
      A copy at a different volume, [0..1].

    • withPitch

      public PlayOptions withPitch(float newPitch)
      A copy at a different playback rate, [0.25..4], where 1 is natural.

    • withPan

      public PlayOptions withPan(float newPan)
      A copy at a different stereo position, [-1..1]. Ignored for stereo clips.

    • withLoop

      public PlayOptions withLoop(boolean newLoop)
      A copy that repeats until stopped.

    • withBus

      public PlayOptions withBus(AudioBus newBus)
      A copy routed through a different mixer bus.

    • withPriority

      public PlayOptions withPriority(PlayOptions.Priority newPriority)
      A copy in a different voice-steal class.

    • at

      public PlayOptions at(float x, float y, float z)
      Positional 3D playback at (x, y, z): mono clips only.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • gain

      public float gain()
      Returns the value of the gain record component.
      Returns:
      the value of the gain record component

    • pitch

      public float pitch()
      Returns the value of the pitch record component.
      Returns:
      the value of the pitch record component

    • pan

      public float pan()
      Returns the value of the pan record component.
      Returns:
      the value of the pan record component

    • loop

      public boolean loop()
      Returns the value of the loop record component.
      Returns:
      the value of the loop record component

    • bus

      public AudioBus bus()
      Returns the value of the bus record component.
      Returns:
      the value of the bus record component

    • priority

      public PlayOptions.Priority priority()
      Returns the value of the priority record component.
      Returns:
      the value of the priority record component

    • position

      public Vec3 position()
      Returns the value of the position record component.
      Returns:
      the value of the position record component