Chapter 6. Digital Media Data Conversion
Prev |  | Next

## Chapter 6. Digital Media Data Conversion

The file input/output routines of Digital Media Libraries, such as the Audio File Library and the Movie Library, use digital media converters to provide automatic data format conversion. This chapter describes how to use the digital media conversion libraries to create and use these converters in your application.

## About Digital Media Data Conversion

Digital media data conversion includes compression and decompression based on industry standards, such as JPEG and MPEG-1. It also encompasses transforming image color spaces, changing audio sample rates, and other basic data modifications. There are two generalized conversion libraries to effect digital media data conversions: the Image Conversion Library for video data, and the Audio Conversion Library for audio data. Applications can access these libraries to convert streams of digital media data. (Because they incur some overhead, the conversion libraries usually are not used for small amounts of data such as single still images.)

The conversion library APIs provide an interface to codecs (compressor-decompressors) such as JPEG or MPEG-1, to the Color Space Library and to other transformation libraries. The codecs and transformation libraries do the actual data conversions. Codecs may be either software modules or hardware devices with software interfaces. The hardware codecs are faster, but the software codecs may offer more options. If your application chooses a software codec in lieu of a hardware one, you may want to have your application notify the user of this fact. For more information about specific codecs see Chapter 2, “Digital Media Essentials.”

The digital media conversion libraries offer a number of benefits:

- They permit memory-to-memory data format conversions. These are more flexible than conversions between memory and I/O devices because the converted data is retained in memory for reuse.

- They integrate the use of software codecs, hardware codecs, and transformation libraries.

- They enable applications to perform conversions by merely specifying three sets of parameters:

  - one that describes the source data format

  - one that describes the destination data format

  - one that gives codec-specific settings

- They enable an application to use a number of codecs simultaneously.

- They have a modular design that allows codecs to be loaded dynamically as the application needs them.

- They allow applications to obtain a codec's parameters and default values, and to change these values appropriately.

## Using Digital Media Converters

A digital media converter is the encoder (compressor) or decoder (decompressor) of a codec. Converters are grouped by the conversion library that uses them. As you might expect, the Image Conversion Library uses the converters for image data, while the Audio Conversion Library uses the converters for audio data. Despite these groupings, converters are used in similar ways.

An application creates a converter instance by using the API of either of the conversion libraries. A converter instance includes a converter, any necessary transformation libraries, an input and an output buffer, and state information in the form of parameters that describe the input data, output data, and conversion process. A number of converter instances can use the same converter simultaneously. A converter instance that includes an encoder takes uncompressed data, applies the transformation libraries needed to make the data usable to the encoder, and then uses the encoder to produce the converted data. A converter instance with a decoder reverses this process.

A converter instance can be viewed as a pipeline. On one end of the pipeline is uncompressed data in a specified format. On the other end is data in the format native to the converter. The uncompressed data is the pipeline's input if the converter is a encoder, otherwise it is the output. The pipeline processing is done by the transformation libraries and the converter. When multiple transformation libraries are needed, the conversion libraries make sure that they are used in an order that best maintains the quality of the data.

Figure 6-1. Conversion Pipeline

To perform a data conversion your application follows these five steps:

1. Create a converter instance.

2. Configure the converter instance.

3. Create data buffers for the converter instance (image conversion only).

4. Convert the data using the converter instance.

5. Destroy the converter instance.

To use the digital media conversion libraries to create a converter instance, you must link your application with `libdmedia.so`.

## Image Data Conversion

This section describes the Digital Media Image Conversion Library and its converters. What follows is a discussion of how to use the Image Conversion API to execute the five steps of an image data conversion.

### Digital Media Image Conversion Library

The API of the Digital Media Image Conversion Library provides an interface for memory-to-memory image conversion that is independent of the algorithm. The Image Conversion Library, see also `dmic(4)`, lets you create an image converter instance based on a codec's encoder or decoder. Table 6-1 lists commonly installed codecs that can be accessed through the Image Conversion API. As shown in the table, these codecs usually have both types of converters, and may be performed by hardware on properly equipped systems. The columns DM_IC_ENGINE Value and DM_IC_ID Value contain identification values that are used with `dmICGetDescription()` as described in the section “1. Creating a Converter Instance Using the Image Conversion API.”

Table 6-1. Digital Media Image Converters

Codec Name | DM_IC_ENGINE Values | DM_IC_ID Value
--- | --- | ---
Apple QuickTime Animation | “The Apple Animation compressor” “The Apple Animation decompressor” | `rle `
Cinepak | ”The Cinepak compressor” “The Cinepak decompressor” | `cvid'
Intel Indeo | “The Indeo Video compressor” “The Indeo Video decompressor” | `IV32'
H.261 | “The H261 software encoder” “The H261 software decoder” | `h261'
JPEG | “Software JPEG Encoder” “Software JPEG Decoder” “Vice” | `jpeg'
MPEG-1 Video | “Vice” | `mpeg'
Motion Video Compressor 1 | “The MVC1 compressor” ”The MVC1 decompressor” | `mvc1'
Motion Video Compressor 2 | ”The MVC2 compressor” ”The MVC2 decompressor” | `mvc2'
8-bit Run Length Encode | “The RLE compressor” “The RLE decompressor” | `rle1'
24-bit Run Length Encode | “The RLE24 compressor” “The RLE24 decompressor” | `rle2'
Apple QuickTime Video | ”The Apple Video compressor” ”The Apple Video decompressor” | `rpza'

In addition to the operations done by the codecs, an image converter instance may also perform transformations involving

- color space

- size

- clipping

- orientation

- interlacing

- image rate

For some of these, the image converter instance calls the Color Space Library during the conversion process. This library is discussed in “The Digital Media Color Space Library.” Also shown is how the Image Conversion Library provides access to it independently of a converter instance.

As the next five sections demonstrate, The Image Conversion Library enables you to effectively use codecs and the Color Space Library by following the five steps listed in “Using Digital Media Converters.” To use the Image Conversion API, you must include these header files:

    #include <dmedia/dmedia.h>
    #include <dmedia/dm_imageconvert.h>

#### 1. Creating a Converter Instance Using the Image Conversion API

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:

- Get the number of image converters present in the system with `dmICGetNum()`

- Get the description of a specific converter with `dmICGetDescription()`

- Choose a converter based on your application's conversion needs with `dmICChooseConverter()`

- Create a converter instance with `dmICCreate()`

| 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.

DM_IC_ID and `dmParamsGetInt()` | The codec's DM_IC_ID value, as shown in Table 6-1
DM_IC_ENGINE and `dmParamsGetString()` | The codec's DM_IC_ENGINE value, as shown in Table 6-1
DM_IC_VERSION and `dmParamsGetInt()` | The codec's version number, for example 1.
DM_IC_REVISION and `dmParamsGetInt()` | The codec's revision number, for example 2.
DM_IC_CODE_DIRECTION and `dmParamsGetEnum()` | DM_IC_CODE_DIRECTION_UNDEFINED DM_IC_CODE_DIRECTION_ENCODE DM_IC_CODE_DIRECTION_DECODE
DM_IC_SPEED and `dmParamsGetEnum()` | DM_IC_SPEED_UNDEFINED DM_IC_SPEED_REALTIME DM_IC_SPEED_NONREALTIME

| 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.

#### 2. Configuring a Converter Instance Using the Image Conversion API

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:

- Get the source, destination, and conversion parameters, and their default settings, with `dmICGetDefaultSrcParams()`, `dmICGetDefaultDstParams()`, and `dmICGetDefaultConvParams()`

- Get the actual settings of the source, destination, and conversion parameters with `dmICGetSrcParams()`, `dmICGetDstParams()`, and `dmICGetConvParams()`

- Change the settings of the source, destination, and conversion parameters with `dmICSetSrcParams()`, `dmICSetDstParams()`, and `dmICSetConvParams()`

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.”

DM_IMAGE_BITRATE and `dmParamsGetInt()` | An integer value that indicates the rate, in bits per second, of a compressed video stream.
DM_IMAGE_QUALITY_SPATIAL and `dmParamsGetFloat()` | DM_IMAGE_QUALITY_NORMAL DM_IMAGE_QUALITY_LOSSLESS several others.
DM_IMAGE_QUALITY_TEMPORAL and `dmParamsGetFloat()` | DM_IMAGE_QUALITY_NORMAL DM_IMAGE_QUALITY_LOSSLESS several others.

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.

DM_IMAGE_WIDTH and `dmParamsSetInt()` | Image pixel width, e.g. 640.
DM_IMAGE_HEIGHT and `dmParamsSetInt()` | Image pixel height, e.g. 480.
DM_IMAGE_PACKING and `dmParamsSetEnum()` | DM_IMAGE_PACKING_RGBX many others.
DM_IMAGE_ORIENTATION and `dmParamsSetEnum()` | DM_IMAGE_TOP_TO_BOTTOM DM_IMAGE_BOTTOM_TO_TOP

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.

#### 3. Creating Data Buffers Using the Image Conversion API

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:

- Get the source and destination pool requirements with `dmICGetSrcPoolParams()` and `dmICGetDstPoolParams()`

- Select the buffer pool from which to receive data with `dmICSetDstPool()`

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.

#### 4. Converting Data Using the Image Conversion API

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:

- Send data to and receive it from a converter instance with `dmICSend()` and `dmICReceive()`

- Use a file descriptor to be notified of data arriving from a converter instance with `dmICGetDstQueueFD()`

- Determine the number of buffers that are ready to be received from the converter instance with `dmICGetDstQueueFilled()` and the number that are ready to be processed by the converter instance with `dmICGetSrcQueueFilled()`

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.

#### 5. Destroying a Converter Instance Using the Image Conversion API

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.

#### Using the Image Conversion API

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” );
        }
    }

### The Digital Media Color Space Library

The Digital Media Color Space Library is a lower level library that is called by the Image Conversion Library. It provides the support for many of the parameter keyword operations discussed in “2. Configuring a Converter Instance Using the Image Conversion API,”such as DM_IMAGE_WIDTH, DM_IMAGE_HEIGHT, DM_IMAGE_PACKING, DM_IMAGE_ORDER, DM_IMAGE_ORIENTATION, and DM_IMAGE_MIRROR. More explicitly, the Color Space Library enables your application to do the following

- Convert between these color spaces: RGB, YCrCb, and Y

- Convert between many packings, such as DM_IMAGE_PACKING_RGB, DM_IMAGE_PACKING_CbYCr, and DM_IMAGE_PACKING_LUMINANCE

- Convert between many data types, such as DM_IMAGE_DATATYPE_BIT, DM_IMAGE_DATATYPE_CHAR, and DM_IMAGE_DATATYPE_SHORT10L

- Provide gamma correction for the RGB components of source and destination data

- Adjust the hue, saturation, brightness, contrast, bias, and scale of individual components

- Enable colorimetry adjustments of specific monitors

Normally, your application does not need to call the Color Space Library directly. The Image Conversion Library calls it as determined by the values in the source, destination, and conversion parameters of your converter instance. However, to enable easy access to the Color Space Library for conversions involving only uncompressed data, the Image Conversion Library provides the convenience function `dmICAnyToAny()`.

Use `dmICAnyToAny()` to make color space conversions on uncompressed data:

     DMstatus dmICAnyToAny ( void *pBufferSrc, void *pBufferDst,
                            DMparams *pParamsSrc, DMparams *pParamsDst,
                            DMparams *pParamsConv )

The two variables pBufferSrc and pBufferDst, are pointers to the source and destination data which is uncompressed. Under some circumstances, pBufferSrc and pBufferDst, can be the same, allowing in-place data conversions. See `dmColor(3dm)` for more information. The variables pParamsSrc, pParamsDst, and pParamsConv, are pointers to DMparams structures which are set as shown in “Using the Image Conversion API.” For example, the next sample changes the packing of a 640-by-480 pixel image from CbYCrY to XBGR:

    /* Points to the source and destination buffers. */
    void        *pBufferSrc, *pBufferDst;

    /* Points to the source and destination parameters. */
    DMparams    *pParamsSrc, pParamsDst;

    /* Allocate buffers and fill source buffer. */
    ...
    /* Do other preliminary processing */
    ...

    /* Set the source parameters. */
    dmParamsCreate( &pParamsSrc );
    dmParamsSetInt( pParamsSrc,  DM_IMAGE_WIDTH, 640 );
    dmParamsSetInt( pParamsSrc,  DM_IMAGE_HEIGHT,480 );
    dmParamsSetEnum( pParamsSrc, DM_IMAGE_PACKING,
                                 DM_IMAGE_PACKING_CbYCrY);

    /* Set the destination parameters. */
    dmParamsCreate( &pParamsDst );
    dmParamsSetInt( pParamsDst,  DM_IMAGE_WIDTH, 640 );
    dmParamsSetInt( pParamsDst,  DM_IMAGE_HEIGHT,480 );
    dmParamsSetEnum( pParamsDst, DM_IMAGE_PACKING,
                                 DM_IMAGE_PACKING_XBGR);

    /* Do the conversion and clean up. */
    dmICAnyToAny( pBufferSrc, pBufferDst,
                  pParamsSrc, pParamsDst, NULL );
    dmParamsDestroy( pParamsSrc );
    dmParamsDestroy( pParamsDst );

For more information about the Color Space Library, see “The Color Space Library” in Appendix A.

### Summary of the Digital Media Image Conversion Library

These are the functions of the Digital Media Image Conversion Library API. More details about specific functions, such as the errors they return, can be found by looking at the reference pages mention in the “Description” column.

Table 6-2. The Digital Media Image Conversion Library API

Function | Description
--- | ---
int `dmICGetNum` ( void ) | Return the number of image converters available. See also `dmICGetNum(3dm)`.
int `dmICChooseConverter` ( DMparams *srcParams, DMparams *dstParams, DMparams *convParams ) | Return the index of an image converter that matches the specified image parameters. See also `dmICChooseConverter(3dm)`.
DMstatus `dmICGetDescription` ( int i, DMparams *converterParams ) | Get the description of the converter indicated by index i. See also `dmICGetDescription(3dm)`.
DMstatus `dmICCreate` ( int i, DMimageconverter *converter ) | Create an instance of image converter i. See also `dmICCreate(3dm)`.
void `dmICDestroy` ( DMimageconverter converter ) | Destroy the image converter instance. See also `dmICDestroy(3dm)`.
DMstatus `dmICGetSrcParams` ( DMimageconverter converter, DMparams *srcParams ) | Get the actual settings of source parameters of an image converter instance. See also `dmICGetSrcParams(3dm)`.
DMstatus `dmICSetSrcParams` ( DMimageconverter converter, DMparams *srcParams ) | Change the settings of source parameters of an image converter instance. See also `dmICSetSrcParams(3dm)`.
DMstatus `dmICGetDefaultSrcParams` ( DMimageconverter converter, DMparams *srcParams ) | Get the source parameters and default values of an image converter instance. See also `dmICGetDefaultSrcParams(3dm)`.
DMstatus `dmICGetDstParams` ( DMimageconverter converter, DMparams *dstParams ) | Get the actual settings of destination parameters of an image converter instance. See also `dmICGetDstParams(3dm)`.
DMstatus `dmICSetDstParams` ( DMimageconverter converter, DMparams *dstParams ) | Change the settings of destination parameters of an image converter instance. See also `dmICSetDstParams(3dm)`.
DMstatus `dmICGetDefaultDstParams` ( DMimageconverter converter, DMparams *dstParams ) | Get the destination parameters and default values of an image converter instance. See also `dmICGetDefaultDstParams(3dm)`.
DMstatus `dmICGetConvParams` ( DMimageconverter converter, DMparams *convParams ) | Get the actual settings of conversion parameters of an image converter instance. See also `dmICGetConvParams(3dm)`.
DMstatus `dmICSetConvParams` ( DMimageconverter converter, DMparams *convParams ) | Change the settings of conversion parameters of an image converter instance. See also `dmICSetConvParams(3dm)`.
DMstatus `dmICGetDefaultConvParams` ( DMimageconverter converter, DMparams *convParams ) | Get the conversion parameters and default values of an image converter instance. See also `dmICGetDefaultConvParams(3dm)`.
DMstatus `dmICGetSrcPoolParams` ( DMimageconverter converter, DMparams *poolParams ) | Get the input buffering needs of the image converter instance. See also `dmICGetSrcPoolParams(3dm)`.
DMstatus `dmICGetDstPoolParams` ( DMimageconverter converter, DMparams *poolParams ) | Get the output buffering needs of the image converter instance. See also `dmICGetDstPoolParams(3dm)`.
DMstatus `dmICSetDstPool` ( DMimageconverter converter, DMbufferpool pool ) | Set the pool from which converter allocates each output DMbuffer. See also `dmICSetDstPool(3dm)`.
int `dmICGetDstQueueFD` ( DMimageconverter converter ) | Get the queue file descriptor of the image converter instance. See also `dmICGetDstQueueFD(3dm)`.
int `dmICGetDstQueueFilled` ( DMimageconverter converter ) | Get the number of buffers ready to be received from the converter instance. See also `dmICGetDstQueueFilled(3dm)`.
int `dmICGetSrcQueueFilled` ( DMimageconverter converter ) | Get the number of buffers sent to the converter instance, but not yet processed. See also `dmICGetSrcQueueFilled(3dm)`.
int `dmICSend` ( DMimageconverter converter, DMbuffer srcBuffer, int numRefBuffers, DMbuffer *refBuffers ) | Transfer source buffer and reference buffers to the image converter instance. See also `dmICSend(3dm)`.
DMstatus `dmICReceive` ( DMimageconverter converter, DMbuffer *dstBuffer ) | Transfer data from the image converter instance. See also `dmICReceive(3dm)`.
DMstatus `dmICAnyToAny` ( void *src, void *dst, DMparams *srcParams, DMparams *dstParams, DMparams *convParams ) | A convenience function.

## Audio Data Conversion

This section describes the Digital Media Audio Conversion Library, its converters, and how to use the Audio Conversion API to execute the four steps of an audio data conversion.

### The Digital Media Audio Conversion Library

The Digital Media Audio Conversion Library provides data format conversion for applications that do real-time audio capture, playback and file conversion. It makes it possible to efficiently move data between any audio producer and any audio consumer, regardless of their native formats. The library provides a single API for performing memory-to-memory sound compression and conversion. Table 6-1 lists commonly installed codec options that can be accessed through the Audio Conversion API. The “DM_AUDIO_COMPRESSION Value” column contains the identification values that are used with `dmACSetParams()` as described in “Configuring a Converter Instance Using the Audio Conversion API.”

Table 6-3. Digital Media Audio Codecs

DM_AUDIO_COMPRESSION Value | Description
--- | ---
DM_AUDIO_DVI | Intel's Digital Video Interactive. See also “The DVI Audio Compression Library” in Appendix A.
DM_AUDIO_G711_ALAW DM_AUDIO_G711_ULAW | International Telecommunication Union Standard G.711. See “The G.711 Audio Compression Library” in Appendix A.
DM_AUDIO_G722 | International Telecommunication Union Standard G.722. See “The G.722 Audio Compression Library” in Appendix A.
DM_AUDIO_G726 | International Telecommunication Union Standard G.726. See “The G.726 Audio Compression Library” in Appendix A.
DM_AUDIO_G728 | International Telecommunication Union Standard G.728. See “The G.728 Audio Compression Library” in Appendix A.
DM_AUDIO_GSM | Global System for Mobile Telecommunications. See “The GSM Audio Compression Library” in Appendix A.
DM_AUDIO_MPEG1 | MPEG-1 Audio. See “The MPEG-1 Audio Compression Library” in Appendix A.
DM_AUDIO_MULTIRATE | Aware MultiRate near-lossless compression.

In addition to the compression and decompression done by the codecs, an audio converter instance may also perform such transformations as

- converting between different numerical representations, such as unsigned integer and two's complement signed integer

- converting between big-endian and little-endian byte orders

- audio sampling rate conversion (see “The Audio Rate Conversion Library” in Appendix A)

- converting between different numbers of interleaved channels, such as mono and stereo

- Pulse Code Modulation (PCM) mapping

As the next sections demonstrate, the Audio Conversion Library enables you to effectively use the codecs and transformation libraries by following the steps listed in “Using Digital Media Converters.” To use the Audio Conversion API, you must use these header files:

    #include <dmedia/dm_audioconvert.h>
    #include <dmedia/dm_audioutil.h>

#### Creating a Converter Instance Using the Audio Conversion API

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.

#### Configuring a Converter Instance Using the Audio Conversion API

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:

- Configure an audio converter instance by setting the source, destination, and conversion parameters with `dmACSetParams()`

- Get the source, destination, and conversion parameter settings of a configured audio converter instance with `dmACGetParams()`

- Reset an audio converter instance to its original configuration with `dmACReset()`

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.

- DM_AUDIO_FORMAT and dmParamsSetEnum():

  DM_AUDIO_TWOS_COMPLEMENT

  DM_AUDIO_UNSIGNED

  DM_AUDIO_FLOAT

  DM_AUDIO_DOUBLE

- DM_AUDIO_WIDTH and `dmParamsSetInt()`:

  The width of the data in bits. An integer value between 1 and 32.

- DM_AUDIO_BYTE_ORDER and `dmParamsSetEnum()`:

  DM_AUDIO_BIG_ENDIAN

  DM_AUDIO_LITTLE_ENDIAN

- DM_AUDIO_CHANNELS and `dmParamsSetInt()`:

  The number of audio channels. An integer value greater than 0.

- DM_AUDIO_RATE and `dmParamsSetFloat()`:

  The audio sampling rate in Hz. A DM_TYPE_FLOAT value greater than 0.0.

- DM_AUDIO_COMPRESSION and `dmParamsSetString()`:

  DM_AUDIO_UNCOMPRESSED or one of the values shown in Table 6-1.

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.

- DM_AUDIO_PCM_MAP_SLOPE and `dmParamsSetFloat()`:

  The full voltage PCM value. (Default is 32767.0)

- DM_AUDIO_PCM_MAP_INTERCEPT and `dmParamsSetFloat()`:

  The zero voltage PCM value. (Default is 0.0)

- DM_AUDIO_PCM_MAP_MAXCLIP and `dmParamsSetFloat()`:

  Clip all PCM values to this maximum value. (Default is 32767.0)

- DM_AUDIO_PCM_MAP_MINCLIP and `dmParamsSetFloat()`:

  Clip all PCM values to this minimum value. (Default is -32768.0)

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.

1. The Processing Mode Parameter

   This parameter, whose keyword is DM_AUDIO_PROCESS_MODE, is used to determine the converter's Processing mode. It can also be used to set the processing mode when both the input and output data are uncompressed. There are two processing modes: push and pull. In pull mode, your application requests a given number of output frames. Decompression must use pull mode and your application uses a buffer length parameter to specify how many frames of uncompressed data the converter instance should put in the output buffer of `dmACConvert()`. In push mode, your application gives the converter a specified number of input frames. Compression requires push mode and your application specifies how many frames of uncompressed data are in the input buffer. The two settings for DM_AUDIO_PROCESS_MODE are

   - DM_AUDIO_PROCESS_PULL and `dmParamsGetInt()`

   - DM_AUDIO_PROCESS_PUSH and `dmParamsGetInt()`

2. Buffer Length Parameters

   The three buffer length parameters are used to determine the number of frames in the input or output buffers. Your application specifies them only during compression, decompression, or rate conversion because the input and output buffer lengths are equal at all other times. Your application must set the parameter DM_AUDIO_MAX_REQUEST_LEN prior to calling `dmACConvert()` to specify the largest buffer the converter instance will have to process. Your application then calls `dmACGetParams()` to find the value of DM_AUDIO_MIN_INPUT_LEN or DM_AUDIO_MIN_OUTPUT_LEN. If the converter instance is in pull mode, DM_AUDIO_MIN_INPUT_LEN gives the minimum number of frames the converter instance requires in the input buffer. If the instance is in push mode, DM_AUDIO_MIN_OUTPUT_LEN gives the minimum number of frames the instance requires in the output buffer. Your application then allocates buffers appropriate to these sizes. The parameters, DMparams functions, and typical values are as follows:

   - DM_AUDIO_MAX_REQUEST_LEN and dmParamsSetInt():

     An integer value greater than 0. This value can only be set.

   - DM_AUDIO_MIN_INPUT_LEN and dmParamsGetInt():

     An integer value that your application can only read.

   - DM_AUDIO_MIN_OUTPUT_LEN and dmParamsGetInt():

     An integer value that your application can only read.

3. The Dithering Parameter

   The dithering parameter, whose keyword is DM_AUDIO_DITHER_ALGORITHM, is used only when data is converted from a larger to a smaller data type. An example of such a conversion would be going from a floating point to a 16-bit integer representation. The dithering algorithm is applied to reduce the quantization error distortion inherent in reducing resolution. The two possible values are as follows:

   - DM_AUDIO_DITHER_NONE (default)

   - DM_AUDIO_DITHER_LSB_TPDF (Least Significant Bit—Triangular Probability Density Function)

4. Rate Conversion Parameters

   There are three parameters that affect the rate conversion algorithm. They are used only when the input and output sampling rates are not equal. The three parameters, their DMparams setting functions, and their possible values are shown below. See `dmAudioRateConverterSetParams(3dm)` for more information about them.

   - DM_AUDIO_RC_ALGORITHM and dmParamsSetString():

     DM_AUDIO_RC_JITTER_FREE (default)

     DM_AUDIO_RC_POLYNOMIAL_ORDER_1

     DM_AUDIO_RC_POLYNOMIAL_ORDER_3

   - DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION and dmParamsSetFloat():

     DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_78_DB
     (default)

     DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_96_DB

     DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_120_DB

   - DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH and dmParamsSetFloat():

     DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_1_PERCENT

     DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_10_PERCENT

     DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_20_PERCENT

5. The Channel Conversion Parameter

   The channel conversion or channel matrix parameter is used to mix the channels associated with a track. The matrix is a one-dimensional array composed of a two-dimensional array in row-major order, where each row represents an output channel and each column represents an input channel. See the `afSetChannelMatrix(3dm)` reference page for a detailed explanation. The parameter keyword and its DMparams-setting function are as follows:

   - DM_AUDIO_CHANNEL_MATRIX and `dmParamsSetFloatArray()`:

     A DMfloatarray of double-precision floating point numbers.

#### Converting Data Using the Audio Conversion API

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.

- Digital Video Interactive (DVI) has one parameter.

  DM_DVI_AUDIO_BITS_PER_SAMPLE specifies the compression algorithm. Its possible values are

  - DM_DVI_AUDIO_3BITS_PER_SAMPLE

  - DM_DVI_AUDIO_4BITS_PER_SAMPLE (default)

- ITU-T G722 has three parameters.

  DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK

  DM_AUDIO_CODEC_FRAMES_PER_BLOCK

  DM_AUDIO_CODEC_FILTER_DELAY

- ITU-T G722 has two parameters.

  DM_AUDIO_BITRATE is an integer in units of bits per second with one of the following values: 16000, 24000, 32000, 40000.

  DM_G726_NATIVE_FORMAT specifies the input or output sample data format. Its possible values are

  - AUDIO_ENCODING_ULAW

  - AUDIO_ENCODING_ALAW

  - AUDIO_ENCODING_LINEAR

- ITU-T G728 has one parameter.

  DM_G728_POSTFILTERING_FLAG selects a decoder with or without post filtering. Its possible values are

  - DM_G728_POSTFILTERING_YES

  - DM_G728_POSTFILTERING_NO

- Global System for Mobile Telecommunications (GSM) has three parameters.

  DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK

  DM_AUDIO_CODEC_FRAMES_PER_BLOCK

  DM_AUDIO_CODEC_FILTER_DELAY

- MPEG-1 Audio has seven parameters for encoding and decoding.

  DM_AUDIO_RATE is the input or output sampling rate given in Hz. It is a double with possible values of 32000, 44100 (default), and 48000.

  DM_AUDIO_FORMAT is the format of each input or output sample. The only supported value is DM_AUDIO_TWOS_COMPLEMENT

  DM_AUDIO_WIDTH is the width of each input or output sample. The only supported value is DM_AUDIO_WIDTH_16

  DM_AUDIO_CHANNELS is the number of channels in the input or output data. It is an integer value of 1 or 2 (default).

  DM_MPEG1_AUDIO_LAYER is a flag specifying the basic algorithm to be used. There are two possible values.

  - DM_MPEG1_AUDIO_LAYER1

  - DM_MPEG1_AUDIO_LAYER2 (default)

  DM_AUDIO_CHANNEL_POLICY indicates how multiple channels should be treated. There are three possible values.

  - DM_AUDIO_STEREO—The channels are part of a single multichannel signal.

  - DM_AUDIO_JOINT_STEREO (default)—The algorithm may attempt to exploit redundancy between channels for greater coding gain.

  - DM_AUDIO_INDEPENDENT—The separate channels are unrelated and should be processed separately.

  DM_AUDIO_BIT_RATE specifies the desired bit rate, in bits per second, for the compressed data.

  Supported values with DM_MPEG1_AUDIO_LAYER1 are 32000, 64000, 96000, 128000, 160000, 192000, 224000, 256000 (default), 288000, 320000, 352000, 384000, 416000, and 448000. Supported values with DM_MPEG1_AUDIO_LAYER2 are 32000, 48000, 56000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000 (default), 320000, and 38400

- MPEG-1 Audio has four parameters to use with encoding only.

  DM_MPEG1_AUDIO_PSYCHOMODEL selects which psychoacoustic model to use for calculating the safe masking thresholds for quantizing noise. There are two possible values.

  - DM_MPEG1_AUDIO_PSYCHOMODEL1

  - DM_MPEG1_AUDIO_PSYCHOMODEL2

  DM_MPEG1_AUDIO_PSYCHOMODEL1_ALPHA is a float value that specifies the alpha parameter for DM_MPEG1_AUDIO_PSYCHOMODEL1. It has a possible value within (0.0, 2.0]. Default is 2.0.

  DM_MPEG1_AUDIO_BITRATE_POLICY is a flag used for the interpretation of DM_AUDIO_BIT_RATE. There are two possible values.

  - DM_MPEG1_AUDIO_FIXRATE (default)

  - DM_MPEG1_AUDIO_CONSTANT_QUALITY

  DM_MPEG1_AUDIO_CONST_QUAL_NMR is the desired mask-to-noise ratio in decibels. It is a float value with a value within (-13.0, 13.0]. The default is 0.0.

- MPEG-1 Audio has three parameters to use with decoding only.

  DM_MPEG1_AUDIO_DECIMATION_SCALE specifies the decimation factor applied to reduce the complexity of decoding. It has three possible values.

  - DM_MPEG1_AUDIO_BANDWIDTH_FULL (default)

  - DM_MPEG1_AUDIO_BANDWIDTH_HALF

  - DM_MPEG1_AUDIO_BANDWIDTH_QUARTER

  DM_MPEG1_AUDIO_SCALE_FILTERSHAPE specifies the filter shape applied to reduce the complexity of decoding. It has three possible values.

  - DM_MPEG1_AUDIO_DEFAULT_FILTER (default)

  - DM_MPEG1_AUDIO_FILTER_SHAPE1

  - DM_MPEG1_AUDIO_FILTER_SHAPE2

  DM_MPEG1_AUDIO_COMBINE_CHANS_FLAG enables single channel output. It is an integer with a default value of 0, that is JOINT_STEREO mode. A value of 1 forces the decoder to produce single channel output.

- MPEG-1 Audio has three parameters to use only in query mode.

  DM_AUDIO_CODEC_FRAMES_PER_BLOCK is an integer that specifies how many sample frames are put into each compressed data block.

  DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK is an integer that indicates the maximum number of bytes that will compose a compressed data block.

  DM_AUDIO_CODEC_FILTER_DELAY is an integer that indicates the delay, in sample frames, introduced by compression and decompression processing.

#### Destroying a Converter Instance Using the Audio Conversion API

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.

### Summary of the Digital Media Audio Conversion Library

These are the functions of the Digital Media Audio Conversion Library API. More details about specific functions, such as the errors they return, can be found by looking at the reference pages mention in the “Description” column.

Table 6-4. The Digital Media Audio Conversion API

Function | Description
--- | ---
DMstatus `dmACConvert` ( DMaudioconverter converter, void *inbuffer, void *outbuffer, int *in_amount, int *out_amount ) | Convert the audio data format, sampling rate, and compression. See also `dmACConvert(3dm)`.
DMstatus `dmACCreate` ( DMaudioconverter *converter ) | Create a DMaudioconverter handle to use for audio format conversion. See also `dmACCreate(3dm)`.
DMstatus `dmACDestroy` ( DMaudioconverter converter ) | Destroy a DMaudioconverter handle used for audio format conversion. See also `dmACDestroy(3dm)`.
DMstatus `dmACReset` ( DMaudioconverter converter ) | Reset a DMaudioconverter handle to its default state. See also `dmACReset(3dm)`.
DMstatus `dmACSetParams` ( DMaudioconverter converter, DMparams *sourceparams, DMparams *destparams, DMparams *conversionparams ) | Set the DMaudioconverter parameter values. See also `dmACSetParams(3dm)`.
DMstatus `dmACGetParams` ( DMaudioconverter converter, DMparams *sourceparams, DMparams *destparams, DMparams *conversionparams ) | Get the DMaudioconverter parameter values. See also `dmACGetParams(3dm)`.

Prev | Table of Contents | Next
Chapter 5. Digital Media Buffers |  | Chapter 7. Digital Media Audio File Operations