dmicwork(3dm)

NAME
     dmICWork, - call the image converter and have it perform a task

SYNOPSIS
     #include <dmedia/dm_imageconvert.h>

     DMstatus dmICWork(DMimageconverter converter, int *status_flags,
     int *n_input_dequeued, int *n_output_enqueued);

PARAMETERS
     This function calls into the image converter and has it perform a task
     (such as a compress or uncompress) on the buffers that have previously
     been sent to it using dmICSend.

     converter    the converter instance

     status_flags bit field flags returning information about what transpired
                  during the dmICWork call, especially in the event of an
                  error.  Flags include: DM_IC_WORK_NO_STATUS,
                  DM_IC_WORK_ERROR, DM_IC_WORK_NOT_NEEDED,
                  DM_IC_WORK_INSUFFICIENT_INPUT_DATA, and
                  DM_IC_WORK_INSUFFICIENT_OUTPUT_SPACE.

     n_input_dequeued
                  the number of source buffers dequeued by this dmICWork call

     n_output_enqueued
                  the number of output buffers enqueued by this dmICWork call

DESCRIPTION
     This call will have the converter actually perform the conversion on the
     srcBuffer previously sent by dmICSend.  Note that this call is only
     necessary if the default threaded model of dmIC has been turned off, so
     that there is only one thread.  This is done by setting a DM_IC_THREADS
     dmParam to be DM_IC_THREADS_DISABLED, and then calling dmICSetConvParams
     on the DMimageconverter immediately after it is created with dmICCreate.
     See the source code example below.

     dmICWork is a synchronous operation.  When dmICWork returns, the
     conversion is finished, and dmICReceive can be used to pick up the output
     if an output buffer has been enqueued.

     dmICWork must NOT be called in the default threaded dmIC model.

     dmICWork will attempt to do the smallest amount of work possible while
     still achieving something.  For the vast majority of image converters,
     this means it dequeues exactly one buffer, compresses or uncompresses
     that buffer, and enqueues exactly one result buffer.

     Several types of errors can occur in dmICWork, and these will result
     various status flags being returned.  For example, the input queue could
     be empty (DM_IC_WORK_INSUFFICIENT_INPUT_DATA), or the output queue could
     be full (DM_IC_WORK_INSUFFICIENT_OUTPUT_SPACE).  In the case of a
     hardware accelerated image converter, dmICWork will return DM_SUCCESS,
     and will also set the status flag to be DM_IC_WORK_NOT_NEEDED, since the
     hardware has already performed the task. In this case there will be no
     buffers dequeued or enqueued.

EXAMPLE
     The following source code suppresses the default threaded behavior of
     dmIC, and uses the dmICWork function to perform the tasks that by default
     would have been done by a separate thread:

       /*
        * Create the image converter from the index
        */
       if (dmICCreate(convIndex, &imageConverter) != DM_SUCCESS)
           fatal("dmICCreate failed for our imageConverter");

       ... some code not included ...

       /*
        * Set the "disable sproc" converter param
        */
       dmParamsCreate(&cPrms);
       dmParamsSetEnum(cPrms, DM_IC_THREADS, DM_IC_THREADS_DISABLED);
       if (dmICSetConvParams(imageConverter, cPrms) != DM_SUCCESS)
           fatal("should never occur");

       ... some code not included ...

       if (dmICSend(imageConverter, srcBuf, NULL, NULL) != DM_SUCCESS)
           fatal("dmICSend failed");
       dmBufferFree(srcBuf);

       if (dmICWork(imageConverter, &status, &nIn, &nOut) != DM_SUCCESS)
           fatal("dmICWork failed");

       ... use system call "select()" here to wait for results ...

       if (dmICReceive(imageConverter, &dstBuf) != DM_SUCCESS)
           fatal("dmICReceive failed");


SEE ALSO
     dmBufferAllocate(3dm), dmICSend(3dm), dmICSetSrcParams(3dm),
     dmICSetDstParams(3dm), dmICSetConvParams(3dm), dmICReceive(3dm).