qccdatasetread.3

spiht for linux this is used to decod and encode vedio i wich all enjoy

.TH QCCDATASETREAD 3 "QCCPACK" ""
.SH NAME
QccDatasetReadWholefile,
QccDatasetReadHeader,
QccDatasetStartRead,
QccDatasetEndRead,
QccDatasetReadBlock,
QccDatasetReadSlidingBlock
\- reading of QccDataset structures from DAT-format files
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccDatasetReadWholefile(QccDataset *" dataset );
.br
.BI "int QccDatasetReadHeader(QccDataset *" dataset );
.br
.BI "int QccDatasetStartRead(QccDataset *" dataset );
.br
.BI "int QccDatasetEndRead(QccDataset *" dataset );
.br
.BI "int QccDatasetReadBlock(QccDataset *" dataset );
.br
.BI "int QccDatasetReadSlidingBlock(QccDataset *" dataset );
.SH DESCRIPTION
These routines implement the reading of
.B QccDataset
datasets from
.BR DAT -format
files.
There are three distinct modes in which the vector-array data
in datasets may be read:
the whole file may be read at once, or
the file may be read in blocks, either non-overlapping
or overlapping (sliding) blocks.
.LP
.B QccDatasetReadWholefile()
reads the
.BR DAT -format
file whose filename is given by
.IR dataset -> filename .
The entire file is read, including the header,
and the vectors are returned in the vector array
.IR dataset -> vectors .
If 
.IR dataset -> vectors
is
.BR NULL ,
.IR dataset -> vectors
is allocated via a call to
.B QccDatasetAlloc() 
prior to reading;
otherwise, it is assumed that sufficient space has already been allocated.
.LP
.B QccDatasetReadHeader()
reads the header information of the
.BR DAT -format
file pointed to by
.IR dataset -> fileptr ,
which must be already open and positioned at the start of the file.
Information read from the header is returned in the fields of
.IR dataset .
.LP
.B QccDatasetStartRead()
must be called before any block-based read of
.IR dataset .
.B QccDatasetStartRead()
opens the file with 
.BR QccFileOpen (3),
reads the file's header with
.BR QccDatasetReadHeader (3),
and allocates storage space, if needed, for the
vector array by calling
.BR QccDatasetAlloc (3)
(note that allocation is performed only if 
.IR dataset -> vectors
is 
.BR NULL).
Prior to calling
.BR QccDatasetStartRead() ,
.IR dataset -> filename
must contain the name of the file and
.IR dataset -> access_block_size
must give the block size desired for subsequent block-based reads.
The remaining fields of
.I dataset
are filled in from the file's header.
After
.B QccDatasetStartRead()
returns,
.IR dataset -> fileptr
contains the
.B FILE
pointer to the open file, and the file
is positioned at the start of the vector-array data, ready for reading the
first block of vectors.
.LP
.B QccDatasetEndRead()
closes a dataset file opened by a previous call to
.BR QccDatasetStartRead() ;
additionally, the vector array,
.IR dataset -> vectors ,
is freed with a call to 
.BR QccDatasetFree (3).
.LP
.B QccDatasetReadBlock()
reads the next block of vectors in the dataset.
.I dataset
must be prepared by a prior call to
.BR QccDatasetStartRead() ;
that is, 
.IR dataset -> fileptr
must point to an open file,
.IR dataset -> access_block_size
must contain the size of the block of vectors to read,
and
.IR dataset -> vectors
must be allocated with space sufficient for storing
the block of vectors.
.B QccDatasetReadBlock()
reads non-overlapping blocks of data from the file;
after
.B QccDatasetReadBlock()
returns, the file is positioned at the start of the subsequent block.
.LP
.B QccDatasetReadSlidingBlock()
reads the next block of vectors in the dataset;
however, contrary to
.BR QccDatasetReadBlock() ,
which reads non-overlapping blocks,
the block of vectors returned by a call to
.B QccDatasetReadSlidingBlock()
overlaps the block returned by the preceding call.
That is, the start of the block returned by
.B QccDatasetReadSlidingBlock()
is one vector after the block returned by the preceding call.
Consequently, the block of data vectors returned by
.B QccDatasetReadSlidingBlock()
"slides" along the dataset with subsequent calls.
When the requested block size starts to reach beyond the end of the file,
the size of the block returned starts to shrink, and
.IR dataset -> access_block_size
is decremented.
.SH "RETURN VALUE"
These routines return 0 on successful completion, 1 if an error occurs
while reading the file.
.SH "SEE ALSO"
.BR QccDatasetWrite (3),
.BR QccDataset (3),
.BR QccFileOpen (3),
.BR QccPack (3)
.SH AUTHOR
Copyright (C) 1997-2009  James E. Fowler
.\"  The programs herein are free software; you can redistribute them an.or
.\"  modify them under the terms of the GNU General Public License
.\"  as published by the Free Software Foundation; either version 2
.\"  of the License, or (at your option) any later version.
.\"  
.\"  These programs are distributed in the hope that they 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 the GNU General Public License
.\"  along with these programs; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.