Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide
Previous Contents Index

3.4.9 Stopping Waveform Audio Recording

Use the waveInReset function to stop waveform audio recording and mark all pending buffers as done. Before closing the device using the waveInClose function, call the waveInReset function to mark any pending data blocks as done.

Use the waveInStop function to stop waveform audio recording.

See the descriptions of the waveInReset and waveInStop functions in Section 3.8 for more information about stopping waveform audio recording.

3.4.10 Closing a Waveform Audio Input Device

After waveform audio recording is complete, call the waveInClose function to close a waveform audio input device. If the waveInClose function is called before recording is completed (that is, before all buffers have been returned to the application), the close operation fails and an error code indicating that there are still buffers in the queue is returned.

To close a waveform audio input device before recording is complete, call the waveInReset function. The waveInReset function terminates audio recording by marking all pending buffers as done and returning them to the calling application. Then, call the waveInClose function to close the device.

3.5 Waveform Audio Header Files

The function prototypes, constants, flags, and data structures that applications can use to access the waveform audio services are defined in the mme_api.h header file provided with Multimedia Services for OpenVMS. Include this header file in all application programs that use waveform audio functions.

3.6 Waveform Audio Data Structures

This section contains the data structures used by the waveform audio functions. The data structures are presented in alphabetical order. Each structure is defined, followed by a description of each field.

Note
All audio data structures must be allocated with the mmeAllocMem function. All audio data buffers must be allocated with the mmeAllocBuffer or the mmeAllocBufferAndGetShminfo function. See Chapter 2 for more information about the memory allocation functions.

3.6.1 PCMWAVEFORMAT Data Structure

For PCM waveform data, the PCMWAVEFORMAT data structure includes a WAVEFORMAT data structure (described in Section 3.6.2) and a field containing information specific to the PCM waveform data format.

Example 3-6 shows the PCMWAVEFORMAT data structure definition.

Example 3-6 PCMWAVEFORMAT Data Structure Definition 

typedef struct pcmwaveformat_tag { 
    WAVEFORMAT  wf;                 /* general format information */ 
    UINT        wBitsPerSample;     /* number of bits per sample */ 
} PCMWAVEFORMAT;

The PCMWAVEFORMAT data structure has the following fields:

wf
Specifies general format information.

wBitsPerSample
Specifies the number of bits per sample for each channel of PCM data. For example, specify the value 16 for both 16-bit stereo and 16-bit mono.

3.6.2 WAVEFORMAT Data Structure

The WAVEFORMAT data structure specifies format information common to all types of waveform data formats. Currently, the only formats supported are pulse code modulation (PCM) and MULAW.

Example 3-7 shows the WAVEFORMAT data structure definition.

Example 3-7 WAVEFORMAT Data Structure Definition 

typedef struct waveformat_tag { 
    WORD    wFormatTag;          /* format type */ 
    WORD    nChannels;;          /* number of channels */ 
    DWORD   nSamplesPerSec;   /* number of samples per second */ 
    DWORD   nAvgBytesPerSec;     /* average data rate */ 
    WORD    nBlockAlign;         /* block alignment */ 
} WAVEFORMAT;

The WAVEFORMAT data structure has the following fields:

wFormatTag
Specifies the format type for the data. Currently, the only values defined for this field are WAVE_FORMAT_PCM for PCM waveform data and WAVE_FORMAT_MULAW for MULAW data.

nChannels
Specifies the number of discrete channels in the format. Use a value of 1 for mono data and 2 for stereo data.

nSamplesPerSec
Specifies the sample rate.

nAvgBytesPerSec
Specifies the average data rate in bytes per second. For example, 16-bit stereo at 44.1 kHz has an average data rate of 176400 bytes per second (2 channels M-4, 2 bytes per sample per channel M-4, 44,100 samples per second).

nBlockAlign
Specifies the minimum atomic unit of data that can be passed to a driver. For PCM or MULAW data, the block alignment is the number of bytes used by a single sample, including data for both channels if the data is stereo. For example, the block alignment for 16-bit stereo PCM is 4 bytes (2 channels M-4, 2 bytes per sample).

In addition to the general information in the WAVEFORMAT data structure, specific information is needed to describe a PCM waveform data format completely. No additional information is needed to describe MULAW data. The PCMWAVEFORMAT data structure, described in Section 3.6.1, contains this information.

3.6.3 WAVEFORMATINFO Data Structure

The WAVEFORMATINFO data structure specifies format information common to all types of waveform data formats.

Example 3-8 shows the WAVEFORMATINFO data structure definition.

Example 3-8 WAVEFORMATINFO Data Structure Definition 

typedef struct waveformatinfo_tag { 
    DWORD   cbStruct;                /* size of this structure */ 
    DWORD   dwNumFormatsSupported;   /* number of formats supported */ 
    DWORD   dwMaxWaveformatexSize;   /* max size of waveformatex for all */ 
                                     /*   supported formats */ 
    DWORD   dwMaxDescriptionSize;    /* max size of the ASCII description */ 
                                     /*   for all supported formats */ 
} WAVEFORMATINFO, *LPWAVEFORMATINFO;

The WAVEFORMATINFO data structure has the following fields:

cbStruct
Specifies the size of the data structure.

dwNumFormatsSupported
Specifies the number of formats supported.

dwMaxWaveformatexSize
Specifies the maximum size of the WAVEFORMATEX data structure for all supported formats.

dwMaxDescriptionSize
Specifies the maximum size of the ASCII description for all supported formats.

3.6.4 WAVEHDR Data Structure

The WAVEHDR data structure is used by the waveInAddBuffer and waveOutWrite functions to describe the data blocks used by these functions to pass audio data to a device driver.

Example 3-9 shows the WAVEHDR data structure definition.

Example 3-9 WAVEHDR Data Structure Definition 

typedef struct wavehdr_tag { 
    LPSTR              lpData;          /* pointer to data block */ 
    DWORD              dwBufferLength;  /* length of data block */ 
    DWORD              dwBytesRecorded; /* number of bytes recorded */ 
    DWORD              dwUser;          /* user instance data */ 
    DWORD              dwFlags;         /* assorted flags */ 
    DWORD              dwLoops;         /* loop control counter */ 
    struct wavehdr_tag *lpNext;         /* private to driver */ 
    DWORD              reserved;        /* private to driver */ 
} WAVEHDR;

The WAVEHDR data structure has the following fields:

lpData
Specifies pointer to data block.

dwBufferLength
Specifies length (in bytes) of data block.

dwBytesRecorded
Specifies number of bytes recorded.

dwUser
Specifies user instance data.

dwFlags
Specifies assorted flags.

dwLoop
Specifies information private to driver.

lpNext
Specifies information private to driver.

reserved
Specifies information private to driver.

3.6.5 WAVEINCAPS Data Structure

The WAVEINCAPS data structure is filled by the waveInGetDevCaps function with information about the capabilities of a specified waveform audio input device.

Example 3-10 shows the WAVEINCAPS data structure definition.

Example 3-10 WAVEINCAPS Data Structure Definition 

typedef struct waveincaps_tag { 
    UINT wMid;                    /* manufacturer ID */ 
    UINT wPid;                    /* product ID */ 
    VERSION vDriverVersion;       /* driver version */ 
    char szPname[MAXPNAMELEN];    /* product name */ 
    DWORD dwFormats;              /* supported standard formats */ 
    UINT  wChannels;              /* number of channels */ 
} WAVEINCAPS;

The WAVEINCAPS data structure has the following fields:

wMid
Specifies the manufacturer ID for the author of the device driver. MM_DIGITAL or MM_COMPAQ specifies Compaq Computer Corporation as the manufacturer. MM_ESS specifies that ESS Technology is the manufacturer.

wPid
Specifies the product ID for the device. MM_DIGITAL_BBA specifies the driver that supports the built-in audio capabilities of the workstation. MM_DIGITAL_J300AUDIO specifies the driver that supports the J300 audio device. MM_DIGITAL_MSB specifies the driver that supports the Microsoft Sound Board. MM_ESS_AUDIO specifies the driver that supports the ESS audio chip. MM_COMPAQ_ENS specifies the driver that supports the Ensoniq AudioPCI module.

vDriverVersion
Specifies a version number for the device driver. The high-order byte of this field is the major version number; the low-order byte is the minor version number.

szPname[MAXPNAMELEN]
Points to a null-terminated string containing the product name. Use the product name to identify devices to share.

dwFormats
Specifies the standard waveform formats supported by a device. The following flags, corresponding to each standard format, are defined as:

WAVE_FORMAT_08M08_MULAW
8-bit mono MULAW at 8 kHz
This format identifier is a Compaq extension to the API specification for the built-in audio capabilities of the workstation.

WAVE_FORMAT_1M08
8-bit mono at 11.025 kHz

WAVE_FORMAT_1S08
8-bit stereo at 11.025 kHz

WAVE_FORMAT_1M16
16-bit mono at 11.025 kHz

WAVE_FORMAT_1S16
16-bit stereo at 11.025 kHz

WAVE_FORMAT_2M08
8-bit mono at 22.05 kHz

WAVE_FORMAT_2S08
8-bit stereo at 22.05 kHz

WAVE_FORMAT_2M16
16-bit mono at 22.05 kHz

WAVE_FORMAT_2S16
16-bit stereo at 22.05 kHz

WAVE_FORMAT_4M08
8-bit mono at 44.1 kHz

WAVE_FORMAT_4S08
8-bit stereo at 44.1 kHz

WAVE_FORMAT_4M16
16-bit mono at 44.1 kHz

WAVE_FORMAT_4S16
16-bit stereo at 44.1 kHz

This field is a logical OR of the flags listed previously.

wChannels
Specifies the number of channels.

3.6.6 WAVEOUTCAPS Data Structure

The WAVEOUTCAPS data structure is filled by the waveOutGetDevCaps function with information about the capabilities of a specified waveform audio output device.

Example 3-11 shows the WAVEOUTCAPS data structure definition.

Example 3-11 WAVEOUTCAPS Data Structure Definition 

typedef struct waveoutcaps_tag { 
   UINT wMid;                   /* manufacturer ID */       
   UINT wPid;                   /* product ID */ 
   VERSION vDriverVersion;      /* driver version */     
   char szPname[MAXPNAMELEN];   /* product name */     
   DWORD dwFormats;             /* supported standard formats */ 
   UINT wChannels;;             /* number of channels */ 
   DWORD dwSupport;             /* supported features */ 
} WAVEOUTCAPS;

The WAVEOUTCAPS data structure has the following fields:

wMid
Specifies the manufacturer ID for the author of the device driver. MM_DIGITAL or MM_COMPAQ specifies Compaq Computer Corporation as the manufacturer. MM_ESS specifies that ESS Technology is the manufacturer.

wPid
Specifies the product ID for the device. MM_DIGITAL_BBA specifies the driver that supports the built-in audio capabilities of the workstation. MM_DIGITAL_J300AUDIO specifies the driver that supports the J300 audio device. MM_DIGITAL_MSB specifies the driver that supports the Microsoft Sound Board. MM_ESS_AUDIO specifies the driver that supports the ESS audio chip. MM_COMPAQ_ENS specifies the driver that supports the Ensoniq AudioPCI module.

vDriverVersion
Specifies a version number for the device driver. The high-order byte of this field is the major version number; the low-order byte is the minor version number.

szPname[MAXPNAMELEN]
Points to a null-terminated string containing the product name. Use the product name to identify devices to share.

dwFormats
Specifies the standard waveform formats supported by a device. The following flags, corresponding to each standard format, are defined as:

WAVE_FORMAT_08M08_MULAW
8-bit mono MULAW at 8 kHz
This format identifier is a Compaq extension to the API specification for the built-in audio capabilities of the workstation.

WAVE_FORMAT_1M08
8-bit mono at 11.025 kHz

WAVE_FORMAT_1S08
8-bit stereo at 11.025 kHz

WAVE_FORMAT_1M16
16-bit mono at 11.025 kHz

WAVE_FORMAT_1S16
16-bit stereo at 11.025 kHz

WAVE_FORMAT_2M08
8-bit mono at 22.05 kHz

WAVE_FORMAT_2S08
8-bit stereo at 22.05 kHz

WAVE_FORMAT_2M16
16-bit mono at 22.05 kHz

WAVE_FORMAT_2S16
16-bit stereo at 22.05 kHz

WAVE_FORMAT_4M08
8-bit mono at 44.1 kHz

WAVE_FORMAT_4S08
8-bit stereo at 44.1 kHz

WAVE_FORMAT_4M16
16-bit mono at 44.1 kHz

WAVE_FORMAT_4S16
16-bit stereo at 44.1 kHz

This field is a logical OR of the flags listed previously.

wChannels
Specifies the number of channels.

dwSupport
Specifies the standard waveform formats supported by a device. The following flags, corresponding to each standard format, are defined as:

WAVECAPS_VOLUME
Volume control support

WAVECAPS_LRVOLUME
Individual volume control support for left and right channels

This field is a logical OR of the flags listed previously.

3.6.7 ACMFORMATDETAILS Data Structure

The ACMFORMATDETAILS data structure is returned by the waveInFormatDetails and waveOutFormatDetails functions with information about a specified driver format.

Example 3-12 shows the ACMFORMATDETAILS data structure definition.

Example 3-12 ACMFORMATDETAILS Data Structure Definition 

typedef struct tACMFORMATDETAILS { 
        DWORD cbStruct; 
        DWORD dwFormatIndex; 
        DWORD dwFormatTag; 
        DWORD fdwSupport; 
        LPWAVEFORMATEX pwfx; 
        DWORD cbwfx;                     /*size of *pwfx structure*/ 
        char szFormat[ACMFORMATDETAILS_FORMAT_CHARS]; 
} ACMFORMATDETAILS, *PACMFORMATDETAILS, FAR *LPACMFORMATDETAILS;

The ACMFORMATDETAILS data structure has the following fields:

cbStruct
Specifies the size, in bytes, of the ACMFORMATDETAILS data structure. This field must be initialized before calling the waveInFormatDetails or waveOutFormatDetails functions.

dwFormatIndex
Specifies the index of the format. The index ranges from zero to one less than the number of formats supported by a driver. The number of formats supported by a driver is returned in the dwNumFormatsSupported field of the WAVEFORMATINFO data structure. The dwFormatIndex field is used only when querying format details on a driver by index; otherwise, this field should be zero.

dwFormatTag
Specifies the wave format tag.

fdwSupport
Specifies driver-support flags specific to the specified format. This argument can be a combination of the following values and indicates which operations the driver supports for the format tag.

Flags as specified by Microsoft:

ACMDRIVERDETAILS_SUPPORTF_CODEC
Specifies that this driver supports conversion between two different format tags for the specified format. For example, if a driver supports compression from WAVE_FORMAT_PCM to WAVE_FORMAT_ADPCM with the specified format, then this flag is set.

ACMDRIVERDETAILS_SUPPORTF_CONVERTER
Specifies that this driver supports conversion between two different formats of the same format tag while using the specified format. For example, if a driver supports resampling of WAVE_FORMAT_PCM to the specified format, then this flag is set.

ACMDRIVERDETAILS_SUPPORTF_FILTER
Specifies that this driver supports a filter (which modifies data without changing any format attributes) with the specified format. For example, if a driver supports volume or echo operations on WAVE_FORMAT_PCM, then this flag is set.

ACMDRIVERDETAILS_SUPPORTF_HARDWARE
Specifies that this driver supports hardware input and output of the specified format through a waveform device. An application should use acmMetrics with the ACM_METRIC_HARDWARE_WAVE_INPUT and ACM_METRIC_HARDWARE_WAVE_OUTPUT metric indexes to get the waveform device identifiers associated with the supporting ACM driver.

Flags as extended by Compaq:

ACMDRIVERDETAILS_SUPPORTF_NATIVE
Specifies that the format is implemented natively in hardware.

ACMDRIVERDETAILS_SUPPORTF_SIMULATED
Specifies that the format is implemented via hardware simulation, for example, by mixing stereo channels to play on a mono device.

ACMDRIVERDETAILS_SUPPORTF_CPU_ASSIST
Specifies that the format is implemented with significant or complete software assist.

ACMDRIVERDETAILS_SUPPORTF_UNAVAILABLE
Specifies that the format is supported, but it is temporarily unavailable.

pwfx
Specifies a pointer to a WAVEFORMATEX data structure that will receive the format details. This data structure requires no initialization by the application unless the ACM_FORMATDETAILSF_FORMAT flag is specified in waveInFormatDetails or waveOutFormatDetails .

cbwfx
Specifies the size, in bytes, available for the pwfx field to receive the format details. The waveInGetFormatInfo and waveOutGetFormatInfo functions can be used to determine the maximum size required for any format available for the specified driver.

szFormat[ACMFORMATDETAILS_FORMAT_CHARS]
Specifies a string that describes the format for the dwFormatTag field.

3.7 Waveform Audio Function Overview

Table 3-2 provides a summary of the waveform audio functions.

Table 3-2 Waveform Audio Function Summary
Application Function Description
Functions for querying waveform audio device capabilities:
waveInGetDevCaps Returns the capabilities of the specified waveform audio input device and its currently available standard formats
waveInGetDevCapsEx Returns the capabilities of the specified waveform audio input device and all its standard formats
waveOutGetDevCaps Returns the capabilities of the specified waveform audio output device and its currently available standard formats
waveOutGetDevCapsEx Returns the capabilities of the specified waveform audio output device and all its standard formats
Functions for querying waveform audio device formats:
waveInFormatDetails Returns detailed information relating to a specific supported format of the specified waveform audio input device
waveInGetFormatInfo Returns all formats supported by the specified waveform audio input device
waveOutFormatDetails Returns detailed information relating to a specific supported format of the specified waveform audio output device
waveOutGetFormatInfo Returns all formats supported by the specified waveform audio output device
Functions for returning waveform audio device IDs:
waveInGetID Gets the device ID for the specified waveform audio input device
waveOutGetID Gets the device ID for the specified waveform audio output device
Functions for querying the number of waveform audio devices:
waveInGetNumDevs Returns the number of waveform audio input devices present in the system
waveOutGetNumDevs Returns the number of waveform audio output devices present in the system
Functions for opening and closing a waveform audio device:
waveInClose Closes the specified waveform audio input device
waveInOpen Opens the specified waveform audio input device for recording
waveOutClose Closes the specified waveform audio output device
waveOutOpen Opens the specified waveform audio output device for playback
Functions for describing an audio error:
waveInGetErrorText Retrieves a text description of the error identified by the specified error number
waveOutGetErrorText Retrieves a text description of the error identified by the specified error number
Functions for allocating and preparing an audio data block:
waveInAddBuffer Sends an input buffer to the specified waveform audio input device
waveOutWrite Sends a data block to the specified waveform audio output device
Functions for getting the current record and playback position:
waveInGetPosition Retrieves the current position of the specified waveform audio input device
waveOutGetPosition Retrieves the current playback rate setting of the specified waveform audio output device
Functions for pausing and restarting playback:
waveOutPause Pauses playback on the specified waveform audio output device
waveOutRestart Restarts the specified paused waveform audio output device
Functions for modifying record and playback volume:
waveInGetVolume Queries the current volume setting of the specified waveform audio input device
waveInSetVolume Sets the current volume of the specified waveform audio input device
waveOutGetVolume Queries the current volume setting of the specified waveform audio output device
waveOutSetVolume Sets the current volume of the specified waveform audio output device
Functions for starting and stopping waveform audio recording:
waveInStart Starts input on the specified waveform audio input device
waveInStop Stops input on the specified waveform audio input device
Functions for resetting waveform audio devices:
waveInReset Stops recording on the specified waveform audio input device and resets the current position to 0
waveOutReset Stops playback on the specified waveform audio output device and resets the current position to 0
Function for breaking a loop on a waveform audio output device:
waveOutBreakLoop Breaks a loop on the specified waveform audio output device and allows playback to continue with the next block in the driver list
Functions for specifying ports:
waveInGetPorts Determines the ports through which input of audio data is enabled
waveInSelectPorts Selects the ports through which input of audio data is enabled
waveOutGetPorts Determines the ports through which output of audio data is enabled
waveOutSelectPorts Selects the ports through which output of audio data is enabled

Previous Next Contents Index