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

Quence PyBuzz 1.0
Python Script System for Buzz-Machines
Copyright (C) 2003 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)

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

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


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

    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
    --------------
    
        > GetEventTarget(eventName)
        
            Returns the current function associated with a
            Buzz-event.
            
        > GetMachine()
        
            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().
        
        > 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
        
        > GetPeerCtrlName(peerCtrlIndex)
        
            returns the name of the peer controller.
            
        > GetPeerCtrlTarget(peerCtrlIndex)
        
            Returns a tuple of three values: 
            
            (machine, group, paramIndex)
            
        > SendPeerCtrlChange(peerCtrlIndex,trackIndex,valueIndex)
        
            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.
            
        > 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)
                         
        > 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.
        
        > 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 = 1
