MMPM/2 Device Driver Reference:IOCtl Functions

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):
 * 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.

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;
 * Parameter Packet Format:Not used. The packet pointer must be NULL.
 * Pointer to structure:

typedef  MCI_AUDIO_INIT   FAR  *LPMCI_AUDIO_INIT;


 * Data Packet Format


 * 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.

typedef struct _stat { LONG                  lSRate; LONG                  lBitsPerSRate; LONG                  lBsize; SHORT                 sMode; SHORT                 sChannels; ULONG                 ulFlags; ULONG                 ulOperation; MCI_AUDIO_CHANGE      rAudioChange; } MCI_AUDIO_STATUS;
 * Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef  MCI_AUDIO_STATUS   FAR * LPMCI_AUDIO_STATUS;


 * Data Packet Format


 * 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.

typedef struct _MCI_AUDIO_CONTROL { USHORT      usIOCtlRequest; VOID       *pbRequestInfo; ULONG       ulPosition; SHORT       sReturnCode; } MCI_AUDIO_CONTROL;
 * 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  MCI_AUDIO_CONTROL  FAR * LPMCI_AUDIO_CONTROL


 * Data Packet Format:


 * 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.

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;
 * Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef  MCI_AUDIO_BUFFER FAR * LPMCI_AUDIO_BUFFER;


 * Data Packet Format:


 * 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.

typedef struct _load { CHAR FAR     *pbBuffer; ULONG         ulSize; ULONG         ulFlags; } MCI_AUDIO_LOAD;
 * Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef  MCI_AUDIO_LOAD FAR * LPMCI_AUDIO_LOAD;


 * Data Packet Format:


 * 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.

typedef struct _hpi { VOID FAR                 *pvEntry ; VOID FAR                 *pvCallBack ; LPMCI_AUDIO_IOBUFFER      prXBuff; LPMCI_AUDIO_IOBUFFER      prRBuff; USHORT                    usFlags; } MCI_AUDIO_HPI;
 * Pointer to structure:Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef  MCI_AUDIO_HPI FAR * LPMCI_AUDIO_HPI;


 * Data Packet Format:


 * 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.

typedef struct _audio_update { CHAR          iobuf_type; CHAR FAR     *buffer_address; ULONG         buffer_length; USHORT        rc; void FAR     *reserved; } audio_update;
 * Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef struct audio_update FAR * UPDATE;


 * Data Packet Format:


 * 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.

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;
 * Pointer to structure: Pointer to structure The data packet parameter is a pointer to the following data structure.

typedef MCI_AUDIO_CAPS FAR * PAUDIO_CAPS;


 * Data Packet Format:


 * Returns:
 * SUPPORT_SUCCESS
 * UNSUPPORTED_RATE
 * UNSUPPORTED_CHANNELS
 * UNSUPPORTED_BPS
 * UNSUPPORTED_DATATYPE
 * UNSUPPORTED_OPERATION

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;
 * Example Code

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.

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

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;
 * Pointer to structure

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


 * 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.

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);
 * Example Code



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.

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

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;
 * Pointer to structure

typedef  LINECONNECTIONS   FAR   * PLINECONNECTIONS; The caller is responsible for filling in the ulLine and ulConnections fields of the LINECONNECTIONS structure.


 * Data Packet Format


 * 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.

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); 
 * Example Code

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.

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

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;
 * Pointer to structure

typedef  MIXERLINEINFO   FAR   * PMIXERLINEINFO; The caller is responsible for filling in the ulLine field of the MIXERLINEINFO structure.


 * Data Packet Format


 * 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.

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); 
 * Example Code

MIX_GETCONTROL (63h) - Get Current State of a Line
This IOCtl enables an application to get the current state of a particular line.

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

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;
 * Pointer to structure

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


 * 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.

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);
 * Example Code



MIX_SETCONTROL (64h) - Set State of a Mixer Line
This IOCtl enables an application to set the current state of a particular line.

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

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;
 * Pointer to structure

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


 * 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.

The following code illustrates how to use MIX_GETCONNECTIONS. HMIXER  hMix; MIXERCONTROL       MixerControl;
 * Example Code

/* 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.
 * 1) define  INCL_DOSDEVICES


 * 1) include 
 * 2) include 
 * 3) include                  /* 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.

=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). 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.

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

The data packet parameter is a pointer to device-specific structure.
 * Data Packet Format



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.

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

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

Not used.
 * Data Packet Format



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.

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

Not used.
 * Data Packet Format



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.

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

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;
 * Pointer to structure

typedef  VCALOAD  FAR  * PVCALOAD;


 * Data Packet Format



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.

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

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;
 * Pointer to structure

typedef  VCAIMAGERF   FAR   * PVCAIMAGERF;


 * Data Packet Format



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.

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

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;
 * Pointer to structure

typedef  VCAIMAGECF   FAR   * PVCAIMAGECF;


 * Data Packet Format



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.

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

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;
 * Pointer to structure

typedef  VCASTREAM   FAR * PVCASTREAM;


 * Data Packet Format



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.

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

Not used.
 * Data Packet Format

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



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.

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

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;
 * Pointer to structure

typedef  VCATUNCHAN   FAR   * PVCATUNCHAN;


 * Data Packet Format

The following status values are returned by VCAI_TUNERCHANNEL.
 * Returns

<div id="VCAI_VIDEOINPUT">

VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector
This IOCtl sets or queries the current video input source connector.

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

Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _VCASETVIDEOINPUT { ULONG      INPUT_CONNECTOR; } VCASETVIDEOINPUT;
 * Pointer to structure

typedef  VCASETVIDEOINPUT   FAR   *   PVCASETVIDEOINPUT ;

<div id="VCAI_SETCAPTRECT">
 * Data Packet Format

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.

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

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;
 * Pointer to structure

typedef  VCASETCAPTURERECT   FAR * PVCASETCAPTURERECT;


 * Data Packet Format

<div id="VCAI_GETIMAGESCALE">

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.

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

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;
 * Pointer to structure

typedef  VCAGETIMAGESCLAE   FAR * PVCAGETIMAGESCALE;


 * Data Packet Format

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).
 * Returns

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.
 * Remarks

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.

<div id="VCAI_GETDEVINFO">

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.

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

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;
 * Pointer to structure

typedef  VCADEVINFO   FAR * PVCADEVINFO;


 * Data Packet Format

<div id="VCAI_VALIDRECT">

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.

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

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;
 * Pointer to structure

typedef  VCACAPISIZE   FAR * PVCACAPISIZE ;


 * Data Packet Format

<div id="VCAI_UNFREEZE">

VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer
This IOCtl tells the video device to continuously digitize the incoming video source.

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

Not used.
 * Data Packet Format

<div id="VCAI_FREEZE">

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.

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

Not used.
 * Data Packet Format

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.

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

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;
 * Pointer to structure

typedef  VCASETVIDEO   FAR * PVCASETVIDEO;


 * Data Packet Format

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.
 * Remarks

<div id="VCAI_SETFPS">

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

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

Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETFPS { ULONG      set_FPS; ULONG      ulFlags; } VCASETFPS;
 * Pointer to structure

typedef  VCASETFPS   FAR * PVCASETFPS;


 * Data Packet Format

<div id="VCAI_USER">

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.

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

Application Dependent.
 * Data Packet Format

<div id="VCAI_SETMONITOR">

VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor
This IOCtl enables or disables display of live video on the display device.

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

Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETMONITOR { BOOL      bMonitor; } VCASETMONITOR;
 * Pointer to structure

typedef  VCASETMONITOR   FAR   *   PVCASETMONITOR ;

VCAI_SETMONITOR (80h) - Data Packet Format
<div id="VCAI_EDCOLORKEY">

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.

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

Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCAEDCOLORKEY { BOOL      bColorKeying; } VCAEDCOLORKEY;
 * Pointer to structure

typedef  VCAEDCOLORKEY   FAR * PVCAEDCOLORKEY;


 * Data Packet Format

<div id="VCAI_SETCOLORKEY">

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.

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

Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETCOLORKEY { ULONG      ulColorKey; } VCASETCOLORKEY;
 * Pointer to structure

typedef  VCASETCOLORKEY   FAR * PVCASETCOLORKEY;


 * Data Packet Format