SINKPIC

Manage ICEPIC playback from a Midas file/pipe

<input file>    Name of the input file/pipe
<output file>   Name of the RAMDISK or RAM template file
<device>        Name of PIC device port alias in the HWCONFIG file
<decimation>    Amount of upsampling applied to the output 
<frequency>     Frequency parameter for certain output ports
<gain>          Gain parameter for certain output ports

This routine writes data to a RAMDISK file or an in-memory buffer that is
playing out data through an ICE-PIC card.  The <device> is required to
specify the card and which port on the card to perform the playback.
See explain PICDRIVER for more details on HW alias specifications.

The <output file> is assumed to already exist. The size of file is used as the 
circular buffer length and the format must be either SP, SB,SI,SL,CB, or CI. 

The sync flag is used to mark the host system time at the top of each 
cycle through the file (for continuous/circular playback only). 
The /SYNC=label switch can be used to specify a results label to be set at
the top of each RAM buffer.  The result receives the number of seconds since
midnight at which sync occurred. 

The /LOST=label switch can be used keep track of the number of buffers that 
SINKPIC has gone ahead and duplicated if data was not available in the input 
file/pipe when needed.  If the input pointer is overtaken by the output 
pointer, SINKPIC will repeat the last buffer and increment the /LOST=label.

The /REPLAY controls the startup mode of the routine as follows:

 /REPLAY=-N  File	- plays buffer N times and quits (default file2file)
 /REPLAY=0   Stopped	- waits at top of buffer
 /REPLAY=1   Oneshot	- plays buffer once and waits at the top again
 /REPLAY=2   Continuous - plays buffer continuously (default piped)
 /REPLAY=3   StopTop	- stop PIC at next top of buffer
 /REPLAY=4   StopNow	- stop PIC now (does not restart where it left off !!)
 /REPLAY=5   Spin       - play buffer but do NOT read new data from input file
 /REPLAY=6   Reload 	- reload RAM buffer from input file (used with Spin)
 /REPLAY=7   ReStart    - restart continuous playback (resync timecode)
 /REPLAY=8   Abort	- abort processing and close output pipe/file

In NeXtMidas the /REPLAY= switch can be specified by the item number or name.

File mode is the default in file-2-file mode.  In a piped macro, Continuous 
is the default. Oneshot mode is used if REPLAY appears as a state switch 
(no "=" after the switch). All modes can be interrupted by sending controls 
while they are in progress (i.e. through the XPIPE window). The options are 
accessed through the REPLAY MODE control item under SINKPIC primitive menu.

The /REPLAY=0 switch will start the routine stopped at the top of the buffer 
waiting for a control to replay the buffer.  This will be a menu item in XPIPE.

Master/slave relationships between multiple invocations of SINKPIC in the
same macro are handled with the /MASTER=wid and /SLAVE switches.  The /MASTER
switch points to the SYNC MODE widget of another SINKPIC.  Whenever the
master SINKPIC starts or stops its acquisition, it will signal the slave
to start or stop accordingly. The REPLAY widget of the slave should NOT be
set by the user.   It is synchronized and changed by the SINKPIC master.
 
The master/slave relationships may be cascaded to allow multiple slaves.
For example, the following shows one master and 2 slaves.
 
  SINKPIC/WB=1/MASTER=2002        _CB1 RAMFILE1 MOD1A
  SINKPIC/WB=2/MASTER=3002/SLAVE  _CB2 RAMFILE2 MOD1B
  SINKPIC/WB=3/SLAVE              _CB3 RAMFILE3 MOD2A

In NeXtMidas, the /MASTER=value must be the slaved Command ID, not
the slaved WidgetID as in XMidas.  For example:

  SINKPIC/ID=SPM/MASTER=SPS    _cb1 ramfile1 MOD1A
  SINKPIC/ID=SPS/SLAVE         _cb2 ramfile2 MOD1B
 
A "flags" switch along with a string in the hwconfig file are used to modify
the default behavior of the device for special purposes.  See the PICDRIVER
explain file for details.

The Reload and Spin REPLAY options are useful for generating test output data
that is too fast to read off disk but OK to repeat at the end of the RAM
buffer.  This routine may be fed by a SOURCEFILE primitive to process 
different files or sections of files with one instance of SINKPIC.

NOTE: If an initial Reload command is not given, Spin will output whatever 
is currently in the RAM buffer, or garbage if not using a true RAM disk.

Switches:
  /FLAGS=flgs  Add specific flags to config string (see PIC HELP FLAGS)
  /SYNC=label  Result label to be set at top of each buffer (X-Midas)
  /LOST=label  Result label to be set with number of buffers lost/duplicated (X-Midas)
  /PFULL=label Result label to be set with percentage full of buffer (X-Midas)
  /REPLAY=n    Controls the startup mode of the routine
  /MASTER=wid   Widget id of synch mode of slave sink/sourcepic to control (X-Midas)
  /MASTER=rid   Registry ID of slave sink/sourcepic to control (NeXtMidas)
  /SLAVE       Run port in slave mode and use cue from master (uses SGO)
  /SLAVE=SS    Run port in slave mode from master on same side (uses RGO)
  /SLAVE=XT    Run port in slave mode from external trigger (uses XGO|TGO)
  /WAIT=sec    Seconds to wait after M$SYNC before starting
  /POLL=sec    Seconds to pause polling the card for new data
  /DELAY=sec   Seconds of data to read in before starting output (def=0.2)
  /THROTTLE=1  Throttle the output if input is not available by triggering 
		oneshots as each new host buffer becomes available. (ONESHOTS)
  /THROTTLE=2  Throttle the output if input is not available by switching 
		to a slower clock when data is not available. (CONTINUOUS)
                This is only supported with MUXCLK=I.
  /THROTTLE=4  Throttle the output if input is not available by outputting  
		N*CSIZE chunks of the buffer as they become available. (ONDEMAND)
  /SKIP=n      Write only every Nth frame of data to the monitor pipe.
  /WRAP	       Automatically repeat input at end of input file
  /SRATE=freq  Override samplerate in file for actual playback
  /TRATE=freq  Override throttled rate (def = max(10kHz,rate/8)) for /THROTTLE=2
  /STATS=N     Show buffer status at top of every Nth buffer (if X-Midas N=1 only)
  /ARCHSF=N    DeArchive each from N Separate Files (archname_XXXXX count)
  /ARCHSFN=fmt Format for Seperate File Name (ex fmt=filename_%04d) or (_%x to specify just after last _)
  /ASYNC       Use asynchronous read thread (needed for throttling of high-latency input devices)

NeXtMidas Only Switches:
  /MON=pipe	Name of the monitor output file or pipe (used to be a parameter)
  /MONITOR=mode Output pipe monitor mode = OFF,ASYNC,INFO,FULL
  /PICKEYS=table Table of extra keys to set or get after initialization, example syntax:
                 {key1=val,key2=QUERY,key3} where key2 and key3 are only added to query list

Control Widgets: (X-Midas)
	1. M:REPLAY MODE
	2. M:SYNCH MODE
	3. D:SAMPLE RATE
	4. L:REDUCTION
	5. L:NCYCLE
	6. L:LOST (Host buffer fall behind count)
	7. L:MISS (Card buffer fall behind count)

Messages: (X-Midas)
        MGO     INFO=replaymode D:time to take action
                returns =MGO with actual time of event
        RATE    D:samplerate
        DEC     D:decimation