Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d7xx/d711/theweb.lha/TheWeb/Demo.DOC

Text File | 1992-08-19 | 45KB | 932 lines

        The Web System Data Collection and Management Program Suite
              ===============================================

                        -- Demonstration Edition --

                                1992 July 1

Contents:                                      LINE:     POSITION:

        Concepts                                 31          5%
        The Demonstration Package               117         15%
        Distribution                            159         20%
        Getting Started                         210         24%
        Prerequisites and Package Components    233         26%
        Brief Overview of the Master Screen     293         33%
        The Control Buttons                     326         37%
        The Project Menu                        466         54%
        Temporary Windows                       488         55%
        Loading Configurations from File        498         57%
        CLI command line for the Web            531         60%

        The Demonstration Modules               561         62%
        Module Parameter Panels                 659         72%

        Principles                              823         88%

---------------------------------------------------------------------


Concepts
========

Rather than being a single program, the Web should be thought of as
a configurable, easily extensible suite of programs for the integrated
management of data collection and processing.  The one invariant is the
Web Master control program, giving the user a visual "flow diagram"
representation of the configuration that he or she can manipulate with
ease -- even while data is flowing.

The underlying concept is of a series of data processing elements,
beginning with a data `source' -- which might be acquiring input directly
from a hardware channel, from a disk file, or even as in the demonstration
generating it itself -- and subsequent `filters' that act on the data.
The elements are connected by paths along which the data flows; each
element takes some specific action with respect to the data, then passes
it along the path (perhaps modified, perhaps not).

A path may be more elaborate than just beginning at a source and passing
through some filters in straight sequence.  It may contain branches, where
the data flow is duplicated into separate streams.  Alternatively, more
than one stream may converge on an element; most filters can accept several
input connections, although the data all flows on through a single output
path.

In addition to the simple Sources and Filters exemplified by the modules
here, it is possible for a single element to have multiple input and
output connections, each with a different function.  A multi-connection
`Path-Synchronization' module has been included in the set to give some
idea of this.

Naturally the system takes full advantage of the Amiga's multitasking:
several flow paths -- either independent or connected -- can be working on
their own data simultaneously.  On the other hand, the design is such as to
avoid unnecessary task-switching; typically a single process handles most
of the data manipulation algorithms that are chained into one path.

The data to be processed is purely the concern of the Modules "plugged
in" to the Web.  The Master program itself has no interest in, or control
over, the data format: it solely determines the paths over which the data
will flow.  The only inherent assumption is that the data can be maintained
as "packets" in some way, so that each "station" on a path can work on a
packet at a time.  There is complete freedom as to what form a packet
should take, and what may happen to it on its travels.

By the way, those of you familiar with products for other platforms that
look superficially similar, be cautious about equating the Web's function
with these.  For instance, the Web is not a `Simulation' package: such
typically compute the state of the whole system repetitively at specific
time-steps, based on the state at the previous time-step; calculations are
performed `synchronously' for all the elements, and each generates one
data-point per step.  In contrast, the Web is designed for processing
real-time data, and has essentially an asynchronous `data-flow' approach,
with many data-points (as many as possible for efficiency) in each packet.

[Note to prospective purchasers:  the Web Master and SHADOW library
themselves are proprietary, but sources will be available (by licence
arrangement) for most of the existing data modules -- with the exception,
I believe, of the FFT code, which is copyright by others.  Header files
and documentation for the protocols used by the Web will be included in
the full package.]

Although the modules included here are directed toward a particular
application, the system is designed to be adaptable to a wide range
of needs.  "Sampler" modules can be written to acquire data from
any available source that can connect to the Amiga; output of data
to channels other than display or disk could also easily be arranged.
The packet structure is also totally flexible, and can be designed
to suit the purpose.  With suitably written modules, some examples of
possible applications that spring to mind are: neural spike recording
and analysis, MIDI event processing... even image processing, where a
series of transforms is to be applied in sequence to an image.

The modules included in this demonstration edition are a subset of those
designed for its initial application -- the collection and analysis of
"acoustic events".  Absent are the actual data collection modules that
would interface with hardware such as a GPIB card, and the modules which
write the data to disk files.  The data source here is simply a random
wave generator (although a FileRead module and some sample data are also
provided).  Included, though, are modules for scaling and limiting the
signals, cutting segments out of the waveform, and FFT and inverse FFT,
as well as an audio output and two display modules: a straightforward
"Scope", and an X-Y "Lissajous" display.  Up to sixteen channels of
waveform can be held in a packet.


The Demonstration Package
=========================

This demonstration edition of the Web Master has all the capabilities
of the full program, except that a configuration cannot be recorded to
a disk file.  Two Demo startup icons are supplied, as well as an initial
installation icon (see below for how to get started).

The first icon starts up the full environment, with all the modules, and
loads a trivial configuration -- a random generator connected to a scope.
From that starting point, you can experiment with the features of the
system.

The second Demo loads a more complex configuration that connects all
the available types of module in a chain (with one branch).  Two channels
of random wave are first FFTransformed, and a gate is used to extract
narrow segments of the transformed data; this is then inverse-transformed
to produce a narrow-band signal, which is boosted a bit by a scaler and
passed to both audio and visual displays.  (The branch at the end of the
path is just for demonstration: it is actually more efficient to have all
the elements in-line, because they are then managed by a single process.)
Explore this one by using the `Select' and `Param' operations to see what
each element in the chain is doing.  In particular, bring up the parameter
control panel for the Gating element and try changing the cut limit sliders
for channels 0 and 1 to see the effect on the output waves.

A third demonstration configuration is included, but it has no icon to
load it.  You will have to have started the Web with one of the icons
for the other demos, then use the `Load Config' menu option to load
`Data_Demo'.  (To ensure it runs at full speed, you should preferably
clear the original configuration with `New' from the same menu first,
but this is not necessary.  All three demos may be running at the same
time, if you wish.)  This demo displays some actual recorded data in X-Y
form, to give you some idea of its "real world" use.  (The range of data
displayed has been kept short enough so that the program should be able
to read it from (DOS) buffer storage, rather than continually reading it
off disk.  If this isn't so in your case, and you are running from a
floppy, you might want to copy everything -- or just the DATA directory --
to RAM: and try again.)

---------------------------------------------------------------------

Distribution
============

This suite of programs and its documentation is copyright, all rights
reserved.  This demonstration package is freely distributable, however,
provided that it is kept intact as initially provided, and that no charge
is made for its distribution aside from that necessary to cover duplication
and other reasonable overheads.

The full package with the complete existing set of modules is available
from the authors, price by arrangement depending on needs.  We are willing
to write modules for other environments, or to consult in your own
development of such modules.  As mentioned above, sources for the
current data modules are included with the full package.

For more information, please contact:

        Pete Goodeve
        3012 Deakin St #D
        Berkeley, CA 94705

        phone: [phone]

        Internet: [e-mail]


        David Navas
        7 Avocet Dr. #205
        Redwood Shores, CA 94065

        phone: [phone]

        Internet: [e-mail]


For technical information (no orders please), you may also contact:

        Kent Polk
        Div. 17
        Southwest Research Institute
        San Antonio TX 78228-0510

        phone: [phone]
        Internet: [e-mail]

Please use the Internet addresses for information requests only.  Orders
should only be sent through US Mail.

---------------------------------------------------------------------


Getting Started
===============

A full discussion of prerequisites and so on follows, but if you want
to try it out immediately, provided that you are running version 2.04
(or later) of the operating system and have the supplied package available
with all its components in some directory of your system, just follow these
steps:

Double-click on the `Install Libs' icon.  This will copy two required
library files to your `LIBS:' directory: `ppipc.library' (size about 3K)
and `shadow.library' (24K).

Double-click on `Web DEMO 1'.  This will start the Web Master and all
the supplied modules, then load a trivial configuration.  You may play
with this as you desire, but for explanations look to the sections below.

To close down the Web when you are done, use the `QUIT' item of the main
menu.  This shuts everything down, except for two things: the module Master
program is left sleeping in memory and the Traveller program remains
resident (see later for how to remove these items as well).


Prerequisites and Package Components
====================================

The Web program and associated modules need the 2.0 environment, and
ppipc.library and shadow.library must be available in `LIBS:'. (The modules
also use IEEE floating point math, so mathieeedoubbas.library must be there
also.)  In the demonstration package an icon is provided ("Install Libs")
that will copy the two special libraries for you, or you may do it yourself.
(They are in the `Libs' subdirectory.)

The system should run on any Amiga, with or without floating point
hardware.  It will. however, not show its full speed potential on a
basic 68000 machine (!).  The minimum memory needed has not been directly
checked, but it probably should run in a 1MB machine.

Whatever the rest of the environment (Samplers, Filters and so on) three
program files must be available for the Web system to function.  One is
the main `Web' program itself, which is normally started at the beginning
of a session and remains running until the end.  The `Traveller' program
performs all the data-transfers along the links of the Web, and must be
available -- either as a resident module, or in the path for the CLI from
which Web was invoked -- while Web is running.  Things will start up faster
if it is made resident; one Traveller process is started (automatically)
for each Source element in the Web.  The third module is `Brancher',
required to manage the forking of data at branch points; this should be
started when other modules are, before any configuration is built or
loaded; only one brancher process runs, however many branch points are
placed.

The actual data-handling modules must be run after Web has started, but
before building a configuration.  These `Source' and `Filter' modules all
require a common "Module Master" process to be running also before they
will start (distinct from the "Web Master" itself).  This program
(`MODULES/Master') may be started either before or after `Web', but
always before the modules.

Note that when the Web Master is eventually shut down, all the Module
and Traveller processes also terminate.  The Module Master, however,
does not: it remains in memory (dormant) until explicitly shut down with a
`BREAK' CLI command to its process.  (Use the `STATUS' command to find the
right CLI process number `n', then issue `BREAK n', or do the whole thing
in one step with the following command line:

        break `status COM=MODULES/Master`

-- note the back quotes.)  If the Traveller module has been made resident
(as is done by the demos) you may remove it also with the usual `RESIDENT
traveller REMOVE' CLI command.

The `Demo' icons in this package invoke a script (`run_Web') that performs
all the required startups properly.  This is the most convenient way of
starting the system, but the components can be started directly and
individually if preferred, provided that the sequence of startup is
observed.  (Direct execution icons are provided for the Web and Brancher;
the Traveller also has an icon, but it is normally pointless to start
this that way; no icons have been included for the modules, but if you
want to add your own there is no problem.)



Brief Overview of the Master Screen
===================================

The buttons on the right represent the running modules, those at the
bottom the operations that can be performed.  There is a `Project' menu
that contains a fairly standard set of choices: `New', `Load Config',
`Save Config' (inhibited for the demonstration), `About', and `QUIT'.
(The "Direction" Menu over on the right-hand side is not one you are
ever likely to need, but it can be used to change the orientation of
elements placed on the screen.  There is also a `Modules' menu which
is only relevant to the full system; it is disabled for the demo.)

Each module appears as a button on the right-hand panel.  Clicking on one
of these will select that module for relevant operations, such as "Place"
or "Insert". The name on the button is usually not quite the same as the
filename of the Module it represents (here, the program "RanGen" connects
to the "Random Waves" button, "ClipnScale" is "Scale/Clip", and so on).

An operation mode selected from the lower buttons remains in effect until
another is picked -- except for a couple, like `Cancel', that are
momentary.  A description of each button's function follows below.

Other windows will appear on the Web Master screen as well, in the
course of a session.  Each Scope element, for instance, has its own display
window, which is maintained as long as that element exists. And in `Select'
mode, clicking on a part of the diagram causes the appearance of one or two
temporary panels: one gives information about the item that was selected,
the other -- if present -- presents a selection of possible actions to
be taken on that item.  Most modules, too, have Parameter Control Panels,
which can be displayed for an element by selecting in `Param' mode or
using the `Param' button; they will remain until explicitly closed.


The Control Buttons
===================

    Place           When this button is engaged, an instance of the
                    current module (determined by whichever of the
                    right-hand panel buttons is selected) will --
                    if possible -- be placed in the main window at
                    any point at which the (left-hand) mouse button
                    is clicked.
                    This is the default initial mode if no file
                    was specified in the command line.

    Link            In this mode, elements (instances of modules)
                    already placed on the screen may be connected
                    into a chain by data paths.  Click first on the
                    "output connector" (small dot on the right hand
                    side of the element, usually), and then on one
                    of the sides other than the output of the element
                    you wish to connect it to.  If you click on
                    intermediate (empty) points in the window between
                    these two actions, the path will pass through those
                    points as well.
                    You may also begin a new path from an intermediate
                    point on another (making a `Branch'); simply click
                    first on the desired branch point rather than on an
                    output connector.  (This action will be refused if
                    the `Brancher' program is not running.)

    Insert          This is similar to `Place', except that the element
                    can only be inserted into an already existing path.
                    A single click at the desired point in the path will
                    insert a new instance of the selected module there.

    Param           In this mode, clicking on any element that has a
                    control (`Parameter') panel will bring that panel up.
                    This panel remains on the screen until explicitly
                    closed.  (The screen element the panel refers to will
                    remain highlighted while the panel is visible, unless
                    a `Select' or other operation on the same element later
                    clears this.)

    Replace         In this mode, clicking on an element will, if
                    POSSIBLE, replace it with an instance of the
                    currently selected module.  It will fail if the
                    two elements are not compatible (trying to replace
                    a filter in a data path with a source, for example).

    Elide           Is essentially the reverse of `Insert'.  Clicking
                    on an element in a path will remove it but leave
                    the path intact.  It can, of course, only operate
                    on elements that have exactly one input and one
                    output connected. (Or, for convenience, on elements
                    that aren't connected at all.)

    Delete          Clicking on an element will remove that element
                    TOGETHER with any flow links currently connected to it
                    (unless one of these links itself cannot be removed,
                    in which case the diagram will not be changed).

    CUT Link        Click on one end of the flow you wish to remove,
                    then on the other. (It doesn't matter in which
                    order you do this.)
                    Note that you cannot remove a link that leads to
                    a Branch: you must delete one of the branch links
                    first.

    Restore Link    IF neither of the elements previously connected
                    by the last link you cut has been moved in the
                    meantime, clicking this button will restore the
                    connection.  (This is a single action button --
                    the current mode remains unchanged.)

    Move            Click on an element you wish to move, then on
                    the new position you wish it to have.  Any data
                    paths connected to the element will be suitably
                    readjusted (to the program's satisfaction, at any
                    rate! You may want to re-route them yourself).

    Route           Allows you to specify points you wish a given
                    existing path to be adjusted to follow.  Click
                    first on the output connector that is the source
                    of the path, then on the points, in order, that
                    you want it to go through, then finally on the
                    (existing) input connection of that path.
                    Note that you cannot change either of the connection
                    points themselves with this command; this can only
                    be done by cutting and re-Linking.

    Select          In this mode, you can click on any part of the diagram
                    to bring up an information window about that point; the
                    window remains visible until you either select another
                    item or click on some empty space (or `CANCEL').
                    The contents of the information window depend on whether
                    you have clicked on an element, a connecting link, a
                    connection point, or a branch point. (The selected
                    diagram element is highlighted.)

                    If the selected item is an element, its current name
                    is shown within a string gadget, which you may edit
                    as you desire; a unique default name is initially
                    assigned by the program (`SRCn' or `FLTn' as
                    appropriate). (In the full system, this name would
                    be stored when a configuration file is saved.  It is
                    also passed to the modules for their own use, but as
                    it is a new addition none of the supplied modules
                    make use of this yet.)

                    If appropriate, a window of applicable buttons will
                    also pop up; the button labels correspond to mode
                    selections in the main control panel, but only affect
                    the selected item.

                    Buttons available when a placed element is selected
                    are some or all of:

                        `Param', `Move', `Elide', `Delete'

                    Buttons for inapplicable operations are suppressed,
                    except for `Param' (because this is managed by the
                    module itself).

                    A selected Link,  can be `Cut' (if this is possible).
                    A selected BranchPoint can be `Move'd.

                    For a connector on a normal source or filter, only
                    an information panel appears, but if it is a multi-
                    connector element, you will also get a panel of
                    buttons designating the possible choices for that
                    connection (with the current choice highlighted).

                    `Select' mode is engaged initially if a file was
                    specified in the command line (as is actually the
                    case with both demos).

    CANCEL          This button will abort any uncompleted action, such
                    as a Link, Move or Route.  It will NOT undo any
                    operation you have actually completed.  (The program
                    does not currently have an UNDO as such.  Sorry.)


The Project Menu
================

    New             Clears any current configuration from the screen.

    Load Config     Brings up a standard File Requester to select a
                    previously saved Configuration File for loading.
                    It does not clear the screen first; more than one
                    configuration may be loaded at a time, provided
                    that they do not conflict in element positioning
                    or naming.

    Save Config as...   Brings up a Standard File Requester to specify
                        a file into which the configuration is to be saved.
                        (Inhibited in demonstration edition.)

    About Web       Version and Copyright information.

    QUIT Web        Shuts down any running configuration and exits the
                    program.


Temporary Windows
=================

If you move a temporary window (such as the message panel or the `Select'
information window) to another location while it is open, the next time
it pops up it will again be at the new location. (This does not necessarily
apply to windows managed by the modules themselves, such as parameter
panels.)


Loading Configurations from File
================================

A Configuration File is a text file that describes the sequence of steps
needed to recreate a diagram, together with any parameter settings for
individual module instances.

A configuration that is being read expects all the modules that it needs
to be running.  If the read operation encounters a request to place
an element whose module is *not* yet running, it displays the message
"Waiting for Module xxxx", and waits for this to register itself.  If the
module is not already on its way in, you have the choice of either giving
an appropriate CLI command or icon-click to start that module, or aborting
the whole load by clicking `CANCEL'.  The Brancher process is treated here
just like any other module.

A Load operation will also abort if there is any conflict between the
file being loaded and what is already on the screen.  Such conflicts
include overlapping an already existing element or having the same name
as an existing one.  You will usually want to clear the screen (`New' in
the Project Menu) before reading a fresh configuration.  However the two
supplied demo configurations (`config.1' and `config.2') have been
constructed so that they can be loaded together.

The `Load' menu operation uses a standard ASL File Requester for selection.
If you try to Load a non-existent file you will get an error message --
which is immediately covered by the reappearance of the file requester!

Each invocation of the requester remembers the context from the previous
time.  The Web command line option `DIR' (see later) may be used to specify
the initial default directory for the requester.


CLI command line for the Web
============================

The Web can be invoked from the CLI with command-line parameters.

The switch parameter `LACE' (or `INTERLACE' or `-i') sets Interlace mode
for the Web screen.

The parameter `DIR dirname' sets the initial directory for configuration
files.

A configuration file named in the line will be read immediately on start up.
(More than one name can appear, but there will probably be name conflicts
between elements in the two files unless special precautions have been
taken.)

There are no tooltypes recognized by Web as yet.  In most cases anyway you
will probably want to start the whole environment -- with its modules -- as
a unit, so a script is recommended.  Use Xicon or iconX to run that script
from the Workbench.

The common script (`run_Web')used to start up the Web demos accepts up to
three parameters (one of which is the configuration file for that demo,
specified in the command line in the icon).  You can invoke it from the CLI
with added arguments (such as `LACE'), or modify the entry in the icon
ToolTypes, if you like.

                               + + + + +


The Demonstration Modules
=========================

The following modules accompany the demonstration edition of the Web.
The name in brackets is the actual filename of the module (in the MODULES
subdirectory).

  Random Waves  [RanGen]

                Generates a random signal in lieu of real audio events.
                Data is managed as 8-bit integers for the demonstration
                (but is converted to floating point values internally
                by some of the modules, such as the scaler and scope).


  Scale/Clip    [ClipnScale]

                Selectably applies either a scaling factor or a sharp-cut
                limit to all channels of the data.

  FFT           [FFT]

                Performs either a normal or inverse Fast Fourier Transform
                on all channels of the data.  The number of points in a
                channel (set in the source element for the path) MUST be
                a power of two, otherwise NO transform will be performed.

  Gating        [Gate]

                Allows the user to specify `start' and `stop' gating
                points on the waveform.  This module does not actually
                make any change in the waveforms themselves.
                Note that in the current implementation only the first
                Gating element encountered in a path has any observable
                effect.

  Gate Cut      [GCut]

                Applies the cut points specified by a previous Gating
                module in the chain.

  SCOPE         [Scope]

                Displays all the channels of the data in standard
                "time-base" graphical form.

  Liss SCOPE    [Lissajous]

                Displays any two channels of data in X-Y coordinate
                form.

  Play Audio    [Play]

                Generates audio signals of various (user selectable)
                kinds from the data.  This is a very complex, application
                specific module that won't be described in detail here.
                Note that the audio module cannot accept a further event
                while it is still playing the previous one; although the
                Traveller that carries the event being played is released
                as the sound begins, any further arrival during the sound
                period will have to wait until the sound completes.
                Only one Audio element can be active at a time for each
                of the four audio channels (the first instance placed
                grabs the channel); if you set the `Waveform #' for a
                channel to 16 (invalid) the channel will become available.

  Read Events   [FileRead]

                Reads previously recorded data from a file (some examples
                are provided).  Playback rates, ranges, and so on are user
                controllable.

                (Naturally, there is a corresponding FileWrite module
                in the full system, not included in the Demonstration
                Edition.)

  Sync          This is a demonstration of how multiple connections to
                an element are handled.  It accepts three `filter'
                connections (each with it's own input and output).
                Packets passing along `Chan A' and `Chan B' will be
                synchronized: whatever the time they arrive on their
                respective channels, they will always be passed on
                simultaneously. A packet arriving on the `Flush' path,
                though, will release any waiting packets (while not
                being delayed itself).

                Be aware that when you are playing with the more complex
                sort of paths that multi-connector modules allow it is
                quite easy to lock up the data flow.  A full breakdown
                of the ways this could happen would be lengthy, but if
                you do get into such a lockup, it isn't serious.  Simply
                delete the offending module and re-link, to start the
                data flowing again.  (Linking around the module without
                deleting it probably won't be enough, because the data
                packet is almost certainly waiting at that module, and
                won't be affected by breaking the link.)


Module Parameter Panels
=======================

Each module has its own set of panel gadgets (brought up for an instance
of that module by `Param' selection in the Web Master).  These are detailed
in the sections following.

  Random Waves

        #Channels       -- sets the number of channels of data to be
                           generated (1-16)
        #pts/waveform   -- how many points are to be generated for
                           each channel (per packet).
        Pause           -- toggles the generation of data On/Off.


  Scale/Clip

        Factor          -- set a value between 1 and 1000, used as
                           determined by the cycle gadget below.

        [cycle gadget:]

            Off         -- Data is passed straight through without action.

            x Factor/1000
                        -- Data values are multiplied by the Slider
                           factor and divided by 1000, thus scaling the
                           data by a fractional value between 0 and 1.
            x Factor/100
                        -- Multiplies by slider value divided by 100, to
                           give a maximum magnification of 10 times.
            x Factor/10
                        -- Multiplies by slider value divided by 10, to
                           give a maximum magnification of 100 times.
            Clip        -- Slider is taken as a value of n/1000 to clip
                           the data at plus and minus that value.


  FFT

        Transform Type [cycle between:]

            FFT         -- direct FFT
            IFT         -- inverse FFT


  Gating

        Channel         -- The channel on which the gadget values
                           displayed below are to operate.  (The
                           element affects all channels, but you may
                           select parameters for each individually.
                           (Channels are labelled 0-15.)

        Min             -- Sets the lower gate position (scaled as a
                           fraction n/1000 of the whole waveform period).

        Max             -- Sets the upper gate position in the same way.

        Thresh          -- Sets a threshold amplitude value for the
                           channel, for possible reference by other
                           modules (only the audio module currently
                           uses this... in one of the functions not
                           described here).


  Gate Cut

        [cycle gadget:]

            NoGate          -- Gate Marks are ignored; data passed through
                               unchanged.
            Gate Interior   -- The waveform BETWEEN the gate marks (set by
                               a preceding Gating element) is excluded.
            Gate Exterior   -- The waveform OUTSIDE the gate marks is
                               excluded.



  SCOPE

        Pause           -- Freezes the display for that element.  It
                           does NOT stop the flow of data, which just
                           bypasses the paused element.

        Detail of Display   -- this controls how the scope handles a case
                               where there are more points in the waveform
                               that there are pixels across the display
                               window.  (It has no visual effect if there
                               are fewer points per waveform than this.)
         [cycles between:]

            Detail      -- All points are plotted, even if several must
                           be shown in the same single-pixel column.
            Average     -- Plots the average of the points that would
                           otherwise appear in the same column.
                           (Note that this is the slowest of the modes
                           -- even if no actual averaging is being done.)
            Fast        -- Plots only the first point of the group that
                           would appear in one column.

        Waves:  [16 toggle buttons] -- toggles on or off the display
                                       of the corresponding channel.


  Liss SCOPE

        Pause           -- same as for SCOPE above.

        Detail of Display   -- same options as for SCOPE, but the
                               criterion for choosing the number of
                               points to plot is a little arbitrary.

        X-axis Channel  -- selects which of the 16 channels is to
                           be plotted horizontally.

        Y-axis Channel  -- selects which of the 16 channels is to
                           be plotted vertically.


  Play Audio        (Only some functions will be mentioned here -- you
                    may be able to elicit others by experiment.)

        Pause           -- Same as for SCOPE etc., but note that it
                           doesn't take effect until the current sound
                           has finished.

        Channel [cycle] -- selects which of the four audio channels
                           the remaining gadgets operate on.

        Waveform #      -- selects the channel from the data that is
                           to be fed to this audio channel.

        Play Type [cycles between:]

            WFORM       -- Plays the waveform (from the data channel
                           selected by the `Waveform #' slider directly
                           as a sample. The `Duration' and `# Reps'
                           sliders set the play period and number of
                           repeats for the sample. (The duration is
                           in milliseconds provided that the number of
                           points in the waveform is adequate; it will
                           not maintain this for short data lengths.)
            GWFORM      -- As for WFORM, but plays only the data within
                           gate marks.
            Tone        -- These modes play a tone determined by the time
            GTone          of the first zero-crossing encountered in
            OGTone         various ways.  (They will not be considered
                           further.)
            Tonic       -- plays a tone (controlled by the `Scale' slider
                           and `Scale Type' selector, but otherwise
                           unaffected by the controls OR the data) for
                           each packet.

        Volume          -- Sets the overall volume for that channel.


  Read Events       -- the controls here should be fairly self explanatory.
                    I'll leave you to experiment...

                               + + + + +


Principles
==========

The picture to have of the whole system is of a web of "data processing
elements" or "nodes" linked by paths; the paths are traversed by processes
that carry data packets between the elements, where operations are
performed on the data.  Each path begins at a "source" node where the data
initially enters the system; other nodes on the path are generically known
as "filters", because data enters at one point and leaves at another --
possibly after having been altered in form or content.  A filter does not
necessarily change the data at all, though: it may perform some other
action such as displaying it or recording it in a file, passing its input
on unchanged.

At the end of a path there will be one filter that has not been given any
output; at this point, the data packet is simply discarded, and the
travelling process goes back to the source for another load.  (Note that
there is nothing otherwise special about the terminating filter; the path
could be extended if desired by linking it on to further processing.)

It is possible for a path to "branch".  At a branch point, incoming data
is duplicated and passed independently down the two downstream forks.  A
branch is thus effectively both a filter, for data passing down one fork,
and a source, for the duplicated data sent down the other.

A running Web configuration comprises quite a number of processes working
cooperatively to perform the desired job.  The most visible process is the
`Web' itself, which manages the configuration diagram visible on the
screen.  However, this process has no connection with, or even knowledge
of, the data that is flowing through the web.  It communicates with the
other processes via `IPCMessages' and the `ppIPC' protocol.

Packets of data are carried between the elements of the configuration by
`Traveller' processes, one such process for each source of data that is
present (remembering that a branch is also considered a source for one of
its outflows).  Because there is only one Traveller per source, this must
complete its path and return to that source before another packet of data
can be handled.  (In actuality, the Web mechanism does not fundamentally
restrict the number of Travellers that could be associated with a source;
a facility for specifying this number will be provided in a future version.)

Again, though, the Travellers have no real concern with the data they carry
-- this is purely determined by the modules that actually provide and
manipulate the data.  A Traveller is started as needed by the Web master
program, but after that it controls its own progress around the Web path
it is assigned, until the source it is associated with is deleted.

The Modules that actually manage the data, and the format they use, can
be written to suit the needs of the environment.  As well as working on
the data itself, they will usually provide other functions such as a
"Control Panel" for parameter settings, which can be brought up by a
message sent from the Web master.  The protocol the modules need to
register themselves in the Web, and to accept Traveller data and control
messages is well defined, and full information is available to purchasers
who wish to write their own modules.

One point you should keep clear is that there is one, and only one,
running program for each type of module available to the configuration.
You may place as many instances of that type of element as you like in
the diagram (unless there are other constraints -- a module that reads
data from an external hardware channel might be restricted to a single
instance, for example), but that does not start new instances of that
program.  Of course for each new source element, a new Traveller process
will be assigned.

Also take note that, although each module has its own process, that process
is often not the one that does the data manipulation.  Rather, the Traveller
that arrives at that point in the Web simply makes a `function call' to
code supplied by the Module, and executes that within its own process
context.  The alternative used by other Modules -- particularly sources --
is for the module process itself to handle all the data packets from all
the instances of that element; the Traveller sends an IPCMessage
(containing the data) to the Module process, which does the required
operation and passes the message back to the Traveller again.

The disadvantage of the second method is that passing a message from one
process to another also requires that control pass from the first process
to the second, and this involves a delay while the switch takes place.
A simple function call is much faster, and is therefore preferable where
it is appropriate.  On the other hand, some operations are better managed
by a single process, especially when you may need to "queue" -- as when a
data source must wait for data (from a hardware channel); in this case it
is simpler for the Traveller to send a message and wait for its return.
It is trivial to switch a module from one mechanism to the other; the data
is maintained in the same IPCMessage structure for both cases.

Branch points are managed by a further program in almost exactly the same
way as each diagram element, except that the program doesn't appear in
the user selectable buttons.  The single process manages all branch points,
using the IPCMessage mechanism.  An additional Traveller process is used
for one of the forks; the original message continues on down the other.

In most cases each Module must either be a "Source", with just one output,
or a "Filter" with one output and one or more inputs.  A normal Filter
-- although it has ony one input "channel", i.e. it applies the same
algorithm to all input -- is permitted to have several input *connections*;
in other words paths can converge on it.  It can, however, have no more
than one output connection.

The Web can also handle more specialized modules, with more than one actual
functional connection per element like the `Sync' module in this demo. (The
Branch is basically one such as well -- it has one input and two outputs,
although it does no processing).  These modules use a natural extension
of the single Source and Filter mechanism, but will not be described
further here.

                              +  +  +  +  +

                                     -- Copyright 1992 Peter J. Goodeve --