MMPM/2 Device Driver Reference
Adding Support for Audio and Video Adapters Audio Physical Device Driver Template Audio Virtual Device Driver Template MAD16 PDD and VDD Sample Device Drivers PDD Sample for Video Capture Adapters PDD Sample for MPEG Video Playback Devices Audio Sample for Vendor-Specific Drivers Using the High-Resolution Timer Real-Time MIDI Subsystem Audio Device Driver Exerciser (PMADDE) Tool AP2/P2STRING Tool Ultimotion Data Stream Specification DDCMD Messages SHD Messages Vendor-Specific Driver Commands IOCtl Functions Data Types Types of MIDI Messages Notices Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

OS/2 device drivers are used to access the I/O hardware. The IOCtl functions provide a method for an application, or subsystem, to send device specific control commands to a physical device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl function request. The DosDevIOCtl request can be used only by OS/2 applications; the INT 21h IOCtl request can be used only by DOS applications.

This reference describes audio (category 80h) and video (category 140h) IOCtls.

Audio IOCtl Functions

Audio device drivers are controlled through input/output control (IOCtl) calls, which are used to instruct the audio device driver on the type of audio to use (for example, MIDI, 8- or 16-bit PCM, and so forth) and which operation to perform (for example, record, play, start, or pause). During audio playback, data is written to an audio device driver using standard file I/O functions. MIDI data is written in blocks containing timing information that enables the device driver to synchronize the data with its internal time base. Sampled audio data is output, sample-by-sample, at the specified sample rate. Therefore, data written to the device driver is queued until the correct time for it to be processed.

It is in the best interest of OS/2, MMPM/2, and the application that the audio IOCtls be used only for setting audio attributes and not for passing audio data from an MMPM/2 application to the PDD. The preferred method of passing audio data is for the application to issue play and record commands using the media control interface. A logical media device is called, which in turn calls the stream programming interface. Data transfer takes place between a stream handler device driver and the PDD by means of the inter- device driver communications (IDC) interface.

Using the IDC method of data transfer relieves applications from the burden of allocating data buffer memory and monitoring the flow of data. The messages that comprise the IDC interface can be found in DDCMD Messages and SHD Messages.

Audio IOCtl parameters are passed to and from a device driver in a data area containing one or more 16-bit USHORT parameters. The first parameter always is the Request ID. Subsequent USHORTs pass data to, or receive data from, the device driver. The generic IOCtl interface uses two data-passing parameters, the parameter packet and the data packet. For audio IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used.

The audio IOCtls listed in the following table are category 80h (user defined):

Function No.	Function	Description
40h	AUDIO_INIT	Initialize audio device driver.
41h	AUDIO_STATUS	Obtain status of audio hardware.
42h	AUDIO_CONTROL	Control audio adapter.
43h	AUDIO_BUFFER	Determine buffer status.
44h	AUDIO_LOAD	Load DSP code.
45h	AUDIO_WAIT	Suspend program operation.
46h	AUDIO_HPI	Access high-performance interface.
47h	AUDIO_UPDATE	Update buffer information.
48H	AUDIO_CAPABILITY	Determine supported audio settings.
52H		reserved
53H		reserved
54H		reserved
55H		reserved
60H	MIX_GETCONNECTIONS	Determine if line is enabled.
61H	MIX_SETCONNECTIONS	Enable a line to the Record/monitor circuitry.
62H	MIX_GETLINEINFO	Determine line capabilities.
63H	MIX_GETCONTROL	Get current state of a line.
64H	MIX_SETCONTROL	Set current state of a line.

Note: This chapter documents AudioDD IOCTLs that could be sent to MMPM/2 device drivers.

To support MMPM/2 the following IOCTLs are necessary:

AUDIO_INIT

Required for all MMPM/2 device drivers.

AUDIO_CONTROL

Required for all MMPM/2 device drivers.

AUDIO_LOAD

Optional, used to load DSP tasks.

MIXDM_GETCONNECTIONS

Enhanced mixing IOCTLs (new)

MIXDM_SETCONNECTIONS
MIXDM_GETLINEONFO
MIXDM_GETCONTROL
MIXDM_SETCONTROL
AUDIO_CAPABILITY

Used to simplify install (new)

The remaining IOCtls documented in this chapter are provided as reference for device driver writers who wish to support AudioDD knowledgeable applications. These applications include IBM Linkway Live and early versions of IBM AVC (Audio Visual Connection).

AUDIO_INIT (40h) - Initialize Audio Device Driver

This IOCtl enables an application to tell the audio device driver which operation and audio type to use. It does this by initializing the appropriate MCI_AUDIO_INIT fields to the desired values and calling AUDIO_INIT.

Parameter Packet Format: Not used. The packet pointer must be NULL.
Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _init {
  LONG           lSRate;
  LONG           lBitsPerSRate;
  LONG           lBsize;
  SHORT          sMode;
  SHORT          sChannels;
  LONG           lResolution;
  CHAR           abLoadPath[LOAD_PATH];
  ULONG          ulFlags;
  ULONG          ulOperation;
  SHORT          sReturnCode;
  SHORT          sSlotNumber;
  SHORT          sDeviceID;
  VOID FAR      *pvReserved;
  ULONG          ulVersionLevel;
} MCI_AUDIO_INIT;

typedef   MCI_AUDIO_INIT   FAR  *LPMCI_AUDIO_INIT;

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_INIT

Returns: If the audio device driver can satisfy the request as specified, it returns 0. If the request cannot be performed as specified, the audio device driver fills in the MCI_AUDIO_INIT fields with the supported values that most closely approximate the values specified by the user, sets the BESTFIT_PROVIDED bit in ulFlags, and returns 0 to the application.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

Remarks: Before calling AUDIO_INIT, the application must have opened the audio device driver. If the application specifies invalid data in the MCI_AUDIO_ INIT, the device driver probably will not return an error. Instead, one of its supported modes will return with the BESTFIT_PROVIDED bit set in ulFlags of the MCI_AUDIO_INIT structure and the fields filled in. If, after examination of the returned values, the application is satisfied with the approximation, it can continue. Otherwise, it should use other values and reissue AUDIO_INIT.

Some audio devices are capable of performing more than one audio operation at a time. Therefore, the device driver for such devices can permit more than one application to use the device at one time by allowing multiple Opens to be active. If the device can perform the operations requested by two applications at the same time, it will appear to be two different audio devices. If the device cannot perform a requested operation because that operation is being performed for another application, it will return the OVERLOADED flag set in the sReturnCode field.

Note: It is critical that the application check the returned ulFlags and sReturnCode fields before proceeding.

If an application is going to perform audio simultaneously on more than one track, the application should perform OPENs and AUDIO_INITs for both devices before issuing AUDIO_START for either device. This enables the device to select the correct DSP load module to support both tasks, when possible.

AUDIO_STATUS (41h) - Obtain Status of Audio Hardware

This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.

This IOCtl enables an application to obtain the current state of the audio hardware for a particular track.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _stat {
  LONG                   lSRate;
  LONG                   lBitsPerSRate;
  LONG                   lBsize;
  SHORT                  sMode;
  SHORT                  sChannels;
  ULONG                  ulFlags;
  ULONG                  ulOperation;
  MCI_AUDIO_CHANGE       rAudioChange;
} MCI_AUDIO_STATUS;

typedef   MCI_AUDIO_STATUS   FAR * LPMCI_AUDIO_STATUS;

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_STATUS

Returns: The values associated with the current audio mode are returned in the fields, lSRate, lBitsPerSRate, lBsize, sMode, sChannels, and ulFlags of the MCI_AUDIO_STATUS structure. The MCI_AUDIO_CHANGE data structure contains the current input, output, monitor, volume, balance, and tone control settings.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

AUDIO_CONTROL (42h) - Control Audio Adapter

This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The adapter state is changed by the following usIOCtlRequest values:

AUDIO_START (Not required for MMPM/2.)
AUDIO_STOP (Not required for MMPM/2.)
AUDIO_PAUSE (Not required for MMPM/2.)
AUDIO_RESUME (Not required for MMPM/2.)
AUDIO_CHANGE

Adapter characteristics are changed by the usIOCtlRequest value AUDIO_ CHANGE.

Parameter Packet Format: Not used. The packet pointer must be NULL.
Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _MCI_AUDIO_CONTROL {
  USHORT       usIOCtlRequest;
  VOID        *pbRequestInfo;
  ULONG        ulPosition;
  SHORT        sReturnCode;
} MCI_AUDIO_CONTROL;

typedef   MCI_AUDIO_CONTROL  FAR * LPMCI_AUDIO_CONTROL

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_CONTROL

Returns: If a requested input or output device is not supported by the audio device, sReturnCode is set and an error returned.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

Remarks: The K12 version does not support ulPosition values except for 0. Any pending AUDIO_CHANGE requests are discarded when AUDIO_INIT is issued.

AUDIO_BUFFER (43h) - Determine Buffer Status

This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.

This IOCtl is used to determine the amount of data currently queued, device driver internal queue sizes, and whether an overrun or underrun has occurred. If either state has occurred, its respective bit is turned on in the ulFlags field.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _buffer {
  ULONG       ulFlags;
  ULONG       ulReadBufSize;
  ULONG       ulWriteBufSize;
  ULONG       ulReadBufTime;
  ULONG       ulWriteBufTime;
  ULONG       ulReadBufMax;
  ULONG       ulWriteBufMax;
  ULONG       ulPosition;
  ULONG       ulPositionType;
  LONG        lReadBufCap;
  LONG        lWriteBufCap;
  LONG        lRequestBufCap;
} MCI_AUDIO_BUFFER;

typedef   MCI_AUDIO_BUFFER FAR * LPMCI_AUDIO_BUFFER;

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_BUFFER

Returns: The amount of data is expressed as the number of bytes currently in the queues. Notice that the amount of queue data that this IOCtl returns is accurate only at the point in time this value is determined. The amount of queued data can be different at any other point in time.

If the size of the buffer contents can be represented as an amount of time, that amount of time is returned in the fields ulReadBufTime and ulWriteBufTime. If not, the values returned are -1. To help determine the optimal size of the Read and Write kernel buffer queues, the maximum number of bytes that these queues have ever contained is returned in ulReadBufMax and ulWriteBufMax.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

Remarks: This IOCtl is used to return data from the device driver and cannot be used to pass data to the device driver.

AUDIO_LOAD (44h) - Load DSP Code

If the LOAD_CODE bit is set in the ulFlags field of the MCI_AUDIO_INIT structure on an AUDIO_INIT request, the application must load the DSP code (specified by the device driver in the abLoadPath field of MCI_AUDIO_INIT) into a buffer and issue an AUDIO_LOAD IOCtl request.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _load {
  CHAR FAR      *pbBuffer;
  ULONG          ulSize;
  ULONG          ulFlags;
} MCI_AUDIO_LOAD;

typedef   MCI_AUDIO_LOAD FAR * LPMCI_AUDIO_LOAD;

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_LOAD

Remarks: The pbBuffer field of the MCI_AUDIO_LOAD structure must point to the start of the buffer where the code is loaded. The ulSize field must be set to the number of bytes of loaded code (which is the size of the file). The ulFlags field permits loading the file in multiple pieces. To do this, the first piece is written with the LOAD_START flag set and the last piece with the LOAD_END flag set. All intermediate pieces have both flags cleared. To load the file in a single piece, both flags are set. Notice that the first buffer written must be at least 128 bytes in length.

AUDIO_WAIT (45h) - Suspend program operation

This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.

This IOCtl is used to suspend program operation until all previously written data is played by the device.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Data Packet Format: There are no parameters for AUDIO_WAIT. The packet pointer must be NULL.

Returns: Refer to the OS/2 Control Program Guide and Reference for a description of the return code for DosDevIOCtl.

Remarks: The actual playing of audio data by the audio device can occur after the Write call is returned to the caller. If the caller does not want to continue program execution until all data is actually played by the device, it can issue AUDIO_WAIT. Some audio devices play audio data in discrete blocks. Data is not played unless at least a full block of data is available. If less than a block of data remains to be played, AUDIO_WAIT can be called, which causes the audio device driver to pad the data with silence, thus permitting the data to be played. The amount of data in the buffers can be determined using AUDIO_BUFFER.

AUDIO_WAIT does nothing if there are no prior calls to Write or AUDIO_HPI. Instead, it returns immediately to the caller.

AUDIO_HPI (46h) - Access high-performance interface

This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.

This IOCtl provides several high-performance interface functions and can be used to increase the size of the device driver's internal input and output buffers for higher bandwidth audio modes.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _hpi {
  VOID FAR                  *pvEntry ();
  VOID FAR                  *pvCallBack ();
  LPMCI_AUDIO_IOBUFFER       prXBuff;
  LPMCI_AUDIO_IOBUFFER       prRBuff;
  USHORT                     usFlags;
} MCI_AUDIO_HPI;

typedef   MCI_AUDIO_HPI FAR * LPMCI_AUDIO_HPI;

Data Packet Format

Field	C Datatype
Pointer to structure	LPMCI_AUDIO_HPI

Returns: An address is returned in pvEntry () in the MCI_AUDIO_HPI structure that can be used to invoke audio device driver functions directly. NULL is returned if this function is not available in the current environment.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

AUDIO_UPDATE (47h) - Update Buffer Information

This IOCtl is not required for MMPM/2. It is part of the AudioDD specification and is provided for reference.

This IOCtl has two purposes:

To condense the array of buffers by removing all buffers that have been processed from the array of buffers in the MCI_AUDIO_IOBUFFER data structure.
To add a buffer to the list. The address and length of the buffer is passed down to the device driver in the audio_update structure.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _audio_update {
  CHAR           iobuf_type;
  CHAR FAR      *buffer_address;
  ULONG          buffer_length;
  USHORT         rc;
  void FAR      *reserved;
} audio_update;

typedef struct audio_update FAR * UPDATE;

Data Packet Format

Field	C Datatype
Pointer to structure	UPDATE

Returns: On exit, rc of the audio_update structure contains an error code if one of the DevHlp calls failed or the maximum number of buffers have already been queued.

Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl.

Remarks: To use this IOCtl, the application must use the high-performance interface. When AUDIO_HPI calls the device driver, an MCI_AUDIO_IOBUFFER structure with the maximum number of buffers that can be present must be passed. The iobuf->num_buffers field should have the maximum number of buffers in it. Notice that there is a limit of 16 buffers that can be present.

It is not necessary for buffers passed in the buffer array of the MCI_AUDIO _IOBUFFER structure to contain addresses to buffers. Any or all of the buffers can point to NULL addresses and have lengths of 0. The device driver searches the list of the buffers, counts the number of non-NULL buffers, and sets the iobuf->num_buffers to this number. All internal variables are initialized to allow access to that number of buffers. AUDIO_ HPI must be called again if this number changes.

When AUDIO_UPDATE is called, it removes all buffers in the current MCI_ AUDIO_IOBUFFER buffer array that have been processed. It then recalculates iobuf->num_buffers and iobuf->size (the total of all the buffer lengths). Notice that the buffer size must be an even number of bytes and less than 64KB in length.

If the MCI_AUDIO_IOBUFFER structure to be updated is to be transmitted, it is assumed that the buffer passed is full of data to be played. The pHead pointer is updated to point to the beginning of the buffer following the buffer just added to the chain. The lCount field is also updated by the device driver to include this buffer of data.

If buffer_address is NULL, this IOCtl simply frees processed buffers and returns. To free a buffer, the device driver unlocks it if it is locked and sets the length to 0.

AUDIO_CAPABILITY (48h) - Determine If a Group of Audio Settings is Supported

This IOCtl enables an application to determine if a particular group of audio settings can be supported. If the mode is supported, resource management information will be returned to the caller.

Parameter Packet Format: Not used. The packet pointer must be NULL.

Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _MCI_AUDIO_CAPS {
  ULONG       ulLength;
  ULONG       ulSamplingRate;
  ULONG       ulChannels;
  ULONG       ulBitsPerSample;
  ULONG       ulDataType;
  ULONG       ulOperation;
  ULONG       ulSupport;
  ULONG       ulDataSubType;
  ULONG       ulResourceUnits;
  ULONG       ulResourceClass;
  ULONG       ulBlockAlign;
  BOOL        fCanRecord;
  ULONG       ulFlags;
  ULONG       ulCapability;
} MCI_AUDIO_CAPS;

typedef MCI_AUDIO_CAPS  FAR * PAUDIO_CAPS;

Data Packet Format

Field	C Datatype
Pointer to structure	PAUDIO_CAPS

Returns

SUPPORT_SUCCESS
UNSUPPORTED_RATE
UNSUPPORTED_CHANNELS
UNSUPPORTED_BPS
UNSUPPORTED_DATATYPE
UNSUPPORTED_OPERATION

Example Code

The following example code illustrates an application querying the audio device driver for its capabilities. If the device supports the desired mode, the application saves the information.

  AUDIOCAPS   audiocaps;

  audiocaps.ulSamplingRate = 11025;
  audiocaps.ulBitsPerSample = 16;
  audiocaps.ulChannels = 2;
  audiocaps.ulDataType = DATATYPE_WAVEFORM;
  MAKE1616(&audiocaps);
     rc = DosDevIOCtl(  handle,
                       AUDIO_IOCTL_CAT,
                       AUDIO_CAPABILITY,
                       0,
                       0,
                       0,
                       sizeof (audiocaps),
                       &audiocaps,
                       (PVOID) &ulParmLengthMax);
  if ( audiocaps.ulReturn )
    {
     // process success
     }
  else
     // process failure

Remarks: This information supersedes the information found in the VSD resource file. If this IOCtl is supported, a VSD resource DLL is not necessary.

The ulSamplingRate, ulChannels, ulBitsPerSample, and ulDataType fields of the MCI_AUDIO_CAPS structure must be filled in by the caller. The device driver will return SUPPORT_SUCCESS in the ulSupport field if it supports the combination and non-zero if it does not. If SUPPORT_SUCCESS is returned, the driver must also fill in the following fields of the MCI_ AUDIO_CAPS structure:

ulDataSubType. See valid subtypes in os2medef.h.

ulResourceClass. See Resource Classes and Resource Units for more information.

ulResourceUnits. See Resource Classes and Resource Units for more information.

ulBlockAlign. Block alignment of the data.

If ulSupport contains a non-zero value, the driver should fill in the MCI_ AUDIO_CAPS structure with the nearest mode that matches the user's request (e.g. best-fit). The following fields must be updated for a best-fit:

ulSamplingRate
ulChannels
ulBitsPerSample
ulDataType

Resource Classes and Resource Units

When each audio device driver is installed in MMPM/2, the following three keywords are placed in the MMPM/2 INI file by the install routines:

RESOURCEUNITS=
RESOURCECLASSES=
VALIDCOMBINATIONS=

Because MMPM/2 allows many applications to simultaneously open the audio card, it uses the following keywords to determine which applications can simultaneously use the audio device. Although the numbers are arbitrary and are defined on a device-by-device basis, device driver writers should use the numbering scheme described below:

The keyword RESOURCECLASSES indicates the different resource types available on the audio device. Vendors should provide a class for each data type that they support. For example, if the XYZ audio card can only play only PCM files, it would only have one resource class in the MMPM2.INI file, the PCM class. However, if the ABC card could play PCM, MIDI and ADPCM, it would have three classes in the MMPM2.INI file. The device driver should fill in the ulResourceClass field with the correct class for the current mode.

The keyword RESOURCEUNITS indicates the maximum number of instances that can be active on the card at any particular time. For example, if the XYZ card mentioned above had the ability to play three PCM files at the same time, the RESOURCEUNITS in the MMPM2.INI file for this card would be three. In contrast, the ABC card can only play one PCM and one MIDI at any one time. Therefore, its resource units should be two in the MMPM2.INI file. The device driver should fill in the ulResourceUnits field of the AUDIO_ CAPABILITY structure with the correct number of resources for the current mode (typically, one).

The keyword VALIDCOMBINATIONS informs MMPM/2 which RESOURCECLASS can be active at the same time on the audio device. For example, the XYZ card mentioned above can only play PCM files so it has no valid combinations. By contrast, the ABC card can play MDI and PCM at the same time; therefore, the VALIDCOMBINATIONS statement would state that the MIDI class could be active at the same time the PCM class is active and vise-versa. The valid combinations information is static and does not need to be returned by the device driver.

Mixer IOCtl Functions Introduction

The model of this mixer interface is based on a mixer device with a number of sources (such as microphone, PCM playback, and internal CD connector) which can be routed to a number of sinks or outputs (such as the recording circuitry or monitoring circuitry). The settings for the sources or sinks can be queried and set; and the capabilities of each input/output line can easily be determined.

 +------------------------------------+
 |                                    |
 |    Sources          Sinks          |
 | +--------------------------------+ |
 | |               |                | |
 | |   Synth       |   Line Out     | |
 | |               |                | |
 | |   Line In     |   Speaker Out  | |
 | |               |                | |
 | |   Wave Data   |   Head Phones  | |
 | |               |                | |
 | |   Internal    |   Generic Out  | |
 | |   Audio       |                | |
 | |               |   Wave         | |
 | |   Microphone  |                | |
 | |               |   NULL         | |
 | |   PC Speaker  |                | |
 | |               |                | |
 | +--------------------------------+ |
 +------------------------------------+

Standard sources are listed on the left. Standard sinks are listed on the right. The Generic Out includes line out, speaker out, and head phones.

The following IOCtls are recent additions to the AUDIO IOCTL category:

MIX_GETCONNECTIONS
MIX_SETCONNECTIONS
MIX_GETLINEINFO
MIX_GETCONTROL
MIX_SETCONTROL

MIX_GETCONNECTIONS (60h) - Determine if Line is Enabled

This IOCtl enables an application to determine if a particular mixer line is enabled.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS;

The caller is responsible for filling in the ulLine field of the LINECONNECTIONS structure.

A bitmap describing the current connection structure will be returned in the ulConnections field. Each on bit indicates a connector which is enabled. For example, if the input line to be queried was set to 0 (i.e. the first line) and if that input line is connected to output line #0, bit 0 of ulConnections will be set. Logically, connection information can only be maintained for a mixer with a maximum of 32 inputs and 32 outputs.

Data Packet Format

Field	C Datatype
Pointer to structure	PLINECONNECTIONS

Returns

MIXERR_NOERR Successful operation.
MIXERR_INVALIDHANDLE Invalid handle specified.
MIXERR_INVALIDINPUT Invalid source specified.
MIXERR_INVALIDOUTPUT Invalid sink specified.
MIXERR_NOTSUPPORTED Mixer type unsupported.

Example Code

The following code illustrates how to use MIX_GETCONNECTIONS.

   HMIXER   hMix;
   LINECONNECTIONS  LineCon;
   /*-----------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   LineCon.ulLine = SOURCE_SYNTHESIZER;
   LineCon.ulLength = sizeof( LINECONNECTIONS);
    rc = DosDevIOCtl( hMix,
                      AUDIO_IOCTL_CATEGORY,
                      MIX_GETCONNECTIONS,
                      0,
                      0,
                      0,
                      sizeof (LINECONNECTIONS),
                      &LineCon,
                      &ulDataLengthOut);

MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line

This IOCtl enables an application to connect an input line to an output line.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS;

The caller is responsible for filling in the ulLine and ulConnections fields of the LINECONNECTIONS structure.

Data Packet Format

Field	C Datatype
Pointer to structure	PLINECONNECTIONS

Returns

MIXERR_NOERR Successful operation.
MIXERR_INVALIDHANDLE Invalid handle specified.
MIXERR_INVALIDINPUT Invalid source specified.
MIXERR_INVALIDOUTPUT Invalid sink specified.
MIXERR_NOTSUPPORTED Mixer type unsupported.

Example Code

The following code illustrates how to use MIX_SETCONNECTIONS.

 HMIXER   hMix;
 LINECONNECTIONS     mixinfo;
 PVOID     p16Info;
  /*-------------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   mixinfo.ulLine = SOURCE_SYNTHESIZER;
   mixinfo.ulConnection = SINK_SPEAKER;
      rc = DosDevIOCtl( hMix,
                        AUDIO_IOCTL_CATEGORY,
                        MIX_SETCONNECTIONS,
                        0,
                        0,
                        0,
                        sizeof (LINECONNECTIONS),
                        &mixinfo,
                        &ulDataLengthOut);

MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line

This IOCtl enables an application to determine the capabilities of a particular line. For instance, an application will call this function to determine if an individual line (for example, the microphone) allows adjustments for volume or balance.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _MIXERLINEINFO {
  ULONG       ulLength;
  ULONG       ulNumChannels;
  ULONG       ulSupport;
  ULONG       ulConnectionsPossible;
  ULONG       ulLine;
} MIXERLINEINFO;

typedef   MIXERLINEINFO   FAR   * PMIXERLINEINFO;

The caller is responsible for filling in the ulLine field of the MIXERLINEINFO structure.

Data Packet Format

Field	C Datatype
Pointer to structure	MIXERLINEINFO

Returns

MIXERR_NOERR Successful operation.
MIXERR_INVALIDHANDLE Invalid handle specified.
MIXERR_INVALIDINPUT Invalid source specified.
MIXERR_INVALIDOUTPUT Invalid sink specified.
MIXERR_NOTSUPPORTED Mixer type unsupported.

Example Code

The following code illustrates how to use MIX_GETCONNECTIONS.

   HMIXER   hMix;
   LINECONNECTIONS     mixinfo;
   /*-------------------------------------------
   * Find out the capabilities for setting the
   * synth input.
   *-----------------------------------------*/
   mixinfo.ulLine = SOURCE_SYNTHESIZER;
   rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_GETLINEINFO,
                     0,
                     0,
                     0,
                     sizeof (LINECONNECTIONS),
                     &mixinfo,
                     &ulDataLengthOut);

MIX_GETCONTROL (63h) - Get Current State of a Line

This IOCtl enables an application to get the current state of a particular line.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR  * PMIXERCONTROL;

The caller is responsible for filling in the ulLinefield of the MIXERCONTROL structure.

The device driver should return the current setting of the line in the ulSetting field of the MIXERCONTROL structure. For stereo controls, the high-order word should contain information for the left-channel and the low -order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout.

Data Packet Format

Field	C Datatype
Pointer to structure	PMIXERCONTROL

Returns

MIXERR_NOERR Successful operation.
MIXERR_INVALIDHANDLE Invalid handle specified.
MIXERR_INVALIDINPUT Invalid source specified.
MIXERR_INVALIDOUTPUT Invalid sink specified.
MIXERR_NOTSUPPORTED Mixer type unsupported.

Example Code

The following code illustrates how to use MIX_GETCONNECTIONS.

   HMIXER   hMix;
   MIXERCONTROL        MixerControl;
   /*-------------------------------------------
   * Find out the setting for the synth.
   *-----------------------------------------*/
   MixerControl.ulLine= SOURCE_SYNTHESIZER;
   /* Ask vsd what is the current setting of the connector */
   MixerControl.ulControl = MIX_VOLUME;
   /* The controls current setting will be returned here */
         rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_GETCONTROL,
                     MixerControl,
                     0,
                     0,
                     sizeof (MIXERCONTROL),
                     (PVOID) &ulParmLengthMax,
                     &ulDataLengthOut);

MIX_SETCONTROL (64h) - Set State of a Mixer Line

This IOCtl enables an application to set the current state of a particular line.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR  * PMIXERCONTROL;

The caller is responsible for filling in the ulControl, the ulLine, and the ulSetting, fields of the MIXERCONTROL.

The device driver should return the current setting of the line in ulSetting of the MIXERCONTROL structure. For stereo controls, the high- order word should contain information for the left-channel and the low- order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout.

Data Packet Format

Field	C Datatype
Pointer to structure	PMIXERCONTROL

Returns

MIXERR_NOERR Successful operation.
MIXERR_INVALIDHANDLE Invalid handle specified.
MIXERR_INVALIDINPUT Invalid source specified.
MIXERR_INVALIDOUTPUT Invalid sink specified.
MIXERR_NOTSUPPORTED Mixer type unsupported.

Example Code

The following code illustrates how to use MIX_GETCONNECTIONS.

   HMIXER   hMix;
   MIXERCONTROL        MixerControl;

   /* Set the volume for the output device */

   MixerControl.ulControl = MIX__VOLUME;
   MixerControl.ulLine = SINK_LINE_OUT;
   MixerControl.ulSetting = 100;
     rc = DosDevIOCtl( hMix,
                     AUDIO_IOCTL_CATEGORY,
                     MIX_SETCONTROL,
                     0,
                     0,
                     0,
                     sizeof (MIXERCONTROL),
                     &MixerControl,
                     &ulDataLengthOut);

IOCtl Examples

Examples of how IOCtls are used to communicate with an audio device driver are shown in this section for C programs running under OS/2, and for assembler language programs running under DOS. The following example is a pseudocode example that shows how an application records or plays back audio data.

Open audio device driver.
 If error opening driver:
     then end with error message.
 Issue AUDIO_INIT IOCtl to set type of audio data to play or record.
 If BESTFIT_PROVIDED flag set:
     check audio parameters returned by AUDIO_INIT IOCtl
     if returned parameters not acceptable:
         then end with message.
 If LOAD_CODE flag set:
     load file name returned in loadpath and issue AUDIO_LOAD IOCtl.

 Issue AUDIO_CONTROL CHANGE to initialize connections and control values.

 If recording:
     Open new file to write audio data to issue AUDIO_CONTROL START IOCtl.
     Do until Stop key pressed:
10
     Issue Read to get data.
     Write data to file.
     Do user interface or other processing.
     End Do.
 Issue AUDIO_CONTROL STOP IOCtl (optional).

 Else if playback:
     Open file containing data to play back.
     Issue AUDIO_BUFFER IOCtl to determine size of buffers.
     Read data from file and write data to fill audio DD buffer.
     Issue AUDIO_CONTROL START IOCtl.
     Do until end of file or Stop key pressed:
       Issue AUDIO_BUFFER IOCtl to determine free space in audio DD buffer.
       Read data from file.
       Write data to audio DD to fill audio DD buffer.
       Do user interface or other processing.
       End Do.
     Issue AUDIO_CONTROL STOP IOCtl (optional).
 Close data file.
 Close audio DD.

Under OS/2, IOCtls are called using the DosDevIOCtl function. The following example is an OS/2 AUDIO_INITexample.

#define   INCL_DOSDEVICES

#include  <os2.h>
#include  <io.h>
#include  <audiodd.h>                 /* Defines for flags, and so forth */

init_adpcmv(Handle)                   /* Initialize to record ADPCM voice */

HFILE Handle;                         /* Handle returned from DosOpen() */
{
   struct audio_init buffer;          /* I/O buffer (defined in audiodd.h) */
   USHORT rc;

   buffer.srate = 11025;              /* Set rate = Voice mode   */
   buffer.bits_per_sample = 16;       /* 16-bits per sample      */
   buffer.bsize = 576;                /* Size of Voice mode data block */
   buffer.mode = ADPCM;               /* ADPCM mode              */
   buffer.channels = 1;               /* Mono                    */
   buffer.flags = FIXED;              /* Fixed block size data   */
   buffer.operation = RECORD;         /* Set up to record        */
   buffer.version_level = 0x01000018; /* Set version level       */

   rc = DosDevIOCtl(Handle, AUDIO_IOCTL_CAT, AUDIO_INIT, NULL, 0L,
        &ParmLengthInOut, &buffer, (LONG)sizeof(buffer),
        &lDataLengthInOut);

   if(rc)
      return(rc);
}

Under DOS, IOCtls are called by using INT 21h Function 44h. The following is a DOS IOCtl example.

INCLUDE AUDIODD.INC             ; Audio DD equates
/abort
; Read the queue status using AUDIO_BUFFER IOCtl

Handle  DW  ?                   ; Handle to open device (MIDIn$)
Buffer                          ; I/O Buffer
FLAGS           DD  0           ; Error condition flags
READ_BUF_SIZE   DD  0           ; Number of bytes currently in Receive queue
WRITE_BUF_SIZE  DD  0           ; Number of bytes currently in Transmit queue
READ_BUF_TIME   DD  0           ; Amount of data in Receive queue in millisecs
WRITE_BUF_TIME  DD  0           ; Amount of data in Transmit queue in millisecs
READ_BUF_MAX    DD  0           ; Maximum number of bytes ever in Read queue
WRITE_BUF_MAX   DD  0           ; Maximum number of bytes ever in Write queue
POSITION        DD  0           ; Time count since beginning of operation
POSITION_TYPE   DD  0           ; Specifies the type of position units
READ_BUF_CAP    DD  0           ; Capacity of Receive queue ; -1 if variable 
WRITE_BUF_CAP   DD  0           ; Capacity of Write queue ; -1 if variable
REQUEST_BUF_CAP DD  0           ; Maximum number of requests that can be queued
Query_Q_Status: 

     MOV   AH, 44h                 ; Function call - IOCtl
     MOV   AL, 0Ch                 ; Indicate generic IOCtl request
     MOV   BX, Handle              ; Select audio device handle (from previous OPEN)
     MOV   CH, 80h                 ; Generic IOCtl category
     MOV   CL, 40h + AUDIO_BUFFER  ; Generic IOCtl Function ID
     MOV   DX, Offset  Buffer      ; DS:DX points to buffer
     INT   21h                     ; Issue request to DOS
     JC    Error                   ; Error code in AX if C set
     .
     .
     .

M-Audio MCI_AUDIO_INIT Parameters

The following table lists the MCI_AUDIO_INIT parameters for the operating modes currently supported by the IBM M-Audio Capture and Playback Adapter.

Description	Mode	Bits per Sample	Sample rate	No. Chan.	Block size	Flags
MIDI	MIDI	-	-	-	-	-
AVC Voice	ADPCM	16	11025	1	576	Fixed
AVC Music	ADPCM	16	22050	1	1128	Fixed
AVC Stereo	ADPCM	16	22050	2	2256	Fixed
AVC High Quality	ADPCM	16	44100	1	1128	Fixed
8 bit PCM	PCM	8	8000, 11025, 22050, 44100	1	560	0
8 bit PCM stereo	PCM	8	8000, 11025, 22050, 44100	2	560	0
16 bit PCM mono	PCM	16	8000, 11025, 22050, 44100	1	560	TWOS_COMPLEMENT
16 bit PCM stereo	PCM	16	8000, 11025, 22050, 44100	2	560	TWOS_COMPLEMENT
8 bit mu-law mono	MU_LAW	8	8000, 11025, 22050, 44100	1	560	0
8 bit mu-law stereo	MU_LAW	8	8000, 11025, 22050	2	560	0
8 bit A-law mono	A_LAW	8	8000, 11025, 22050, 44100	1	560	0
8 bit A-law stereo	A_LAW	8	8000, 11025, 22050	2	560	0
Claim Hardware	CLAIM_HDWR	-	-	-	-	-
Source Mix	SOURCE_MIX	-	-	-	-	-
Speech Viewer/2 BCPCM	SPV2BCPCM	16	14700	-	426 tx / 426 rx	0
Speech Viewer/2 PCM	SPV2PCM	16	14700	-	964 tx / 2 rx	0
Speech Viewer/2 Computations	SPV2NONE	-	-	-	256 tx / 138 rx	-
ADPCM XA mono	ADPCMXA	16	18900, 37800	1	1304	0
ADPCM XA stereo	ADPCMXA	16	18900, 37800	2	1304	0

Video IOCtl Functions

Video capture and/or playback device drivers are controlled through input/output control (IOCtl) calls, which are used to query and instruct the video device driver. This interface has been used for numerous types and combinations of video devices-e.g., frame grabber, overlay, inlay, TV tuner, uncompressed playback, and compress video playback.

Video IOCtl parameters are passed to and from a device driver in a data area containing one or more 16-bit USHORT parameters. The first parameter is always the Request ID. Subsequent USHORTs are used to pass data to, or receive data from, the device driver. The generic IOCtl interface uses two parameters for passing data, the parameter packet and the data packet. For video IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used.

Capture

Video images can be captured one frame at a time when directed by the application. This type of capture mode is referred to as asymmetric capture because the time between successive frames is not constant. The frame rate is determined by the length of time that the application delays between taking image snapshots. Asymmetric capture is performed with IOCtls only; the MMPM/2 streaming mechanism is not used.

Typically, a stream is established to read a series of movingimages from the device. This continuous capture mode is called symmetric or real-time capture, and is done at a constant frame rate and constant frame size. When established, a stream captures images continuously without assistance from the application code. A running stream cannot dynamically alter frame rate or size; but video quality attributes such as brightness, hue, and contrast can be altered dynamically. The command used in streaming capture can be found in the Device Driver Commands (DDCMD) messages and Stream-Handler Device (SHD) messages sections.

Streaming capture is used to make real-time movies and to monitor live video on frame-grabber cards.

Playback

Video playback is all done through the VCAI_PLAY IOCtl interface. Unlike record, this is performed through the Inter-Device Driver (IDC) DDCMD messages. The MMPM/2 subsystem invokes the VCAI_PLAY functions from one of two places:

For compressed playback, the hardware (COmpressor/DECompressor) CODEC calls the play function directly with the compressed data.

With compressed data playback, the MCD issues all the VSD/PDD commands except the VCAI_PLAY and VCAI_LOAD_MICROCODE commands-which are issued by the CODEC.

In the case of uncompressed playback, the play function is issued by the Direct Interface Video Extensions (DIVE) component after the appropriate CODEC has decompressed the image. DIVE knows to call this video device driver instead of the normal display driver because of the (OverlayAccelerator) entry in the DIVE.INI file, where the VSD DLL (VSDDRIVE =) and video device driver (PDDNAME=) names are specified for DIVE. When DIVE uses the VSD/PDD to play back video, the MCD is unaware of the hardware; DIVE issues all of the VSD/PDD commands to control window placement and playback function.

User-Defined Video IOCtls

The video IOCtls listed in the following table are category 140 (user defined).

Function Number	Function	Description
60h	VCAI_INIINFO	Setup Information
61h	VCAI_SAVE	Save Device State
62h	VCAI_RESTORE	Restore Device State
63h	VCAI_LOAD_MICROCODE	Query/Load/Unload Microcode
64h	VCAI_RESTORE_FORMAT	Set/Query Image Restore Format
65h	VCAI_CAPTURE_FORMAT	Set/Query Image Capture Format
67h	VCAI_PLAY	Restore Image to the Device
68h	VCAI_QUERYVIDEOSIGNAL	Query Video Input Connector's Signal
69h	VCAI_TUNERCHANNEL	Set/Query Tuner Channel
6Ah	VCAI_VIDEOINPUT	Set/Query Video Input Source Connector
6Bh	VCAI_SETCAPTRECT	Set Source and Destination Capture Rectangles
6Ch	VCAI_GETIMAGESCALE	Get Image and Scale into RAM Buffer
6Dh	VCAI_GETDEVINFO	Get Device Information
6Eh	VCAI_VALIDRECT	Validate Video Rectangle
72h	VCAI_UNFREEZE	Unfreeze Image Digitizer
74h	VCAI_FREEZE	Freeze Image Digitizer
75h	VCAI_VIDEOADJ
76h	VCAI_SETFPS	Set Frame Rate for Streaming
79h	VCAI_USER	Device Specific Commands
80h	VCAI_SETMONITOR	Enable/Disable Overlay Monitor Function
81h	VCAI_EDCOLORKEY	Enable/Disable Transparent Color
82h	VCAI_SETCOLORKEY	Set Color Key/Transparent Color

Note: Functions 68h, 69h, 80h, 81h, and 82h provide support for overlay devices.

VCAI_INIINFO (60h) - Setup Information from INI file

This IOCtl provides the device driver with the data from the device driver's INI file. The name of this file is based on the device driver installation name. For example, the INI file for the first VCA adapter would be VIDVCI1.INI and the second would be VIDVCI2.INI. The VSD reads the INI file and passes information to the PDD as a part of the open processing. The PDDName is obtained from the digital-video device's "PDDNAME= " line in the MMPM2.INI file.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

The data packet parameter is a pointer to device-specific structure.

VCAI_SAVE (61h) - Save Device State

This IOCtl saves the current state of the video device. The video device can be shared among several processes that might gain or lose ownership of the device at any time. This IOCtl is issued when a process is about to lose ownership of the device and needs to save the state of the device before relinquishing ownership.

Description

This IOCtl saves the current state of the video device. The video device can be shared among several processes that might gain or lose ownership of the device at any time. This IOCtl is issued when a process is about to lose ownership of the device and needs to save the state of the device before relinquishing ownership.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Not used.

VCAI_RESTORE (62h) - Restore Device State

This IOCtl restores a previously saved state to the video capture device. This call is issued when a process that owned (but relinquished) the video device is regaining control of the device. The device is set to the state it was in the last time the process was active (save device state was issued), or if the device was not previously active, the device is set to the defaults.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Not used.

VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode

This IOCtl allows the device to be loaded with micro code, if needed. As soon as the current image format is set via VCAI_RESTORE_FORMAT and/or VCAI _CAPTURE_FORMAT, the device may require micro code to be loaded onto the card. The command allows the micro code's file name to be queried and the micro code to be loaded and later unloaded, if needed. The CODEC (Ring 3 code) will read in the file for the DD (Ring 0 code) because Ring 0 code cannot perform file I/O.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _VCALOAD {
  ULONG       ulflags;
  CHAR        ProdInfo[256];
  LONG        ulLoadID;
  ULONG       ulLength;
  PVOID       pLoadData;
} VCALOAD;

typedef   VCALOAD  FAR  * PVCALOAD;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCALOAD

VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format

This IOCtl is used to query the image formats supported by the device and to query the current image format. It may also be used to set the current image format.

Note:Image format (fourCC) refers to the type of data that will be passed to the device on the VCAI_PLAY IOCtl.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _VCAIMAGERF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGERF;

typedef   VCAIMAGERF   FAR   * PVCAIMAGERF;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCAIMAGERF

VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format

This IOCtl is used to query the devices supported image capture formats, query the current image capture format, and set the current image capture format. This image format will be returned on VCAI_GETIMAGESCALE and on the SHD_READ_COMPLETE flag (of the ulFlag parameter of the SHD_REPORTINT structure) through the IDC streaming interface.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _VCAIMAGECF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGECF;

typedef   VCAIMAGECF   FAR   * PVCAIMAGECF;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCAIMAGECF

VCAI_PLAY (67h) - Restore/Play Image to the Screen

This IOCtl is used to play back and restore images to a device. The format of the image data pointed to by pImageData is determined by the VCAI_ RESTORE_FORMAT IOCtl and the source and destination image size is determined by the VCAI_SETCAPTRECT If the device supports this command, the CanRestore flag in the VCADEVINFO structure should be set to 1.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCASTREAM {
  ULONG       ulLength;
  PVOID       pImageData;
  ULONG       ulFlags;
  ULONG       ulSCR;
  ULONG       ulPTS;
  ULONG       ulAudioTime;
} VCASTREAM;

typedef   VCASTREAM   FAR * PVCASTREAM;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASTREAM

VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal

This IOCtl is used to determine if the current video input connector has a valid video signal present. For example, this IOCtl could be used to help automatically detect which video input has a camera attached and turned on or whether or not the tuner is tuned to a valid channel.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Not used.

Returns

This IOCtl returns a status value equal to one of the following.

VCAERR_SIGNAL_LOCKED	10
VCAERR_SIGNAL_NOT_LOCKED	11
VCAERR_SIGNAL_INDETERMINATE	12

VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel

This IOCtl is used to change channel/frequency on the TV tuner or to query the correct tuner frequency. If the device support TV tuner functions, the HasTuner flag should be set to 1 in the VCADEVINFO structure.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCATUNCHAN {
  ULONG        ulFlags;
  ULONG        ulOptions;
  USHORT       usResv01;
  USHORT       usResv02;
  LONG         lFineTune;
  ULONG        ulFrequency;
} VCATUNCHAN;

typedef   VCATUNCHAN   FAR   * PVCATUNCHAN;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCATUNCHAN

Returns

The following status values are returned by VCAI_TUNERCHANNEL.

VCAERR_CHANNEL_TOO_LOW	6
VCAERR_CHANNEL_TOO_HIGH	7
VCAERR_CHANNEL_NO_TUNER	9

VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector

This IOCtl sets or queries the current video input source connector.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _VCASETVIDEOINPUT {
  ULONG       INPUT_CONNECTOR;
} VCASETVIDEOINPUT;

typedef   VCASETVIDEOINPUT   FAR   *   PVCASETVIDEOINPUT ;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETVIDEOINPUT

VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles

This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the DDCMD_READ message. The portion of the source image to be captured is determined by the size of the destination image.

This command does not start the capture. It specifies the source and destination. Streaming capture is started using the DDCMD_START flag of the ulCmd parameter of the DDCMDCONTROL structure.

The destination X_LEFT and Y_TOP are used only for overlay adapters to control where the overlay image is placed on the screen.

If the device is being used for play back instead of capture as discussed above, source refers to the size of the image that is to be restored and dest (destination) refers to where the image is to be placed. Instead of the DDCMD message discussed above, the image data is passed to the device driver via the VCAI_PLAY IOCtl.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _VCASETCAPTURERECT {
  ULONG       Source_X_Left;
  ULONG       Source_Y_Top;
  ULONG       Source_Y_Height;
  ULONG       Source_X_Width;
  ULONG       Dest_X_Left;
  ULONG       Dest_Y_Top;
  ULONG       Dest_Y_Height;
  ULONG       Dest_X_Width;
} VCASETCAPTURERECT;

typedef   VCASETCAPTURERECT   FAR * PVCASETCAPTURERECT;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETCAPTURERECT

VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer

This IOCtl is used to capture a single frame of data from the video capture device to a buffer provided by the calling application.

The video capture device has a capture frame buffer, which contains the current, full sized image captured (or digitized) by the device. The portion of the full sized image that is to be copied to the calling application's buffer is indicated by the source frame, which describes a window in the captured frame. The source frame can encompass part or all of the captured frame. The image data contained in the source frame dimensions are copied to a destination frame. The following figure illustrates this.

        0,0                       0,0
        +--------------------+    +--------------------+
        |   64               |    |                    |
   32   |  +-------------\   |    |                    |
        |  |Source   240 | --+--->|  Destination       |
        |  |             |   |    |                    |
        |  |   320       |   |    |                    |
        |  +-------------+   |    |                    |
        +--------------------+    +--------------------+
                    640,480                      160,120

  X-Left    32
  Y-Top     64
  X-Width  320
  Y-Height 240

If the destination frame is not the same size as the source frame, the source image is scaled down to fit into the destination frame. This allows the image to be reduced to fit in a specific window. It also allows for a change in the aspect ratio.

For better performance, this IOCtl does not validate that the source and destination frames are equal to or smaller than the full sized capture frame. The caller of this function must ensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use VCAI_GETDEVINFO to determine the maximum image extents.

Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCAGETIMAGESCALE {
  ULONG       Capture_Buf_Len;
  ULONG       Capture_Buf_Ptr;
  ULONG       Source_X_Left;
  ULONG       Source_Y_Top;
  ULONG       Source_Y_Height;
  ULONG       Source_X_Width;
  ULONG       Dest_X_Left;
  ULONG       Dest_Y_Top;
  ULONG       Dest_Y_Height;
  ULONG       Dest_X_Width;
} VCAGETIMAGESCALE;

typedef   VCAGETIMAGESCLAE   FAR * PVCAGETIMAGESCALE;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCAGETIMAGESCALE

Returns

If the video device driver can satisfy the request as specified, it returns 0 (VCAERR_SUCCESS). Otherwise, an error code is returned that indicates what caused the failure (VCAERR_INVALID_BUFFER, VCAERR_INVALID_RECT).

Remarks

This IOCtl captures one single video image per call. To perform streaming ( continuous, multiple image capturing), use the stream programming interface to create a stream and record from the video capture device.

Note: Most video device drivers do not support all the transposition and scaling possibilities supported with this IOCtl. Consult the specific device driver's documentation for limitations, or use VCAI_GETDEVINFO to determine its capabilities.

VCAI_GETDEVINFO (6Dh) - Get Device Information

This IOCtl returns device-specific information about a video capture device. The information returned is the default state of the device. It does not reflect changes that might have been made to the defaults since initialization.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct _vcadevinfo {
  ULONG        Length;
  CHAR         ProdInfo[30];
  CHAR         ManInfo[30];
  CHAR         Version[10];
  ULONG        ImgFormat;
  USHORT       BitsPerPEL;
  USHORT       Overlay;
  ULONG        Brightness;
  ULONG        hue;
  ULONG        saturation;
  ULONG        contrast;
  ULONG        Sharpness;
  ULONG        unused1;
  ULONG        S_X_Left;
  ULONG        S_Y_Top;
  ULONG        S_Y_Height;
  ULONG        S_X_Width;
  ULONG        D_X_Left;
  ULONG        D_Y_Top;
  ULONG        D_Y_Height;
  ULONG        D_X_Width;
  ULONG        D_ScaleFactor;
  ULONG        S_X_MAX;
  ULONG        S_Y_MAX;
  ULONG        D_X_MAX;
  ULONG        D_Y_MAX;
  ULONG        O_X_MAX;
  ULONG        O_Y_MAX;
  USHORT       VideoInputs;
  USHORT       CanRestore;
  USHORT       CanStretch;
  USHORT       CanDistort;
  USHORT       HasVolume;
  USHORT       HasBalance;
  USHORT       CanScale;
  USHORT       CanStream;
  ULONG        DI_ulFilenum;
  BYTE         HasTuner;
  BYTE         HasTeleTex;
  LONG         Delay_Time;
  BYTE         HasAFC;
  BYTE         HasPolarization;
} VCADEVINFO;

typedef   VCADEVINFO   FAR * PVCADEVINFO;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCADEVINFO

VCAI_VALIDRECT (6Eh) - Validate Video Rectangle

This IOCtl modifies the source X_Width and source Y_Height to a valid size determined by the destination rectangle information. This IOCtl compensates for video capture adapters that do not support scaling images from a given source destination rectangle. The media control driver uses this information to center the source rectangle on the area in the original source rectangle.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCACAPISIZE {
  ULONG       X_Left;
  ULONG       Y_Top;
  ULONG       Y_Height;
  ULONG       X_Width;
  ULONG       ScaleFactor;
} VCACAPISIZE;

typedef   VCACAPISIZE   FAR * PVCACAPISIZE ;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCACAPISIZE

VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer

This IOCtl tells the video device to continuously digitize the incoming video source.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Not used.

VCAI_FREEZE (74h) - Freeze the Image Digitizer

This IOCtl tells the video device to freeze the current digitized image. This freezes the capture card digitizer to produce a stable image. However, it is typically very slow because the device might have to wait for one or more video field times to pass to make sure the digitizer has come to a complete stop.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Not used.

VCAI_VIDEOADJ (75h) - Set/Query Video Adjustments

This IOCtl allows the caller to set and query the value of attributes controlling the behavior (and thus the image) of the video device. Typical video image adjustments, such as those found on television sets, including brightness, contrast, and hue, can be queried and set with this call.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCASETVIDEO {
  ULONG       set_brightness;
  ULONG       set_hue;
  ULONG       set_saturation;
  ULONG       set_contrast;
  ULONG       ret_brightness;
  ULONG       ret_hue;
  ULONG       ret_saturation;
  ULONG       ret_contrast;
} VCASETVIDEO;

typedef   VCASETVIDEO   FAR * PVCASETVIDEO;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETVIDEO

Remarks

When setting a value, put the value desired (in the range of 0 to 255) into the value's field. If resetting the value to the defaults, put DEFAULT into the value's field. If no change is desired for a particular value, put NO_ CHANGE in the value's field. The call always returns the current value or NOT_SUPPORTED for each setting after the value has been updated.

VCAI_SETFPS (76h) - Set Frame Rate for Streaming

This IOCtl allows the caller to set the framerate, in frames per second or in microseconds per frame, that the device driver will use to capture images from the device. This call does not initiate video capture, it only sets the frame rate. The frame rate cannot

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCASETFPS {
  ULONG       set_FPS;
  ULONG       ulFlags;
} VCASETFPS;

typedef   VCASETFPS   FAR * PVCASETFPS;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETFPS

VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver

This IOCtl is the result of a MCI_DEV_ESCAPE COMMAND. It allows an application to pass device-specific commands to the device driver. This will allow for new commands specific to a device to be supported without impact to the MCD/MCI.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Data Packet Format

Application Dependent.

VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor

This IOCtl enables or disables display of live video on the display device.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCASETMONITOR {
  BOOL       bMonitor;
} VCASETMONITOR;

typedef   VCASETMONITOR   FAR   *   PVCASETMONITOR ;

VCAI_SETMONITOR (80h) - Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETMONITOR

VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color

This IOCtl enables video to show through a specific color determined by the transparent-color key when the overlay monitor is enabled. If color keying is not enabled and the monitor is enabled, video will show through even if the transparent color is not present.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCAEDCOLORKEY {
  BOOL       bColorKeying;
} VCAEDCOLORKEY;

typedef   VCAEDCOLORKEY   FAR * PVCAEDCOLORKEY;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCAEDCOLORKEY

VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color

This IOCtl sets the colors that video replaces when color keying is enabled and the monitor is enabled.

Parameter Packet Format

Not used. The packet pointer must be NULL.

Pointer to structure

Pointer to structure The data packet parameter is a pointer to the following structure.

typedef struct _VCASETCOLORKEY {
  ULONG       ulColorKey;
} VCASETCOLORKEY;

typedef   VCASETCOLORKEY   FAR * PVCASETCOLORKEY;

Data Packet Format

Field	C Datatype
Pointer to structure	PVCASETCOLORKEY

MMPM/2 Device Driver Reference:IOCtl Functions

Contents

Audio IOCtl Functions

AUDIO_INIT (40h) - Initialize Audio Device Driver

AUDIO_STATUS (41h) - Obtain Status of Audio Hardware

AUDIO_CONTROL (42h) - Control Audio Adapter

AUDIO_BUFFER (43h) - Determine Buffer Status

AUDIO_LOAD (44h) - Load DSP Code

AUDIO_WAIT (45h) - Suspend program operation

AUDIO_HPI (46h) - Access high-performance interface

AUDIO_UPDATE (47h) - Update Buffer Information

AUDIO_CAPABILITY (48h) - Determine If a Group of Audio Settings is Supported

Resource Classes and Resource Units

Mixer IOCtl Functions Introduction

MIX_GETCONNECTIONS (60h) - Determine if Line is Enabled

MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line

MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line

MIX_GETCONTROL (63h) - Get Current State of a Line

MIX_SETCONTROL (64h) - Set State of a Mixer Line

IOCtl Examples

M-Audio MCI_AUDIO_INIT Parameters

Video IOCtl Functions

Capture

Playback

User-Defined Video IOCtls

VCAI_INIINFO (60h) - Setup Information from INI file

VCAI_SAVE (61h) - Save Device State

VCAI_RESTORE (62h) - Restore Device State

VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode

VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format

VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format

VCAI_PLAY (67h) - Restore/Play Image to the Screen

VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal

VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel

VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector

VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles

VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer

VCAI_GETDEVINFO (6Dh) - Get Device Information

VCAI_VALIDRECT (6Eh) - Validate Video Rectangle

VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer

VCAI_FREEZE (74h) - Freeze the Image Digitizer

VCAI_VIDEOADJ (75h) - Set/Query Video Adjustments

VCAI_SETFPS (76h) - Set Frame Rate for Streaming

VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver

VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor

VCAI_SETMONITOR (80h) - Data Packet Format

VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color

VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color

Navigation menu

Search