clGetNextImageInfo(3dm)clGetNextImageInfo(3dm)NAMEclGetNextImageInfo - Get information about a compressed image stream
SYNOPSIS
#include <dmedia/cl.h>
int clGetNextImageInfo(CLhandle handle,
CLimageInfo *info, int sizeOfImageInfo)
ARGUMENTS
handle An open handle that is actively compressing or decompressing.
info A pointer where a CLimageInfo structure is to be placed.
sizeOfImageInfo
The size of the CLimageInfo structure in bytes.
DESCRIPTION
This call is used to obtain information about images (fields or frames)
as they are compressed or decompressed. The information includes size,
time, and a relative image index value.
Before using clGetNextImageInfo it must be enabled by setting the
CL_ENABLE_IMAGEINFO parameter to TRUE via the clSetParam function. This
must be done before calling clCompress or clDecompress.
The CLimageInfo structure is defined in <dmedia/cl.h> and has the
following fields:
typedef struct {
unsigned size; /* size of compressed image in bytes */
unsigned long long ustime; /* time in nanoseconds */
unsigned imagecount; /* absolute media stream counter */
unsigned status; /* additional status information */
} CLimageInfo;
During video compression from an external device, the imagecount field is
initialized to one when the first field is received by the compressor
after a call to clCompress. It counts forward whenever a new field
arrives. If the compression data buffer fills up, then a field will be
dropped, but the imagecount will continue to increase. An application
can thus detect a dropped field by noticing a jump in the imagecount
field of more than one. The ustime indicates the time the uncompressed
field entered the compressor.
During video decompression to an external device, the imagecount field
reflects the count of fields sent by the application to the decompressor.
The ustime indicates the time that field left the decompressor. In
certain situations, fields are repeated on output in which case the
imagecount will remain the same, but the ustime will increase. In the
Page 1
clGetNextImageInfo(3dm)clGetNextImageInfo(3dm)
case of Cosmo decompression, there is a 1 frame delay through
Galileo/IndyVideo before the field actually leaves the machine.
RETURN VALUESclGetNextImageInfo returns SUCCESS when an image is available or
CL_NEXT_NOT_AVAILABLE when there is not. Other errors are defined in
<dmedia/cl.h>.
BUGS
There are two mechanisms for monitoring data flow through a
compressor/decompressor. The routines clQueryFree and clQueryValid are
implemented for all schemes. The clGetNextImageInfo mechanism is
implemented only for CL_JPEG_COSMO.
The CL_JPEG_COSMO compressor will not function properly unless the
application enables clGetNextImageInfo and reads a CLimageInfo structure
corresponding to each compressed image prior to reading the compressed
image data from the dataBuffer argument to clCompress. If the
application enables clGetNextImageInfo and fails to subsequently call the
routine, JPEG data will not be delivered to the application.
An application is not required to enable and read CLimageInfo structures
when using the CL_JPEG_COSMO decompressor.
CAVEATSclGetNextImageInfo will block until the first valid decompressed field
has exited the CL_JPEG_COSMO decompressor. This is the only condition
under which the call blocks.
The ustime field returns a meaningful value only when compressing or
decompressing to an external device.
SEE ALSOCLintro(3dm), clSetParam(3dm), clCompress(3dm), clDecompress(3dm),
clQueryFree(3dm), clQueryValid(3dm), dmGetUST(3dm)
Page 2
