clGetNextImageInfo(3dm)                                clGetNextImageInfo(3dm)


NAME
     clGetNextImageInfo - 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


     case of Cosmo decompression, there is a 1 frame delay through
     Galileo/IndyVideo before the field actually leaves the machine.


RETURN VALUES
     clGetNextImageInfo 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.


CAVEATS
     clGetNextImageInfo 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 ALSO
     CLintro(3dm), clSetParam(3dm), clCompress(3dm), clDecompress(3dm),
     clQueryFree(3dm), clQueryValid(3dm), dmGetUST(3dm)


                                                                        Page 2