===============================================================

Quence PyBuzz 1.5
Python Script System for Buzz-Machines
Copyright (C) 2003,2004,2005 by 
Leonard :paniq: Ritter (paniq@gmx.net)
Parts of this program rely on BTDSys PeerCtrl source code 
copyright (C) 2003 by Ed Powley (e@btd2001.freeserve.co.uk)
and P. DooM's BUZZHACK source code copyright (C) 2001 by 
Peter "P. DooM" Kaufmann (p_doom@space.ch).

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

===============================================================

Programming Reference
=====================

    Contents
    ========
    1. The 'buzz' Module
        - 1.1 Functions
        - 1.2 Constants
    2. The 'pybuzz' Module
        - 2.1 Functions
        - 2.2 Constants
    3. History


1. The 'buzz' Module
--------------------

    The buzz module is an internal module exposed by the PyBuzz-
    machine. Any script that is loaded into the host can use
    this library.

    To use the buzz module, you must import it into your python
    script using
    
        import buzz
        
    You can also directly import the module into your local
    namespace, therefore not needing to prepend 'buzz.' to
    every function call:
    
        from buzz import *
    

    1.1 Functions
    --------------
    
        > AreMachinesEqual(firstMachine, secondMachine)
        
            Returns 1 if both C-Objects represent the same
            CMachine* pointer, 0 if not.
    
        > ClearPeerCtrlTarget(peerCtrlIndex)
        
            Disconnects the peer controller from any
            machine parameter it might point to.
    
        > GetEventTarget(eventName)
        
            Returns the current function associated with a
            Buzz-event.
            
        > GetLoopBegin()
        
            Returns the current begin of the loop in ticks.
            
        > GetLoopEnd()
        
            Returns the current end of the loop in ticks.
            
        > GetMachine(machineName)
        
            Returns a C-Object representing a CMachine* pointer
            which can be used in calls to GetMachineName,
            GetMachineInfo and SetPeerCtrlTarget.
        
        > GetMachineInfo(machine)
        
            Returns a C-Object representing a CMachineInfo*
            pointer which can be used in calls to 
            UnpackMachineInfo.
            
        > GetMachineName(machine)
        
            Returns a string representing the current name
            of a machine.
            
        > GetMachineNames()
        
            Returns a list of machine name strings which can
            be used in calls to GetMachine().
            
        > GetMachinePosition(machine)
        
            Returns a tuple of two floats indicating the 
            current position of the machine in the machine
            view.
        
        > GetMasterInfo()
        
            Returns a list of master info values which
            correspond to the members of the CMasterInfo class.
            
            index | name
            ------+--------------------
            0     | beatsPerMin
            1     | ticksPerBeat
            2     | samplesPerSec
            3     | samplesPerTick
            4     | posInTick
            5     | ticksPerSec
        
        > GetParameter(track,index)
        
            Returns the parameter currently set for a column index
            on a specific track.
        
        > GetPeerCtrlName(peerCtrlIndex)
        
            returns the name of the peer controller.
            
        > GetPeerCtrlTarget(peerCtrlIndex)
        
            Returns a tuple of three values: 
            
            (machine, group, paramIndex)
            
        > GetPeerCtrlValue(peerCtrlIndex, track)
        
            Returns the current value of the parameter that
            the peer controller points to. -1 indicates an
            error. Usually it makes only sense to get values
            from parameters that have the MPF_STATE flag set.
            
        > GetSongEnd()
        
            Returns the current song end in ticks.    
        
        > GetSongPosition()
        
            Returns the current song position in ticks.
            
        > GetThisMachine()
        
            Returns a C-Object representing a CMachine* pointer
            to the machine executing the current script. It can
            be used in calls to GetMachineName and GetMachineInfo.
            
        > GetTrackCount()
        
            Returns the current track count (usually 16).
            
        > Play()
        
            Plays the song.
            
        > SendPeerCtrlChange(peerCtrlIndex,trackIndex,value)
        
            Sends a new value to the target of a peer controller.
            trackIndex should be zero in case the target is
            a global parameter or never be larger than the
            maxTracks parameter of the target machine in case
            the target is a track parameter.
            
            In case the peer controller has been assigned
            to a fixed track number (number in front of parameter
            name), trackIndex will be ignored.

        > SendPeerCtrlChangeNextTick(peerCtrlIndex,trackIndex,value)
        
            Sends a new value to the target of a peer controller.
            trackIndex should be zero in case the target is
            a global parameter or never be larger than the
            maxTracks parameter of the target machine in case
            the target is a track parameter.
            
            the value is sent with the next tick. unlike with
            SendPeerCtrlChange, the target slider values, if any,
            are updated too.

            In case the peer controller has been assigned
            to a fixed track number (number in front of parameter
            name), trackIndex will be ignored.
            
        > SetEventTarget(eventName, eventTarget)
        
            Associates a Buzz-event name with a handler function. 
            Here is a table of event names and the corresponding
            function definitions:
            
            eventName    | eventTarget
            -------------+--------------------
            "OnTick"     | OnTick()
            "OnWork"     | OnWork()
            "OnCommand"  | OnCommand(text)
            "OnParameter"| OnParameter(trackIndex,paramIndex,value)
            "OnMasterInfoChange"
                         | OnMasterInfoChange()
            "OnStop"     | OnStop()
            "OnSave"     | OnSave() -> return data
            "OnLoad"     | OnLoad(data)
            "OnDescribeValue"
                         | OnDescribeValue(paramIndex,value)
                         | -> return string
            "OnMidiControlChange"
                         | OnMidiControlChange(ctrl,channel,value)
            "OnMidiNote"
                         | OnMidiNote(channel,value,velocity)
                         
        > SetMachinePosition(machine,x,y)
        
            Sets the current position of the machine in the 
            machine view. The view is not updated.
            
        > SetPeerCtrlName(peerCtrlIndex,name)
        
            Names one of the 256 peer controllers. This can
            be used to give hints to the user of the script
            which function this controller will have.
        
        > SetPeerCtrlTarget(peerCtrlIndex,machine,group,paramIndex)
        
            Associates one of the 256 peer controllers to a 
            machine parameter. A group value of 1 refers to
            a global parameter, 2 refers to a track parameter.
        
        > SetSongPosition(position)
        
            Sets the current song position in ticks.          
        
        > Stop()
        
            Stops the song.
        
        > UnpackMachineInfo(machine)
        
            Returns a list of CMachineInfo* values which 
            correspond to the members of the CMachineInfo class.
            
            index | name
            ------+--------------------
            0     | type
            1     | version
            2     | flags
            3     | minTracks
            4     | maxTracks
            5     | numGlobalParameters
            6     | numTrackParameters
            7     | list of parameters
            8     | numAttributes
            9     | C-Object of attributes
            10    | name
            11    | shortName
            12    | author
            13    | commands
            
            Each parameter value represents the members of
            the CMachineParameter class.
            
            index | name
            ------+--------------------
            0     | type
            1     | name
            2     | description
            3     | minValue
            4     | maxValue
            5     | noValue
            6     | flags
            7     | defaultValue
            
    1.2 Constants
    --------------
    
        In order to help parsing informational values, following
        buzz constants have been exported as members of the buzz
        module:
        
            MI_VERSION

            PI
            MAX_BUFFER_LENGTH

            MT_MASTER
            MT_GENERATOR
            MT_EFFECT

            NOTE_NO
            NOTE_OFF
            NOTE_MIN
            NOTE_MAX
            SWITCH_OFF
            SWITCH_ON
            SWITCH_NO
            WAVE_MIN
            WAVE_MAX
            WAVE_NO

            MPF_WAVE
            MPF_STATE
            MPF_TICK_ON_EDIT

            MIF_MONO_TO_STEREO
            MIF_PLAYS_WAVES
            MIF_USES_LIB_INTERFACE
            MIF_USES_INSTRUMENTS
            MIF_DOES_INPUT_MIXING
            MIF_NO_OUTPUT
            MIF_CONTROL_MACHINE
            MIF_INTERNAL_AUX

            WM_NOIO
            WM_READ
            WM_WRITE
            WM_READWRITE

            SF_PLAYING
            SF_RECORDING

            pt_note
            pt_switch
            pt_byte
            pt_word

            WF_LOOP
            WF_STEREO
            WF_BIDIR_LOOP

            OWF_SINE
            OWF_SAWTOOTH
            OWF_PULSE
            OWF_TRIANGLE
            OWF_NOISE
            OWF_303_SAWTOOTH

            EIF_SUSTAIN
            EIF_LOOP
        
        following additional constants have been added:

            P_GLOBAL = 1
            P_TRACK  = 2

            PYBUZZ_VERSION = 5
            
            MAX_PEERCTRLS = 256

2. The 'pybuzz' Module
----------------------

    The pybuzz module is an extension library that adds various
    helper functions to complement the core functions supplied
    by the buzz module. You'll need to install a full python
    distribution for this to work. To make the module available
    to all of your scripts, put it in
    
       <python base>\lib\site-packages
    
    To use the pybuzz module, you must import it into your python
    script using
    
        import pybuzz
        
    You can also directly import the module into your local
    namespace, therefore not needing to prepend 'pybuzz.' to
    every function call:
    
        from pybuzz import *
        
    All undocumented functions found in the pybuzz source are
    subject to change.        

    2.1 Functions
    --------------
    
        > MakeNote(octave,note)
        
            Returns an integer resembling a buzz note value
            which represents given octave and note.
            
        > UnMakeNote(note)
        
            Converts a buzz note value back to octave and
            note.
            
    2.2 Constants
    --------------

        bpm \
        tpb |
        sps > those values represent the six members of the        
        spt | master info structure and are updated whenever
        pit | the master info changes. You can always rely
        tps / on those when making calculations.
        
        FALSE = 0
        TRUE  = 1

3. History
----------

	Version 1.5
	------------
		- improved python interoperability
		- added support for multithreaded sharing of python services (pyshared24.dll)

	Version 1.42
	------------
		- fixed connecting peers not working on different platforms/installations

	Version 1.41
	------------
		- machine parameter window is recognized when connecting peers
		- fixed non-parameter sliders being highlighted when connecting peers

	Version 1.4
	-----------
		- CONTROL key does multiselection when connecting peers
		- hovered controls get outlined when connecting peers
		- increased peer label width
		- fixed labels not being updated when changed from script
		- fixed crash when empty pybuzz machine is in bmx

	Version 1.4b
	------------
		- Rewrote peer controller selection GUI
		- Enabled peer controller track assignment
		- Increased peer controller serialization version to 3
		- Removed console from being opened when machine was doubleclicked
		- added ctrl+doubleclick as shortcut for "open peers"
		- added alt+doubleclick as shortcut for "open console"
		- removed dos console
		- incremented PYBUZZ_VERSION to 5

	Version 1.3
	-----------
		- Fixed python thread deadlock
		- Fixed print in Tick() leading to GUI deadlock		

    Version 1.2
    -----------
        - Added pybuzz module
        - buzz event: OnMidiControlChange
        - buzz event: OnMidiNote
        - buzz module: Added GetPeerCtrlValue
        - buzz module: Added GetThisMachine
        - buzz module: Added GetMachinePosition
        - buzz module: Added SetMachinePosition
        - buzz module: Added GetSongPosition
        - buzz module: Added SetSongPosition
        - buzz module: Added GetLoopBegin
        - buzz module: Added GetLoopEnd
        - buzz module: Added GetSongEnd
        - buzz module: Added Play
        - buzz module: Added Stop
