fmod 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d2902236224e5d663766bcc5b5fb7c48147aa20
-  data.tar.gz: a8b3106722a1da66d22ec30902a24bedaacec0ab
+  metadata.gz: ab0b3cff45deeb4271467582cab4249c7841e315
+  data.tar.gz: d087b00bd2bfecea2864e9eddb927104ce5ffe96
 SHA512:
-  metadata.gz: 1c651d58f0ae40f3c5f615e9bb0a1435b43f07f8d86f0c8dae6441cf8b704a35bdfa3a74a39b08b2ca9ad50000f278a0582ff8a31a5dda0a704be1826fe9651b
-  data.tar.gz: b77425a784f7f48c5687f693f013aab28c48ebd9267664a90b74a43f9c67254534af7ac71479793d135b2a51a70809f7c8cf322e9e35d91dd327c4f6b8d059f3
+  metadata.gz: 7dbef60ec374a31a856f152ba889c61c508888556c7219aafd1eb3c851f88753e59b195aa3a6a1eb50ce038d69c5f3e946aee66e94942e21f7ca9771ab1e67ae
+  data.tar.gz: bac72c7849c3cd063f5260c05fe771ac0a6e078279c4cf9a71f200f4fc6bdce68fd0f6d8beaca54b88ce011962a6d40b4ec83cedd8aa6a1735f743945651a0c0

data/HISTORY.txt

@@ -1,4 +1,26 @@
-=== 0.9.1 /  2018-07-10
+=== 0.9.2 / 2018/07/11
+
+* Added ReverbIndex class
+
+* Added .from_index class function to Reverb class
+
+* Implemented skeleton DspDescription structure
+
+* Deprecated constants in DspType:
+    * LOW_PASS
+    * LOW_PASS_SIMPLE
+    * HIGH_PASS
+    * HIGH_PASS_SIMPLE
+    * LADSPA_PLUGIN
+
+* Deprecated constants in Effects:
+    * LowPass
+    * LowPassSimple
+    * HighPass
+    * HighPassSimple
+    * LadspaPlugin
+
+=== 0.9.1 / 2018-07-10
 
 * Added Features
     * Expanded methods to FMOD::Core::Structure

data/README.md

@@ -1,6 +1,6 @@
 # FMOD
 
-[![Gem Version](https://badge.fury.io/rb/fmod.svg)](https://badge.fury.io/rb/fmod) ![Documentation](https://img.shields.io/badge/Documentation-71%25-orange.svg)
+[![Gem Version](https://badge.fury.io/rb/fmod.svg)](https://badge.fury.io/rb/fmod) ![Documentation](https://img.shields.io/badge/Documentation-99.22%25-green.svg)
 
 
 A full-featured (*complete* Ruby wrapper) of the ultra-powerful FMOD Low-Level API. Uses the built-in Fiddle library (Ruby 2.0+), and has no external gem dependencies, all that is needed is the native FMOD platform-specific native FMOD libraries.
@@ -72,8 +72,6 @@ Each get/set method in the FMOD API has been converted to an "attribute" that ca
 
 ## Future Releases
 
-As of the current release, only slightly better than 71% of documentation is complete. The scripts are highly technical, and good documentation takes time, but it is actively being updated, and will be completed at the highest priority level. If you are using version `1.0.0`, you will have to rely more heavily upon the included FMOD Low-Level API Reference that is included in the `./extras` folder.
-
 There is still yet to be a few areas that need completed, and are in active development. Included are the following known issues:
    * FMOD plugin support (including 3rd party codecs)
    * Loading custom sound formats (related to plugin support)

data/Rakefile

@@ -1 +1,2 @@
-require "bundler/gem_tasks"
+require "bundler/gem_tasks"
+

data/bin/console

@@ -4,6 +4,7 @@ require 'bundler/setup'
 require 'fmod'
 require 'irb'
 
+
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 

data/fmod.gemspec

@@ -9,8 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Eric "ForeverZer0" Freed']
   spec.email         = ['efreed09@gmail.com']
   spec.summary       = %q{Ruby wrapper around the high performance, cross-platform FMOD low-level sound library. You get all the benefits of the FMOD library, but in the object-oriented Ruby way!}
-  spec.description   = %q{A full-featured (complete Ruby wrapper) of the ultra-powerful FMOD Low-Level API. Uses the built-in Fiddle library (Ruby 2.0+), and has no external gem dependencies, all that is needed is the FMOD platform-specific libraries (included). FMOD supports a host of audio formats including .aiff, .asf, .asx, .dls, .flac, .fsb, .it, .m3u, .mid, .midi, .mod, .mp2, .mp3, .ogg .pls, .s3m , vag, .wav, .wax, .wma, .xm, and.xma.}
-
+  spec.description   = %q{A full-featured (complete Ruby wrapper) of the ultra-powerful FMOD Low-Level API. Uses the built-in Fiddle library (Ruby 2.0+), and has no external gem dependencies, all that is needed is the FMOD platform-specific libraries (included). FMOD supports a host of audio formats including .aiff, .asf, .asx, .dls, .flac, .fsb, .it, .m3u, .mid, .midi, .mod, .mp2, .mp3, .ogg .pls, .s3m , vag, .wav, .wax, .wma, .xm, and .xma.}
   spec.homepage      = 'https://github.com/ForeverZer0/fmod'
   spec.license       = 'MIT'
   spec.has_rdoc      = 'yard'

data/lib/fmod/channel_control.rb

@@ -6,6 +6,16 @@ module FMOD
   # The base class for both {Channel} and {ChannelGroup} objects.
   class ChannelControl < Handle
 
+    ##
+    # Describes a volume point to fade from or towards, using a clock offset and
+    # 0.0 to 1.0 volume level.
+    #
+    # @attr clock [Integer] DSP clock of the parent channel group to set the
+    #   fade point volume.
+    # @attr volume [Float] lume level where 0.0 is silent and 1.0 is normal
+    #   volume. Amplification is supported.
+    FadePoint = Struct.new(:clock, :volume)
+
     ##
     # Emulates an Array-type container of a {ChannelControl}'s DSP chain.
     class DspChain
@@ -520,6 +530,43 @@ module FMOD
       vector
     end
 
+    ##
+    # @!attribute cone_settings
+    # The angles that define the sound projection cone including the volume when
+    # outside the cone.
+    # @since 0.9.2
+    # @return [ConeSettings] the sound projection cone.
+    def cone_settings
+      args = ["\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT, "\0" * SIZEOF_FLOAT]
+      FMOD.invoke(:ChannelGroup_Get3DConeSettings, self, *args)
+      ConeSettings.new(*args.map { |arg| arg.unpack1('f') } )
+    end
+
+    def cone_settings=(settings)
+      FMOD.type?(settings, ConeSettings)
+      set_cone(*settings.values)
+      settings
+    end
+
+    ##
+    # Sets the angles that define the sound projection cone including the volume
+    # when outside the cone.
+    # @param inside_angle [Float] Inside cone angle, in degrees. This is the
+    #   angle within which the sound is at its normal volume.
+    # @param outside_angle [Float] Outside cone angle, in degrees. This is the
+    #   angle outside of which the sound is at its outside volume.
+    # @param outside_volume [Float] Cone outside volume.
+    # @since 0.9.2
+    # @return [void]
+    def set_cone(inside_angle, outside_angle, outside_volume)
+      if outside_angle < inside_angle
+        raise Error, 'Outside angle must be greater than inside angle.'
+      end
+      FMOD.invoke(:ChaennlGroup_Set3DConeSettings, self, inside_angle,
+                  outside_angle, outside_volume)
+      self
+    end
+
     # @!endgroup
 
     ##

data/lib/fmod/core.rb

@@ -27,6 +27,7 @@ module FMOD
     require_relative './core/parameter_info'
     require_relative './core/parameter_type'
     require_relative './core/result'
+    require_relative './core/reverb_index'
     require_relative './core/reverb'
     require_relative './core/sound_ex_info'
     require_relative './core/sound_format'

data/lib/fmod/core/bool_description.rb

@@ -1,18 +1,23 @@
 module FMOD
   module Core
+
+    ##
+    # Structure describing a boolean parameter for a DSP unit.
     class BoolDescription < 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)
         super(address, [TYPE_INT, TYPE_VOIDP], [:default, :names])
       end
 
+      # @!attribute [r] default
+      # @return [Boolean] the default value for the parameter.
       def default
         self[:default] != 0
       end
-
-      def names
-        %w(true false)
-      end
     end
   end
 end

data/lib/fmod/core/channel_mask.rb

@@ -1,23 +1,84 @@
 module FMOD
   module Core
+
+    ##
+    # These are bit-fields to describe for a certain number of channels in a
+    # signal, which channels are being represented.
+    #
+    # For example, a signal could be 1 channel, but contain the LFE channel
+    # only.
     module ChannelMask
+
+      ##
+      # Front-left
       FRONT_LEFT = 0x00000001
+
+      ##
+      # Front-right
       FRONT_RIGHT = 0x00000002
+
+      ##
+      # Front-center
       FRONT_CENTER = 0x00000004
+
+      ##
+      # Low-frequency or sub-woofer
       LOW_FREQUENCY = 0x00000008
+
+      ##
+      # Surround-left
       SURROUND_LEFT = 0x00000010
+
+      ##
+      # Surround-right
       SURROUND_RIGHT = 0x00000020
+
+      ##
+      # Back-left
       BACK_LEFT = 0x00000040
+
+      ##
+      # Back-right
       BACK_RIGHT = 0x00000080
+
+      ##
+      # Back-center
       BACK_CENTER = 0x00000100
+
+      ##
+      # Mono, single speaker
       MONO = FRONT_LEFT
+
+      ##
+      # Stereo
       STEREO = FRONT_LEFT | FRONT_RIGHT
+
+      ##
+      # Left-Right-Center
       LRC = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
+
+      ##
+      # Quads
       QUAD = FRONT_LEFT | FRONT_RIGHT | SURROUND_LEFT | SURROUND_RIGHT
+
+      ##
+      # Surround
       SURROUND = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | SURROUND_LEFT | SURROUND_RIGHT
+
+      ##
+      # 5.1
       FIVE_POINT_ONE = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | LOW_FREQUENCY | SURROUND_LEFT | SURROUND_RIGHT
+
+      ##
+      # 5.1 with Rears
       FIVE_POINT_ONE_REARS = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | LOW_FREQUENCY | BACK_LEFT | BACK_RIGHT
+
+      ##
+      # 7.0 Surround
       SEVEN_POINT_ZERO = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | SURROUND_LEFT | SURROUND_RIGHT | BACK_LEFT | BACK_RIGHT
+
+      ##
+      # 7.1 Surround
       SEVEN_POINT_ONE = FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | LOW_FREQUENCY | SURROUND_LEFT | SURROUND_RIGHT | BACK_LEFT | BACK_RIGHT
     end
   end

data/lib/fmod/core/data_description.rb

@@ -1,11 +1,55 @@
 module FMOD
   module Core
+
+    ##
+    # Structure describing a data parameter for a DSP unit.
     class DataDescription < Structure
 
+      ##
+      # The default data type. All user data types should be 0 or above.
+      TYPE_USER = 0
+
+      ##
+      # The data type for overall-gain parameters. There should a maximum of one
+      # per DSP.
+      TYPE_OVERALLGAIN = 1
+
+      ##
+      # The data type for 3D attribute parameters. There should a maximum of one
+      # per DSP.
+      TYPE_3DATTRIBUTES = 2
+
+      ##
+      # The data type for side-chain parameters. There should a maximum of one
+      # per DSP.
+      TYPE_SIDECHAIN = 3
+
+      ##
+      # The data type for FFT parameters. There should a maximum of one per DSP.
+      TYPE_FFT = 4
+
+      ##
+      # The data type for multiple 3D attribute parameters. There should a
+      # maximum of one per DSP.
+      TYPE_3DATTRIBUTES_MULTI = 5
+
+      ##
+      # @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)
         super(address, [TYPE_INT], [:data_type])
       end
 
+      ##
+      # The type of data for this parameter. Use 0 or above for custom types or
+      # set to one of the following are possible values:
+      # * {TYPE_USER}
+      # * {TYPE_OVERALLGAIN}
+      # * {TYPE_3DATTRIBUTES}
+      # * {TYPE_SIDECHAIN}
+      # * {TYPE_FFT}
+      # * {TYPE_3DATTRIBUTES_MULTI}
       def data_type
         self[:data_type]
       end

data/lib/fmod/core/dsp_description.rb

@@ -1,7 +1,178 @@
 module FMOD
   module Core
+
+    ##
+    # When creating a DSP unit, declare one of these and provide the relevant
+    # callbacks and name for FMOD to use when it creates and uses a DSP unit of
+    # this type.
+    # @since 0.9.2
     class DspDescription < Structure
-      # TODO
+
+      # @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)
+        types = [:plugin_sdk_version, :name, :version, :input_buffers,
+                 :output_buffers, :create, :release, :reset, :read, :process,
+                 :set_position, :parameter_count, :parameter_description,
+                 :set_param_float, :set_param_int, :set_param_bool,
+                 :set_param_data, :get_param_float, :get_param_int,
+                 :get_param_bool, :get_param_data, :should_process, :user_data,
+                 :register, :deregister, :mix]
+        members = [TYPE_INT, [TYPE_CHAR, 32], TYPE_INT, TYPE_INT, TYPE_INT,
+                   TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP,
+                   TYPE_VOIDP, TYPE_INT, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP,
+                   TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP,
+                   TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP, TYPE_VOIDP,
+                   TYPE_VOIDP]
+        super(address, types, members)
+      end
+
+      [:plugin_sdk_version, :name, :version, :input_buffers, :output_buffers,
+       :create, :release, :reset, :read, :process, :set_position,
+       :parameter_count, :parameter_description, :set_param_float,
+       :set_param_int, :set_param_bool, :set_param_data, :get_param_float,
+       :get_param_int, :get_param_bool, :get_param_data, :should_process,
+       :user_data, :register, :deregister, :mix].each do |symbol|
+
+        define_method(symbol) { self[symbol] }
+        define_method("#{symbol}=") { |value| self[symbol] = value }
+      end
+
+      ##
+      # @!attribute plugin_sdk_version
+      # @return [Integer] the plugin SDK version this plugin is built for.
+
+      ##
+      # @!attribute name
+      # @return [String] the identifier of the DSP. This will also be used as
+      #   the name of DSP and shouldn't change between versions.
+
+      def name
+        self[:name].join.delete("\0")
+      end
+
+      def name=(name)
+        chars = name.chars.slice(0, 32)
+        chars << "\0" while chars.size < 32
+        self[:name] = chars
+      end
+
+      ##
+      # @!attribute version
+      # @return [Integer] the plugin writer's version number.
+
+      # @!attribute input_buffers
+      # @return [Integer] the number of input buffers to process. Use 0 for DSPs
+      #   that only generate sound and 1 for effects that process incoming sound
+
+      ##
+      # @!attribute output_buffers
+      # @return [Integer] the number of audio output buffers. Only one output
+      #   buffer is currently supported.
+
+      ##
+      # @!attribute create
+      # @return [Closure] Create callback. This is called when DSP unit is
+      #   created.
+
+      ##
+      # @!attribute release
+      # @return [Closure] Release callback. This is called just before the unit
+      #   is freed so the user can do any cleanup needed for the unit.
+
+      ##
+      # @!attribute reset
+      # @return [Closure] Reset callback. This is called by the user to reset
+      #   any history buffers that may need resetting for a filter, when it is
+      #   to be used or re-used for the first time to its initial clean state.
+      #   Use to avoid clicks or artifacts.
+
+      ##
+      # @!attribute read
+      # @return [Closure] Read callback. Processing is done here.
+
+      ##
+      # @!attribute process
+      # @return [Closure] Process callback. Can be specified instead of the read
+      #   callback if any channel format changes occur between input and output.
+      #   This also replaces {#should_process} and should return an error if the
+      #   effect is to be bypassed.
+
+      ##
+      # @!attribute set_position
+      # @return [Closure] Set position callback. This is called if the unit
+      #   wants to update its position info but not process data, or reset a
+      #   cursor position internally if it is reading data from a certain
+      #   source.
+
+      ##
+      # @!attribute parameter_count
+      # @return [Integer] the of parameters used in this filter.
+
+      ##
+      # @!attribute parameter_description
+      # @return [Pointer] a variable number of parameter structures.
+
+      ##
+      # @!attribute set_param_float
+      # @return [Closure] Called when the user sets a float parameter.
+
+      ##
+      # @!attribute set_param_int
+      # @return [Closure] Called when the user sets an integer parameter.
+
+      ##
+      # @!attribute set_param_bool
+      # @return [Closure] Called when the user sets a boolean parameter.
+
+      ##
+      # @!attribute set_param_data
+      # @return [Closure] Called when the user sets a data parameter.
+
+      ##
+      # @!attribute get_param_float
+      # @return [Closure] Called when the user gets a float parameter.
+
+      ##
+      # @!attribute get_param_int
+      # @return [Closure] Called when the user gets an integer parameter.
+
+      ##
+      # @!attribute get_param_bool
+      # @return [Closure] Called when the user sets a boolean parameter.
+
+      ##
+      # @!attribute get_param_data
+      # @return [Closure] Called when the user sets a data parameter.
+
+      ##
+      # @!attribute should_process
+      # @return [Closure] This is called before processing. You can detect if
+      #   inputs are idle and return Result::OK to process, or any other error
+      #   code to avoid processing the effect. Use a count down timer to allow
+      #   effect tails to process before idling!
+
+      ##
+      # @!attribute user_data
+      # @return [Pointer] the user data to be attached to the DSP unit during
+      #   creation.
+
+      # @!attribute register
+      # @return [Closure] Register callback. This is called when DSP unit is
+      #   loaded/registered. Useful for 'global'/per system object init for
+      #   plugin.
+
+      # @!attribute register
+      # @return [Closure] Deregister callback. This is called when DSP unit is
+      #   unloaded/deregistered. Useful as 'global'/per system object shutdown
+      #   for plugin.
+
+      # @!attribute register
+      # @return [Closure] System mix stage callback. This is called when the
+      #   mixer starts to execute or is just finishing executing. Useful for
+      #   'global'/per system object once a mix update calls for a plugin.
+
     end
   end
 end