MMPM/2 Device Driver Reference:IOCtl Functions
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 packetand the data packet. For audio IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used.
The audio IOCtls listed in the following table are category 80h (user defined):
/-----------------------------------------------------------------\ |Function No. |Function |Description | |--------------+---------------------+----------------------------| |40h |AUDIO_INIT |Initialize audio device | | | |driver. | |--------------+---------------------+----------------------------| |41h |AUDIO_STATUS |Obtain status of audio | | | |hardware. | |--------------+---------------------+----------------------------| |42h |AUDIO_CONTROL |Control audio adapter. | |--------------+---------------------+----------------------------| |43h |AUDIO_BUFFER |Determine buffer status. | |--------------+---------------------+----------------------------| |44h |AUDIO_LOAD |Load DSP code. | |--------------+---------------------+----------------------------| |45h |AUDIO_WAIT |Suspend program operation. | |--------------+---------------------+----------------------------| |46h |AUDIO_HPI |Access high-performance | | | |interface. | |--------------+---------------------+----------------------------| |47h |AUDIO_UPDATE |Update buffer information. | |--------------+---------------------+----------------------------| |48H |AUDIO_CAPABILITY |Determine supported audio | | | |settings. | |--------------+---------------------+----------------------------| |52H | |reserved | |--------------+---------------------+----------------------------| |53H | |reserved | |--------------+---------------------+----------------------------| |54H | |reserved | |--------------+---------------------+----------------------------| |55H | |reserved | |--------------+---------------------+----------------------------| |60H |MIX_GETCONNECTIONS |Determine if line is | | | |enabled. | |--------------+---------------------+----------------------------| |61H |MIX_SETCONNECTIONS |Enable a line to the | | | |Record/monitor circuitry. | |------------- + --------------------+----------------------------| |62H |MIX_GETLINEINFO |Determine line capabilities.| |--------------+---------------------+----------------------------| |63H |MIX_GETCONTROL |Get current state of a line.| |--------------+---------------------+----------------------------| |64H |MIX_SETCONTROL |Set current state of a line.| \-----------------------------------------------------------------/
Note: This chapter documents AudioDD IOCTLs that could be sent to MMPM/2 device drivers.
To support MMPM/2 the following IOCTLs are necessary:
- AUDIO_INIT
- Required for all MMPM/2 device drivers.
- AUDIO_CONTROL
- Required for all MMPM/2 device drivers.
- AUDIO_LOAD
- Optional, used to load DSP tasks.
- MIXDM_GETCONNECTIONS
- Enhanced mixing IOCTLs (new)
- MIXDM_SETCONNECTIONS
- MIXDM_GETLINEONFO
- MIXDM_GETCONTROL
- MIXDM_SETCONTROL
- AUDIO_CAPABILITY
- Used to simplify install (new)
The remaining IOCtls documented in this chapter are provided as reference for device driver writers who wish to support AudioDD knowledgeable applications. These applications include IBM Linkway Live and early versions of IBM AVC (Audio Visual Connection).
AUDIO_INIT (40h) - Initialize Audio Device Driver
This IOCtl enables an application to tell the audio device driver which operation and audio type to use. It does this by initializing the appropriate MCI_AUDIO_INIT fields to the desired values and calling AUDIO_ INIT.
AUDIO_INIT (40h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_INIT (40h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _init {
LONG lSRate;
LONG lBitsPerSRate;
LONG lBsize;
SHORT sMode;
SHORT sChannels;
LONG lResolution;
CHAR abLoadPath[LOAD_PATH];
ULONG ulFlags;
ULONG ulOperation;
SHORT sReturnCode;
SHORT sSlotNumber;
SHORT sDeviceID;
VOID FAR *pvReserved;
ULONG ulVersionLevel;
} MCI_AUDIO_INIT;
typedef MCI _ AUDIO _ INIT FAR * LPMCI _ AUDIO _ INIT ;
AUDIO_INIT (40h) - Data Packet Format
/---------------------------------------------\ |Field C Datatype | |---------------------------------------------| |Pointer to structure LPMCI_AUDIO_INIT | \---------------------------------------------/
AUDIO_INIT (40h) - 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.
AUDIO_INIT (40h) - 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 ulFlagsof 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 ulFlagsand 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.
AUDIO_STATUS (41h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_STATUS (41h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _stat {
LONG lSRate;
LONG lBitsPerSRate;
LONG lBsize;
SHORT sMode;
SHORT sChannels;
ULONG ulFlags;
ULONG ulOperation;
MCI_AUDIO_CHANGE rAudioChange;
} MCI_AUDIO_STATUS;
typedef MCI _ AUDIO _ STATUS FAR * LPMCI _ AUDIO _ STATUS ;
AUDIO_STATUS (41h) - Data Packet Format
/-----------------------------------------------\ |Field C Datatype | |-----------------------------------------------| |Pointer to structure LPMCI_AUDIO_STATUS | \-----------------------------------------------/
AUDIO_STATUS (41h) - 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 usIOCtlRequestvalues:
- 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.
AUDIO_CONTROL (42h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_CONTROL (42h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _MCI_AUDIO_CONTROL {
USHORT usIOCtlRequest;
VOID *pbRequestInfo;
ULONG ulPosition;
SHORT sReturnCode;
} MCI_AUDIO_CONTROL;
typedef MCI _ AUDIO _ CONTROL FAR * LPMCI _ AUDIO _ CONTROL
AUDIO_CONTROL (42h) - Data Packet Format
/------------------------------------------------\ |Field C Datatype | |------------------------------------------------| |Pointer to structure LPMCI_AUDIO_CONTROL | \------------------------------------------------/
AUDIO_CONTROL (42h) - 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.
AUDIO_CONTROL (42h) - Remarks
The K12 version does not support ulPositionvalues 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.
AUDIO_BUFFER (43h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_BUFFER (43h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _buffer {
ULONG ulFlags;
ULONG ulReadBufSize;
ULONG ulWriteBufSize;
ULONG ulReadBufTime;
ULONG ulWriteBufTime;
ULONG ulReadBufMax;
ULONG ulWriteBufMax;
ULONG ulPosition;
ULONG ulPositionType;
LONG lReadBufCap;
LONG lWriteBufCap;
LONG lRequestBufCap;
} MCI_AUDIO_BUFFER;
typedef MCI _ AUDIO _ BUFFER FAR * LPMCI _ AUDIO _ BUFFER ;
AUDIO_BUFFER (43h) - Data Packet Format
/-----------------------------------------------\ |Field C Datatype | |-----------------------------------------------| |Pointer to structure LPMCI_AUDIO_BUFFER | \-----------------------------------------------/
AUDIO_BUFFER (43h) - 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 Referencefor more information on the return code for DosDevIOCtl.
AUDIO_BUFFER (43h) - 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 ulFlagsfield of the MCI_AUDIO_INIT structure on an AUDIO_INITrequest, 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.
AUDIO_LOAD (44h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_LOAD (44h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _load {
CHAR FAR *pbBuffer;
ULONG ulSize;
ULONG ulFlags;
} MCI_AUDIO_LOAD;
typedef MCI _ AUDIO _ LOAD FAR * LPMCI _ AUDIO _ LOAD ;
AUDIO_LOAD (44h) - Data Packet Format
/---------------------------------------------\ |Field C Datatype | |---------------------------------------------| |Pointer to structure LPMCI_AUDIO_LOAD | \---------------------------------------------/
AUDIO_LOAD (44h) - 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.
AUDIO_WAIT (45h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_WAIT (45h) - Data Packet Format
There are no parameters for AUDIO_WAIT. The packet pointer must be NULL.
AUDIO_WAIT (45h) - Returns
Refer to the OS/2 Control Program Guide and Reference for a description of the return code for DosDevIOCtl.
AUDIO_WAIT (45h) - 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.
AUDIO_HPI (46h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_HPI (46h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _hpi {
VOID FAR *pvEntry ();
VOID FAR *pvCallBack ();
LPMCI_AUDIO_IOBUFFER prXBuff;
LPMCI_AUDIO_IOBUFFER prRBuff;
USHORT usFlags;
} MCI_AUDIO_HPI;
typedef MCI _ AUDIO _ HPI FAR * LPMCI _ AUDIO _ HPI ;
AUDIO_HPI (46h) - Data Packet Format
/--------------------------------------------\ |Field C Datatype | |--------------------------------------------| |Pointer to structure LPMCI_AUDIO_HPI | \--------------------------------------------/
AUDIO_HPI (46h) - 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 Referencefor 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.
AUDIO_UPDATE (47h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_UPDATE (47h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _audio_update {
CHAR iobuf_type;
CHAR FAR *buffer_address;
ULONG buffer_length;
USHORT rc;
void FAR *reserved;
} audio_update;
typedef struct audio _ update FAR * UPDATE ;
AUDIO_UPDATE (47h) - Data Packet Format
/-------------------------------------\ |Field C Datatype | |-------------------------------------| |Pointer to structure UPDATE | \-------------------------------------/
AUDIO_UPDATE (47h) - 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.
AUDIO_UPDATE (47h) - 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.
AUDIO_CAPABILITY (48h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_CAPABILITY (48h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _MCI_AUDIO_CAPS {
ULONG ulLength;
ULONG ulSamplingRate;
ULONG ulChannels;
ULONG ulBitsPerSample;
ULONG ulDataType;
ULONG ulOperation;
ULONG ulSupport;
ULONG ulDataSubType;
ULONG ulResourceUnits;
ULONG ulResourceClass;
ULONG ulBlockAlign;
BOOL fCanRecord;
ULONG ulFlags;
ULONG ulCapability;
} MCI_AUDIO_CAPS;
typedef MCI _ AUDIO _ CAPS FAR * PAUDIO _ CAPS ;
AUDIO_CAPABILITY (48h) - Data Packet Format
/----------------------------------------\ |Field C Datatype | |----------------------------------------| |Pointer to structure PAUDIO_CAPS | \----------------------------------------/
AUDIO_CAPABILITY (48h) - Returns
- SUPPORT_SUCCESS
- UNSUPPORTED_RATE
- UNSUPPORTED_CHANNELS
- UNSUPPORTED_BPS
- UNSUPPORTED_DATATYPE
- UNSUPPORTED_OPERATION
AUDIO_CAPABILITY (48h) - Example Code
The following example code illustrates an application querying the audio device driver for its capabilities. If the device supports the desired mode , the application saves the information.
AUDIOCAPS audiocaps;
audiocaps.ulSamplingRate = 11025;
audiocaps.ulBitsPerSample = 16;
audiocaps.ulChannels = 2;
audiocaps.ulDataType = DATATYPE_WAVEFORM;
MAKE1616(&audiocaps);
rc = DosDevIOCtl( handle,
AUDIO_IOCTL_CAT,
AUDIO_CAPABILITY,
0,
0,
0,
sizeof (audiocaps),
&audiocaps,
(PVOID) &ulParmLengthMax);
if ( audiocaps.ulReturn )
{
// process success
}
else
// process failure
AUDIO_CAPABILITY (48h) - 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 (60h) - Determine if Line is Enabled
This IOCtl enables an application to determine if a particular mixer line is enabled.
MIX_GETCONNECTIONS (60h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
MIX_GETCONNECTIONS (60h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _LINECONNECTIONS {
ULONG ulLength;
ULONG ulConnections;
ULONG ulLine;
} LINECONNECTIONS;
typedef LINECONNECTIONS FAR * PLINECONNECTIONS ;
The caller is responsible for filling in the ulLine field of the LINECONNECTIONS structure.
A bitmap describing the current connection structure will be returned in the ulConnectionsfield. Each onbit 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.
MIX_GETCONNECTIONS (60h) - Data Packet Format
/---------------------------------------------\ |Field C Datatype | |---------------------------------------------| |Pointer to structure PLINECONNECTIONS | \---------------------------------------------/
MIX_GETCONNECTIONS (60h) - 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.
MIX_GETCONNECTIONS (60h) - Example Code
The following code illustrates how to use MIX_GETCONNECTIONS.
HMIXER hMix;
LINECONNECTIONS LineCon;
/*-----------------------------------------
* Find out the setting for the synth.
*-----------------------------------------*/
LineCon.ulLine = SOURCE_SYNTHESIZER;
LineCon.ulLength = sizeof( LINECONNECTIONS);
rc = DosDevIOCtl( hMix,
AUDIO_IOCTL_CATEGORY,
MIX_GETCONNECTIONS,
0,
0,
0,
sizeof (LINECONNECTIONS),
&LineCon,
&ulDataLengthOut);
MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line
This IOCtl enables an application to connect an input line to an output line.
MIX_SETCONNECTIONS (61h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
MIX_SETCONNECTIONS (61h) - Pointer to structure
Pointer to structure The data packet parameter is a pointer to the following data structure.
typedef struct _LINECONNECTIONS {
ULONG ulLength;
ULONG ulConnections;
ULONG ulLine;
} LINECONNECTIONS;
typedef LINECONNECTIONS FAR * PLINECONNECTIONS ;
The caller is responsible for filling in the ulLine and ulConnections fields of the LINECONNECTIONS structure.
MIX_SETCONNECTIONS (61h) - Data Packet Format
/---------------------------------------------\ |Field C Datatype | |---------------------------------------------| |Pointer to structure PLINECONNECTIONS | \---------------------------------------------/
MIX_SETCONNECTIONS (61h) - 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.
MIX_SETCONNECTIONS (61h) - Example Code
The following code illustrates how to use MIX_SETCONNECTIONS.
HMIXER hMix;
LINECONNECTIONS mixinfo;
PVOID p16Info;
/*-------------------------------------------
* Find out the setting for the synth.
*-----------------------------------------*/
mixinfo.ulLine = SOURCE_SYNTHESIZER;
mixinfo.ulConnection = SINK_SPEAKER;
rc = DosDevIOCtl( hMix,
AUDIO_IOCTL_CATEGORY,
MIX_SETCONNECTIONS,
0,
0,
0,
sizeof (LINECONNECTIONS),
&mixinfo,
&ulDataLengthOut);
MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETLINEINFO (62h)
Description:
Determine the Capabilities of a Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
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.
MIX_GETLINEINFO (62h) - Description
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.
MIX_GETLINEINFO (62h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
MIX_GETLINEINFO (62h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _MIXERLINEINFO {
ULONG ulLength;
ULONG ulNumChannels;
ULONG ulSupport;
ULONG ulConnectionsPossible;
ULONG ulLine;
} MIXERLINEINFO;
typedef MIXERLINEINFO FAR * PMIXERLINEINFO ;
The caller is responsible for filling in the ulLine field of the MIXERLINEINFO structure.
MIX_GETLINEINFO (62h) - Data Packet Format
/------------------------------------------\ |Field C Datatype | |------------------------------------------| |Pointer to structure MIXERLINEINFO | \------------------------------------------/
MIX_GETLINEINFO (62h) - 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.
MIX_GETLINEINFO (62h) - Example Code
The following code illustrates how to use MIX_GETCONNECTIONS.
HMIXER hMix;
LINECONNECTIONS mixinfo;
/*-------------------------------------------
* Find out the capabilities for setting the
* synth input.
*-----------------------------------------*/
mixinfo.ulLine = SOURCE_SYNTHESIZER;
rc = DosDevIOCtl( hMix,
AUDIO_IOCTL_CATEGORY,
MIX_GETLINEINFO,
0,
0,
0,
sizeof (LINECONNECTIONS),
&mixinfo,
&ulDataLengthOut);
MIX_GETLINEINFO (62h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETLINEINFO (62h)
Description:
Determine the Capabilities of a Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
MIX_GETCONTROL (63h) - Get Current State of a Line
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETCONTROL (63h)
Description:
Get Current State of a Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
This IOCtl enables an application to get the current state of a particular line.
MIX_GETCONTROL (63h) - Description
This IOCtl enables an application to get the current state of a particular line.
MIX_GETCONTROL (63h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
MIX_GETCONTROL (63h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _MIXERCONTROL {
ULONG ulLength;
ULONG ulLine;
ULONG ulControl;
ULONG ulSetting;
} MIXERCONTROL;
typedef MIXERCONTROL FAR * PMIXERCONTROL ;
The caller is responsible for filling in the ulLinefield of the MIXERCONTROL structure.
The device driver should return the current setting of the line in the ulSettingfield 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.
MIX_GETCONTROL (63h) - Data Packet Format
/------------------------------------------\ |Field C Datatype | |------------------------------------------| |Pointer to structure PMIXERCONTROL | \------------------------------------------/
MIX_GETCONTROL (63h) - 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.
MIX_GETCONTROL (63h) - Example Code
The following code illustrates how to use MIX_GETCONNECTIONS.
HMIXER hMix;
MIXERCONTROL MixerControl;
/*-------------------------------------------
* Find out the setting for the synth.
*-----------------------------------------*/
MixerControl.ulLine= SOURCE_SYNTHESIZER;
/* Ask vsd what is the current setting of the connector */
MixerControl.ulControl = MIX_VOLUME;
/* The controls current setting will be returned here */
rc = DosDevIOCtl( hMix,
AUDIO_IOCTL_CATEGORY,
MIX_GETCONTROL,
MixerControl,
0,
0,
sizeof (MIXERCONTROL),
(PVOID) &ulParmLengthMax,
&ulDataLengthOut);
MIX_GETCONTROL (63h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETCONTROL (63h)
Description:
Get Current State of a Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
MIX_SETCONTROL (64h) - Set State of a Mixer Line
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_SETCONTROL (64h)
Description:
Set State of a Mixer Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
This IOCtl enables an application to set the current state of a particular line.
MIX_SETCONTROL (64h) - Description
This IOCtl enables an application to set the current state of a particular line.
MIX_SETCONTROL (64h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
MIX_SETCONTROL (64h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _MIXERCONTROL {
ULONG ulLength;
ULONG ulLine;
ULONG ulControl;
ULONG ulSetting;
} MIXERCONTROL;
typedef MIXERCONTROL FAR * PMIXERCONTROL ;
The caller is responsible for filling in the ulControl, the ulLine, and the ulSetting, fields of the MIXERCONTROL.
The device driver should return the current setting of the line in ulSettingof 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.
MIX_SETCONTROL (64h) - Data Packet Format
/------------------------------------------\ |Field C Datatype | |------------------------------------------| |Pointer to structure PMIXERCONTROL | \------------------------------------------/
MIX_SETCONTROL (64h) - 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.
MIX_SETCONTROL (64h) - Example Code
The following code illustrates how to use MIX_GETCONNECTIONS.
HMIXER hMix;
MIXERCONTROL MixerControl;
/* Set the volume for the output device */
MixerControl.ulControl = MIX__VOLUME;
MixerControl.ulLine = SINK_LINE_OUT;
MixerControl.ulSetting = 100;
rc = DosDevIOCtl( hMix,
AUDIO_IOCTL_CATEGORY,
MIX_SETCONTROL,
0,
0,
0,
sizeof (MIXERCONTROL),
&MixerControl,
&ulDataLengthOut);
MIX_SETCONTROL (64h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_SETCONTROL (64h)
Description:
Set State of a Mixer Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
IOCtl Examples
Examples of how IOCtls are used to communicate with an audio device driver are shown in this section for C programs running under OS/2, and for assembler language programs running under DOS. The following example is a pseudocode example that shows how an application records or plays back audio data.
Open audio device driver.
If error opening driver:
then end with error message.
Issue AUDIO_INIT IOCtl to set type of audio data to play or record.
If BESTFIT_PROVIDED flag set:
check audio parameters returned by AUDIO_INIT IOCtl
if returned parameters not acceptable:
then end with message.
If LOAD_CODE flag set:
load file name returned in loadpath and issue AUDIO_LOAD IOCtl.
Issue AUDIO_CONTROL CHANGE to initialize connections and control values.
If recording:
Open new file to write audio data to issue AUDIO_CONTROL START IOCtl.
Do until Stop key pressed:
10
Issue Read to get data.
Write data to file.
Do user interface or other processing.
End Do.
Issue AUDIO_CONTROL STOP IOCtl (optional).
Else if playback:
Open file containing data to play back.
Issue AUDIO_BUFFER IOCtl to determine size of buffers.
Read data from file and write data to fill audio DD buffer.
Issue AUDIO_CONTROL START IOCtl.
Do until end of file or Stop key pressed:
Issue AUDIO_BUFFER IOCtl to determine free space in audio DD buffer.
Read data from file.
Write data to audio DD to fill audio DD buffer.
Do user interface or other processing.
End Do.
Issue AUDIO_CONTROL STOP IOCtl (optional).
Close data file.
Close audio DD.
Under OS/2, IOCtls are called using the DosDevIOCtl function. The following example is an OS/2 AUDIO_INITexample.
#define INCL_DOSDEVICES
#include <os2.h>
#include <io.h>
#include <audiodd.h> /* Defines for flags, and
so forth */
init_adpcmv(Handle) /* Initialize to record
ADPCM voice */
HFILE Handle; /* Handle returned from
DosOpen() */
{
struct audio_init buffer; /* I/O buffer (defined in
audiodd.h) */
USHORT rc;
buffer.srate = 11025; /* Set rate = Voice mode */
buffer.bits_per_sample = 16; /* 16-bits per sample */
buffer.bsize = 576; /* Size of Voice mode data
block */
buffer.mode = ADPCM; /* ADPCM mode */
buffer.channels = 1; /* Mono */
buffer.flags = FIXED; /* Fixed block size data */
buffer.operation = RECORD; /* Set up to record */
buffer.version_level = 0x01000018; /* Set version level */
rc = DosDevIOCtl(Handle, AUDIO_IOCTL_CAT, AUDIO_INIT, NULL, 0L,
&ParmLengthInOut, &buffer, (LONG)sizeof(buffer),
&lDataLengthInOut);
if(rc)
return(rc);
}
Under DOS, IOCtls are called by using INT 21h Function 44h. The following is a DOS IOCtl example.
INCLUDE AUDIODD.INC ; Audio DD equates
/abort
; Read the queue status using AUDIO_BUFFER IOCtl
Handle DW ? ; Handle to open device (MIDIn$)
Buffer ; I/O Buffer
FLAGS DD 0 ; Error condition flags
READ_BUF_SIZE DD 0 ; Number of bytes currently in
; Receive queue
WRITE_BUF_SIZE DD 0 ; Number of bytes currently in
; Transmit queue
READ_BUF_TIME DD 0 ; Amount of data in Receive queue
; in millisecs
WRITE_BUF_TIME DD 0 ; Amount of data in Transmit queue
; in millisecs
READ_BUF_MAX DD 0 ; Maximum number of bytes ever in
; Read queue
WRITE_BUF_MAX DD 0 ; Maximum number of bytes ever in
; Write queue
POSITION DD 0 ; Time count since beginning of
; operation
POSITION _ TYPE DD 0 ; Specifies the type of position
; units
READ _ BUF _ CAP DD 0 ; Capacity of Receive queue ; - 1 if
; variable
WRITE _ BUF _ CAP DD 0 ; Capacity of Write queue ; - 1 if
; variable
REQUEST _ BUF _ CAP DD 0 ; Maximum number of requests that
; can be queued
Query _ Q _ Status :
MOV AH , 44h ; Function call - IOCtl
MOV AL , 0Ch ; Indicate generic IOCtl request
MOV BX , Handle ; Select audio device handle ( from
; previous OPEN )
MOV CH , 80h ; Generic IOCtl category
MOV CL , 40h + AUDIO _ BUFFER ; Generic IOCtl Function ID
MOV DX , Offset Buffer ; DS : DX points to buffer
INT 21h ; Issue request to DOS
JC Error ; Error code in AX if C set
.
.
.
M-Audio MCI_AUDIO_INIT Parameters
The following table lists the MCI_AUDIO_INITparameters for the operating modes currently supported by the IBM M-Audio Capture and Playback Adapter.
/-------------------------------------------------------------------------------------------\ |Description |Mode |Bits |Sample rate |No. |Block size |Flags | | | |per | |Chan. | | | | | |Sample| | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |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, |1 |560 |0 | | | | |22050, 44100 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |8 bit PCM stereo |PCM |8 |8000, 11025, |2 |560 |0 | | | | |22050, 44100 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |16 bit PCM mono |PCM |16 |8000, 11025, |1 |560 |TWOS_ | | | | |22050, 44100 | | |COMPLEMENT | |--------------------+-------------+------+-----------------+------+-----------+------------| |16 bit PCM |PCM |16 |8000, 11025, |2 |560 |TWOS_ | |stereo | | |22050, 44100 | | |COMPLEMENT | |--------------------+-------------+------+-----------------+------+-----------+------------| |8 bit mu-law mono |MU_LAW |8 |8000, 11025, |1 |560 |0 | | | | |22050, 44100 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |8 bit mu-law stereo |MU_LAW |8 |8000, 11025, |2 |560 |0 | | | | |22050 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |8 bit A-law mono |A_LAW |8 |8000, 11025, |1 |560 |0 | | | | |22050, 44100 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |8 bit A-law stereo |A_LAW |8 |8000, 11025, |2 |560 |0 | | | | |22050 | | | | |--------------------+-------------+------+-----------------+------+-----------+------------| |Claim Hardware |CLAIM_HDWR |- |- |- |- |- | |--------------------+-------------+------+-----------------+------+-----------+------------| |Source Mix |SOURCE_MIX |- |- |- |- |- | |--------------------+-------------+------+-----------------+------+-----------+------------| |Speech Viewer/2 |SPV2BCPCM |16 |14700 |- |426 tx / |0 | |BCPCM | | | | |426 rx | | |--------------------+-------------+------+-----------------+------+-----------+------------| |Speech Viewer/2 PCM |SPV2PCM |16 |14700 |- |964 tx / 2 |0 | | | | | | |rx | | |--------------------+-------------+------+-----------------+------+-----------+------------| |Speech Viewer/2 |SPV2NONE |- |- |- |256 tx / |- | |Computations | | | | |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 asymmetriccapture 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 symmetricor real-timecapture, and is done at a constant frame rate and constant frame size. When established, a stream captures images continuously without assistance from the application code. A running stream cannot dynamically alter frame rate or size; but video quality attributes such as brightness, hue, and contrast can be altered dynamically. The command used in streaming capture can be found in the Device Driver Commands (DDCMD) messages and Stream-Handler Device (SHD) messages sections.
Streaming capture is used to make real-time movies and to monitor live video on frame-grabber cards.
Playback
Video playback is all done through the VCAI_PLAY IOCtl interface. Unlike record, this is performed through the Inter-Device Driver (IDC) DDCMD messages. The MMPM/2 subsystem invokes the VCAI_PLAY functions from one of two places:
�For compressed playback, the hardware (COmpressor/DECompressor) CODEC calls the play function directly with the compressed data.
With compressed data playback, the MCD issues all the VSD/PDD commands except the VCAI_PLAY and VCAI_LOAD_MICROCODE commands-which are issued by the CODEC.
�In the case of uncompressed playback, the play function is issued by the Direct Interface Video Extensions (DIVE) component after the appropriate CODEC has decompressed the image. DIVE knows to call this video device driver instead of the normal display driver because of the [ OverlayAccelerator] entry in the DIVE.INI file, where the VSD DLL (VSDDRIVE =) and video device driver (PDDNAME=) names are specified for DIVE. When DIVE uses the VSD/PDD to play back video, the MCD is unaware of the hardware; DIVE issues all of the VSD/PDD commands to control window placement and playback function.
User-Defined Video IOCtls
The video IOCtls listed in the following table are category 140 (user defined).
/----------------------------------------------------------------\ |Function |Function |Description | |Number | | | |--------------+---------------------+---------------------------| |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.
VCAI_INIINFO (60h) - Setup Information from INI file
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_INIINFO (60h)
Description:
Setup Information from INI file
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_INIINFO (60h) - Description
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.
VCAI_INIINFO (60h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_INIINFO (60h) - Data Packet Format
The data packet parameter is a pointer to device-specific structure.
VCAI_INIINFO (60h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_INIINFO (60h)
Description:
Setup Information from INI file
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_SAVE (61h) - Save Device State
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SAVE (61h)
Description:
Save Device State
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl saves the current state of the video device. The video device can be shared among several processes that might gain or lose ownershipof 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.
VCAI_SAVE (61h) - 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 ownershipof 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.
VCAI_SAVE (61h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_SAVE (61h) - Data Packet Format
Not used.
VCAI_SAVE (61h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SAVE (61h)
Description:
Save Device State
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_RESTORE (62h) - Restore Device State
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_RESTORE (62h)
Description:
Restore Device State
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_RESTORE (62h) - Description
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.
VCAI_RESTORE (62h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_RESTORE (62h) - Data Packet Format
Not used.
VCAI_RESTORE (62h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_RESTORE (62h)
Description:
Restore Device State
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_LOAD_MICROCODE (63h)
Description:
Query/Load/Unload Microcode
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_LOAD_MICROCODE (63h) - Description
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.
VCAI_LOAD_MICROCODE (63h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_LOAD_MICROCODE (63h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _VCALOAD {
ULONG ulflags;
CHAR ProdInfo[256];
LONG ulLoadID;
ULONG ulLength;
PVOID pLoadData;
} VCALOAD;
typedef VCALOAD FAR * PVCALOAD ;
VCAI_LOAD_MICROCODE (63h) - Data Packet Format
/-------------------------------------\ |Field C Datatype | |-------------------------------------| |Pointer to structure PVCALOAD | \-------------------------------------/
VCAI_LOAD_MICROCODE (63h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_LOAD_MICROCODE (63h)
Description:
Query/Load/Unload Microcode
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_RESTORE_FORMAT (64h)
Description:
Query/Set Image Restore Format
Select an item:
Description Parameter Packet Format Data Packet 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.
VCAI_RESTORE_FORMAT (64h) - Description
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.
VCAI_RESTORE_FORMAT (64h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_RESTORE_FORMAT (64h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _VCAIMAGERF {
ULONG ulFlags;
ULONG ulNumFormats;
ULONG ulCurIndex;
ULONG FourCC[64];
} VCAIMAGERF;
typedef VCAIMAGERF FAR * PVCAIMAGERF ;
VCAI_RESTORE_FORMAT (64h) - Data Packet Format
/----------------------------------------\ |Field C Datatype | |----------------------------------------| |Pointer to structure PVCAIMAGERF | \----------------------------------------/
VCAI_RESTORE_FORMAT (64h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_RESTORE_FORMAT (64h)
Description:
Query/Set Image Restore Format
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_CAPTURE_FORMAT (65h)
Description:
Query/Set Image Capture Format
Select an item:
Description Parameter Packet Format Data Packet 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 ulFlagparameter of the SHD_REPORTINT structure) through the IDC streaming interface.
VCAI_CAPTURE_FORMAT (65h) - Description
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 ulFlagparameter of the SHD_REPORTINT structure) through the IDC streaming interface.
VCAI_CAPTURE_FORMAT (65h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_CAPTURE_FORMAT (65h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _VCAIMAGECF {
ULONG ulFlags;
ULONG ulNumFormats;
ULONG ulCurIndex;
ULONG FourCC[64];
} VCAIMAGECF;
typedef VCAIMAGECF FAR * PVCAIMAGECF ;
VCAI_CAPTURE_FORMAT (65h) - Data Packet Format
/----------------------------------------\ |Field C Datatype | |----------------------------------------| |Pointer to structure PVCAIMAGECF | \----------------------------------------/
VCAI_CAPTURE_FORMAT (65h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_CAPTURE_FORMAT (65h)
Description:
Query/Set Image Capture Format
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_PLAY (67h) - Restore/Play Image to the Screen
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_PLAY (67h)
Description:
Restore/Play Image to the Screen
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl is used to play back and restore images to a device. The format of the image data pointed to by pImageDatais 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.
VCAI_PLAY (67h) - Description
This IOCtl is used to play back and restore images to a device. The format of the image data pointed to by pImageDatais 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 CanRestoreflag in the VCADEVINFO structure should be set to 1.
VCAI_PLAY (67h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_PLAY (67h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCASTREAM {
ULONG ulLength;
PVOID pImageData;
ULONG ulFlags;
ULONG ulSCR;
ULONG ulPTS;
ULONG ulAudioTime;
} VCASTREAM;
typedef VCASTREAM FAR * PVCASTREAM ;
VCAI_PLAY (67h) - Data Packet Format
/---------------------------------------\ |Field C Datatype | |---------------------------------------| |Pointer to structure PVCASTREAM | \---------------------------------------/
VCAI_PLAY (67h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_PLAY (67h)
Description:
Restore/Play Image to the Screen
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_QUERYVIDEOSIGNAL (68h)
Description:
Query Video Input Connector's Signal
Select an item:
Description Parameter Packet Format Data Packet Format Returns
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.
VCAI_QUERYVIDEOSIGNAL (68h) - Description
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.
VCAI_QUERYVIDEOSIGNAL (68h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_QUERYVIDEOSIGNAL (68h) - Data Packet Format
Not used.
VCAI_QUERYVIDEOSIGNAL (68h) - Returns
This IOCtl returns a status value equal to one of the following.
VCAERR_SIGNAL_LOCKED 10 VCAERR_SIGNAL_NOT_LOCKED 11 VCAERR_SIGNAL_INDETERMINATE 12
VCAI_QUERYVIDEOSIGNAL (68h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_QUERYVIDEOSIGNAL (68h)
Description:
Query Video Input Connector's Signal
Select an item:
Description Parameter Packet Format Data Packet Format Returns
VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_TUNERCHANNEL (69h)
Description:
Set/Query Tuner Channel
Select an item:
Description Parameter Packet Format Data Packet Format Returns
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 HasTunerflag should be set to 1 in the VCADEVINFO structure.
VCAI_TUNERCHANNEL (69h) - Description
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 HasTunerflag should be set to 1 in the VCADEVINFO structure.
VCAI_TUNERCHANNEL (69h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_TUNERCHANNEL (69h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCATUNCHAN {
ULONG ulFlags;
ULONG ulOptions;
USHORT usResv01;
USHORT usResv02;
LONG lFineTune;
ULONG ulFrequency;
} VCATUNCHAN;
typedef VCATUNCHAN FAR * PVCATUNCHAN ;
VCAI_TUNERCHANNEL (69h) - Data Packet Format
/----------------------------------------\ |Field C Datatype | |----------------------------------------| |Pointer to structure PVCATUNCHAN | \----------------------------------------/
VCAI_TUNERCHANNEL (69h) - Returns
The following status values are returned by VCAI_TUNERCHANNEL.
VCAERR_CHANNEL_TOO_LOW 6 VCAERR_CHANNEL_TOO_HIGH 7 VCAERR_CHANNEL_NO_TUNER 9
VCAI_TUNERCHANNEL (69h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_TUNERCHANNEL (69h)
Description:
Set/Query Tuner Channel
Select an item:
Description Parameter Packet Format Data Packet Format Returns
VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VIDEOINPUT (6Ah)
Description:
Set/Query Video Input Source Connector
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl sets or queries the current video input source connector.
VCAI_VIDEOINPUT (6Ah) - Description
This IOCtl sets or queries the current video input source connector.
VCAI_VIDEOINPUT (6Ah) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_VIDEOINPUT (6Ah) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _VCASETVIDEOINPUT {
ULONG INPUT_CONNECTOR;
} VCASETVIDEOINPUT;
typedef VCASETVIDEOINPUT FAR * PVCASETVIDEOINPUT ;
VCAI_VIDEOINPUT (6Ah) - Data Packet Format
/----------------------------------------------\ |Field C Datatype | |----------------------------------------------| |Pointer to structure PVCASETVIDEOINPUT | \----------------------------------------------/
VCAI_VIDEOINPUT (6Ah) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VIDEOINPUT (6Ah)
Description:
Set/Query Video Input Source Connector
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETCAPTRECT (6Bh)
Description:
Set Source and Destination Capture/Restore Rectangles
Select an item:
Description Parameter Packet Format Data Packet Format
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 ulCmdparameter 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, sourcerefers 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.
VCAI_SETCAPTRECT (6Bh) - Description
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 ulCmdparameter 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, sourcerefers 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.
VCAI_SETCAPTRECT (6Bh) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_SETCAPTRECT (6Bh) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _VCASETCAPTURERECT {
ULONG Source_X_Left;
ULONG Source_Y_Top;
ULONG Source_Y_Height;
ULONG Source_X_Width;
ULONG Dest_X_Left;
ULONG Dest_Y_Top;
ULONG Dest_Y_Height;
ULONG Dest_X_Width;
} VCASETCAPTURERECT;
typedef VCASETCAPTURERECT FAR * PVCASETCAPTURERECT ;
VCAI_SETCAPTRECT (6Bh) - Data Packet Format
/-----------------------------------------------\ |Field C Datatype | |-----------------------------------------------| |Pointer to structure PVCASETCAPTURERECT | \-----------------------------------------------/
VCAI_SETCAPTRECT (6Bh) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETCAPTRECT (6Bh)
Description:
Set Source and Destination Capture/Restore Rectangles
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_GETIMAGESCALE (6Ch)
Description:
Get Image and Scale into RAM Buffer
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
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 applications 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 mustensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use VCAI_GETDEVINFOto determine the maximum image extents.
Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur.
VCAI_GETIMAGESCALE (6Ch) - Description
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 applications 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 mustensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use VCAI_GETDEVINFOto determine the maximum image extents.
Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur.
VCAI_GETIMAGESCALE (6Ch) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_GETIMAGESCALE (6Ch) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCAGETIMAGESCALE {
ULONG Capture_Buf_Len;
ULONG Capture_Buf_Ptr;
ULONG Source_X_Left;
ULONG Source_Y_Top;
ULONG Source_Y_Height;
ULONG Source_X_Width;
ULONG Dest_X_Left;
ULONG Dest_Y_Top;
ULONG Dest_Y_Height;
ULONG Dest_X_Width;
} VCAGETIMAGESCALE;
typedef VCAGETIMAGESCLAE FAR * PVCAGETIMAGESCALE ;
VCAI_GETIMAGESCALE (6Ch) - Data Packet Format
/----------------------------------------------\ |Field C Datatype | |----------------------------------------------| |Pointer to structure PVCAGETIMAGESCALE | \----------------------------------------------/
VCAI_GETIMAGESCALE (6Ch) - 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).
VCAI_GETIMAGESCALE (6Ch) - 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 notsupport all the transposition and scaling possibilities supported with this IOCtl. Consult the specific device driver's documentation for limitations, or use VCAI_GETDEVINFOto determine its capabilities.
VCAI_GETIMAGESCALE (6Ch) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_GETIMAGESCALE (6Ch)
Description:
Get Image and Scale into RAM Buffer
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
VCAI_GETDEVINFO (6Dh) - Get Device Information
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_GETDEVINFO (6Dh)
Description:
Get Device Information
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_GETDEVINFO (6Dh) - Description
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.
VCAI_GETDEVINFO (6Dh) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_GETDEVINFO (6Dh) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following data structure.
typedef struct _vcadevinfo {
ULONG Length;
CHAR ProdInfo[30];
CHAR ManInfo[30];
CHAR Version[10];
ULONG ImgFormat;
USHORT BitsPerPEL;
USHORT Overlay;
ULONG Brightness;
ULONG hue;
ULONG saturation;
ULONG contrast;
ULONG Sharpness;
ULONG unused1;
ULONG S_X_Left;
ULONG S_Y_Top;
ULONG S_Y_Height;
ULONG S_X_Width;
ULONG D_X_Left;
ULONG D_Y_Top;
ULONG D_Y_Height;
ULONG D_X_Width;
ULONG D_ScaleFactor;
ULONG S_X_MAX;
ULONG S_Y_MAX;
ULONG D_X_MAX;
ULONG D_Y_MAX;
ULONG O_X_MAX;
ULONG O_Y_MAX;
USHORT VideoInputs;
USHORT CanRestore;
USHORT CanStretch;
USHORT CanDistort;
USHORT HasVolume;
USHORT HasBalance;
USHORT CanScale;
USHORT CanStream;
ULONG DI_ulFilenum;
BYTE HasTuner;
BYTE HasTeleTex;
LONG Delay_Time;
BYTE HasAFC;
BYTE HasPolarization;
} VCADEVINFO;
typedef VCADEVINFO FAR * PVCADEVINFO ;
VCAI_GETDEVINFO (6Dh) - Data Packet Format
/----------------------------------------\ |Field C Datatype | |----------------------------------------| |Pointer to structure PVCADEVINFO | \----------------------------------------/
VCAI_GETDEVINFO (6Dh) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_GETDEVINFO (6Dh)
Description:
Get Device Information
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_VALIDRECT (6Eh) - Validate Video Rectangle
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VALIDRECT (6Eh)
Description:
Validate Video Rectangle
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl modifies the source X_Widthand source Y_Heightto 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.
VCAI_VALIDRECT (6Eh) - Description
This IOCtl modifies the source X_Widthand source Y_Heightto 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.
VCAI_VALIDRECT (6Eh) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_VALIDRECT (6Eh) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCACAPISIZE {
ULONG X_Left;
ULONG Y_Top;
ULONG Y_Height;
ULONG X_Width;
ULONG ScaleFactor;
} VCACAPISIZE;
typedef VCACAPISIZE FAR * PVCACAPISIZE ;
VCAI_VALIDRECT (6Eh) - Data Packet Format
/-----------------------------------------\ |Field C Datatype | |-----------------------------------------| |Pointer to structure PVCACAPISIZE | \-----------------------------------------/
VCAI_VALIDRECT (6Eh) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VALIDRECT (6Eh)
Description:
Validate Video Rectangle
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_UNFREEZE (72h)
Description:
Unfreeze the Image Digitizer
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl tells the video device to continuously digitize the incoming video source.
VCAI_UNFREEZE (72h) - Description
This IOCtl tells the video device to continuously digitize the incoming video source.
VCAI_UNFREEZE (72h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_UNFREEZE (72h) - Data Packet Format
Not used.
VCAI_UNFREEZE (72h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_UNFREEZE (72h)
Description:
Unfreeze the Image Digitizer
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_FREEZE (74h) - Freeze the Image Digitizer
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_FREEZE (74h)
Description:
Freeze the Image Digitizer
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_FREEZE (74h) - Description
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.
VCAI_FREEZE (74h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_FREEZE (74h) - Data Packet Format
Not used.
VCAI_FREEZE (74h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_FREEZE (74h)
Description:
Freeze the Image Digitizer
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_VIDEOADJ (75h) - Set/Query Video Adjustments
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VIDEOADJ (75h)
Description:
Set/Query Video Adjustments
Select an item:
Description Parameter Packet Format Data Packet Format Remarks
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.
VCAI_VIDEOADJ (75h) - Description
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.
VCAI_VIDEOADJ (75h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_VIDEOADJ (75h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCASETVIDEO {
ULONG set_brightness;
ULONG set_hue;
ULONG set_saturation;
ULONG set_contrast;
ULONG ret_brightness;
ULONG ret_hue;
ULONG ret_saturation;
ULONG ret_contrast;
} VCASETVIDEO;
typedef VCASETVIDEO FAR * PVCASETVIDEO ;
VCAI_VIDEOADJ (75h) - Data Packet Format
/-----------------------------------------\ |Field C Datatype | |-----------------------------------------| |Pointer to structure PVCASETVIDEO | \-----------------------------------------/
VCAI_VIDEOADJ (75h) - Remarks
When setting a value, put the value desired (in the range of 0 to 255) into the value's field. If resetting the value to the defaults, put DEFAULT into the value's field. If no change is desired for a particular value, put NO_ CHANGE in the value's field. The call always returns the current value or NOT_SUPPORTED for each setting after the value has been updated.
VCAI_VIDEOADJ (75h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_VIDEOADJ (75h)
Description:
Set/Query Video Adjustments
Select an item:
Description Parameter Packet Format Data Packet Format Remarks
VCAI_SETFPS (76h) - Set Frame Rate for Streaming
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETFPS (76h)
Description:
Set Frame Rate for Streaming
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl allows the caller to set the frame rate, 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
VCAI_SETFPS (76h) - Description
This IOCtl allows the caller to set the frame rate, 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
VCAI_SETFPS (76h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_SETFPS (76h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCASETFPS {
ULONG set_FPS;
ULONG ulFlags;
} VCASETFPS;
typedef VCASETFPS FAR * PVCASETFPS ;
VCAI_SETFPS (76h) - Data Packet Format
/---------------------------------------\ |Field C Datatype | |---------------------------------------| |Pointer to structure PVCASETFPS | \---------------------------------------/
VCAI_SETFPS (76h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETFPS (76h)
Description:
Set Frame Rate for Streaming
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_USER (79h)
Description:
Pass Device-Specific Commands to Device Driver
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_USER (79h) - Description
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.
VCAI_USER (79h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_USER (79h) - Data Packet Format
Application Dependent.
VCAI_USER (79h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_USER (79h)
Description:
Pass Device-Specific Commands to Device Driver
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETMONITOR (80h)
Description:
Enable/Disable Overlay Monitor
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl enables or disables display of live video on the display device.
VCAI_SETMONITOR (80h) - Description
This IOCtl enables or disables display of live video on the display device.
VCAI_SETMONITOR (80h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_SETMONITOR (80h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCASETMONITOR {
BOOL bMonitor;
} VCASETMONITOR;
typedef VCASETMONITOR FAR * PVCASETMONITOR ;
VCAI_SETMONITOR (80h) - Data Packet Format
/-------------------------------------------\ |Field C Datatype | |-------------------------------------------| |Pointer to structure PVCASETMONITOR | \-------------------------------------------/
VCAI_SETMONITOR (80h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETMONITOR (80h)
Description:
Enable/Disable Overlay Monitor
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_EDCOLORKEY (81h)
Description:
Enable/Disable Transparent Color
Select an item:
Description Parameter Packet Format Data Packet Format
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.
VCAI_EDCOLORKEY (81h) - Description
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.
VCAI_EDCOLORKEY (81h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_EDCOLORKEY (81h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCAEDCOLORKEY {
BOOL bColorKeying;
} VCAEDCOLORKEY;
typedef VCAEDCOLORKEY FAR * PVCAEDCOLORKEY ;
VCAI_EDCOLORKEY (81h) - Data Packet Format
/-------------------------------------------\ |Field C Datatype | |-------------------------------------------| |Pointer to structure PVCAEDCOLORKEY | \-------------------------------------------/
VCAI_EDCOLORKEY (81h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_EDCOLORKEY (81h)
Description:
Enable/Disable Transparent Color
Select an item:
Description Parameter Packet Format Data Packet Format
VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETCOLORKEY (82h)
Description:
Set Color Key/Transparent Color
Select an item:
Description Parameter Packet Format Data Packet Format
This IOCtl sets the colors that video replaces when color keying is enabled and the monitor is enabled.
VCAI_SETCOLORKEY (82h) - Description
This IOCtl sets the colors that video replaces when color keying is enabled and the monitor is enabled.
VCAI_SETCOLORKEY (82h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
VCAI_SETCOLORKEY (82h) - Pointer to structure
Pointer to structureThe data packet parameter is a pointer to the following structure.
typedef struct _VCASETCOLORKEY {
ULONG ulColorKey;
} VCASETCOLORKEY;
typedef VCASETCOLORKEY FAR * PVCASETCOLORKEY ;
VCAI_SETCOLORKEY (82h) - Data Packet Format
/--------------------------------------------\ |Field C Datatype | |--------------------------------------------| |Pointer to structure PVCASETCOLORKEY | \--------------------------------------------/
VCAI_SETCOLORKEY (82h) -
Category:
VIDEO_IOCTL_CAT (140)
Function:
VCAI_SETCOLORKEY (82h)
Description:
Set Color Key/Transparent Color
Select an item:
Description Parameter Packet Format Data Packet Format
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation