vqfea.3

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\"  @(#)vqfea.3	1.3 29 Apr 1997 ESI
.TH VQFEA 3\-ESPSu 29 Apr 1997
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH NAME
.nf
allo_vqfea_rec \- allocate memory for FEA_VQ file record
get_vqfea_rec \- get the next data record from an ESPS FEA_VQ data file
init_vqfea_hd \- initialize an FEA file header for subtype FEA_VQ
put_vqfea_rec \- write the next data record of an ESPS FEA_VQ file
.SH SYNOPSIS
.ft B
.nf
#include <esps/esps.h>
#include <esps/fea.h>
#include <esps/vq.h>

struct vqcbk *
allo_vqfea_rec(hd)
struct header *hd;

int
.br
get_vqfea_rec(data, hd, file)
.br
struct vqcbk *data;
.br
struct header *hd;
.br
FILE *file;

int
init_vqfea_hd(hd, rows, cols)
struct header *hd;	\fI/*FEA file header*/\fP
long rows;		\fI/*number of rows in codebook*/\fP
long cols;		\fI/*number of columns in codebook*/\fP

void
.br
put_vqfea_rec(data, hd, file)
.br
struct vqcbk *data;
.br
struct header *hd;
.br
FILE *file;
.fi
.ft
.SH DESCRIPTION
.I allo_vqfea_rec
allocates memory for a FEA_VQ file record and returns a pointer to it.
The number of  elements allocated to 
.I clusterdist
and
.I clustersize
os given by the generic header item
.I "codebook size."  
The number of elements allocated to 
.I codebook
is given by the product of the two generic header items 
.I "codebook size" 
and
.I "codeword dimen."  
(These allocations assume that the header 
was initialized with 
.I init_vqfea_hd
(3\-ESPSu).  
Since the size of the allocated record depends on values in the data
file header, it is important to be sure that a given FEA_VQ record is
consistent with the header of the file it is being used with.  (See
.I init_vqfea_hd
(3\-ESPSu).  
Internally, 
.I allo_vqfea_rec
calls 
.I allo_fea_rec
(3\-ESPSu) and then hooks the FEA record up to a vqcbk struct.  Note that, 
like other components, the codebook is stored in the FEA record.  Thus, 
for example, you cannot assign an arbitrary pointer to the codebook and 
expect \fIput_vq_rec\fP to work properly.  
.PP
.I get_vqfea_rec
reads the next FEA_VQ 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 
.I allo_vqfea_rec.
The parameter 
.I hd
points to the ESPS header in which the various FEA_VQ fields have been
defined.  When the header was originally created, it must have been 
initialized by means of 
.I init_vqfea_hd
(3\-ESPSu).  
An EOF is returned upon end of file.  A
positive non-zero value is returned otherwise.  
.PP
.I Init_vqfea_hd
takes a pointer 
.I hd
to an ESPS FEA header.  It sets
.I hd.hd.fea\->fea_type
to FEA_VQ and initializes the record-field definitions to define the
fields that make up a file of subtype FEA_VQ.  It does this by means of
calls to 
.I add_fea_fld
(3\-ESPSu).  
The parameter 
.I rows 
specifies the size of the fields 
.I clusterdist
and
.I clustersize.  
The size of the 
.I codebook
field is 
.I "rows * cols".  
For a description of the various FEA_VQ record fields, see FEA_VQ(5\-ESPS).
.I Init_vqfea_hd
also defines the generic header items
.I "design_size"
and
.I "codeword_dimen",
and it sets their values respectively to 
.I rows
and
.I cols.  
.I Init_vqfea_hd
returns 1 if any of the internal calls to 
.I add_fea_fld
(3\-ESPSu) return an error code.  Otherwise, it returns 0.  
.I Init_vqfea_hd
should only be called when creating a new FEA_VQ file, after the 
call to 
.I new_header
(3\-ESPSu).  
.PP
.I put_vqfea_rec
writes an FEA_VQ data record pointed to by \fIdata\fR onto the stream
\fIfile\fR, which should be an open ESPS VEA_VQ file.   The header must
be written out to the FEA_VQ file before calling this function.   
When the header was originally created, it must have been 
initialized by means of 
.I init_vqfea_hd
(3\-ESPSu).  
.SH EXAMPLE
.if n .ta 33
.if t .ta 3i
struct vqcbk *p;	
.br
struct header *ih;
.br
ih = read_header(file);	/* read FEA_VQ file header */
.br
p = allo_vqfea_rec(ih);	/* allocate record */
.br
design_size= *p->design_size;	/* record reference */
if(get_vqfea_rec(p,ih,file) == EOF) . . .

.nf
ih = new_header(FT_FEA);
if (init_vqfea_hd(fea_oh, c_rows, fea_dim) != 0) 
         ERROR_EXIT("error filling FEA header");
 .
 .
 .		
write_header(ih);
p = allo_vqfea_rec(ih); 
 .
 .
 .
put_vqfea_rec(p,ih,file);
.fi
.SH DIAGNOSTICS
If \fIhd\fR does not point to a FEA header of subtype
FEA_VQ, then the program terminates with an assertion failure.
In
.I get_vqfea_rec,
if an incomplete record is read, a message is printed on the standard error
output.
With
.I put_vqfea_rec,
if an I/O error occurs during the write, a message is written to standard error
and the program exits with status 1.
.SH BUGS
None known.
.SH SEE ALSO
.nf
\fIeopen\fR(3\-ESPSu), \fIallo_fea_rec\fR(3\-ESPSu), \fIcopy_header\fR(3\-ESPSu), 
\fInew_header\fR(3\-ESPSu), \fIread_header\fR(3\-ESPSu), FEA_VQ(5\-ESPS),
FEA(5\-ESPS), ESPS(5\-ESPS)
.fi
.SH AUTHOR
John Shore