Commits

Anonymous committed 79e954a

Merged trunk changes up to revision 2180

  • Participants
  • Parent commits 15abbc8
  • Branches tylerthemovie

Comments (0)

Files changed (6)

docs/ref/camera.html

   <tr><td><a href="camera.html#pygame.camera.Camera">pygame.camera.Camera</a> - <font size=-1>load a camera</font></td><td>load a camera</td></tr>
 </table></small></ul>
 <p>Pygame currently supports only Linux and v4l2 cameras. </p>
+<p><tt>EXPERIMENTAL!:</tt> meaning this api may change, or dissapear in later pygame releases. If you use this, your code will break with the next pygame release. </p>
 <p>The Bayer to <tt>RGB</tt> function is based on: </p>
 <pre> Sonix SN9C101 based webcam basic I/F routines
  Copyright (C) 2004 Takafumi Mizuno <taka-qce@ls-a.jp>
  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  SUCH DAMAGE.
-</pre>
+</pre><p>New in pygame <tt>1.9.0</tt>. </p>
 <!--COMMENTS:pygame.camera--> &nbsp;<br> 
 
 

docs/ref/gfxdraw.html

   <tr><td><a href="gfxdraw.html#pygame.gfxdraw.bezier">pygame.gfxdraw.bezier</a> - <font size=-1>draw a bezier curve</font></td><td>draw a bezier curve</td></tr>
 </table></small></ul>
 <p>Wraps SDL_gfx primatives. </p>
+<p><tt>EXPERIMENTAL!:</tt> meaning this api may change, or dissapear in later pygame releases. If you use this, your code will break with the next pygame release. </p>
 <p>Most of the functions accept a color argument that is an <tt>RGB</tt> triplet. These can also accept an <tt>RGBA</tt> quadruplet. The color argument can also be an integer pixel value that is already mapped to the Surface's pixel format. </p>
 <p>For all functions the arguments are strictly positional. Only integers are accepted for coordinates and radii. </p>
+<p>New in pygame <tt>1.9.0</tt>. </p>
 <!--COMMENTS:pygame.gfxdraw--> &nbsp;<br> 
 
 

docs/ref/music.html

 </table></small></ul>
 <p>The music module is closely tied to <tt>pygame.mixer</tt>. Use the music module to control the playback of music in the sound mixer. </p>
 <p>The difference between the music playback and regular Sound playback is that the music is streamed, and never actually loaded all at once. The mixer system only supports a single music stream at once. </p>
+<p>Be aware that <tt>MP3</tt> support is limited. On some systems an unsupported format can crash the program, <tt>e.g</tt>. Debian Linux. Consider using <tt>OGG</tt> instead. </p>
 <!--COMMENTS:pygame.mixer.music--> &nbsp;<br> 
 
 

docs/ref/scrap.html

   <tr><td><a href="scrap.html#pygame.scrap.lost">pygame.scrap.lost</a> - <font size=-1>Checks whether the clipboard is currently owned by the application.</font></td><td>Checks whether the clipboard is currently owned by the application.</td></tr>
   <tr><td><a href="scrap.html#pygame.scrap.set_mode">pygame.scrap.set_mode</a> - <font size=-1>Sets the clipboard access mode.</font></td><td>Sets the clipboard access mode.</td></tr>
 </table></small></ul>
+<p><tt>EXPERIMENTAL!:</tt> meaning this api may change, or dissapear in later pygame releases. If you use this, your code will break with the next pygame release. </p>
 <p>The scrap module is for getting and putting stuff from the clipboard. So you can copy and paste things between pygame, and other application types. It defines some basic own data types </p>
 <pre>  SCRAP_PPM
   SCRAP_PBM
 </pre><p>As stated before you can define own types for the clipboard, those however might not be usable by other applications. Thus data pasted into the clipboard using </p>
 <pre>  pygame.scrap.put ("own_data", data)
 </pre><p>can only be used by applications, which query the clipboard for the "own_data" type. </p>
-<p><tt>EXPERIMENTAL!</tt> </p>
 <p>New in pygame <tt>1.8</tt>. Only works for Windows, <tt>X11</tt> and Mac <tt>OS</tt> <tt>X</tt> so far. On Mac <tt>OSX</tt> only text works at the moment - other types will be supported in the next release. </p>
 <!--COMMENTS:pygame.scrap--> &nbsp;<br> 
 
 It uses the portmidi library.  Is portable to which ever platforms
 portmidi supports (currently windows, OSX, and linux).
 
+This uses pyportmidi for now, but may use its own bindings at some
+point soon.
+
 New in pygame 1.9.0.
+"""
 
 
-
-
-TODO:
-    - write all docs as inline python docs.
-    - rewrite docs for pygame doc style.
-        - follow the format, and style of current docs.
-    - export docs from .py to .doc.
-    - create a background thread version for input threads.
-        - that can automatically inject input into the event queue
-          once the input object is running.  Like joysticks.
-    - generate test stubs (probably after docs are written)
-        - $ cd test/util/
-          $ python gen_stubs.py sprite.Sprite
-    - start writing tests.
-
-Uses portmidi library for putting midi into and out of pygame.
-
-This uses pyportmidi for now, but may use its own bindings at some
-point.
-"""
+#TODO:
+#    - export docs from .py to .doc.
+#    - generate test stubs (probably after docs are written)
+#        - $ cd test/util/
+#          $ python gen_stubs.py sprite.Sprite
+#    - start writing tests.
+#    - create a background thread version for input threads.
+#        - that can automatically inject input into the event queue
+#          once the input object is running.  Like joysticks.
 
 
 
 
 
 class Input(object):
-    """ An Input object is used to get midi input from midi devices.
+    """Input is used to get midi input from midi devices.
     Input(device_id)
     Input(device_id, buffer_size)
 
         self.device_id = device_id
 
 
-    def read(self, length):
-        """ [[status,data1,data2,data3],timestamp]
+    def read(self, num_events):
+        """reads num_events midi events from the buffer.
+        Input.read(num_events): return midi_event_list
+
+        Reads from the Input buffer and gives back midi events.
+        [[[status,data1,data2,data3],timestamp],
+         [[status,data1,data2,data3],timestamp],...]
         """
-        return self._input.Read(length)
+        return self._input.Read(num_events)
+
 
     def poll(self):
-        """ returns true if there's data, or false if not.
-            Otherwise it raises a MidiException.
+        """returns true if there's data, or false if not.
+        Input.poll(): return Bool
+
+        raises a MidiException on error.
         """
         r = self._input.Poll()
         if r == pypm.TRUE:
 class Output(object):
     def __init__(self, device_id, latency = 0, buffer_size = 4096):
         """
+        Output(device_id)
+        Output(device_id, latency = 0)
+        Output(device_id, buffer_size = 4096)
+        Output(device_id, latency, buffer_size)
+
         The buffer_size specifies the number of output events to be 
         buffered waiting for output.  (In some cases -- see below -- 
         PortMidi does not buffer output at all and merely passes data 
         self.device_id = device_id
 
     def write(self, data):
-        """
+        """writes a list of midi data to the Output.
+        Output.write(data)
 
-        output a series of MIDI information in the form of a list:
+        writes series of MIDI information in the form of a list:
              write([[[status <,data1><,data2><,data3>],timestamp],
                     [[status <,data1><,data2><,data3>],timestamp],...])
         <data> fields are optional
 
     def write_short(self, status, data1 = 0, data2 = 0):
         """ write_short(status <, data1><, data2>)
-             output MIDI information of 3 bytes or less.
-             data fields are optional
-             status byte could be:
-                  0xc0 = program change
-                  0x90 = note on
-                  etc.
-                  data bytes are optional and assumed 0 if omitted
-             example: note 65 on with velocity 100
-                  WriteShort(0x90,65,100)
+        Output.write_short(status)
+        Output.write_short(status, data1 = 0, data2 = 0)
+
+        output MIDI information of 3 bytes or less.
+        data fields are optional
+        status byte could be:
+             0xc0 = program change
+             0x90 = note on
+             etc.
+             data bytes are optional and assumed 0 if omitted
+        example: note 65 on with velocity 100
+             write_short(0x90,65,100)
         """
         self._output.WriteShort(status, data1, data2)
 
 
     def write_sys_ex(self, when, msg):
-        """ write_sys_ex(<timestamp>,<msg>)
-        writes a timestamped system-exclusive midi message.
-        <msg> can be a *list* or a *string*
+        """writes a timestamped system-exclusive midi message.
+        Output.write_sys_ex(when, msg)
+
+        write_sys_ex(<timestamp>,<msg>)
+
+        msg - can be a *list* or a *string*
         example:
-            (assuming y is an input MIDI stream)
-            y.write_sys_ex(0,'\\xF0\\x7D\\x10\\x11\\x12\\x13\\xF7')
-                              is equivalent to
-            y.write_sys_ex(pygame.midi.Time,
-            [0xF0, 0x7D, 0x10, 0x11, 0x12, 0x13, 0xF7])
+          (assuming o is an onput MIDI stream)
+            o.write_sys_ex(0,'\\xF0\\x7D\\x10\\x11\\x12\\x13\\xF7')
+          is equivalent to
+            o.write_sys_ex(pygame.midi.Time,
+                           [0xF0,0x7D,0x10,0x11,0x12,0x13,0xF7])
         """
         self._output.WriteSysEx(when, msg)
 
 
     def note_on(self, note, velocity=None, channel = 0):
-        """ note_on(note, velocity=None, channel = 0)
-        Turn a note on in the output stream.
-        """
-        if velocity is None:
-            velocity = 0
-        self.write_short(0x90+channel, note, velocity)
+        """ turns a midi note on.  Note must be off.
+        Output.note_on(note, velocity=None, channel = 0)
 
-    def note_off(self, note, velocity=None, channel = 0):
-        """ note_off(note, velocity=None, channel = 0)
-        Turn a note off in the output stream.
+        Turn a note on in the output stream.  The note must already
+        be off for this to work correctly.
         """
         if velocity is None:
             velocity = 0
 
+        if not (0 <= channel <= 15):
+            raise ValueError("Channel not between 0 and 15.")
+
+        self.write_short(0x90+channel, note, velocity)
+
+    def note_off(self, note, velocity=None, channel = 0):
+        """ turns a midi note off.  Note must be on.
+        Output.note_off(note, velocity=None, channel = 0)
+
+        Turn a note off in the output stream.  The note must already
+        be on for this to work correctly.
+        """
+        if velocity is None:
+            velocity = 0
+
+        if not (0 <= channel <= 15):
+            raise ValueError("Channel not between 0 and 15.")
+
         self.write_short(0x80 + channel, note, velocity)
 
 
     def set_instrument(self, instrument_id, channel = 0):
-        """ set_instrument(instrument_id, channel = 0)
-        Select an instrument, with a value between 0 and 127.
+        """ Select an instrument, with a value between 0 and 127.
+        Output.set_instrument(instrument_id, channel = 0)
+
         """
         if not (0 <= instrument_id <= 127):
             raise ValueError("Undefined instrument id: %d" % instrument_id)
+
+        if not (0 <= channel <= 15):
+            raise ValueError("Channel not between 0 and 15.")
+
         self.write_short(0xc0+channel, instrument_id)
 
 
+
 def time():
-    """ Returns the current time in ms of the PortMidi timer.
+    """returns the current time in ms of the PortMidi timer
+    pygame.midi.time(): return time
     """
     return pypm.Time()
 
 
 
 def midis2events(midis, device_id):
-    """ takes a sequence of midi events and returns a list of pygame events.
+    """converts midi events to pygame events
+    pygame.midi.midis2events(midis, device_id): return [Event, ...]
+
+    Takes a sequence of midi events and returns list of pygame events.
     """
     evs = []
     for midi in midis:

test/midi_test.py

+if __name__ == '__main__':
+    import sys
+    import os
+    pkg_dir = os.path.split(os.path.abspath(__file__))[0]
+    parent_dir, pkg_name = os.path.split(pkg_dir)
+    is_pygame_pkg = (pkg_name == 'tests' and
+                     os.path.split(parent_dir)[1] == 'pygame')
+    if not is_pygame_pkg:
+        sys.path.insert(0, parent_dir)
+else:
+    is_pygame_pkg = __name__.startswith('pygame.tests.')
+
+if is_pygame_pkg:
+    from pygame.tests import test_utils
+    from pygame.tests.test_utils import test_not_implemented, unittest
+else:
+    from test import test_utils
+    from test.test_utils import test_not_implemented, unittest
+import pygame
+import pygame.movie
+from pygame.locals import *
+
+import os
+import sys
+import time
+
+
+class MidiTest( unittest.TestCase ):            
+
+    def todo_test_poll(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Input.poll:
+
+          # returns true if there's data, or false if not.
+          # Input.poll(): return Bool
+          # 
+          # raises a MidiException on error.
+
+        self.fail() 
+
+    def todo_test_read(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Input.read:
+
+          # reads num_events midi events from the buffer.
+          # Input.read(num_events): return midi_event_list
+          # 
+          # Reads from the Input buffer and gives back midi events.
+          # [[[status,data1,data2,data3],timestamp],
+          #  [[status,data1,data2,data3],timestamp],...]
+
+        self.fail() 
+
+    def todo_test_message(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.MidiException.message:
+
+          
+
+        self.fail() 
+
+    def todo_test_note_off(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.note_off:
+
+          # turns a midi note off.  Note must be on.
+          # Output.note_off(note, velocity=None, channel = 0)
+          # 
+          # Turn a note off in the output stream.  The note must already
+          # be on for this to work correctly.
+
+        self.fail() 
+
+    def todo_test_note_on(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.note_on:
+
+          # turns a midi note on.  Note must be off.
+          # Output.note_on(note, velocity=None, channel = 0)
+          # 
+          # Turn a note on in the output stream.  The note must already
+          # be off for this to work correctly.
+
+        self.fail() 
+
+    def todo_test_set_instrument(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.set_instrument:
+
+          # Select an instrument, with a value between 0 and 127.
+          # Output.set_instrument(instrument_id, channel = 0)
+
+        self.fail() 
+
+    def todo_test_write(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.write:
+
+          # writes a list of midi data to the Output.
+          # Output.write(data)
+          # 
+          # writes series of MIDI information in the form of a list:
+          #      write([[[status <,data1><,data2><,data3>],timestamp],
+          #             [[status <,data1><,data2><,data3>],timestamp],...])
+          # <data> fields are optional
+          # example: choose program change 1 at time 20000 and
+          # send note 65 with velocity 100 500 ms later.
+          #      write([[[0xc0,0,0],20000],[[0x90,60,100],20500]])
+          # notes:
+          #   1. timestamps will be ignored if latency = 0.
+          #   2. To get a note to play immediately, send MIDI info with
+          #      timestamp read from function Time.
+          #   3. understanding optional data fields:
+          #        write([[[0xc0,0,0],20000]]) is equivalent to
+          #        write([[[0xc0],20000]])
+          # 
+          # Can send up to 1024 elements in your data list, otherwise an 
+          #  IndexError exception is raised.
+
+        self.fail() 
+
+    def todo_test_write_short(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.write_short:
+
+          # write_short(status <, data1><, data2>)
+          # Output.write_short(status)
+          # Output.write_short(status, data1 = 0, data2 = 0)
+          # 
+          # output MIDI information of 3 bytes or less.
+          # data fields are optional
+          # status byte could be:
+          #      0xc0 = program change
+          #      0x90 = note on
+          #      etc.
+          #      data bytes are optional and assumed 0 if omitted
+          # example: note 65 on with velocity 100
+          #      write_short(0x90,65,100)
+
+        self.fail() 
+
+    def todo_test_write_sys_ex(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.Output.write_sys_ex:
+
+          # writes a timestamped system-exclusive midi message.
+          # Output.write_sys_ex(when, msg)
+          # 
+          # write_sys_ex(<timestamp>,<msg>)
+          # 
+          # msg - can be a *list* or a *string*
+          # example:
+          #   (assuming o is an onput MIDI stream)
+          #     o.write_sys_ex(0,'\xF0\x7D\x10\x11\x12\x13\xF7')
+          #   is equivalent to
+          #     o.write_sys_ex(pygame.midi.Time,
+          #                    [0xF0,0x7D,0x10,0x11,0x12,0x13,0xF7])
+
+        self.fail() 
+
+    def todo_test_get_count(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.get_count:
+
+          # gets the number of devices.
+          # pygame.midi.get_count(): return num_devices
+          # 
+          # 
+          # Device ids range from 0 to get_count() -1
+
+        self.fail() 
+
+    def todo_test_get_default_input_device_id(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.get_default_input_device_id:
+
+          # gets the device number of the default input device.
+          # pygame.midi.get_default_input_device_id(): return default_id
+          # 
+          # 
+          # Return the default device ID or -1 if there are no devices.
+          # The result can be passed to the Input()/Ouput() class.
+          # 
+          # On the PC, the user can specify a default device by
+          # setting an environment variable. For example, to use device #1.
+          # 
+          #     set PM_RECOMMENDED_INPUT_DEVICE=1
+          # 
+          # The user should first determine the available device ID by using
+          # the supplied application "testin" or "testout".
+          # 
+          # In general, the registry is a better place for this kind of info,
+          # and with USB devices that can come and go, using integers is not
+          # very reliable for device identification. Under Windows, if
+          # PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
+          # *NOT* found in the environment, then the default device is obtained
+          # by looking for a string in the registry under:
+          #     HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
+          # and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
+          # for a string. The number of the first device with a substring that
+          # matches the string exactly is returned. For example, if the string
+          # in the registry is "USB", and device 1 is named
+          # "In USB MidiSport 1x1", then that will be the default
+          # input because it contains the string "USB".
+          # 
+          # In addition to the name, get_device_info() returns "interf", which
+          # is the interface name. (The "interface" is the underlying software
+          #     system or API used by PortMidi to access devices. Examples are
+          #     MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
+          #     At present, the only Win32 interface is "MMSystem", the only Linux
+          #     interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
+          # To specify both the interface and the device name in the registry,
+          # separate the two with a comma and a space, e.g.:
+          #     MMSystem, In USB MidiSport 1x1
+          # In this case, the string before the comma must be a substring of
+          # the "interf" string, and the string after the space must be a
+          # substring of the "name" name string in order to match the device.
+          # 
+          # Note: in the current release, the default is simply the first device
+          #     (the input or output device with the lowest PmDeviceID).
+
+        self.fail() 
+
+    def todo_test_get_default_output_device_id(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.get_default_output_device_id:
+
+          # get the device number of the default output device.
+          # pygame.midi.get_default_output_device_id(): return default_id
+          # 
+          # 
+          # Return the default device ID or -1 if there are no devices.
+          # The result can be passed to the Input()/Ouput() class.
+          # 
+          # On the PC, the user can specify a default device by
+          # setting an environment variable. For example, to use device #1.
+          # 
+          #     set PM_RECOMMENDED_OUTPUT_DEVICE=1
+          # 
+          # The user should first determine the available device ID by using
+          # the supplied application "testin" or "testout".
+          # 
+          # In general, the registry is a better place for this kind of info,
+          # and with USB devices that can come and go, using integers is not
+          # very reliable for device identification. Under Windows, if
+          # PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
+          # *NOT* found in the environment, then the default device is obtained
+          # by looking for a string in the registry under:
+          #     HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
+          # and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
+          # for a string. The number of the first device with a substring that
+          # matches the string exactly is returned. For example, if the string
+          # in the registry is "USB", and device 1 is named
+          # "In USB MidiSport 1x1", then that will be the default
+          # input because it contains the string "USB".
+          # 
+          # In addition to the name, get_device_info() returns "interf", which
+          # is the interface name. (The "interface" is the underlying software
+          #     system or API used by PortMidi to access devices. Examples are
+          #     MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
+          #     At present, the only Win32 interface is "MMSystem", the only Linux
+          #     interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
+          # To specify both the interface and the device name in the registry,
+          # separate the two with a comma and a space, e.g.:
+          #     MMSystem, In USB MidiSport 1x1
+          # In this case, the string before the comma must be a substring of
+          # the "interf" string, and the string after the space must be a
+          # substring of the "name" name string in order to match the device.
+          # 
+          # Note: in the current release, the default is simply the first device
+          #     (the input or output device with the lowest PmDeviceID).
+
+        self.fail() 
+
+    def todo_test_get_device_info(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.get_device_info:
+
+          # returns (interf, name, input, output, opened)
+          # pygame.midi.get_device_info(an_id): return (interf, name, input,
+          # output, opened)
+          # 
+          # 
+          # If the id is out of range, the function returns None.
+
+        self.fail() 
+
+    def todo_test_init(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.init:
+
+          # initialize the midi module
+          # pygame.midi.init(): return None
+          # 
+          # Call the initialisation function before using the midi module.
+          # 
+          # It is safe to call this more than once.
+
+        self.fail() 
+
+    def todo_test_midis2events(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.midis2events:
+
+          # converts midi events to pygame events
+          # pygame.midi.midis2events(midis, device_id): return [Event, ...]
+          # 
+          # Takes a sequence of midi events and returns list of pygame events.
+
+        self.fail() 
+
+    def todo_test_quit(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.quit:
+
+          # uninitialize the midi module
+          # pygame.midi.quit(): return None
+          # 
+          # 
+          # Called automatically atexit if you don't call it.
+          # 
+          # It is safe to call this function more than once.
+
+        self.fail() 
+
+    def todo_test_time(self):
+
+        # __doc__ (as of 2009-05-19) for pygame.midi.time:
+
+          # returns the current time in ms of the PortMidi timer
+          # pygame.midi.time(): return time
+
+        self.fail() 
+
+ 
+if __name__ == '__main__':
+    unittest.main()