rtmidi 0.2.2 → 0.3

data/lib/rtmidi.rb

@@ -1,4 +1,9 @@
 require 'ffi'
+
+# The RtMidi namespace. The interface for this library consists of the {In} and {Out} classes for MIDI input and output.
+module RtMidi
+end
+
 require 'rtmidi/interface.rb'
 require 'rtmidi/in.rb'
 require 'rtmidi/out.rb'

data/lib/rtmidi/build/compiler.rb

@@ -0,0 +1,132 @@
+require_relative 'system'
+
+module RtMidi
+
+  # @private
+  module Build
+
+    # @private
+    class Compiler
+      include RtMidi::Build::System
+
+      def initialize(ext_dir, rtdmidi_dir, options={})
+        @ext_dir = ext_dir
+        @rtmidi_dir = rtdmidi_dir
+        @options = options
+        configure # also validates the configuration and gives appropriate errors before we start compiling
+      end
+
+      def compile
+        compile_rtmidi
+        compile_ruby_rtmidi_wrapper
+        create_shared_library
+        puts "\nCompilation complete" if verbose?
+      end
+
+      def compile_rtmidi
+        puts "\nCompiling RtMidi C++ library" if verbose?
+        cd @rtmidi_dir
+        if gcc?
+          run "g++ -O3 -Wall -Iinclude -fPIC #{@predefines} -o RtMidi.o -c RtMidi.cpp"
+        else
+          run "cl /O2 /Iinclude #{@predefines} /EHsc /FoRtMidi.obj /c RtMidi.cpp"
+        end
+      end
+
+      def compile_ruby_rtmidi_wrapper
+        puts "\nCompiling Ruby RtMidi wrapper" if verbose?
+        cd @ext_dir
+        if gcc?
+          run "g++ -g -Wall -I#{@rtmidi_dir} -fPIC -o ruby-rtmidi.o -c ruby-rtmidi.cpp"
+        else
+          run "cl /I#{@rtmidi_dir} /D__RUBY_RTMIDI_DLL__ /EHsc /Foruby-rtmidi.obj /c ruby-rtmidi.cpp"
+        end
+      end
+
+      def create_shared_library
+        puts "\nCreating the RtMidi + wrapper shared library" if verbose?
+        cd @ext_dir
+        if gcc?
+          run "g++ -g -Wall -I#{@rtmidi_dir} -I#{@rtmidi_dir}/include #{@predefines} -fPIC -shared -o ruby-rtmidi.so " +
+                "ruby-rtmidi.o #{@rtmidi_dir}/RtMidi.o #{@system_libs}"
+        else
+          run "cl /I#{@rtmidi_dir} /I#{@rtmidi_dir}/include #{@predefines} /LD ruby-rtmidi.obj #{@rtmidi_dir}/RtMidi.obj #{@system_libs}"
+        end
+      end
+
+
+      ############################
+      private
+
+      def verbose?
+        @verbose ||= @options.fetch(:verbose, false)
+      end
+
+      def gcc?
+        @compiler == :gcc
+      end
+
+      def cl?
+        @compiler == :cl
+      end
+
+      def jack?
+        @api == :jack
+      end
+
+      def alsa?
+        @api == :alsa
+      end
+
+      def configure
+        configure_compiler
+        configure_midi_api
+        configure_predefines
+        configure_system_libs
+      end
+
+      def configure_compiler
+        @compiler = case
+          when windows? && can_run('cl.exe') then :cl
+          when can_run('gcc') && can_run('g++') then :gcc
+          else raise "Cannot find gcc/g++#{' or cl.exe' if windows?} compiler"
+        end
+      end
+
+      def configure_midi_api
+        @api = case
+          when osx? then :coremidi
+          when windows? then :winmm
+          when linux?
+            case
+              when linux_package_exists(:jack) then :jack
+              when linux_package_exists(:alsa) then :alsa
+              else raise 'Neither JACK or ALSA detected using pkg-config. Please install one of them first.'
+            end
+          else raise "Unsupported platform #{platform}"
+        end
+      end
+
+      def configure_predefines
+        @predefines = case
+          when osx? then '-D__MACOSX_CORE__'
+          when windows? && gcc? then '-D__WINDOWS_MM__'
+          when windows? && cl? then '/D__WINDOWS_MM__'
+          when linux? && jack? then '-D__UNIX_JACK__'
+          when linux? && alsa? then '-D__LINUX_ALSA__'
+          else raise "Could not set predefines"
+        end
+      end
+
+      def configure_system_libs
+        @system_libs = case
+          when osx? then '-framework CoreMIDI -framework CoreAudio -framework CoreFoundation'
+          when windows? && gcc? then '-lwinmm'
+          when windows? && cl? then 'winmm.lib'
+          when linux? then linux_library(@api)
+          else raise "Could not set system_libs"
+        end
+      end
+    end
+  end
+end

data/lib/rtmidi/build/system.rb

@@ -0,0 +1,58 @@
+require 'mkmf'
+
+module RtMidi
+
+  # @private
+  module Build
+
+    # @private
+    module System
+
+      def platform
+        case RbConfig::CONFIG['host_os'].downcase
+          when /darwin/ then :osx  # check this first since the next case would match darwin for :windows
+          when /(win)|(mingw)/ then :windows
+          when /linux/ then :linux
+        end
+      end
+
+      def osx?
+        platform == :osx
+      end
+
+      def windows?
+        platform == :windows
+      end
+
+      def linux?
+        platform == :linux
+      end
+
+      def cd(dir)
+        puts "cd #{dir}"
+        Dir.chdir(dir)
+      end
+
+      def can_run(cmd)
+        find_executable(cmd)
+      end
+
+      def run(cmd)
+        puts cmd
+        unless system(cmd)
+          puts "Error: command exited with return value #{$?.exitstatus}"
+          exit $?.exitstatus
+        end
+      end
+
+      def linux_package_exists(pkg)
+        system "pkg-config --exists #{pkg}"
+      end
+
+      def linux_library(pkg)
+        `pkg-config --libs #{pkg}`.chomp
+      end
+
+    end
+  end
+end

data/lib/rtmidi/in.rb

@@ -1,10 +1,11 @@
 module RtMidi
 
-  # Ruby representation of a RtMidiIn C++ object
+  # Object for handling MIDI input.
+  # The Ruby representation of a {http://www.music.mcgill.ca/~gary/rtmidi/classRtMidiIn.html RtMidiIn C++ object}..
   # @see Out
   class In
 
-    # Create a new RtMidiIn wrapper object.
+    # Create a new instance.
     def initialize
       @midiin = Interface::midiin_new()
       at_exit{ Interface::midiin_delete @midiin }
@@ -28,49 +29,99 @@ module RtMidi
     # @see #port_name
     # @see #open_port
     def port_names
-      @port_names ||= (
-        names = []
-        port_count.times{|i| names << Interface::midiin_port_name(@midiin, i) }
-        names
-      )       
+      @port_names ||= (0...port_count).map{|port_index| Interface::midiin_port_name(@midiin, port_index) }
     end
 
     # Open the MIDI input port at the given index.
+    # @note only one port may be open per RtMidi::In instance
     # @see #port_names
     def open_port(index)
       Interface::midiin_open_port(@midiin, index)
     end
 
-    # Close all opened ports.
-    def close_ports()
+    # Close the port, if opened.
+    # @see #open_port
+    def close_port()
       Interface::midiin_close_port(@midiin)
     end
 
-    # TODO: enable sysex listening by hooking up to midiin_ignore_types
-    # but that will require a more flexible callback interface.
+    # @deprecated use {#close_port}
+    def close_ports
+      puts "Deprecated, use #close_port instead"
+      close_port
+    end
 
     # Setup a callback block to handle incoming MIDI channel messages from opened ports.
+    # @note Only one receive callback may be active per RtMidi::In instance.
+    #       Calling this method or {#receive_message} multiple times will replace the previous receive callback.
     #
-    # The block should receive 3 bytes (Ruby integers)
+    # The block should receive 3 bytes (Ruby Fixnum integers)
     #
-    # All messages are assumed to have 3 bytes.
+    # All messages are assumed to have 3 bytes. SysEx messages will be ignored.
     # Some channel messages only have 2 bytes in which case the 3rd byte is 0.
+    #
+    # This is more efficient than {#receive_message} and should be used when handling only MIDI channel messages.
+    #
+    # @yield [Fixnum, Fixnum, Fixnum] MIDI channel message as individual bytes
+    #
     # @example
-    #          midiin.set_callback do |byte1, byte2, byte3|
+    #          midiin.receive_channel_message do |byte1, byte2, byte3|
     #            puts "#{byte1} #{byte2} #{byte3}"
     #          end
+    #
     # @see #open_port
+    # @see #receive_message
     # @see #cancel_callback
-    def set_callback &callback      
+    def receive_channel_message &callback
+      cancel_callback # otherwise first callback wins. I think last wins is more intuitive
+      Interface::midiin_ignore_types(@midiin, true, true, true) # Ignore sysex, timing, or active sensing messages.
       Interface::midiin_set_callback(@midiin, callback)
+      @callback_set = true
     end
 
-    # Cancel previously registered callbacks.
-    # @see #set_callback
-    def cancel_callback
-      Interface::midiin_cancel_callback(@midiin)
+
+    # Setup a callback block to handle all incoming MIDI messages from opened ports.
+    # @note Only one receive callback may be active per RtMidi::In instance.
+    #       Calling this method or {#receive_message} multiple times will replace the previous receive callback.
+    #
+    # The block should receive a variable number of Ruby Fixnum integers.
+    # SysEx messages will be passed to the callback.
+    #
+    # This is less efficient than {#receive_channel_message} and should only be used when handling
+    # SysEx, timing, or active sensing messages.
+    #
+    # @yield [*Fixnum] MIDI channel message as individual bytes
+    #
+    # @example
+    #          midiin.receive_message do |*bytes|
+    #            puts bytes.inspect
+    #          end
+    #
+    # @see #open_port
+    # @see #receive_channel_message
+    # @see #cancel_callback
+    def receive_message &callback
+      cancel_callback # otherwise first callback wins. I think last wins is more intuitive
+      Interface::midiin_ignore_types(@midiin, false, false, false) #  Don't ignore sysex, timing, or active sensing messages.
+      Interface::midiin_set_varargs_callback(@midiin, ->(bytes,size){ yield *bytes.read_array_of_uchar(size) })
+      @callback_set = true
     end
 
+    alias set_callback receive_message
+
+
+    # Cancel the current receive callback, if any.
+    # @see #receive_message
+    # @see #receive_channel_message
+    def stop_receiving
+      if @callback_set
+        Interface::midiin_cancel_callback(@midiin)
+        @callback_set = false
+      end
+    end
+
+    alias cancel_callback stop_receiving
+
   end
 
 end

data/lib/rtmidi/interface.rb

@@ -1,8 +1,6 @@
 module RtMidi
 
-  # The interface to RtMidi C++ code
-  # @see RtMidi::In
-  # @see RtMidi::Out
+  # @private
   module Interface
     extend FFI::Library
     ffi_lib [
@@ -37,7 +35,11 @@ module RtMidi
     # void midiin_set_callback(rtmidi_ptr p, rtmidi_callback callback);
     callback :rtmidi_callback, [:int, :int, :int], :void
     attach_function :midiin_set_callback, [:pointer, :rtmidi_callback], :void
-    
+
+    # void midiin_set_varargs_callback(rtmidi_ptr p, rtmidi_varargs_callback callback);
+    callback :rtmidi_varargs_callback, [:pointer, :int], :void
+    attach_function :midiin_set_varargs_callback, [:pointer, :rtmidi_varargs_callback], :void
+
     # void midiin_cancel_callback(rtmidi_ptr p);
     attach_function :midiin_cancel_callback, [:pointer], :void
 
@@ -63,8 +65,11 @@ module RtMidi
     # void midiout_close_port(rtmidi_ptr p);
     attach_function :midiout_close_port, [:pointer], :void
 
-    # void midiout_message(rtmidi_ptr p, int byte1, int byte2, int byte3);
-    attach_function :midiout_send_message, [:pointer, :int, :int, :int], :void    
+    # void midiout_send_message(rtmidi_ptr p, int byte1, int byte2, int byte3);
+    attach_function :midiout_send_message, [:pointer, :int, :int, :int], :void
+
+    # void midiout_send_bytes(rtmidi_ptr p, int* bytes);
+    attach_function :midiout_send_bytes, [:pointer, :pointer, :int], :void
   end
 
 end

data/lib/rtmidi/out.rb

@@ -1,10 +1,11 @@
 module RtMidi
 
-  # Ruby representation of a RtMidiOut C++ object
+  # Object for handling MIDI output.
+  # The Ruby representation of a {http://www.music.mcgill.ca/~gary/rtmidi/classRtMidiOut.html RtMidiOut C++ object}.
   # @see In
   class Out
 
-    # Create a new RtMidiOut wrapper object.
+    # Create a new instance.
     def initialize
       @midiout = Interface::midiout_new()
       at_exit{ Interface::midiout_delete @midiout }
@@ -28,11 +29,7 @@ module RtMidi
     # @see #port_name
     # @see #open_port
     def port_names
-      @port_names ||= (
-        names = []
-        port_count.times{|i| names << Interface::midiout_port_name(@midiout, i) }
-        names
-      )       
+      @port_names ||= (0...port_count).map{|port_index| Interface::midiout_port_name(@midiout, port_index) }
     end
 
     # Open the MIDI output port at the given index.
@@ -41,19 +38,46 @@ module RtMidi
       Interface::midiout_open_port(@midiout, index)
     end
 
-    # Close all opened ports.
-    def close_ports()
+    # Close the port, if opened.
+    def close_port()
       Interface::midiout_close_port(@midiout)
     end
 
-    # Send a 3-byte MIDI channel message to the opened port.
+    # @deprecated use {#close_port}
+    def close_ports
+      puts "Deprecated, use #close_port instead"
+      close_port
+    end
+
+    # Send a 2 or 3 byte MIDI channel message to the opened port.
     #
     # Some channel messages only have 2 bytes in which case the 3rd byte is ignored.
+    #
+    # This is more efficient than {#send_message} and should be used when handling only MIDI channel messages.
+    #
     # @see #open_port
-    def send_message(byte1, byte2, byte3=0)
+    # @see #send_message
+    def send_channel_message(byte1, byte2, byte3=0)
       Interface::midiout_send_message(@midiout, byte1, byte2, byte3)
     end
 
+    # Send an arbitrary multi-byte MIDI message to the opened port.
+    #
+    # This supports SysEx messages.
+    #
+    # This is less efficient than {#send_channel_message} and should only be used when handling
+    # SysEx, timing, or active sensing messages.
+    #
+    # @see #open_port
+    # @see #send_channel_message
+    def send_message(*bytes)
+      bytes.flatten!
+      FFI::MemoryPointer.new(:int, bytes.length) do |p|
+        p.write_array_of_int(bytes)
+        Interface::midiout_send_bytes(@midiout, p, bytes.length)
+      end
+    end
+
   end
 
 end