,fea2kb_rec.3

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" %W%	%G% ESI
.TH FEA2KB_REC 3\-ESPS %G%
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.ds ]Y "\fBESI INTERNAL\fP
.SH NAME
.nf
allo_fea2kb_rec \- allocate memory for an ESPS FEA_2KB file record.
get_fea2kb_rec \- get the next data record from an ESPS FEA_2KB file.
init_fea2kb_hd \- initialize a FEA file header for subtype FEA_2KB.
put_fea2kb_rec \- write the next data record of an ESPS FEA_2KB file.
.SH SYNOPSIS
.ft B
.nf
#include <esps/esps.h>
#include <esps/fea.h>
#include <esps/anafea.h>
#include <esps/fea2kb.h>
#include <esps/feaqhist.h>

struct fea2kb *
allo_fea2kb_rec( hd )
struct header *hd;

int
get_fea2kb_rec( data, hd, file )
struct fea2kb *data;
struct header *hd;
FILE *file;

int
init_fea2kb_hd( hd, avg_pitch, avg_power, lsf_quant, pitch_quant, power_quant,
    pre, preemp_uv, u_avg, v_avg )
struct header *hd;
char *avg_pitch;
char *avg_power;
char *lsf_quant;
char *pitch_quant;
char *power_quant;
struct zfunc *pre;
char *preemp_uv;
short *u_avg;
short *v_avg;

void
put_fea2kb_rec( data, hd, file )
struct fea2kb *data;
struct header *hd;
FILE *file;
.fi
.ft
.SH DESCRIPTION
\fIAllo_fea2kb_rec\fR allocates memory for a FEA_2KB file record and
returns a pointer to it. The memory allocations assume that the header 
was initialized by a call to \fIinit_fea2kb_hd\fR. Because
the size of the allocated record depends on values in the data file header,
it is important to ensure that a FEA_2KB record is consistent with the
header of the file it is being used with [see \fIinit_fea2kb_hd\fR].
Internally, \fIallo_fea2kb_rec\fR calls \fIallo_fea_rec\fR (3\-ESPS), and
then hooks the FEA record up to a \fIfea2kb\fR structure.
.PP
\fIGet_fea2kb_rec\fR reads the next FEA_2KB record from stream \fIfile\fR
into the data structure pointed to by \fIdata\fR, which must have been
allocated by means of a call to \fIallo_fea2kb_rec\fR. The parameter 
\fIhd\fR points to the ESPS header in which the various FEA_2KB fields have been
defined. When the header was originally created, it must have been initialized
by means of \fIinit_fea2kb_hd\fR. An EOF is returned upon end of file.
A positive, non-zero value is returned otherwise.
.PP
\fIInit_fea2kb_hd\fR accepts a pointer \fIhd\fR to an ESPS FEA file header. It
sets \fIhd.hd.fea\->fea_type\fR to FEA_2KB and initializes the record-field
definitions to describe the fields that make up a file of subtype FEA_2KB. It
does this by means of calls to \fIadd_fea_fld\fR (3\-ESPS). For a description
of the various FEA_2KB record fields, see \fIfea_2kb\fR (5\-ESPS).
\fIInit_fea2kb_hd\fR also defines the generic header items described in
\fIfea_2kb\fR (5\-ESPS). For those generic header items which correspond to
the parameters in the call to \fIinit_fea2kb_hd\fR, values are assigned by
\fIinit_fea2kb_hd\fR itself [see \fIfea_2kb\fR (5\-ESPS) for a description of
these parameters]. For the remaining generic header items, values
must be assigned by the calling program. \fIInit_fea2kb_hd\fR returns 1 if
any of the internal calls to \fIadd_fea_fld\fR
(3\-ESPS) returns an error code; otherwise, it returns 0. \fIInit_fea2kb_hd\fR
should be called only when creating a new FEA_2KB file, after the call to
\fInew_header\fR (3\-ESPS).
.PP
\fIPut_fea2kb_rec\fR writes a FEA_2KB data record pointed to by \fIdata\fR
onto the stream \fIfile\fR, which should be an open ESPS FEA_2KB file. The
header must be written out to the FEA_2KB file before calling this function.   
When the header was originally created, it must have been initialized by means
of \fIinit_fea2kb_hd\fR.
.SH EXAMPLES
.if n .ta 33
.if t .ta 3i
.nf
\fB\s-1Reading an existing file:\s+1\fR

FILE *ifp;
struct fea2kb *fea2kb_rec;
struct header *ih;

ih = read_header( ifp );
fea2kb_rec = allo_fea2kb_rec( ih );
if ( get_fea2kb_rec( fea2kb_rec, ih, ifp ) == EOF ) . . .

word = *fea2kb_rec\->bitstream;

\fB\s-1Creating a new file:\s+1\fR

FILE *ofp;
struct fea2kb *fea2kb_rec;
struct header *oh;

oh = new_header( FT_FEA );
if ( init_fea2kb_hd( oh, avg_pitch, avg_power, lsf_quant, pitch_quant, power_quant,
    pre, preemp_uv, u_avg, v_avg ) )
        ERROR_EXIT( "error filling FEA_2KB header" );
 . . .
write_header( oh, ofp );
fea2kb_rec = allo_fea2kb_rec( oh ); 
 . . .
*fea2kb_rec\->bitstream = word;
put_fea2kb_rec( fea2kb_rec, oh, ofp );

.fi
.SH DIAGNOSTICS
If \fIhd\fR does not point to a FEA header of subtype FEA_2KB, the
program terminates with an assertion failure. In \fIget_fea2kb_rec\fR,
if an incomplete record is read, a message is written to \fIstderr\fR.
In \fIput_fea2kb_rec\fR, if an I/O error occurs during the write,
a message is written to \fIstderr\fR and the program exits with status 1.  
.SH BUGS
None known.
.SH SEE ALSO
allo_fea_rec (3\-ESPS), fea_2kb (5\-ESPS).
.SH AUTHOR
Programs and manual page by Jim Elliott.