\"  iionodT.roff from ObjectProDSP 0.1
\"  Copyright (C) 1994, Mountain Math Software. All rights reserved.
\"  
\"  This file is part of ObjectProDSP, a tool for Digital Signal
\"  Processing design, development and implementation. It is free
\"  software provided you use and distribute it under the terms of
\"  version 2 of the GNU General Public License as published
\"  by the Free Software Foundation. You may NOT distribute it or
\"  works derived from it or code that it generates under ANY
\"  OTHER terms.  In particular NONE of the ObjectProDSP system is
\"  licensed for use under the GNU General Public LIBRARY License.
\"  Mountain Math Software plans to offer a commercial version of
\"  ObjectProDSP for a fee. That version will allow redistribution
\"  of generated code under standard commercial terms.
\"  
\"  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 version 2 of the GNU General
\"  Public License along with this program. See file COPYING. If not
\"  or if you wish information on commercial versions and licensing
\"  write Mountain Math Software, P. O. Box 2124, Saratoga, CA 95070,
\"  USA, or send us e-mail at: support@mtnmath.com.
\"  
\"  You may also obtain the GNU General Public License by writing the
\"  Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
\"  USA.  However if you received a copy of this program without the
\"  file COPYING or without a copyright notice attached to all text
\"  files, libraries and executables please inform Mountain Math Software.
\"  
\"  ObjectProDSP is a trademark of Mountain Math Software.
\"  
.H 1 "ObjectProDSP binary format data files"
\".LINE \label{Sec:FileFormat}

Output node
\".LINE \DppNm{OutputNode}
`OutputNode'
writes its input channels to a disk file.
This file can be read by input node
\".LINE \DppNm{InputNode}.
`InputNode'.
The data is written
in binary exactly as it is generated.

This file format is convenient for saving multiple channels from
a network to a single file. All the data in all the channels directed
to this node will be saved as a single file. This data can then
be accessed any time in the future in the same sequence
in which it was generated.

This node is also used for ObjectProDSP validation and regression testing.
See the section on validation for more information on this topic.

.H 2 "OutputNode"

The parameters for
\".LINE \DppNm{OutputNode}
`OutputNode'
include a block size
to determine the consecutive words that
are written from a single channel to the disk file. Making this larger
will improve efficiency at the cost of more memory for buffers.

.H 2 "InputNode"

\".LINE \DppNm{InputNode}
`InputNode'
reads most of the characteristics of its input data 
in the file header. This includes the number of channels.
Pamameter `DeltaOut' controls how often the node is scheduled
and can influence efficiency. You can also ignore the input
sample rate and force it be 1 on the base channel.

This node must be able to read its input file
at the time its constructor is called or it cannot initialize itself
properly from the input file. Any node that does not succeed in doing
this read will be unusable later.

.H 2 "File format"

The files written by
\".LINE \DppNm{OutputNode}
`OutputNode'
and read by
\".LINE \DppNm{InputNode}
`InputNode'
begin with
a header format organized in packets. A sequence of packets
that gives general header information is followed by a packet giving
information for each channel.
\".LINE The format of these packets is defined in Table~\PageRef{Tbl:PktFmt}.
Each packet has the following format.

\".CAPTION 3 "Disk file packet format" "Tbl:PktFmt"
.TS
center;
lll.
Field	Size in bits	Contents
Type	8	Code for packet type
Size	8	Length of data field in bytes
Identifier	32	Data identification
Data	\
\".LINE Size$\times$8 
Size * 8\
	Packet data
.TE

The general header information and the information for
each channel is contained in the
\".LINE sequence of packets defined in Table~\PageRef{Tbl:FileHdr}.
following sequence of packets.

\".CAPTION -1 "Disk file header packets" "Tbl:FileHdr"
.TS 
center;
llll.
Packet type	Code	Identifier	Data
FileEltsHeader	0	NONE	\
\".LINE See Table~\PageRef{Tbl:FileElts} 
See following table\

FileEltsNodeName	1	NONE	Node name
FileEltsCaption	2	NONE	Caption parameter
FileEltsChannelHeader	3	NONE	\
\".LINE See Table~\PageRef{Tbl:ChnHdr} 
See table for channel header\

.TE

The data in the FileEltsHeader packet is structured as
\".LINE shown in Table~\PageRef{Tbl:FileElts}.\index{FileEltsHeader}
follows.
\".CAPTION -1 "FileEltsHeader\index{FileEltsHeader} packet structure" "Tbl:FileElts"
.TS
center;
lll.
Field	Size in bits	Interpretation
DataType	32 (enum DataType)	\
\".LINE See Table~\PageRef{Tbl:DataType}
See following table\

NumberOfChannels	16	Input channels
BlockSize	32	Contiguous data size
.TE

The codes for the DataType field are
\".LINE listed in Table~\PageRef{Tbl:DataType}\index{DataType}.
listed below.
\".CAPTION -1 "DataType\index{DataType} codes" "Tbl:DataType"
.TS
center;
lll.
Name	Code	Size of one MachWord in bits
ArithDouble	1	64
ArithInt16	2	16
ArithInt32	3	32
ArithFloat	4	32
.TE

The packet for each channel header contains
\".LINE the data shown in Table~\PageRef{Tbl:ChnHdr}.
the following data.
\".CAPTION -1 3 "Channel header" "Tbl:ChnHdr"
.TS
center;
lll.
Field name	Size in bits	Interpretation
NumeratorSampling	32	Samples input (ratio)
DenominatorSampling	32	Samples output (ratio)
FirstSample	64 (double)	Time of first output
ElementSize	32	MachWords in one sample
NumberWords	32 (long)	MachWords in file
.TE

This header information is followed with a series of data packets
containing samples from a single channel. The data from each channel
is in sequential order. The sequences of the packets from different
channels is determined by the order in which the data is written
and is not easy to determine.
The format of these packets is
\".LINE is shown in Table~\ref{Tbl:ChanData}.
as follows.
\".CAPTION "Data packet format" "Tbl:ChanData"
.TS
center;
lll.
Field	Size in bits	Interpretation
Channel	16	Index of this channel
Word index	32	Index of first word
Data	\
\".LINE 8$\times$sizeof(MachWord)$\times$BlockSize
8*sizeof(MachWord)*BlockSize\
	Node input data
.TE

