View source for MMPM/2 Device Driver Reference:IOCtl Functions

{{MMPM2DDRef}}
{{IBM-Reprint}}

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):
{|class="wikitable"
!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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_STATUS|MCI_AUDIO_STATUS]] structure. The [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_CHANGE|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.
<pre>
typedef struct _MCI_AUDIO_CONTROL {
  USHORT       usIOCtlRequest;
  VOID        *pbRequestInfo;
  ULONG        ulPosition;
  SHORT        sReturnCode;
} MCI_AUDIO_CONTROL;

typedef   MCI_AUDIO_CONTROL  FAR * LPMCI_AUDIO_CONTROL
</pre>

;Data Packet Format:
{| class="wikitable"
!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|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.
<pre>
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;
</pre>

;Data Packet Format:
{| class="wikitable"
!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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|MCI_AUDIO_INIT]] structure on an [[#AUDIO_INIT|AUDIO_INIT]] request, the application must load the DSP code (specified by the device driver in the ''abLoadPath'' field of [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|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.
<pre>
typedef struct _load {
  CHAR FAR      *pbBuffer;
  ULONG          ulSize;
  ULONG          ulFlags;
} MCI_AUDIO_LOAD;

typedef   MCI_AUDIO_LOAD FAR * LPMCI_AUDIO_LOAD;
</pre>

;Data Packet Format:
{| class="wikitable"
!Field||C Datatype
|-
|Pointer to structure||LPMCI_AUDIO_LOAD
|}

;Remarks:The ''pbBuffer'' field of the [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_LOAD|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|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.
<pre>
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;
</pre>

;Data Packet Format:
{| class="wikitable"
!Field||C Datatype
|-
|Pointer to structure||LPMCI_AUDIO_HPI
|}

;Returns:An address is returned in ''pvEntry ()'' in the [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_HPI|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_IOBUFFER|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|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.
<pre>
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;
</pre>

;Data Packet Format:
{| class="wikitable"
!Field||C Datatype
|-
|Pointer to structure||UPDATE
|}

;Returns:On exit, ''rc'' of the [[#AUDIO_UPDATE|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|AUDIO_HPI]] calls the device driver, an [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_IOBUFFER|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_IOBUFFER|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|AUDIO_ HPI]] must be called again if this number changes.

When AUDIO_UPDATE is called, it removes all buffers in the current [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_IOBUFFER|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_IOBUFFER|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.
<pre>
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;
</pre>

;Data Packet Format:
{| class="wikitable"
!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.
<pre>
  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
</pre>

;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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_CAPS|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_CAPS|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 [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_CAPS|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.
<pre>
 +------------------------------------+
 |                                    |
 |    Sources          Sinks          |
 | +--------------------------------+ |
 | |               |                | |
 | |   Synth       |   Line Out     | |
 | |               |                | |
 | |   Line In     |   Speaker Out  | |
 | |               |                | |
 | |   Wave Data   |   Head Phones  | |
 | |               |                | |
 | |   Internal    |   Generic Out  | |
 | |   Audio       |                | |
 | |               |   Wave         | |
 | |   Microphone  |                | |
 | |               |   NULL         | |
 | |   PC Speaker  |                | |
 | |               |                | |
 | +--------------------------------+ |
 +------------------------------------+
</pre>
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_GETCONNECTIONS]]
*[[#MIX_SETCONNECTIONS|MIX_SETCONNECTIONS]]
*[[#MIX_GETLINEINFO|MIX_GETLINEINFO]]
*[[#MIX_GETCONTROL|MIX_GETCONTROL]]
*[[#MIX_SETCONTROL|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.
<pre>
typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS;
</pre>
The caller is responsible for filling in the ''ulLine'' field of the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|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
{| class="wikitable"
!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.
<pre>
   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);
</pre>

<div id="MIX_SETCONNECTIONS">

===MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line===
</div>
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.
<pre>
typedef struct _LINECONNECTIONS {
  ULONG       ulLength;
  ULONG       ulConnections;
  ULONG       ulLine;
} LINECONNECTIONS;

typedef   LINECONNECTIONS   FAR   * PLINECONNECTIONS;
</pre>
The caller is responsible for filling in the ''ulLine'' and ''ulConnections'' fields of the [[MMPM/2 Device Driver Reference:Data Types#LINECONNECTIONS|LINECONNECTIONS]] structure.

;Data Packet Format
{| class="wikitable"
!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.
<pre>
 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);
</pre>
<div id="MIX_GETLINEINFO">

===MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line===
</div>
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.
<pre>
typedef struct _MIXERLINEINFO {
  ULONG       ulLength;
  ULONG       ulNumChannels;
  ULONG       ulSupport;
  ULONG       ulConnectionsPossible;
  ULONG       ulLine;
} MIXERLINEINFO;

typedef   MIXERLINEINFO   FAR   * PMIXERLINEINFO;
</pre>
The caller is responsible for filling in the ''ulLine'' field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERLINEINFO|MIXERLINEINFO]] structure.

;Data Packet Format
{| class="wikitable"
!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.
<pre>
   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);
</pre>
<div id="MIX_GETCONTROL">

===MIX_GETCONTROL (63h) - Get Current State of a Line===
</div>
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.
<pre>
typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR  * PMIXERCONTROL;
</pre>
The caller is responsible for filling in the ''ulLine''field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|MIXERCONTROL]] structure.

The device driver should return the current setting of the line in the ''ulSetting'' field of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|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
{| class="wikitable"
!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.
<pre>
   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);
</pre>

<div id="MIX_SETCONTROL">

===MIX_SETCONTROL (64h) - Set State of a Mixer Line===
</div>
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.
<pre>
typedef struct _MIXERCONTROL {
  ULONG       ulLength;
  ULONG       ulLine;
  ULONG       ulControl;
  ULONG       ulSetting;
} MIXERCONTROL;

typedef   MIXERCONTROL   FAR  * PMIXERCONTROL;
</pre>
The caller is responsible for filling in the ''ulControl'', the ''ulLine'', and the ''ulSetting'', fields of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|MIXERCONTROL]].

The device driver should return the current setting of the line in ''ulSetting'' of the [[MMPM/2 Device Driver Reference:Data Types#MIXERCONTROL|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
{| class="wikitable"
!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.
<pre>
   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);
</pre>

=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.
<pre>
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.
</pre>
Under OS/2, IOCtls are called using the DosDevIOCtl function. The following example is an OS/2 [[#AUDIO_INIT|AUDIO_INIT]]example.
<pre>
#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);
}
</pre>
Under DOS, IOCtls are called by using INT 21h Function 44h. The following is a DOS IOCtl example.
<pre>
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
     .
     .
     .
</pre>

==M-Audio MCI_AUDIO_INIT Parameters==
The following table lists the [[MMPM/2 Device Driver Reference:Data Types#MCI_AUDIO_INIT|MCI_AUDIO_INIT]] parameters for the operating modes currently supported by the IBM M-Audio Capture and Playback Adapter.
{| class="wikitable"
!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 ''moving''images 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).
{|class="wikitable"
!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||Set/Query Video Adjustments|
|-
|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.

<div id="VCAI_INIINFO">
==VCAI_INIINFO (60h) - Setup Information from INI file==
</div>
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.

<div id="VCAI_SAVE">
==VCAI_SAVE (61h) - Save Device State==
</div>
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.

<div id="VCAI_RESTORE">
==VCAI_RESTORE (62h) - Restore Device State==
</div>
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.

<div id="VCAI_LOAD_MICROCODE">
==VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode==
</div>
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|VCAI_RESTORE_FORMAT]] and/or [[#VCAI _CAPTURE_FORMAT|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.
<pre>
typedef struct _VCALOAD {
  ULONG       ulflags;
  CHAR        ProdInfo[256];
  LONG        ulLoadID;
  ULONG       ulLength;
  PVOID       pLoadData;
} VCALOAD;

typedef   VCALOAD  FAR  * PVCALOAD;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure||PVCALOAD
|}

<div id="VCAI_RESTORE_FORMAT">
==VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format==
</div>
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|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.
<pre>
typedef struct _VCAIMAGERF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGERF;

typedef   VCAIMAGERF   FAR   * PVCAIMAGERF;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCAIMAGERF
|}

<div id="VCAI_CAPTURE_FORMAT">
==VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format==
</div>
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|VCAI_GETIMAGESCALE]] and on the SHD_READ_COMPLETE flag (of the ''ulFlag'' parameter of the [[MMPM/2 Device Driver Reference:Data Types#SHD_REPORTINT|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.
<pre>
typedef struct _VCAIMAGECF {
  ULONG       ulFlags;
  ULONG       ulNumFormats;
  ULONG       ulCurIndex;
  ULONG       FourCC[64];
} VCAIMAGECF;

typedef   VCAIMAGECF   FAR   * PVCAIMAGECF;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure || PVCAIMAGECF
|}

<div id="VCAI_PLAY">
==VCAI_PLAY (67h) - Restore/Play Image to the Screen==
</div>
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|VCAI_ RESTORE_FORMAT]] IOCtl and the source and destination image size is determined by the [[#VCAI_SETCAPTRECT|VCAI_SETCAPTRECT]] If the device supports this command, the ''CanRestore'' flag in the [[MMPM/2 Device Driver Reference:Data Types#VCADEVINFO|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.
<pre>
typedef struct _VCASTREAM {
  ULONG       ulLength;
  PVOID       pImageData;
  ULONG       ulFlags;
  ULONG       ulSCR;
  ULONG       ulPTS;
  ULONG       ulAudioTime;
} VCASTREAM;

typedef   VCASTREAM   FAR * PVCASTREAM;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCASTREAM
|}

<div id="VCAI_QUERYVIDEOSIGNAL">
==VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal==
</div>
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
|}

<div id="VCAI_TUNERCHANNEL">
==VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel==
</div>
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 [[MMPM/2 Device Driver Reference:Data Types#VCADEVINFO|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.
<pre>
typedef struct _VCATUNCHAN {
  ULONG        ulFlags;
  ULONG        ulOptions;
  USHORT       usResv01;
  USHORT       usResv02;
  LONG         lFineTune;
  ULONG        ulFrequency;
} VCATUNCHAN;

typedef   VCATUNCHAN   FAR   * PVCATUNCHAN;
</pre>

;Data Packet Format
{|class="wikitable"
!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
|}

<div id="VCAI_VIDEOINPUT">
==VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector==
</div>
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.
<pre>
typedef struct _VCASETVIDEOINPUT {
  ULONG       INPUT_CONNECTOR;
} VCASETVIDEOINPUT;

typedef   VCASETVIDEOINPUT   FAR   *   PVCASETVIDEOINPUT ;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCASETVIDEOINPUT
|}
<div id="VCAI_SETCAPTRECT">
== VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles ==
</div>
This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the [[MMPM/2 Device Driver Reference:DDCMD Messages#DDCMD_READ|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 [[MMPM/2 Device Driver Reference:Data Types#DDCMDCONTROL|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|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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure || PVCASETCAPTURERECT
|}

<div id="VCAI_GETIMAGESCALE">
== VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer ==
</div>
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.
<pre>
        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
</pre>
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|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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!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|VCAI_GETDEVINFO]] to determine its capabilities.

<div id="VCAI_GETDEVINFO">
== VCAI_GETDEVINFO (6Dh) - Get Device Information ==
</div>
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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCADEVINFO 
|}

<div id="VCAI_VALIDRECT">
== VCAI_VALIDRECT (6Eh) - Validate Video Rectangle ==
</div>
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.
<pre>
typedef struct _VCACAPISIZE {
  ULONG       X_Left;
  ULONG       Y_Top;
  ULONG       Y_Height;
  ULONG       X_Width;
  ULONG       ScaleFactor;
} VCACAPISIZE;

typedef   VCACAPISIZE   FAR * PVCACAPISIZE ;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCACAPISIZE
|}

<div id="VCAI_UNFREEZE">
== VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer ==
</div>
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.

<div id="VCAI_FREEZE">
==VCAI_FREEZE (74h) - Freeze the Image Digitizer==
</div>
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.
<pre>
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;
</pre>

;Data Packet Format
{|class="wikitable"
!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.

<div id="VCAI_SETFPS">
==VCAI_SETFPS (76h) - Set Frame Rate for Streaming==
</div>
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.
<pre>
typedef struct _VCASETFPS {
  ULONG       set_FPS;
  ULONG       ulFlags;
} VCASETFPS;

typedef   VCASETFPS   FAR * PVCASETFPS;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCASETFPS
|}

<div id="VCAI_USER">
==VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver==
</div>
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.

<div id="VCAI_SETMONITOR">
==VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor==
</div>
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.
<pre>
typedef struct _VCASETMONITOR {
  BOOL       bMonitor;
} VCASETMONITOR;

typedef   VCASETMONITOR   FAR   *   PVCASETMONITOR ;
</pre>

=== VCAI_SETMONITOR (80h) - Data Packet Format ===
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCASETMONITOR
|}

<div id="VCAI_EDCOLORKEY">
==VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color==
</div>
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.
<pre>
typedef struct _VCAEDCOLORKEY {
  BOOL       bColorKeying;
} VCAEDCOLORKEY;

typedef   VCAEDCOLORKEY   FAR * PVCAEDCOLORKEY;
</pre>

;Data Packet Format
{|class="wikitable"
!Field !!C Datatype
|-
|Pointer to structure ||PVCAEDCOLORKEY
|}

<div id="VCAI_SETCOLORKEY">
==VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color==
</div>
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.
<pre>
typedef struct _VCASETCOLORKEY {
  ULONG       ulColorKey;
} VCASETCOLORKEY;

typedef   VCASETCOLORKEY   FAR * PVCASETCOLORKEY;
</pre>

;Data Packet Format
{|class="wikitable"
!Field||C Datatype
|-
|Pointer to structure ||PVCASETCOLORKEY
|}

[[Category:MMPM/2 Device Driver Reference]]