feasd.tme

speech signal process tools

It is permissible for all samples to be smaller\*(--that is,
.i max_value
is an upper bound rather than an exact maximum.
For example, if the data are from an A/D converter,
.i max_value
may be used to indicate the maximum value
that can be represented by the converter.
In multichannel files,
.i max_value
may have one component for each channel
or may be a single value applying to all channels.
.lp
The header of a FEA_SD file also contains a definition for one field
given by the following table:
.pp
.TS
center, box, tab(;);
c | c | c | c | c | c 
c | c | c | c | c | c.
Name;Size;Rank;Dimen;Type;Enums
=
samples;no. of channels;1;NULL or {size};any numeric;NULL
.TE
.lp
The field can be created by calling
.i init_feasd_hd (3-ESPSu).
.sh 2 "External Record Format"
.pp
When the size of the field "samples" is 1, there is a single channel;
if no additional fields are present, each record is a single sample of
the given type, and the part of the file after the header is just a
sequence of such samples.  That is, the non-header part of the file is
identical to that of an SD file of the same data type and containing
the same data.  When the size is greater than 1, the file contains
multi-channel data.  The data portion of the file is still just a
sequence of samples when no additional fields are present.  However,
the samples are conceptually grouped into vectors, each containing one
sample from each channel.  In general, each record in the file
contains such a vector.
.pp
Each complex item is represented externally by a consecutive pair of
real items with the real part first.
.sh 2 "Internal Record Format\*(--The Support Structure"
.pp
Most programs that deal with FEA_SD files will use the support
routines in the ESPS library and will not directly use the information
in the tables above.  (These routines are discussed in the next
subsection.)  For example programs will usually define the "samples"
field in a file header by calling the support function
.i init_feasd_hd (3-ESPSu)
rather than by calling
.i add_fea_field (3-ESPSu)
directly.
.pp
Programs that deal with FEA_SD files do so in terms of C structures of a
particular type (struct feasd).  A structure of this type contains the
location of a data array together with other information that provides
convenient access to the data or is used by the FEA_SD support
functions.  For example the read and write functions,
.i get_feasd_recs (3-ESPSu),
.i get_feasd_orecs (3-ESPSu),
and
.i put_feasd_recs (3-ESPSu),
take pointers to such structures as parameters
and either read data into the associated data array or write data from it.
.pp
Here is the definition of the
.i feasd
structure as given in
.i <esps/feasd.h>:
.nf
.ta .5i 1i 1.75i

    struct feasd {
	short		data_type;
	long		num_records, num_channels;
	char		*data, *ptrs;
    };
.fi
.lp
The structure members have the following meanings.
.ip data_type
An integer code indicating the data type of the samples as stored in memory.
Legal values are give by the ten type-code constants
DOUBLE, FLOAT, etc. shown in the table in Subsection 2.2.
They are defined in the include file
.i esps/esps.h.
This type need not match the data type
of a FEA_SD file used for input or output;
if the types are different,
automatic type conversion takes place upon input or output.
.ip num_records
The number of consecutive records that may be stored in the data part
of this
.i feasd
structure (see below).
.ip num_channels
The number of channels of sampled data.
.ip data
A pointer to the beginning of a data array for storing the sampled data from
.i num_records
elements of the type indicated by
.i data_type.
For single-channel data, the pointer
.i data
can simply be cast to an appropriate type and regarded as pointing to the
beginning of a one-dimensional array of samples.
The appropriate types are (char *) for BYTE data, (short *) for SHORT data,
(double_cplx *) for DOUBLE_CPLX data, etc.
For example, with declarations
.ip
.i
struct feasd	*rec;
.br
short	*s_data;
.r
.ip
suppose
.i rec
points to a
.i feasd
structure initialized to hold SHORT data.
(So
.i rec \->\c
.i data_type ==\c
.i SHORT .)
Then, after the assignment
.ip
.i "s_data = (short *) rec\->data;"
.ip
sample number
.i s
may be accessed as
.i s_data [\c
.i s ].
For multi-channel files,
the storage is conceptually a 2-dimensional array with
.i num_records
rows and as many columns as there are channels.
It is the purpose of the structure member
.i ptrs,
discussed next,
to make access to the data
as convenient as indexing an actual two-dimensional array.
.ip ptrs
When appropriately cast,
.i ptrs,
if not NULL, points to the first element of an array of
.i num_records
pointers,
each of which points to the first element of a row of the data array.
Appropriate types for the cast are (char **) for BYTE data, (short **) for
SHORT data, etc.
To continue the example begun above under
.i data,
suppose a declaration
.ip
.i short	**s_ptr;
.ip
and a cast
.ip
.i "s_ptr = (short **) rec\->ptrs;"
.ip
then sample number
.i s
of channel
.i c
can be accessed as
.i s_ptr [\c
.i s ][\c
.i c ].
The function
.i allo_feasd_recs (3-ESPSu),
which creates
.i feasd
structures, has a parameter that determines whether to set up the pointer
array or to make the
.i ptrs
structure member NULL.
.sh 2 "FEA_SD Support Functions"
.pp
There are five FEA_SD support functions:
.ip
.nf
.i "init_feasd_hd  " "	\*(--\ initialize a FEA file header for subtype FEA_SD"
.i "allo_feasd_recs" "	\*(--\ allocate memory for FEA_SD file records"
.i "get_feasd_recs " "	\*(--\ get data records from an ESPS FEA_SD data file"
.i "get_feasd_orecs" "	\*(--\ get overlapping data from an ESPS FEA_SD data file"
.i "put_feasd_recs " "	\*(--\ write data records to an ESPS FEA_SD file"
.fi
.lp
See the
.i feasd_recs (3-ESPSu)
manual entry for full documentation.
.sh 3 "init_feasd_hd"
.pp
Before a newly created FEA file header (\c
.i i.e.
one obtained from
.i new_header (3-ESPSu))
can be used as a FEA_SD header, it must be initialized, preferably by
.i init_feasd_hd.
A call of this function has the form
.ip
init_feasd_hd(hd, data_type, num_channels, start_time, mult_st_t, record_freq)
.lp
The function takes a pointer
.i hd
to an ESPS FEA header and sets the item
.i hd\->hd.fea\->fea_type
in the FEA-specific part of the header equal to FEA_SD.
(This is an integer code, defined in
.i esps/fea.h,
that identifies the file as a FEA_SD file).
The function also initializes the header to define the field "samples".
The argument
.i data_type
determines
the data type of the field;
legal values are given by the ten data-type constants
BYTE, SHORT, LONG, etc.
The integer argument
.i num_channels
gives
the size of the field.
The arguments
.i start_time
and
.i record_freq
initialize the required generic header items
(see Subsection 4.1).
The argument
.i mult_st_t
is a flag indicating whether there is 
a starting time for each channel or just one for the entire file.
If the value is YES,
.i start_time
points to the beginning of an array containing the values.
If the value is NO,
.i start_time
is a pointer to a single element.
By contrast,
.i record_freq
holds the actual value, not a pointer to it.
The function returns a value 0 upon successful completion
and a nonzero error code otherwise.
.sh 3 "allo_feasd_recs"
.pp
Before a FEA_SD file can be read or written by the support functions,
a
.i feasd
structure must be created.
This is done by the function
.i allo_feasd_recs.
A call has the form
.ip
allo_feasd_recs(hd, data_type, num_records, data, make_ptrs)
.lp
.pp
The function allocates memory for a 
.i feasd
structure and fills in values for the structure members.
If requested, it will also allocate storage for the associated data array,
the pointer array, or both.
(See
.i data
and
.i ptrs
in the previous subsection.)
The function allocates the data array if the argument
.i data
is (char *) NULL.
If the argument is non-NULL,
it should point to the beginning of a suitable block of storage,
and the pointer value is simply copied into the
.i data
member of the structure.
When the value of the argument
.i make_ptrs
is YES, the function creates
the pointer array.
When
.i make_ptrs
is NO,
.i ptrs
is made NULL.
The dimensions of the array are determined by the argument
.i num_records
and the size of the "samples" field defined in the header
.i *hd,
which gives the number of channels.
The
.i data_type
argument determines the data type of the array.
Legal values are given by the ten data-type constants
BYTE, SHORT, LONG, etc.
The
.i data_type
and
.i num_records
members of the structure are filled in
with the values of the corresponding function arguments.
The returned value is a pointer to the structure upon successful completion,
or NULL in case of failure.
When the data area is supplied by the programmer, its size should be at least
.i num_records
*
.i num_channels
*
.i typesiz (\c
.i data_type ),
where
.i num_channels
may be obtained as the value of
.i get_fea_siz (\c
"samples",
.i hd, (\c
.i short " *)
.i NULL, (\c
.i long " **)
.i NULL ).
.sh 3 "get_feasd_recs
.pp
With a
.i feasd
structure and a FEA_SD header in hand and a file open for reading,
it is possible to read some data.
The FEA_SD function analogous to the SD support functions
.i get_sd_rec {\c
.i dfs }
is
.i get_feasd_recs.
A call has the form
.ip
get_feasd_recs(rec, start, num_records, hd, file)
.lp