fmod 0.9.1 → 0.9.2

data/lib/fmod/core/reverb_index.rb

@@ -0,0 +1,105 @@
+module FMOD
+  module Core
+
+    ##
+    # Strongly-typed indices for built-in reverb effects.
+    module ReverbIndex
+
+      ##
+      # No reverb.
+      OFF = 0
+
+      ##
+      # Generic reverb effect.
+      GENERIC = 1
+
+      ##
+      # Padded cell environment
+      PADDED_CELL = 2
+
+      ##
+      # Room environment
+      ROOM = 3
+
+      ##
+      # Bathroom environment
+      BATHROOM = 4
+
+      ##
+      # Living room environment
+      LIVING_ROOM = 5
+
+      ##
+      # Stone corridor environment
+      STONE_ROOM = 6
+
+      ##
+      # Auditorium environment
+      AUDITORIUM = 7
+
+      ##
+      # Concert hall environment
+      CONCERT_HALL = 8
+
+      ##
+      # Cave environment
+      CAVE = 9
+
+      ##
+      # Arena environment
+      ARENA = 10
+
+      ##
+      # Hangar environment
+      HANGAR = 11
+
+      ##
+      # Carpeted hallway environment
+      CARPETED_HALLWAY = 12
+
+      ##
+      # Hallway environment
+      HALLWAY = 13
+
+      ##
+      # Stone corridor environment
+      STONE_CORRIDOR = 14
+
+      ##
+      # Alley environment
+      ALLEY = 15
+
+      ##
+      # Forest environment
+      FOREST = 16
+
+      ##
+      # City environment
+      CITY = 17
+
+      ##
+      # Mountains environment
+      MOUNTAINS = 18
+
+      ##
+      # Quarry environment
+      QUARRY = 19
+
+      ##
+      # Plain environment
+      PLAIN = 20
+
+      ##
+      # Parking lot environment
+      PARKING_LOT = 21
+
+      ##
+      # Sewer pip environment
+      SEWER_PIPE = 22
+
+      ##
+      # Underwater environment
+      UNDERWATER = 23
+    end
+  end
+end

data/lib/fmod/core/sound_ex_info.rb

@@ -1,5 +1,9 @@
 module FMOD
   module Core
+
+    ##
+    # Use this structure with System.create_sound when more control is needed
+    # over loading.
     class SoundExInfo < Structure
       # TODO
     end

data/lib/fmod/core/sound_group_behavior.rb

@@ -1,8 +1,22 @@
 module FMOD
   module Core
+
+    ##
+    # These values are used with to determine what happens when more sounds are
+    # played than are specified.
     module SoundGroupBehavior
+
+      ##
+      # Will simply fail when attempting to play.
       FAIL = 0
+
+      ##
+      # Will be silent, then if another sound in the group stops the sound that
+      # was silent before becomes audible again.
       MUTE = 1
+
+      ##
+      # Will steal the quietest / least important sound playing in the group.
       STEAL_LOWEST = 2
     end
   end

data/lib/fmod/core/sound_type.rb

@@ -4,6 +4,7 @@ module FMOD
     ##
     # These definitions describe the type of song being played.
     module SoundType
+
       ##
       # 3rd party / unknown plugin format.
       UNKNOWN = 0

data/lib/fmod/core/spectrum_data.rb

@@ -1,12 +1,47 @@
 module FMOD
   module Core
+
+    ##
+    # Describes spectrum values between 0.0 and 1.0 for each "FFT bin".
     class SpectrumData < 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_FLOAT, 32]]
         members = [:length, :channel_count, :spectrum]
         super(address, types, members)
       end
+
+      # @!attribute [r] length
+      # @return [Integer] the number of entries in this spectrum window. Divide
+      #   this by the output rate to get the hz per entry.
+      # @since 0.9.2
+
+      # @!attribute [r] channel_count
+      # @return [Integer] the number of channels in the spectrum.
+      # @since 0.9.2
+
+      # @!attribute [r] spectrum
+      # Values inside the float buffer are typically between 0.0 and 1.0.
+      #
+      # Each top level array represents one PCM channel of data.
+      #
+      # Address data as spectrum[channel][bin]. A bin is 1 FFT window entry.
+      #
+      # Only read/display half of the buffer typically for analysis as the 2nd
+      # half is usually the same data reversed due to the nature of the way FFT
+      # works.
+      #
+      # @todo Test for proper structure
+      # @return [Array<Float>] per channel spectrum arrays.
+      # @since 0.9.2
+
+      [:length, :channel_count, :spectrum].each do |symbol|
+        define_method(symbol) { self[symbol] }
+      end
     end
   end
 end

data/lib/fmod/core/structures.rb

@@ -3,12 +3,18 @@ module FMOD
 
   module Core
 
-    WetDryMix = Struct.new(:pre_wet, :post_wet, :dry)
-
+    ##
+    # Describes the loop points for the channel.
+    # @attr start [Integer] The  loop start point, this point in time is played
+    #   so it is inclusive.
+    # @attr start_unit [Integer] Time format used for the loop start point. See
+    #   {TimeUnit}.
+    # @attr end [Integer] The loop end point, this point in time is played so it
+    #   is inclusive.
+    # @attr end_unit [Integer] Time format used for the loop end point. See
+    #   {TimeUnit}.
     LoopPoints = Struct.new(:start, :start_unit, :end, :end_unit)
 
-    FadePoint = Struct.new(:clock, :volume)
-
     ##
     # Defines the sound projection cone including the volume when outside the
     # cone.

data/lib/fmod/core/tag.rb

@@ -1,27 +1,95 @@
 module FMOD
   module Core
+
+    ##
+    # Structure describing a piece of tag data.
     class Tag < Structure
 
       include Fiddle
 
+      ##
+      # Strings for ID3v1 tags that use a number to represent the genre. That
+      # number can be used as an index into this array to retrieve the name for
+      # the genre.
+      #
+      # @since 0.9.2
+      ID3V1_GENRES = %w[
+        Blues Classic\ Rock Country Dance Disco Funk Grunge Hip-Hop Jazz Metal
+        New\ Age Oldies Other Pop R&B Rap Reggae Rock Techno Industrial
+        Alternative Ska Death\ Metal Pranks Soundtrack Euro-Techno Ambient
+        Trip-Hop Vocal Jazz+Funk Fusion Trance Classical Instrumental Acid House
+        Game Sound\ Clip Gospel Noise Alternative\ Rock Bass Soul Punk Space
+        Meditative Instrumental\ Pop Instrumental\ Rock Ethnic Gothic Darkwave
+        Techno-Industrial Electronic Pop-Folk Eurodance Dream Southern\ Rock
+        Comedy Cult Gangsta Top\ 40 Christian\ Rap Pop/Funk Jungle Native\
+        American Cabaret New\ Wave Psychedelic Rave Showtunes Trailer Lo-Fi
+        Tribal Acid\ Punk Acid\ Jazz Polka Retro Musical Rock\ &\ Roll Hard\
+        Rock Folk Folk/Rock National\ Folk Swing Fusion Bebob Latin Revival
+        Celtic Bluegrass Avantgarde Gothic\ Rock Progressive\ Rock Psychedelic\
+        Rock Symphonic\ Rock Slow\ Rock Big\ Band Chorus Easy\ Listening
+        Acoustic Humour Speech Chanson Opera Chamber\ Music Sonata Symphony
+        Booty\ Bass Primus Porn\ Groove Satire Slow\ Jam Club Tango Samba
+        Folklore Ballad Power\ Ballad Rhythmic\ Soul Freestyle Duet Punk\ Rock
+        Drum\ Solo A\ Cappella Euro-House Dance\ Hall Goa Drum\ &\ Bass
+        Club-House Hardcore Terror Indie BritPop Negerpunk Polsk\ Punk Beat
+        Christian\ Gangsta\ Rap Heavy\ Metal Black\ Metal Crossover
+        Contemporary\ Christian Christian\ Rock Merengue Salsa Thrash\ Metal
+        Anime Jpop Synthpop Abstract Art\ Rock Baroque Bhangra Big\ Beat
+        Breakbeat Chillout Downtempo Dub EBM Eclectic Electro Electroclash Emo
+        Experimental Garage Global IDM Illbient Industro-Goth Jam\ Band
+        Krautrock Leftfield Lounge Math\ Rock New\ Romantic Nu-Breakz Post-Punk
+        Post-Rock Psytrance Shoegaze Space\ Rock Trop\ Rock World\ Music
+        Neoclassical Audiobook Audio\ Theatre Neue\ Deutsche\ Welle Podcast
+        Indie-Rock G-Funk Dubstep Garage\ Rock Psybient
+      ].freeze
+
+      ##
+      # @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_VOIDP, TYPE_VOIDP, TYPE_INT, TYPE_INT]
         members = [:type, :data_type, :name, :data, :data_length, :updated]
         super(address, types, members)
       end
 
+      ##
+      # @!attribute [r] type
+      # @return [Integer] the type of this tag.
+      #   @see TagType
+
+      ##
+      # @!attribute [r] data_type
+      # @return [Integer] the type of data that this tag contains.
+      #   @see TagDataType
+
+      ##
+      # @!attribute [r] data_length
+      # @return [Integer] the length of the data contained in this tag in bytes.
+
       [:type, :data_type, :data_length].each do |symbol|
         define_method(symbol) { self[symbol] }
       end
 
+      ##
+      # @!attribute [r] name
+      # @return [String] the name of this tag i.e. "TITLE", "ARTIST" etc.
       def name
         self[:name].to_s
       end
 
-      def updated
+      ##
+      # @return [Boolean] a flag indicating if this tag has been updated sinc
+      #   last being accessed.
+      def updated?
         self[:updated] != 0
       end
 
+      ##
+      # Retrieves the tag data, which can vary depending on the value specified
+      # in {#data_type}.
+      # @return [String, Float, Integer] the tag data.
+      # @see TagDataType
       def value
         raw = self[:data].to_s(self[:data_length])
         raw.delete!("\0") unless self[:data_type] == TagDataType::BINARY
@@ -37,15 +105,8 @@ module FMOD
         else ''
         end
       end
-
-      def to_s
-        begin
-          "#{value}"
-        rescue Encoding::CompatibilityError
-          value.inspect
-          # TODO
-        end
-      end
     end
   end
-end
+end
+
+

data/lib/fmod/core/tag_data_type.rb

@@ -1,14 +1,44 @@
 module FMOD
   module Core
+
+    ##
+    # Strongly-typed values for indicating the data types used in music tags.
     module TagDataType
+
+      ##
+      # Raw binary data.
       BINARY = 0
+
+      ##
+      # A 32-bit integer
       INT = 1
+
+      ##
+      # A 32-bit floating point value
       FLOAT = 2
+
+      ##
+      # A string with no specified encoding.
       STRING = 3
+
+      ##
+      # A UTF-16 encoded string.
       STRING_UTF16 = 4
+
+      ##
+      # A UTF-16 Big-Endian string.
       STRING_UTF16BE = 5
+
+      ##
+      # A UTF-8 encoded string.
       STRING_UTF8 = 6
+
+      ##
+      # @deprecated Do not use.
+      # A CDTOC tag.
       CDTOC = 7
+
+      deprecate_constant :CDTOC
     end
   end
 end

data/lib/fmod/core/tag_type.rb

@@ -0,0 +1,55 @@
+module FMOD
+  module Core
+
+    ##
+    # List of tag types that could be stored within a sound. These include id3
+    # tags, metadata from net-streams and vorbis/asf data.
+    # @since 0.9.2
+    module TagType
+
+      ##
+      # Unknown
+      UNKNOWN = 0
+
+      ##
+      # ID3V1
+      ID3V1 = 1
+
+      ##
+      # ID3V2
+      ID3V2 = 2
+
+      ##
+      # Vorbis Comment
+      VORBIS_COMMENT = 3
+
+      ##
+      # ShoutCast
+      SHOUT_CAST = 4
+
+      ##
+      # IceCast
+      ICE_CAST = 5
+
+      ##
+      # ASF
+      ASF = 6
+
+      ##
+      # MIDI
+      MIDI = 7
+
+      ##
+      # Play list
+      PLAYLIST = 8
+
+      ##
+      # FMOD
+      FMOD = 9
+
+      ##
+      # User
+      USER = 10
+    end
+  end
+end

data/lib/fmod/core/time_unit.rb

@@ -1,5 +1,8 @@
 module FMOD
   module Core
+
+    ##
+    # Strongly-typed values for indicating various units of time.
     module TimeUnit
 
       ##

data/lib/fmod/core/vector.rb

@@ -1,18 +1,31 @@
 module FMOD
   module Core
-    # @attr x [Float]
-    # @attr y [Float]
-    # @attr z [Float]
+
+    ##
+    # Structure describing a point in 3D space.
     class Vector < Structure
 
+      ##
+      # @return [Vector] a new {Vector} with all values set to 0.0.
       def self.zero
         new(0.0, 0.0, 0.0)
       end
 
+      ##
+      # @return [Vector] a new {Vector} with all values set to 1.0.
       def self.one
         new(1.0, 1.0, 1.0)
       end
 
+      ##
+      # @overload initialize(address)
+      #   @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.
+      # @overload initialize(x, y, z)
+      #   @param x [Float] The X coordinate in 3D space.
+      #   @param y [Float] The Y coordinate in 3D space.
+      #   @param z [Float] The Z coordinate in 3D space.
       def initialize(*args)
         address ||= args.size == 1 ? args.first : nil
         members = [:x, :y, :z]
@@ -21,19 +34,43 @@ module FMOD
         set(*args) if args.size == 3
       end
 
+      # @!attribute x
+      # @return [Float] the X coordinate in 3D space.
+
+      # @!attribute y
+      # @return [Float] the Y coordinate in 3D space.
+
+      # @!attribute z
+      # @return [Float] the Z coordinate in 3D space.
+
       [:x, :y, :z].each do |symbol|
         define_method(symbol) { self[symbol] }
         define_method("#{symbol}=") { |value| self[symbol] = value.to_f }
       end
 
+      ##
+      # Helper function to set the {#x}, {#y}, and {#z} values simultaneously.
+      #
+      # @param x [Float] The X coordinate in 3D space.
+      # @param y [Float] The Y coordinate in 3D space.
+      # @param z [Float] The Z coordinate in 3D space.
+      #
+      # @return [self]
       def set(x, y, z)
         self[:x], self[:y], self[:z] = x, y, z
+        self
       end
 
+      ##
+      # @return [Array(Float, Float, Float)] the result of interpreting the
+      #   vector as an Array.
       def to_a
         @members.map { |sym| self[sym] }
       end
 
+      ##
+      # @return [Hash<Symbol, Float>] the result of interpreting the vector as a
+      #   Hash.
       def to_h
         { x: self[:x], y: self[:y], z: self[:z] }
       end