qccimgimagesequence.3

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

.TH QCCIMGIMAGESEQUENCE 3 "QCCPACK" ""
.SH NAME
QccIMGImageSequence \- 
data structure 
.B QccIMGImageSequence
for a sequence of images
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BR "int QccIMGImageSequenceInitialize(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceAlloc(QccIMGImageSequence *" image_sequence );
.br
.BR "void QccIMGImageSequenceFree(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceLength(const QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceSetCurrentFilename(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceIncrementFrameNum(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceFindFrameNums(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceReadFrame(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceWriteFrame(QccIMGImageSequence *" image_sequence );
.br
.BR "int QccIMGImageSequenceStartRead(QccIMGImageSequence *" image_sequence );
.br
.SH DESCRIPTION
QccPack provides data structure
.B QccIMGImageSequence
for representing a sequence of images.
It is generally assumed that all images of the sequence
have the same size and color depth.
The frames of the image sequence are indexed by a
"frame number" which runs consecutively from some
starting frame number to an ending frame number.
.LP
The main component of a
.B QccIMGImageSequence
structure is a
.BR QccIMGImage (3)
structure that holds the current frame of the image
sequence.
.SH "DATA STRUCTURE"
The
.B QccIMGImageSequence
data structure is defined as:
.RS
.nf

typedef struct
{
  QccString filename;
  int start_frame_num;
  int end_frame_num;
  int current_frame_num;
  QccString current_filename;
  QccIMGImage current_frame;
} QccIMGImageSequence;
.fi
.RE
.LP
The fields of
.B QccIMGImageSequence
are as follows:
.TP
.I filename
The filename template for the image sequence.
.TP
.IR start_frame_num ", " end_frame_num
The numbers of the first and last frames of the image sequence.
.TP
.IR current_frame_num
The number of the current frame.
.TP
.IR current_filename
The filename for the current frame.
.TP
.IR current_frame
The current frame.
.SH "FILE ACCESS"
A
.BR QccIMGImageSequence
structure holds only a single frame of the image sequence,
and most routines that process image sequences
will process a single frame at a time.
Consequently, image sequences are
normally read and written by specifying a filename template that is
"filled in" with the current frame number to access the
current frame.
The
.IR filename
field of the
.BR QccIMGImageSequence
structure is the filename template, and it is a 
.BR printf (3)
format string that contains exactly one numerical descriptor
(i.e., %d, %x, etc.).
For example, if 
.IR filename
is given as
.IR imagefile.%03d.pgm ,
then the image sequence will be accessed as
.IR imagefile.000.pgm ", " imagefile.001.pgm ", " imagefile.002.pgm ", ...,"
assuming that the first frame of the sequence is frame number 0.
The filenames, as well as the numerical descriptor in the filename template,
must use zero padding on the left so that the files are processed in
the correct numerical order.
.SH "ROUTINES"
.B QccIMGImageSequenceInitialize()
should be called before any use of a
.B QccIMGImageSequence
structure.
.B QccIMGImageSequenceInitialize()
initializes the fields of
.I image_sequence
to the following values:
.RS

.IR filename :
.B NULL
string
.br
.IR start_frame_num :
0
.br
.IR end_frame_num :
0
.br
.IR current_frame_num :
0
.br
.IR current_filename :
.B NULL
string
.RE
.LP
.B QccIMGImageSequenceAlloc()
allocates storage space for 
.IR image_sequence->current_frame
by calling
.BR QccIMGImageAlloc (3).
The size of
.IR image_sequence->current_frame
must be set via a call to
.BR QccIMGImageSetSize (3)
or
.BR QccIMGImageSetSizeYUV (3)
prior to calling
.BR QccIMGImageSequenceAlloc() .
.LP
.B QccIMGImageSequenceFree()
frees
.I image_sequence->current_frame
via a call to
.BR QccIMGImageFree (3).
.LP
.BR QccIMGImageSequenceLength()
calculates the number of frames of
.IR image_sequence .
It is assumed that no frames are skipped between the starting frame
and the ending frame, so the number of frames isa
.IR image_sequence->end_frame_num " - " image_sequence->start_frame_num " + 1."
.LP
.BR QccIMGImageSequenceSetCurrentFilename()
updates
.IR image_sequence->current_filename
by placing the current frame number,
.IR image_sequence->current_frame_num ,
into the filename template,
.IR image_sequence->filename .
This is done by having
.IR image_sequence->current_filename
be the output of a call to
.BR QccStringSprintf (3)
wherein
.IR image_sequence->filename
is the format string.
.LP
.BR QccIMGImageSequenceIncrementFrameNum()
increments
.IR image_sequence->current_frame_num
and then calls
.BR QccIMGImageSequenceSetCurrentFilename()
to update the current filename.
.LP
.BR QccIMGImageSequenceFindFrameNums()
determines the starting and ending frame numbers for the specified
image sequence. Using the filename template,
.IR image_sequence->filename ,
.BR QccIMGImageSequenceFindFrameNums()
scans all the frame numbers matching the template, checking for
the existence of a file with that frame number.
.IR image_sequence->start_frame_num
is set to the first frame number for which a file exists.
.IR image_sequence->end_frame_num
is set to the last frame number for which a file exists, such
that all frame numbers between
.IR image_sequence->start_frame_num
and
.IR image_sequence->end_frame_num
correspond to existing files; i.e., the sequence of
frames from the starting frame number to the ending frame
number is consecutive with no skipped frames.
.LP
.BR QccIMGImageSequenceReadFrame()
calls
.BR QccIMGImageSequenceSetCurrentFilename()
to update the current filename, and then
.BR QccIMGImageRead (3)
to read the current frame, with the current frame being returned in
.IR image_sequence->current_frame .
.LP
.BR QccIMGImageSequenceWriteFrame()
calls
.BR QccIMGImageSequenceSetCurrentFilename()
to update the current filename, and then
.BR QccIMGImageWrite (3)
to write
.IR image_sequence->current_frame
to the current filename.
.LP
.BR QccIMGImageSequenceStartRead()
calls
.BR QccIMGImageSequenceReadFrame()
to read the first frame of the sequence, i.e.,
the one with frame number
.IR image_sequence->start_frame_num .
.SH "RETURN VALUE"
These routines return 0 on success, and 1 on failure, except
.BR QccIMGImageSequenceLength() ,
which returns the length of the image sequence.
.SH "SEE ALSO"
.BR QccStringSprintf (3),
.BR QccFileWriteDouble (3),
.BR QccIMGImage (3),
.BR QccPackIMG (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.