fmod 0.9.1 → 0.9.2

data/lib/fmod/core/init_flags.rb

@@ -1,18 +1,84 @@
 module FMOD
   module Core
+
+    ##
+    # Initialization flags. Use them with System.create in the flags parameter
+    # to change various behavior.
+    #
+    # Use System advanced settings to adjust settings for some of the features
+    # that are enabled by these flags.
     module InitFlags
+
+      ##
+      # Initialize normally.
       NORMAL = 0x00000000
+
+      ##
+      # No stream thread is created internally. Streams are driven from
+      # System.update. Mainly used with non-realtime outputs.
       STREAM_FROM_UPDATE = 0x00000001
+
+      ##
+      # No mixer thread is created internally. Mixing is driven from
+      # System.update.
       MIX_FROM_UPDATE = 0x00000002
+
+      ##
+      # 3D calculations will be performed in right-handed coordinates.
       RIGHT_HANDED_3D = 0x00000004
+
+      ##
+      # Enables usage of Channel low-pass gain, Channel occlusion, or automatic
+      # usage by the Geometry API. All voices will add a software low-pass
+      # filter effect into the DSP chain which is idle unless one of the
+      # previous functions/features are used.
       CHANNEL_LOW_PASS = 0x00000100
+
+      ##
+      # All FMOD 3D based voices will add a software low-pass and high-pass
+      # filter effect into the DSP chain which will act as a distance-automated
+      # bandpass filter. Use System advanced settings to adjust the center
+      # frequency.
       CHANNEL_DISTANCE_FILTER = 0x00000200
+
+      ##
+      # Enable TCP/IP based host which allows FMOD Designer or FMOD Profiler to
+      # connect to it, and view memory, CPU and the DSP network graph in
+      # real-time.
       PROFILE_ENABLE = 0x00010000
+
+      ##
+      # Any sounds that are 0 volume will go virtual and not be processed except
+      # for having their positions updated virtually. Use System advanced
+      # settings to adjust what volume besides zero to switch to virtual at.
       VOL0_BECOMES_VIRTUAL = 0x00020000
+
+      ##
+      # With the geometry engine, only process the closest polygon rather than
+      # accumulating all polygons the sound to listener line intersects.
       GEOMETRY_USE_CLOSEST = 0x00040000
+
+      ##
+      # When using a 5.1 speaker mode with a stereo output device, use the Dolby
+      # Pro Logic II down-mix algorithm instead of the SRS Circle Surround
+      # algorithm.
       PREFER_DOLBY_DOWN_MIX = 0x00080000
+
+      ##
+      # Disables thread safety for API calls. Only use this if FMOD low level is
+      # being called from a single thread, and if Studio API is not being used!
       THREAD_UNSAFE = 0x00100000
+
+      ##
+      # Slower, but adds level metering for every single DSP unit in the graph.
       PROFILE_METER_ALL = 0x00200000
+
+      ##
+      # Using a 5.1 speaker mode with a stereo output device will enable the SRS
+      # Circle Surround down-mixer. By default the SRS down-mixer applies a high
+      # pass filter with a cutoff frequency of 80Hz. Use this flag to disable
+      # the high pass filter, or use {PREFER_DOLBY_DOWN_MIX} to use the Dolby
+      # Pro Logic II down-mix algorithm instead.
       DISABLE_SRS_HIGH_PASS_FILTER = 0x00400000
     end
   end

data/lib/fmod/core/integer_description.rb

@@ -1,22 +1,42 @@
 module FMOD
   module Core
+
+    ##
+    # Structure describing a integer parameter for a DSP unit.
     class IntegerDescription < Structure
 
+      ##
+      # @param address [Pointer, Integer, String, nil] The address in memory
+      #   where the structure will be created from. If no address is given, new
+      #   memory will be allocated.
       def initialize(address = nil)
         types = [TYPE_INT, TYPE_INT, TYPE_INT, TYPE_INT, TYPE_VOIDP]
         members = [:min, :max, :default, :infinite, :names]
         super(address, types, members)
       end
 
+      # @!attribute min
+      # @return [Integer] the minimum parameter value.
+
+      # @!attribute max
+      # @return [Integer] the maximum parameter value.
+
+      # @!attribute default
+      # @return [Integer] the default parameter value.
+
       [:min, :max, :default].each do |symbol|
         define_method(symbol) { self[symbol] }
       end
 
-      def infinite
+      ##
+      # @return [Boolean] flag indicating if the last value represents infinity.
+      def infinite?
         self[:infinite] != 0
       end
 
-      def names
+      ##
+      # @return [Array<String>] the names for each value.
+      def value_names
         return [] if self[:names].null?
         count = max - min + 1
         (0...count).map { |i| (self[:names] + (i * SIZEOF_INTPTR_T)).ptr.to_s }

data/lib/fmod/core/output_type.rb

@@ -1,29 +1,108 @@
 module FMOD
   module Core
+
+    ##
+    # Strongly-typed supported output types.
     module OutputType
-      AUTODETECT = 0
+
+      ##
+      # Picks the best output mode for the platform. This is the default.
+      AUTO_DETECT = 0
+
+      ##
+      # All - 3rd party plugin, unknown.
       UNKNOWN = 1
+
+      ##
+      # All - Perform all mixing but discard the final output.
       NO_SOUND = 2
+
+      ##
+      # All - Writes output to a .wav file.
       WAV_WRITER = 3
-      NOSOUND_NRT = 4
+
+      ##
+      # All - Non-realtime version of {NO_SOUND}. User can drive mixer with
+      # System.update at whatever rate they want.
+      NO_SOUND_NRT = 4
+
+      ##
+      # All - Non-realtime version of {WAV_WRITER}. User can drive mixer with
+      # System.update at whatever rate they want.
       WAV_WRITER_NRT = 5
+
+      ##
+      # Windows only - Direct Sound. (Default on Windows XP and below)
       DSOUND = 6
+
+      ##
+      # Windows only - Windows Multimedia.
       WINMM = 7
+
+      ##
+      # Win/WinStore/XboxOne - Windows Audio Session API. (Default on Windows
+      # Vista and above, Xbox One and Windows Store Applications)
       WASAPI = 8
+
+      ##
+      # Windows only - Low latency ASIO 2.0.
       ASIO = 9
+
+      ##
+      # Linux - Pulse Audio. (Default on Linux if available)
       PULSE_AUDIO = 10
+
+      ##
+      # Linux - Advanced Linux Sound Architecture. (Default on Linux if
+      # PulseAudio isn't available)
       ALSA = 11
+
+      ##
+      # Mac/iOS - Core Audio. (Default on Mac and iOS)
       CORE_AUDIO = 12
+
+      ##
+      # Xbox 360 - XAudio. (Default on Xbox 360)
       X_AUDIO = 13
+
+      ##
+      # PS3 - Audio Out. (Default on PS3)
       PS3 = 14
+
+      ##
+      # Android - Java Audio Track. (Default on Android 2.2 and below)
       AUDIO_TRACK = 15
+
+      ##
+      # Android - OpenSL ES. (Default on Android 2.3 and above)
       OPEN_SL = 16
+
+      ##
+      # Wii U - AX. (Default on Wii U)
       WII_U = 17
+
+      ##
+      # PS4/PSVita - Audio Out. (Default on PS4 and PS Vita)
       AUDIO_OUT, = 18
+
+      ##
+      # PS4 - Audio3D.
       AUDIO3D = 19
+
+      ##
+      # Windows - Dolby Atmos (WASAPI).
       ATMOS = 20
+
+      ##
+      # Web Browser - JavaScript webaudio output. (Default on JavaScript)
       WEB_AUDIO = 21
+
+      ##
+      # NX - NX nn::audio. (Default on NX)
       NN_AUDIO = 22
+
+      ##
+      # Win10 / XboxOne - Windows Sonic.
       WIN_SONIC = 23
     end
   end

data/lib/fmod/core/parameter_info.rb

@@ -1,31 +1,67 @@
 module FMOD
   module Core
+
+    ##
+    # Base Structure for DSP parameter descriptions.
     class ParameterInfo < Structure
 
       include Fiddle
 
+      ##
+      # @param address [Pointer, Integer, String, nil] The address in memory
+      #   where the structure will be created from. If no address is given, new
+      #   memory will be allocated.
       def initialize(address = nil)
         types = [TYPE_INT, [TYPE_CHAR, 16], [TYPE_CHAR, 16], TYPE_VOIDP, TYPE_VOIDP]
         members = [:type, :name, :label, :description, :info]
         super(address, types, members)
       end
 
+      ##
+      # @!attribute [r] type
+      # @return [Integer] the type of this parameter.
+      #   @see ParameterType
+
       def type
         self[:type]
       end
 
+      ##
+      # @!attribute [r] name
+      # @return [String] the of the parameter to be displayed (ie "Cutoff
+      #   frequency").
+
       def name
         (self + SIZEOF_INT).to_s(16).delete("\0").force_encoding('UTF-8')
       end
 
+      ##
+      # @!attribute [r] label
+      # @return [String] a string to be put next to value to denote the unit
+      #   type (ie "Hz").
+
       def label
         (self + SIZEOF_INT + 16).to_s(16).delete("\0")
       end
 
+      ##
+      # @!attribute [r] description
+      # @return [String] the description of the parameter to be displayed as a
+      #   help item / tooltip for this parameter.
       def description
         self[:description].to_s
       end
 
+      ##
+      # Struct containing information about the parameter. The type of info
+      # will vary depending on the {#type} value.
+      # * {ParameterType::FLOAT} => {FloatDescription}
+      # * {ParameterType::INT} => {IntegerDescription}
+      # * {ParameterType::BOOL} => {BoolDescription}
+      # * {ParameterType::DATA} => {DataDescription}
+      #
+      # @return [FloatDescription, IntegerDescription, BoolDescription,
+      #   DataDescription] the parameter type description.
       def info
         pointer = self + SIZEOF_INT + (SIZEOF_CHAR * 32) + SIZEOF_INTPTR_T
         case self[:type]

data/lib/fmod/core/parameter_type.rb

@@ -1,9 +1,24 @@
 module FMOD
   module Core
+
+    ##
+    # DSP parameter types.
     module ParameterType
+
+      ##
+      # A float type parameter.
       FLOAT = 0
+
+      ##
+      # An integer type parameter.
       INT = 1
+
+      ##
+      # A boolean type parameter.
       BOOL = 2
+
+      ##
+      # A data type parameter.
       DATA = 3
     end
   end

data/lib/fmod/core/reverb.rb

@@ -3,14 +3,19 @@
 module FMOD
 
   module Core
+
     ##
     # Structure defining a reverb environment.
     class Reverb < Structure
 
+      ##
+      # @param address [Pointer, Integer, String, nil] The address in memory
+      #   where the structure will be created from. If no address is given, new
+      #   memory will be allocated.
       def initialize(address = nil)
         types = Array.new(12, TYPE_FLOAT)
-        members = [:decay_time, :early_delay, :late_delay,
-                   :hf_reference, :hf_decay_ratio, :diffusion, :density, :low_shelf_freq,
+        members = [:decay_time, :early_delay, :late_delay, :hf_reference,
+                   :hf_decay_ratio, :diffusion, :density, :low_shelf_freq,
                    :low_shelf_gain, :high_cut, :early_late_mix, :wet_level]
         super(address, types, members)
       end
@@ -21,54 +26,160 @@ module FMOD
         define_method(symbol) {self[symbol]}
       end
 
+      # @!attribute decay_time
+      # Reverberation decay time (ms).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 20000.0
+      # * *Default:* 1500.0
       def decay_time=(value)
         self[:decay_time] = value.clamp(0.0, 20000.0)
       end
 
+      # @!attribute early_delay
+      # Initial reflection delay time (ms).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 300.0
+      # * *Default:* 7.0
+      # @return [Float]
       def early_delay=(value)
         self[:early_delay] = value.clamp(0.0, 300.0)
       end
 
+      # @!attribute late_delay
+      # Late reverberation delay time relative to initial reflection (ms).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 100.0
+      # * *Default:* 11.0
+      # @return [Float]
       def late_delay=(value)
         self[:late_delay] = value.clamp(0.0, 100.0)
       end
 
+      # @!attribute hf_reference
+      # Reference high frequency (Hz).
+      # * *Minimum:* 20.0
+      # * *Maximum:* 20000.0
+      # * *Default:* 5000.0
+      # @return [Float]
       def hf_reference=(value)
         self[:hf_reference] = value.clamp(20.0, 20000.0)
       end
 
+      # @!attribute hf_decay_ratio
+      # High-frequency to mid-frequency decay time ratio (%).
+      # * *Minimum:* 10.0
+      # * *Maximum:* 100.0
+      # * *Default:* 50.0
+      # @return [Float]
       def hf_decay_ratio=(value)
         self[:hf_decay_ratio] = value.clamp(10.0, 100.0)
       end
 
+      # @!attribute diffusion
+      # The echo density in the late reverberation decay (%).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 100.0
+      # * *Default:* 100.0
+      # @return [Float]
       def diffusion=(value)
         self[:diffusion] = value.clamp(0.0, 100.0)
       end
 
+      # @!attribute density
+      # The modal density in the late reverberation decay (%).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 100.0
+      # * *Default:* 100.0
+      # @return [Float]
       def density=(value)
         self[:density] = value.clamp(0.0, 100.0)
       end
 
+      # @!attribute low_shelf_freq
+      # Reference low frequency (Hz).
+      # * *Minimum:* 20.0
+      # * *Maximum:* 1000.0
+      # * *Default:* 250.0
+      # @return [Float]
       def low_shelf_freq=(value)
         self[:low_shelf_freq] = value.clamp(20.0, 1000.0)
       end
 
+      # @!attribute low_shelf_gain
+      # Relative room effect level at low frequencies (dB).
+      # * *Minimum:* -36.0
+      # * *Maximum:* 12.0
+      # * *Default:* 0.0
+      # @return [Float]
       def low_shelf_gain=(value)
         self[:low_shelf_gain] = value.clamp(-36.0, 12.0)
       end
 
+      # @!attribute high_cut
+      # Relative room effect level at high frequencies (Hz).
+      # * *Minimum:* 20.0
+      # * *Maximum:* 20000.0
+      # * *Default:* 20000.0
+      # @return [Float]
       def high_cut=(value)
         self[:high_cut] = value.clamp(20.0, 20000.0)
       end
 
+      # @!attribute early_late_mix
+      # Early reflections level relative to room effect (%).
+      # * *Minimum:* 0.0
+      # * *Maximum:* 100.0
+      # * *Default:* 50.0
+      # @return [Float]
       def early_late_mix=(value)
         self[:early_late_mix] = value.clamp(0.0, 100.0)
       end
 
+      # @!attribute wet_level
+      # Room effect level at mid frequencies (dB).
+      # * *Minimum:* -80.0
+      # * *Maximum:* 20.0
+      # * *Default:* -6.0
+      # @return [Float]
       def wet_level=(value)
         self[:wet_level] = value.clamp(-80.0, 20.0)
       end
 
+      ##
+      # Returns a pre-mad Reverb preset from the specified {ReverbIndex}.
+      #
+      # @param index [Integer] The index of the preset to retrieve.
+      #
+      # @return [Reverb] the reverb preset.
+      def self.from_index(index)
+        case index
+        when ReverbIndex::GENERIC then generic
+        when ReverbIndex::PADDED_CELL then padded_cell
+        when ReverbIndex::ROOM then room
+        when ReverbIndex::BATHROOM then bathroom
+        when ReverbIndex::LIVING_ROOM then living_room
+        when ReverbIndex::STONE_ROOM then stone_room
+        when ReverbIndex::AUDITORIUM then auditorium
+        when ReverbIndex::CONCERT_HALL then concert_hall
+        when ReverbIndex::CAVE then cave
+        when ReverbIndex::ARENA then arena
+        when ReverbIndex::HANGAR then hangar
+        when ReverbIndex::CARPETED_HALLWAY then carpeted_hallway
+        when ReverbIndex::HALLWAY then hallway
+        when ReverbIndex::STONE_CORRIDOR then stone_corridor
+        when ReverbIndex::ALLEY then alley
+        when ReverbIndex::FOREST then forest
+        when ReverbIndex::CITY then city
+        when ReverbIndex::MOUNTAINS then mountains
+        when ReverbIndex::QUARRY then quarry
+        when ReverbIndex::PLAIN then plain
+        when ReverbIndex::PARKING_LOT then parking_lot
+        when ReverbIndex::SEWER_PIPE then sewer_pipe
+        when ReverbIndex::UNDERWATER then underwater
+        else off
+        end
+      end
+
       ##
       # @return [Reverb] no reverberation.
       def self.off