fmod 0.9.0 → 0.9.1

data/lib/fmod/channel_group.rb

@@ -1,54 +1,118 @@
 
 module FMOD
+
+  # Represents a logical grouping of {Channel} and/or {ChannelGroup} objects
+  # that can be manipulated as one.
   class ChannelGroup < ChannelControl
 
     include Fiddle
     include Enumerable
 
+    # @!attribute [r] subgroup_count
+    # @return [Integer]  the number of sub groups under this channel group.
     integer_reader(:subgroup_count, :ChannelGroup_GetNumGroups)
+
+    # @!attribute [r] channel_count
+    # @return [Integer] the number of assigned channels to this channel group.
     integer_reader(:channel_count, :ChannelGroup_GetNumChannels)
 
+    ##
+    # @return [String] the name of the channel group set when the group was
+    #   created.
     def name
       buffer = "\0" * 512
       FMOD.invoke(:ChannelGroup_GetName, self, buffer, 512)
       buffer.delete("\0")
     end
 
+    ##
+    # Retrieves the sub-group at the specified index.
+    #
+    # @param index [Integer] Index to specify which sub channel group to get.
+    # @return [ChannelGroup, nil] the group or +nil+ if no group was found at
+    #   the specified index.
     def subgroup(index)
-      FMOD.valid_range?(index, 0, subgroup_count - 1)
+      return nil unless FMOD.valid_range?(index, 0, subgroup_count - 1, false)
       FMOD.invoke(:ChannelGroup_GetGroup, self, index, group = int_ptr)
       ChannelGroup.new(group)
     end
 
+    ##
+    # @!attribute [r] parent_group
+    # @return [ChannelGroup, nil] the channel group parent.
     def parent_group
       FMOD.invoke(:ChannelGroup_GetParentGroup, self, group = int_ptr)
       group.null? ? nil : ChannelGroup.new(group)
     end
 
+    ##
+    # Retrieves the {Channel} within this group at the specified index.
+    #
+    # @param index [Integer] Index within the group of the channel.
+    #
+    # @return [Channel, nil] the specified {Channel}, or +nil+ if no channel
+    #   exists at the specified index.
     def [](index)
-      FMOD.valid_range?(index, 0, channel_count - 1)
+      return nil unless FMOD.valid_range?(index, 0, channel_count - 1, false)
       FMOD.invoke(:ChannelGroup_GetChannel, self, index, channel = int_ptr)
       Channel.new(channel)
     end
 
+    ##
+    # Enumerates the channels contained within the {ChannelGroup}.
+    #
+    # @overload each
+    #   When called with block, yields each {Channel} within the object before
+    #   returning self.
+    #   @yield [channel] Yields a channel to the block.
+    #   @yieldparam channel [Channel] The current enumerated channel.
+    #   @return [self]
+    # @overload each
+    #   When no block specified, returns an Enumerator for the {ChannelGroup}.
+    #   @return [Enumerator]
     def each
       return to_enum(:each) unless block_given?
       (0...channel_count).each { |i| yield self[i] }
       self
     end
 
+    ##
+    # Adds a {Channel} or a {ChannelGroup} as a child of this group.
+    #
+    # @param channel_control [Channel, ChannelGroup] The channel or group to
+    #   add as a child.
+    #
+    # @return [self, DspConnection] either self if a {Channel} was added, or a
+    #   {DspConnection} if a group was added.
     def <<(channel_control)
       return add_channel(channel_control) if channel_control.is_a?(Channel)
       return add_group(channel_control) if channel_control.is_a?(ChannelGroup)
       raise TypeError, "#{channel_control} is not a #{ChannelControl}."
     end
 
+    ##
+    # Adds a channel as a child of the this group. This detaches the channel
+    # from any group it may already be attached to.
+    #
+    # @param channel [Channel] Channel to add as a child.
+    #
+    # @return [self]
     def add_channel(channel)
       FMOD.type?(channel, Channel)
       channel.group = self
-      channel
+      self
     end
 
+    ##
+    # Adds a channel group as a child of the current channel group.
+    #
+    # @param group [ChannelGroup] Channel group to add as a child.
+    # @param propagate_clock [Boolean] When a child group is added to a parent
+    #   group, the clock values from the parent will be propagated down into
+    #   the child.
+    #
+    # @return [DspConnection] a DSP connection, which is the connection between
+    #   the parent and the child group's DSP units.
     def add_group(group, propagate_clock = true)
       FMOD.type?(group, ChannelGroup)
       FMOD.invoke(:ChannelGroup_AddGroup, self, group,

data/lib/fmod/core.rb

@@ -1,35 +1,44 @@
 
-require_relative './core/structure'
-require_relative './core/structures'
-require_relative './core/bool_description'
-require_relative './core/channel_mask'
-require_relative './core/data_description'
-require_relative './core/driver'
-require_relative './core/dsp_description'
-require_relative './core/dsp_index'
-require_relative './core/dsp_type'
-require_relative './core/extensions'
-require_relative './core/file_system'
-require_relative './core/filter_type'
-require_relative './core/float_description'
-require_relative './core/guid'
-require_relative './core/init_flags'
-require_relative './core/integer_description'
-require_relative './core/mode'
-require_relative './core/output_type'
-require_relative './core/parameter_info'
-require_relative './core/parameter_type'
-require_relative './core/result'
-require_relative './core/reverb'
-require_relative './core/sound_ex_info'
-require_relative './core/sound_format'
-require_relative './core/sound_group_behavior'
-require_relative './core/sound_type'
-require_relative './core/speaker_index'
-require_relative './core/speaker_mode'
-require_relative './core/spectrum_data'
-require_relative './core/tag'
-require_relative './core/tag_data_type'
-require_relative './core/time_unit'
-require_relative './core/vector'
-require_relative './core/window_type'
+module FMOD
+
+  ##
+  # Namespace for classes and structures used primarily within the API, to
+  # create a logical separation of the native FMOD classes from enumerations,
+  # structures, and internally used data types.
+  module Core
+    require_relative './core/structure'
+    require_relative './core/structures'
+    require_relative './core/bool_description'
+    require_relative './core/channel_mask'
+    require_relative './core/data_description'
+    require_relative './core/driver'
+    require_relative './core/dsp_description'
+    require_relative './core/dsp_index'
+    require_relative './core/dsp_type'
+    require_relative './core/extensions'
+    require_relative './core/file_system'
+    require_relative './core/filter_type'
+    require_relative './core/float_description'
+    require_relative './core/guid'
+    require_relative './core/init_flags'
+    require_relative './core/integer_description'
+    require_relative './core/mode'
+    require_relative './core/output_type'
+    require_relative './core/parameter_info'
+    require_relative './core/parameter_type'
+    require_relative './core/result'
+    require_relative './core/reverb'
+    require_relative './core/sound_ex_info'
+    require_relative './core/sound_format'
+    require_relative './core/sound_group_behavior'
+    require_relative './core/sound_type'
+    require_relative './core/speaker_index'
+    require_relative './core/speaker_mode'
+    require_relative './core/spectrum_data'
+    require_relative './core/tag'
+    require_relative './core/tag_data_type'
+    require_relative './core/time_unit'
+    require_relative './core/vector'
+    require_relative './core/window_type'
+  end
+end

data/lib/fmod/core/mode.rb

@@ -1,35 +1,173 @@
 module FMOD
   module Core
+
+    ##
+    # Sound description bit-fields, bitwise OR them together for loading and
+    # describing sounds.
     module Mode
+
+      ##
+      # Default for all modes listed below. {LOOP_OFF}, {TWO_D},
+      # {WORLD_RELATIVE_3D}, {INVERSE_ROLLOFF_3D}
       DEFAULT = 0x00000000
+
+      ##
+      # For non looping sounds. (DEFAULT). Overrides {LOOP_NORMAL} /
+      # {LOOP_BIDI}.
       LOOP_OFF = 0x00000001
+
+      ##
+      # For forward looping sounds.
       LOOP_NORMAL=  0x00000002
+
+      ##
+      # For bidirectional looping sounds. (only works on software mixed static
+      # sounds).
       LOOP_BIDI = 0x00000004
+
+      ##
+      # Ignores any 3D processing. ({DEFAULT}).
       TWO_D = 0x00000008
+
+      ##
+      # Makes the sound positionable in 3D. Overrides {TWO_D}.
       THREE_D = 0x00000010
+
+      ##
+      # Decompress at runtime, streaming from the source provided (ie from
+      # disk). Overrides {CREATE_SAMPLE} and {CREATE_COMPRESSED_SAMPLE}. Note a
+      # stream can only be played once at a time due to a stream only having 1
+      # stream buffer and file handle. Open multiple streams to have them play
+      # concurrently.
       CREATE_STREAM = 0x00000080
+
+      ##
+      # Decompress at load time, decompressing or decoding whole file into
+      # memory as the target sample format (ie PCM). Fastest for playback and
+      # most flexible.
       CREATE_SAMPLE = 0x00000100
+
+      ##
+      # Load MP2/MP3/FADPCM/IMAADPCM/Vorbis/AT9 or XMA into memory and leave it
+      # compressed. Vorbis/AT9/FADPCM encoding only supported in the .FSB
+      # container format. During playback the FMOD software mixer will decode it
+      # in realtime as a 'compressed sample'. Overrides {CREATE_SAMPLE}. If the
+      # sound data is not one of the supported formats, it will behave as if it
+      # was created with {CREATE_SAMPLE} and decode the sound into PCM.
       CREATE_COMPRESSED_SAMPLE = 0x00000200
+
+      ##
+      # Opens a user created static sample or stream.
       OPEN_USER = 0x00000400
+
+      ##
+      # "source" will be interpreted as a pointer to memory instead of filename
+      # for creating sounds. If used with {CREATE_SAMPLE} or
+      # {CREATE_COMPRESSED_SAMPLE}, FMOD duplicates the memory into its own
+      # buffers. Your own buffer can be freed after open. If used with
+      # {CREATE_STREAM}, FMOD will stream out of the buffer whose pointer you
+      # passed in. In this case, your own buffer should not be freed until you
+      # have finished with and released the stream.
       OPEN_MEMORY = 0x00000800
+
+      ##
+      # "source" will be interpreted as a pointer to memory instead of filename
+      # for creating sounds. This differs to {OPEN_MEMORY} in that it uses the
+      # memory as is, without duplicating the memory into its own buffers.
+      # Cannot be freed after open, only after Sound::release. Will not work if
+      # the data is compressed and {CREATE_COMPRESSED_SAMPLE} is not used.
       OPEN_MEMORY_POINT = 0x10000000
+
+      ##
+      # Will ignore file format and treat as raw PCM.
       OPEN_RAW = 0x00001000
+
+      ##
+      # Just open the file, dont pre-buffer or read. Good for fast opens for
+      # info, or when Sound.read_data is to be used.
       OPEN_ONLY = 0x00002000
+
+      ##
+      # For System.create_sound - for accurate Sound.length/Channel.position on
+      # VBR MP3, and MOD/S3M/XM/IT/MIDI files. Scans file first, so takes longer
+      # to open. {OPEN_ONLY} does not affect this.
       ACCURATE_TIME = 0x00004000
+
+      ##
+      # For corrupted / bad MP3 files. This will search all the way through the
+      # file until it hits a valid MPEG header. Normally only searches for 4k.
       MPEG_SEARCH = 0x00008000
+
+      ##
+      # For opening sounds and getting streamed sub-sounds (seeking)
+      # asynchronously. Use Sound.open_state to poll the state of the sound as
+      # it opens or retrieves the sub-sound in the background.
       NON_BLOCKING = 0x00010000
+
+      ##
+      # Unique sound, can only be played one at a time
       UNIQUE = 0x00020000
+
+      ##
+      # Make the sound's position, velocity and orientation relative to the
+      # listener.
       HEAD_RELATIVE_3D = 0x00040000
+
+      ##
+      # Make the sound's position, velocity and orientation absolute (relative
+      # to the world). ({DEFAULT})
       WORLD_RELATIVE_3D = 0x00080000
+
+      ##
+      # This sound will follow the inverse rolloff model where min distance =
+      # full volume, max distance = where sound stops attenuating, and rolloff
+      # is fixed according to the global rolloff factor. ({DEFAULT})
       INVERSE_ROLLOFF_3D = 0x00100000
+
+      ##
+      # This sound will follow a linear rolloff model where min distance is full
+      # volume, max distance is silence.
       LINEAR_ROLLOFF_3D = 0x00200000
+
+      ##
+      # This sound will follow a linear-square rolloff model where min distance
+      # is full volume, max distance is silence.
       LINEAR_SQUARE_ROLLOFF_3D = 0x00400000
+
+      ##
+      # This sound will follow the inverse rolloff model at distances close to
+      # min distance and a linear-square rolloff close to max distance.
       INVERSE_TAPERED_ROLLOFF_3D = 0x00800000
+
+      ##
+      # is sound will follow a rolloff model defined by Sound.custom_rolloff /
+      # Channel.custom_rolloff.
       CUSTOM_ROLLOFF_3D = 0x04000000
+
+      ##
+      # Is not affect by geometry occlusion. If not specified in Sound:.mode, or
+      # Channel.mode, the flag is cleared and it is affected by geometry again.
       IGNORE_GEOMETRY_3D = 0x40000000
+
+      ##
+      # Skips id3v2/asf/etc tag checks when opening a sound, to reduce seek/read
+      # overhead when opening files (helps with CD performance).
       IGNORE_TAGS = 0x02000000
+
+      ##
+      # Removes some features from samples to give a lower memory overhead, like
+      # Sound.name.
       LOW_MEM = 0x08000000
+
+      ##
+      # Load sound into the secondary RAM of supported platform. On PS3, sounds
+      # will be loaded into RSX/VRAM.
       LOAD_SECONDARY_RAM = 0x20000000
+
+      ##
+      # For sounds that start virtual (due to being quiet or low importance),
+      # instead of swapping back to audible, and playing at the correct offset
+      # according to time, this flag makes the sound play from the start.
       VIRTUAL_PLAY_FROM_START = 0x80000000
     end
   end

data/lib/fmod/core/result.rb

@@ -1,87 +1,371 @@
 module FMOD
   module Core
+
+    ##
+    # Result codes returned from every function call to FMOD.
     module Result
+      ##
+      # No errors.
       OK = 0
+
+      ##
+      # Tried to call a function on a data type that does not allow this type of
+      # functionality (ie calling {Sound.lock} on a streaming sound).
       BAD_COMMAND = 1
+
+      ##
+      # Error trying to allocate a channel.
       CHANNEL_ALLOC = 2
+
+      ##
+      # The specified channel has been reused to play another sound.
       CHANNEL_STOLEN = 3
+
+      ##
+      # DMA Failure. See debug output for more information.
       DMA = 4
+
+      ##
+      # DSP connection error. Connection possibly caused a cyclic dependency or
+      # connected dsps with incompatible buffer counts.
       DSP_CONNECTION = 5
+
+      ##
+      # DSP return code from a DSP process query callback. Tells mixer not to
+      # call the process callback and therefore not consume CPU. Use this to
+      # optimize the DSP graph.
       DSP_DONT_PROCESS = 6
+
+      ##
+      # DSP Format error. A DSP unit may have attempted to connect to this
+      # network with the wrong format, or a matrix may have been set with the
+      # wrong size if the target unit has a specified channel map.
       DSP_FORMAT = 7
+
+      ##
+      # DSP is already in the mixer's DSP network. It must be removed before
+      # being reinserted or released.
       DSP_IN_USE = 8
+
+      ##
+      # DSP connection error. Couldn't find the DSP unit specified.
       DSP_NOT_FOUND = 9
+
+      ##
+      # DSP operation error. Cannot perform operation on this DSP as it is
+      # reserved by the system.
       DSP_RESERVED = 10
+
+      ##
+      # DSP return code from a DSP process query callback. Tells mixer silence
+      # would be produced from read, so go idle and not consume CPU. Use this to
+      # optimize the DSP graph.
       DSP_SILENCE = 11
+
+      ##
+      # DSP operation cannot be performed on a DSP of this type.
       DSP_TYPE = 12
+
+      ##
+      # Error loading file.
       FILE_BAD = 13
+
+      ##
+      # Couldn't perform seek operation. This is a limitation of the medium (ie
+      # net-streams) or the file format.
       FILE_COULD__SEEK = 14
+
+      ##
+      # Media was ejected while reading.
       FILE_DISK_EJECTED = 15
+
+      ##
+      # End of file unexpectedly reached while trying to read essential data
+      # (truncated?).
       FILE_EOF = 16
+
+      ##
+      # End of current chunk reached while trying to read data.
       FILE_END_OF_DATA = 17
+
+      ##
+      # File not found.
       FILE_NOT_FOUND = 18
+
+      ##
+      # Unsupported file or audio format.
       FORMAT = 19
+
+      ##
+      # There is a version mismatch between the FMOD header and either the FMOD
+      # Studio library or the FMOD Low Level library.
       HEADER_MISMATCH = 20
+
+      ##
+      # A HTTP error occurred. This is a catch-all for HTTP errors not listed
+      # elsewhere.
       HTTP = 21
+
+      ##
+      # The specified resource requires authentication or is forbidden.
       HTTP_ACCESS = 22
+
+      ##
+      # Proxy authentication is required to access the specified resource.
       HTTP_PROXY_AUTH = 23
+
+      ##
+      # A HTTP server error occurred.
       HTTP_SERVER_ERROR = 24
+
+      ##
+      # The HTTP request timed out.
       HTTP_TIMEOUT = 25
+
+      ##
+      # FMOD was not initialized correctly to support this function.
       INITIALIZATION = 26
+
+      ##
+      # Cannot call this command after FMOD::System.create.
       INITIALIZED = 27
+
+      ##
+      # An error occurred that wasn't supposed to. Contact support.
       INTERNAL = 28
+
+      ##
+      # Value passed in was a NaN, Inf or de-normalized float.
       INVALID_FLOAT = 29
+
+      ##
+      # An invalid object handle was used.
       INVALID_HANDLE = 30
+
+      ##
+      # An invalid parameter was passed to a function.
       INVALID_PARAM = 31
+
+      ##
+      # An invalid seek position was passed to a function.
       INVALID_POSITION = 32
+
+      ##
+      # An invalid speaker was passed to this function based on the current
+      # speaker mode.
       INVALID_SPEAKER = 33
+
+      ##
+      # The syncpoint did not come from this sound handle.
       INVALID_SYNC_POINT = 34
+
+      ##
+      # Tried to call a function on a thread that is not supported.
       INVALID_THREAD = 35
+
+      ##
+      # The vectors passed in are not unit length, or perpendicular.
       INVALID_VECTOR = 36
+
+      ##
+      # Reached maximum audible playback count for this sound's sound group.
       MAX_AUDIBLE = 37
+
+      ##
+      # Not enough memory or resources.
       MEMORY = 38
+
+      ##
+      # Can't use "open memory point" on non PCM source data, or non
+      # mp3/xma/adpcm data if "create compressed sample" was used.
       MEMORY_CANT_POINT = 39
+
+      ##
+      # Tried to call a command on a 2d sound when the command was meant for 3D
+      # sound.
       NEEDS_3D = 40
+
+      ##
+      # Tried to use a feature that requires hardware support.
       NEEDS_HARDWARE = 41
+
+      ##
+      # Couldn't connect to the specified host.
       NET_CONNECT = 42
+
+      ##
+      # A socket error occurred. This is a catch-all for socket-related errors
+      # not listed elsewhere.
       NET_SOCKET_ERROR = 43
+
+      ##
+      # The specified URL couldn't be resolved.
       NET_URL = 44
+
+      ##
+      # Operation on a non-blocking socket could not complete immediately.
       NET_WOULD_BLOCK = 45
+
+      ##
+      # Operation could not be performed because specified sound/DSP connection
+      # is not ready.
       NOT_READY = 46
+
+      ##
+      # Error initializing output device, but more specifically, the output
+      # device is already in use and cannot be reused.
       OUTPUT_ALLOCATED = 47
+
+      ##
+      # Error creating hardware sound buffer.
       OUTPUT_CREATE_BUFFER = 48
+
+      ##
+      # A call to a standard soundcard driver failed, which could possibly mean
+      # a bug in the driver or resources were missing or exhausted.
       OUTPUT_DRIVER_CALL = 49
+
+      ##
+      # Sound card does not support the specified format.
       OUTPUT_FORMAT = 50
+
+      ##
+      # Error initializing output device.
       OUTPUT_INIT = 51
+
+      ##
+      # The output device has no drivers installed. If pre-init, NO_SOUND is
+      # selected as the output mode. If post-init, the function just fails.
       OUTPUT_NO_DRIVERS = 52
+
+      ##
+      # An unspecified error has been returned from a plugin.
       PLUGIN = 53
+
+      ##
+      # A requested output, DSP unit type or codec was not available.
       PLUGIN_MISSING = 54
+
+      ##
+      # A resource that the plugin requires cannot be found. (ie the DLS file
+      # for MIDI playback)
       PLUGIN_RESOURCE = 55
+
+      ##
+      # A plugin was built with an unsupported SDK version.
       PLUGIN_VERSION = 56
+
+      ##
+      # An error occurred trying to initialize the recording device.
       RECORD = 57
+
+      ##
+      # Reverb properties cannot be set on this channel because a parent channel
+      # group owns the reverb connection.
       REVERB_CHANNEL_GROUP = 58
+
+      ##
+      # Specified instance in Reverb couldn't be set. Most likely because it is
+      # an invalid instance number or the reverb doesn't exist.
       REVERB_INSTANCE = 59
+
+      ##
+      # The error occurred because the sound referenced contains sub-sounds when
+      # it shouldn't have, or it doesn't contain sub-sounds when it should have.
+      # The operation may also not be able to be performed on a parent sound.
       SUBSOUNDS = 60
+
+      ##
+      # This subsound is already being used by another sound, you cannot have
+      # more than one parent to a sound. Null out the other parent's entry
+      # first.
       SUBSOUND_ALLOCATED = 61
+
+      ##
+      # Shared subsounds cannot be replaced or moved from their parent stream,
+      # such as when the parent stream is an FSB file.
       SUBSOUND_CANT_MOVE = 62
+
+      ##
+      # The specified tag could not be found or there are no tags.
       TAG_NOT_FOUND = 63
+
+      ##
+      # The sound created exceeds the allowable input channel count.
       TOO_MANY_CHANNELS = 64
+
+      ##
+      # The retrieved string is too long to fit in the supplied buffer and has
+      # been truncated.
       TRUNCATED = 65
+
+      ##
+      # Something in FMOD hasn't been implemented when it should be! Contact
+      # support!
       UNIMPLEMENTED = 66
+
+      ##
+      # This command failed because System.create or System.output was not
+      # called.
       UNINITIALIZED = 67
+
+      ##
+      # A command issued was not supported by this object. Possibly a plugin
+      # without certain callbacks specified.
       UNSUPPORTED = 68
+
+      ##
+      # The version number of this file format is not supported.
       VERSION = 69
+
+      ##
+      # The specified bank has already been loaded.
       EVENT_ALREADY_LOADED = 70
+
+      ##
+      # The live update connection failed due to the game already being
+      # connected.
       EVENT_LIVE_UPDATE_BUSY = 71
+
+      ##
+      # The live update connection failed due to the game data being out of sync
+      # with the tool.
       EVENT_LIVE_UPDATE_MISMATCH = 72
+
+      ##
+      # The live update connection timed out.
       EVENT_LIVE_UPDATE_TIMEOUT = 73
+
+      ##
+      # The requested event, bus or vca could not be found.
       EVENT_NOT_FOUND = 74
+
+      ##
+      # The Studio::System object is not yet initialized.
       STUDIO_UNINITIALIZED = 75
+
+      ##
+      # The specified resource is not loaded, so it can't be unloaded.
       STUDIO_NOT_LOADED = 76
+
+      ##
+      # An invalid string was passed to this function.
       INVALID_STRING = 77
+
+      ##
+      # The specified resource is already locked.
       ALREADY_LOCKED = 78
+
+      ##
+      # The specified resource is not locked, so it can't be unlocked.
       NOT_LOCKED = 79
+
+      ##
+      # The specified recording driver has been disconnected.
       RECORD_DISCONNECTED = 80
+
+      ##
+      # The length provided exceeds the allowable limit.
       TOO_MANY_SAMPLES = 81
     end
   end