The DM Library provides type definitions for digital media. 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:

Table 2-1 lists the digital media parameter type definitions that are defined in dmedia/dm_params.h.

Parameter-value lists are used to store configuration information for movies, movie tracks, ring buffers, and video paths. A parameter-value list is a list of pairs, where each pair contains the name of a parameter and the corresponding value for that parameter.

Typical ways in which you might use a parameter-value list include:

Every parameter-value 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 and DM_AUDIO.

The routines described in this chapter follow the general rule that ownership of data is not passed during procedure calls, except in the routines that create and destroy parameter-value 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.

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>

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.

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_d.so, by using -ldmedia_d instead of -ldmedia, and then run your program. 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.

Some libraries require you to allocate memory for parameter-value lists, but with the DM library, you need not allocate memory for parameter-value 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 parameter-value list, set the parameter value(s) and use them, and then destroy the structure, freeing its associated memory.

dmParamsCreate() is the only function that can create a parameter-value list, and dmParamsDestroy() is the only function that can free one. This means that parameter-value 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 parameter-value list, call dmParamsCreate(). Its function prototype is:

DMstatus dmParamsCreate ( DMparams** returnNewList )

where:

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 parameter-value list, you must destroy it to free the associated memory. To free both the parameter-value list structure and its contents, call dmParamsDestroy(). Its function prototype is:

void dmParamsDestroy ( DMparams* params )

where:

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

DMparams* params;
if ( dmParamsCreate( &params ) != DM_SUCCESS ) {
    printf( "Out of memory.\n" );
    exit( 1 );
}
if ( mvSetMovieDefaults(params, MV_FORMAT_SGI_3) != DM_SUCCESS ) {
    printf( "Out of memory.\n" );
    exit( 1 );
}
dmParamsDestroy ( params );

There are standard parameters that apply to images (for video and movies) and standard parameters that apply to audio (for movies). This section explains how to use the DM Library convenience routines that initialize parameter-value lists for standard audio and image configurations.

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

size_t dmAudioFrameSize ( DMparams* params )

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

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

size_t dmImageFrameSize ( DMparams* params )

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

After creating an empty parameter-value 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 parameter-value 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 2-1.

All of these functions store and retrieve entries in parameter-value lists. 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.

Table 2-6 lists the DM Library routines for setting parameter values. These routines require three arguments:

These routines return either DM_SUCCESS or DM_FAILURE.

Table 2-7 lists the DM Library routines for setting parameter values. These routines require two arguments:

Routines that get values return either a pointer to a value or the value itself. For strings, parameter-value lists, and table-of-contents entries, the pointer that is returned points into the internal data structure of the parameter-value 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 parameter-value list, it should be copied.

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

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

This section explains how to manipulate parameter-value lists.

Table 2-8 lists the routines that perform operations on parameter-value lists and the entries within them.

The sections that follow explain how to use each routine.

int dmParamsGetNumElems ( DMparams* params )

DMstatus dmParamsCopyAllElems ( DMparams* fromParams,
                                DMparams* toParams )

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

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

DMparamtype dmParamsGetElemType ( DMparams* params, int index )

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

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

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