The Image Conversion Library allows you to choose among the image converters in the system. To find a converter and create an instance of it, the Image Conversion Library enables you to do the following:

---

Note: Many of the Image Conversion Library functions return a DMstatus value. The value is DM_SUCCESS if they succeed, DM_FAILURE if not. After a receiving a DM_FAILURE, your application can call the function dmGetError() or dmGetErrorForPID() to return an error message and error number. See “Digital Media Error Handling” in Chapter 3 for more information.

---

Use the function dmICGetNum() to find the number of image converters available:

int dmICGetNum ( void )

The function returns an integer that is the number of available image converters.

Use the function dmICGetDescription() to obtain the description of a converter:

DMstatus dmICGetDescription ( int i, DMparams *converterParams )

The parameter i, which is the index of the converter, is the key to the description returned. The converter's index is an integer between 0 and n-1 where n is the number of image converters returned by dmICGetNum(). The parameter converterParams points to a previously created DMparams data structure. If dmICGetDescription() is successful, the data structure contains six parameters whose values characterize the converter.

---

Tip: The application controls the creation and destruction of DMparams structures. See the upcoming section “Using the Image Conversion API” for examples.

---

To extract the converter's description from the structure pointed to by converterParams, you submit parameter keywords to the appropriate DMparams-querying functions. The left side of the following table lists the six parameter keywords and the relevant DMparams-querying functions. On the right side are possible values returned by the querying functions.

---

Note: Although they are not shown here, DMparams-querying functions have corresponding setting functions. For example, dmParamsSetEnum() corresponds with dmParamsGetEnum(). However, some parameter values, such as those above, cannot be set by your application. See Chapter 3, “Digital Media Parameters,” for a discussion of using DMparams.

---

Your application should check the value of DM_IC_CODE_DIRECTION to determine if the codec is an encoder or decoder. The contents of DM_IC_ID and DM_IC_ENGINE may not have enough information to make this decision. If the value of DM_IC_SPEED is DM_IC_SPEED_REALTIME, the codec is suitable for real-time encoding or decoding. Usually, this indicates a hardware codec.

Use the function dmICChooseConverter() to choose a converter based on parameter values:

int dmICChooseConverter ( DMparams *srcParams, DMparams *dstParams,
                          DMparams *convParams )

The function returns the index of the converter that matches the requirements specified by the DMparams structures pointed to by srcParams, dstParams, and convParams. For dmICChooseConverter() to succeed, either the DM_IC_CODE_DIRECTION and DM_IC_ID parameters must be set in convParams, or the DM_IMAGE_COMPRESSION parameter must be set in srcParams and dstParams.

This function opens the converter that matches the specified parameters and values. If dmICChooseConverter() is successful, srcParams, dstParams, and convParams can be used as inputs to dmICSetSrcParams(), dmICSetDstParams(), and dmICSetConvParams() respectively. (See “2. Configuring a Converter Instance Using the Image Conversion API.”) The converter chosen is guaranteed to be optimal only for the given parameters. If the user changes any of the parameter values, your application may need to call dmICChooseConverter() again.

Use the function dmICCreate() to create an image converter instance:

DMstatus dmICCreate ( int i, DMimageconverter *converter )

This function opens the converter corresponding to i, an index returned by dmICChooseConverter(), and initializes converter (the address of a previously declared DMimageconverter variable) with the handle (the address of a pointer) of a converter instance. The handle is declared as follows:

typedef struct _DMimageconverter *DMimageconverter;

An application normally may open multiple converter instances based on one or more converters. However, some converters may limit the number of instances based on them. A converter is always used as part of a converter instance.

---

Tip: Because converters can be loaded dynamically, a converter's index can vary from system to system, or even from time to time on the same system. Before using an index, your application should use either dmICGetDescription() to check its validity, or dmICChooseConverter() to establish its value. Once determined, the value of the index will not change while an application is running.

---

The code that follows the comment “// 1. Creating a converter instance” in the section “Using the Image Conversion API” makes use of some of the above functions.

Once a converter instance has been created, it must be configured. The application does this by using DMparams data structures to specify a set of source parameters, a set of destination parameters, and, optionally, a set of conversion parameters. The source parameters describe the image data that is the converter instance's input. The input is uncompressed data if the converter is a compressor, otherwise it is in the format native to the converter. The destination parameters describe the converter instance's output. The output is in the format native to the converter if the converter is a compressor, otherwise it is uncompressed data. The conversion parameters fine tune settings that are specific to the converter.

The Image Conversion Library enables you to do the following:

In each of the nine functions described in this section, the first parameter, converter, is a DMimageconverter previously initialized by dmICCreate(). The second parameter is a pointer to a DMparams structure.

Use the functions dmICGetDefaultSrcParams(), dmICGetDefaultDstParams(), and dmICGetDefaultConvParams() to get the default parameter settings:

DMstatus dmICGetDefaultSrcParams ( DMimageconverter converter,
                                   DMparams *srcParams )

DMstatus dmICGetDefaultDstParams ( DMimageconverter converter,
                                   DMparams *dstParams )

DMstatus dmICGetDefaultConvParams ( DMimageconverter converter,
                                    DMparams *convParams )

After each of these functions returns, the DMparams structure contains the parameters, along with their default values, that your application can set for the converter instance indicated by converter using the setting functions described in this section. Although the conversion parameters, pointed to by convParams, vary markedly from converter to converter, those shown below are supported by many. The left side of the table lists each conversion parameter and its DMparams-querying function. Possible values for the parameter are listed on the right. For a more complete discussion of retrieving parameter values, see Chapter 3, “Digital Media Parameters.”

Use the functions dmICGetSrcParams(), dmICGetDstParams(), and dmICGetConvParams() to get the actual parameter settings:

DMstatus dmICGetSrcParams ( DMimageconverter converter,
                            DMparams *srcParams )

DMstatus dmICGetDstParams ( DMimageconverter converter,
                            DMparams *dstParams )

DMstatus dmICGetConvParams ( DMimageconverter converter,
                             DMparams *convParams )

After these functions return successfully, the DMparams structures contain the parameters and values that describe the input image, the output image, and the conversion settings for the data in the buffer obtained by the last successful call to dmICReceive(). The parameters are not defined prior to a successful call to dmICReceive(). See the section “4. Converting Data Using the Image Conversion API” for more information on dmICReceive().

Use the functions dmICSetSrcParams(), dmICSetDstParams(), and dmICSetConvParams() to change the parameter values:

DMstatus dmICSetSrcParams ( DMimageconverter converter,
                            DMparams *srcParams )

DMstatus dmICSetDstParams ( DMimageconverter converter,
                            DMparams *dstParams )

DMstatus dmICSetConvParams ( DMimageconverter converter,
                             DMparams *convParams )

The parameters and values to be used are specified in the DMparams structures pointed to by srcParams, dstParams, and convParams. The settings describe the input image, the output image, and the conversion settings for the data in the buffer that will be sent by the next dmICSend() operation. See the section “4. Converting Data Using the Image Conversion API” for more information on dmICSend().

The left side of the following table lists the image conversion parameters that must be specified in the source and destination DMparams structures. Also listed are the appropriate DMparams-setting functions. Possible values of the parameters are listed on the right. See dm_image.h for all the image parameters, and Chapter 3, “Digital Media Parameters” for a complete discussion of them.

The code that follows the comment “// 2. Configuring a converter instance” in the section “Using the Image Conversion API” makes use of some of the above functions.

The Image Conversion Library uses a buffering system to transmit data between your application and the converter instance. Typically, a data buffer contains a single video image, either compressed or uncompressed. You use the Image Conversion Library to create an source (input) buffer pool and an destination (output) buffer pool. Your application allocates individual buffers from the source buffer pool, and uses them to send data to the converter instance. The converter instance returns processed data to your application with buffers it creates from the destination buffer pool. The buffer pools, which are fixed in size, are created during an application's initialization. Before creating the buffer pools with dmBufferCreatePool(), your application must make sure they satisfy the requirements of all the libraries that are going to use them. This last point is explained more fully below with the functions dmICGetSrcPoolParams() and dmICGetDstPoolParams().

The Image Conversion Library allows you to determine the buffering requirements of a converter instance prior to creating a buffer pool. To find a converter instance's buffering needs, the Image Conversion Library enables you to do the following:

Use the functions dmICGetSrcPoolParams() and dmICGetDstPoolParams() to determine a converter instance's buffering needs:

DMstatus dmICGetSrcPoolParams ( DMimageconverter converter,
                                DMparams *poolParams )

DMstatus dmICGetDstPoolParams ( DMimageconverter converter,
                                DMparams *poolParams )

The converter instance indicated by converter modifies the DMparams structure pointed to by poolParams to describe its buffering needs. Your application should also pass this poolParams to other libraries that may share the same buffer pool. For example, if the buffer pool must be shared with the Video Library or the Graphics Library, poolParams should be passed to vlDMPoolGetParams() or dmBufferGetGLPoolParams(). This function returns an error if it detects that requirements set in poolParams by another library conflict with those of the converter instance.

Use dmICSetDstPool() to choose the buffer pool for a converter instance's output:

DMstatus dmICSetDstPool ( DMimageconverter converter,
                          DMbufferpool *pool )

The variable pool points to the destination buffer pool from which the converter instance, converter, allocates output buffers. Your application is responsible for creating and disposing of pool. The function returns an error if the converter instance does not meet the requirements of pool. This function must be called prior to dmICSend() or dmICReceive(), which are described in the next section.

The code that follows the comment “// 3. Creating data buffers for the converter instance” in the section “Using the Image Conversion API” makes use of some of the above functions.

During the actual conversion process, your application sends data buffers to a converter instance, and receives buffers of processed data from it. A converter instance has a source and destination queue to handle buffer traffic. Your application allocates, fills, and sends data buffers to the source queue. The instance attaches the buffers in the queue, that is prevents them from being deleted, until it can process the data. The destination queue, containing data buffers created by the instance from the destination buffer pool selected with dmICSetDstPool(), holds the processed data until your application is ready to receive it. The source and destination queues allow the converter instance to interact asynchronously with your application.

The Image Conversion Library enables your application to do the following:

Use the function dmICSend() to send data to a converter instance for conversion:

DMstatus dmICSend ( DMimageconverter converter, DMbuffer srcBuffer,
                    int numRefBuffers, DMbuffer *refBuffers )

This function adds the data buffer srcBuffer to the input queue of the converter instance converter. It is an asynchronous operation, and the conversion may not have taken place when dmICSend() returns. However, if it is no longer needed by your application, the buffer can be freed with dmBufferFree() immediately after dmICSend() returns. The buffer is attached by the converter instance until it can be used, and will not be deleted until the converter instance is finished with it. The integer numRefBuffers is the number of reference buffers in an array pointed to by refBuffers. The converter instance uses the reference buffers to interpret subsequent buffers which are coded in terms of them.

The dmICSend() function returns errors if the queue is full, or if any of the parameters are invalid. If the requirements of the source, destination, and conversion parameters set previously cannot be met during the instance's processing, an error is returned on a subsequent call to dmICReceive().

Use the function dmICReceive() to receive data from a converter instance:

DMstatus dmICReceive ( DMimageconverter converter,
                       DMbuffer *dstBuffer )

This function removes a completed data buffer, pointed to by dstBuffer, from the output queue of converter. The buffer is automatically attached to the caller. When your application no longer needs it, the buffer must be freed with dmBufferFree(). The function returns an error of DM_IC_Q_EMPTY if there are no buffers ready.

Use the function dmICGetDstQueueFD() to obtain a file descriptor associated with the data from a converter instance:

int dmICGetDstQueueFD ( DMimageconverter converter )

The function returns the file descriptor associated with the converter instance converter. Your application can use this file descriptor with select() or poll() to be notified when data is available to be retrieved with dmICReceive(). The code sample in “Using the Image Conversion API” shows an example of this technique.

Use dmICGetDstQueueFilled() to determine how many data buffers have been processed by a converter instance and are now available to your application. Use the function dmICGetSrcQueueFilled() to find how many data buffers have been sent to the converter instance, but not processed:

int dmICGetDstQueueFilled ( DMimageconverter converter )
int dmICGetSrcQueueFilled ( DMimageconverter converter )

The function dmICGetDstQueueFilled() returns an integer that is the number of buffers from converter that can be removed by dmICReceive(). The dmICGetSrcQueueFilled() function returns an integer that is the number of buffers that have been sent to converter with dmICSend() and have yet to be processed. Buffers that are being processed by the converter instance are not counted by either function.

The code following the comment “// 4. Converting the data using a converter instance” in the section “Using the Image Conversion API” uses some of the above functions.

The Image Conversion Library enables you to free a converter instance's resources with dmICDestroy():

void dmICDestroy ( DMimageconverter converter )

This function closes the converter instance indicated by converter. The converter instance's internal storage and other resources are freed and converter is no longer valid.

The code that follows the comment “// 5. Destroying a converter instance” in the next section uses this function.

What follows is a code sample that demonstrates the use of the Image Conversion API.

#include <stdio.h>
#include <unistd.h>
#include <dmedia/dmedia.h>
#include <dmedia/dm_image.h>
#include <dmedia/dm_buffer.h>
#include <dmedia/dm_imageconvert.h>

//
// main()
//
int main( int argc, char *argv[] )
{
    int               nNumConverters = 0;
    DMimageconverter  ImgCvt;
    DMparams          *pParams;
    DMbufferpool      InPool, OutPool;
    DMbuffer          InBuffer, OutBuffer;
    int               i;

// 1. Creating a converter instance

    // Get the number of converters
    nNumConverters = dmICGetNum();
    if (nNumConverters <= 0)  {
        fprintf( stderr, “ICGetNum() = (%d)\n”, nNumConverters );
        return( -1 );
    }

    // Open the first converter
    if (dmICCreate( 0, &ImgCvt ) != DM_SUCCESS)  {
        fprintf( stderr, “ICCreate() failed.\n” );
        return( -1 );
    }

    // Get description of first converter and print it 
    dmParamsCreate( &pParams );
    if (dmICGetDescription( 0, pParams ) != DM_SUCCESS)  {
        fprintf( stderr, “GetDescription() Failed\n” );
        return( -1 );
    }
    PrintDescription( pParams );
    dmParamsDestroy( pParams );

// 2. Configuring a converter instance

    // Set SrcParams and print
    dmParamsCreate( &pParams );
    dmSetImageDefaults( pParams, 320, 240, DM_IMAGE_PACKING_RGBX );
    if (dmICSetSrcParams( ImgCvt, pParams ) != DM_SUCCESS)  {
        fprintf( stderr, “SetSrcParams() Failed\n” );
        return( -1 );
    }
    if (dmICGetSrcParams( ImgCvt, pParams ) != DM_SUCCESS)  {
        fprintf( stderr, “GetSrcParams() Failed\n” );
    }
    PrintImageParams( pParams, “Src” );
    dmParamsDestroy( pParams );

    // Set DstParams and print
    dmParamsCreate( &pParams );
    dmSetImageDefaults( pParams, 160, 120, DM_IMAGE_PACKING_RGBX );
    if (dmICSetDstParams( ImgCvt, pParams ) != DM_SUCCESS)  {
        fprintf( stderr, “SetDstParams() Failed\n” );
        return( -1 );
    }
    if (dmICGetDstParams( ImgCvt, pParams ) != DM_SUCCESS)  {
        fprintf( stderr, “GetDstParams() Failed\n” );
    }
    PrintImageParams( pParams, “Dst” );
    dmParamsDestroy( pParams );

// 3. Creating data buffers for the converter instance

    // Create Pool
    dmParamsCreate( &pParams );
    dmBufferSetPoolDefaults( pParams, 5, 1024, DM_TRUE, DM_FALSE );
    if (dmBufferCreatePool( pParams, &InPool ) != DM_SUCCESS)  {
        fprintf( stderr, “Create Input Pool Failed\n” );
        return( -1 );
    }
    if (dmBufferCreatePool( pParams, &OutPool ) != DM_SUCCESS)  {
        fprintf( stderr, “Create Output Pool Failed\n” );
        return( -1 );
    }
    dmParamsDestroy( pParams );

    if (dmICSetDstPool( ImgCvt, OutPool ) != DM_SUCCESS)  {
        fprintf( stderr, “SetDstPool() Failed\n” );
        return( -1 );
    }

// 4. Converting data using the converter instance

    // We loop twice to test whether the codec does a coredump
    // when no src/dst/conv params are sent.
    // A real application would not have this arbitrary cut off.
    for ( i = 0 ; i < 2; ++i )  {
        dmBufferAllocate( InPool, &InBuffer );

        if (dmICSend( ImgCvt, InBuffer, 0, NULL ) != DM_SUCCESS)  {
            fprintf( stderr, “ICSend() Failed\n” );
            return( -1 );
        }

        if (dmBufferFree( InBuffer ) != DM_SUCCESS)  {
            fprintf( stderr, “dmBufferFree() Failed\n” );
            return( -1 );
        }

        {
            int     FD;
            fd_set  fdset;

            FD = dmICGetDstQueueFD( ImgCvt );
            FD_ZERO( &fdset );
            FD_SET( FD, &fdset );
            fprintf( stderr, “Waiting on FD %d\n”, FD );
            select( FD+1, &fdset, NULL, NULL, NULL );
        }
        if (dmICReceive( ImgCvt, &OutBuffer ) != DM_SUCCESS)  {
           fprintf( stderr, “ICReceive() Failed\n” );
           return( -1 );
        }
        // OutBuffer can now be sent anywhere a DMbuffer is accepted.
        // We just free it here.
        if (dmBufferFree( OutBuffer ) != DM_SUCCESS)  {
           fprintf( stderr, “dmBufferFree() Failed\n” );
           return( -1 );
        }
    }

// 5. Destroying a converter instance

    // Close converter
    dmICDestroy( ImgCvt );
    return( 0 );
}

//
// PrintDescription()
//   Prints the description obtained by dmICGetDescription().
//
void PrintDescription( DMparams *pParams )
{
    fprintf( stderr, “Name: %s\n”,
             dmParamsGetString( pParams, DM_IC_ENGINE ) );
    switch( dmParamsGetEnum( pParams, DM_IC_SPEED ) )  {
        case DM_IC_SPEED_UNDEFINED:
            fprintf( stderr, “Speed Undefined\n” );
            break;
        case DM_IC_SPEED_REALTIME:
            fprintf( stderr, “Speed Real Time\n” );
            break;
        case DM_IC_SPEED_NONREALTIME:
            fprintf( stderr, “Speed Not Real Time\n” );
            break;
        default:
            fprintf( stderr, “Speed Unknown\n” );
    }
    switch( dmParamsGetEnum( pParams, DM_IC_CODE_DIRECTION ) )  {
        case DM_IC_CODE_DIRECTION_UNDEFINED:
            fprintf( stderr, “Code Direction Undefined\n” );
            break;
        case DM_IC_CODE_DIRECTION_ENCODE:
            fprintf( stderr, “Code Direction Encode\n” );
            break;
        case DM_IC_CODE_DIRECTION_DECODE:
            fprintf( stderr, “Code Direction Decode\n” );
            break;
        default:
            fprintf( stderr, “Code Direction Unknown\n” );
    }
    fprintf( stderr, “Version: %d\n”,
             dmParamsGetInt( pParams, DM_IC_VERSION ) );
    fprintf( stderr, “Revision: %d\n”,
             dmParamsGetInt( pParams, DM_IC_REVISION ) );
}

//
// PrintImageParams()
//   Prints the descriptions obtained by dmICGetxxxParams().
//
void PrintImageParams( DMparams *pParams, const char *pOrigin )
{
    fprintf( stderr, “Width: %d   Height: %d\n”,
             dmParamsGetInt( pParams, DM_IMAGE_WIDTH ),
             dmParamsGetInt( pParams, DM_IMAGE_HEIGHT ) );
    switch( dmParamsGetEnum( pParams, DM_IMAGE_PACKING ) )  {
        case DM_IMAGE_PACKING_RGBX:
            fprintf( stderr, “RGBX Packing\n” );
            break;
        case DM_IMAGE_PACKING_XBGR:
            fprintf( stderr, “XBGR Packing\n” );
            break;
        case DM_IMAGE_PACKING_RGBA:
            fprintf( stderr, “RGBA Packing\n” );
            break;
        case DM_IMAGE_PACKING_ABGR:
            fprintf( stderr, “ABGR Packing\n” );
            break;
        default:
            fprintf( stderr, “Unknown Packing\n” );
    }
}

Use dmACCreate() to create an audio converter instance:

DMstatus dmACCreate ( DMaudioconverter* converter )

This function creates and initializes converter, a handle to a DMaudioconverter instance. All the Audio Conversion Library functions use this handle which is declared as follows:

typedef struct _DMaudioconverter *DMaudioconverter;

---

Note: All of the Audio Conversion Library functions return a DMstatus value of DM_SUCCESS if they succeed, DM_FAILURE if not. After a receiving a DM_FAILURE, your application can call the function the function dmGetErrorForPID() or dmGetError() to return an error message and error number. See “Digital Media Error Handling” in Chapter 3 for more information.

---

Once a converter instance has been created, it must be configured. As with the Image Conversion Library, your application does this by using DMparams data structures to specify a set of source parameters, a set of destination parameters, and, optionally, a set of conversion parameters.

The Audio Conversion Library enables you to do the following:

Use dmACSetParams() to set the DMaudioconverter parameter values:

DMstatus dmACSetParams ( DMaudioconverter converter,
                         DMparams *sourceparams, DMparams *destparams,
                         DMparams *conversionparams )

The handle converter indicates an audio converter instance created by a previous call to dmACCreate(). The DMparams structures pointed to by sourceparams and destparams describe the formats of the audio data prior to and after conversion. The variable conversionparams points to a DMparams structure that contains parameters specific to the conversion process. The variables destparams and conversionparams are optional and may be set to NULL.

Use dmACGetParams() to get the DMaudioconverter parameter values:

DMstatus dmACGetParams ( DMaudioconverter converter,
                         DMparams *sourceparams, DMparams *destparams,
                         DMparams *conversionparams )

The handle converter indicates an audio converter instance previously configured by a call to dmACSetParams(). The DMparams structures pointed to by sourceparams and destparams describe the formats of the audio data prior to and after conversion. The variable conversionparams points to a DMparams structure that contains parameters specific to the conversion process. The variables destparams and conversionparams are optional and may be set to NULL.

Use dmACReset() to reset a DMaudioconverter handle to its original configuration:

DMstatus dmACReset ( DMaudioconverter converter )

The handle converter indicates an audio converter instance already configured by a call to dmACSetParams().

The next three sections describe the DMparams structures for source, destination, and conversion parameters in more detail. They are followed by a section that discusses parameters relevant to specific converters.

Source Parameters

The source parameters, which describe the data to be converted, are contained in the DMparams structure indicated by sourceparams. The source parameters that must be specified are shown below. There are no default values. The parameters and their DMparams-setting functions follow the bullets. Legal values for the parameters follow the dashes.

Destination Parameters

The destination parameters, which describe the output audio data, are contained in the DMparams structure indicated by destparams. Any destination parameter not specified defaults to its source parameter value, except DM_AUDIO_COMPRESSION which defaults to DM_AUDIO_UNCOMPRESSED.

There is a set of four parameters for PCM mapping whose values, although they can be set for source data, are normally specified only for destination data. The parameters are based on a model where there is a PCM value that corresponds to zero voltage and a differential value that corresponds to full voltage. The set consists of the following parameters, which are shown with their DMparams setting functions and appropriate values.

The function dmACSetParams() automatically sets their default input and output values from the input and output data format specifications. Your application needs to set them only if it has special mapping requirements, such as input data with a fixed offset like a DC bias. If your application sets any of these four parameters, it must set all of them. See afIntro(3dm) for more information on PCM mapping.

Conversion Parameters

The conversion parameters, which modify the codec settings and other aspects of the conversion process, are contained in the DMparams structure indicated by conversionparams. There are five categories of conversion parameters.

Use dmACConvert() to convert the audio data's format, sampling rate, and compression:

DMstatus dmACConvert ( DMaudioconverter converter, void *inbuffer,
                       void *outbuffer, int *in_amount,
                       int *out_amount )

This function performs the data format, sampling rate, and compression or decompression specified by dmACSetParams(). The variable converter is a handle to an audio converter instance previously created with dmACCreate() and configured with dmACSetParams(). The variables inbuffer and outbuffer point to the buffers that contain the audio data prior to and after conversion. As described in “Configuring a Converter Instance Using the Audio Conversion API,” your application may need to determine the number of frames these buffers must hold using the DM_AUDIO_MIN_INPUT_LEN or DM_AUDIO_MIN_OUTPUT_LEN parameters. If inbuffer is NULL, the converter instance flushes any internal buffers to the output buffer.

The variable in_amount points to an integer containing the number of frames (bytes if the data is compressed) of input data available to the converter instance. This can be any value greater than 0. In pull mode, dmACConvert() resets this value to the number of frames (bytes) read from inbuffer by the converter instance. (To review the push and pull modes, see the conversion parameter discussion in “Configuring a Converter Instance Using the Audio Conversion API.”) The pointer out_amount indicates an integer containing the number of frames (bytes if the data is compressed) of converted data your application wants from the converter instance. The initial value is ignored in push mode. After processing the data, dmACConvert() resets the out_amount value to the number of frames (bytes) actually placed into outbuffer. If the conversion involved rate conversion, compression, or decompression, this value can vary significantly from the in_amount value. It can even be zero when the in_amount value was positive.

Compression Parameters

The compression parameters modify individual audio converters listed in Table 6-1. The parameters and their values are listed below. For more information about using specific parameters, please refer to the relevant reference pages.

The Audio Conversion library provides the function dmACDestroy() to destroy an audio converter instance:

DMstatus dmACDestroy ( DMaudioconverter converter )

The function frees the memory associated with the DMaudioconverter handle. The handle is not valid after this call returns.