dmic(4)

NAME
     DMimageconverter - Digital Media image conversion and compression

SYNOPSIS
     #include <dmedia/dm_imageconvert.h>

     -ldmedia

     DMimageconverter ic;

DESCRIPTION
     The DMimageconverter data type and its operations implement the Digital
     Media image converter subsystem.  This is a framework which supports a
     variety of compression and decompression devices and algorithms video
     rate JPEG and MPEG.  NOTE: Some realtime compression devices are
     available only as extra optional products.

     The DMimageconverter data type represents an image converter context
     which performs a specific image conversion.  The image conversion is
     principally a specific compression or decompression possibly including
     color space conversion, cropping, zooming, or other such image
     reformatting.  The image converter context takes input from enqueued
     DMbuffers and produces an output queue of new DMbuffers representing
     converted data.

INITIALIZATION OVERVIEW
     An image converter is first selected on the basis of the type of
     conversion desired.  The image converter context is then created.
     Appropriate buffering is created to hold the input and output data.
     Other producers and consumers of image data are initialized at this time
     as well (such as OpenGL graphics rendering and live video I/O).

OPERATIONAL OVERVIEW
     The image converter either encodes or decodes a given specific data
     format.

     The image converter takes input packetized in DMbuffer's.

     The image converter produces output also packetized in DMbuffer's.

     The image converter operates asynchronously to the process.  A process
     may determine when newly converted data is available using select on a
     file descriptor associated with the image converter context.

IMAGE CONVERTER SELECTION
     dmICGetNum, dmICGetDescription, and dmICChooseConverter are used to
     discover the image converters installed in the system.

CONTEXT CREATION
     dmICCreate creates a DMimageconverter context for one of the image
     converters discovered above.  A process may create one or more
     DMimageconverter contexts of the same or different image converter.
     Multiple DMimageconverter contexts are fully independent and share and
     exchange data only as directed by the DMbuffer operations used in the
     process.

     dmICDestroy destroys the specified DMimageconverter. No further
     operations on the context are valid.

BUFFERING
     A mechanism for opaquely passing memory buffering requirements from the
     image converter to the DMbuffer system is available using the following
     operations.

     dmICGetSrcPoolParams adds the image converter's src (input) memory
     buffering requirements to the passed DMparams.

     dmICGetDstPoolParams adds the image converter's dst (output) memory
     buffering requirements to the passed DMparams.

     dmICSetDstPool indicates to the image converter the DMbufferpool from
     which it will allocate each DMbuffer placed in the output queue.

DATA TRANSFER
     An image converter has one input queue and one output queue.

     dmICSend places the DMbuffer on the image converter's input queue.  The
     meaning of the additional DMbuffer arguments is dependent on the image
     converter.  For example, the MPEG image converter uses this mechanism to
     find the reference data needed for interframe decode.

     dmICReceive returns a DMbuffer from the image converter's output queue.

IMAGE FORMAT CONTROL
     The process describes the image format of the input data and the format
     of the desired output.

     The DMparams passed to dmICSetSrcParams describes the image format of
     input to the image converter.

     The DMparams passed to dmICSetDstParams describes the image format of
     output from the image converter.

     mvAddTrackDataParams and dmSetImageDefaults set parameters useful in
     these calls including:

     DM_IMAGE_WIDTH

     DM_IMAGE_HEIGHT

     DM_IMAGE_PACKING

CONVERSION CONTROL
     dmICSetConvParams is used to pass parameters to the image converter to
     control the conversion process.  All converters accept the following
     controls:

     DM_IMAGE_QUALITY_SPATIAL

     DM_IMAGE_QUALITY_TEMPORAL

     DM_IMAGE_BITRATE

VIDEO I/O - VL
     Image data is transported between video I/O devices and image converters
     using the DMbuffer subsystem.  Refer to vlEventRecv(3dm),
     vlEventToDMBuffer(3dm), and vlDMBufferSend(3dm).

GRAPHICS RENDERING AND TEXTURING - OpenGL
     Image data is transported between graphics rendering and texturing using
     the DMbuffer subsystem and operations in the OpenGL DMbuffer extension.

SEE ALSO
     dmICGetNum(3dm), dmICGetDescription(3dm), dmICChooseConverter(3dm),
     dmICCreate(3dm), dmICDestroy(3dm), dmICGetSrcParams(3dm),
     dmICSetSrcParams(3dm), dmICGetDefaultSrcParams(3dm),
     dmICGetDstParams(3dm), dmICSetDstParams(3dm),
     dmICGetDefaultDstParams(3dm), dmICGetConvParams(3dm),
     dmICSetConvParams(3dm), dmICGetDefaultConvParams(3dm),
     dmICGetSrcPoolParams(3dm), dmICGetDstPoolParams(3dm),
     dmICSetDstPool(3dm), dmICGetDstQueueFD(3dm), dmICGetDstQueueFilled(3dm),
     dmICSend(3dm), dmICReceive(3dm).

     dm_jpeg(3dm).

     dmBufferSetPoolDefaults(3dm), dmBufferCreatePool(3dm),
     dmBufferDestroyPool(3dm), dmBufferGetAllocSize(3dm),
     dmBufferGetPoolFD(3dm), dmBufferSetPoolSelectSize(3dm),
     dmBufferAllocate(3dm), dmBufferFree(3dm), dmBufferMapData(3dm),
     dmBufferGetUSTMSCpair(3dm), dmBufferSetUSTMSCpair(3dm),
     dmBufferGetSize(3dm), dmBufferSetSize(3dm), dmBufferGetImageType(3dm),
     dmBufferSetImageType(3dm), dmBufferGetGLPoolParams(3dm).