dmIC(3dm)dmIC(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
Page 1
dmIC(3dm)dmIC(3dm)
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 ALSOdmBufferAllocate(3dm), dmICSend(3dm), dmICSetSrcParams(3dm),
dmICSetDstParams(3dm), dmICSetConvParams(3dm), dmICReceive(3dm).
Page 2
