Chapter 3. Digital Media Parameters
Prev |  | Next

## Chapter 3. Digital Media Parameters

This chapter explains how to use digital media data structures that facilitate data specification and setting, getting, and passing parameters.

## Digital Media Data Type Definitions

The DM Library provides type definitions for digital media that are useful when programming with the family of Digital Media Libraries. Data types and constant names have an uppercase DM prefix; routines have a lowercase dm prefix.

The `dmedia/dmedia.h` header file provides these type definitions:

DMboolean |  | integer for conditionals; DM_FALSE is 0 and DM_TRUE is 1
DMfraction |  | integer numerator divided by integer denominator
DMstatus |  | enumerated type consisting of DM_SUCCESS and DM_FAILURE

It is good programming practice to check the return values of functions. DMstatus provides a way to check return values. When a function succeeds, DM_SUCCESS is returned. When a function fails, DM_FAILURE is returned and a system error code is set that can be interpreted using the functions described in the next section.

### Digital Media Error Handling

Errors encountered while using the Digital Media Libraries can be diagnosed with the help of two routines. The function `dmGetError()` retrieves the number, summary, and detailed description of an error generated by the execution of the current process. The current process in this case is the same as determined by `getpid()`. The companion function, `dmGetErrorForPID()`, gets the same type of error information for a process your application specifies.

    const char *dmGetError ( int *errornum,
                             char error_detail[DM_MAX_ERROR_DETAIL] )
    const char *dmGetErrorForPID ( pid_t pid, int *errornum,
                                   char error_detail[DM_MAX_ERROR_DETAIL] )

The functions `dmGetError()` and `dmGetErrorForPID()` enable your application to handle in a consistent manner errors generated while using the digital media libraries. Both functions return a pointer to a null-terminated character string that summarizes the error. The setting of the errors by the libraries and the retrieval of them by your application is guaranteed to be thread-safe. Only the most recent error for a given thread is returned. If there are no errors, the functions return NULL.

The parameter pid in `dmGetErrorForPID()` is the id of the process in which to check for an error. The last parameter in both functions, error_detail, is the address of a null-terminated character array of size DM_MAX_ERROR_DETAIL. If one exists, a detailed description of the error is loaded into the array. If you set error_detail to NULL, no description is loaded. The remaining parameter, errornum, is a pointer to an integer into which the number of the current error is loaded. If your application sets errornum to NULL, no number is loaded. The error numbers returned in errornum fall into ranges according to the digital media libraries that generated them. The currently defined error ranges and their libraries are as follows:

0-999 | UNIX® System (The error numbers are identical to those returned by `oserror(3C)`.)
1000-1999 | Color Space Library in `libdmedia`
2000-2999 | Movie Library in `libmoviefile` or `libmovieplay`
3000-3999 | Audio File Library in `libaudiofile`
4000-4999 | DMbuffer in `libdmedia`
5000-5999 | Audio Converter in `libdmedia`
6000-6999 | Image Converter in `libdmedia`
10000-10999 | Global Digital Media Library in `libdmedia`
11000-11999 | FX Plug-in Utility Library in `libfxplugutils`
12000-12999 | FX Plug-in Manager Library in `libfxplugmgr`

## Digital Media Parameter Types

The DM Library provides definitions for the digital media parameter data types. Table 3-1 lists the digital media parameter type definitions that are defined in `dmedia/dm_params.h`.

Table 3-1. Digital Media Parameter Data Types

Parameter Type | Meaning
--- | ---
DM_TYPE_BINARY | Binary data
DM_TYPE_ENUM | Enumerated type
DM_TYPE_ENUM_ARRAY | Array of enumerated types
DM_TYPE_FLOAT | Floating point value (double)
DM_TYPE_FLOAT_ARRAY | Array of floats
DM_TYPE_FLOAT_RANGE | Range of floats
DM_TYPE_FRACTION | Ratio
DM_TYPE_FRACTION_ARRAY | Array of fractions
DM_TYPE_FRACTION_RANGE | Range of fractions
DM_TYPE_INT | Integer value
DM_TYPE_INT_ARRAY | Array of integers
DM_TYPE_INT_RANGE | Range of integers
DM_TYPE_LONG_LONG | Long long (64-bits)
DM_TYPE_PARAMS | DMparams list
DM_TYPE_STRING | String
DM_TYPE_STRING_ARRAY | Array of strings
DM_TYPE_TOC_ENTRY | Table-of-contents entry for ring buffers

## Digital Media Parameter Lists

Parameter-value lists, which are contained in a DMparams structure supply configuration information for digital media objects such as audio ports, movie tracks, and video devices. A DMparams list is a list of pairs, where each pair contains the name of a parameter and the corresponding value for that parameter.

You can use a DMparams list to

- configure a digital media structure upon initialization by passing a complete list containing all the parameters and values needed to configure that object to a creation routine

- change the settings of an existing digital media structure by providing a list of parameters and corresponding values to replace

Most Digital Media Libraries provide convenience routines for setting, adjusting, and getting relevant parameter values.

Every DMparams list that describes a format includes the parameter DM_MEDIUM to indicate what kind of data it describes. DM_MEDIUM is an enumerated type consisting of:

DM_IMAGE | which represents image data
DM_AUDIO | which represents audio data
DM_TIMECODE | which represents a timecode
DM_TEXT | which represents text

Another common parameter, DM_CODEC, is an enumerated type that describes whether a codec is synchronous (DM_SYNC_CODEC) or asynchronous (DM_ASYNC_CODEC). The compressor and decompressor of a synchronous codec are linked such that there must be both uncompressed input available to the compressor and compressed input available to the decompressor before either can generate output. An asynchronous codec has no such linkage.

This section explains how to use the DM Library routines for

- creating and destroying DMparams lists

- creating default audio and image configurations

- setting and getting values in DMparams lists

- manipulating DMparams lists

The routines described in this section follow the general rule that ownership of data is not passed during procedure calls, except in the routines that create and destroy DMparams lists. Functions that take strings copy the strings if they want to keep them. Functions that return strings or other structures retain ownership and the caller must not free them.

In the initialization section of your application, you create and use DMparams lists to configure data structures for your application as described in the following steps:

1. Create an empty DMparams list by calling dmParamsCreate().

2. Set the parameter values by one of the methods listed below:

   - Use a function that sets up a standard configuration for a particular type of data: dmSetImageDefaults() for images, dmSetAudioDefaults() for audio.

   - Use a generic function such as dmParamsSetInt() to set the values of individual parameters within an empty DMparams list or one that has already been initialized with the standard audio or image configuration. See “Setting and Getting Individual Parameter Values” for a description of this method.

   - Use a library function such as mvSetMovieDefaults() to set a group of parameters specific to that library.

3. Free the DMparams list and its contents by calling dmParamsDestroy().

These steps are described in detail in the sections that follow.

### Creating and Destroying DMparams Lists

Some libraries require you to allocate memory for DMparams lists, but with the DM library, you need not allocate memory for DMparams lists, because memory management is provided for you by the dmParamsCreate() and dmParamsDestroy() routines. These routines work together as a self-contained block within which you create the DMparams list, set the parameter value(s) and use them, and then destroy the structure, freeing its associated memory.

Only the dmParamsCreate() function can create a DMparams list, and only the dmParamsDestroy() function can free one. This means that DMparams lists are managed correctly when every call to create one is balanced by a call to destroy one. The creation function can fail because of lack of memory, so it returns an error code. The destructor can never fail.

To create an empty DMparams list, call dmParamsCreate(). Its function prototype is:

    DMstatus dmParamsCreate ( DMparams** returnNewList )

where:

returnNewList |  | is a pointer to a handle that is returned by the DM Library

If there is sufficient memory to allocate the structure, a pointer to the newly created structure is put into *returnNewList and DM_SUCCESS is returned; otherwise, DM_FAILURE is returned.

When you have finished using the DMparams list, you must destroy it to free the associated memory. To free both the DMparams list structure and its contents, call dmParamsDestroy(). Its function prototype is:

    void dmParamsDestroy ( DMparams* params )

where:

params |  | is a pointer to the DMparams list you want to destroy

Example 3-1 is a code fragment that creates a DMparams list called params, then calls a Movie Library routine, mvSetMovieDefaults(), to initialize the default movie parameters, and finally destroys the list, freeing both the structure and its contents.

Example 3-1. Creating and Destroying a DMparams List

    DMparams* params;
    if ( dmParamsCreate( &params ) != DM_SUCCESS ) {
        printf( "s\n", dmGetError(NULL, NULL) );
        exit( 1 );
    }
    if ( mvSetMovieDefaults(params, MV_FORMAT_SGI_3) != DM_SUCCESS ) {
        printf( “s\n”, mvGetErrorStr(mvGetErrno()));
        exit( 1 );
    }
    dmParamsDestroy ( params );

### Setting and Getting Individual Parameter Values

After creating an empty DMparams list or a default audio or image configuration, you can use the routines described in this section to set and get values for individual elements of a DMparams list.

There is a routine for setting and getting the parameter values for each parameter data type defined in the DM Library, as listed in Table 3-1.

All of these functions store and retrieve entries in a DMparams list. They assume that the named parameter is present and is of the specified type; the debugging version of the library asserts that this is the case. All functions that can possibly fail return an error code indicating success or failure. Insufficient memory is the only reason these routines can fail. Type mismatch causes a failed assertion in the debug library and undefined results in the non-debug library.

Table 3-2 lists the DM Library routines for setting parameter values. All the routines except `dmParamsSetBinary()` require three arguments:

params |  | a pointer to a DMparams list
paramName |  | the name of the parameter whose value you want to set
value |  | a value of the appropriate type for the given parameter Table 3-2. DM Library Routines for Setting Parameter Values
Routine | Purpose
--- | ---
`dmParamsSetBinary()` | Sets the contents of a data buffer. See ```dmParamsSetInt(3dm)`.
`dmParamsSetEnum()` | Sets the value of an enum parameter whose type is int.
`dmParamsSetEnumArray()` | Sets the value of a parameter whose type is DMenumarray.
`dmParamsSetFloat()` | Sets the value of a parameter whose type is double.
`dmParamsSetFloatArray()` | Sets the value of a parameter whose type is DMfloatarray.
`dmParamsSetFloatRange()` | Sets the value of a parameter whose type is DMfloatrange.
`dmParamsSetFract()` | Sets the value of a parameter whose type is DMfraction.
`dmParamsSetFractArray()` | Sets the value of a parameter whose type is DMfractionarray.
`dmParamsSetFractRange()` | Sets the value of a parameter whose type is DMfractionrange.
`dmParamsSetInt()` | Sets the value of a parameter whose type is int.
`dmParamsSetIntArray()` | Sets the value of a parameter whose type is DMintarray.
`dmParamsSetIntRange()` | Sets the value of a parameter whose type is DMintrange.
`dmParamsSetLongLong()` | Sets the value of a parameter whose type is long long.
`dmParamsSetParams()` | Sets the value of a parameter whose type is DMparam.
`dmParamsSetString()` | Sets the value of a parameter whose type is a character string.
`dmParamsSetStringArray()` | Sets the value of a parameter whose type is DMstringarray.

These routines return either DM_SUCCESS or DM_FAILURE.

Table 3-3 lists the DM Library routines for getting parameter values. All the routines except `dmParamsGetBinary()` require two arguments:

params |  | a pointer to a DMparams list
paramName |  | the name of the parameter whose value you want to get

Routines that get values return either a pointer to a value or the value itself. For strings, DMparams lists, and table-of-contents entries, the pointer that is returned points into the internal data structure of the DMparams list. This pointer should never be freed and is only guaranteed to remain valid until the next time the list is changed. In general, if you need to keep a string value around after getting it from a DMparams list, it should be copied.

Table 3-3. DM Library Routines for Getting Parameter Values

Routine | Purpose
--- | ---
`dmParamsGetBinary()` | Returns a pointer to binary data. See `dmParamsSetInt(3dm)`.
`dmParamsGetEnum()` | Returns an integer value for the given enum parameter.
`dmParamsGetEnumArray()` | Returns a pointer to a value of type DMenumarray.
`dmParamsGetFloat()` | Returns a value of type double for the given parameter.
`dmParamsGetFloatArray()` | Returns a pointer to a value of type DMfloatarray.
`dmParamsGetFloatRange()` | Returns a pointer to a value of type DMfloatrange.
`dmParamsGetFract()` | Returns a value of type DMfraction for the given parameter.
`dmParamsGetFractArray()` | Returns a pointer to a value of type DMfractionarray.
`dmParamsGetFractRange()` | Returns a pointer to a value of type DMfractionrange.
`dmParamsGetInt()` | Returns an integer value for the given parameter.
`dmParamsGetIntArray()` | Returns a pointer to a value of type DMintarray for the parameter.
`dmParamsGetIntRange()` | Returns a pointer to a value of type DMintrange for the parameter.
`dmParamsGetLongLong()` | Returns a 64-bit long for the given parameter.
`dmParamsGetParams()` | Returns a pointer to a value of type DMparams for the parameter.
`dmParamsGetString()` | Returns a pointer to a value of type const char for the parameter.
`dmParamsGetStringArray()` | Returns a pointer to a value of type DMstringarray.

### Setting Parameter Defaults

#### Setting Image Defaults

To initialize a DMparams list with the default image configuration, call dmSetImageDefaults(), passing in the width and height of the image frame, and the image packing format. Its function prototype is:

    DMstatus dmSetImageDefaults ( DMparams* params, int width,
                                  int height, DMpacking packing )

where:

params |  | is a pointer to a DMparams list that was returned by dmParamsCreate()
width |  | is the width of the image in pixels
height |  | is the height of the image in pixels
packing |  | is the image packing format

Table 3-4 lists the parameters and values set by dmSetImageDefaults().

Table 3-4. Image Defaults

Parameter | Default
--- | ---
DM_MEDIUM | DM_IMAGE
DM_IMAGE_WIDTH | width
DM_IMAGE_HEIGHT | height
DM_IMAGE_RATE | 15.0 frames per second (Hz)
DM_IMAGE_INTERLACING | DM_IMAGE_NONINTERLACED
DM_IMAGE_PACKING | packing
DM_IMAGE_ORIENTATION | DM_BOTTOM_TO_TOP
DM_IMAGE_COMPRESSION | DM_IMAGE_UNCOMPRESSED

#### Determining the Buffer Size Needed to Store an Image Frame

To determine the image frame size for a given DMparams list, call dmImageFrameSize(). dmImageFrameSize() returns the number of bytes needed to store one uncompressed image frame in the given format. Its function prototype is:

    size_t dmImageFrameSize ( const DMparams* params )

Example 3-2 is a code fragment that creates a DMparams list, fills in the image defaults, and then frees the structure and its contents.

Example 3-2. Setting Image Defaults

    DMparams* imageParams;

    if ( dmParamsCreate( &imageParams ) != DM_SUCCESS ) {
        printf( "s\n", dmGetError(NULL, NULL) );
        exit( 1 );
    }
    if ( dmSetImageDefaults( imageParams,
           320,  /* width */
           240,  /* height */
           DM_PACKING_RGBX ) != DM_SUCCESS ) {
        printf( "s\n", dmGetError(NULL, NULL) );
        exit( 1 );
    }
    printf( "%d bytes per image frame.\n",
            dmImageFrameSize( imageParams ) );
    dmParamsDestroy( imageParams );

#### Setting Audio Defaults

To initialize a DMparams list with the default audio configuration, call dmSetAudioDefaults(), passing in the desired sample width, sample rate, and number of channels. Its function prototype is:

    DMstatus dmSetAudioDefaults ( DMparams* params, int width,
                                  double rate, int channels )

where:

params |  | is a pointer to a DMparams list that was returned from dmParamsCreate()
width |  | is the number of bits per audio sample: 8, 16, or 24
rate |  | is the audio sample rate; the native audio sample rates are 8000, 11025, 16000, 22050, 32000, 44100, and 48000 Hz
channels |  | is the number of audio channels

dmSetAudioDefaults() returns DM_SUCCESS if there was enough memory available to set up the parameters; otherwise, it returns DM_FAILURE.

Table 3-5 lists the parameters and values set by dmSetAudioDefaults().

Table 3-5. Audio Defaults

Parameter | Default
--- | ---
DM_MEDIUM | DM_AUDIO
DM_AUDIO_WIDTH | width
DM_AUDIO_FORMAT | DM_AUDIO_TWOS_COMPLEMENT
DM_AUDIO_RATE | rate
DM_AUDIO_CHANNELS | channels
DM_AUDIO_COMPRESSION | DM_AUDIO_UNCOMPRESSED

#### Determining the Buffer Size Needed to Store an Audio Frame

To determine the audio frame size for a given DMparams list, call dmAudioFrameSize(). dmAudioFrameSize() returns the number of bytes needed to store one audio frame (one sample from each channel). Its function prototype is:

    size_t dmAudioFrameSize ( DMparams* params )

Example 3-3 is a code fragment that creates a DMparams list, fills in the audio defaults, and then frees the structure and its contents.

Example 3-3. Setting Audio Defaults

    DMparams* audioParams;
    if ( dmParamsCreate( &audioParams ) != DM_SUCCESS ) {
        printf( "s\n", dmGetError(NULL, NULL) );
        exit( 1 );
    }
    if ( dmSetAudioDefaults ( audioParams,
                              16,    /* width (in bits/sample) */
                              22050, /* sampling rate */
                              2      /* # channels (stereo) */
                              ) != DM_SUCCESS ) {
        printf( "s/n", dmGetError(NULL, NULL) );
        exit( 1 );
    }
    printf( "%d bytes per audio frame.\n",
             dmAudioFrameSize( audioParams ) );
    dmParamsDestroy( audioParams );

Example 3-4 shows two equivalent ways of setting up a complete image format description; the first sets the parameter values individually, the second creates a default image configuration with the appropriate values.

Example 3-4. Setting Individual Parameter Values

    DMparams* format;
    dmParamsCreate( &format );
    dmParamsSetInt ( format, DM_IMAGE_WIDTH, 320 );
    dmParamsSetInt ( format, DM_IMAGE_HEIGHT, 240 );
    dmParamsSetFloat ( format, DM_IMAGE_RATE, 15.0 );
    dmParamsSetString( format, DM_IMAGE_COMPRESSION, DM_IMAGE_UNCOMPRESSED );
    dmParamsSetEnum( format, DM_IMAGE_INTERLACING, DM_IMAGE_NONINTERLEAVED );
    dmParamsSetEnum ( format, DM_IMAGE_PACKING, DM_PACKING_RGBX );
    dmParamsSetEnum ( format, DM_IMAGE_ORIENTATION, DM_BOTTOM_TO_TOP );dmParamsDestroy ( format );

The following is equivalent:

    DMparams* format;
    dmParamsCreate ( &format );
    dmSetImageDefaults ( format, 320, 240, DM_PACKING_RGBX );
    dmParamsDestroy ( format );

### Manipulating DMparams Lists

This section explains how to manipulate DMparams lists. Some of the tasks you can two with DMparams lists include:

- testing two parameter values for equality

- copying either individual parameter-value pairs or entire DMparams lists

- determine how many parameter-value pairs are in a particular DMparams list

- getting information about parameter names, data types

Table 3-6 lists the routines that perform operations on DMparams lists and the entries within them.

Table 3-6. Routines for Manipulating DMparams Lists and Entries

Routine | Purpose
--- | ---
dmParamsAreEqual() | Determine if the values of two parameters are equal
dmParamsCopyAllElems() | Copy the entire contents of one list to another
dmParamsCopyElem() | Copy one parameter-value pair from one DMparams list to another
dmParamsGetElem() | Get the name of a given parameter
dmParamsGetElemType() | Get the data type of a given parameter
dmParamsGetNumElems() | Get the number of parameters in a list
dmParamsGetType() | Get the data type of the named parameter
dmParamsIsPresent() | Determine if a given parameter is in the list
dmParamsRemoveElem() | Remove a given parameter from the list
dmParamsScan() | Scan all the entries of a digital media parameter list

The sections that follow explain how to use each routine.

#### Determining DMparams Equivalence

The function `dmParamsAreEqual()` compares two DMparams structures and tests for equality. Its function prototype is:

    DMboolean dmParamsAreEqual ( const DMparams *params1,
                                 const DMparams *params2 )

If params1 and params2 have the same number of parameter-value pairs, and if the parameters of the same name have the same type and value in both lists, then the function returns DM_TRUE.

#### Determining the Number of Elements in a DMparams List

To perform any task that requires your application to loop through the contents of a DMparams list (for example, to print out a list of parameters and their values) you need to know how many parameters are in the list in order to set up a loop to step through the entries one-by-one.

To get the total number of elements present in a DMparams list, call dmParamsGetNumElems(). Its function prototype is:

    int dmParamsGetNumElems ( const DMparams* params )

The number of elements and their position in a list is guaranteed to remain stable unless the list is changed by using one of the “set” functions, by copying an element into it, or by removing an element from it.

There is also a convenience function, dmParamsScan(), for looping through the contents of a DMparams list and performing the same operation on each element of the list. See for more information on

#### Copying the Contents of One DMparams List into Another

To copy the entire contents of the fromParams list into the toParams list, call dmParamsCopyAllElems(). Its function prototype is:

    DMstatus dmParamsCopyAllElems ( const DMparams* fromParams,
                                    DMparams* toParams )

If there are any parameters of the same name in both lists, the corresponding value(s) in the destination list are overwritten. DM_SUCCESS is returned if there is enough memory to hold the copied data; otherwise, DM_FAILURE is returned. Type mismatch causes a failed assertion in the debug version of the library.

#### Copying an Individual Parameter Value from One List into Another

If a parameter appears in more than one DMparams list, it is sometimes more convenient to copy the individual parameter or group of parameters from one list to another, rather than individually setting the parameter value(s) for each list.

To copy the parameter-value pair for the parameter named paramName from the fromParams list into the toParams list, call dmParamsCopyElem(). Its function prototype is:

    DMstatus dmParamsCopyElem ( const DMparams* fromParams,
                                const char* paramName,
                                DMparams* toParams )

If there is a preexisting parameter with the same name in the destination list, that value is overwritten. DM_SUCCESS is returned if there is enough memory to hold the copied element; otherwise, DM_FAILURE is returned.

#### Determining the Name of a Given Parameter

To get the name of the entry occupying the position given by index in the params list, call dmParamsGetElem(). Its function prototype is:

    const char* dmParamsGetElem ( const DMparams* params, const int index )

The index must be from 0 to one less than the number of elements in the list.

#### Determining the Data Type of a Given Parameter

To get the data type of the value occupying the position given by index in the params list, call dmParamsGetElemType(). Its function prototype is:

    DMparamtype dmParamsGetElemType ( const DMparams* params,
                                      const int index )

Similarly, to get the data type of the parameter given by name in the params list, call dmParamsGetType(). Its function prototype is:

    DMparamtype dmParamsGetType ( const DMparams* params,
                                  const char* paramName )

See Table 3-1 for a list of valid return values.

#### Determining if a Given Parameter Exists

To determine whether the element named paramName exists in the params list, call dmParamsIsPresent(). Its function prototype is:

    DMboolean dmParamsIsPresent  ( const DMparams* params,
                                   const char* paramName )

DM_TRUE is returned if paramName is in params; otherwise, DM_FALSE is returned.

#### Scanning a DMparams List

Instead of creating your own loop to cycle through the contents of a DMparams list, you can use the convenience routine `dmParamsScan()`, which performs a specified operation on each element of the list. Its function prototype is:

    DMstatus dmParamsScan ( const DMparams* params,
                            DMstatus (*scanFunc) ( const DMparams* params,
                                                   const char* paramName,
                                                   void* scanArg,
                                                   DMboolean* stopScan ),
                            void* scanArg )

The function `dmParamsScan()` passes the name of each entry in a DMparams list and scanArg as parameters to scanFunc. If scanFunc sets the value of stopScan to DM_TRUE, `dmParamsScan()` stops the DMparams list scan and returns the value returned by scanFunc. Otherwise, `dmParamsScan()` processes all elements in the list and returns DM_SUCCESS.

#### Removing an Element from a DMparams List

To remove the paramName entry from the params list, call dmParamsRemoveElem(). Its function prototype is:

    const char* dmParamsRemoveElem ( DMparams* params,
                                     const char* paramName)

The element named paramName must be present.

Example 3-5 prints the contents of a DMparams list.

Example 3-5. Printing the Contents of a Digital Media DMparams List

    void PrintParams( DMparams* params ) {
        int i;
        int numElems = dmParamsGetNumElems( params );

       for ( i = 0;  i < numElems;  i++ ) {
            const char* name = dmParamsGetElem( params, i );
            DMparamtype type = dmParamsGetElemType( params, i );
            printf( "    %20s: ", name );
            switch( type ) {
                case DM_TYPE_ENUM:
                    printf( "%d", dmParamsGetEnum( params, name ) );
                    break;
                case DM_TYPE_INT:
                    printf( "%d", dmParamsGetInt( params, name ) );
                    break;
                case DM_TYPE_STRING:
                    printf( "%s", dmParamsGetString( params, name ) );
                    break;
                case DM_TYPE_FLOAT:
                    printf( "%f", dmParamsGetFloat( params, name ) );
                    break;
                case DM_TYPE_FRACTION:
                    DMfraction f = dmParamsGetFract( params, name );
                    printf( "%d/%d", f.numerator, f.denominator );
                    break;
                case DM_TYPE_PARAMS:
                    printf( "... param list ... " );
                    break;
                case DM_TYPE_TOC_ENTRY:
                    printf( "... toc entry ..." );
                    break;
                default:
                    assert( DM_FALSE );
                }
            printf( "\n" );
        }
    }

### Compiling and Linking a Digital Media Library Application

Applications that call DM Library routines must include the `libdmedia` header files to obtain definitions for the library; however, these files are usually included in the header file of the library you are using.

This code fragment includes all the `libdmedia` header files:

    #include <dmedia/dmedia.h>
    #include <dmedia/dm_audio.h>
    #include <dmedia/dm_image.h>
    #include <dmedia/dm_params.h>
    #include <dmedia/dm_buffer.h>
    #include <dmedia/dm_imageconvert.h>
    #include <dmedia/dm_audioconvert.h>

Link with the DM Library when compiling an application that makes DM Library calls by including -ldmedia on the link line. It's likely that you'll be linking with other libraries as well, and because the linking order is usually specific, follow the linking instructions for the library you are using.

### Debugging a Digital Media Library Application

The debugging version of the DM Library checks for library usage violations by setting assertions that state the requirements for a parameter or value.

To debug your DM application, link with the debugging version of the DM Library, `libdmedia.so.1`, by setting your LD_LIBRARY_PATH environment variable to the directory containing the debug library before linking with -ldmedia, and then run your program. For example, use `setenv LD_LIBRARY_PATH /usr/lib/debug` to set the path.

Your application will abort with an error message if it fails an assertion. The message explains the situation that caused the error and, by implication or by explicit description, suggests a corrective action.

When you have finished debugging your application, you should relink with the nondebugging library, `libdmedia.a`, because the runtime checks imposed by the debugging library cause an undesirable size and performance overhead for a packaged application.

Prev | Table of Contents | Next
Chapter 2. Digital Media Essentials |  | Chapter 4. Digital Media I/O