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

Quence PyBuzz 1.2
Python Script System for Buzz-Machines
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).

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

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.

        > 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.
            
        > 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 = 4
            
            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.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
