MMPM/2 Device Driver Reference
By IBM
MMPM/2 Device Driver Reference
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
About This Book
The MMPM/2 Device Driver Reference for OS/2 is for subsystem developers who want to write their own physical device drivers (and associated virtual device drivers) to support audio and video adapters in the Multimedia Presentation Manager/2 system.
Note: Multimedia Presentation Manager/2 (MMPM/2) is also referred to as "OS/2 Multimedia".
The IBM Developer Connection Device Driver Kit for OS/2 (DDK) provides PDD and VDD source code that serves as a template that can be modified easily to meet your hardware requirements. Tools to test your device drivers are also available.
Related Information
You should be familiar with the IBM Developer's Toolkit for OS/2. Related OS/2 and OS/2 multimedia technical information includes:
OS/2 Physical Device Driver Reference Defines what a physical device driver is, and how it operates. It also describes the types of physical device drivers, their interfaces, and available system services.
An online version of this book is provided in this package.
OS/2 Virtual Device Driver Reference Defines what a virtual device driver is, how it operates, and when to use one. It also describes the types of virtual device drivers, their interfaces, and available kernel services.
An online version of this book is provided in this package.
OS/2 Multimedia Technical Library
Online versions of the following books are provided with the OS/2 Developer's Toolkit.
OS/2 Multimedia Subsystem Programming Guide Provides guidelines for developing multimedia subsystems. Each subsystem component is described in detail in individual chapters. Models are used to complement the information provided by component sample program templates.
OS/2 Multimedia Application Programming Guide Provides advisory information on application interfaces to help you select and implement functions for your OS/2 multimedia applications. Code examples from fully documented sample programs accompany the descriptions of the functions.
OS/2 Multimedia Programming Reference Provides detailed information on multimedia functions, messages, and data structures to enable you to write code for your multimedia application programs and subsystems.
Using the Online Reference
Before you begin to use this reference, it would be helpful to understand how you can:
- Expand the Contents window to see all available topics
- Obtain additional information for a highlighted word or phrase
- Use action bar choices
How to Use the Contents
When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign (+) indicates that additional topics are available.
To expand the Contents if you are using a mouse, click on the plus sign. If you are using a keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus key (+).
To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press Enter).
How to Obtain Additional Information
After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are highlighted in green letters. These are called "hypertext terms". If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word and then press Enter. Additional information will appear in a window.
To return to the window you were viewing before you selected a hypertext term, press Esc.
How to Use Action Bar Choices
Several choices are available for managing information presented in the online MMPM/2 Device Driver Reference. There are three pull-down menus on the action bar: the Services menu, the Options menu, and the Help menu.
The actions that are selectable from the Services menu operate in the active window currently displayed on the screen. These actions include the following:
Bookmark Sets a place holder so you can retrieve information of interest to you.
When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty.
To set a bookmark, do the following:
- Select a topic from the Contents.
- When that topic appears, choose the Bookmark option from the Services menu.
- If you want to change the name used for the bookmark, type the new name in the field.
- Select the Place radio button (or press the Up or Down Arrow key to select it).
- Select OK. The bookmark is then added to the bookmark list.
Search Finds occurrences of a word or phrase in the current topic, selected topics, or all topics.
You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list.
To search for a word or phrase in all topics, do the following:
- Choose the Search option from the Services pull-down.
- Type the word or words to be searched.
- Select All sections.
- Select Search to begin the search.
- The list of topics where the word or phrase appears is displayed.
- Prints one or more topics. You can also print a set of topics by first marking the topics in the Contents list.
You can print one or more topics. You can also print a set of topics by first marking the topics on the Contents list.
To print the document Contents list, do the following:
- Select Print from the Services menu.
- Select Contents.
- Select Print.
- The Contents list is printed on your printer.
- Copy
- Copies a topic you are viewing to a file you can edit.
You can copy a topic you are viewing into a temporary file named "TEXT.TMP". You can later edit that file by using an editor such as the System Editor.
To copy a topic, do the following:
- Expand the Contents list and select a topic.
- When the topic appears, select Copy to file from the Services menu.
The system copies the text pertaining to that topic into the temporary TEXT.TMP file.
For information on any of the other choices in the Services menu, highlight the choice and press the F1 key.
- Options
- Changes the way the Contents list is displayed.
You can control the appearance of the Contents list.
To expand the Contents and show all levels for all topics, select Expand all from the Options menu.
For information on any of the other choices in the Options menu, highlight the choice and press the F1 key.
What's New
- Discussion of and pointers to the PAS16 audio sample have been removed.
- Pointers to the new object-oriented audio driver sample, TROPEZ.SYS have been included.
- References to the AUDIOVDD.SYS virtual driver have been removed. The VBSAUDIO.SYS driver serves as its replacement.
For information on any items discussed in this reference that have been added to OS/2 (beginning with Warp) and their compatibility with different versions of OS/2, see OS/2 Version Compatibility Considerations.
Assistance
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.
To access the DDSC BBS, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.
Additional assistance is available through the IBM Solution Developer Program. For membership information:
- Internet: ibmsdp@vnet.ibm.com
- US/Canada: 800-627-8363
- International: 770-835-9902
- International Fax: 770-835-9444
Ordering Information
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.
- The Physical Device Driver Reference
- The Storage Device Driver Reference
- The Input/Output Device Driver Reference
- The Pen for OS/2 Device Driver Reference
- The Virtual Device Driver Reference
- The Presentation Device Driver Reference
- The Display Device Driver Reference
- The Printer Device Driver Reference
- The Graphics Adapter Device Driver Reference
- The MMPM/2 Device Driver Reference (Multimedia)
To order the DDK call:
| U.S.A.: | 1-800-633-8266 | |||||||||||||||
| Canada: | 1-800-561-5293 | |||||||||||||||
| When calling from Europe, the Middle East, or Africa, the number depends on the language you use to place the order: | English | (+45) 48101500 | ||||||||||||||
| French | (+45) 48101200 | |||||||||||||||
| Italian | (+45) 48101600 | |||||||||||||||
| German | (+45) 48101000 | |||||||||||||||
| Spanish | (+45) 48101100 | |||||||||||||||
| Dutch | (+45) 48101400 | |||||||||||||||
| Danish | (+45) 48101300 | |||||||||||||||
| Finish | (+45) 48101650 | |||||||||||||||
| Swedish | (+45) 48101150 | |||||||||||||||
| Norwegian | (+45) 48101250 | |||||||||||||||
| FAX | (+45) 48142207 | |||||||||||||||
| When ordering from Latin America or South America, the number depends on the country from which you are calling: |
|
01-257-0111 | * Dominican Republic | 566-5161 | * El Salvador | 02-98 5011 | * Honduras | 32-2319 | * Paraguay | 021-444 094 | * Urugruay | 02-923 617 | 02-633-4400 | 223-6222 | * Ecuador | 02-56 5100 | * Guatemala | 02-31 5859 | * Panama | 02-639 977 | * Peru | 014-36 6345 | * Venezuela | 02-908-8901 | * Argentina | 01-313-0014 | |
| * All except Japan |(61) 2-354-7684 | * Japan |(81) 3-3495-2045(Fax) | |Fax request to: | |DAP-J, IBM Japan | |||||||||||||
| (021) 800-6120(Voice)| | (021) 800-6936(Fax) | | |||||||||||||||
| * Mexico City |627-2444 | * Country |91-800-00639 |
Adding Support for Audio and Video Adapters
This DDK enables adding audio and video adapter support to the Multimedia Presentation Manager/2 (MMPM/2) audio and video subsystems without having to write a separate installation DLL for each adapter.
Adapters are added to the appropriate MMPM/2 subsystem by:
- Specifying parameters in a resource file (.RC). The resource file is compiled to create the resource DLL.
- Modifying control files that tell MINSTALL how to install your adapter.
- Modifying a help file that displays help information to users when they are installing your adapter.
This process is shown in the following illustration for a video adapter. [Artwork not shown]
For additional information about adding support for an audio adapter, see Audio Adapter Installationor for adding support for a video adapter, see Video Adapter Installation.
Audio Adapter Installation
MMPM/2 allows installation of device drivers developed for audio adapters into the MMPM/2 audio subsystem. MMPM/2 can then use the audio adapter to play and record digital audio files. It can also play, but not record, MIDI files.
This DDK provides a generic installation program that performs the following functions:
�Asks the user for any information needed to install your adapter, such as the interrupt level.
�Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.
�Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.
�Copies the files needed by your adapter, such as device drivers.
The following steps provide an overview of how to use the generic audio installation program to install a device driver into the MMPM/2 audio subsystem. The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. For more information about the AUDINST files, see Source Code. More detailed information about each step is provided in the following sections.
To add an audio adapter to the MMPM/2 audio subsystem, follow these steps:
1.Create an OS/2 device driver for the audio adapter.
For information on creating an OS/2 device driver, refer to Audio Physical Device Driver Template.
2.Write a Vendor-Specific Driver Resource File.
This file is an audio resource file that describes your audio device to MMPM/2.
For more information, see Step 2. Writing a Vendor-Specific Driver.
3.Modify the CARDINFO.RC file.
This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.
For more information, see Step 3. Modifying the CARDINFO.RC File.
4.If necessary, create a DLL to perform actions not provided by this generic audio installation program.
This step is not necessary, unless you want to perform some action that is not provided by the generic audio installation program.
For more information, see Step 4. Creating an Audio Installation DLL.
5.Modify the AUDHELP.ITL file.
This file contains information that is presented to the user when installing your adapter.
For more information, see Step 5. Modifying the AUDHELP.ITL File.
6.Run the MAKEFILE.
This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.
For more information, see Step 6. Running the MAKEFILE.
7.Modify the CONTROL.SCR file.
This file is the control file used by MINSTALL to determine what subsystems and devices a user can install.
For more information, see Step 7. Modifying the CONTROL.SCR File.
8.Modify the AUDFILES.SCR file.
This file lists the files the adapter uses. It tells MINSTALL which files need to be copied and into which subdirectories to place them.
For more information, see Step 8. Modifying the AUDFILES.SCR File.
9.If necessary, create a MIDI map.
This step is not necessary if the adapter uses the general MIDI specifications.
For more information, see Step 9. Creating a MIDI Map.
10.Create an installation diskette.
This diskette must contain all the files necessary to install the adapter into the MMPM/2 audio subsystem using MINSTALL.
For more information, see Step 10. Creating the Installation Diskette.
11.Install your adapter using MINSTALL.
For more information, see Step 11. Using MINSTALL to Install Your Adapter.
Source Code
The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. These sample files illustrate how to install an audio device driver into the MMPM/2 audio subsystem. The sample files include:
/-------------------------------------------------------------\ |Source File |Description | |-------------------------+-----------------------------------| |MAKEFILE |Creates the resource DLL containing| | |the audio adapter information by | | |compiling the CARDINFO.RC file into| | |the CARDINFO.DLL file. This file | | |also compiles the AUDHELP.ITL file | | |into the AUDHELP.HLP help file. | |-------------------------+-----------------------------------| |CARDINFO.RC |Supplies information about the | | |audio adapter. | |-------------------------+-----------------------------------| |MIDIMAP.RC |Contains the sample MIDI map table.| |-------------------------+-----------------------------------| |RCSTUB.C |Stub 'C' file for compiling | | |CARDINFO.RC. | |-------------------------+-----------------------------------| |AUDHELP.ITL |Contains the help information. | |-------------------------+-----------------------------------| |CONTROL.SCR |Contains the control information | | |used by MINSTALL to install the | | |audio adapter. | |-------------------------+-----------------------------------| |AUDFILES.SCR |Lists the files to be copied by | | |MINSTALL. MINSTALL also copies this| | |file. | |-------------------------+-----------------------------------| |MIDIMAP.SCR |Contains the INI change control | | |file used by MINSTALL to install a | | |MIDI map table. | |-------------------------+-----------------------------------| |GENIN.DLL |Is the generic installation program| | |that installs your adapter. | |-------------------------+-----------------------------------| |GENINMRI.DLL |Contains the text used be GENIN.DLL| \-------------------------------------------------------------/
Note:Before modifying any of these files, make sure you have a backup copy.
Step 1. Creating an OS/2 Device Driver for an Audio Adapter
For information on creating an OS/2 device driver, refer to Audio Physical Device Driver Template.
Step 2. Writing a Vendor-Specific Driver
The vendor-specific driver (VSD) resource file describes your audio device to MMPM/2. When audio services are requested, the Media Device Manager (MDM ) communicates with the amplifier-mixer (ampmix) device. Then, the ampmix device is opened, and it loads the VSD resource DLL and transfers adapter information into a memory buffer. If a user requests a particular mode (or audio setting), the VSD looks up that mode to determine the device characteristics and reports the specific information to the MDM. This process is shown in the following illustration:
[Artwork not shown]
You can reduce the amount of code required to add a device to MMPM/2 by using a VSD resource file. This file enables you to supply only one DLL for all the devices being added to MMPM/2.
To add a new audio device to the MMPM/2 audio subsystem, you must supply a device driver and a VSD resource file. Both are installed using the generic audio installation program. For more information, see Audio Adapter Installation.
An example VSD resource file (SAMPLE.RC) is in the \MMOS2\MMTOOLKT\SAMPLES\ VSDRC subdirectory. When you use the generic audio installation program, you must specify the following parameters in the audio ampmixer's device- specific parameters:
RESOURCEDLL= Specifies the name of the DLL that contains the audio resource description. The resource example in the Toolkit contains a DLL named SAMPLE.DLL and creates the following line in the MMPM2.INI file:
RESOURCEDLL=SAMPLE
Note:Do not specify the .DLL extension.
RCID= Indicates which adapter in the VSD resource file is used for audio support. Resource DLLs can contain descriptions for multiple adapters. The sample resource file (\MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC) contains a description of two audio adapters, the ProAudio Spectrum (indicated by RCID =1) and the Sound Blaster Pro (indicated by RCID=2).
Resource File Layout
The following is the format of the vendor-specific driver (VSD) resource file:
BEGIN RCDATA <Device Number> <Device Name>, <Device ID>, <Reserved1>, <Reserved2>, <Number of Datatype Rows>, <Datatype Row> END
The following list describes the VSD resource file format parameters:
RCDATA Indicates the beginning of the resource file for each audio adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter is (indicated in red):
RCDATA PAS_16
Device Number Describes the offset in the resource file used to describe the device. This parameter is usually the name of the adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
RCDATA PAS_16
and for the Creative Labs Sound Blaster Pro adapter it is:
RCDATA SB_PRO
Each device number in the resource file must be unique. These numbers are determined by the manufacturer. The defines for the device numbers that are valid in this field are in the SAMPLE.H file.
This field must be a ULONG.
Device Name Indicates the device name. This parameter must be the first item in the table because it is used by the amplifier-mixer to return product information. This string must be an ASCII string. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is:
"Media Vision Pro Audio Spectrum"
and for the Creative Labs Sound Blaster Pro adapter it is:
"Creative Labs Sound Blaster Pro"
Device ID Indicates which device the system is using. It is the same as the device ID returned from the AUDIO_INIT IOCtl. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is ( indicated in red):
PAS16, 0,
and for the Creative Labs Sound Blaster Pro adapter it is (indicated in red ):
SOUND_BLASTER, 0,
This field must be a USHORT.
Note:Because the Device ID in not explicitly defined to be a LONG, the resource compiler assumes this field is a USHORT.
Reserved1 This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
PAS16, 0, 0,
This field must be a USHORT.
Reserved2 This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
PAS16, 0, 0,
This field must be a USHORT.
Number of Data Type Rows Indicates the number of data type rows. A data type row is defined below.
Some parameters in the data type row can be duplicated, however, all rows must be unique. For example, the Bits Per Sample parameter is repeated often, but the rows are unique.
In the SAMPLE.RC file, the Media Vision ProAudio Spectrum adapter has 17 unique combinations of parameters such as Samples Per Second, Bits Per Sample, and Channels (these fields are described in the following parameters). Therefore, the value of this field is:
17L
and the Creative Labs Sound Blaster Pro adapter has 11 unique row descriptions. Therefore, the value of this field is:
11L
This field must be a ULONG.
Data type Row A data type row describes the specific capabilities of each of audio device and consists of a combination of the following parameters:
�RIFF Data Type
�RIFF Data Subtype
�Samples per Second
�Bits per Sample
�Channels
�Sampling Descriptions
�Play Resource Class
�Play Resource Units Used
�Record Resource Class
�Record Resource Units Used
RIFF Data Type Indicates a RIFF defined data type indicated in OS2MEDEF.H. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
For additional information, see the OS/2 Multimedia Programming Reference. These are the same subtypes used in the streaming subsystem.
This field must be a ULONG.
RIFF Data Subtype Indicates the RIFF subtypes for a given data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
For additional information, see the OS/2 Multimedia Programming Reference. These are the same subtypes used in the streaming subsystem.
Samples Per Second Indicates the sampling rate supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
This field must be a USHORT.
Bits Per Sample Indicates the bits per sample supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
This field must be a USHORT.
Channels Indicates the channels supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
This field must be a USHORT.
Sampling Descriptions Describes the sampling rates. If the current data type row supports a specific sampling rate (for example, the device only supports one specific rate), the STATIC_RATE flag should be specified. For example, the M-Audio adapter can play only one specific sampling rate, so the STATIC_FLAG is specified (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16 8000, 16, 1, STATIC_RATE, PCM_CLASS, 1, 0, 0,
If a range of sampling rates are supported (for example, the device can play any rate between 2 kHz and 48 kHz), the lowest sampling rate in the range should contain the BEGIN_CONTINUOUS flag and highest sampling rate should be specified in one of the following rows with the END_CONTINUOUS flag. Intermediate sampling rates should also contain the BEGIN_CONTINUOUS flag. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter indicates support for rates between 2 kHz and 48 kHz (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1, DATATYPE_WAVEFORM, WAVE_FORMAT_1M16, 11025, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1, DATATYPE_WAVEFORM, WAVE_FORMAT_2M16, 22050, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1, DATATYPE_WAVEFORM, WAVE_FORMAT_4M16, 48000, 16, 1, END_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
Notice that BEGIN_CONTINUOUS is used with the first sampling rate of 2000 and that END_CONTINUOUS ends the sampling rate at 48000. For additional information, see the OS/2 Multimedia Subsystem Programming Guide.
This field must be a ULONG.
Play Resource Class Indicates the class for the data type defined in this row. For example, this parameter indicates that when a particular data type is defined, the data type falls under this particular class. This parameter matches a class defined for the amplifier-mixer (ampmix) device in the MMPM2.INI file and is determined by the manufacturer. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
This parameter is defined in the SAMPLE.H file. This field must be a USHORT .
Play Resource Units Used Indicates the number of resource units this RIFF data type (or class) consumes. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
The Media Vision ProAudio Spectrum adapter only supports one instance at a time playing PCM, so the total resources for the class is 1. When this parameter specifies 1 for the Data type row, MDM assures that not more than one instance plays PCM at any one time. For additional information, see the OS/2 Multimedia Subsystem Programming Guide.
This field must be a USHORT.
Record Resource Class Indicates the class for the RIFF data type in record mode. This parameter matches the class defined in the MMPM2.INI file and is determined by the manufacturer. If this value is nonzero, the amplifier- mixer assumes that recording is possible for this data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
If the class contains a zero, it is assumed that recording is not possible. For example, a device might not be able to record mono, PCM, 44 kHz data. Therefore, a 0 is entered in the record class (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 44000, 8, 1, END_CONTINUOUS, PCM_CLASS, 1, 0, 1,
This parameter also indicates that when a particular data type is defined, the data type falls under this particular class. The Media Vision ProAudio Spectrum adapter supports only one instance at a time when recording PCM, so the total resources for the class is 1. When this parameter specifies 1 for the data type, MDM assures that the device does not exceed this number of units.
This field must be a USHORT.
Record Resource Units Used Indicates the number of resources this RIFF data type consumes in record mode (USHORT). For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):
DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
Step 3. Modifying the CARDINFO.RC File
The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory. Modify this file so that it contains information relevant to your audio adapter. MMPM/2 uses this information to interface with your adapter.
Notes:
1.The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.
2.If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.
3.If the audio adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string "/0" in the parameter.
The CARDINFO.RC parameters are:
RCDATA 1 Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of audio adapter, place that number in this parameter.
For example, in the CARDINFO.RC file, the ProAudio Spectrum adapter is:
RCDATA 1 BEGIN "1" /* Number of adapters in this rc file */ END
RCDATA 10 Contains two parameters, the ID number and the type of audio adapter. The ID number is used in the CONTROL.SCR file that you modify in Step 7. The ID number can be any number. However, it must match the ssdllinputparmskeyword in the CONTROL.SCR file. For the type of adapter, use "audiovdd" if the adapter uses the IBM AUDIOVDD.SYS device driver. If the adapter does not use this driver, put "audio" in this field.
For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:
RCDATA 10
BEGIN
"26", /* ID number of this adapter */
"audiovdd" /* Type of adapter - use audiovdd if */
/* you use the IBM audiovdd.sys driver */
END
For more information, see Audio Physical Device Driver Template.
RCDATA 11 Contains parameters that indicate:
�The maximum number of this type of audio adapter that can be installed at one time. The maximum is six adapters.
�The name of the help file that describes the audio adapter. This name defaults to AUDHELP.HLP if the MAKEFILE provided to create the help file is used.
�The name of the audio-adapter-specific DLL you wrote to perform functions not provided by this generic audio installation program. This DLL is described in Step 4. Creating an Audio Installation DLL. If you did not write a DLL, specify "\0".
�The name of the audio-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify "\0".
�The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the audio adapter. The maximum is six lines.
Note:Do not count the AUDIOVDD.SYS line.
�The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file (except for the AUDIOVDD.SYS line). Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:
- PATH* Indicates the path where MMPM/2 is installed (for example, c:\MMOS2) .
- ORD* Indicates the device ordinal of this adapter.
- SEQ* Indicates the sequential number of this adapter. For example, if the user installs two IBM audio adapters, the first will have a number of 1 and the second a number of 2.
- PDD* Indicates the PDDName of this adapter.
- VAL* Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.
Note:Later in the CARDINFO.RC file, you specify which questions the installation program should ask.
- SPEC* Indicates special values passed from your adapter-specific DLL.
For example, the line in the sample CARDINFO.RC file is:
"DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*"
After the real values are substituted, the CONFIG.SYS line is similar to:
DEVICE=C:\MMOS2\MVPRODD.SYS /I5 /D12 /N:PAS161$
�The number of drivers to install into the MMPM/2 system. For an audio adapter, this would normally be three because most audio adapters install a Waveform, Audio Sequencer, and Audio Ampmixer driver. The maximum is six drivers.
�The name of the adapter as it is displayed to the user.
�The version number of the device driver.
�The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a "$" is added to this name to form the final PDDName. For example, if the user installs two ProAudio Spectrum 16 adapters, the PDDNames are PAS161$ and PAS162$.
�The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.
�The name of the VSD command table used by the drivers. In most cases this is blank.
For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:
RCDATA 11
BEGIN
"1", /* Max number of adapters (2 chars) */
"audhelp.HLP", /* Helpfile name (19 chars) */
"\0", /* Adapter specific dll name (19 chars) */
"\0", /* Adapter specific dll entry point (39 chars)*/
/**** Data for CONFIG.SYS **/
"1", /* Number of CONFIG.SYS lines (1 char) */
"DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*"
/* CONFIG.SYS Line 1 */
/* (255 chars after token substitution) */
/**** Data for INI File ****/
"3", /* Number of Drivers to Install (1 char) */
"Pro AudioSpectrum 16", /* Product name (39 chars) */
"1.0" /* Version of the adapter's software (5 chars)*/
"PAS16", /* PDD Name (6 chars) */
"MDM", /* MCD table name (19 chars) */
"\0" /* VSD table name (19 chars) */
END
RCDATA 12 This group of parameters is repeated for each driver you want to install. The repeated groups start with RCDATA 13, RCDATA 14, and so forth. ) These parameters indicate:
�The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMWAVEPAS1601).
�The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
�The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.
�The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD "AUDIOMCD."
�The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD "AUDIOIF."
�The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
�The name to be given to this driver's resources. Specifies a unique name for the management of the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different resource name for each driver. For more information, see Resource Units and Classes.
�The number of resource units supported by this driver. For more information, see Resource Units and Classes.
�The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see Resource Units and Classes.
�The resource classes. For more information, see Resource Units and Classes .
�The number of valid combinations of resource classes. The maximum is 81 combinations. For more information, see Resource Units and Classes.
�The valid resource class combinations. Resource class combinations are always listed in pairs. For example, if a class 1 can combine with a class 2, then class 2 can combine with class 1.
For more information, see Resource Units and Classes.
�The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as connectors. Connectors have defined connector types, and each connector type has an associated connector-type name.
�The connectors. Each connector has three values:
-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
-InstallName of the driver to which it connects. If left blank, a default connector is used.
-Sequential number of the connector to which it connects. The sample CARDINFO.RC file uses:
"3","IBMAMPMIXPAS16","1"
where:
3 Indicates the wave stream connector.
"IBMAMPMIXPAS16" Indicates the amplifier-mixer device.
1 Indicates the first connector of the amplifier-mixer device.
�The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .WAV extension is associated with an internal driver name, that driver will be used if a file ending in .WAV is opened.
�The file-name extensions associated with this driver.
�The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file's extended attribute. For example, if the "Digital Audio" extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of "Digital Audio" is opened.
�The AliasName given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second Waveform Audio driver would be given an AliasName of Digital Audio 2.
�Any device specific parameters. For the Waveform Audio driver, the following parameters set up the initial state of the adapter, and should be listed:
FORMAT= RIFF Datatype The RIFF Datatype is a format tab defined in \MMOS2\ MMTOOLKT\H\OS2MEDEF.H.
SAMPRATE= Indicates the sample rate.
BPS= Indicates the bits per second.
CHANNEL= Indicates mono (1) or stereo (2).
DIRECTION= Indicates PLAY or RECORD.
For the Audio AmpMixer driver, the following parameters set up the initial state of the adapter, and should be listed.
TREBLE= Indicates the treble setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
BASS= Indicates the bass setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
PITCH= Indicates the pitch setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
GAIN= Indicates the increase in level of output over the level of input setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
BALANCE= Indicates the BALANCE setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
VOL= Indicates the volume setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.
INPUT= Specifies LINE or MIC.
OUTPUT= Specifies SPEAKERS or HEADPHONES.
RESOURCEDLL= Specifies the name of the vendor-specific driver resource DLL that you create. For more information, see Step 2. Writing a Vendor- Specific Driver.
RCID Specifies the resource ID in the vendor-specific driver resource DLL that you create. For more information, see Step 2. Writing a Vendor- Specific Driver. For the Sequencer driver, the following parameters are listed:
CHANNELS= This parameter is followed by 16 1s or 0s to represent whether the sequencer's channels default to on (1) or off (0).
MIDITYPE= This parameter is followed by "General MIDI" if your adapter uses the General MIDI specification. If your adapter does not use General MIDI, you create a MIDI Map Table as specified in Step 9. Creating a MIDI Map. In this case, the parameter is followed by the adapter name. This name must be the same name used for "keyname" in the MIDIMAP.SCR file in Step 9. Creating a MIDI Map.
For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:
RCDATA 12
BEGIN
/ * * * * WAVEAUDIO Driver * * * * /
" IBMWAVEPAS16 " / * Installname ( 17 chars ) * /
" 7 " , / * Device type ( 3 chars ) * /
" 1 " , / * Device flag ( 3 chars ) * /
" AUDIOMCD " , / * MCD driver name ( 19 chars ) * /
" AUDIOIF " , / * VSD driver name ( 19 chars ) * /
" 3 " , / * Share Type ( 3 chars ) * /
" ProAudioSpecW " , / * Resource name ( 17 chars ) * /
" 1 " , / * # of Resource units ( 2 chars ) * /
" 1 " , / * # of Resource classes ( 2 chars ) * /
" 1 " , / * Resource classes ( 2 char each ) * /
" 0 " , / * # Valid resource class combos ( 2 chars ) * /
/ * Valid resource class combos ( 2 chars each ) * /
" 1 " , / * # of connectors ( 2 chars ) * /
" 3 " , " IBMAMPMIXPAS16 " , " 1 " , / * Connectors ( 2 chars ) , ( 17 chars ) , ( 2 chars ) * /
" 1 " , / * # of extensions ( 2 chars ) * /
" WAV " , / * Extension names ( 3 chars each ) * /
" Digital Audio " , / * Extended attribute ( 255 chars ) * /
" Digital Audio " , / * Alias Name ( 17 chars ) * /
" FORMAT = 1 , SAMPRATE = 22050 , BPS = 16 , CHANNELS = 1 , DIRECTION = PLAY "
/ * Device Specific Parameters ( 255 chars ) * /
END
RCDATA 19 This group of parameters indicates:
�The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the adapter. The maximum is 10 prompts.
�The title of the prompt text as it is displayed to the user.
�The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.
�The valid answers to your prompt. These answers are displayed to the user . The user can select one.
�The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user- friendly fashion and then place a more cryptic value in the CONFIG.SYS line .
For example, if you want to ask the user which song to play, you can use the following prompt:
Song to play on startup?
You can present the following choices to the user:
Happy Birthday Beethoven's Fifth Joy to the World
The values put into the CONFIG.SYS line could be "birthday.wav", "beet_5. wav", or "joyworld.wav".
�The default answer to the prompt. This is an index into the list of valid answers. For example, if the second answer is the default, specify "2". For an example of how to specify the RCDATA 19 parameters for this example, see Songs Example.
For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:
RCDATA 19
BEGIN
// Prompts for the User
"2", /* Number of prompts to ask user (2 chars) */
/* (max 10 prompts) */
// Prompt 1
"DMA Channel", /* Title of Prompt (max 50 chars) */
"7", /* # of valid values (2 chars) */
"0","1","2","3", /* Valid values (20 chars each) */
"5","6","7",
"0","1","2","3", /* Corresponding config.sys values */
"5","6","7", /* (20 chars each) */
"4", /* Default value - Index into valid values */
/* (2 chars) */
// Prompt 2
"Interrupt Level", /* Title of Prompt (max 50 chars) */
"8", /* # of valid values (2 chars) */
"Interrupt 2", /* Valid values (20 chars each) */
"Interrupt 3",
"Interrupt 5",
"Interrupt 7",
"Interrupt 10",
"Interrupt 11",
"Interrupt 12",
"Interrupt 15",
"2", /* Corresponding config.sys values */
"3", /* (20 chars each) */
"5",
"7",
"10",
"11",
"12",
"15",
"6" /* Default value - Index into valid values */
/* (2 chars) */
END
Songs Example
The following is an example of how to specify RCDATA 19 parameters to ask a user what song to play:
RCDATA 19
BEGIN
// Prompts for the User
"1", /* Number of prompts to ask user (2 chars) */
/* (max 10 prompts). */
// Prompt 1
"Song to play on startup?", /* Title of prompt (max 50 chars). */
"3", /* Number of valid values (2 chars). */
"Happy Birthday" /* Valid values (20 chars each). */
"Beethoven's Fifth"
"Joy to the World"
"birthday.wav" /* Corresponding CONFIG.SYS values */
"beet_5.wav" /* (20 chars each) */
"joyworld.wav"
"2", /* Default value - Index into valid values */
/* (2 chars) */
END
Step 4. Creating an Audio Installation DLL
In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic audio installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.
The audio installation program calls your DLL and allows it to return values that can be added to your lines in the CONFIG.SYS file. The following steps describe how to use your DLL:
1.Write and compile the DLL.
The entry point to your DLL must accept the following parameters:
CardSpecDLLEntry (USHORT usCardNum,
CHAR achSpec[259])
where:
usCardNum Is the sequential number of this adapter.
For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.
achSpec[5][259] Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The audio installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:
achSpec[0]="rec" achSpec[1]="3" achSpec[2]="11" achSpec[3]="" achSpec[4]=""
The format of your CONFIG.SYS line in CARDINFO.RC is:
"DEVICE=*PATH*\\MVPRODD.SYS *SPEC* *SPEC* *SPEC*"
The line that is put into CONFIG.SYS is:
DEVICE=D:\MMOS2\MVPRODD.SYS rec 3 11
2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.
Step 5. Modifying the AUDHELP.ITL File
AUDHELP.ITL is a help file that gives information to the user when the user installs the audio adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.
Step 6. Running the MAKEFILE
The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.
Step 7. Modifying the CONTROL.SCR File
You must modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL what subsystems and devices that the user can install.
Modify the following fields in the Audio Adapter Group:
Note:Do not change the fields notlisted here.
ssgroup Specifies the audio adapter group number. The only reason you might need to change this number is if you are installing more than one type of adapter. If you install more than one type of adapter, you must duplicate the entire audio adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.
ssname Specifies the audio adapter's name.
ssversion Specifies the version number of the device driver.
sssize Specifies the total size (in KB) of the device drivers, the AUDHELP. HLP help file, GENIN.DLL, GENINMRI.DLL, and any other files you install.
ssdllinputparms Matches the ID number used in CARDINFO.RC.
Specifies the MIDI map table. Uncomment this line if you create a MIDI map in Step 9.
Step 8. Modifying the AUDFILES.SCR File
Modify the AUDFILES.SCR file so that it lists all the files your adapter uses. AUDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.
After changing the list of files in AUDFILES.SCR, change the "Total Number of Files to Copy" in AUDFILES.SCR to match the number of files you have listed.
Step 9. Creating a MIDI Map
If the audio adapter uses the General MIDI specification, this step is not necessary. When MMPM/2 plays a MIDI file, it maps the patch assignments according to the General MIDI specification. If the audio adapter uses a patch assignment other than General MIDI, you must create a MIDI map table to tell MMPM/2 how to map the patches.
The following steps describe how to create a MIDI map:
1.Modify the MIDIMAP.RC file to hold the MIDI map table.
The MIDIMAP.RC file holds a sample MIDI map table. Modify this table to describe the adapter. The data in MIDIMAP.RC is defined by the MIDITYPE structure. This structure is defined in the MIDITYPE.H file.
typedef struct {
USHORT uGenMidiPatchNumber; /* Device To General MIDI Conversion */
USHORT uDevMidiPatchNumber; /* General MIDI to Device Conversion */
USHORT uVolumePercent; /* Channel Patch Volume Scaler */
USHORT uGenMidiKeyNumber; /* Device To General MIDI Key Conversion */
USHORT uDevMidiKeyNumber; /* General MIDI to Device Key Conversion */
} MIDITYPEENTRY;
typedef MIDITYPEENTRY FAR * PMIDITYPEENTRY;
typedef struct {
USHORT uStyle; /* MIDI Mapping Style */
USHORT uDrums10; /* Patch for Percussion Channel 10 */
USHORT uDrums16; /* Patch for Percussion Channel 16 */
ULONG ulReserved; /* Reserved */
MIDITYPEENTRY MidiTypeEntry[128]; /* Array of MIDITYPEENTRYs */
CHAR szPatchAndPercKeyName[2*128*40];
/* List of 128 Patch Names */
/* that are null terminated, then a */
/* list of 128 Percussion key names */
/* that are double null terminated */
/* Each item is null terminated */
} MIDITYPE;
typedef MIDITYPE FAR * PMIDITYPE;
The uStylefield specifies flags that indicate the type of mapping that is required in order to translate from general MIDI to a specific device.
The MT_PERCUSSIONKEYS flag indicates that the device supports percussion keys and that the percussion keys will be translated according to the key conversion tables. If percussion keys are not supported by the MIDI device and MT_MAPPERCKEYPATCHES is specified, then patches on percussion channels will be mapped to the patch indicated in uDrums10or uDrums16. This will enable the mapper to map patch changes on a percussion channel to a drum patch. Individual percussion sounds cannot be mapped but a percussive sound will be heard.
Included in the MIDITYPE data structure is an array of MIDITYPEENTRY structures. This structure includes information for mapping patches and percussion keys between general MIDI and the particular MIDI device.
uGenMidiPatchNumber Describes the mapping of the nth Patch number from the devices patch assignments to general MIDI patch assignments.
uDevMidiPatchNumber Describes the mapping of the nth patch number from the general MIDI patch assignments of the device.
uRelativeVolume Describes the relative volume of the nth patch when mapping from general MIDI to the specified MIDI device.
uGenMidiKeyNumber Describes the mapping of the nth percussion key number from the devices percussion key assignments to general MIDI percussion key assignments.
uDevMidiKeyNumber Describes the mapping of the nth percussion key number from general MIDI percussion key assignments to the devices percussion key assignments.
szPatchAndPercKeyName Lists patch names for each of 128 patches for this MIDI device. Each name is null terminated and the list is double-null terminated. Following the list of patch names is the list of percussion key names for each of 128 keys. These names can eventually be used in a user interface.
2.Modify the MAKEFILE to build the MIDIMAP.RC file into a resource file.
At the end of the MAKEFILE, there is a group of commands that are commented out. These are the commands that build MIDIMAP.RC into MIDIMAP.DLL. Take the comment character (#) off the beginning of each of these lines.
Also in the MAKEFILE are two lines that begin with the word "all." These should be near the 83rd line. Take the comment character (#) off the beginning of the second line and add a comment character (#) to the beginning of the first line. These lines tell the MAKEFILE which targets to build.
3.Run the MAKEFILE to create the MIDIMAP.DLL resource file.
4.Modify the .INI change file called MIDIMAP.SCR.
In MIDIMAP.SCR, change the keyname from "Your Adapter" to the name of the adapter. This file tells the installation program to install the MIDI map table contained in MIDIMAP.DLL into MMPM/2's MIDITYPE.INI file.
5.Modify the CARDINFO.RC file to name your MIDI map.
In the device-specific parameters field for the Sequencer driver, there is a parameter called MIDITYPE. Set this parameter to the same name used in the MIDIMAP.SCR file in Step 5. For example, you could use MIDITYPE=Your Adapter.
Note:Make sure that you use the exact spelling (including capitalization) as in MIDIMAP.SCR.
6.Modify CONTROL.SCR so that it calls MIDIMAP.SCR.
The last line of the CONTROL.SCR file contains a line that is commented out . Take the comment characters (/* */) off of this line. This removal causes the installation program to run MIDIMAP.SCR during installation.
7.Modify AUDFILES.SCR to add the MIDIMAP.DLL file.
In the AUDFILES.SCR file, the last file listed is MIDIMAP.DLL. This file is commented out. Remove the comment characters (/*) at the beginning of the line so that your MIDI map file is copied. Increment the number of files at the top of AUDFILES.SCR.
Step 10. Creating the Installation Diskette
Create a diskette that contains the following files:
�CONTROL.SCR
�AUDFILES.SCR
�MIDIMAP.SCR (if you created one)
�MIDIMAP.DLL (if you created one)
�CARDINFO.DLL
�AUDHELP.HLP
�GENIN.DLL
�GENINMRI.DLL
�Your device drivers
Step 11. Using MINSTALL to Install Your Adapter
You can test your installation diskette before sending it to your customers by running MINSTALL.
Before installing the audio adapter, the base MMPM/2 that comes with OS/2 2 .1 (or later) must be installed.
After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:
1.Place the installation diskette in drive A.
2.Type MINSTALLon the OS/2 command line.
3.Change the source drive to A.
4.Select the adapter.
5.If errors occur, check the MINSTALL.LOG file in the \MMOS2\INSTALL subdirectory for error messages.
Video Adapter Installation
MMPM/2 allows installation of device drivers developed for video adapters into the MMPM/2 video subsystem using a generic video installation program.
This DDK provides a generic video installation program that performs the following functions:
�Asks the user for any information needed to install your adapter, such as the interrupt level.
�Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.
�Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.
�Copies the files needed by your adapter, such as device drivers.
The following steps provide an overview of how to install a device driver into the MMPM/2 video subsystem so that it can be used by the Digital Video Recorder to record software motion video. The \MMOS2\MMTOOLKT\SAMPLES\ VIDINST subdirectory provides the generic video installation sample files. For more information about the VIDINST files, see Source Code.
Source Code
The \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory provides the installation sample files for a video device driver. These sample files illustrate how to install a video device driver into the MMPM/2 video subsystem. The sample files include:
/-------------------------------------------------------------\ |Sample File |Description | |-------------------------+-----------------------------------| |MAKEFILE |Creates the resource DLL containing| | |the video adapter information by | | |compiling the CARDINFO.RC file into| | |the CARDINFO.DLL file. This file | | |also compiles the VIDHELP.ITL file | | |into the VIDHELP.HLP help file. | |-------------------------+-----------------------------------| |CARDINFO.RC |Supplies information about the | | |video adapter. | |-------------------------+-----------------------------------| |RCSTUB.C |Stub 'C' file for compiling | | |CARDINFO.RC. | |-------------------------+-----------------------------------| |VIDHELP.ITL |Contains the help information. | |-------------------------+-----------------------------------| |CONTROL.SCR |Contains the control information | | |used by MINSTALL to install the | | |video adapter. | |-------------------------+-----------------------------------| |VIDFILES.SCR |Lists the files to be copied by | | |MINSTALL. MINSTALL also copies | | |this file. | \-------------------------------------------------------------/
Note:Before modifying any of these files, make sure you have a backup copy.
More detailed information about each step is provided in the following sections. The steps must be performed in the order listed.
To add a video capture adapter to the MMPM/2 video subsystem, follow these steps:
1.Create an OS/2 device driver for the video capture adapter.
For information on creating an OS/2 device driver, refer to the OS/2 Physical Device Driver Reference.
2.Modify the CARDINFO.RC file.
This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.
For more information, see Step 2. Modifying the CARDINFO.RC File.
3.If necessary, create a DLL to perform actions not provided by this generic video installation program.
This step is not necessary, unless you want to perform some action that is not supported by the generic video installation program. For more information, see Step 3. Creating a Video Installation DLL.
4.Modify the VIDHELP.ITL file.
This file contains information that is presented to the user when installing your adapter.
For more information, see Step 4. Modifying the VIDHELP.ITL File.
5.Run the MAKEFILE.
This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.
For more information, see Step 5. Running the MAKEFILE.
6.Modify the CONTROL.SCR file.
This file is the control file used by MINSTALL to determine what subsystems and devices a user can install.
For more information, see Step 6. Modifying the CONTROL.SCR File.
7.Modify the VIDFILES.SCR file.
This file lists the files the adapter uses. It tells MINSTALL which files need to be copied, and into which subdirectories to place them.
For more information, see Step 7. Modifying the VIDFILES.SCR File.
8.Create an installation diskette.
This diskette must contain all the files necessary to install the adapter into the MMPM/2 video subsystem using MINSTALL.
For more information, see Step 8. Creating the Installation Diskette.
9.Install your adapter using MINSTALL.
For more information, see Step 9. Using MINSTALL to Install Your Adapter.
Step 1. Creating an OS/2 Device Driver
For information on creating an OS/2 device driver, refer to the OS/2 Physical Device Driver Reference.
Step 2. Modifying the CARDINFO.RC File
The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory. Modify this file so that it contains information relevant to your video adapter. MMPM/2 uses this information to interface with the adapter.
Notes:
1.The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.
2.If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.
3.If the video adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string "/0" in the parameter.
The CARDINFO.RC parameters are:
RCDATA 1 Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of video adapter, place that number in this parameter.
For example, in the CARDINFO.RC file, the Video Blaster adapter is:
RCDATA 1 BEGIN "1" /* Number of adapters in this rc file */ END
RCDATA 10 Contains two parameters, the ID number and type of adapter used in the CONTROL.SCR file. The ID number can be any number. However, it must match the ssdllinputparmskeyword in the CONTROL.SCR file that is modified in Step 6. Modifying the CONTROL.SCR File. For the type of adapter, the only valid value is "vca."
For example, in the CARDINFO.RC file, the Video Blaster adapter is:
RCDATA 10 BEGIN "33", /* ID number of this adapter */ "vca" /* Type of adapter */ END
RCDATA 11 Contains parameters that indicate:
�The maximum number of this type of video adapter that can be installed at one time. The maximum is six adapters.
�The name of the help file that describes the video adapter. This name defaults to VIDHELP.HLP if the MAKEFILE provided to create the help file is used.
�The name of the video-adapter-specific DLL you wrote to perform functions not provided by this generic video installation program. This DLL is described in Step 3. Creating a Video Installation DLL. If you did not write a DLL, specify "\0."
�The name of the video-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify "\0."
�The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the video adapter. The maximum is six lines.
�The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file. Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:
- PATH* Indicates the path where MMPM/2 was installed (for example, c:\MMOS2 ).
- ORD* Indicates the device ordinal of this adapter.
- SEQ* Indicates the sequential number of this adapter. For example, if the user installs two IBM video capture adapters, the first will have a number of 1 and the second a number of 2.
- PDD* Indicates the PDDName of this adapter.
- VAL* Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.
Note:Later in the CARDINFO.RC file, you specify which questions the install program should ask.
- SPEC* Indicates special values passed from your adapter-specific DLL.
For example, the line in the sample CARDINFO.RC file is:
"DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*"
After the real values are substituted, the CONFIG.SYS line is similar to:
DEVICE=C:\MMOS2\VIDVBC.SYS /0F00000 /2AD6 /I5 /1
�The number of drivers to install into the MMPM/2 system. For a video capture adapter, this would normally be 1 because a Digital Video driver is the only driver installed. The maximum is six drivers.
�The name of the adapter as it is displayed to the user.
�The version number of the device driver.
�The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a "$" is added to this name to form the final PDDName. For example, if the user installs two Video Blaster** Adapters, the PDDNames are VIDVBC1$ and VIDVBC2$.
�The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.
�The name of the VSD command table used by the drivers. In most cases, this is blank.
For example, in the CARDINFO.RC file, the Video Blaster adapter is:
RCDATA 11
BEGIN
"1", /* Max number of adapters (2 chars) (6 max) */
"vidhelp.hlp", /* Helpfile name (19 chars) */
"\0", /* Adapter specific dll name (19 chars) */
"\0", /* Adapter specific dll entry point (39 chars)*/
/**** Data for CONFIG.SYS **/
"1", /* Number of CONFIG.SYS lines (1 char) */
"DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*",
/* CONFIG.SYS Line 1 */
/* (255 chars after token substitution) */
/**** Data for INI File ****/
"1", /* Number of Drivers to Install (1 char) */
"Video Blaster", /* Product name (39 chars) */
"1.0.0", /* Version of the adapter's software (6 chars)*/
"VIDVBC", /* PDD Name (5 chars) */
"MDM", /* MCD table name (19 chars) */
"\0" /* VSD table name (19 chars) */
END
RCDATA 12 This group of parameters is repeated for each driver you want to install. The repeated groups should start with RCDATA 13, RCDATA 14, and so forth. These parameters indicate:
�The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMDIGVIDCVB01).
�The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
�The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.
�The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD 'SVMC'.
�The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD 'VIDVCI'.
�The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
�The name to be given to this driver's resources. Specifies a unique name for the management for the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different name for each driver. For more information, see Resource Units and Classes.
�The number of resource units supported by this driver. For more information, see Resource Units and Classes.
�The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see Resource Units and Classes.
�The resource classes. For more information, see Resource Units and Classes .
�The number of valid combinations of resource classes. For more information , see Resource Units and Classes.
�The valid resource class combinations. Resource class combinations are always listed in pairs.
Note:This field is not in the sample because Video Blaster does not have any valid resource class combinations. If it did, the combination would be listed similar to this:
"1","2", (One combines with two) "2","1", (Two combines with one)
For more information, see Resource Units and Classes.
�The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as connectors. Connectors have defined connector types, and each connector type has an associated connector-type name.
�The connectors. Each connector has three values:
-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.
-InstallName of the driver to which it connects. If left blank, a default connector is used.
-Sequential number of the connector to which it connects.
The sample CARDINFO.RC file uses:
"3","","1"
where:
3 Indicates the wave stream connector.
"" Indicates the default WaveAudio device.
1 Indicates the first connector of the WaveAudio device.
�The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .AVI extension is associated with an internal driver name, that driver will be used if a file ending in .AVI is opened.
�The file-name extensions associated with this driver.
Note:This field is not used in the sample because no extensions are associated with the driver for Video Blaster. If there were extensions, they would be listed like the following:
"AVI", "AVS"
�The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the files extended attribute . For example, if the "Digital Video" extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of "Digital Video" is opened.
�The AliasName given to the driver. This is an alternate name given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second DigitalVideo device would be given an AliasName of Digital Video 2.
�Any device specific parameters. These parameters allow you to provide additional information about the driver to the MCD. In most cases, this is blank.
For example, in the CARDINFO.RC file, the Video Blaster adapter is:
RCDATA 12 BEGIN /**** DIGITAL VIDEO Driver ****/ "IBMDIGVIDCVB", /* Installname (17 chars) */ "12", /* Device type (3 chars) */ "1", /* Device flag (3 chars) */ "SVMC", /* MCD driver name (19 chars) */ "VIDVCI", /* VSD driver name (19 chars) */ "3", /* Share Type (3 chars) */ "Video Blaster", /* Resource name (17 chars) */ "10", /* # of Resource units (2 chars) */ "2", /* # of Resource classes (2 chars) */ "10","1", /* Resource classes (2 char each) */ "0", /* # Valid resource class combos (2 chars) */ /* No combos */ /* Valid resource class combos (2 chars each) */ "1", /* # of connectors (2 chars) */ "3","","1", /* Connectors (2 chars), (17 chars), (2 chars)*/ "0", /* # of extensions (2 chars) */ /* no extension names */ /* Extension names (3 chars each) */ "\0", /* Extended attribute (255 chars) */ "Digital Video", /* Alias Name (17 chars) */ "\0" /* Device Specific Parameters (255 chars) */ END
RCDATA 19 This group of parameters indicate:
�The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the user's adapter. The maximum is 10 prompts.
�The title of the prompt text as it is displayed to the user.
�The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.
�The valid answers to your prompt. These answers are displayed to the user . The user can select one.
�The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user- friendly fashion and then place a more cryptic value in the CONFIG.SYS line .
For example, you can ask the user if they want to run a hardware test on startup with the following prompt:
Run hardware test on startup?
The valid answers that you present to the user could be:
Yes No
The valid values that could be put into the CONFIG.SYS line could be "test" or "notest."
�The default answer to the prompt. This is an index into the list of valid answers. For example, if the first answer is the default, specify "1." For an example of how to specify the RCDATA 19 parameters for this example, see Startup Example.
For example, in the CARDINFO.RC file, the Video Blaster adapter is:
RCDATA 19
BEGIN
// Prompts for the User
"3", /* # Number of prompts to ask user (3 chars) */
/* (max 10 prompts) */
// Prompt 1
"Frame Buffer Base Address",/* Title of Prompt (max 50 chars) */
"8", /* # of valid values (2 chars) */
"0F00000", /* Valid values (20 chars each) */
"0E00000",
"0D00000",
"0C00000",
"0B00000",
"0A00000",
"0900000",
"0800000",
"1", /* Default value - Index into valid values */
/* (2 chars) */
// Prompt 2
"Base I/O Address", /* Title of Prompt (max 50 chars) */
"3", /* # of valid values (2 chars) */
"2AD6", /* Valid values (20 chars each) */
"2A90",
"2AF0",
"1", /* Default value - Index into valid values */
/* (2 chars) */
// Prompt 3
"Interrupt", /* Title of Prompt (max 50 chars) */
"4", /* # of valid values (2 chars) */
"I5",
"I10", /* Valid values (20 chars each) */
"I11",
"I12",
"2" /* Default value - Index into valid values */
/* (2 chars) */
END
Startup Example
The following is an example of how to specify RCDATA 19 parameters to ask a user if they want to run a hardware setup test:
RCDATA 19
BEGIN
// Prompts for the User
"1", /* Number of prompts to ask user (3 chars) */
/* (max 10 prompts). */
// Prompt 1
"Run hardware test on startup",/* Title of Prompt (max 50 chars). */
"2", /* Number of valid values (2 chars). */
"yes" /* Valid values (20 chars each). */
"no"
"test" /* Corresponding CONFIG.SYS values */
"notest" /* (20 chars each). */
"1", /* Default value - Index into valid values */
/* (2 chars). */
END
Step 3. Creating a Video Installation DLL
In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic video installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.
The video installation program calls your DLL and allows it to return values that can be added to the CONFIG.SYS file. The following steps describe how to use your DLL:
1.Write and compile the DLL.
The entry point to your DLL must accept the following parameters:
CardSpecDLLEntry (USHORT usCardNum,
CHAR achSpec[5][259])
where:
usCardNum Is the sequential number of this adapter.
For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.
achSpec[5][259] Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The video installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:
achSpec[0]="rec" achSpec[1]="3" achSpec[2]="11" achSpec[3]="" achSpec[4]=""
The format of your CONFIG.SYS line in CARDINFO.RC is:
DEVICE=*PATH*\\VIDVBC.SYS *SPEC* *SPEC* *SPEC*
The line that is put into CONFIG.SYS is:
DEVICE=D:\MMOS2\VIDVBC.SYS rec 3 11
2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.
Step 4. Modifying the VIDHELP.ITL File
VIDHELP.ITL is a help file that gives information to the user when the user installs the video adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file, because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.
Step 5. Running the MAKEFILE
The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.
Step 6. Modifying the CONTROL.SCR File
Modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL which subsystems and devices that the user can install.
Modify the following fields in the Video Adapter Group:
Note:Do not change the fields not listed here.
ssgroup Specifies the video adapter group number. The only reason to change this number is if you are installing more than one video adapter. If you install more than one type of adapter, you must duplicate the entire video adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.
ssname Specifies the video adapter's name.
ssversion Specifies the version number of your device driver.
sssize Specifies the total size (in KB) of your device drivers and the VIDHELP.HLP help file.
ssdllinputparms Matches the ID number used in CARDINFO.RC.
Step 7. Modifying the VIDFILES.SCR File
Modify the VIDFILES.SCR file so that it lists all the files the adapter uses. VIDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.
After changing the list of files in VIDFILES.SCR, change the "Total Number of Files to Copy" in VIDFILES.SCR to match the number of files you have listed.
Step 8. Creating the Installation Diskette
Create a diskette that contains the following files:
�CONTROL.SCR
�VIDFILES.SCR
�CARDINFO.DLL
�VIDHELP.HLP
�Your device drivers
Step 9. Using MINSTALL to Install Your Adapter
You can test your installation diskette by running MINSTALL. Before installing the video adapter, you must install:
�OS/2 Version 2.1 (or later)
�MMPM/2
�The files that came with this DDK.
After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:
1.Place the installation diskette in drive A.
2.Type MINSTALL.
3.Change the source drive to A.
4.Select the adapter.
5.If errors occur, check the \MMOS2\INSTALL\MINSTALL.LOG file.
Resource Units and Classes
Device contexts are managed by the Media Device Manager (MDM), using an abstract concept of resource units, resource classes, and valid class combinations.
Resource units provide a measurement for the resource manager to determine how many device contexts can be active at any given time. Each device specifies how many resource units it can process concurrently.
In addition to a total resource number, each resource class has a maximum number of resource units available to it. This allows the MDM to determine how many device contexts from a particular class can be active concurrently . During the installation procedure the maximum numbers are provided.
On the MCI_OPEN of a device context the required resource units and class for the device context is returned in the MMDRV_OPEN_PARMS structure. The required resource units and resource class of a device context can be changed by the MCD by calling the MDM with the MCIDRV_CHANGERESOURCE message. For example, if a waveaudio device allocated one resource unit for a mono wave and two units for a stereo wave, then a load command might change the required units for that device context.
The final piece of resource management is provided during installation. This piece is the valid class combinations. A certain device might have multiple classes but might not allow certain classes to have active device contexts concurrently.
For further information on Resource Units and Classes, refer to the OS/2 Multimedia Subsystem Programming Guide
Audio Physical Device Driver Template
This DDK provides two working samples for writing your own audio physical device drivers for the MMPM/2 environment:
�For wave audio/midi, the Turtle Beach "Tropez Plus" device driver. See the document "Object-oriented OS/2 Audio Device Driver Sample" which resides on the DDK Web page for details.
�For wave audio, the IBM-written AD1848 Business Audio device driver.
These samples include all the code required for communication with MMPM/2- including establishing communication with MMPM/2, controlling specific hardware devices, and establishing inter-device driver (IDC) communications with the MMPM/2 stream handlers and IOCtl-based communications with the MMPM/2 amplifier-mixer (ampmix) and media control drivers (MCDs).
Note:For further information on when to use a physical device driver (PDD ) and how it operates, see the online OS/2 Physical Device Driver Referenceprovided in this package. This reference describes the types of physical device drivers, their interfaces, and available system services.
PDD Architecture
The MMPM/2 audio PDD is a standard OS/2 PDD. Audio PDDs have two entry points for communication with the system. The OS/2 device driver standard strategy entry point is used for open/close and setup operations-received from application-level components. Data movement is done via Ring-0 interdevice driver (IDC) interface. These interfaces provide the foundation for sharing of the audio device by MMPM/2 applications and media drivers.
The audio IOCtls are standard OS/2 IOCtls. Definitions follow in this chapter. Media drivers running at Ring 3 use the IOCtl interface to set up the audio device sample rate, for access, to change volume controls, and so on. The IOCtl interface is not meant to be used to send audio data to the device driver.
The IDC interface is standard 16:16 to 16:16 for procedure calls, initiated by the OS/2 AttachDD DevHlp function. Stream handler device drivers and audio physical device drivers use the IDC interface to communicate with one another to coordinate their efforts to stream data to and from the audio device.
The following graphic shows the audio physical device driver architecture. [Artwork not shown]
The IDC Interface
Two entry points are provided for the two device drivers participating in the IDC interface, DDCMDEntryPointand SHDEntryPoint. DDCMDEntryPointallows the stream handler device driver to call to the PDD, and SHDEntryPointallows the audio PDD to call to the stream handler.
Note that streaming data buffer pointers are passed by the Sync/Stream Manager to the audio stream handler by means of Sync/Stream Manager Helper (SMH) calls. Then the audio stream handler passes pointers to the PDD using device driver command (DDCMD) messages.
The following graphic shows the audio physical device driver modules. [Artwork not shown]
Communication to the PDD
DDCMD Messagesare defined from the DDCMDEntryPoint. Each message represents a specific request by the stream handler for the audio PDD to perform an action.
Read and write messages allow the stream handler to get and receive data directly from the PDD without any intervention required by the application. The application neither has to send data through an IOCtl nor allocate and lock memory to perform data transfers.
Communication to the Stream Handler
The SHDEntryPointcontains the following two messages. These messages are located in the SHDD.H file of the \MMOS2\MMTOOLKT\H subdirectory. SHDD.H contains the data structures, their type definitions, and #define statements for certain values. Note that the messages pass pointers to packets of data, to allow maximum flexibility for the future.
SHD_REPORT_INTThe PDD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler it has used up all the data and needs more.
When the stream handler gets the call, it knows the PDD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the PDD a fresh buffer to consume.
SHD_REPORT_EVENTThe stream handler uses this message to keep in sync with PDD activities. For example, the stream handler can request the PDD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The PDD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the PDD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the PDD returns.
The PDD keeps track of the processes. In other words, only the PDD knows how much data, to the millisecond, has been played out to the device. The stream handler can approximate the data played, using calculations based on how much data has gone by. But the stream handler cannot calculate the data played to the millisecond, or even to the fraction of a millisecond, the way the PDD can.
Stream Handler Values
There are certain values that the stream handler is expecting. For example , when the stream handler requests a stop or a pause on a DDCMD_CONTROLmessage, the pointer that comes back to the stream handler is a pointer to the cumulative time that the PDD has recorded in real time. So whenever the stream handler requests the device to stop, the PDD honors that request and informs the stream handler the real time that the PDD stopped within the stream.
Another value the stream handler looks for is returned on DDCMD_STATUS. This is also a pointer to the cumulative time from the PDD, with respect to when that stream was first started at the stream handler's request.
PDD Values
The stream handler passes a pointer to the PDD on DDCMD_STATUS. This points to a value used by the PDD for setting the referenced time of the PDD. It is not always correct for the PDD to start its time at 0 every time the stream handler does a start, because the stream handler might have performed a seek in the stream. The PDD might have played a minute of data and then performed a backwards seek to the 30-second mark in the data. If a start is issued, the PDD should start from the 30-second mark in that stream.
DDCMD_CONTROLhas an important NOTIFY subfunction, which is used for cuepoint or event detection. The stream handler supports events in cuepoints-an application request to be notified when a particular location in the file is reached or a specific time period has elapsed. The stream handler uses two methods for detecting how much time has elapsed:
�Using DDCMD_CONTROL NOTIFY, the stream handler requests to be notified by the PDD at a particular time and passes a pointer to the cue time.
�The stream handler determines the time internally. This method is not as precise as the first method, because only the PDD knows the real time.
For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the PDD supports precise event detection, it must accept this request and put it into a queue somewhere, preferably a linked list. This linked list will have the time of one minute so that during the streaming process, the PDD occasionally checks to see whether it is at the one minute mark. When this event occurs, the PDD calls back on an SHD_REPORT_EVENT. Then you can free up the event detection linked list node.
Keep in mind that the PDD should have the capability to queue these requests because there might be additional requests. For example, an application might request to be notified at the one-minute mark, next at a minute and a half, and possibly every five minutes.
If the PDD does not support event detection, then when it gets called on a DDCMD_CONTROL NOTIFY, it responds with an ERROR_INVALID_REQUEST. This response tells the stream handler that it must do the event-detection itself.
Source Code for the Object-oriented Audio Device Driver
Source code for the object-oriented audio device driver, TROPEZ.SYS, which supports the Turtle Beach "Tropez Plus" audio card is located on the DDK Web page. Documentation describing the driver sample can be viewed with a browser at the following Web page:
http://service.boulder.ibm.com/ddk/
Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.
Source Code for AD1848 PDD
Source code for the AD1848 device driver is located in the \MMOS2\MMTOOLKT\ SAMPLES\AD1848 subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.
/-------------------------------------------------------------\ |Source File |Description | |-------------------------+-----------------------------------| |AD1848.C |This file contains functions that | | |interface with the Analog Device | | |stereo codec AD1848. | |-------------------------+-----------------------------------| |AUDCONT.C |This file contains functions that | | |support audio control commands from| | |the DosDevIoctl interface to the | | |device driver. | |-------------------------+-----------------------------------| |DMA.C |This file contains routines that | | |support DMA services. | |-------------------------+-----------------------------------| |HEADER.C |This file contains device driver | | |header information. | |-------------------------+-----------------------------------| |MEM.C |This file contains functions | | |related to dynamic memory | | |allocation. | |-------------------------+-----------------------------------| |PARAM.C |This file contains routines that | | |parse parameters from the device | | |assignment statement in the | | |config.sys file. | |-------------------------+-----------------------------------| |PRINTF.C |This file contains routines to | | |implement C printf functions for | | |writing messages to console during | | |initialization and to COM: port | | |during execution for debugging. | | |COM: support is ifdefed out of | | |driver for production builds. | |-------------------------+-----------------------------------| |STRATEGY.C |This file contain the routine that | | |services the device driver strategy| | |entry point and routines that | | |support the vdd interface. | |-------------------------+-----------------------------------| |STRING.C |This file contains miscellaneous | | |string utility functions. | |-------------------------+-----------------------------------| |STRMCONT.C |This file contains functions that | | |service requests from the audio | | |stream handler and report events to| | |the audio stream handler. | |-------------------------+-----------------------------------| |STRMHELP.C |This file contains routines that | | |support stream related services. | |-------------------------+-----------------------------------| |TIMER.C |This file contains miscellaneous | | |time related functions. | |-------------------------+-----------------------------------| |TRACE.C |This file contains routines that | | |support the data logging facility | | |used for device driver debugging | | |and performance analysis. | |-------------------------+-----------------------------------| |AUDCONT.H |This file contains prototypes for | | |public functions originating in | | |AUDCONT.C | |-------------------------+-----------------------------------| |DEVHELP.H |This file contains prototypes for | | |public functions in DEVHLP.ASM. | |-------------------------+-----------------------------------| |DEVICE.H |This file contains definitions for | | |shared constants and prototypes for| | |public functions that originate in | | |DEVICE.C. | |-------------------------+-----------------------------------| |DMA.H |This file contains prototypes for | | |public functions and definitions | | |for shared constants originating in| | |DMA.C. | |-------------------------+-----------------------------------| |ECHO.H |This file contains prototypes for | | |public functions originating in | | |ECHO | |-------------------------+-----------------------------------| |END.H |This file contains prototypes for | | |public functions in END.C. | |-------------------------+-----------------------------------| |DEVHLP.ASM |This file contains routines that | | |support device driver helper | | |services from the operating system.| |-------------------------+-----------------------------------| |ENTRY.ASM |This file contains functions that | | |support all the entry points into | | |the driver. | |-------------------------+-----------------------------------| |UTIL.ASM |This file contains miscellaneous | | |utility functions for io port data | | |transfer, memory data transfer, and| | |address manipulation. | \-------------------------------------------------------------/
Data Transfers
Following are the two methods of transferring data:
Direct Memory Access (DMA) The most efficient way to transfer data from the host system to the audio adapter's memory is through direct memory access ( DMA). This is a technique for moving data directly between main storage without requiring processing of the data by the CPU. To accomplish this, we create a DMA buffer within the device driver to transfer the data. As the device driver receives the stream buffer data, it copies the stream buffer data into the DMA buffer at interrupt time. When the DMA buffer is full, it can be sent directly to the audio device. A preferable (but unproven) method would be to DMA directly from the stream buffer. Currently, however, a copy operation (which requires time and CPU utilization) is required to get data into the AUDIODD DMA buffer.
To perform direct memory access, you are essentially programming the DMA microcontroller on the system board. For each direct memory access, you can DMA transfer data up to the limit of the DMA channel that the audio adapter is using:
- 64KB for the 8-bit DMA channels 0, 1, and 3
- 128KB for the 16-bit DMA channels 5, 6, and 7
Note that this DMA transfer must always be from the same buffer pointer. Unless you decide to change the buffer pointer, you would have to reprogram the microcontroller from the beginning.
Therefore, if you want to DMA directly from the stream buffer, your device driver would always require a different pointer which means reprogramming the DMA controller at each interrupt. So, each time you get a new buffer from the stream handler, you would have to look at the pointer, reprogram the DMA controller, and then start the DMA transfer. At this stage, most developers state that there is not enough time to reprogram the DMA controller during interrupt time. Therefore, they are creating one DMA buffer when the device driver is initialized at system startup. The developer programs the DMA controller at that point, informs the controller that this is the pointer, and tells it how much data the device driver is going to transfer. The value is set for the lifetime of the driver.
Dual DMA Buffers
MMPM/2's stream handler implementation uses two DMA buffers or dual DMA buffersto ensure a smooth flow of audio data.
In this implementation, the amplifier-mixer (ampmix) device issues a request through the OS/2 kernel to the audio PDD for it to prepare to process audio data. The audio PDD informs the stream handler that it needs the audio data, and the stream handler informs the file system PDD to fill two 4KB DMA buffers with the appropriate audio data.
When the audio PDD processes the first 4KB buffer, it issues a hardware interrupt that signals the file system PDD to replace the first 4KB buffer with the next 4KB of audio data. Meanwhile, the audio PDD is processing the second 4KB buffer. When the audio PDD processes the second 4KB buffer, it issues a hardware interrupt again and the process is repeated.
With this process, you only have to track two DMA buffers and the stream handler ensures a smooth flow of audio data to the audio PDD. The following illustration provides an overview of this process.
1st 4KB DMA 2nd 4KB DMA
/---------------------------\
/---�| | |
| | | |
| \---------------------------/
| � �
/----------------------\ \---------------The audio PDD
| | issues hardware
| /-----------------\ | interrupts when it
| | Stream Handler | | finishes processing
| \---- - ------- - ---- / | each 4KB DMA block .
| � | | � |
| | | | | |
| | � � | | The stream handler manages
| / - - ----- \ / ---- - -- \ | the process of the audio
| | Audio | | File | | PDD processing 4KB DMA
| | PDD | | System | | blocks and the file system
| | | | PDD | | PDD replacing the block as
| \ ------- / \ ------- / | it is processed .
\ ---------- ---------- -- /
Programmed I/O Programmed I/O involves copying the stream buffer's data directly to the adapter's buffer.
Stream Descriptions
Each physical device driver supports the following:
Multiple Opens A PDD must be able to handle multiple open operations. In other words, the OS/2 operating system should be able to open your device driver as many times as necessary. However, resource should only be allocated at the audio initialization stage (IOCtl stage).
Multiple Streams A PDD must be able to handle multiple streams. For example, there might be ten multimedia programs on the desktop that have the device open. However, only one program can own the device. For that one program, a stream is created and resources are used. However, if that one program gets put to sleep or the audio is paused, a second program can take its place and use that resource. The Media Device Manager will save pointers to the stream instance that is currently paused, point to the next program, and allow the program to use the resource. At this point, there will be two streams created. If the second program gets initialized, and perhaps paused, the third program will be initialized, and so on.
Many streams can be created, however, the program that has focus is the program using the adapter. In addition, a device driver might have ten streams allocated but only one stream will be active at a given time if the hardware supports only one stream. Some hardware can support more than one active stream at a time. For example, the ACPA card can play two mono streams at the same time but only one stereo.
Multiple Streams Implementation A stream table is a collection of streams with each stream having different data-similar to a data instance for DLLs. For example, one stream might be set up for recording using specific data rates and buffer pointers, while another stream might be set up for playback of a different data rate and buffer pointers. The two streams are unaffected by each other. The hardware will react to whichever stream is active.
A stream table contains the key indexes to determine which stream to make active. The key indexes are hStreamand ulSysFileNum. The hStreamcomes from the stream handler during stream registration while the ulSysFileNumcomes from both the DDCMD_REGISTER message and the AUDIO_INIT IOCtl. For example, in the following table, stream #1 has a system file number of 6B and stream #2 has a system file number of 7C. When the AUDIO_INIT IOCtl comes in to start the second instance, the IOCtl requests that you start the stream with the matching ulSysFileNum. Next, across the inter-device driver communications interface, the stream handler will tell you to start stream #2. To start stream #2, search the stream table for a match with system file number #7C. If you find a match, make the stream active. If you do not find a match, the operation fails.
IOCtl
ulSysFileNum
|
|
�
hstream sysfile# state data pData
/--------------------------------------\
IDC | 1 | 6B | | | |
hStream |--------|--------|------|-----|-------|
---------� | 2 | 7C | | | |
|--------|--------|------|-----|-------|
| 3 | 8D | | | |
\--------------------------------------/
Roadmaps
The following figures illustrate the routines and IOCtls included in the audio physical device driver files.
STARTUP.ASM
STARTUP.ASM File
/---------------------\
OS/2 IOCtls ----------� | AUDIODD.C |
| |
Stream Handler IDC ---� | MMDDCMDS.C |
| |
VDD IDC --------------� | AUDIOVDM.C |
| |
VDD �---------------- | CallVDD() |
\---------------------/
AUDIODD.C
AUDIODD.C File /------------------------------------------\ | Strategy.C() | | | | | |-� IOCTL_Init() | | |-� IOCTL_Invalid() | | |-� IOCTL_Read() | | |-� IOCTL_NondestructiveRead() | | |-� IOCTL_ReadStatus() | | |-� IOCTL_FlushInput() | | |-� IOCTL_Write() | | |-� IOCTL_WriteStatus() | | |-� IOCTL_FlushOutput() | | |-� IOCTL_Input() | | |-� IOCTL_Output() | | |-� IOCTL_Open() | | |-� IOCTL_Close() | | \-� IOCTL_GenIOCTL() | | | | | |-� Audio_IOCTL_Init() | | |-� Audio_IOCTL_Status() | | |-� Audio_IOCTL_Control() | | |-� Audio_IOCTL_Buffer() | | |-� Audio_IOCTL_Load() | | |-� Audio_IOCTL_Wait() | | \-� Audio_IOCTL_Hpi() | | | | InitPos() | | InitStreams() | | AllocDMABuffer() | | ParseArgs() | \------------------------------------------/
MMDDCMDS.C
MMDDCMDS.C File /------------------------------------------\ | DDCMDInternalEntryPoint() | | | | | |-� DDCMDSetup() | | |-� DDCMDRead() | | |-� DDCMDWrite() | | |-� DDCMDStatus() | | |-� DDCMDControl() | | |-� DDCMDRegister() | | \-� DDCMDDeRegister() | | | | GetStreamEntry() | \------------------------------------------/
AUDIOVDM.C
AUDIOVDM.C File /------------------------------------------\ | PDDInternalEntryPoint() | | | | VDMInterruptTime () | | | | | \-� CallVDD() | | | | VDMClose() | | | | | \-� CallVDD() | \------------------------------------------/
AUDINTR.C
AUDINTR.C File /-------------------------------------------------\ | InterruptHandler() | | | | | |-� VDMInterruptTime() | | |-� WriteDatatoCard() | | |-� SHDEntryPoint() call back to stream handler| | \-� EOI() | \-------------------------------------------------/
CDEVHLP.ASM
CDEVHLP.ASM File /------------------------------\ | DevHlp_AllocGDTSelector() | | DevHlp_AllocPhys() | | DevHlp_PhysToGDTSelector() | | DevHlp_PhysToVirt() | | DevHlp_VirtToLin() | | DevHlp_ABIOSCall() | | DevHlp_GETLIDEntry() | | DevHlp_FreeLIDEntry() | | DevHlp_RegisterPDD() | | DevHlp_AttachDD() | \------------------------------/
Audio Virtual Device Driver Template
The IBM Developer Connection Device Driver Kit for OS/2includes full source for the MMPM/2 provided Virtual Device Driver, VBSAUDIO.SYS. Use VBSAUDIO.SYS to serialize DOS application access to audio hardware in the MMPM/2 environment. This VDD can communicate with multiple audio PDDs through the Inter-Device Driver Communication (IDC) Interface. However, where the services of VBSAUDIO.SYS are not sufficient, you can modify the audio VDD template to meet your device driver requirements.
You can code your Physical Device Driver to meet the interfaces of VBSAUDIO .SYS as an initial step toward virtualization. You can expand this functionality by copying and changing VBSAUDIO.SYS to take advantage of your hardware and private interfaces which can be established between the VDD and DOS or WIN-OS/2 audio device drivers.
Note:For further information on when to use a VDD and how it operates, see the online OS/2 Virtual Device Driver Referenceprovided in this package. This reference describes the types of virtual device drivers, their interfaces, and available kernel services.
Source Code
The VDD template is written using Watcom C and linked with the 32-bit OS/2 linker. Source code for the audio VDD sample is located in the \DDK\BASE\ SRC\VDEV\MME\VBSAUDIO subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.
VDD Architecture
The VBSAUDIO.SYS virtual device driver is a Ring 0, 32-bit device driver responsible for controlling multiple virtual DOS sessions. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely.
VDD architecture usually calls for a device driver pair: a PDD and VDD working together to serialize and control a common piece of hardware, called shared hardware. The PDD controls access to the hardware and OS/2 sessions; the VDD controls DOS sessions and communicates with the PDD to serialize access. That is, the PDD and VDD communicate to make sure DOS sessions and OS/2 sessions cannot concurrently access the shared hardware.
Without a VDD, DOS sessions have complete access to system hardware. Most DOS visible hardware resources are controlled by system VDDs, preventing DOS sessions from interfering with each other and protecting OS/2 applications from DOS sessions.
When a PDD exists with no VDD, the hardware device is visible to the OS/2 side (through the PDD) and to all DOS sessions (through the VDM Manager). This presents an opportunity for DOS sessions to take control of a hardware resource owned by an OS/2 PDD. Writing a virtual device driver corrects this situation, resulting in system-wide protected access to the hardware resource.
This PDD-VDD pair usually results in a VDD (like a PDD) being written to the specifications of a specific hardware device. VBSAUDIO.SYS supports multiple adapters by using a protocol for PDD-VDD communication where the PDD defines the characteristics of its device at system startup. [Artwork not shown]
The key to supporting multiple PDDs is communication at system startup to attain a description of the physical characteristics of each adapter. PDDs are loaded and initialized prior to VDDs. When the PDD loads, it registers itself as willing to communicate with VDDs by providing its IDC name and entry point for this communication. When the VDD loads, it calls a Virtual DevHlp service (VDHOpenPDD) to resolve the IDC entry point of the PDD. On this call, the operating system calls the PDD to deliver the VDD IDC entry point. When the PDD and VDD exchange entry points, the drivers are free to communicate through whatever private protocol is chosen including exchanging register-based entry points.
For these calls to function, the VDD must know the name by which the PDD registered. In a non-generic implementation, this is not a problem as the two device drivers can refer to the name from a common include file. This "generic" VDD takes the PDD names as DEVICE=VBSAUDIO.SYS parameters on the CONFIG.SYS statement.
In the case where a single PDD supports multiple devices, the PDD should register its IDC name and entry point (specifying the name on the DEVICE= VBSAUDIO.SYS statement). During initialization, the VDD calls the PDD to establish communication and to query the hardware resources that the PDD controls. The VDD will use this information to trap DOS session attempts to access the adapter. When a DOS session takes control of a PDD-owned resource, the VDD traps the DOS session pending permission to use the hardware. As the PDD controls access, the VDD queries the PDD for permission to use the hardware. If permission is granted, the VDD disables further traps and allows the DOS session to continue uninterrupted. Traps are disabled to give maximum performance. Because the VDD does not keep track of port accesses (and does not know the details of supported adapters ), it is unable to remember the state of the adapter. That is, as soon as a DOS session owns the hardware, ownership cannot be relinquished and restored, because the VDD does not know how to restore the state of the device. The VDD supports serialization (not virtualization).
If access is denied by the PDD, or if another DOS session already owns the hardware, a pop-up message is displayed asking the user for direction. The user can give instruction to terminate the session, suspend the session, or pretend the hardware does not exist. Based on this response, the VDD executes Virtual DevHlp services to perform the necessary actions. Semaphores are used to block DOS session execution when they are suspended awaiting access to hardware. When the last DOS session releases the hardware, the VDD returns hardware ownership to the PDD.
Note:See VDD Operationsfor further information.
VDD Operations
When writing a PDD to control physical hardware, it is common to write a VDD to provide serialization with DOS sessions. Without a VDD, DOS sessions have complete access to system resources. That is, if an adapter has only a PDD, DOS sessions can directly access the adapter resulting in unpredictable consequences.
When DOS sessions are created, the VDD installs hooks for the indicated port ranges. On first access, the DOS session is said to be "requesting hardware access." By convention, the PDD controls hardware access. To gain use, the VDD must ask the PDD for permission to use the hardware. When granted, the DOS session traps are removed and the session is allowed to continue executing. At interrupt time, the PDD calls the VDD IDC entry point where the VDD virtualizes the hardware interrupt for the owning session.
Subsequent DOS session access attempts are denied pending hardware availability. A hard error pop-up window is displayed giving the user three options:
�End - Terminate the DOS session
�Retry - Block until hardware becomes free
�Ignore - Instruct the VDD to ignore the adapter
If retry is chosen, the DOS session is blocked until the hardware becomes available. When the DOS session in use releases the hardware, the next DOS session gains access. This process continues until no more devices are waiting at which point the VDD relinquishes ownership to the PDD.
If ignore is chosen, the DOS session continues execution but with no visibility to the protected adapter. This allows sound-enabled DOS applications to execute under the impression that the system does not have an audio card installed.
For access queues, the PDD uses semaphores and the OS/2 scheduler. The VDD maintains no queues. Instead, 1 mutex and 1 event semaphore are used to control access. Only one DOS session can own the hardware at any one time. When the VDD owns the hardware, the DOS session owning the mutex semaphore is allowed to execute. All others are blocked pending hardware availability. When the owning session releases the hardware (the semaphore ), the OS/2 semaphore routines and scheduler determine which session next gains access.
A DOS session can also be denied access due to OS/2 PDD refusal to relinquish ownership. This would be the case when an OS/2 application is using the services of the PDD before a DOS session attempts access. Here, all pending DOS sessions are queued waiting on an event semaphore. When the OS/2 PDD relinquishes hardware, all blocked sessions are allowed to run by posting the event semaphore. The sessions compete for ownership of the mutex semaphore. One session wins, the others block; serialization is maintained.
Inter-Device Driver Communication (IDC) Interface
Virtual device drivers (VDDs) communicate with physical device drivers ( PDDs) through the inter-device driver communication (IDC) interface provided with the OS/2 operating system. The drivers exchange the address of an entry point and call each other through the exchanged addresses. A VDD communicates with a PDD directly through a callable 16:32 interface or by using the Virtual DevHlp services that map to File System APIs.
Physical device drivers and virtual device drivers use the following OS/2 DevHlp functions to establish inter-device driver communication (IDC).
RegisterPDD This function is called by the PDD during initialization to advertise a 16:16 entry point for VDD-PDD communication. The PDD provides a textual name, which the VDD must supply during its initialization.
VDHOpenPDD This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service, RegisterPDD. If the function is successful, it returns a pointer to the physical device driver IDC entry point.
MAD16 PDD and VDD Sample Device Drivers (Watcom C)
The Developer Connection Device Driver Source Kit for OS/2 includes a PDD/ VDD pair that program the OPTi/MediaChips 82C928/82C929 Audio Controller ( MAD16). The MAD16 is an integrated digital audio controller for PC sound applications.
Beyond its use for multimedia device developers, the sample provides a reference for using Watcom 16 and 32-bit C compilers for OS/2 device driver development.
The device drivers are located on the CD-ROM in the multimedia section.
PDD \ddkx86\mmos2\samples\mad16
VDD \ddkx86\mmos2\samples\vmad16
Board Architecture
The reference design for the MAD16 includes the following primary parts:
/-------------------------------------------------------------\ |Chip |Description | |-------------------------+-----------------------------------| |OPTi 82C929 (MAD16) |Primary chip. ISA bus interface, | | |CD-ROM control, MPU-401 interface | | |and Sound Blaster to Windows Sound | | |System command translation. | |-------------------------+-----------------------------------| |Audio Codec |Windows Sound System compatible | | |audio CODEC. The sample supports | | |the Analog Devices AD1848 and the | | |Crystal Semiconductor CS4231. | |-------------------------+-----------------------------------| |Yamaha YMF-262 (OPL-3) |FM MIDI synthesis (same part as | | |Sound Blaster Pro). | |-------------------------+-----------------------------------| |CD-ROM connectors |Support Sony31A, Mitsumi, IDE and | | |Panasonic drives. All interfaces | | |are controlled via the MAD16. | \-------------------------------------------------------------/
The MAD16-based board can support applications and device drivers written to a variety of CD-ROM, audio and MIDI interfaces.
MAD16.ADD Device Driver Overview
All device configuration is performed through software programmable settings. Base I/O address and DMA and IRQ selections for CD-ROM and audio are initialized from software through the MAD16.ADD device driver. There are no jumpers.
Once enabled, existing device drivers can be used to perform audio and CD- ROM actions. For example, existing AD1848 business audio device drivers can be used on configurations with the AD1848. Existing CS4231 device drivers can be used in board configurations that have the CS4231 device. Likewise, the MAD16 device can be set to enable Sony31A, Mitsumi, Panasonic or IDE CD -ROM interfaces. An appropriate CD-ROM device driver is loaded later to perform CD-ROM activities.
The job of the MAD16.ADD is to initialize the device.
Boot Sequence
To initialize the device before the other device drivers load, the MAD16. ADD device driver has to load before the other device drivers (Audio/CD-ROM ). OS/2 loads device drivers in a specific order. Device drivers needed to boot the system are loaded early. Less critical device drivers including audio are loaded toward the end of the device driver load sequence. In a particular class of device drivers, load order is based on order in the CONFIG.sys.
Device driver load order is as follows:
1.Kernel known basedevs (resource manager)
2.BASEDEVs
a..ADDs first
b..SYS
3.Non-BASEDEVs (for example, Audio)
To load early, the MAD16.ADD wakeup code is written as a BASEDEV .ADD. This insures that regardless of CONFIG.SYS order, it loads early. For CD-ROM however, both the wakeup code and CD-ROM device driver are .ADDs. This creates an install requirement that the MAD16.ADD precede the CD-ROM device driver in CONFIG.SYS.
PDD Operation and Architecture
The MAD16.ADD does most of its work during initialization. Device modes and settings are read from a persistent database (CONFIG.SYS). The MAD16 device is programmed to set the base address of all the other parts on the board. For CD-ROM, turning the device on is all that is required. For audio, an initialization sequence is required to bring the audio Codec and MAD16 to a state where both Windows Sound System and Sound Blaster applications can be supported.
Using Watcom 16-bit C, the MAD16.ADD device driver has very little assembler code. The strategy routine is executed with no assembler stub. Watcom provides "pragma aux ", which allows the programmer to specify that parameters arrive in registers rather than on the stack. With this, much of the stub code popular in C device drivers is unnecessary.
The following table describes the MAD16.ADD source code.
/-------------------------------------------------------------\ |MAD16.ADD Source Files |Description | |-------------------------+-----------------------------------| |makefile |Build procedure - "nmake". | |-------------------------+-----------------------------------| |DATA.C |Device driver data (global). | |-------------------------+-----------------------------------| |DDPRINTF.C |Support for writing messages to | | |console (printf). | |-------------------------+-----------------------------------| |DDSTRING.C |String processing routines (command| | |line parsing support). | |-------------------------+-----------------------------------| |HEADER.C |Device driver header (DevHdr). | |-------------------------+-----------------------------------| |IDC_PDD.C |IDC operations for PDDs. | |-------------------------+-----------------------------------| |IDC_VDD.C |IDC operations for VDDs. | |-------------------------+-----------------------------------| |INIT.C |Initialization code (Good place to | | |start reading). | |-------------------------+-----------------------------------| |IOCTL.C |IO Control processing (called from | | |Strategy routine). | |-------------------------+-----------------------------------| |MAD16.C |Code that knows how to initialize | | |the 82C929 MAD16 device. | |-------------------------+-----------------------------------| |MADUTIL.C |Code that programs the MAD16 | | |(retained after init). | |-------------------------+-----------------------------------| |QMAD16.C |32-bit Application - display PDD | | |structures to screen. | |-------------------------+-----------------------------------| |SNDBLAST.C |Code that knows how to reset and | | |program a Sound Blaster Pro. | |-------------------------+-----------------------------------| |STRATEGY.C |Device driver strategy routine. | |-------------------------+-----------------------------------| |TRACE.C |Holds trace information and copies | | |of error messages. | |-------------------------+-----------------------------------| |UTIL.C |I/O delay function, OPL-3 mute | | |code. | |-------------------------+-----------------------------------| |WSS.C |Code that initializes the audio | | |CODEC. | |-------------------------+-----------------------------------| |WSSUTIL.C |Audio CODEC code (retained after | | |init). | |-------------------------+-----------------------------------| |SEGS.ASM |Define device driver segments. | |-------------------------+-----------------------------------| |UTILA.ASM |IDC entrypoints (16:16 <-> 16:32 | | |thunks). | |-------------------------+-----------------------------------| |DATA.H |Header file for DATA.C. | |-------------------------+-----------------------------------| |DDPRINTF.H |Header file for DDPRINTF.C. | |-------------------------+-----------------------------------| |DDSTRING.H |Header file for DDSTRING.C. | |-------------------------+-----------------------------------| |HEADER.H |Header file for HEADER.C. | |-------------------------+-----------------------------------| |IDC_PDD.H |Header file for IDC_PDD.C. | |-------------------------+-----------------------------------| |IDC_VDD.H |Header file for IDC_VDD.C. | |-------------------------+-----------------------------------| |IOCTL.H |Header file for IOCTL.C. | |-------------------------+-----------------------------------| |MAD16.H |Header file for MAD16.C. | |-------------------------+-----------------------------------| |REQPKT.H |Header file for REQPKT.C. | |-------------------------+-----------------------------------| |RMHELP.H |Header file for RMHELP.C. | |-------------------------+-----------------------------------| |SNDBLAST.H |Header file for SNDBLAST.C. | |-------------------------+-----------------------------------| |STRATEGY.H |Header file for STRATEGY.C. | |-------------------------+-----------------------------------| |TRACE.H |Header file for TRACE.C. | |-------------------------+-----------------------------------| |UTIL.H |Header file for UTIL.C. | |-------------------------+-----------------------------------| |WSS.H |Header file for WSS.C. | \-------------------------------------------------------------/
VDD Operation and Architecture
Because all audio operations are performed by the audio CODEC, only one audio mode can be active at one time. The device is not capable of performing two concurrent wave audio play operations.
At initialization, one mode must be selected. By convention, the Windows Sound System mode is the default because this support is used by MMPM/2 and WinOS2 for wave audio operations.
Becuase OS/2 and WinOS2 audio are controlled by the audio CODEC PDD, DRV, and VDD, the VMAD16 VDD must communicate with the other drivers to negotiate use of the audio device.
Audio operations are performed using existing audio device drivers. Sound Blaster games are supported in a virtual DOS machine through a OS/2 Virtual Device Driver (VMAD16).
The figure below illustrates the architecture.
/----------\ /----------\ /----------\ /-----------\ /-----------\
|QMAD16.exe| |MMPM/2 | |WinOS2 | |DOS Session| |DOS Session|
|Diagnostic| |MME subsys| |MME subsys| |WSS App | |SB App |
\----------/ \----------/ |----------| \-----------/ \-----------/
| | |Audio.DRV | | |
| Ring-3 | \----------/ | |
-----|-------------|--------------|-----------|-------------|-------
| Ring-0 | | /---------/ |
/---------\ /---------\ /---------\ /---------\
|MAD16.ADD| |Audio PDD|-----|AudioVDD | | VMAD16 |
\---------/ \---------/ \---------/ \---------/
| \----------------------------------/ |
\-----------------------------------------------------/
When a Sound Blaster specific application, such as a game, programs the device from a Virtual DOS machine, the VMAD16.SYS VDD intercepts the first port I/O and takes this as a request to use the audio hardware. It communicates with the audio CODEC PDD to gain ownership. Once ownership is attained, the VMAD16 VDD sends a command to the MAD16.ADD wakeup code commanding it to switch the device from Windows Sound System mode into Sound Blaster mode.
When the owning DOS application terminates, the VDD commands a switch back to Windows Sound System mode and returns device ownership to the audio CODEC PDD.
The following table describes the VMAD16.SYS source code.
/-------------------------------------------------------------\ |VMAD16.SYS Source |Description | |-------------------------+-----------------------------------| |makefile |Build procedure - "nmake". | |-------------------------+-----------------------------------| |DDSTRING.C |String processing routines. | |-------------------------+-----------------------------------| |EVENTS.C |Session create/terminate and other | | |event hooks. | |-------------------------+-----------------------------------| |GLOBDATA.C |VDD global data declarations. | |-------------------------+-----------------------------------| |INIT.C |Initialization code. | |-------------------------+-----------------------------------| |AUDIOREQ.C |Routines to communicate with audio | | |PDD for hardware ownership. | |-------------------------+-----------------------------------| |DATA.ASM |Per DOS session instance data | | |declarations. | |-------------------------+-----------------------------------| |UTILA.ASM |IDC support (16:32 to 16:16 far | | |calls). | |-------------------------+-----------------------------------| |AUDIOREQ.H |Header for AUDIOREQ.C. | |-------------------------+-----------------------------------| |AUDIOVDD.H |Header for AUDIOVDD.C. | |-------------------------+-----------------------------------| |DATA.H |Prototypes for GLOBDATA.C and | | |DATA.ASM. | |-------------------------+-----------------------------------| |DDSTRING.H |Header for DDSTRING.C. | |-------------------------+-----------------------------------| |EVENTS.H |Header for EVENTS.C. | |-------------------------+-----------------------------------| |UTIL.H |Header for UTIL.C. | \-------------------------------------------------------------/
PDD Sample for Video Capture Adapters
This DDK provides a sample of a video capture physical device driver (PDD) to assist in the creation of physical device drivers (PDDs) for video capture adapters (VCAs).
Source Code
Source code for the physical device driver (PDD) sample is located in the \ MMOS2\MMTOOLKT\SAMPLES\VCADDT subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines used in incorporating the module.
The sample programs require MASM** 5.1 for assembly.
/-------------------------------------------------------------\ |File |Description | |-------------------------+-----------------------------------| |README |Describes how to create the | | |resource DLL containing the video | | |adapter information and how to | | |create the .SYS file containing the| | |VCDD. | |-------------------------+-----------------------------------| |VCA32.ASM |Contains the main entry point for | | |IOCtl parsing. | |-------------------------+-----------------------------------| |VCACAPT.ASM |Contains image copy and scale | | |routines. | |-------------------------+-----------------------------------| |VCAIDC.ASM |Contains device specific streaming | | |routines. | |-------------------------+-----------------------------------| |VCAINIT.ASM |Contains device initialization | | |routines. | |-------------------------+-----------------------------------| |VIDIDC.ASM |Contains generic device streaming | | |routines. | |-------------------------+-----------------------------------| |VIDIDC.INC |Contains streaming instances | | |structures. | |-------------------------+-----------------------------------| |VIDIN.INC |Contains the open instance | | |structure. | |-------------------------+-----------------------------------| |VIDVCI.INC |Contains the interface for the | | |IOCtl. | |-------------------------+-----------------------------------| |VIDVCIT.SYS |Is the compiled device driver. | \-------------------------------------------------------------/
Program Flow
The following figure illustrates the program flow from the Media Device Manager (MDM) through the PDD and finally on to the video capture adapter.
/--------------\ /--------------\
| Media Device | (4) | SPI |
| Manager |--------------� Interfaces |
| | | SSM |
\--------------/ \------�-------/
(1) | (5) |
| |
/------�-------\ /------�-------\
| Vendor- | | Video Capture|
| Specific | | Stream |
| Driver | | Handler |
\--------------/ \------�-------/
(2) | (6) |
| |
/------�-------\ |
| Physical | |
| Device �---------------------/
| Driver |
\--------------/
(3) |
|
/------�-------\
| Video |\ �-- Video Input
| Capture |/
| Adapter |
\--------------/
1 Media Control Interface functions are passed from the MCD to the vendor- specific driver.
2 The VSD passes information to the PDD.
3 The PDD controls the video capture adapter. The sample provided works with the IBM VCA adapter. To modify the sample to work with a different adapter, you must replace all hardware-specific routines with routines that are specific to your adapter. If you update the PDD sample, make a backup copy first. In order for the generic install to work, you must update the RCDATA 12 parameters so that MINSTALL will install the correct PDD.
4 After the video capture adapter is initialized, the MCD passes control to the Video Capture Stream Handler through the SPI interface.
5 The SPI interface receives video data from the video capture stream handler.
6 The control video data from the Video Capture Stream Handler is passed to and from the PDD.
PDD Architecture
The following figure illustrates how the PDD fits in the overall MMPM/2 subsystem structure. The media device manager (MDM) uses Media Control Interface commands to pass information through the vendor-specific driver and on to the PDD. The PDD directly controls the video capture adapter and passed video adapter request to the video capture stream handler.
ÉÍÍÍÍÍÍÍÍ» /-------------\
º º | Multimedia |
º º�--\ | Application |
ÈÍÍÍÍÍÍÍͼ | \---�---------/
PM Monitor | Notifications | | MCI Commands
| /------+-----+------\
| /----+------------�------+----\
| | | MDM | |
| \----+-------------------+----/
| | /----------------+-------------------\
| /-------------\ /------�--------\ |
mmioOpen \----|Digital Video| |Amplifier Mixer| |
/--------------------|Media Driver|-\ /-| Media Driver |-----\ |
| mmioSetHeader \-----�-------/ | | \--------�------/ | |
| | | | | | |
| | /-----�-�------\ | | |
| | |SPI Interfaces| | | |
| | |--------------| | | |
| \---| SSM |---/ | |
| \-------------�/�--\ | |
| audio data | | | |
| /-----------\ /---------\ | /-�-----\ /-------\|
/---------\mmioWrite|Multi-track�------------/�---+--|Audio �--|Audio ||
| MMIO �---------|Stream | /-\ \\ |Stream | |Adapter||
| Manager |mmioSeek |Handler �--+-| | |Handler| \-------/|
\---------/ \-----------/ |-| uncompressed| \-------/ /---/
multi|track data/---\ compressed |-| /---------\ \�/-------\ /----�--\
/----�----------+-\ | data |-| \---------/�--|Video | |Capture|
| AVI | | | \�/ | data |Capture�--|DD |
| IOProc | | | | | |Stream | |copy |
\---------------+-/ | | \-----\ |Handler| |scale |
| /------------+-\ | | | \-------/ \-------/
| | Ultimotion | | | | /-----�-------\ /---�---\
| | RT Codec | | | \---| Compression | |Video |
| \------------+-/ \-------------------| Stream | |Adapter|
� \-----------------------� Handler | \-------/
raw data compression \-------------/
Strategy Commands
There are several generic strategy commands that are supported by all physical device drivers, video or otherwise. These are documented in the OS /2 Physical Device Driver Reference. The generic strategy commands supported by video device drivers are described in the following table.
/------------------------------------------\ |Functions |Description | |-----------+------------------------------| |INIT |Initializes the device. | |-----------+------------------------------| |OPEN |Opens an instance of the | | |device and prepares it for | | |use. | |-----------+------------------------------| |CLOSE |Closes an instance of the | | |device. | \------------------------------------------/
PDD Sample for MPEG Video Playback Devices
The Developer Connection Device Driver Source Kit for OS/2 provides a sample MPEG Video Playback physical device driver (PDD) to assist in the creation of PDDs for other video playback devices. This sample provides a code base for a new PDD, simplifies development, and illustrates the OS/2 MPEG Video Playback PDD model for a nonshared frame buffer device, also referred to as an overlay device. The ReelMagic card from Sigma Designs, Inc. is an example of such a device.
The code contained in this sample was derived from a working driver. All hardware-specific code and header files have been removed from the sample. Although this device driver was written for a device that uses the split- stream model, it is easily adaptable to the single-stream model.
The split-stream MPEG I/O procedure splits the audio and video packets out of the MPEG file. The audio data packets are passed through the subsystem to the audio DD, and the video data packets are passed through the subsystem to the video DD. As the audio DD returns the buffers that it has played, it also returns the current audio time-which is in turn passed through the subsystem to MPEG hardware compressor/decompressor (CODEC) and from there is sent to the video DD on the next VCAI_PLAY command.
The single-stream MPEG I/O procedure reads the entire MPEG file one buffer at a time-without splitting the video and audio data. As each buffer is read in, it is passed through the subsystem to the video DD. With single stream, every byte in the file is passed to the DD; whereas with split stream, only the video data packets are passed to the video DD. The single- stream video DD and its hardware are then responsible for producing the video and audio along with all synchronization.
Note:From the video DD's perspective, the main difference in the single- stream model is that the SCR, PTS, and Audio PTS fields in the VCAI_PLAY contain zero.
Source Code
Source code for the PPD sample is located on the Developer Connection Device Driver Source Kit for OS/2 CD-ROM. Source files include documented headers, which provide detailed descriptions of the programming concepts and routines.
/-------------------------------------------------------------\ |File |Description | |-------------------------+-----------------------------------| |MAKEFILE |Makefile. | |-------------------------+-----------------------------------| |INIT.ASM |Handles the Device Init message at | | |OS/2 start-up time. | |-------------------------+-----------------------------------| |IOCTL.ASM |IOCtl message routing and IOCtl | | |processing. | |-------------------------+-----------------------------------| |SUBSA.ASM |Device-specific Assembler routines.| |-------------------------+-----------------------------------| |VEND.C |Device-specific C routines. | |-------------------------+-----------------------------------| |VIDRMS1.INI |Device-specific .INI (defaults | | |settings) file. | |-------------------------+-----------------------------------| |VIDVCI.INC |IOCtl interface description/header | | |file. | |-------------------------+-----------------------------------| |ENDOF.ASM |Label to mark the end of the code. | |-------------------------+-----------------------------------| |INOUTP.C |C-callable routines for port IN and| | |OUT. | |-------------------------+-----------------------------------| |INOUTP.H |C interface header file for Port IN| | |and Port OUT routines. | |-------------------------+-----------------------------------| |VIDVCI.H |IOCtl interface description/header | | |file for .C. | |-------------------------+-----------------------------------| |VIDVCI.INC |IOCtl interface description/header | | |file for .ASM. | |-------------------------+-----------------------------------| |ARUNTIME.ASM |Standard C runtime routines written| | |in assembler. | \-------------------------------------------------------------/
Program Flow
1.The application opens the MPEG Digital Video Device through the media control interface (MCI).
2.The media control device (MCD) finds the PDDnameand VSDnamein the MMPM2.INI file and opens the VSD with the PDDname.
3.The VSD opens the PDD, reads in an .INI file, and passes the .INI file to the PDD. The filename is based on the first seven characters of the PDDnamewith the .INI extension. The .INI file is device-dependent. The types of information in the .INI file may include default key color, video alignment offsets, and video quality adjustments.
4.Through the DevInfo IOCTL, the VSD queries the PDD to determine its capabilities.
5.The application loads an MPEG file through the MCI.
a.Through the standard I/O Proc interfaces, the MCD identifies MPGIO as the I/O Proc for the MPEG file.
b.Through the standard compressor/decompressor (CODEC) interfaces, the MPEG I/O Proc (MPEGIO) selects the MPEG hardware decompressor (MPEGDC). The MCD tells the VSD handle to the MPEGDC so that it can call the VSD/PDD to play back the compressed Video MPEG data.
c.Through the VSD and the PDD, the hardware CODEC MPEGDC loads the device with its DSP/MicroCode from a file whose name matches the results of a query of the VSD/PDD.
d.The MCD opens the playback window, queries the VSD/PDD for the transparent/key color, and paints the window with the key color.
e.The MCD tells the VSD/PDD the source movie size and window location.
f.The MCD tells the VSD/PDD to enable the monitor window and color keying.
6.The application issues a play command through the MCI.
7.The MPEG I/O Proc reads part of the MPEG file.
8.The audio data is sent through the system to the audio PDD.
Note:MPEG audio data is passed to the audio device driver via the DDCMD_ READWRITE_PARM structure. Field ulParm1 contains the initial audio system clock reference (SCR), and ulParm2 contains the Presentation Time Stamp ( PTS).
9.The video data is sent through the system to the MPEG CODEC (MPEGDC). If this data is the first packet in the stream, MPEGDC will issue a VCA_ PlayStart IOCtl to the VSD/PDD to set up the device and initialize the stream time. As the data arrives, MPEGDC issues a VCA_PlayData IOCtl to the VSD/PDD.
10.As the audio PDD plays audio buffers, it reports back to the audio stream time, which is eventually sent to MPEGDC.
11.The audio time is passed on the next VCA_PlayData IOCtl to the VSD/PDD.
Note:When playing from the beginning of an MPEG file the audio time will begin at zero regardless of the files initial SCR value.
12.Steps 7 through 11 are repeated until the end of the MPEG data/file is reached-at which time, a VCA_PlayStop is issued indicating that the end of the file has been reached.
Audio and Video Synchronization (Split-Stream Model)
The MPEGDC is a decompressor that does not require the MMPM/2 subsystem to control or time the flow of images to the decompressor, whereas the Ultimotion CODEC allows the MMPM/2 subsystem to control the flow of images to the decompressor, which is not called until it is time to display the image. Data is sent to MPEGDC as fast it can be sent by the system. The PDD and its hardware must control the synchronization between audio and video. When the data is arriving too fast (the hardware data buffers are filled), the PDD must suspend processing on the MPEGDC thread until the hardware can accept more data. The hardware may contain over three-fourths of a second of video data waiting to be decompressed. The hardware will decompress the image when its SCR reaches the presentation time stamp (PTS) of the data packet in the hardware buffer. If the SCR is greater than the PTS, the hardware will speed up or skip images until the PTS and SCR match.
To synchronize the audio with the video, the PDD must know the current audio time. Because the audio and video have separate hardware with different clocks, the video PDD will need the audio time to keep the video synchronized with the audio.
As the audio stream plays the audio buffer, it reports back the current audio time. This time is relayed to the MPEGDC. The MPEGDC will pass down the last reported audio time to the PDD on the VCA_PlayData IOCtl. To get the current audio SCR, the PDD multiplies the audio time by 30 to convert from MMTime to the MPEG 90KHz clock and adds the stream's initial SCR from the VCA_PlayStart IOCtl audio time. The PlayStart audio time is the initial stream SCR. It is required because the audio stream times reported by the audio subsystem are zero-based times and the PTSs in the video stream are based on the initial SCR. The PDD compares the hardware video SCR with the calculated audio SCR to determine if the video is ahead of or behind the audio. If the audio is not synchronized with the video hardware, the video SCR must be updated to match the audio SCR.
Note:The audio time may contain the same value on subsequent PlayData commands until the audio device driver updates the audio stream time. The audio time can be set to zero, meaning no audio in the MPEG file or no audio PDD. In either case, the audio and video synchronization logic may be skipped.
Running the Sample Device Driver
The easiest way to install and run this sample device driver is to install Sigma Designs' ReelMagic through the OS/2 Warp Selective Install and copy this sample device driver over the Sigma Design Reel Magic device driver that has the same name. The file can be found in the MMOS2 subdirectory ( usually \MMOS2\VIDRMS1.SYS).
This device driver will not display images on the screen because it contains no hardware-specific code, but it will allow you to see and follow the commands and data to the device driver.
Reboot the computer after installing this sample device driver.
Audio Sample for Vendor-Specific Drivers
OS/2 Warp, Version 3 provides sample files that assist in the creation of vendor-specific drivers (VSDs). The VSD defines a generic device driver- like interface that effectively decomposes high-level media control interface functions into more fundamental operations at the DLL level.
Note:VSD functionality is available for OS/2 Warp, Version 3 and is not downward compatible.
The following figure illustrates the program flow from the Media Device Manager (MDM) through the VSD and finally on to the audio adapter.
[Artwork not shown]
1 Media Control Interface functions are passed from the Media Device Manager to the vendor-specific driver using VSD commands.
2 The VSD passes information to its device driver. This provides a Ring-3 interface to control audio devices. The VSD sample provided with the DDK should be adequate to cover all basic audio functions. If your audio adapter requires special processing, you might have to supplement the sample VSD. To install the VSD, update the VSDDriver= option in the generic install routines (or CARDINFO.RC).
3 The device driver controls the audio adapter.
4 After the audio adapter is initialized, the MDM passes control to the Audio Stream Handler through the SPI interface.
In order to play or record audio data, the audio stream handler sends VSD_ DDCMD messages to the VSD.
5 The SPI interface sends/receives audio data from the audio stream handler .
6 The Audio Stream Handler controls audio data passed to and from the VSD.
7 The VSD reports stream events (such as buffer completion) via the SHC_ REPORT_INT message.
Source Code
Source code for the vendor-specific driver (VSD) sample is located in the IBM Device Driver Source Kit for OS/2. Source files include documentation headers that provide detailed descriptions of the programming concepts and routines used in incorporating the sample.
/-------------------------------------------------------------\ |AUDIOIF.C |This module checks for valid VSD | | |messages and routes them to the | | |appropriate function. It also | | |performs flag checking and error | | |reporting. | |-------------------------+-----------------------------------| |VSDOPEN.C |This module retrieves the | | |VSD_AUDIOOPEN_PARMS structure from | | |the VSD_OPEN message, checks to see| | |if the hardware supports the | | |requested mode and returns resource| | |management information. VSDs should| | |not allocate hardware resource on | | |the message. This will happen on | | |the VSD_RESTORE message. | |-------------------------+-----------------------------------| |VSDSET.C |The source file processes the | | |following VSD_SET messages: | | |VSD_SETVOLUME | | |Changes the volume for the current | | |instance. | | |VSD_SETCONNECTOR | | |Enable/Disables connectors. | | |VSD_SETMIXCONNECTIONS | | |Connects a source to a sink. | | |VSD_SETAUDIOATTRIBUTES | | |Sets audio items such as treble, | | |bass etc. | | |VSD_SETMONITOR | | |Enables/disables audio monitoring. | | |VSD_SETDATATYPE | | |Sets mode (i.e. bits/sample, | | |channels, sampling rate etc.). | | |VSD_SETMIXCONTROL | | |Sets the attributes for a mixer | | |line. | |-------------------------+-----------------------------------| |VSDMAN.C |Processes the following messages: | | |VSD_RESTORE | | |Consumes hardware resources. On | | |some audio cards, it will also load| | |a DSP. | | |VSD_SAVE | | |Removes hardware utilization (other| | |instances can use it after it is | | |done). | | |VSD_CLOSE | | |Closes VSD and frees memory etc. | | |VSD_RESOURCE | | |Returns resource management | | |information to the caller. | |-------------------------+-----------------------------------| |VSDIOCTL.C |This C module makes AUDIODD IOCTL | | |calls. See the AUDIODD reference | | |for more information. | |-------------------------+-----------------------------------| |VSDCAP.C |Processes the VSD_GETDEVCAPS | | |message. Returns the capabilities | | |of the VSD to the caller. | |-------------------------+-----------------------------------| |VSDQUERY.C |Processes the following messages: | | |VSD_QUERYVOLUME | | |Returns the current volume setting.| | |VSD_QUERYCONNECTOR | | |Returns the state of a hardware | | |connector. | | |VSD_QUERYMIXCONNECTIONS | | |Returns the source/sink connection | | |information. | | |VSD_QUERYAUDIOATTRIBUTES | | |Returns the status of audio | | |attributes. | | |VSD_QUERYMONITOR | | |Returns if audio monitoring is | | |available. | | |VSD_QUERYDATATYPE | | |Returns if a particular datatype is| | |supported in the VSD. | | |VSD_QUERYMIXCONTROL | | |Returns the status of audio | | |attributes for a mixer sink/source.| | |VSD_QUERYMIXLINE | | |Returns line capabilities. | |-------------------------+-----------------------------------| |VSDCONN.C |Handles AUDIODD input/output | | |connections. | |-------------------------+-----------------------------------| |VSDDEF.C |Processes shared memory for the | | |VSD. | |-------------------------+-----------------------------------| |VSDINI.C |This file reads a vendor specific | | |initialization file, determines | | |resource management information to | | |be returned on VSD_OPEN or | | |VSD_QUERYDATATYPE. | |-------------------------+-----------------------------------| |OS2MIXER.C |Processes AUDIODD mixer IOCtls. For| | |more information, see Mixer IOCtl | | |Functions Introduction. | |-------------------------+-----------------------------------| |VSDINI2.C |Main entry point. | |-------------------------+-----------------------------------| |DDCMD.C |Processes streaming related | | |functions. Communicates with | | |protect mode device driver to | | |implement DDCMD processing. | \-------------------------------------------------------------/
VSD Architecture
The VSD layer is a device-independent physical device driver-like layer that resides in Ring 3. It passes information between the media control interface subsystem and multimedia devices. [Artwork not shown] A VSD has the following characteristics:
�Does not deal with media control interface notifications.
�Usually uses a single standard time format (milliseconds).
�Usually does not have to deal with file management.
Interface to the VSD
The interface to the Vendor Specific Driver (VSD) uses an entry point called VSDEntry. First a DosLoadModule is issued for the VSD's DLL. The DosLoadModule returns a handle for the VSD. Then with the VSD handle, a DosQueryProcAddr is issued to find the VSD entry point (VSDEntry). From this point on, calls to the VSD are made through the following API:
ULONG VSDEntry ( HVSD hvsd, // Handle to VSD driver
ULONG ulFunc, // Function code
ULONG ulFlags, // Flags for driver
PVOID pRequest) // Request Parameter Block/Value
Events
When the VSD receives VSD_DDCMD with DDCMDREGISTER, it should store the hid , hStream, and pSHDEntryPointfields of the DDCMDREGISTERstructure for use in reporting events. To report an event, the VSD should use the function pointer from the register to call the stream handler.
VSD_DDCMD
DDCMD_STOP (see the ulCmdfield of the DDCMDCONTROLstructure) operates differently for VSDs than for physical device drivers.
When a PDD receives a DDCMD_STOP, it is assumed that the stop is completed.
When a VSD receives a DDCMD_STOP, the stop is not considered complete when it is returned from the call. Rather it is considered complete when it the VSD is sent a STREAM_STOP_NOW (see ulFlagof the SHD_REPORTINTstructure and ulFlagof the MSG_REPORTINTstructure.)
Note:VSDs will receive VSD_DDCMDin the ulFuncparameter of the VSDEntry. To process specific VSD_DDCMDs, you must examine the pRequestparameter.
The following code sample shows how this can be written.
LONG APIENTRY mixerDDCMDEntryPoint( HVSD hvsd,
ULONG ulFunc,
ULONG ulFlags,
PVOID pRequest )
{
PDDCMDCOMMON pCommon = (PDDCMDCOMMON) pRequest;
if (pCommon == NULL)
{
return (ERROR_INVALID_BLOCK) ;
}
switch (pCommon->ulFunction)
{
case DDCMD_SETUP:
return DDCmdSetup ((PDDCMDSETUP)pCommon, (PMCI_AMP_INSTANCE)hvsd );
case DDCMD_READ:
return DDCmdRead ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);
case DDCMD_WRITE:
return DDCmdWrite ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);
case DDCMD_STATUS:
return DDCmdStatus ((PDDCMDSTATUS)pCommon, (PMCI_AMP_INSTANCE)hvsd);
case DDCMD_CONTROL:
return DDCmdControl ((PDDCMDCONTROL)pCommon, (PMCI_AMP_INSTANCE)hvsd);
case DDCMD_REG_STREAM:
return DDCmdRegister ((PDDCMDREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);
case DDCMD_DEREG_STREAM:
return DDCmdDeRegister ((PDDCMDDEREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);
default:
return (ERROR_INVALID_FUNCTION);
}
}
Communication to the Stream Handler
The SHDEntryPointcontains the following two messages. These messages are located in the SHDD.H file of the \MMOS2\MMTOOLKT\H subdirectory. SHDD.H contains the data structures, their type definitions, and #define statements for certain values. Note that the messages pass pointers to packets of data, to allow maximum flexibility for the future.
SHC_REPORT_INIT The VSD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler that it has used up all the data and needs more.
When the stream handler gets the call, it knows the VSD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the VSD a fresh buffer to consume.
Note:It is possible for the stream handler to call back into the VSD when the stream handler receives an shc_report_init.
SHC_REPORT_EVENT The stream handler uses this message to keep in sync with VSD activities. For example, the stream handler can request the VSD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The VSD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the VSD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the VSD returns.
The VSD keeps track of the processes. In other words, only the VSD knows how much data, to the millisecond, has been played out to the device. The stream handler can approximate the data played, using calculations based on how much data has gone by. But the stream handler cannot calculate the data played to the millisecond, or even to the fraction of a millisecond, the way the VSD can.
Stream Handler Values
There are certain values that the stream handler is expecting. For example , when the stream handler requests a stop or a pause on a DDCMD_CONTROLmessage, the pointer that comes back to the stream handler is a pointer to the cumulative time that the VSD has recorded in real time. So whenever the stream handler requests the device to stop, the VSD honors that request and informs the stream handler the real time that the VSD stopped within the stream.
Another value the stream handler looks for is returned on DDCMD_STATUS. This is also a pointer to the cumulative time from the VSD, with respect to when that stream was first started at the stream handler's request.
VSD Values
The stream handler passes a pointer to the VSD on DDCMD_STATUS. This points to a value used by the VSD for setting the referenced time of the VSD. It is not always correct for the VSD to start its time at 0 every time the stream handler does a start, because the stream handler might have performed a seek in the stream. The VSD might have played a minute of data and then performed a backwards seek to the 30-second mark in the data. If a start is issued, the VSD should start from the 30-second mark in that stream.
DDCMD_CONTROLhas an important NOTIFY subfunction that is used for cuepoint or event detection. The stream handler supports events in cuepoints-an application request to be notified when a particular location in the file is reached or a specific time period has elapsed. The stream handler uses two methods for detecting how much time has elapsed:
�Using DDCMD_CONTROL NOTIFY, the stream handler requests to be notified by the VSD at a particular time and passes a pointer to the cue time.
�The stream handler determines the time internally. This method is not as precise as the first method, because only the VSD knows the real time.
For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the VSD supports precise event detection, it must accept this request and put it into a queue somewhere, preferably a linked list. This linked list will have the time of one minute so that during the streaming process, the VSD occasionally checks to see whether it is at the one minute mark. When this event occurs, the VSD calls back on an SHD_REPORT_EVENT. Then you can free up the event detection linked list node.
Keep in mind that the VSD should have the capability to queue these requests because there might be additional requests. For example, an application might request to be notified at the one-minute mark, next at a minute and a half, and possibly every five minutes.
If the VSD does not support event detection, then when it gets called on a DDCMD_CONTROL NOTIFY, it responds with an ERROR_INVALID_REQUEST. This response tells the stream handler that it must do the event-detection itself.
Priorities
When the VSD receives DDCMD_READand DDCMD_WRITEmessages, it will occur on a time-critical thread from the audio stream handler. If other threads are running, the DDCMD thread will always run first because of priority.
Other commands such as VSD_SETand VSD_QUERYmay come simultaneously at a normal priority. (You may be executing one command and then be jumped to a thread of higher priority.)
Device Type Function Table
Because the VSD interface supports commands for numerous data types, it is not necessary for every VSD to support all commands. The only commands that must be supported are those for the particular device type (for example, audio, video, and so on) that the VSD is implementing. This section provides guidelines for which functions and flags must be supported and which functions and flags are optional. The following table shows which functions are Required (R) and Optional (O) by device type.
/------------------------------------------------------------------\ |Functions/Subfunctions |Digital|Amp |Laser |Fax/Tam| | |Audio |Mixer |Disk | | |----------------------------------+-------+-------+-------+-------| |VSD_CLOSE |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_GETDEVCAPS |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_OPEN |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_RESOURCE |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_RESTORE |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_SAVE |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_QUERY |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_SET |R |R |R |R | |----------------------------------+-------+-------+-------+-------| |VSD_ESCAPE |O |O |O |O | \------------------------------------------------------------------/
Legend: R - Required Command O - Optional Command
The flags that must be supported by a VSD for the VSD_SET command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type.
/------------------------------------------------------------------\ |Functions/Subfunctions |Digital|Amp |Laser |Fax/Tam| | |Audio |Mixer |Disk | | |----------------------------------+-------+-------+-------+-------| |VSD_SETVOLUME |O |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETAUDIOATTRIBUTES |O |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETMONITOR | |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETDATATYPE | |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETCONNECTOR | | | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETMIXCONNECTIONS | | | | | |----------------------------------+-------+-------+-------+-------| |VSD_SETMIXCONTROL | | | | | \------------------------------------------------------------------/
Legend: R - Required Command O - Optional Command <Blank> - Not Applicable
The flags that must be supported by a VSD for the VSD_QUERY command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type.
/------------------------------------------------------------------\ |Functions/Subfunctions |Digital|Amp |Laser |Fax/Tam| | |Audio |Mixer |Disk | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYCONNECTOR |O |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYDATATYPE | |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYMONITOR | |O | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYVOLUME |O |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYMIXCONNECTIONS | |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYMIXCONTROL | |R | | | |----------------------------------+-------+-------+-------+-------| |VSD_QUERYMIXLINE | |R | | | \------------------------------------------------------------------/
Legend: R - Required Command O - Optional Command <Blank> - Not Applicable
Device States
Media devices that transport data are considered to be in one of the following states at any given time:
�Registered
�Deregistered
�Saved
�Restored
�Closed
When a device is opened and restored, the device context is assumed to be in the restoredstate. The closedstate can be viewed as both the initial state and the termination state. Or this state can be thought of as not a state at all, because a device context does not exist before it is opened, and ceases to exist when it is closed.
The following figure lists the allowable device states across the top of the table and indicates the changes in state that occur when the command messages shown in the first column of the table are issued. This table assumes all error conditions keep the device in its current state. For example, a waveform player that is opened without an element remains in the stopped state when a play is issued, and the MCD receives an error code.
The following figure is provided as a guide to application developers and MCD writers. There can be no guarantee that every media device will conform to this table, but every effort should be made to hide the complexity of the device from the application.
[Artwork not shown]
Legend
- After a restore, the device is considered active and available for use. If the stream has been registered, it is restored to the state it was in before the VSD_SAVE.
- Error condition.
Install
To manually install the VSD, change the VSDDRIVER= statement for the relevant amp-mixer device to the new DLL name. To permanently install the VSD, see Adding Support for Audio and Video Adapters.
Using the High-Resolution Timer
The high-resolution timer (HRT) is used to provide millisecond-accuracy timing services to device drivers and applications.
Introduction
The high-resolution timer package includes the following files:
TIMER0.SYS the high-resolution timer driver
CLOCK01.SYS a modified CLOCK01.SYS for high-resolution timer support
CLOCK02.SYS modified CLOCK02.SYS for high-resolution timer support
TMR0_IDC.H the header file used to communicate with the high-resolution timer from another PDD
TMR0_IOC.H the header file for IOCtl interface to the high-resolution timer
TIMER0.DDP the DDINSTAL installation script
Installation
To install the high-resolution timer device driver, follow these steps:
1.Remove the readonly attribute from \OS2\BOOT\CLOCK*.SYS with the attrib command, e.g.:
-r \os2\boot\clock*.sys
where * is the number in the name of your existing clock-system file.
2.Make a backup of \OS2\BOOT\CLOCK*.SYS.
3.Use DDINSTAL to install the driver.
4.Reboot.
Note:The high-resolution timer is intended for use with OS/2 Warp 3.0 and later. It has not been tested and is not supported under any previous version of OS/2. If you do use this timer with any previous version of OS/2 , you do so at your own risk.
Information for Microsoft C 6.0 Users
The header files were designed for Watcom C/C++ 10.0. If you are using Microsoft C 6.0, the only change that should be needed is to change the __ far, __cdecl, and __loadds keywords to _far, _cdecl, and _loadds-i.e., replace the double underscores with single underscores. To date, however, this has not been verified.
Ring-0 Usage
The high-resolution timer provides the following two services:
callback every nmilliseconds where nis an integer >= 1. This first option allows your device driver to register itself with the high-resolution timer . The device driver provides a 16:16 address of a function that the high- resolution timer calls every nmilliseconds. Registration (and deregistration) cannot occur during interrupt time.
If a device driver re-registers itself-by calling the registration function with the same 16:16 pointer-the high-resolution timer simply changes the count. This can occur at interrupt time.
query the current time This second option is used to obtain a 16:16 pointer to the current count variable. This variable can then be read by the device driver to obtain the current time. Note that this variable is only updated if the high-resolution timer is active-which is only true if at least one driver or application has registered itself with the high-resolution timer. Also note that this variable can be synchronized to another timeclock.
To call the high-resolution timer, call DevHelp_AttachDD with the first parameter as "TIMER0$ ". Remember, DDTable must be allocated in the default data segment. If you make it a local non-static variable (i.e., it is on the stack), the DevHelp_AttachDD call will fail. For example:
TIMER0_ATTACH_DD DDTable;
PTMRFN ptmrfn;
DDTable.pfn=NULL;
if( DevHelp_AttachDD( ( NPSZ ) "TIMER0$ ", ( NPBYTE ) &DDTable ) )
{
// TIMER0.SYS not loaded
}
if( !DDTable.pfn )
{
// Something wrong with TIMER0.SYS
}
ptmrfn=DDTable.pfn;
To register your driver with TIMER0.SYS, do something like this:
#define N 10 // Call me every N milliseconds
void __far __loadds InterruptHandler( void )
{
// This function is called every N milliseconds
}
if( ptmrfn( TMR0_REG, ( ULONG ) InterruptHandler, N ) )
{
// Registration failed
}
A ptmrfn() call mustoccur at ring 0. This means that it cannot be made from your strategy INIT routine. The DevHelp_AttachDD call can be made from the INIT routine.
The ptrmfn() call cannot be made from INIT COMPLETE either. Attempts to do so will result in a return code of 6.
Ring-3 Usage
The IOCtl interface provides the ability to:
obtain a pointer to the clock counter The pointer returned is a 16:16 pointer, which should be converted to a 0:32 pointer for use with 32-bit applications.
query and set the resolution Currently, the resolution is always 1 millisecond. Attempts to set it to another value will be ignored, and querying the driver will always return 1 millisecond. You should set the resolution anyway-in the future, the driver may actually use a lower resolution to conserve resources.
block until a certain time has elapsed
Use the following code as an example of reading the current time. The compiler used is C-Set++ 2.1. If you use a different compiler, you may need another technique for handling 16:16 pointers.
#include "tmr0_ioc.h"
APIRET rc;
HFILE hfile;
ULONG ulAction;
ULONG ulOpenFlag = OPEN_ACTION_OPEN_IF_EXISTS;
ULONG ulOpenMode = OPEN_FLAGS_FAIL_ON_ERROR |
OPEN_SHARE_DENYNONE |
OPEN_ACCESS_READWRITE;
ULONG ulResolution = 1;
ULONG ulSize1=sizeof( ulResolution );
ULONG * _Seg16 pulTimer16;
ULONG ulSize2=sizeof( pulTimer16 );
ULONG *pulTimer;
rc=DosOpen( "TIMER0$ ", &hfile, &ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
if( rc )
{
printf( "Couldn't open TIMER0$.\n" );
return;
}
printf( "TIMER0$ opened. File Handle is %lu\n",hfile );
rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_SET_RESOLUTION,
&ulResolution, ulSize1, &ulSize1, NULL, 0, NULL );
if( rc )
{
printf( "Couldn't set resolution.\n" );
DosClose( hfile );
return;
}
rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_GET_POINTER,
NULL, 0, NULL, &pulTimer16, ulSize2, &ulSize2 );
if( rc )
{
printf( "Couldn't get pointer.\n" );
DosClose( hfile );
return;
}
pulTimer=pulTimer16; // Converts a 16:16 pointer to a 0:32 pointer
if( !pulTimer )
{
printf( "NULL pointer.\n" );
DosClose( hfile );
return;
}
// At this point, pulTimer is now a pointer to the timer 0 counter variable
rc=DosClose( hfile );
DosOpen( "TIMER0$" ) registers the application as a client. At this point, the high-resolution timer driver is taking interrupts; so make sure the driver is open only when you need timer services. The pointer is valid for the life of the process; and each call to HRT_GET_POINTER allocates another selector-therefore, this call should be made only once.
To block until a certain time has elapsed, use the following code as an example. For brevity, the details (such as checking return codes) have been omitted.
ULONG ulDelay=1; // Number of milliseconds to wait
ULONG ulSize2=sizeof( ulDelay );
DosOpen( "TIMER0$ ", &hfile, &ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
DosSetPriority( 0, PRTYC_TIMECRITICAL, 0, 0 );
DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_BLOCKUNTIL,
&ulDelay, ulSize2, &ulSize2, NULL, 0, NULL );
Using a time-critical thread is important.
Common Problems
The following problems might occur due to the nature of the high-resolution driver.
trap D This is usually caused by using the wrong version of CLOCK0x.SYS. If the old CLOCK0x.SYS is in \OS2, for example, and the new one is in \OS2\ BOOT, the kernel will load the old driver. A quick way to check is to use the command "dir \clock0?.sy? /s" on the boot partition. This will search the entire hard drive for the clock drivers.
clock driver will not load Either some performance tool is running, or you are using the Warp GA version of CLOCK0x.SYS.
Caveats
The following should be considered when using the high-resolution timer:
�Only the first parameter to PTMRFN is checked; no other parameters are checked.
�It is possible to write to the timer count variable from another PDD and disrupt the high-resolution timer.
�While TIMER0 is active (i.e., while it is taking interrupts), DOS sessions do not have access to timer 0.
�Performance tools such as C Set's DDE4XTRA.SYS and Visual Age's CPPOPA3. SYS are incompatible with this driver.
�Device drivers should not depend on having the first tick occur at any particular time.
If a driver registers for 1 millisecond, for example, the first tick might occur less than 1 millisecond after the registration.
Anomalies
The following anomalies currently exist in the use of the high-resolution timer:
�Having multiple device driver's attached to the high-resolution timer has not been tested.
�The high-resolution timer sets interrupts at 1 millisecond even if a slower rate would suffice. If one driver wants callbacks every 2 milliseconds and another wants them at 4 milliseconds, the driver could program IRQ 0 for 2-millisecond ticks, but it does not.
�HRT_FREE_POINTER does not currently do anything.
�While the high-resolution timer is taking interrupts, DOS sessions (VDMs) will not receive INT 8 or INT 1Ch calls. Only one device driver can receive interrupts on a given IRQ in OS/2; and VTIMER.SYS-the VDD that provides INT 8 and INT 1Ch services to VDMs-expects CLOCK0x.SYS to deliver IRQ 0 interrupts. Because the high-resolution timer gets IRQ 0 interrupts, CLOCK0x.SYS-and therefore VTIMER.SYS-cannot get them.
Real-Time MIDI Subsystem
The real-time MIDI subsystem (RTMIDI) provides real-time processing of MIDI data within the driver itself. The following sections describe how device drivers communicate with RTMIDI:
�IDC Interface
�Type-A Drivers
�Registering a Type-A Driver
Refer to the Multimedia Subsystem Programming Guide(included with the IBM Developer's Toolkit for OS/2) for more information on the real-time MIDI subsystem.
IDC Interface
IDC stands for inter-device-driver communication. It is a technique for making function calls from one driver to another, thereby allowing the two drivers to communicate with one another. For more information on IDC, refer to the OS/2 Physical Device Driver Reference.
Function prototypes and other declarations are found in MIDI_IDC.H. Note that "function pointers" and "entry points" are synonymous. All pointers, function or otherwise, are 16:16 (far) pointers.
Supported IDC Interfaces
The RTMIDI IDC interface is designed to support multiple "types" of client device drivers. An RTMIDI client device driver is a 16-bit physical device driver that registers itself with RTMIDI as a particular type. Currently, only Type A drivers are supported. The Type A drivers send and receive single MIDI bytes. This type is primarily intended for supporting the UART MIDI port on standard sound cards.
An individual physical device driver can be of multiple types and it can register itself with RTMIDI as many times as necessary. For instance, a sound card with four physical MIDI ports would make four Type-A registrations. RTMIDI would not realize that these four devices actually existed on one physical sound card and are handled by one driver.
The header file MIDI_IDC.H contains the function prototype for the entry points of RTMIDI. The initial call to the RTMIDI's main IDC entry point is used to obtain additional function entry points, one of each type.
Initializing IDC Communication
To initialize communication between your driver and RTMIDI:
Use the following code segment to obtain the main IDC entry point to RTMIDI and the entry points used to register the driver with RTMIDI. DevHelp_ AttachDD is used to obtain the main entry point, and DDTable.pfn retrieves the registration entry points.
This routine is normally executed when processing the init_complete strategy call. Make sure that DDTable is located in the current data segment (DS) and not on the stack (SS).
MIDI_ATTACH_DD DDTable;
MIDI_REGISTER reg;
if (DevHelp_AttachDD("MIDI$ ", (NPBYTE) &DDTable ) )
{
// Error
// Return
}
reg.usSize=sizeof( MIDI_REGISTER );
DDTable.pfn(®);
Type-A Drivers
Type-A drivers send and receive single bytes to and from RTMIDI. They are typically used for simple UART MIDI ports or simple synthesizers, such as those found on most sound cards.
Type-A Driver Capabilities
When Type-A drivers register with RTMIDI, they must provide information on their capabilities by setting the appropriate bits in the flCapabilitiesfield of the MIDIREG_TYPEA structure that is passed for registration. (See Registering a Type-A Driverfor an example of registering a Type-A driver.) Flags marked with an asterisk (*) are not currently supported and should not be set. The flags are:
MIDICAPSA_INPUT Set this flag to indicate that this device can receive MIDI messages from RTMIDI. If set, then the pfnRecvByte and pfnRecvString fields in the MIDIREG_TYPEA structure must be properly initialized. If not set, then the corresponding hardware node cannot be enabled for receive.
MIDICAPSA_OUTPUT Set this flag to indicate that this device can send MIDI messages to RTMIDI. If not set, then the corresponding hardware node cannot be enabled for send.
MIDICAPSA_USES_BRIDGE * Set this flag to indicate that the device is a candidate for the MMPM/2 bridge.
MIDICAPSA_NOT_DEFAULT * Set this flag to indicate that this device should be selectable as the default device used by MIDISimpleOpen.
MIDICAPSA_RUNNING_STATUS Set this flag to tell RTMIDI that the device or the driver, or both, support running status.
Registering a Type-A Driver
The following is an example of registering a Type-A driver:
USHORT __far __loadds __cdecl Open( USHORT usPort, USHORT usMode )
{
// Open hardware
// For example: grab IRQ, send I/O commands to initialize the chips
}
USHORT __far __loadds __cdecl Close( USHORT usPort, USHORT usMode )
{
// Close hardware
// For example: detach IRQ
}
USHORT __far __loadds __cdecl RecvByte( USHORT usPort, BYTE b )
{
// Send byte bData to hardware
// For example: via an outp() command
}
USHORT __far __loadds __cdecl RecvString( USHORT usPort, BYTE __far *pb,
USHORT usLength )
{
// Send byte bData to hardware
// For example: via an outp() command
}
void __far __loadds __cdecl *Ioctl( PIOCTL_RP pioc )
{
// Process MMPM/2 IOCtl commands here, like volume change
// pioc is a pointer to the actual IOCtl request packet
}
HW_REGISTER hwreg; ULONG ulHandle; PFNSENDBYTE pfnSendByte; hwreg.usSize=sizeof( HW_REGISTER ); hwreg.in.flCapabilities = MIDICAPSA_INPUT | MIDICAPSA_OUTPUT; hwreg.in.pszDeviceName="My Device"; hwreg.in.pfnOpen=Open; hwreg.in.pfnClose=Close; hwreg.in.pfnRecvByte=RecvByte; hwreg.in.pfnRecvString=RecvString;
if( !reg.pfnHWRegister( &hwreg ) )
{
// Error
// Return
}
ulHandle=hwreg.out.ulHandle;
pfnSendByte=hwreg.out.pfnSendByte;
Audio Device Driver Exerciser (PMADDE) Tool
The Audio Device Driver Exerciser (PMADDE) is a PM-interface tool you can use to test code for low-level MMPM/2 components, such as audio device drivers or stream handlers. Using PMADDE, you can test various stages of your code at the Ring 0 level. This is useful when you want to verify that individual functions are working in your device driver without testing media control interface code (which might not be written yet). Each time you complete a function, you can test the function to see that it works, and then continue with the development of your driver.
Setting Up the Program
Before using PMADDE, OS/2 2.xwith MMPM/2 must be installed on your computer. The PMADDE source files are located in the DDK\MMOS2\MMTOOLKT\ NEATSTUF\PMADDE subdirectory. To build the PMADDE program, change to the PMADDE subdirectory, type NMAKE, and press Enter. Your output is the executable file (PMADDE.EXE). You can then type PMADDEfrom the command line to start the program. The Audio Device Driver Exerciser window is displayed. [Artwork not shown]
The PMADDE program defaults to the first waveform audio device it locates. To change the default option, select Options. Select Change Deviceto display the Change Audio Device window. [Artwork not shown]
This window contains information about each installed audio device including the logical device name, physical device name, and product information. Select the audio device you want to test.
PMADDE Functions
The PMADDE tool uses Stream Programming Interface Functionsto test your audio device driver. The Data Streammenu on the Audio Device Driver Exerciser window includes the following choices: (See Stream Setup and Controlfor additional information on SPI functions.)
SpiGet Handler
This option sends an SpiGetHandler function to return a stream handler ID and ensure the stream handler is loaded. Although this function does not perform any actions on the audio device driver, you must complete this function before creating a stream.
SpiCreate
This option sends an SpiCreateStream function to the stream handler to create a data stream of a given data type. The data is then passed to the audio device driver using a DDCMD_REG_STREAMmessage, which establishes a communication link and registers a stream instance with the device driver.
SpiAssociate
This option sends an SpiAssociate function to link a stream objectwith a given stream source or target. A data object must be identified for use with a stream before the stream can be started.
SpiStart
This option sends an SpiStartStream function to start data streaming for a stream instance or group of streams. The device driver receives several calls including DDCMD_SETUP, DDCMD_WRITE, and DDCMD_CONTROL(DDCMD_START) messages.
SpiStop
This option sends an SpiStopStream function to the stream handler, which is translated to the audio device driver as a DDCMD_CONTROL(DDCMD_STOP) message.
SpiInstall Protocol
This option sends an SpiInstallProtocol function to install stream protocolin the stream handler. It also generates an internal Stream Protocol Control Block (SPCB) key, which is used to differentiate between multiple SPCBs of the same data stream type. If your device driver can perform using a type of data format that the MMPM/2 subsystem currently does not use as its default, use this option to install new protocol that your device driver supports.
SpiDestroy
This option sends an SpiDisableSync function to destroy the stream you created with SpiCreate. SpiDestroy calls the DDCMD_CONTROL(DDCMD_STOP) and DDCMD_DEREG_STREAMmessages at the inter-device driver communication (IDC) level. (See Inter-Device Driver Communication (IDC) Interface.)
SpiSeek
This option sends an SpiSeekStream function to set the time within the audio device driver. You can seek the stream to a certain position, back to 0, or position it forward.
SpiQuery Time
This option sends an SpiGetTime function to the stream handler, which issues a DDCMD_STATUSmessage to the audio device driver to report the current stream time in milliseconds.
PMADDE Scenario
The following test scenario uses the PMADDE program to play back a waveform audio file from the source file system stream handler (FSSH) to the target audio system stream handler (AUDIOSH$). See Stream Setup and Controlfor detailed information on the phases of operation for a data stream.
Step 1
To get a handler ID, select Data Stream. Select SpiGet Handlerfor a list of MMPM/2 installed handlers. [Artwork not shown]
Select AUDIOSH$ (audio stream handler) and FSSH (file system stream handler ), and select OK.
Note:AUDIOSH$ and FSSH are the only handlers that can be tested using the PMADDE program. The source code can be modified to create tools that test stream handlers other than AUDIOSH$ and FSSH.
The Active Handlers window then lists the handler names and classes and the IDs for AUDIOSH$ and FSSH. [Artwork not shown]
A handler ID is provided for an active handler to be a source (producer) and a target (consumer). After you have both a producer and consumer stream handler, you can advance to step 2 to create the stream.
Step 2
To create the stream, select Data Stream. Select SpiCreateto display the Create Data Stream window. [Artwork not shown]
Enter the input source and target stream handler IDs. For example, enter the FSSH source ID (4) and the AUDIOSH$ target ID (2). Select a stream data type, and select OK.
The Stream State field in the Active Streams window displays information about the stream that has been created. The audio device driver has accepted the audio IOCtls and the IDC APIs to create the stream.
Step 3
To associate the stream with an audio file, select Data Stream. Select SpiAssociateto display the Associate Data Stream window. [Artwork not shown]
Type the input stream number, an audio file name, and select OK. You can now start the stream you created, or you can create several streams.
Step 4
To start the stream, select Data Stream. Select SpiStartto display the Start Stream window. [Artwork not shown]
Type the stream number and select a start flag. The SpiStartStream function starts data streaming in a specific stream or in a synchronized group of streams. Select the Start flag to start the stream immediately. Select the Preroll flag to cause the source stream handler to start and fill the buffers. An event is generated by the Sync/Stream Manager when a stream is prerolled. The application can then start the stream (or streams) for improved real-time response and initial synchronization of streams.
You can perform a stop at any time on the waveform audio file. To stop a stream, select Data Stream. Select SpiStopto display the Stop Stream window. [Artwork not shown]
Type the stream number and select the appropriate stop flag. There are three types of stops. The first is the regular stop or pause, which pauses the data stream but does not disturb any data. The second type of stop is a discard stop, which stops the stream immediately and discards any data left in the stream buffers. The third type is a flush stop, which stops the source stream handler, but the target stream handler continues until the last buffer held when the stop was requested is consumed by the target stream handler.
For a discard or flush stop, the Sync/Stream Manager detects when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event in the Event Monitor window.
Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.
Note:Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the event routine of the application. To restart the stream after you have paused or stopped it, select SpiStartfrom the Data Streammenu. The program restarts the stream and informs you when an end-of-stream (EOS) is reached.
Step 5
To get the stream time, select SpiQuery Timefrom the Data Streammenu. [Artwork not shown]
Type the input stream number and select OK. The stream time is displayed in milliseconds.
PMADDE Script Interface
To pipe a test script that already exists into the program, select Run Script Filefrom the Optionsmenu. [Artwork not shown]
Select the script file you want to pipe into the PMADDE program, and select OK. If the script file exists, the user interface of the PMADDE program is disabled and commands are accepted from the script file only. The following figure is an example of a PMADDE test script.
;***************************************************** ;** Audio Device Driver Exerciser V 1.0 ;** Test Script File. ;***************************************************** BEGIN ; DEVICENAME AUDIO1$ ; device name GETHANDLER AUDIOSH$ ; stream handler name GETHANDLER FSSH ; CREATE 3 2 3 ; Source ID, Target ID & Data type index SLEEP 1000 ; Sleep for 1000 milliseconds CREATE 3 2 3 ; SLEEP 1000 ; ASSOCIATE 1 WELCOM.WAV ; stream number & Audio file SLEEP 1000 ; ASSOCIATE 2 PMADDE.WAV ; SLEEP 1000 ; START 1 0 ; stream number & flag (0=Start, 1=Preroll) SLEEP 5000 ; START 2 0 ; END ;
The following information describes the syntax associated with the PMADDE script language.
Syntax Description
BEGIN Starts the script file.
DEVICENAME device nameSpecifies the physical device name.
CREATE hidSource hidTarget datatypeCreates a data stream of datatypefrom hidSourceto hidTarget. Select SpiCreatefrom the Data Streammenu to view the stream data types available. The data types listed correspond to a number beginning with 0. The second data type in the list is 1, the third is 2, and so on. To create a data stream from FSSH to AUDIOSH$ of data type PCM, 16-bit, 44 kHz, and mono, type the following:
CREATE 4 2 3;
ASSOCIATE stream # filenameAssociates a data stream with a data object.
START stream# startflagsStarts a data stream. The startflagscan be one of the following:
�PREROLL
�START
STOP stream# stopflagsStops a data stream. The stopflagscan be one of the following:
�FLUSH
�DISCARD
�PAUSE
SEEK stream# mode units positionSeeks to the specified positionin the data stream using the specified unitsand specified mode.
DESTROY stream#Destroys the specified stream.
QRYTIME stream#Queries the stream time of the specified stream.
SLEEP sleepintervalSuspends execution of the script file for the duration of the
END Ends the script file.
You can also create a test script by recording your keystrokes to be piped into the PMADDE program at a later time. You must specify a name for the script file you want to create when starting the PMADDE program. If the script file exists, the user interface is disabled and commands are accepted from the script file only. If the script file specified does not already exist, all actions are recorded and a script file is created. For example, to create a script file named TEST.SCR, use the following syntax:
PMADDE TEST.SCR logfile
Note:You must specify a logfile(for example, TEST.LOG) when creating a test script. If you are using the command-line interface to execute a test script that already exists, you must also specify a logfile.
Stream Setup and Control
There are five phases of operation for a data stream:
1.Configuration
2.Creation
3.Association
4.Streaming/Synchronization
5.Destruction
Each of these five phases involves specific operational steps that an application can control. In any phase, the program can take action to modify certain options. The five phases are described below.
Phase 1. Configuration
After installation, each system has predefined or default connection configurations that allow applications to operate according to general default parameters chosen by the user or by the installation program. An example of stream configuration is where waveform audio data is configured to stream to the Line 1 Output on the IBM Audio Playback and Capture Adapter. This is a default connection that determines which hardware output resource the waveform audio stream will connect to. These configuration options are established when you run the Multimedia Setup program of the MMPM/2 system. Application installation utility programs can also set up connection defaults. Note that the source and target stream handler, as well as the source and target device association, must be specified when the stream is created.
[Artwork not shown]
Phase 2. Creation
When a media control driver (or other multimedia application) determines that data will be streamed between devices, it can invoke SpiCreateStream, which results in the stream being created. The caller specifies the source and target stream handler IDs, source and target device-specific information, and the stream data type. (Use the SpiEnumerateHandlers function to return a list of stream handler names. You can then use the SpiGetHandler function to return a handler ID given a handler name. Use the SpiEnumerateProtocols function to determine which data types a given stream handler can process.)
[Artwork not shown]
The Sync/Stream Manager notifies each of the two stream handlers that a stream is being created, and each stream handler must return a valid stream protocol control block (SPCB) to the Sync/Stream Manager. The Sync/Stream Manager will negotiate the parameters of the stream and notify the handlers by a SHC_NEGOTIATE_RESULT call to each handler. Negotiation consists of determining which SPCB parameters both stream handlers can accept. This includes stream buffer sizes and the number of buffers needed to maintain continuous streaming of data.
Typically, the Sync/Stream Manager allocates buffers for the stream, but it is possible to use the application buffer directly. The SPCBBUF_ USERPROVIDED flag in the SPCB indicates whether to use provided buffers or to allocate buffers. This is useful for streaming to or from the memory stream handler. In a split stream situation, a particular stream might not allocate its own buffers but use the buffers of another stream. In other words, it might share buffers. This is useful for interleaved data coming from one source but going to more than one destination.
For Sync/Stream Manager-allocated buffers, stream buffer allocation is done during stream creation. The number of buffers to allocate is taken from the "negotiated" SPCB. The buffers are allocated and then locked, so that they will not be paged out to disk. The buffers are unlocked and freed upon an SpiDestroyStream request. These buffers are available at Ring 3 in the process linear space and Ring 0 in global linear system memory. The Sync/Stream Manager will provide global descriptor table (GDT) selectors to allow Ring 0 stream handlers to access the buffer memory. The stream handler can assume that the Sync/Stream Manager manages the GDT selectors used. The maximum buffer size is 64KB.
Both handlers (source and target) share access to the buffers allocated by the Sync/Stream Manager. Note that if the minimum buffer space (specified in the SPCB) is not available, the stream creation will fail. The allocation of memory when the stream is created prevents the need to perform allocations of physical memory when the stream is active, which could result in disruption of data flow affecting the real-time performance of the stream. Therefore, it is advantageous to allow the Sync/Stream Manager to allocate buffers and lock them at stream creation time instead of providing buffers to the Sync/Stream Manager that probably cannot be locked when the stream is created.
Phase 3. Association
After a stream is created, and before it is possible to start the stream, it is necessary to make sure that a data resource, or stream object, is identified for use with the stream. For example, if the application wishes to stream waveform data from application memory (the application dynamically creates the waveform), then the application must make an association between the stream and the memory object. This is accomplished using the SpiAssociate function.
[Artwork not shown]
An association for a specific stream handler must match the type of the stream handler as well as the data type of the stream. Each stream handler will list supported object types in response to calling SpiEnumerateProtocols. Note that only one data object can be associated with a stream once the stream is created, and it is specific to a particular stream handler (that is, source or target). Associations can be changed, but the stream cannot be active; it must be stopped first (discard stop, flush stop, or EOS). The SpiAssociate function can be used to " reassociate" data objects for a stream handler as long as the stream handler is the type that the stream was created to handle.
Note:Devices should be associated with stream handlers only when the stream is created.
Phase 4. Streaming/Synchronization
There are several stream operation functions, and each can be used in conjunction with stream synchronization.
[Artwork not shown]
The following paragraphs contain outlines of the function descriptions.
SpiStartStream Starts data streaming in a specific stream or a synchronized group of streams, depending on the flags for this function. This function also allows a stream or group of streams to be prerolled. Preroll allows the source stream handlers to start and fill the buffers. An event is generated by the Sync/Stream Manager when the streams are prerolled. The application can then start the streams for better real-time response and initial synchronization of streams.
If multiple streams are involved, when the synchronization master is started or prerolled, all slavestreams can also be started or prerolled. This synchronization relationship can be set up by using the SpiEnableSync function after all streams are created.
The active stream protocol governs the amount of data buffered and the rate of data flow maintained. Both source and target stream handlers are controlled by the stream protocol (SPCB). Both handlers contribute to the contents of the SPCB when the stream is created. Stream events such as cue points are detected by the appropriate stream handler and an event notification is sent to the process that owns the stream.
SpiStopStream Stops data streaming in a given stream or streams. There are three types of stops for this command. The first is the regular stop or pause, which pauses the data stream, but does not disturb any data. The second kind of stop is a discard stop, which requests that the stream be stopped immediately and the data left in the stream buffers be discarded. The third type is a flush stop. This stop requests that the source stream handler be stopped, but that the target stream handler continue until the last buffer held at the time the stop was requested is consumed by the target stream handler.
For a discard or flush stop, the Sync/Stream Manager will detect when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event.
Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.
Note:Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the applications event routine.
SpiSeekStream Seeks to a specific point in the stream source object. Depending on the type of object associated with the stream at a source or target, this function directs the appropriate stream handler to relocate the current stream index, or position, to the specified location. The object types that support this function are memory, file, CD track, and library object. Use this function to reposition the stream forward or backward from its current position. This can be performed only on a newly created, unstarted stream or a stopped stream (discard stop, flush stop, or EOS).
SpiEnableSync Establishes stream synchronization between multiple streams. Stream synchronization is automatically handled by the stream protocol, depending on whether a given stream is the synchronization masteror slave. Once a synchronization relationship is established, synchronization is maintained according to real-time events detected at the master and passed on to the slaves. The application does not have additional stream events to process due to synchronization. Only one stream can be a master.
SpiDisableSync Stops stream synchronization for a given stream or streams. A previously designated stream master is disabled, and all synchronization under that master is deactivated.
SpiGetTime Fills in the current stream-specific time information. This allows an application to query the stream time. This function is supported for any stream that is active or stopped, and will not disrupt data transport in the stream. A more accurate method to determine the stream time is to enable stream time events, which will report stream time continuously and in real-time to the application.
Phase 5. Destruction
When a stream is no longer to be used by an application, it must be destroyed. Note that the stream handlers involved can remain active with other streams, and will remain available to create additional streams ( without additional calls to SpiGetHandler). The application will receive no further stream events in its event handling routine after calling the SpiDestroyStream function. All system resources allocated to the stream are released, including the physical memory used to create stream buffers. After the stream is destroyed, the stream handler state reverts back to its condition immediately prior to the creation of the stream. If the stream being destroyed is a master stream of a sync group, all synchronization under that master stream will become inactive. If the stream is a slave in a sync group, the stream will be removed from the sync group and will not affect the master or other slave streams in the group.
stream object
A stream object is the data resource or device channel that represents either the data source or target for a stream. In order for a stream to obtain data, it must be associated with a source stream object. This can be a waveform audio data object such as a file on the file system, or it can be a MIDI mapper stream handler from the MIDI hardware adapter. Also, the stream target handler must be associated with a target stream object. This could be a file which will be written to, or it could be an output device that will store, convert, or transmit the data.
Association of a stream with a source stream object, target stream object, or both may be permanent. In other cases, associations must be made whenever the stream is created and before the stream may be manipulated. For example, if there is only one audio adapter with only one input line, then the audio stream handler device driver will always associate a stream with that input line whenever it acts as a source.
Associations are tied to the concept of connections at the media control interface level of the system. Default connections can be made between logical devices and the actual physical device that performs the function of the logical device. Media drivers must use this connection information to determine the source and target handler names to be used on a subsequent SpiGetHandler. The connection information is also used to provide the source and target device or object associations used on an SpiCreateStream function.
Devices may be associated with stream handlers at stream creation time only . An SpiAssociate request can be used, however, to "re-associate" data objects with stream handlers after the stream has been created. The stream must be stopped (discarded, flushed, or EOS) to do this.
stream protocol
A stream protocol defines key parameters that control the behavior of a data stream. The application can query, install, or deinstall a specific SPCB from a stream handler. Each stream handler supports one or more stream protocols. An SPCB is uniquely identified by the value of the stream data type (SPCB key). One field in the SPCB key allows the stream handler to have multiple SPCB's installed for the same data type. This field can be used by an application to specify which SPCB, for any data type, it wants to use. Each application in the system could define multiple SPCB for the same data type (see the ulTypefield in the SPCBKEY data structure). The application can modify a stream protocol by installing a new SPCB and deinstalling the old SPCB.
Stream Programming Interface Functions
The stream programming interface (SPI) contains functions exported by the Sync/Stream Manager to support applications that control real-time data streams. These functions are used to perform stream creation, association, configuration, operation, synchronization, and destruction functions. SPI functions also include enabling applications to modify Stream Protocol Control Blocks (SPCBs) and querying a stream's time information.
/-------------------------------------------------------------\ |Function |Description | |--------------------------+----------------------------------| |SpiAssociate |Associates a data object with a | | |stream handler. | |--------------------------+----------------------------------| |SpiCreateStream |Creates a stream instance between | | |a source and a target stream | | |handler. | |--------------------------+----------------------------------| |SpiDestroyStream |Removes a stream instance from the| | |system. | |--------------------------+----------------------------------| |SpiDetermineSyncMaster |Determines the best master stream | | |to be used in a sync group. | |--------------------------+----------------------------------| |SpiDisableEvent |Disables event detection for a | | |particular event. | |--------------------------+----------------------------------| |SpiDisableSync |Removes a group of streams. | |--------------------------+----------------------------------| |SpiEnableEvent |Enables event detection for a | | |particular event. | |--------------------------+----------------------------------| |SpiEnableSync |Establishes a group of streams to | | |synchronize the streams. | |--------------------------+----------------------------------| |SpiEnumerateHandlers |Returns a list of the stream | | |handler names installed in the | | |SPI.INI file. | |--------------------------+----------------------------------| |SpiEnumerateProtocols |Returns a list of stream protocol | | |keys for the specified stream | | |handler. | |--------------------------+----------------------------------| |SpiGetHandler |Returns the handler ID for the | | |specified stream handler. | |--------------------------+----------------------------------| |SpiGetProtocol |Queries a stream handler for a | | |specified stream protocol. | |--------------------------+----------------------------------| |SpiGetTime |Queries the current stream time. | |--------------------------+----------------------------------| |SpiInstallProtocol |Installs or removes a specified | | |stream protocol for a stream | | |handler. | |--------------------------+----------------------------------| |SpiSeekStream |Seeks to a specified point in the | | |stream object or sets the current | | |stream time. | |--------------------------+----------------------------------| |SpiStartStream |Starts data streaming for a single| | |stream instance or a group of | | |streams. | |--------------------------+----------------------------------| |SpiSendMsg |Sends a message to a stream | | |handler. | |--------------------------+----------------------------------| |SpiStopStream |Stops data streaming for a single | | |stream instance or a group of | | |streams. | \-------------------------------------------------------------/
AP2/P2STRING Tool
This chapter describes the AP2 and P2STRING tools.
AP2
AP2 is the easiest and most complete automated method of testing the audio and video device driver. AP2 provides an easy to use PM interface to the P2STRING tool with a complete set of test scripts for the audio and video device driver. AP2 queries the device driver to determine the functions it supports by using the capability MCI (media control interface) string command. Based on these compatibilities, AP2 will create a list of test scripts that are supported by the default device drivers. You can run any combination of these scripts.
The AP2 tool consists of the file AP2.EXE, AP2.HLP, and AP2.INI and P2S_ DESC.TXT. AP2 also requires the P2STRING tool consisting of P2STRING.EXE AND P2S_DLL.DLL. These files are located in the IBM Developer Connection Device Driver Kit for OS/2. The AP2 script files are located in a subdirectory under AP2 called SCRIPTS, and the data files are located in another subdirectory called DATA.
AP2 does not require any parameters If AP2 is entered from the command line , AP2 will run, test the device capabilities and display all scripts that can be tested. The file P2S_DESC.TXT file contains the descriptions for all the AP2 test scripts. The results of the capability test are placed in the file CAPABLTY.TXT.
The following table shows the parameters that are available for AP2. The AP2 parameters include:
/-------------------------------------------------------------\ |Parameter |Description | |-------------------------+-----------------------------------| |[script_file] |Specifies the script files to be | | |used. The default is *.P2S. | | |Wildcards *,? are supported. | |-------------------------+-----------------------------------| |[-AMPMIX] |Specifies that the Ampmix scripts | | |will be selected when AP2 is | | |started. Ampmix scripts are denoted| | |by an 'A' in the first character in| | |the filename. | |-------------------------+-----------------------------------| |[-CD] |Specifies that the CD scripts will | | |be selected when AP2 is started. CD| | |scripts are denoted by a 'C' in the| | |first character in the filename. | |-------------------------+-----------------------------------| |[-CDXA] |Specifies that the CDXA scripts | | |will be selected when AP2 is | | |started. CDXA scripts are denoted | | |by an 'X' in the first character in| | |the filename. | |-------------------------+-----------------------------------| |[-MIDI] |Specifies that the MIDI scripts | | |will be selected when AP2 is | | |started. MIDI scripts are denoted | | |by an 'M' in the first character in| | |the filename. | |-------------------------+-----------------------------------| |[-WAVE] |Specifies that the Wave scripts | | |will be selected when AP2 is | | |started. Wave scripts are denoted | | |by a 'W' in the first character in | | |the filename. | |-------------------------+-----------------------------------| |[-VIDEO] |Specifies that the Video scripts | | |will be selected when AP2 is | | |started. Video scripts are denoted | | |by a 'V' in the first character in | | |the filename. | |-------------------------+-----------------------------------| |[-MPEG] |Specifies that the MPEG scripts | | |will be selected when AP2 is | | |started. MPEG scripts are denoted | | |by "_M" as the first two characters| | |in the filename. | |-------------------------+-----------------------------------| |[-INTERACTIVE] |Specifies that the Interactive | | |scripts will be selected when AP2 | | |is started. An interactive script | | |requires some form of user input | | |during the execution of the script.| | |A script is denoted as interactive | | |by an 'I' in the seventh character | | |in the filename. | |-------------------------+-----------------------------------| |[-ALL] |Specifies that all loaded scripts | | |will be selected. | |-------------------------+-----------------------------------| |[-BATCH] |Specifies that testing will be in a| | |batch mode. One or more of the | | |above selection parameters is | | |required to specify which scripts | | |are to be tested. In batch mode AP2| | |will automatically start testing, | | |log any messages to an output file | | |and terminate when complete. If the| | |interactive switch is used in | | |conjunction with batch, interactive| | |will be ignored, and no interactive| | |scripts are tested in batch mode. | | |All output and failed scripts are | | |logged to an output file. If an | | |output file is not specified, the | | |default is AP2.OUT. | |-------------------------+-----------------------------------| |[-oOUT_FILE] |If this parameter is specified, all| | |scripts that FAIL will also be | | |logged to this file. | |-------------------------+-----------------------------------| |[-TEST] |Specifies that AP2 will | | |automatically test device | | |capabilities at startup. | |-------------------------+-----------------------------------| |[-NOTEST] |Specifies that AP2 will preform no | | |testing of device capabilities at | | |startup. | |-------------------------+-----------------------------------| |[-DATAPATH] |Specifies the data path to be used | | |by AP2. This is the same as | | |selecting the Data Path button. | \-------------------------------------------------------------/
Starting and Running AP2
When running AP2 for the first time, it is necessary to set the Data Path. The Data Path points to the directory where all the data files for AP2 are located. Every AP2 script that requires a data file uses an environment variable AP2PATH, which is set by AP2.
[Artwork not shown]
The Start Testbutton tests the selected scripts. To test scripts, highlight the selected scripts and click on the Start Testbutton. After each script is completed, the status for that script is displayed. The output for every script is located in the OUT directory. The output file has the same name as the script with the extension of "OUT".
The View Output button allows the viewing of the files that are generated from the execution of the *.P2S files. To view the output for a specific script, highlight the script, and click on the View Outputbutton.
The Data Path button displays a dialog box and allows you to select the location of the AP2 data directory. AP2 will not run correctly if the data path is not set to the directory containing the AP2 data files.
P2STRING
Use the P2STRING script processing tool to test media control interface string commands in the MMPM/2 environment.
The P2STRING tool processes script files (containing string commands and tool directives) to test string commands in your application programs. The P2STRING tool tests your low-level components at the Ring 3 level (as compared to the PMADDE tool, which tests code at the Ring 0 level). P2STRING extracts the strings from the script files and processes the commands through the mciSendString function. Messages and error conditions of the processes included in the scripts are logged to an output file and displayed in windows. P2STRING comes with a set of predefined scripts to test audio and video functions. These tests are a group of test files called test suites. For more information about test suites, see Testing Device Drivers.
Each process logs to its own display window, but all processes log to the same output file. In addition, if you close the display window, the string execution thread is immediately destroyed and the entire process ends.
[Artwork not shown]
Output messages include all non-comment lines read from the script (for example, script directives, command strings, expected return values, expected and received notify messages, and status lines). In addition, errors and debugging statements of unsuccessful string commands are logged to a file named P2STRING.LOG file.
Setting Font Size and Type
Before you start the P2STRING tool, you can change the size and type of font displayed in the P2STRING window on the desktop. For example, to specify Times Roman font with a 10 point font size, type:
SET P2STRING_FONTFACE=TIMES SET P2STRING_FONTSIZE=10
You can specify either font face, font size, or both. Possible FONTFACE values include SYSTEM, COURIER, TIMES, or HELVETICA (default). Possible FONTSIZE values include 8 (default), 10, 12, 14, or 18.
Starting P2STRING
The P2STRING tool consists of two files: P2STRING.EXE and P2S_DLL.DLL. These files are located in the IBM Developer Connection Device Driver Kit for OS/2. The following example displays the syntax used to start the P2STRING program. Associated parameters are described in the following table.
P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]
Note:The parameters are case sensitive.
The following list describes the parameters associated with the P2STRING program.
Parameter Description
script_fileSpecifies the script file name you want to process.
Note:Refer to P2STRING Script Languagefor information on the contents of a script file and how to interpret the script language.
[-a]out_fileSpecifies the output file name containing the results of the test. This file contains only the results of the test you are running, unless you specify the optional -a parameter. For example, to append the output of a script file named SAMPLE.SCR to output currently in a file named MDM.OUT, type:
P2STRING SAMPLE.SCR -aMDM.OUT
[-eerr_file] Specifies the optional error file name that receives messages from string commands that completed unsuccessfully. For example, to create an error file named MDM.ERR, type:
P2STRING SAMPLE.SCR MDM.OUT -eMDM.ERR
[-d|-D] Specifies one of the following optional parameters:
-d Instructs P2STRING to end after processing a script file.
Use this parameter when you are running test cases automatically .
There is no change in the output.
When the script file has completed processing, P2STRING prompts
you with a message requiring you to end the test.
-D Behaves identically to the -d parameter except that the script
directives requiring user input are ignored.
Note:Refer to Tool Directivesfor information on how to add execution directives (which require user input) in a script file.
-E Causes the script file to exit after the first error. By default, script files run to completion regardless of errors. For example, the following command ends the processing of SAMPLE.SCR after an error is encountered:
P2STRING SAMPLE.SCR -aMDM.OUT -d -eMDM.ERR -E
-t Records time stamps for strings and MM_MCIPASSDEVICE notification messages.
P2STRING Script Language
This section describes the contents of a script file and how to interpret the script language. Script files can contain several types of lines including:
�Comments
�Tool Directives
�MMPM/2 String Commands
�Expected Return Strings
�Expected Error Messages
�Expected Notification Messages
The following example displays an example of how a script file appears.
@ PROCESSES = 2
@ EVENTS = { HASCTRL1 = 1 , HASCTRL2 = 0 }
#
#
#
@ PROCESS 1
;
; set masteraudio level for session to 10 % - will affect all
; 3 processes
;
masteraudio volume 10
;
; open waveaudio device non - exclusively
;
open waveaudio alias wav1 shareable notify
+ MM _ MCINOTIFY MCI _ NOTIFY _ SUCCESSFUL MCI _ OPEN # 1
@ WAIT _ NOTIFY 1 60000
@ WAIT _ PASSDEVICE wav1 60000
@ WAIT _ NOTIFY 21 60000
Comments
Script comment lines must start with either a semi-colon(;) or comment sign(#) in the first column. These comment lines are neither displayed nor echoed in the output file. If you want a remark to appear in the output, use the @REM directive.
P2STRING allows for a variable number of lines to be displayed in its window. Regular comment lines (header lines) are not displayed nor written to the output file.
Tool Directives
The P2STRING tool supports either multithreaded or multiprocess execution, but not both. You can use tool directives to test either @PROCESSES or @ THREADS in a script file.
Tool directives start with an at sign(@) in the first column. These directives affect the execution and appearance of the output. The following classes of directives are recognized:
�Initialization
�Execution
Initialization Directives
Use initialization directives to set up the content of the script file. These directives must appear before execution directives because the tool preprocesses the script file and builds process command buffers.
The @THREADS and @PROCESSES directives are mutually exclusive. In other words, the P2STRING tool supports either multithreaded or multiprocess execution in a script file (not both). In addition, there is a limit of 10 processes or threads per script file.
The following table lists the supported initialization directives.
Directive Description
@PROCESSES=x
Specifies the number (x) of processes the script file will be running. For example:
@PROCESSES=2
@THREADS=x
Specifies the number (x) of threads the script file will be running.
@EVENTS={n[=0|1] [,n[=0|1]]}
Specifies one or more names of events. Events are user-defined with a maximum of 15 characters. Events can be set to 1 or 0. Set an event to 1 for an event that is set with the @SET_EVENT execution directive. Set an event to 0 to clear or reset the event. If no initialization values are specified, the event is initialized to 0. For example:
@EVENTS={brad=1,john=1,test=0}
Execution Directives
Use execution directives to process the script file. Again, the @THREAD and @PROCESS directives are mutually exclusive.
The following table lists the supported execution directives.
Note:Timing out on the @WAIT_EVENT and @WAIT_NOTIFY directives is notconsidered a failure.
Directive Description
@THREAD x
Specifies that the script lines following this directive belong to thread number xuntil the next @THREAD directive is encountered.
@PROCESS x
Specifies that the script lines following this directive belong to process number xuntil the next @PROCESS directive is encountered.
@SET_EVENT name 0|1
Sets the event nameto either 1 or 0. Use 1 to mark that the event has happened. Use 0 to clear or reset the event.
Note:The event must be declared through the @EVENTS directive.
@WAIT_EVENT name [to]
Waits until the event nameis set to 1. @WAIT_EVENT does not cause a change of the event state. If you need a reusable event, use this directive.
The timeout (to) is specified in milliseconds. If omitted, it defaults to 3 minutes.
@WAIT_NOTIFY x [to]
Waits for a specific number (x) from an expected MM_ MCINOTIFY notification message. This number must match the index used in the MM_MCINOTIFY reference line. The @WAIT_NOTIFY events are not reusable because there are no events that logically reset it.
The timeout (to) is specified in milliseconds. If omitted, it defaults to 3 minutes.
If the associated mciSendString function fails, the event is posted to prevent delays for notifications that are never going to be sent.
@WAIT_PASSDEVICE alias [to]
Waits until the device instance with an alias of aliasgains use. This assumes that the alias names used within a script file are unique. The maximum alias name length is 20 characters.
Note:Use a unique alias for every OPEN command.
The timeout (to) is specified in milliseconds. If omitted, it defaults to 3 minutes.
The tool assumes that a unique alias is specified on each OPEN string command. If unique aliases are not used, errors conditions might occur.
@REM comment
Echoes the commentto the screen and the output log file. All other script comment lines (those starting with ;or #) are neither transferred nor displayed.
@PAUSE to
Pauses processing of the current thread or process in the input script file for the specified time. It does not stop the processing of the notifications or window functions. Other threads or processes are not affected by this directive.
@BREAK [ message ]
Causes a message box to appear with messagetext. Script processing is halted until the user responds with the correct action . For example:
@BREAK [replace the CD]
@CHECK [message]
Grades the success of the previous command based on the user's response. A pop-up window displays the messageand prompts the user with Yes or No push buttons. The status is passed if the user selects Yes, or failed if No is selected. For example:
@BREAK The music will play for 5 seconds. Ready to time it? play cdaudio notify @PAUSE 5000 @CHECK Did it play?
MMPM/2 String Commands
All lines that do not fall into any of the other categories are interpreted as MMPM/2 string commands. These lines are passed to the Media Device Manager (MDM) through the mciSendString function after the environment variables have been substituted.
Any token in the string command line bracketed by question marks (such as ? FOO?) is interpreted as an environment variable. The actual value of the environment variable is substituted into the string before it is passed to the mciSendString function. If the variable is not found, a warning is issued and the token is replaced with a null string. For example, assuming the environment string MMDATA is set to D:\DATA, open ?mmdata?\temp.wav alias a is equal to open d:\data\temp.wav alias a.
Expected Return Strings
Many MMPM/2 commands return strings. It is possible to check these strings against an expected value with an expected return string line.
An expected return string line has the format:
=result
The equal sign(=) must be in column 1 and should have no trailing spaces. If an empty string is expected, nothing should follow the = (not even spaces). For example:
status cdaudio ready wait =TRUE status cdaudio mode wait =stopped
The expected result is always interpreted as a string. This might produce some unusual outputs for commands that return binary data.
Where the return is a textual numerical value, it can be matched to a tolerance range of +/-10% using a tilde(~) before the number. This is typically used when the exact value cannot be known. For example:
set foo time format milliseconds wait play foo notify @PAUSE 1000 stop foo wait status foo position wait =~1000
Thus, the status command is considered successful if the returned string is in the range 900 - 1100.
Expected Error Messages
When an MMPM/2 string command is expected to fail with an error, use the expected error line to specify the expected error. The expected error line has the format:
=!error
The =! must start in column 1. If any error is acceptable, then use the keyword ERROR. If a specific error is expected, type the exact error message after the =!. For example:
open sequencer alias mymidi wait load mymidi nofile.foo =!File not found.
Be careful about extra blanks in the expected-error and expected-result lines. The case of the strings is unimportant; however, the comparison will fail if the spacing or punctuation does not match exactly.
Expected Notification Messages
Many MMPM/2 string commands cause notification messages to be sent to the P2STRING tool. The system uses notification messages to respond to applications. For example, notification messages indicate system status regarding completion of a media device function or passing of the ownership of a media control device from one process to another.
It is possible to verify that the proper notifications are received by using an expected-notify line. Each expected notification line begins with a plus sign(+) in column 1. The following types of notification lines are possible:
�Command completion/error notifications
�Event notifications
�Position change notifications
Note:Any or all notification messages might be expected for a single MMPM /2 string command.
Command Completion/Error Notifications
A MM_MCINOTIFY line notifies an application when a device successfully completes the action indicated by a media message or when an error occurs.
+MM_MCINOTIFY notify-code [#x]
/-------------------------------------------------------------\ |Keyword |Description | |------------------+------------------------------------------| |notify-code |Specifies the notification message code, | | |for example, MCI_NOTIFY_SUCCESSFUL. The | | |spelling must be the same as the #defines | | |in the OS2ME.H file for the notify codes. | |------------------+------------------------------------------| |message |Specifies the media control interface | | |message that caused the notification, for | | |example, MCI_PLAY. The spelling must be | | |the same as the #defines in the OS2ME.H | | |file for media control interface messages.| |------------------+------------------------------------------| |x |Specifies a unique number (x) used to | | |associate @WAIT_NOTIFY directives with | | |particular notifications. This number has | | |nothing to do with the order in which | | |strings are sent. The number must be | | |unique and in the range 1-99. | \-------------------------------------------------------------/
Event Notifications
A MM_MCIPOSITIONCHANGE line notifies an application of the current media position.
+MM_MCIPOSITIONCHANGE position %user-parameter #x
/-------------------------------------------------------------\ |Keyword |Description | |------------------+------------------------------------------| |position |Specifies the expected MMTIME position of | | |the first position-change message. | |------------------+------------------------------------------| |user-parameter |Specifies the user parameter to be | | |returned. This should be the same as the | | |return value specified in the | | |SETPOSITIONADVISE string command. Note | | |that the return value must be a unique | | |integer in the range of 1 - 99. | |------------------+------------------------------------------| |x |Specifies the number (x) of position | | |change messages expected. For further | | |information, refer to Limitations of | | |MM_MCIPOSITIONCHANGE Verification. | \-------------------------------------------------------------/
Position Change Notifications
A MM_MCICUEPOINT line notifies an application that the playlist processor has encountered a messageinstruction.
+MM_MCICUEPOINT position %user-parameter
/-------------------------------------------------------------\ |Keyword |Description | |------------------+------------------------------------------| |position |Specifies the expected MMTIME position of | | |the first position-change message. | |------------------+------------------------------------------| |user-parameter |Specifies the user parameter to be | | |returned. This should be the same as the | | |return value specified in the | | |SETPOSITIONADVISE string command. Note | | |that the return value must be a unique | | |integer in the range of 1 - 99. | \-------------------------------------------------------------/
Note:Other notifications cannot be compared because they do not allow for a user-parameteras part of the message, which is essential for the tracking of related notifications.
Limitations of MM_MCIPOSITIONCHANGE Verification
There are limitations to what you can verify in the P2STRING tool using event notification lines. The MM_MCIPOSITIONCHANGE line requires the use of the "return value" item in the respective string commands. This line also does not provide for timing start point, for example, playing has started. The P2STRING tool can only count the number of messages received for a specific user parameter (used as a key) and check if subsequent messages have positions approximate to the given expected position interval. The script writer has the responsibility to determine how many POSITIONADVISE messages are expected, taking into account the duration of playing, time format, and start position of the play/record. The reference positiongiven in the expected notification line must be in MMTIME units. If the "expected number of messages" parameter is omitted, the tool verifies only the position interval (not the number). In case of scripts where play, seek, or record are used to cover non-monotonic ranges, the tool might report failures on position-advises because it expects each positionadvise to be in the next position interval from the previous message. If the script makes a jump to a position that does not conform to this, the status will be logged as failed.
For example:
setpositionadvise SomeDevice every 10000 on return 5 +MM_MCIPOSITIONCHANGE 10000 %5 play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages) seek SomeDevice to 30000 wait play SomeDevice notify (produces a number of messages starting at 30000)
The position-change messages are logged as failed, because of the lapse in position interval. A way to handle this situation is to disable the position-change before an explicit position jump is made and enable the same position-advise with a different user parameter.
For example:
setpositionadvise SomeDevice every 10000 on return 5 +MM_MCIPOSITIONCHANGE 10000 %5 play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages) setpositionadvise SomeDevice every 10000 off seek SomeDevice to 30000 wait setpositionadvise SomeDevice every 10000 on return 6 +MM_MCIPOSITIONCHANGE 10000 %6 play SomeDevice notify (produces a number of messages starting at 30000)
Processing Logic
A string command line can be followed by zero to one return value lines, or zero to three notification lines. Note that this is an exclusive OR, meaning that specifying both expected return value and expected notification is not going to give reliable results due to the fact that returned buffer does not become valid prior to the end of the notify message. Also, in case of notify flags, return values are in the procedural interface format rather than in the string interface format.
The MDM will not be able to convert return values to strings for commands processed with the notify flag because media control drivers will be sending their notify messages directly to the application.
Status of each command is determined in two stages. The first stage is at string execution. If the mciSendString function returns an error and there was no =!ERROR reference line in the script following the command string line, the command is considered failed. If a return value was found after mciSendString is processed, the tool will check for expected return and perform comparison of the two. It they do not match, the command is considered failed. In case of an error that is not in the range understood by the mciGetErrorString function, the command is considered failed even if the !ERROR was encountered.
The second stage of the comparison is after a notification is received and after all the commands are issued. If a notification was received and it was successfully compared to the expected notification line, the command is considered successful. If there was no reference notification line, status of the command will not be assigned, unless notify-error was returned. After all the scripts are processed, expected reference notifications will be used to determine if all the notifications were received. The commands that did not receive a notification, and had an expected notification line of the type, are marked failed. Note that command strings are not examined for presence of a notify flag and it is the writer's responsibility to create an expected notify line if it is of importance. In case of expected NOTIFY_SUCCESSFUL messages, all codes other than NOTIFY_ERROR are considered valid. This includes NOTIFY_SUCCESSFUL, NOTIFY_ABORTED and NOTIFY_SUPERSEDED. If any other notify code was specified as expected, and exact match will be checked for. If NOTIFY_ERROR is expected, all errors in the range are verified as passed. There is no facility for verification of an exact error code returned in the notification.
Testing Device Drivers
Test suites have been provided with this release of the DDK to assist in certifying audio and video device drivers. The test suites provided consist of several test cases. The following sections describe how to:
�Set up the environment for running the test suites
�Run the test suites
�Analyze the test
Setting Up the Environment for Running Test Suites
Before using the audio or video test suites with the P2STRING tool, do the following:
1.Make sure that OS/2 2.1 and the adapter to be tested are installed.
2.Update the CONFIG.SYS file.
All the test suites use environment variable to determine the location of the input data files. Add the following SET statements to the CONFIG.SYS file.
SET MMDATA=<path> SET MMDATA-AUD=<path> SET TESTDATA=<path>
The path for MMDATA and MMDATA-AUD must specify the path to the audio input files. For example, your .WAV or .MID files. The path for TESTDATA must specify a path to a temporary working directory that you create.
The following files must be loaded, and their path must be specified in the CONFIG.SYS file:
SETENV.CMD
RESETINI.CMD
HWCODE.CMD
P2STRING.EXE
P2S_DLL.DLL
3.Shut down and restart your workstation so the CONFIG.SYS parameters will take effect.
4.Run HWCODE.CMD for each test suite to be tested.
This file is in the IBM Developer Connection Device Driver Kit for OS/2HWCODE.CMD is a REXX command that determines each test case's exact hardware needs and displays the results. The test case's name contains information that HWCODE.CMD uses to make these determinations, so it is important not to change the name of the test case.
The syntax for HWCODE.CMD is:
HWCODE <Test Case Name>
Note:The Test Case Name must include the file name extension. HWCODE.CMD displays the brand and model of audio and video adapters currently supported by OS/2 2.1. The adapter being tested is not listed if it is new , but this information is useful for comparing results based on expected compatibility with other manufactures.
HWCODE.CMD also displays audio and video hardware codes.
Hardware Codes
The hardware codes are two digit codes. The hyphen (-) in the tables indicate the position of the unspecified digit in the code. For example, if you receive the hardware code 84, you would look in the 8- column and the - 4 column to decipher the hardware code.
Audio Hardware Codes
Audio Capture Playback Adapters
/--------------------------------------------------------------\ |Hardware Code |ACPA |Number of Cards | | | |Unspecified | |--------------------+--------------------+--------------------| |0- | | | |--------------------+--------------------+--------------------| |1- |1 | | |--------------------+--------------------+--------------------| |2- |2 | | |--------------------+--------------------+--------------------| |3- |3 | | |--------------------+--------------------+--------------------| |8- | |1 | |--------------------+--------------------+--------------------| |9- |1 |1 | |--------------------+--------------------+--------------------| |A- |2 |1 | |--------------------+--------------------+--------------------| |B- |3 |1 | |--------------------+--------------------+--------------------| |G- | |2 | |--------------------+--------------------+--------------------| |H- |1 |2 | |--------------------+--------------------+--------------------| |I- |2 |2 | |--------------------+--------------------+--------------------| |J- |3 |2 | |--------------------+--------------------+--------------------| |O- | |3 | |--------------------+--------------------+--------------------| |P- |1 |3 | |--------------------+--------------------+--------------------| |Q- |1 |3 | |--------------------+--------------------+--------------------| |R- |3 |3 | \--------------------------------------------------------------/
OEM
/--------------------------------------------------------------\ |Hardware Code |OEM |Number of CDROMs | |--------------------+--------------------+--------------------| |-0 | | | |--------------------+--------------------+--------------------| |-1 |OPL0 (original Sound| | | |Blaster chipset) | | |--------------------+--------------------+--------------------| |-4 |Sound Blaster 16 | | |--------------------+--------------------+--------------------| |-5 |ProAudio Spectrum 16| | |--------------------+--------------------+--------------------| |-6 |Sound Blaster Pro | | |--------------------+--------------------+--------------------| |-7 |Any Sound Blaster | | |--------------------+--------------------+--------------------| |-8 | |1 | |--------------------+--------------------+--------------------| |-9 |OPL0 (original Sound|1 | | |Blaster chipset) | | |--------------------+--------------------+--------------------| |-C |Sound Blaster 16 |1 | |--------------------+--------------------+--------------------| |-D |ProAudio Spectrum 16|1 | |--------------------+--------------------+--------------------| |-E |Sound Blaster Pro |1 | |--------------------+--------------------+--------------------| |-F |Any Sound Blaster |1 | |--------------------+--------------------+--------------------| |-G | |2 | |--------------------+--------------------+--------------------| |-H |OPL0 |2 | |--------------------+--------------------+--------------------| |-K |Sound Blaster 16 |2 | |--------------------+--------------------+--------------------| |-L |ProAudio Spectrum 16|2 | |--------------------+--------------------+--------------------| |-M |Sound Blaster Pro |2 | |--------------------+--------------------+--------------------| |-N |Any SB |2 | |--------------------+--------------------+--------------------| |-O | |3 | |--------------------+--------------------+--------------------| |-P |OPL0 (original Sound|3 | | |Blaster chipset) | | |--------------------+--------------------+--------------------| |-S |Sound Blaster 16 |3 | |--------------------+--------------------+--------------------| |-T |ProAudio Spectrum 16|3 | |--------------------+--------------------+--------------------| |-U |Sound Blaster Pro |3 | |--------------------+--------------------+--------------------| |-V |Any SB |3 | \--------------------------------------------------------------/
Special Hardware Needs
/-------------------------------------------------------------\ |Hardware Code |Special Hardware Needs | |--------------------+----------------------------------------| |W0 |Pioneer laser disc V80000 | |--------------------+----------------------------------------| |W1 |Pioneer laser disc V4400 | |--------------------+----------------------------------------| |W2 |Pioneer laser disc V4200 | |--------------------+----------------------------------------| |W3 |Pioneer laser disc V4300D | \-------------------------------------------------------------/
Video Hardware Codes
VCA
/--------------------------------------------------------------\ |Hardware Code |VCA |Number of Cards | | | |Unspecified | |--------------------+--------------------+--------------------| |4- | | | |--------------------+--------------------+--------------------| |5- |1 | | |--------------------+--------------------+--------------------| |6- |2 | | |--------------------+--------------------+--------------------| |C- | |1 | |--------------------+--------------------+--------------------| |D- |1 |1 | |--------------------+--------------------+--------------------| |E- |2 |1 | |--------------------+--------------------+--------------------| |K- | |2 | |--------------------+--------------------+--------------------| |L- |1 |2 | |--------------------+--------------------+--------------------| |M- |2 |2 | \--------------------------------------------------------------/
OEM
/--------------------------------------------------------------\ |Hardware Code |OEM |Number of CDROMs | |--------------------+--------------------+--------------------| |-0 |Any video capture | | | |card | | |--------------------+--------------------+--------------------| |-1 |Any video capture | | | |card and a Sound | | | |Blaster 16 | | |--------------------+--------------------+--------------------| |-2 |Any video capture | | | |card and a ProAudio | | | |Spectrum 16 | | |--------------------+--------------------+--------------------| |-8 |Any video capture |1 | | |card | | |--------------------+--------------------+--------------------| |-9 |Any video capture |1 | | |card and a Sound | | | |Blaster 16 | | |--------------------+--------------------+--------------------| |-A |Any video capture |1 | | |card and a ProAudio | | | |Spectrum 16 | | |--------------------+--------------------+--------------------| |-G |Any video capture |2 | | |card | | |--------------------+--------------------+--------------------| |-H |Any video capture |2 | | |card and a Sound | | | |Blaster 16 | | |--------------------+--------------------+--------------------| |-I |Any video capture |2 | | |card and a Sound | | | |Blaster 16 | | \--------------------------------------------------------------/
Special Hardware Needs
/-------------------------------------------------------------\ |Hardware Code |Special Hardware Needs | |--------------------+----------------------------------------| |X0 |IBM VCA NTSC | |--------------------+----------------------------------------| |X1 |Jovian SuperVia NTSC | |--------------------+----------------------------------------| |X2 |Jovian QuickVia NTSC | |--------------------+----------------------------------------| |X3 |Video Blaster NTSC | |--------------------+----------------------------------------| |X4 |IBM VCA PAL | |--------------------+----------------------------------------| |X5 |Jovian SuperVia PAL | |--------------------+----------------------------------------| |X6 |Jovian QuickVia PAL (WinMovie) | |--------------------+----------------------------------------| |X7 |Video Blaster PAL | \-------------------------------------------------------------/
Running the Test Suites
The suites are run using P2STRING. For more information about P2STRING, see AP2/P2STRING Tool.
To run a device test, do the following:
1.Open an OS/2 window.
2.Run SETENV.CMD.
Note:Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
This file is in the IBM Developer Connection Device Driver Kit for OS/2. This command should be run prior to running the first test (each time you open an OS/2 window) because it sets up the audio devices correctly. To run this command, type:
SETENV
3.Run RESETINI.CMD prior to each test.
Note:Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
This file is in the IBM Developer Connection Device Driver Kit for OS/2. This command resets system connections in the appropriate INI files for audio and video tests to their defaults. To run this command, type:
RESETINI
4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:
P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]
For more information about running tests from the command line, see Starting P2STRING.
The tests display messages in a message box and might not automatically close the message box when the test finishes. If the test does not close the message box, you need to manually close it. The message box is not closed if P2STRING is waiting for a return value that might or might not be returned. The test has finished processing if the string "Script completed successfully" is displayed at the bottom of the message box. Allow approximately one minute after this message is displayed before manually closing the message box to allow for any late return codes.
Note:The "Script completed successfully" message does not indicate that all the tests passed. It only indicated the script has finished processing .
Analyzing a Device Driver Test
After an audio or video test is run, the results of the test are stored in a file with a .IND extension appended to the file name. The media control interface strings that passed are flagged with a PASSED keyword in the return string, and failed strings are flagged with a FAILED keyword.
Those that are flagged as FAILED can be analyzed further. When all strings are passed successfully, the device driver is handling all conditions specified by the test correctly.
Note:If a string command is supposed to fail and does, the return string is considered PASSED, because the return string matches the expected results.
The following example illustrates how to compare the results file with the test script.
TEST SCRIPT (AUDIO1.P80)
############################################
# #
# OPEN THE MIDIPLAYER #
# WAIT FOR SUCCESSFUL OPEN #
# #
############################################
#
/---> open sequencer alias midiplayer notify
|/--> +MM_MCINOTIFY MCI_NOTIFY_SUCCESSFUL MCI_OPEN #1
|| @WAIT_NOTIFY 1 45000
|| @WAIT_PASSDEVICE midiplayer
|| ############################################
|| # #
|| # LOAD AND CUE TYPE1. MID FILE #
|| # PLAY jesu.mid FILE AND EXPECT AN #
|| # ABORT FROM A PAUSE #
|| # #
|| ############################################
|| #
|| /-> load midiplayer ?MMDATA-AUD?\jesu.mid wait
|| | cue midiplayer output wait
|| | play midiplayer from 100 to 60000 notify
|| | +MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY
|| | #
|| |
|| |
|| | TEST OUTPUT FILE (AUDIO1.LOG)
|| |
|| |
|| | ****************Opening script file
|| |
|| |
|| | Thread 1 executing 21 commands.
\|--|--------> T:1 send string # 1 open sequencer alias midiplayer notify
\--|--------> EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
| |--> T:1 Notify received for # 1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
| \--> NOTIFY STATUS FOR #1: PASSED
| T:1 Notify received MM_MCIPASSDEVICE MCI_GAINING_USE Device ID 1
| returned string for # 1: 1
| T:1 @WAIT_NOTIFY 1 45000
| T:1 @WAIT_PASSDEVICE MIDIPLAYER
\--------> T:1 send string # 2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid wait
|--> no returned string for # 2.
\--> NOTIFY STATUS FOR #2: FAILED
.
.
.
END OF SCRIPT FILE REACHED. 14 COMMANDS SENT
Waiting for late notifications for 30 sec
T:1 Notify received for # 14 MM_MCINOTIFY SUCCESSFUL by command MCI_CLOSE ID 1
NOTIFY STATUS FOR #14: PASSED
Script completed successfully
The first command "open sequencer alias midiplayer notify" in the test expects the following results:
+MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY
Following the first and second line down in the previous example, you can see that this command passed successfully:
EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1 T:1 Notify received for # 1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1 NOTIFY STATUS FOR #1: PASSED
The following lines in the test script are not expecting returned information:
@WAIT_NOTIFY 1 45000 @WAIT_PASSDEVICE midiplayer
Therefore, the test output echoes these commands to show they were received .
T:1 @WAIT_NOTIFY 1 45000 T:1 @WAIT_PASSDEVICE MIDIPLAYER
However, the "load midiplayer ?MMDATA-AUD?\jesu.mid wait" command did not receive the expected message, and the following is logged to the test file:
T:1 send string # 2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid wait no returned string for # 2. NOTIFY STATUS FOR #2: FAILED
The bottom of the test output file indicates how many commands were processed, it also indicates if it is waiting for late notifications. Depending on the test, and the devices being tested, expected notifications might not always arrive on time or in the order expected. If a notification does not arrive when expected, it can arrive later if the device driver has not failed.
This is especially important on multi-threaded or multi-process processing. The more complicated the test (for example stress testing the device driver with multiple devices), the more difficult it is to decipher the output file. You will have to keep track of each thread or process separately to determine the results of the test.
Ultimotion Data Stream Specification
Advances in microprocessor power, data storage, and compression technology have provided key technologies for creating and playing digital video data on personal computers. The high capacity disk drives and CD-ROMs satisfy the large storage needs of digital video data. Additionally, today's more powerful microprocessors provide sufficient power to handle digital video data in real time. When these advances are combined with image compression techniques, the result is a powerful integration of video and the personal computer.
Several compression algorithms are currently in use throughout the industry . Some of these algorithms are numerically intensive and use additional video hardware to compress and decompress the digitized video. Others are less numerically intensive and can be handled by software running on the main CPU and still maintain sufficient frame rates to provide motion. These are referred to as software-onlyalgorithms. While software-only techniques are attractive due to their low cost, the video quality of these algorithms is typically lower than the hardware-based algorithms. Consequently, producers of digital video data struggle with trading off lower quality and cost of software-only techniques for the higher quality and cost of hardware-assisted video. Ultimotion* provides a motion video compression technique capable of producing a high level of quality in a software-only playback environment.
Overview of Ultimotion Video Compression
Decompression (playback) of Ultimotion video is possible with very low computational complexity to enable real-time playback in a software-only environment. The "nominal Ultimotion movie" is defined as 320 x 240, 15 frames per second at a 150KB per second data rate. This movie can be played on at least a 25 MHz 80386 microprocessor. Systems with faster microprocessors are capable of higher frame rates and larger output image sizes.
Compression (recording) of Ultimotion video can be performed with a range of computational complexity. In a software-only environment using frame- grabber hardware, Ultimotion video can be compressed either in real-time or asymmetrically in conjunction with frame-step recording.
Ultimotion real-time compression provides instant video turn-around at a very low cost. The most common quality type can be used to produce 160 x 120 videos at 15 frames per second with a 25 MHz 80486 microprocessor. A larger frame size can be used to produce 320 x 240 videos at 8 frames per second. The quality level is selectable to attain different data rates. Slower systems may also be used for real time capture or record, but the frame rates will be lower.
Asymmetric compression provides the most compression and quality, but must be used in conjunction with frame-step capture, or raw input source files. With a 25 MHz 80486 microprocessor, 320 x 240 frames can be compressed in one to four seconds. Specialized capture or compression hardware will enable real-time capture with the same quality level now attained through asymmetric compression.
Scalability
Ultimotion is a playback-time scalable video data stream. While the frame rate and output image size (resolution) are set when the video is created, the characteristics of a playback scalable video are modified during playback according to the capabilities of the playback platform. These playback-platform capabilities depend on the type of microprocessor, data bandwidth, display driver, and video adapter available during playback. Based on the characteristics of these components, the output quality of a single Ultimotion video stream can be "scaled" to the playback platform.
Processor Independence
In deriving the Ultimotion data stream, care was taken to balance the requirements of software-only and hardware-assisted decompression. The resulting data stream:
�Uses byte-oriented data organization and simple integer arithmetic (that is, no multiplication or division) so that non-computationally intensive decompression algorithms can be used.
�Organizes the data for efficient processing of unwanted data when being scaled during playback.
Data structures are organized for hardware-assisted techniques wherever feasible but do not utilize any particular processor instruction capability .
Playback Characteristics
While Ultimotion is a runtime scalable data stream, the magnitude that the data stream will "scale" is determined by the amount of information that is encoded in the data stream when it was created. That is, the amount of data placed in the stream at creation time determines the "maximum" playback characteristics that a particular stream can achieve. In turn, the processing capabilities of the playback system determine how much of the data can be processed and presented during playback. Therefore, the playback characteristics of a given video are a function of the data put into the video by the author andthe processing capabilities of the playback system.
The factors affecting the data stream at creation time are:
�Resolution - width and height of video
�Frame duration - frequency at which frames are to be displayed
�I-frame rate - frequency at which reference frames are to occur
�Data rate - average amount of data allowed for an interval of video
Factors affecting the playback of a video are:
�Processing power of the CPU
�Throughput of data storage (for example, CD-ROM, hard disk, and LAN)
�Efficiency of the display subsystem
Resolution Scalability
Resolution of a video determines how much spatial information is in a video image, as well as the "normal" playback size. Ultimotion video compression enables the output image size to be efficiently scaled up or down as it is decompressed, based on user preference or application requirements. Scaling down the output image size enables more efficient playback on slower systems.
Frame Rate Scalability
Frame duration for the frames in a video is usually referred to as frame rate. A frame compressed without regard to a prior frame uses intraframe compression and is called an I-frame. A frame compressed by considering only what has changed from a prior frame uses temporal compression and is called a delta frame. I-frames are a snapshot in time of the video. Delta frames show only what changed. The I-frame rate of a video is the frequency that I-frames occur in the data stream.
The I-frame rate affects several characteristics of a video stream:
�Data rate
�Quality of motion during scanning
�Performance of seek operations
�Ability to maintain smooth motion when frames are dropped to maintain audio synchronization
�Image re-paint time in a windowing system where no backup saving is used during clipping
Since I-frames contain the compressed data of the entire image, they are typically larger than delta frames. Ultimotion data streams that mix I- frames and delta frames:
�Reduce throughput requirements with smaller delta frames
�Provide points in the stream at which the entire image exists (good for seeking and scanning)
�Provide points in the video stream at which artifacts are repaired (with I -frames)
Generally, an I-frame rate of one I-frame every one or two seconds provides the best results.
Color Scalability
Ultimotion compression algorithms store images in a YUV direct color space. This color space is mapped at playback time to the number of colors available on the playback system. This avoids the need to have different versions of video content to fully exploit varying hardware capabilities.
Playback Platform Considerations
Direct Output
When decompressed, the Ultimotion data stream can produce either partial or complete video frames. The technique chosen to display these frames varies from platform to platform and largely depends on the display subsystem of the platform. Some systems allow a decompressor to access the display buffer directly where the decompressor may only update changed information. Others require changed information in full frames. The resulting performance characteristics of playback on various platforms is dependent on the efficiency of the display subsystem.
Window Clipping
In support of direct output in a windowing environment, Ultimotion decompression is well-suited for enabling clipping in the decompressor.
How Ultimotion Video Compression Works
The data stream combines several techniques to provide both temporal and spatial compression. These techniques include the following, which will be discussed in more detail in this section:
�Variable chrominance subsampling
�Luminance transition coding
�Statistical luminance image coding
Interframe versus Intraframe Compression
While the data stream supports both interframe and intraframe compression, no specific distinction is made between frame types. An intraframe compressed frame is one that does not contain any unchanged data. This does not preclude the file format from making such a distinction, as in the Audio/Video Interleaved (AVI) file format. Capture or compression software generally enables periodic insertion of intraframe compressed video frames.
Format of Encoded Video Frame Data
During video compression, each video frame is decomposed into non- overlapping square blocks, nominally of 8 x 8 pixels. Blocks in turn are decomposed into quadrants, nominally of 4 x 4 pixels. The quadrants in a block are considered to be ordered in a counter-clockwise direction, beginning with the upper-left quadrant. [Artwork not shown]
Blocks
The format of the encoded video frame data is the sequence of all blocks in the frame, each encoded as shown in the following figure, and ordered in a raster scan of the grid of blocks in the video frame. The data for a block begins with a one-byte block headerthat defines the interpretation of the data that follows for the block and the quadrants contained in the block.
While the block size is variable on output, the preferred output block size is 8 x 8 pixels, which results in a direct mapping of some encoding types ( statistical).
The following figure shows the format for each encoded block used to represent the decomposed frame.
/---------------------------------------\
|XXXXXXXX| Encoded Block |
\---------------------------------------/
OR
/---------------------------------------\
|XXXXXXXX|Quad 1 Quad 2 Quad 3 Quad 4|
\---------------------------------------/
Header Four Encoded Quadrants
Color Space
The data stream uses a direct color space; that is, no in-stream palettes or lookup tables are used. The color space used provides 6 bits of luminance and 8 bits of chrominance (6Y 4U 4V). The encoding of chrominance is performed by quantizing a portion of the dynamic range of the U and V components. The RGB conversion is performed using the following equations, which assume an RGB 5-6-5 representation:
Y = ((0.299R + 0.2935G + 0.114B) x 2.037) + 0.5
U = (((-0.169R - 0.163G + 0.500B) x 8.226)/6.375) + 5
V = (((0.500R - 0.206G - 0.081B) x 8.226)/7.500) + 6
The value of Y is restricted to 0 through 63 and the values of U and V are restricted to 0 through 15.
Variable Chrominance Subsampling
The chrominance value for each quadrant is determined by taking a weighted average of the chrominance values of the pixels in the quadrant. The chrominance values for each quadrant in the block are then compared with the chrominance values for other quadrants in the block, and if the values are within a threshold tof each other, the chrominance of the entire block is considered to be perceptually similar, and a single chrominance value is used for the entire block. This results in this block of the image being sampled at a low frequency. If, on the other hand, the chrominance values for the quadrants in the block differ by more than t, the block is considered to contain perceptually dissimilar colors, and a unique chrominance value is used for each quadrant in the block. This results in this block of the image being sampled at a high frequency.
Chrominance Modes
The data stream uses a variable chrominance subsampling mechanism. Chrominance data appears in the data stream with a varying frequency depending on the chrominance mode:
�Normal chrominance mode
This is the default mode. A single chrominance value (one byte) immediately follows the block header (except in the case of a completely unchanged block) and that chrominance value is used for the entire block.
�Unique chrominance mode
This mode is entered whenever chrominance subsampling fails; that is, using a single chrominance value for an entire block results in "chrominance bleeding" artifacts. In this mode, the block header is not followed by a chrominance value. Instead, each quadrant encoding includes a unique chrominance value.
�Single unique chrominance
Single unique chrominance is signaled by an escape value and indicates that a unique chrominance mode is used for the next block only. See Escape Values.
Luminance Transition Coding
Luminance transition coding (LTC) is based on the reduction of variation in luminance of a region of an image to a single direction. Each region of the image is analyzed to correlate individual luminance values and determine the direction in which the maximum luminance change is occurring. Sample values are then determined by taking the average number of pixels perpendicular to this direction. The luminance values within the region can then be mapped to one of a predetermined set of luminance values based on various functions of increasing luminance. These functions approximate commonly occurring luminance variations in natural images.
The resultant encoding of the region is then compared with the uncompressed image data for the region. The error (in luminance space) is calculated for use in comparing with other encoding types. The selection of an encoding type is based on the following two considerations: (1) comparison of the errors of the different types (where the error as defined above is inversely correlated to the quality of the representation) and (2) the amount of data each type consumes as allowed by the amount of compression to be obtained.
One-Byte Luminance Transition Region Encoding
The data for a one-byte encoding consists of a single luminance value and 2 bits that indicate a direction of increasing luminance of one step, if any. The one-byte encoding is useful because regions that have the same luminance value (known as homogeneous regions), or only a very small change in luminance, are common and should be encoded with as little data as possible.
Two-Byte Luminance Transition Region Encoding
The data for a two-byte encoding consists of the direction of increasingluminance and a transition index value that specifies a base Y value, a delta Y value, and a transition function. The transition index is the index into a table which defines the common set of four byte-transitions. The derivation of this index value is described later.
Four-Byte Luminance Transition Region Encoding
The data for a four-byte encoding consists of a direction of luminance change and four luminance sample values along the specified direction. The four-byte encoding is useful for regions in which the changes in luminance cannot be accurately mapped to the set of predetermined luminance values used in the two-byte encoding. Note that the specified direction (angle) does not include the opposite directions (ñ 180 degrees) because the luminance values need not be increasing (a requirement of the transition index). Thus the opposite directions are implied by the use of the four luminance values.
Format of Block Header
The encoding for a block begins with a block headerspecifying how the four quadrants it represents have been encoded. In addition to specifying these encoding types, certain values of the block header are reserved as escape values that contain control information about the interpretation of the data stream. The possibilities for processing a block as specified by the block header fall into two basic categories:
�Quadrant encodings
Quadrant encodings specify that the block is comprised of four quadrants, NW, SW, SE, and NE. Each quadrant in turn is separately encoded with a quadrant encoding type. Quadrants in a block are encoded independently, and may use different quadrant encoding types, with some restrictions which are described later.
�Block header escape
Rather than indicate the encoding type for a block and its respective quadrants, certain values are reserved as escape values to enable special processing of the data stream.
A block encoding is encoded using a one-byte block header followed by an encoding type. The following figure shows the format for a block encoding.
/---------------------------------------\ |XXXXXXXX| BLOCK ENCODING DATA | \---------------------------------------/ Header Encoded Quadrants
A quadrant encoding block uses the two left-most bits of the block header to specify how the first quadrant in the stream was encoded. Similarly, the next two left-most bits of the block header specify how the next quadrant was encoded, and so on. The following figure shows the format for a quadrant block.
/----------------------------------------------\ |Q1Q2Q3Q4|COLOR QUAD 1 QUAD 2 QUAD 3 QUAD 4| \----------------------------------------------/ Header Four Quadrant Encodings
The specification of the block header bits depends on the current stream interpretation mode. This mode determines which set of four encoding types is used when a block is decomposed into quadrants. The stream interpretation mode can be switched anywhere within a frame. The stream interpretation mode defaults to mode 0 at the start of each frame.
The following combination of quadrant types are defined for mode 0 stream interpretation:
�00: Unchanged quadrant
�01: Homogeneous/shallow LTC quadrant
�10: LTC quadrant
�11: Statistical/extended LTC quadrant
The following combination of quadrant types are defined for mode 1 stream interpretation:
�00: Unchanged quadrant
�01: Homogenous quadrant
�10: Subsampled 4-luminance quadrant
�11: 16-luminance quadrant
Quadrant Encoding Types
Encoding types used when a block is comprised into quadrants are described here. All the quadrants of a block share a single 8-bit chrominance value unless unique chrominance mode is being used, in which case each of the quadrant encodings in a block are preceded by a unique chrominance value.
Unchanged Quadrant
The data for the quadrant is unchanged from the previous frame and no further data is encoded. Note that a block with four unchanged quadrants is the same as an unchanged block which contains no chrominance value. The following figure shows how the encoded data is organized for a block containing one changed quadrant and three unchanged quadrants.
/-------------------------------\ |00 00 01 00|CHROMINANCE|QUAD 3 |... \-------------------------------/ Block Header One Encoded Quadrant
Decoding Tips
To decode an unchanged quadrant:
1.Move pointers in the output data to the next quadrant of the block.
2.Continue processing the next two bits of the block header.
Compression attained with this quadrant encoding is 0.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant. A completely unchanged block (4 unchanged quadrants) will attain a compression level of 0.125 bits per pixel, as no chrominance information is encoded for the block.
Luminance Transition Coding Quadrant
The data for the quadrant is described as an angle of direction of increasing luminance and an index indicating the luminance sample values along that direction. The delta Y values are distributed to provide lower quantization in shallow gradients. The following figure shows how the encoded data is organized for an LTC quadrant.
/----------------------------------------------------\
|xx 10 xx xx|CHROMINANCE| QUAD 1 | AAAA YDIST index |
\----------------------------------------------------/
Block Header Shared Luminance transition
Chrominance
The quadrant is encoded as follows:
�Four bits representing angle of direction of increasing luminance (0 indicates increasing luminance left to right - 0 degrees - with subsequent angles increasing in a counter-clockwise direction at increments of 22.5 degrees).
4 bits Angle of Direction
0000 0 degrees
0001 22.5 degrees
0010 45 degrees
. . .
1111 337.5 (-22.5) degrees
�12 bits luminance transition index
Decoding Tips
To decode this quadrant:
1.Determine the luminance values to use for the quadrant by performing a table lookup.
2.Interpret the direction bits and reverse luminance values if angle value is greater than 7.
3.Using the shared chrominance for the block plus the 6 bits of the first luminance, convert the resulting color to the target color space.
4.Using the direction bits as a vector, store the color in the appropriate positions of the quadrant. This can be done with eight output routines that map the luminance values into patterns for the first eight angles. The remaining eight angles are the opposite directions from the first eight, and are covered by reversing the luminance values.
5.Convert the remaining Y values and store in appropriate positions in the quadrant.
Compression attained with this quadrant encoding is 1.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.
Statistical Pattern/Extended LTC Quadrant
The first bit of the encoding determines whether the data is a statistical pattern or an extended LTC encoding. If the first bit is 0, the data for the quadrant is described as two luminance values Y1 and Y2, and a pattern specifying the distribution of the two luminance values among the pixels in the quadrant. The following figure shows how the encoded data is organized for a statistical quadrant.
/--------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 | Pattern | 00 Y1 00 Y2 |
\--------------------------------------------------------/
Block Header Shared Pattern Luminance Values
Chrominance
The quadrant is encoded as follows:
�16 bits of pattern in raster scan order (MSB = 0)
�2 bits undefined (decoder must mask)
�6 bits Y1
�2 bits undefined (decoder must mask)
�6 bits Y2
Decoding Tips
To decode this quadrant:
1.Convert the two luminance values to the output color space using the chrominance for the block or the quadrant, as defined by the current chrominance mode.
2.Output the two colors into pixels in the quadrant as defined by the pattern. The color obtained by converting Y1 is output wherever the corresponding pattern bit is 0, and the color obtained by converting Y2 is output wherever the corresponding pattern bit is 1.
The following figure shows how the encoded data is organized for an Extended LTC quadrant.
/------------------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 |1| AAA | Y1 | Y2 | 00 Y3 | 00 Y4 |
\------------------------------------------------------------------/
Block Header Shared Angle Luminance Values
Chrominance
The quadrant is encoded as follows:
�1 bit = 1
�3 bits angle 0-157.5 degrees ( 000 = 0 degrees, 22.5 degree increments)
�6 bits Y1
�6 bits Y2
�2 bits undefined (decoder must mask)
�6 bits Y3
�2 bits undefined (decoder must mask)
�6 bits Y4
Decoding Tips
To decode this quadrant:
1.Shift the luminance values into the same positions that are obtained by the luminance transition index lookup.
2.Enter the appropriate output routine in the LTC quadrant processing based on the angle specified. (Note that only eight angles are encoded. Because individual Y values are uniquely specified, each angle + 180 degrees is implied by reversing the ordering.)
Format of Homogeneous Quadrant/Shallow Gradient Quadrant
An encoded homogeneous/shallow gradient quadrantis specified by its corresponding two bits in the block header and a luminance value. The following figure shows how the encoded data is organized for a decomposed block whose second quadrant is a homogenous/shallow gradient.
/--------------------------------------------\
|xx 01 xx xx|CHROMINANCE| QUAD 1 | ssLL LLLL |
\--------------------------------------------/
Block Header Shared Luminance
Chrominance
The quadrant is encoded as follows:
�2 bits representing Y delta and angle of direction of increasing luminance (00 indicates constant luminance, and values 01, 10, and 11 specify luminance increasing one level across the quadrant in the specified direction).
2 bits Y delta, Angle of Direction
00 0, N/A
01 1, 45 degrees
10 1, 135 degrees
11 1, 270 degrees
�Six bits Y
Decoding Tips
To decode this quadrant:
1.Using the shared chrominance value for the block, use the luminance value Y and convert the YUV color to the target color space.
2.If angle/delta is 0, store the target color in the entire quadrant.
3.If angle/delta is not 0, perform a second color space conversion using Y +1 as the luminance value, and output the two colors with an error diffused density pattern in the direction specified.
4.Increment output pointers to the next quadrant in the block.
5.Move to the next quadrant in the encoded stream.
Compression attained with this quadrant encoding is 2.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.
Subsampled 4-Luminance Quadrant
An encoded subsampled 4-luminance quadrantis specified by its corresponding two bits in the block header and four luminance values. When decoded to an 8 x 8 block size, this quadrant encoding type results in one color value per 2 x 2 pixel region in the quadrant. The following figure shows how the encoded data is organized for a block whose second quadrant is a Subsampled 4-luminance quadrant.
/--------------------------------------------------------------------\
|xx 10 xx xx|CHROMINANCE| QUAD 1 | 1111 1122 | 2222 3333 | 3344 4444 |
\--------------------------------------------------------------------/
Block Header Shared Four Luminance Values
Chrominance
The quadrant is encoded as follows:
�6 bits Y1
�6 bits Y2
�6 bits Y3
�6 bits Y4
Decoding Tips
To decode this quadrant:
1.Using the shared chrominance value in this quadrant and the first luminance value (Y1), convert the YUV color to the target color space.
2.Store the output color in the corresponding 2 x 2 area of the quadrant.
3.Move output pointers to the next 2 x 2 of the quadrant in the order NW, NE, SW, SE.
4.Repeat the last 3 steps for each luminance in the encoded stream.
Compression attained with this quadrant encoding is 1.75 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.
16-Luminance Quadrant
An encoded 16-luminance quadrantis specified by its corresponding two bits in the block header and 16 luminance values. When decoded with an 8 x 8 block size, this quadrant encoding contains one color value per pixel in the quadrant. The following figure shows how the encoded data is organized for a block whose second quadrant is a 16-luminance quadrant.
/--------------------------------------------------------------------\
|xx 11 xx xx|CHROMINANCE| QUAD 1 | 1111 1122 | 2222 3333 | 3344 4444 | ....
\--------------------------------------------------------------------/
Block Header Shared 16 Luminance Values
Chrominance
The quadrant is encoded as follows:
�6 bits Y1
�6 bits Y2
�6 bits Y3
�6 bits Y4
.
.
.
�6 bits Y16
Decoding Tips
To decode this quadrant:
1.Using the shared chrominance value in this quadrant and the first luminance value (Y1), convert the YUV color to the target color space.
2.Store the output color in the corresponding pixel of the quadrant.
3.Repeat the last two steps for each pixel in the quadrant.
Compression attained with this quadrant encoding is 6.25 bits per pixel, assuming normal chrominance mode, including 2 bits chrominance and 2 bits for the block header, representing a 1/4 share of each for a quadrant.
Escape Values
Block headers with a value of 01110xxx are used as escape values, used to specify both block encoding types and data stream interpretation escape values. The following data stream interpretation escape values are defined :
�Normal/unique chrominance mode toggle
This escape toggles the chrominance mode between normal and unique.
�Single unique chrominance mode
This escape causes the following block to be interpreted in unique chrominance mode. The current chrominance mode is unchanged.
�Frame guard byte
For efficiency, decoder implementations may choose not to bounds check addressing into the source data buffer. If the source buffer contains invalid data, an access violation might occur. Additionally, invalid data might be decoded as valid data without any means of software detection. Both of these problems are addressed with the "guard byte" value.
At least one guard byte always appears at the end of a coded frame, and is encoded in the stream. If the byte immediately following the last block encoding for a frame is not equal to this value, it is considered to be an error. As it is highly improbable that a buffer containing invalid data will be decoded and the above condition still met, decoding of invalid source data can be detected in this way.
If a guard byte value is encountered as an escape before the end of the frame, it is also considered to be an error. It is possible to stop a decoder from over-reading with invalid data by appending 64 bytes (the size of the largest block encoding) equal to 73H (the frame guard byte value) to the end of the buffer. A decoder interpreting a stream will then encounter a guard byte before the end of the buffer is overrun.
�Unchanged block run
This escape indicates a number of blocks are completely unchanged. The byte following the escape indicates the total number of blocks to skip. While it is perfectly valid to have consecutive unchanged blocks encoded with block header values of zero, it should be noted that for compression, three or more consecutive unchanged blocks should be encoded as an unchanged block run. Also, since two consecutive unchanged blocks may be encoded as an unchanged block run in the same space as zero block header values, an encoder can establish an unchanged run in the output data stream whenever two consecutive unchanged blocks are encountered.
�General stream control escape
This escape provides a generalized escape mechanism for more escapes than permitted by the 3-bit direct escape in the byte header. This escape is followed by a 1-byte control value. The following generalized escapes are defined:
-Enable stream interpretation mode 0
-Enable stream interpretation mode 1
Note that since block header values 01110xxx are reserved as escape values, quadrant encoding combinations that would produce a block header value with any of these eight values are not allowed and must be altered to other encodings by the compressor.
Predetermined Luminance Transitions
A static set of luminance transitions across a region are defined. Seven types of predetermined transitions are defined for increasing luminance:
1.Linear
The luminance level increases at a constant rate across the region.
2.Low-contrast edge at 1/4 block width from low-luminance edge
The luminance level changes at an edge that is perpendicular to the direction of increasing luminance at a point where the area of the region following the edge is three times the area of that preceding the edge. The change in luminance is not instantaneous, analogous to a blurry transition.
3.Low-contrast edge at 1/2 block width from low-luminance edge
Same as above, but with the change occurring at the point where the areas of the region on either side of the edge are equal.
4.Low-contrast edge at 3/4 block width from low-luminance edge
Same as above, but with the change occurring at the point where the area of the region preceding the edge is three times the area of that following the edge.
5.High-contrast edge at 1/4 block width from low-luminance edge
The luminance level changes at an edge that is perpendicular to the direction of increasing luminance at a point where the area of the region following the edge is three times the area of that preceding the edge. The change in luminance is instantaneous, analogous to a sharp, well defined edge.
6.High-contrast edge at 1/2 block width from low-luminance edge
Same as above, but with the change occurring at the point where the areas of the region on either side of the edge are equal.
7.High-contrast edge at 3/4 block width from low-luminance edge
Same as above, but with the change occurring at the point where the area of the region preceding the edge is three times the area of that following the edge.
The pre-determined luminance transitions are comprised of a subset of the total possible luminance changes in the range 0 through 63 for each of the transition types as follows:
�Linear
Total Y delta = 2 3 4 5 6 7 8 11 14 17 20
�Low-contrast Edge
Total Y delta = 4 5 6 7 8 11 14 17 20 23 26 29 32 36
�High-contrast Edge
Total Y delta = 6 8 11 14 17 20 23 26 29 32 35 40 46
These selections of allowable Y delta values in two-byte Luminance Transition region encodings accomplish several objectives:
�When combined with the seven transition types at all 64 initial luminance levels, the total number of valid transitions (those in which the Y delta value added to the initial luminance level does not exceed the maximum luminance level of 63) is 4096, which can be encoded in 12 bits in the two- byte encoding.
�Regions with small changes in luminance (for example, <= 8) can be encoded with single luminance level precision. Regions with small changes in luminance are more common than regions with extreme changes.
�Regions with larger changes in luminance (8 < x < 32) can be represented with an edge-to-edge error not exceeding one luminance level.
�Extreme changes in luminance (32 < x < 50) can be represented in two-byte encodings if required by data rate constraints, although with some potential loss in quality as the extreme Y delta values are more highly quantized.
The following additional characteristics are exploited in the selection of allowable Y delta values for each transition type:
�Transitions with Y delta values less than two are encoded with the one- byte encoding (resulting in a quantized direction).
�Edge transitions with Y delta values less than 4 are deemed perceptually similar to a linear transition.
�Edge transitions with Y delta values less than 6 are deemed perceptually similar with regard to edge type, that is, low or high contrast.
�Transitions with Y delta values greater than 20 tend to be non-linear, that is, usually include an edge, and are coded only as such
�Luminance changes greater than 50 are extremely rare and can be quantized with little perceptible quality loss.
The luminance transition index is produced by enumerating all valid transitions that are combinations of initial Y values of 0 through 63 and transition types with Y delta values as listed above. The following code fragment illustrates how these combinations are enumerated:
for (Y1 = 0, Y1 <= 63, Y1++) {
for (Y2 = Y1, Y2 <= 63, Y2++) {
Ydelta = Y2 - Y1;
if (Ydelta == <valid linear transition Y delta value>)
<enumerate linear transition>;
if (Ydelta == <valid low-contrast edge transition Y delta value>)
{
<enumerate low-contrast edge at 1/4 transition>;
<enumerate low-contrast edge at 1/2 transition>;
<enumerate low-contrast edge at 3/4 transition>;
}
if (Ydelta == <valid high-contrast edge transition Y delta value>)
{
<enumerate high-contrast edge at 1/4 transition>;
<enumerate high-contrast edge at 1/2 transition>;
<enumerate high-contrast edge at 3/4 transition>;
}
}
}
Data Stream Escape Value Constants
Escape values defined in the data stream are one-byte values, in the range 70H - 77H (01110xxx).
General Stream Control Escape - 70H
This escape is used to imbed control information in the stream. It is followed by a single byte value containing the control information.
Stream control byte values
�Set stream interpretation mode 0 - 00H
Stream interpretation mode 0 block header quadrant decomposition cases:
1.00: Unchanged quadrant
2.01: Homogenous/shallow LTC quadrant
3.10: Luminance transition coding (LTC) quadrant
4.11: Statistical/extended LTC quadrant
�Set stream interpretation mode 1 - 01H
Stream interpretation mode 1 block header quadrant decomposition cases:
1.00: Unchanged quadrant
2.01: Homogenous/shallow LTC quadrant
3.10: Subsampled 4-luminance quadrant
4.11: 16-luminance quadrant
Single Unique Chrominance Block Escape - 71H
This escape signals that the next block contains unique chrominance values. The chrominance mode (normal or unique) is unchanged. If the current chrominance mode is unique, this escape has no effect and is ignored.
Normal/Unique Chrominance Mode Toggle Escape - 72H
This escape causes normal chrominance mode to be entered if the current mode is unique chrominance mode, and causes unique chrominance mode to be entered if the current mode is normal chrominance mode.
Frame Guard Byte Value - 73H
This escape assists the decoder in determining if invalid data has been encountered in the input stream. See Escape Valuesfor a more detailed explanation.
Unchanged Block Run Escape - 74H
This escape value indicates some number of completely unchanged blocks. The number of unchanged blocks follows the escape in a single byte, and as such , is limited to 255.
Reserved Escape Values - 75H, 76H, 77H
These escape values are reserved.
DDCMD Messages
The device driver commands are an interface used by a stream handler to communicate with a physical device driver. This interface uses the inter- device driver communication (IDC) mechanism provided by OS/2 AttachDD DevHelp. The stream handler must attach to the device driver using AttachDD DevHelp to receive the DDCMD entry point address of the device driver. This must be done prior to issuing any DDCMDs. Some device drivers also might require that a DosOpen call be used to open the device driver before it can be used through the AttachDD entry point.
The DDCMDs are provided through a single entry point, DDCMDEntryPoint, which accepts a parameter structure on input.
typedef ULONG (FAR*PSHDFN) (PVOID pParmIn); typedef ULONG (FAR*PDDCMDFN) (PVOID pParmIn);
For the Ring 3 DLL interface, all pointers are 0:32 linear; for Ring 0 stream handlers all pointers are 16:16 far pointers to enable the 16-bit device driver model to be used. The following list contains the message numbers for all DDCMDs. It should be used in the ulFunctionfield, of the parameter structure passed on the call, to indicate which function is being requested by the stream handler.
/--------------------------------------------------------------\ |Message |Message |Description | |Number | | | |--------+--------------------------+--------------------------| |4L |DDCMD_CONTROL |Performs a device-specific| | | |command. | |--------+--------------------------+--------------------------| |6L |DDCMD_DEREG_STREAM |Removes a stream instance | | | |from a device driver. | |--------+--------------------------+--------------------------| |1L |DDCMD_READ |Performs a read from the | | | |device into a buffer. | |--------+--------------------------+--------------------------| |5L |DDCMD_REG_STREAM |Registers a stream | | | |instance with a device | | | |driver. | |--------+--------------------------+--------------------------| |0L |DDCMD_SETUP |Performs a device-specific| | | |stream instance setup. | |--------+--------------------------+--------------------------| |3L |DDCMD_STATUS |Requests status from the | | | |device. | |--------+--------------------------+--------------------------| |2L |DDCMD_WRITE |Performs a write from a | | | |buffer to the device. | \--------------------------------------------------------------/
DDCMDEntryPoint
Select an item:
Syntax Parameters Returns Remarks Glossary
This function enables device driver stream handlers to interface with the hardware physical device driver (PDD).
#include <os2me.h> PDDCMDCOMMON pCommon; /* Pointer to DDCMDCOMMON. */ ULONG rc; /* Return codes. */ rc = DDCMDEntryPoint(pCommon);
DDCMDEntryPoint - Syntax
This function enables device driver stream handlers to interface with the hardware physical device driver (PDD).
#include <os2me.h> PDDCMDCOMMON pCommon; /* Pointer to DDCMDCOMMON. */ ULONG rc; /* Return codes. */ rc = DDCMDEntryPoint(pCommon);
DDCMDEntryPoint Parameter - pCommon
pCommon(PDDCMDCOMMON) - input A pointer to a DDCMD message-specific input parameter block. See DDCMDCOMMON.
DDCMDEntryPoint Return Value - rc
rc(ULONG) - returns Return codes indicating success or the type of failure :
NO_ERROR Successful.
ERROR_INVALID_FUNCTION Invalid function requested.
FAILURE A DDCMD message-specific error return code.
DDCMDEntryPoint - Parameters
pCommon(PDDCMDCOMMON) - input A pointer to a DDCMD message-specific input parameter block. See DDCMDCOMMON.
rc(ULONG) - returns Return codes indicating success or the type of failure :
NO_ERROR Successful.
ERROR_INVALID_FUNCTION Invalid function requested.
FAILURE A DDCMD message-specific error return code.
DDCMDEntryPoint - Remarks
Device driver stream handlers communicate with the hardware PDD through the DDCmdEntryPoint. This is accomplished through the use of Device Driver Command (DDCMD) messages, which enable a stream handler to request a PDD to perform functions such as starting, stopping, or resuming operation of a device. This interface uses the IDC mechanism provided by the ATTACHDD DevHelp function. The stream handler must attach to the device driver to receive the DDCMD entry point address of the device driver. This function is performed prior to issuing device driver command messages.
DDCMDEntryPoint - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
DDCMD_CONTROL
Select an item:
Syntax Returns Remarks Example Code Glossary
This message performs a device-specific command.
pParmIn(PDDCMDCONTROL) A pointer to a DDCMDCONTROLdata structure. The pParmand ulParmSizefields refer to the CONTROL_PARMdata structure. Values for ulCmdinclude:
DDCMD_START Start a device.
DDCMD_STOP Stop a device and return current position.
DDCMD_PAUSE Pause a device and return current position.
DDCMD_RESUME Resume a paused device
DDCMD_ENABLE_EVENT Enable event detection.
DDCMD_DISABLE_EVENT Disable event detection in the device driver.
DDCMD_PAUSE_TIME Pause time but do not pause stream.
DDCMD_RESUME_TIME Resume time.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ulCmdof DDCMDCONTROLis set to DDCMD_ENABLE_EVENT.)
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_SEQUENCE Invalid device control command.
ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.
ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.
ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.
FAILURE Device-driver-specific error return code.
DDCMD_CONTROL Parameter - pParmIn
pParmIn(PDDCMDCONTROL) A pointer to a DDCMDCONTROLdata structure. The pParmand ulParmSizefields refer to the CONTROL_PARMdata structure. Values for ulCmdinclude:
DDCMD_START Start a device.
DDCMD_STOP Stop a device and return current position.
DDCMD_PAUSE Pause a device and return current position.
DDCMD_RESUME Resume a paused device
DDCMD_ENABLE_EVENT Enable event detection.
DDCMD_DISABLE_EVENT Disable event detection in the device driver.
DDCMD_PAUSE_TIME Pause time but do not pause stream.
DDCMD_RESUME_TIME Resume time.
DDCMD_CONTROL Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ulCmdof DDCMDCONTROLis set to DDCMD_ENABLE_EVENT.)
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_SEQUENCE Invalid device control command.
ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.
ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.
ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.
FAILURE Device-driver-specific error return code.
DDCMD_CONTROL - Syntax
This message performs a device-specific command.
pParmIn(PDDCMDCONTROL) A pointer to a DDCMDCONTROLdata structure. The pParmand ulParmSizefields refer to the CONTROL_PARMdata structure. Values for ulCmdinclude:
DDCMD_START Start a device.
DDCMD_STOP Stop a device and return current position.
DDCMD_PAUSE Pause a device and return current position.
DDCMD_RESUME Resume a paused device
DDCMD_ENABLE_EVENT Enable event detection.
DDCMD_DISABLE_EVENT Disable event detection in the device driver.
DDCMD_PAUSE_TIME Pause time but do not pause stream.
DDCMD_RESUME_TIME Resume time.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_REQUEST Device driver does not support events. (Returned when ulCmdof DDCMDCONTROLis set to DDCMD_ENABLE_EVENT.)
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_SEQUENCE Invalid device control command.
ERROR_INSUFF_BUFFER The device driver does not have buffers to perform the requested action.
ERROR_STREAM_NOT_STARTED The stream cannot perform the requested action unless the stream has been started.
ERROR_TOO_MANY_EVENTS The stream handler attempted to enable too many events.
FAILURE Device-driver-specific error return code.
DDCMD_CONTROL - Remarks
The stream handler uses this command to control the actions of the physical device driver.
DDCMD_CONTROL - Example Code
The following code illustrates the stream handler requesting the PDD to stop its current task, for example, the PDD stops playing audio.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDCONTROL ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry
point */
.
.
.
/*-------------------------------------------------------------------*/
/* The stream handler directs the physical device driver to stop. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_CONTROL;
ddcmdpb.hstream = hstream;
ddcmdpb.pParm = NULL;
ddcmdpb.ulParmSize = NULL;
ddcmdpb.ulCmd = DDCMD_STOP;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error! */
DDCMD_CONTROL - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_DEREG_STREAM
Select an item:
Syntax Returns Remarks Example Code Glossary
This message removes a stream instance from a device driver. The stream handler directs the device driver to deregister the stream-destroy the stream and all associated data.
pParmIn(PDDCMDDEREGISTER) A pointer to a DDCMDDEREGISTERdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error.
DDCMD_DEREG_STREAM Parameter - pParmIn
pParmIn(PDDCMDDEREGISTER) A pointer to a DDCMDDEREGISTERdata structure.
DDCMD_DEREG_STREAM Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error.
DDCMD_DEREG_STREAM - Syntax
This message removes a stream instance from a device driver. The stream handler directs the device driver to deregister the stream-destroy the stream and all associated data.
pParmIn(PDDCMDDEREGISTER) A pointer to a DDCMDDEREGISTERdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error.
DDCMD_DEREG_STREAM - Remarks
�This message removes the communication link between the physical device driver and the stream handler for a particular stream instance. The only input is the stream handle, which indicates to the device driver which stream to destroy.
�After a deregister, the VSD (or device driver) no longer has access to any buffers, and the buffers will be returned to SSM by the stream handler. The VSD does not have to return the buffers; they are returned for the it. The VSD should not return from the destroy until it has stopped using all buffers.
DDCMD_DEREG_STREAM - Example Code
The following code illustrates the stream handler requesting the stream to be de-registered.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDDEREGISTER ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry */
/* point */
.
.
.
/*-------------------------------------------------------------------*/
/* The stream handler deregisters with the physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_DEREG_STREAM;
ddcmdpb.hstream = hstream;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error! */
DDCMD_DEREG_STREAM - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_READ
Select an item:
Syntax Returns Remarks Example Code Glossary
This message performs a read from the device into a buffer.
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_READ Parameter - pParmIn
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
DDCMD_READ Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_READ - Syntax
This message performs a read from the device into a buffer.
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_READ - Remarks
This message is used by a stream handler to give an emptybuffer to the physical device driver. An example would be in an audio recording, where the physical device driver fills the buffer it gets from the stream handler . The pBufferparameter is a pointer to the buffer to be filled in by the physical device driver. This pointer is either a physical 0:32 pointer, 16: 16 far pointer or a global linear pointer. This is defined when the stream handler registers a stream with the device driver using DDCMD_REG_STREAM.
Many devices cannot handle a 0 length buffer. If the driver receives a 0 length buffer, it should not reject the buffer. The driver should do nothing with the buffer and return it in the same order in which it was sent.
DDCMD_READ - Example Code
The following code illustrates the PDD ready to receive an empty buffer from the stream handler.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDREADWRITE ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry point */
PVOID pBuffer; /* Pointer to buffer */
.
.
.
/*-------------------------------------------------------------------*/
/* Perform a read from the physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_READ;
ddcmdpb.hstream = hstream;
ddcmdpb.pBuffer = pBuffer;
ddcmdpb.ulBufferSize = 32768;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error!*/
DDCMD_READ - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_REG_STREAM
Select an item:
Syntax Returns Remarks Example Code Glossary
This message registers a stream instance with a device driver for the first time.
pParmIn(PDDCMDREGISTER) A pointer to a DDCMDREGISTERdata structure.
Values for ulStreamOperationinclude:
�STREAM_OPERATION_CONSUME
�STREAM_OPERATION_PRODUCE
Values for ulAddressTypeinclude:
�ADDRESS_TYPE_VIRTUAL
�ADDRESS_TYPE_PHYSICAL
�ADDRESS_TYPE_LINEAR
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.
ERROR_INVALID_SPCBKEY Invalid SPCBKEY.
ERROR_INITIALIZATION An error occurred during device initialization.
ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.
FAILURE Device-driver-specific error return code.
DDCMD_REG_STREAM Parameter - pParmIn
pParmIn(PDDCMDREGISTER) A pointer to a DDCMDREGISTERdata structure.
Values for ulStreamOperationinclude:
�STREAM_OPERATION_CONSUME
�STREAM_OPERATION_PRODUCE
Values for ulAddressTypeinclude:
�ADDRESS_TYPE_VIRTUAL
�ADDRESS_TYPE_PHYSICAL
�ADDRESS_TYPE_LINEAR
DDCMD_REG_STREAM Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.
ERROR_INVALID_SPCBKEY Invalid SPCBKEY.
ERROR_INITIALIZATION An error occurred during device initialization.
ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.
FAILURE Device-driver-specific error return code.
DDCMD_REG_STREAM - Syntax
This message registers a stream instance with a device driver for the first time.
pParmIn(PDDCMDREGISTER) A pointer to a DDCMDREGISTERdata structure.
Values for ulStreamOperationinclude:
�STREAM_OPERATION_CONSUME
�STREAM_OPERATION_PRODUCE
Values for ulAddressTypeinclude:
�ADDRESS_TYPE_VIRTUAL
�ADDRESS_TYPE_PHYSICAL
�ADDRESS_TYPE_LINEAR
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_HNDLR_REGISTERED Stream had already been registered with the Sync/ Stream Manager.
ERROR_INVALID_SPCBKEY Invalid SPCBKEY.
ERROR_INITIALIZATION An error occurred during device initialization.
ERROR_STREAM_CREATION An error occurred during the creation of this stream instance.
FAILURE Device-driver-specific error return code.
DDCMD_REG_STREAM - Remarks
A stream handler must register its entry point with the device driver once for each stream instance. This message sets up the communication link between the stream handler and the physical device driver.
DDCMD_REG_STREAM - Example Code
The following code illustrates how to register a stream instance with a device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDREGISTER ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry */
/* point */
ULONG ulSysFileNum; /* Global file handle */
PSHDFN pshdfn; /* Pointer to SHD entry */
/* point */
SPCBKEY spcbkey; /* Stream protocol key */
.
.
.
/*-------------------------------------------------------------------*/
/* Register a stream instance with a physical device driver. */
/*-------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_REGISTER;
ddcmdpb.hstream = hstream;
ddcmdpb.ulSysFileNum = ulSysFileNum;
ddcmdpb.pSHDEntryPoint = pshdfn;
ddcmdpb.ulStreamOperation = STREAM_OPERATION_CONSUME;
ddcmdpb.spcbkey = spcbkey;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error!*/
DDCMD_REG_STREAM - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_SETUP
Select an item:
Syntax Returns Remarks Example Code Glossary
This message performs device-specific stream instance setup.
pParmIn(PDDCMDSETUP) A pointer to a DDCMDSETUPdata structure. The pSetupParmand ulSetupParmSizefields refer to the SETUP_PARMdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_REQUEST Invalid setup request.
ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.
FAILURE Device-driver-specific error return code.
DDCMD_SETUP Parameter - pParmIn
pParmIn(PDDCMDSETUP) A pointer to a DDCMDSETUPdata structure. The pSetupParmand ulSetupParmSizefields refer to the SETUP_PARMdata structure.
DDCMD_SETUP Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_REQUEST Invalid setup request.
ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.
FAILURE Device-driver-specific error return code.
DDCMD_SETUP - Syntax
This message performs device-specific stream instance setup.
pParmIn(PDDCMDSETUP) A pointer to a DDCMDSETUPdata structure. The pSetupParmand ulSetupParmSizefields refer to the SETUP_PARMdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_REQUEST Invalid setup request.
ERROR_STREAM_NOT_STOP The stream cannot perform the requested function unless the stream has been stopped.
FAILURE Device-driver-specific error return code.
DDCMD_SETUP - Remarks
This message indicates to the physical device driver that a specific stream instance will become the active stream instance. The pSetupParmfield is used for device-specific information. Typically, it is used to pass the current stream time from the stream handler to the PDD because a seek might have been requested on the stream prior to the stream start; thus, the PDD should adjust its time to this new reference time. Time is passed as a pointer to the time in milliseconds.
DDCMD_SETUP - Example Code
The following code illustrates how to perform device-specific stream instance setup.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDSETUP ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry*/
/* point */
ULONG ulStreamTime /* Stream time */
PVOID pBuffer; /* Pointer to buffer */
.
.
.
/*------------------------------------------------------------------*/
/*Activate a stream instance in a physical device driver (Switch */
/* context) */
/*------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_SETUP;
ddcmdpb.hstream = hstream;
ddcmdpb.pSetupParm = &ulStreamTime; /* Setting stream time */
ddcmdpbp.ulSetupParmSize = sizeof(ulStreamTime);
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error!*/
DDCMD_SETUP - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_STATUS
Select an item:
Syntax Returns Remarks Example Code Glossary
This message requests status from the device.
pParmIn(PDDCMDSTATUS) A pointer to a DDCMDSTATUSdata structure. The pStatusand ulStatusSizefields refer to the STATUS_PARMdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error return code.
DDCMD_STATUS Parameter - pParmIn
pParmIn(PDDCMDSTATUS) A pointer to a DDCMDSTATUSdata structure. The pStatusand ulStatusSizefields refer to the STATUS_PARMdata structure.
DDCMD_STATUS Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error return code.
DDCMD_STATUS - Syntax
This message requests status from the device.
pParmIn(PDDCMDSTATUS) A pointer to a DDCMDSTATUSdata structure. The pStatusand ulStatusSizefields refer to the STATUS_PARMdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
FAILURE Device-driver-specific error return code.
DDCMD_STATUS - Remarks
This message queries the status of physical device driver. This message might not be supported by all physical device drivers. It is commonly used by the stream handler to request the current stream time from the physical device driver.
DDCMD_STATUS - Example Code
The following code illustrates how to request status from the device.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDSTATUS ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry */
/* point */
.
.
.
/*--------------------------------------------------------------------*/
/* Get the current stream time from the physical device driver. */
/*--------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_STATUS;
ddcmdpb.hstream = hstream;
ddcmdpb.pStatus =NULL; /* Return stream time*/
ddcmdpb.ulStatusSize = 0;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error!*/
DDCMD_STATUS - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
DDCMD_WRITE
Select an item:
Syntax Returns Remarks Example Code Glossary
This message performs a write from the buffer to the device.
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_WRITE Parameter - pParmIn
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
DDCMD_WRITE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_WRITE - Syntax
This message performs a write from the buffer to the device.
pParmIn(PDDCMDREADWRITE) A pointer to a DDCMDREADWRITEdata structure.
rc(ULONG) Error code indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_BLOCK Invalid address passed in parameter block.
FAILURE Device-driver-specific error return code.
DDCMD_WRITE - Remarks
This message is used by a stream handler to give a full buffer to the physical device driver. An example would be the case of audio playback, where the stream handler passes a buffer with data to the physical device driver.
The pBufferparameter is a pointer to the data buffer. Note that this pointer is either a physical 0:32 pointer, 16:16 far pointer, or a global linear pointer. The pointer type is defined when the stream registers a stream with the device driver (DDCMD_REG_STREAM).
Many devices cannot handle a 0 length buffer. If the driver receives a 0 length buffer, it should not reject the buffer. The driver should do nothing with the buffer and return it in the same order in which it was sent.
DDCMD_WRITE - Example Code
The following code illustrates how to perform a write to the physical device driver.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
DDCMDREADWRITE ddcmdpb; /* Parameter block */
PDDCMDFN pddcmdfn; /* Pointer to DDCMD entry */
/* point */
PVOID pBuffer; /* Pointer to buffer */
.
.
.
/*--------------------------------------------------------------------*/
/* Perform a write to the physical device driver. */
/*--------------------------------------------------------------------*/
ddcmdpb.ulFunction = DDCMD_WRITE;
ddcmdpb.hstream = hstream;
ddcmdpb.pBuffer = pBuffer;
ddcmdpb.ulBufferSize = 32768;
if (ulRC = pddcmdfn (&ddcmdpb))
return (ulRC); /* error! */
DDCMD_WRITE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
SHD Messages
The stream handler device (SHD) messages are provided by a stream handler through a single entry point, SHDEntryPoint, to a physical device driver. For this interface, all pointers are 16:16 pointers; this enables the current 16-bit device-driver model to be used for stream handlers. There are two SHD messages. The message number must be used in the ulFunctionfield, of the parameter structure passed in the call, to indicate which message is being requested by the stream handler.
The following table lists the SHD messages:
/-----------------------------------------------------------------\ |Message |Message |Description | |Number | | | |--------+--------------------+-----------------------------------| |1L |SHD_REPORT_EVENT |Reports an event to the stream | | | |handler. | |--------+--------------------+-----------------------------------| |0L |SHD_REPORT_INT |Reports an interrupt from a device.| \-----------------------------------------------------------------/
SHDEntryPoint
Select an item:
Syntax Parameters Returns Remarks Example Code Glossary
Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.
#include <os2me.h> PSHD_COMMON pCommon; /* Pointer to SHD_COMMON. */ ULONG rc; /* Return codes. */ rc = SHDEntryPoint(pCommon);
SHDEntryPoint - Syntax
Each stream handler must provide this entry point, which is used for the PDD to communicate back to the stream handler.
#include <os2me.h> PSHD_COMMON pCommon; /* Pointer to SHD_COMMON. */ ULONG rc; /* Return codes. */ rc = SHDEntryPoint(pCommon);
SHDEntryPoint Parameter - pCommon
pCommon(PSHD_COMMON) - input Pointer to SHD_COMMON.
SHDEntryPoint Return Value - rc
rc(ULONG) - returns Return codes indicating success or the type of failure :
NO_ERROR Successful.
ERROR_INVALID_FUNCTION Invalid function requested.
FAILURE An SHD message-specific error return code.
SHDEntryPoint - Parameters
pCommon(PSHD_COMMON) - input Pointer to SHD_COMMON.
rc(ULONG) - returns Return codes indicating success or the type of failure :
NO_ERROR Successful.
ERROR_INVALID_FUNCTION Invalid function requested.
FAILURE An SHD message-specific error return code.
SHDEntryPoint - Remarks
Device driver stream handlers receive commands from PDDs to report events and interrupts. These Stream Handler Device (SHD) helper commands are provided through the SHDEntryPoint. This entry point is specifically used for the PDD to call back to the stream handler. For example, the PDD can send an SHD_REPORT_INTcommand to the stream handler to report status, indicate that a buffer is full, or specify that an additional buffer is required.
SHDEntryPoint - Example Code
The following code illustrates how to access this entry point, which is used for the PDD to communicate back to the stream handler.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
HEVENT hevent; /* Event handle */
SHD_REPORTEVENT shdpb; /* Parameter block */
PSHDFN pshdfn; /* Pointer to SHD entry point */
ULONG ulStreamTime; /* Stream time */
.
.
.
/*----------------------------------------------------------------------*/
/* Report a cue point to the stream handler for a stream instance. */
/*----------------------------------------------------------------------*/
shdpb.ulFunction = SHD_REPORT_EVENT;
shdpb.hstream = hstream;
shdpb.hevent = hevent;
shdpb.ulStreamTime = ulStreamTime;
if (ulRC = pshdfn (&shdpb))
return (ulRC); /* error! */
SHDEntryPoint - Topics
Select an item:
Syntax Parameters Returns Remarks Example Code Glossary
SHD_REPORT_EVENT
Select an item:
Syntax Returns Remarks Example Code Glossary
This message reports an event to the stream handler.
pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata structure.
rc(ULONG) Return codes indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_EVENT Invalid event handle.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_EVENT Parameter - pParmIn
pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata structure.
SHD_REPORT_EVENT Return Value - rc
rc(ULONG) Return codes indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_EVENT Invalid event handle.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_EVENT - Syntax
This message reports an event to the stream handler.
pParmIn(PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENTdata structure.
rc(ULONG) Return codes indicating success or the type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_INVALID_EVENT Invalid event handle.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_EVENT - Remarks
This message is a mechanism for the physical device driver to report its own event (cue point) detection. The stream handler will call the PDD with an event via DDCMD_CONTROL(DDCMD_ENABLE_EVENT) and the PDD will monitor the stream time for this event (if the PDD supports event detection). When the event is detected, the PDD will call back the stream handler and report this event via this message. The handle to the event and stream time must be set.
SHD_REPORT_EVENT - Example Code
The following code illustrates how to report an event to the stream handler .
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
HEVENT hevent; /* Event handle */
SHD_REPORTEVENT shdpb; /* Parameter block */
PSHDFN pshdfn; /* Pointer to SHD entry point */
ULONG ulStreamTime; /* Stream time */
.
.
.
/*----------------------------------------------------------------------*/
/* Report a cue point to the stream handler for a stream instance. */
/*----------------------------------------------------------------------*/
shdpb.ulFunction = SHD_REPORT_EVENT;
shdpb.hstream = hstream;
shdpb.hevent = hevent;
shdpb.ulStreamTime = ulStreamTime;
if (ulRC = pshdfn (&shdpb))
return (ulRC); /* error! */
SHD_REPORT_EVENT - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
SHD_REPORT_INT
Select an item:
Syntax Returns Remarks Example Code Glossary
This message is used by the physical device driver to report interrupts from a device and indicate that a new buffer is needed for consumption.
pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata structure.
rc(ULONG) Return codes indicating success or type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_DEVICE_UNDERRUN There was a device data underrun.
ERROR_DEVICE_OVERRUN There was a device data overrun.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_INT Parameter - pParmIn
pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata structure.
SHD_REPORT_INT Return Value - rc
rc(ULONG) Return codes indicating success or type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_DEVICE_UNDERRUN There was a device data underrun.
ERROR_DEVICE_OVERRUN There was a device data overrun.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_INT - Syntax
This message is used by the physical device driver to report interrupts from a device and indicate that a new buffer is needed for consumption.
pParmIn(PSHD_REPORTINT) A pointer to a SHD_REPORTINTdata structure.
rc(ULONG) Return codes indicating success or type of failure:
NO_ERROR Success.
ERROR_INVALID_FUNCTION Illegal function requested.
ERROR_INVALID_STREAM Invalid stream handle.
ERROR_DEVICE_UNDERRUN There was a device data underrun.
ERROR_DEVICE_OVERRUN There was a device data overrun.
FAILURE Stream-handler-specific error return code.
SHD_REPORT_INT - Remarks
This message is a mechanism for the physical device driver to return status , indicate that the buffer has been consumed, or indicate that a new buffer is needed.
When status is returned, you will know whether the playback or record was successful or if there was an error condition. Error conditions for playback are known as underruns, which means the device is not getting data fast enough. Error conditions for records are called overruns, which means the device is generating data faster than empty buffers become available. This might result in a data loss situation. For example, the device is constantly bringing in data from the analog ports of the adapter and converting it to digital data. If the device does not have any empty buffers to store the digital data, the data is lost.
If you report an underrun under Warp and want the stream handler to pause the device, you should report the ERROR_DEVICE_UNDERRUN as well as the SHD_ WRITE_COMPLETE flags.
The VSD must return buffers in the order they were sent and should not hold on to any buffers. Failure to return buffers could result in application hangs.
SHD_REPORT_INT - Example Code
The following code illustrates how to report an interrupt from a device.
#include "os2.h"
#include "os2me.h"
#include "shdd.h"
ULONG ulRC; /* Error return code */
HSTREAM hstream; /* Stream handle */
SHD_REPORTINT shdpb; /* Parameter block */
PSHDFN pshdfn; /* Pointer to SHD entry point */
PVOID pBuffer; /* Pointer to buffer */
ULONG ulStreamTime; /* Stream time in millisecs */
.
.
.
/*----------------------------------------------------------------------*/
/* Report a read has completed. */
/*----------------------------------------------------------------------*/
shdpb.ulFunction = SHD_REPORT_INT;
shdpb.hstream = hstream;
shdpb.pBuffer = pBuffer;
shdpb.ulFlag = SHD_READ_COMPLETE;
shdpb.ulStatus = LengthRecordedBuffer;
shdpb.ulStreamTime = ulStreamTime;
if (ulRC = pshdfn (&shdpb))
return (ulRC); /* error! */
SHD_REPORT_INT - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
Vendor-Specific Driver Commands
The vendor-specific driver (VSD) commands enable communication between vendor-specific drivers (VSDs) and an application such as the user-level audio stream handler or amplifier mixer MCI driver. The interface to the VSD is DLL-based. First, a DosLoadModule function is issued for the VSD's DLL. The DosLoadModule function returns a handle for the VSD. Next, using the VSD handle, DosQueryProcAddr is issued to receive the VSD entry point address. This must be done prior to issuing any VSD commands. Once the entry point address is received, calls to the VSD are made to VSDEntryentry point.
VSDEntry
Select an item:
Syntax Parameters Returns Remarks Glossary
This entry point enables communication between vendor-specific drivers ( VSDs) and an application such as the user-level audio stream handler or amplifier mixer. For audio VSDs, be sure to define INCL_AUDIO_VSD before including the VSDCMDS.H header file.
#define INCL_AUDIO_VSD #include <vsdcmds.h> #include <os2mixer.h> HVSD hvsd; /* Handle to VSD instance. */ ULONG ulFunc; /* Function code. */ ULONG ulFlags; /* Flags for driver. */ PVOID pRequest; /* Request parameter block value. */ ULONG rc; /* Return codes. */ rc = VSDEntry(hvsd, ulFunc, ulFlags, pRequest);
VSDEntry - Syntax
This entry point enables communication between vendor-specific drivers ( VSDs) and an application such as the user-level audio stream handler or amplifier mixer. For audio VSDs, be sure to define INCL_AUDIO_VSD before including the VSDCMDS.H header file.
#define INCL_AUDIO_VSD #include <vsdcmds.h> #include <os2mixer.h> HVSD hvsd; /* Handle to VSD instance. */ ULONG ulFunc; /* Function code. */ ULONG ulFlags; /* Flags for driver. */ PVOID pRequest; /* Request parameter block value. */ ULONG rc; /* Return codes. */ rc = VSDEntry(hvsd, ulFunc, ulFlags, pRequest);
VSDEntry Parameter - hvsd
hvsd(HVSD) - input This parameter is the handle to the VSD instance.
VSDEntry Parameter - ulFunc
ulFunc(ULONG) - input The VSD command to be issued. The following commands are supported for audio VSDs.
/-------------------------------------------------------------\ |Command |Description | |------------------------------+------------------------------| |VSD_CLOSE |Closes the device. (Required) | |------------------------------+------------------------------| |VSD_DDCMD |Allows communication between | | |stream handlers and their | | |attached devices. (Required) | |------------------------------+------------------------------| |VSD_ESCAPE |Sends a buffer to the device. | | |(Optional) | |------------------------------+------------------------------| |VSD_GETDEVCAPS |Retrieves the device | | |capabilities. (Required) | |------------------------------+------------------------------| |VSD_OPEN |Opens an instance of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_QUERY |Queries the status of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_RESOURCE |Manages resources. (Required) | |------------------------------+------------------------------| |VSD_RESTORE |Restores device to a saved | | |state. (Required) | |------------------------------+------------------------------| |VSD_SAVE |Saves the current state of the| | |device instance. (Required) | |------------------------------+------------------------------| |VSD_SET |Modifies settings of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_USER |Allows user-defined commands | | |to be passed into the VSD. | | |(Optional) | \-------------------------------------------------------------/
VSDEntry Parameter - ulFlags
ulFlags(ULONG) - input The ulFlagsparameter is used to further qualify the command specified in ulFunc. In many cases it is used as a subcommand. For more information on ulFlags, see the specific ulFuncparameter.
VSDEntry Parameter - pRequest
pRequest(PVOID) - input Specifies the pointer to the request packet. The caller of the VSD supplies all request buffers. See individual commands for more detailed information.
VSDEntry Return Value - rc
rc(ULONG) - returns The return codes are listed for each command and will vary based on the command sent.
If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
VSDEntry - Parameters
hvsd(HVSD) - input This parameter is the handle to the VSD instance.
ulFunc(ULONG) - input The VSD command to be issued. The following commands are supported for audio VSDs.
/-------------------------------------------------------------\ |Command |Description | |------------------------------+------------------------------| |VSD_CLOSE |Closes the device. (Required) | |------------------------------+------------------------------| |VSD_DDCMD |Allows communication between | | |stream handlers and their | | |attached devices. (Required) | |------------------------------+------------------------------| |VSD_ESCAPE |Sends a buffer to the device. | | |(Optional) | |------------------------------+------------------------------| |VSD_GETDEVCAPS |Retrieves the device | | |capabilities. (Required) | |------------------------------+------------------------------| |VSD_OPEN |Opens an instance of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_QUERY |Queries the status of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_RESOURCE |Manages resources. (Required) | |------------------------------+------------------------------| |VSD_RESTORE |Restores device to a saved | | |state. (Required) | |------------------------------+------------------------------| |VSD_SAVE |Saves the current state of the| | |device instance. (Required) | |------------------------------+------------------------------| |VSD_SET |Modifies settings of the | | |device. (Required) | |------------------------------+------------------------------| |VSD_USER |Allows user-defined commands | | |to be passed into the VSD. | | |(Optional) | \-------------------------------------------------------------/
ulFlags(ULONG) - input The ulFlagsparameter is used to further qualify the command specified in ulFunc. In many cases it is used as a subcommand. For more information on ulFlags, see the specific ulFuncparameter.
pRequest(PVOID) - input Specifies the pointer to the request packet. The caller of the VSD supplies all request buffers. See individual commands for more detailed information.
rc(ULONG) - returns The return codes are listed for each command and will vary based on the command sent.
If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
VSDEntry - Remarks
If a VSD requires unique return codes for certain conditions, it can use return codes starting at VSDERR_BASE.
VSDEntry - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VSD_CLOSE
Select an item:
Syntax Returns Remarks Example Code Glossary
This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to the VSD to be closed.
ulFunc(ULONG) Set to VSD_CLOSE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used for this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_CANNOT_CLOSE VSD is unable to close the device.
VSDERR_HARDWARE A hardware error occurred.
VSD_CLOSE Parameter - hvsd
hvsd(HVSD) Handle to the VSD to be closed.
VSD_CLOSE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_CLOSE.
VSD_CLOSE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_CLOSE Parameter - pRequest
pRequest(PVOID) Not used for this command.
VSD_CLOSE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_CANNOT_CLOSE VSD is unable to close the device.
VSDERR_HARDWARE A hardware error occurred.
VSD_CLOSE - Syntax
This command closes the device. VSD_CLOSE is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to the VSD to be closed.
ulFunc(ULONG) Set to VSD_CLOSE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used for this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_CANNOT_CLOSE VSD is unable to close the device.
VSDERR_HARDWARE A hardware error occurred.
VSD_CLOSE - Remarks
The hvsdhandle is no longer valid after this command is issued.
VSD_CLOSE - Example Code
The following code illustrates how to close a VSD.
HVSD hvsd;
ULONG rc;
rc = pInstance ->pfnAUDIOIF( hvsd,
VSD_CLOSE,
0,
0 );
return (rc);
VSD_CLOSE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_DDCMD
Select an item:
Syntax Returns Remarks Glossary
Stream handlers can communicate to their attached devices using the VSD_ DDCMD call. The DDCMD interface is the primary method of moving data to and from devices in OS/2 multimedia. See the OS/2 Multimedia Programming Referencefor more detailed information on stream handler command (SHC) messages.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_DDCMD.
ulFlags(ULONG) The following flags (subcommands) are defined for this command:
DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. pRequestis a pointer to the DDCMDCONTROLstructure.
DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequestis a pointer to DDCMDDEREGISTERstructure.
DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an emptybuffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a MSG_ REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequestis a pointer to DDCMDREGISTERstructure.
DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequestis a pointer to DDCMDSETUPstructure.
DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. pRequestis a pointer to DDCMDSTATUSstructure.
DDCMD_WRITE This VSD subcommand is used by a stream handler to give a fullbuffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a MSG_REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
pRequest(PVOID) The value of pRequestvaries according to the ulFlagsvalue. See each particular ulFlagsvalue for the definition of pRequest.
rc(ULONG) Possible error codes vary according to the value of ulFlags.
VSD_DDCMD Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_DDCMD Parameter - ulFunc
ulFunc(ULONG) Set to VSD_DDCMD.
VSD_DDCMD Parameter - ulFlags
ulFlags(ULONG) The following flags (subcommands) are defined for this command:
DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. pRequestis a pointer to the DDCMDCONTROLstructure.
DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequestis a pointer to DDCMDDEREGISTERstructure.
DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an emptybuffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a MSG_ REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequestis a pointer to DDCMDREGISTERstructure.
DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequestis a pointer to DDCMDSETUPstructure.
DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. pRequestis a pointer to DDCMDSTATUSstructure.
DDCMD_WRITE This VSD subcommand is used by a stream handler to give a fullbuffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a MSG_REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
VSD_DDCMD Parameter - pRequest
pRequest(PVOID) The value of pRequestvaries according to the ulFlagsvalue. See each particular ulFlagsvalue for the definition of pRequest.
VSD_DDCMD Return Value - rc
rc(ULONG) Possible error codes vary according to the value of ulFlags.
VSD_DDCMD - Syntax
Stream handlers can communicate to their attached devices using the VSD_ DDCMD call. The DDCMD interface is the primary method of moving data to and from devices in OS/2 multimedia. See the OS/2 Multimedia Programming Referencefor more detailed information on stream handler command (SHC) messages.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_DDCMD.
ulFlags(ULONG) The following flags (subcommands) are defined for this command:
DDCMD_CONTROL This subcommand of VSD_DDCMD performs a device-specific command. pRequestis a pointer to the DDCMDCONTROLstructure.
DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequestis a pointer to DDCMDDEREGISTERstructure.
DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an emptybuffer to the VSD (for example, during a record operation). When the buffer has been filled, the VSD is responsible for communicating to the caller that the buffer has been filled. The VSD should pass a MSG_ REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequestis a pointer to DDCMDREGISTERstructure.
DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequestis a pointer to DDCMDSETUPstructure.
DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. pRequestis a pointer to DDCMDSTATUSstructure.
DDCMD_WRITE This VSD subcommand is used by a stream handler to give a fullbuffer to the VSD (for example, during a playback operation). When the buffer has been consumed, the VSD is responsible for communicating to the caller that the buffer has been used. The VSD should pass a MSG_REPORTINTstructure to the pSHDEntryPointin DDCMDREGISTERto inform the caller.
pRequestis a pointer to DDCMDREADWRITEstructure.
pRequest(PVOID) The value of pRequestvaries according to the ulFlagsvalue. See each particular ulFlagsvalue for the definition of pRequest.
rc(ULONG) Possible error codes vary according to the value of ulFlags.
VSD_DDCMD - Remarks
A user-level 32-bit buffer pointer is available in the pProcessLinfield of the DDCMDREADWRITE. VSDs should use this pointer if they want to operate on the data while they are not in protect mode. The pBufferfield of the DDCMDREADWRITEcontains a pointer whose address type was specified by the VSD on DDCMD_REG_STREAM. When the application returns a buffer, it must return the buffer specified by pBufferand notby pProcessLin
VSD_DDCMD - Topics
Select an item:
Syntax Returns Remarks Glossary
VSD_GETDEVCAPS
Select an item:
Syntax Returns Remarks Example Code Glossary
This command queries the device capabilities. These values should be constants that describe the device and driver characteristics. In general, the flags indicate what set of commands are supported. VSD_GETDEVCAPS is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_GETDEVCAPS.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_GETDEVCAPS_PARMS) Pointer to the VSD_GETDEVCAPS_PARMSdata structure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_REQUEST_BUF_TOO_SMALL The ulLengthin the request packet is too small.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_HARDWARE A hardware error occurred.
VSD_GETDEVCAPS Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_GETDEVCAPS Parameter - ulFunc
ulFunc(ULONG) Set to VSD_GETDEVCAPS.
VSD_GETDEVCAPS Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_GETDEVCAPS Parameter - pRequest
pRequest(PVSD_GETDEVCAPS_PARMS) Pointer to the VSD_GETDEVCAPS_PARMSdata structure.
VSD_GETDEVCAPS Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_REQUEST_BUF_TOO_SMALL The ulLengthin the request packet is too small.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_HARDWARE A hardware error occurred.
VSD_GETDEVCAPS - Syntax
This command queries the device capabilities. These values should be constants that describe the device and driver characteristics. In general, the flags indicate what set of commands are supported. VSD_GETDEVCAPS is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_GETDEVCAPS.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_GETDEVCAPS_PARMS) Pointer to the VSD_GETDEVCAPS_PARMSdata structure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_REQUEST_BUF_TOO_SMALL The ulLengthin the request packet is too small.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_HARDWARE A hardware error occurred.
VSD_GETDEVCAPS - Remarks
This command requires the device to be opened. A device might have several types of device units, so this command must know which instance is involved . Once the device is opened, the device capabilities should be constant.
Each element in the bSupports[DC_MAX_DEVCAP]array of the VSD_GETDEVCAPS_ PARMSstructure is a boolean value that indicates if the capability is supported. TRUE indicates that it is supported. FALSE indicates that it is not supported.
VSD_GETDEVCAPS - Example Code
The following code illustrates how to determine device capabilities for a VSD.
HVSD hvsd;
VSD_GETDEVCAPS_PARMS vsdDevCaps;
rc = pInstance->pfnAUDIOIF( hvsd,
VSD_GETDEVCAPS
0,
(PVOID) &vsdDevCaps );
if (!rc)
{
/* If the VSD doesn't support volume */
if( !vsdDevCaps.bSupports[ DC_HASVOLUME] )
{
return ( rc );
}
VSD_GETDEVCAPS - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_ESCAPE
Select an item:
Syntax Returns Glossary
This optional command sends a buffer to the driver.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_ESCAPE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_ESCAPE_PARMS) A pointer to the VSD_ESCAPE_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_ESCAPE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_ESCAPE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_ESCAPE.
VSD_ESCAPE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_ESCAPE Parameter - pRequest
pRequest(PVSD_ESCAPE_PARMS) A pointer to the VSD_ESCAPE_PARMSstructure.
VSD_ESCAPE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_ESCAPE - Syntax
This optional command sends a buffer to the driver.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_ESCAPE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_ESCAPE_PARMS) A pointer to the VSD_ESCAPE_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_ESCAPE - Topics
Select an item:
Syntax Returns Glossary
VSD_INSERTSETTINGSPAGE
Select an item:
Syntax Returns Glossary
This command enables a VSD to insert device-specific settings pages into the system configuration application.
hvsd(HVSD) Handle to a VSD instance.
ulFunc(ULONG) Set to VSD_INSERTSETTINGSPAGE.
ulFlags(ULONG) No flags used for this command.
pRequest(PMCI_DEVICESETTINGS_PARMS) Pointer to the MCI_DEVICESETTINGS_ PARMSdata structure.
hwndRC(HWND) The return code contains the handle to a settings page or zero if no page is inserted.
VSD_INSERTSETTINGSPAGE Parameter - hvsd
hvsd(HVSD) Handle to a VSD instance.
VSD_INSERTSETTINGSPAGE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_INSERTSETTINGSPAGE.
VSD_INSERTSETTINGSPAGE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_INSERTSETTINGSPAGE Parameter - pRequest
pRequest(PMCI_DEVICESETTINGS_PARMS) Pointer to the MCI_DEVICESETTINGS_ PARMSdata structure.
VSD_INSERTSETTINGSPAGE Return Value - hwndRC
hwndRC(HWND) The return code contains the handle to a settings page or zero if no page is inserted.
VSD_INSERTSETTINGSPAGE - Syntax
This command enables a VSD to insert device-specific settings pages into the system configuration application.
hvsd(HVSD) Handle to a VSD instance.
ulFunc(ULONG) Set to VSD_INSERTSETTINGSPAGE.
ulFlags(ULONG) No flags used for this command.
pRequest(PMCI_DEVICESETTINGS_PARMS) Pointer to the MCI_DEVICESETTINGS_ PARMSdata structure.
hwndRC(HWND) The return code contains the handle to a settings page or zero if no page is inserted.
VSD_INSERTSETTINGSPAGE - Topics
Select an item:
Syntax Returns Glossary
VSD_OPEN
Select an item:
Syntax Returns Remarks Example Code Glossary
This command opens the device driver and returns a VSD handle or (HVSD). It should not allocate resources on the device (resource usage should be performed on the VSD restore).
VSD_OPEN is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Not used.
ulFunc(ULONG) Set to VSD_OPEN.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_OPEN_PARMS) Pointer to the VSD_OPEN_PARMSdata structure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.
VSDERR_DEVICE_REJECTED Device driver rejected the request.
VSDERR_HARDWARE A hardware error occurred.
VSDERR_INVALID_BUFF pRequestis not valid.
VSD_OPEN Parameter - hvsd
hvsd(HVSD) Not used.
VSD_OPEN Parameter - ulFunc
ulFunc(ULONG) Set to VSD_OPEN.
VSD_OPEN Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_OPEN Parameter - pRequest
pRequest(PVSD_OPEN_PARMS) Pointer to the VSD_OPEN_PARMSdata structure.
VSD_OPEN Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.
VSDERR_DEVICE_REJECTED Device driver rejected the request.
VSDERR_HARDWARE A hardware error occurred.
VSDERR_INVALID_BUFF pRequestis not valid.
VSD_OPEN - Syntax
This command opens the device driver and returns a VSD handle or (HVSD). It should not allocate resources on the device (resource usage should be performed on the VSD restore).
VSD_OPEN is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Not used.
ulFunc(ULONG) Set to VSD_OPEN.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_OPEN_PARMS) Pointer to the VSD_OPEN_PARMSdata structure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_NO_DEVICE_DRIVER VSD is not connected to a device driver.
VSDERR_DEVICE_REJECTED Device driver rejected the request.
VSDERR_HARDWARE A hardware error occurred.
VSDERR_INVALID_BUFF pRequestis not valid.
VSD_OPEN - Remarks
The installation name of the media control driver (MCD) is passed in so that the VSD can query device-specific parameters from the INI file.
For an audio VSD, the pDevInfopointer points to a VSD_AUDIOOPEN_PARMSstructure. This structure contains enough information to initialize the audio device. The VSD is responsible for filling in the ulDataSubTypefield of the VSD_AUDIOOPEN_PARMSstructure with a valid data subtype.
VSD_OPEN - Example Code
The following code illustrates how to open an audio VSD.
VSD_OPEN_PARMS vsdOpenParms;
VSD_AUDIOOPEN_PARMS vsdData;
vsdData.ulLength = sizeof(VSD_AUDIOOPEN_PARMS);
vsdData.ulFlags = 0;
vsdData.ulSamplingRate = pInstance->lSRate;
vsdData.ulBitsPerSample = pInstance->lBitsPerSRate;
vsdData.ulChannels = pInstance->sChannels;
vsdData.ulDataType = pInstance->sMode;
vsdData.ulDeviceID = pInstance->ulDeviceID;
vsdData.ulOperation = pInstance->ulOperation;
vsdOpenParms.pDevInfo = (PVOID)&vsdData;
vsdOpenParms.ulLength = sizeof(VSD_OPEN_PARMS);
memmove(&vsdOpenParms.szPDDName,
pInstance->szDeviceName,
strlen(pInstance->szDeviceName));
/* Open the audio VSD */
rc = pInstance->pfnAUDIOIF(0,
VSD_OPEN,
0L
(PVOID)&vsdOpenParms);
if (!rc)
}
pInstance->hvsd = vsdOpenParms.hvsd;
{
VSD_OPEN - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_QUERY
Select an item:
Syntax Returns Remarks Glossary
This command allows an application to query the status of the VSD.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) The following flags can be used with VSD_QUERY:
VSD_QUERYAUDIOATTRIBUTES See VSD_QUERYAUDIOATTRIBUTES.
VSD_QUERYCONNECTOR See VSD_QUERYCONNECTOR.
VSD_QUERYDATATYPE See VSD_QUERYDATATYPE.
VSD_QUERYMONITOR See VSD_QUERYMONITOR.
VSD_QUERYVOLUME See VSD_QUERYVOLUME.
VSD_QUERYMIXCONNECTIONS See VSD_QUERYMIXCONNECTIONS.
VSD_QUERYMIXCONTROL See VSD_QUERYMIXCONTROL.
VSD_QUERYMIXLINE See VSD_QUERYMIXLINE.
pRequest(PVOID) Pointer varies according to ulFlags.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERY Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERY Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERY Parameter - ulFlags
ulFlags(ULONG) The following flags can be used with VSD_QUERY:
VSD_QUERYAUDIOATTRIBUTES See VSD_QUERYAUDIOATTRIBUTES.
VSD_QUERYCONNECTOR See VSD_QUERYCONNECTOR.
VSD_QUERYDATATYPE See VSD_QUERYDATATYPE.
VSD_QUERYMONITOR See VSD_QUERYMONITOR.
VSD_QUERYVOLUME See VSD_QUERYVOLUME.
VSD_QUERYMIXCONNECTIONS See VSD_QUERYMIXCONNECTIONS.
VSD_QUERYMIXCONTROL See VSD_QUERYMIXCONTROL.
VSD_QUERYMIXLINE See VSD_QUERYMIXLINE.
VSD_QUERY Return Value - pRequest
pRequest(PVOID) Pointer varies according to ulFlags.
VSD_QUERY Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERY - Syntax
This command allows an application to query the status of the VSD.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) The following flags can be used with VSD_QUERY:
VSD_QUERYAUDIOATTRIBUTES See VSD_QUERYAUDIOATTRIBUTES.
VSD_QUERYCONNECTOR See VSD_QUERYCONNECTOR.
VSD_QUERYDATATYPE See VSD_QUERYDATATYPE.
VSD_QUERYMONITOR See VSD_QUERYMONITOR.
VSD_QUERYVOLUME See VSD_QUERYVOLUME.
VSD_QUERYMIXCONNECTIONS See VSD_QUERYMIXCONNECTIONS.
VSD_QUERYMIXCONTROL See VSD_QUERYMIXCONTROL.
VSD_QUERYMIXLINE See VSD_QUERYMIXLINE.
pRequest(PVOID) Pointer varies according to ulFlags.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERY - Remarks
This command uses flags to indicate what information is queried.
VSD_QUERY - Topics
Select an item:
Syntax Returns Remarks Glossary
VSD_QUERYAUDIOATTRIBUTES
Select an item:
Syntax Returns Remarks Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the current audio settings and capabilities. A valid length must be placed in the ulLengthfield of the VSD_AUDIOATTRIBUTES_PARMSstructure and the audio setting (such as treble, bass, and so on) must be placed in the ulFlagsfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYAUDIOATTRIBUTES.
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYAUDIOATTRIBUTES Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYAUDIOATTRIBUTES Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYAUDIOATTRIBUTES Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYAUDIOATTRIBUTES.
VSD_QUERYAUDIOATTRIBUTES Parameter - pRequest
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
VSD_QUERYAUDIOATTRIBUTES Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYAUDIOATTRIBUTES - Syntax
This subcommand of the VSD_QUERYcommand queries the current audio settings and capabilities. A valid length must be placed in the ulLengthfield of the VSD_AUDIOATTRIBUTES_PARMSstructure and the audio setting (such as treble, bass, and so on) must be placed in the ulFlagsfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYAUDIOATTRIBUTES.
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYAUDIOATTRIBUTES - Remarks
All values are returned in the ulValuefield and can range from 0 - 100.
VSD_QUERYAUDIOATTRIBUTES - Example Code
The following code illustrates how to query audio attribute information from the VSD.
HVSD hvsd;
VSD_AUDIOATTRIBUTES_PARMS vsdAttr;
/* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;
/*---------------------------------------------
* Ask the VSD to either set or query an audio
* attribute. The caller determines whether
* to set or query via the command variable.
*---------------------------------------------*/
rc = pInstance->pfnAUDIOIF(hvsd,
VSD_QUERY,
VSD_QUERYAUDIOATTRIBUTES,
(PVOID)&vsdAttr);
/* If Bass value is too high then...*/
if (!rc)
{
if (vsdAttr.ulValue > 70)
{
}
VSD_QUERYAUDIOATTRIBUTES - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_QUERYCONNECTOR
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the state of the connector . (A connector can be a hardware or software connection on the device the VSD is controlling.) If the connector is enabled, the fEnabledfield of the VSD_CONNECTOR_PARMSstructure will contain MCI_TRUE, otherwise it will contain MCI_FALSE. For further information regarding connectors, refer to the MCI connector command in the OS/2 Multimedia Programming Reference. Valid connectors can be found in MCIOS2.H.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYCONNECTOR.
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.
VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.
VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.
VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.
VSDERR_INVALID_CONNECTOR Invalid connector.
VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYCONNECTOR Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYCONNECTOR Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYCONNECTOR Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYCONNECTOR.
VSD_QUERYCONNECTOR Parameter - pRequest
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
VSD_QUERYCONNECTOR Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.
VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.
VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.
VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.
VSDERR_INVALID_CONNECTOR Invalid connector.
VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYCONNECTOR - Syntax
This subcommand of the VSD_QUERYcommand queries the state of the connector . (A connector can be a hardware or software connection on the device the VSD is controlling.) If the connector is enabled, the fEnabledfield of the VSD_CONNECTOR_PARMSstructure will contain MCI_TRUE, otherwise it will contain MCI_FALSE. For further information regarding connectors, refer to the MCI connector command in the OS/2 Multimedia Programming Reference. Valid connectors can be found in MCIOS2.H.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYCONNECTOR.
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_UNSUPPORTED_CONN_TYPE Connector type not supported.
VSDERR_INVALID_CONNECTOR_TYPE Invalid connector type.
VSDERR_INVALID_CONNECTOR_INDEX Invalid connector index.
VSDERR_CANNOT_MODIFY_CONNECTOR Cannot enable or disable this connector.
VSDERR_INVALID_CONNECTOR Invalid connector.
VSDERR_UNSUPPORTED_CONNECTOR Unsupported connector.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYCONNECTOR - Example Code
The following code illustrates how to query the state of the connector.
HVSD hvsd;
VSD_CONNECTOR_PARMS vsdConn;
vsdConn.ulConn_Type = pConnector->ulConnectorType;
vsdConn.ulIndex = pConnector->ulConnectorIndex;
lError = pInstance->pfnNewVSD(hvsd,
VSD_QUERY,
VSD_QUERYCONNECTOR,
(PVOID)&vsdConn);
prConnector->ulReturn = vsdConn.fEnabled;
VSD_QUERYCONNECTOR - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_QUERYDATATYPE
Select an item:
Syntax Returns Remarks Example Code Glossary
This subcommand of the VSD_QUERYcommand queries if a particular set of data types are supported. The ulSamplingRate, ulBitsPerSample, ulChannels, and ulDataTypewill be filled in on input. The ulDataSubTypeis filled in by the VSD on output. If the current mode is not supported, the VSD should fill in the ulSamplingRate, ulBitsPerSample, and ulChannelswith the closest that it supports.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYDATATYPE.
pRequest(PVSD_AUDIODATATYPE_PARMS) Pointer to the VSD_AUDIODATATYPE_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYDATATYPE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYDATATYPE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYDATATYPE Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYDATATYPE.
VSD_QUERYDATATYPE Parameter - pRequest
pRequest(PVSD_AUDIODATATYPE_PARMS) Pointer to the VSD_AUDIODATATYPE_PARMSstructure.
VSD_QUERYDATATYPE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYDATATYPE - Syntax
This subcommand of the VSD_QUERYcommand queries if a particular set of data types are supported. The ulSamplingRate, ulBitsPerSample, ulChannels, and ulDataTypewill be filled in on input. The ulDataSubTypeis filled in by the VSD on output. If the current mode is not supported, the VSD should fill in the ulSamplingRate, ulBitsPerSample, and ulChannelswith the closest that it supports.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYDATATYPE.
pRequest(PVSD_AUDIODATATYPE_PARMS) Pointer to the VSD_AUDIODATATYPE_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_QUERYDATATYPE - Remarks
This command is typically sent by applications which need to determine if the VSD supports a particular datatype.
VSD_QUERYDATATYPE - Example Code
The following code illustrates the use of VSD_QUERYDATATYPE:
HVSD hvsd;
VSD_AUDIODATATYPE_PARMS AudioCaps;
/*---------------------------------------
* Tell the VSD that we want to enable a
* connector.
*---------------------------------------*/
rc = pInstance->pfnNewVSD( hvsd ,
VSD_QUERY,
VSD_QUERYDATATYPE,
(PVOID ) &AudioCaps );
if ( rc )
{
rc = MCIERR_INVALID_CONNECTION ;
return (rc);
}
else
{
rc = MCIERR_SUCCESS;
}
return ( rc );
} /* TestConnection */
VSD_QUERYDATATYPE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_QUERYMIXCONNECTIONS
Select an item:
Syntax Returns Remarks Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the output that a particular VSD line (or connector) is routed to. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXCONNECTIONS.
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONNECTIONS Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYMIXCONNECTIONS Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYMIXCONNECTIONS Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYMIXCONNECTIONS.
VSD_QUERYMIXCONNECTIONS Parameter - pRequest
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
VSD_QUERYMIXCONNECTIONS Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONNECTIONS - Syntax
This subcommand of the VSD_QUERYcommand queries the output that a particular VSD line (or connector) is routed to. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXCONNECTIONS.
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONNECTIONS - Remarks
The ulConnectionsfield of the LINECONNECTIONSstructure returns the particular output that a line is routed to. The ulLinefield of the LINECONNECTIONSstructure must contain a valid line on input. For more information on the values for ulLineand ulConnections, see the LINECONNECTIONSstructure.
VSD_QUERYMIXCONNECTIONS - Example Code
The following code illustrates how to query the output that a particular line is routed to.
HVSD hvsd;
LINECONNECTIONS LineCon;
/* Find out the setting for the synth. */
LineCon.ulLine = SOURCE_SYNTHESIZER;
LineCon.ulLength = sizeof(MIXERLINEINFO);
/* Ask VSD for the capabilities of this line. */
rc = pInstance->(hvsd,
VSD_QUERY,
VSD_QUERYMIXCONNECTIONS,
(PVOID)&LineCon);
/* Are we connected to the amp or record outputs... */
if (LineCon.ulConnection & (SINK_SPEAKERS))
{
pMixParms->ulReturn = MCI_OUTPUT_AMP;
}
else
{
pMixParms->ulReturn = MCI_OUTPUT_DIGITALAUDIO;
}
VSD_QUERYMIXCONNECTIONS - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_QUERYMIXCONTROL
Select an item:
Syntax Returns Remarks Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the audio attributes for an audio VSD connector (for example, the treble setting on a microphone connector). For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXCONTROL.
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONTROL Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYMIXCONTROL Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYMIXCONTROL Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYMIXCONTROL.
VSD_QUERYMIXCONTROL Parameter - pRequest
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
VSD_QUERYMIXCONTROL Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONTROL - Syntax
This subcommand of the VSD_QUERYcommand queries the audio attributes for an audio VSD connector (for example, the treble setting on a microphone connector). For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXCONTROL.
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXCONTROL - Remarks
The ulLinefield of the MIXERCONTROLstructure must be filled in with one of the VSD sources/sinks in the low-order byte of the low word.
The ulControlfield of the MIXERCONTROLstructure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting 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.
VSD_QUERYMIXCONTROL - Example Code
The following code illustrates how to query the settings of audio attributes for a particular connector.
HVSD hvsd;
MIXERCONTROL MixerControl;
USHORT usBass;
/* Find out the setting for the synth. */
MixerControl.ulLine = SOURCE_SYNTHESIZER;
/* Ask VSD what is the current setting of the connector. */
MixerControl.ulControl = MIX_BASS;
rc = pInstance->(hvsd,
VSD_QUERY,
VSD_QUERYMIXCONTROL,
(PVOID)&MixerControl);
usBass = (MixControl.ulSetting)
}
VSD_QUERYMIXCONTROL - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_QUERYMIXLINE
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the audio attributes that are supported for the given VSD connector. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXLINE.
pRequest(PMIXERLINEINFO) A pointer to the MIXERLINEINFOstructure. The ulSupportfield will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ulLinefield must be filled in by the caller.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXLINE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYMIXLINE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYMIXLINE Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYMIXLINE.
VSD_QUERYMIXLINE Parameter - pRequest
pRequest(PMIXERLINEINFO) A pointer to the MIXERLINEINFOstructure. The ulSupportfield will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ulLinefield must be filled in by the caller.
VSD_QUERYMIXLINE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXLINE - Syntax
This subcommand of the VSD_QUERYcommand queries the audio attributes that are supported for the given VSD connector. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMIXLINE.
pRequest(PMIXERLINEINFO) A pointer to the MIXERLINEINFOstructure. The ulSupportfield will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ulLinefield must be filled in by the caller.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_QUERYMIXLINE - Example Code
The following code illustrates how to query the supported audio attributes from a mixer connector.
HVSD hvsd;
MIXERLINEINFO mixerinfo;
mixerinfo.ulLine = SYNTHESIZER_INPUT;
mixerinfo.ulLength = sizeof(MIXERLINEINFO);
rc = pInstance->pfnAUDIOIF( hsvd,
VSD_QUERY,
VSD_QUERYMIXLINE,
(PVOID) &mixerinfo);
if(!rc)
if(mixerinfo.ulSupport & MIX_VOLUME)
{
/* process volume */
}
} /* If no errors */
VSD_QUERYMIXLINE - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_QUERYMONITOR
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the device to determine if audio monitoring is enabled. The VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD instance.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMONITOR.
pRequest(PULONG) Output.
rc(ULONG) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.
VSD_QUERYMONITOR Parameter - hvsd
hvsd(HVSD) Handle to a VSD instance.
VSD_QUERYMONITOR Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYMONITOR Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYMONITOR.
VSD_QUERYMONITOR Parameter - pRequest
pRequest(PULONG) Output.
VSD_QUERYMONITOR Return Value - rc
rc(ULONG) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.
VSD_QUERYMONITOR - Syntax
This subcommand of the VSD_QUERYcommand queries the device to determine if audio monitoring is enabled. The VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD instance.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYMONITOR.
pRequest(PULONG) Output.
rc(ULONG) VSD returns TRUE if the monitor is enabled and FALSE if it is disabled.
VSD_QUERYMONITOR - Example Code
The following code illustrates how to query the state of monitoring.
rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
VSD_QUERY,
VSD_QUERYMONITOR,
(PVOID)&pStat->ulReturn);
VSD_QUERYMONITOR - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_QUERYSTATUSLEVEL
Select an item:
Syntax Returns Glossary
This subcommand of the VSD_QUERYcommand queries the status of the audio input level (percentage). This command is optional.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYSTATUSLEVEL.
pRequest(PULONG) Current level of device.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_QUERYSTATUSLEVEL Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYSTATUSLEVEL Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYSTATUSLEVEL Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYSTATUSLEVEL.
VSD_QUERYSTATUSLEVEL Parameter - pRequest
pRequest(PULONG) Current level of device.
VSD_QUERYSTATUSLEVEL Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_QUERYSTATUSLEVEL - Syntax
This subcommand of the VSD_QUERYcommand queries the status of the audio input level (percentage). This command is optional.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYSTATUSLEVEL.
pRequest(PULONG) Current level of device.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_QUERYSTATUSLEVEL - Topics
Select an item:
Syntax Returns Glossary
VSD_QUERYVOLUME
Select an item:
Syntax Returns Remarks Example Code Glossary
This subcommand of the VSD_QUERYcommand queries the volume level. The volume is returned as a percentage between 0% and 100%
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYVOLUME.
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful. field.
VSD_QUERYVOLUME Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_QUERYVOLUME Parameter - ulFunc
ulFunc(ULONG) Set to VSD_QUERY.
VSD_QUERYVOLUME Parameter - ulFlags
ulFlags(ULONG) Set to VSD_QUERYVOLUME.
VSD_QUERYVOLUME Parameter - pRequest
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
VSD_QUERYVOLUME Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful. field.
VSD_QUERYVOLUME - Syntax
This subcommand of the VSD_QUERYcommand queries the volume level. The volume is returned as a percentage between 0% and 100%
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_QUERY.
ulFlags(ULONG) Set to VSD_QUERYVOLUME.
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful. field.
VSD_QUERYVOLUME - Remarks
On return, the VSD will fill in the ulVolumefield of the VSD_VOLUME_PARMSstructure.
VSD_QUERYVOLUME - Example Code
The following code illustrates how to query audio volume from the VSD.
VSD_VOLUME_PARMS vsdVol;
ULONG ulVol;
vsdVol.ulLength = sizeof(VSD_VOLUME_PARMS);
vsdVol.ulFlags = ulFlags;
/*------------------------------------------
* Ask the VSD to query audio volume.
*------------------------------------------*/
rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
VSD_QUERY,
VSD_QUERYVOLUME,
(PVOID)&vsdVol);
ulVol = vsdvol.ulVolume;
VSD_QUERYVOLUME - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_RESOURCE
Select an item:
Syntax Returns Remarks Example Code Glossary
This command can be issued only when the device is opened and is used for resource management.
VSD_RESOURCE is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_RESOURCE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_RESOURCE_PARMS) Pointer to the VSD_RESOURCE_PARMSdata structure.
The driver is responsible for filling in the ulResUnitsand ulClassfields. The caller is responsible for filling in the ulDataTypefield.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters is missing.
VSD_RESOURCE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_RESOURCE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_RESOURCE.
VSD_RESOURCE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_RESOURCE Parameter - pRequest
pRequest(PVSD_RESOURCE_PARMS) Pointer to the VSD_RESOURCE_PARMSdata structure.
The driver is responsible for filling in the ulResUnitsand ulClassfields. The caller is responsible for filling in the ulDataTypefield.
VSD_RESOURCE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters is missing.
VSD_RESOURCE - Syntax
This command can be issued only when the device is opened and is used for resource management.
VSD_RESOURCE is a required command and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_RESOURCE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVSD_RESOURCE_PARMS) Pointer to the VSD_RESOURCE_PARMSdata structure.
The driver is responsible for filling in the ulResUnitsand ulClassfields. The caller is responsible for filling in the ulDataTypefield.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS Command completed successfully.
VSDERR_MISSING_PARAMETER One or more parameters is missing.
VSD_RESOURCE - Remarks
When an audio device driver is installed in MMPM/2, the installation routines place the following three keywords in the MMPM2.INI file:
�RESOURCEUNITS=
�RESOURCECLASS=
�VALIDCOMBINATIONS=
Because MMPM/2 allows many applications to simultaneously open the audio card, it uses these keywords to determine which applications can simultaneously use the audio device. All of the numbers are arbitrary and are defined on a device-by-device basis. However, device driver writers should use the numbering scheme defined below:
The keyword RESOURCECLASSESindicates the different resource types available on the audio device. The first parameter is the number of classes and it is followed by a listing of classes. A vendor should provide a class for each data type that they support. For instance, if the XYZ audio card can only play PCM files, it would only have one resource class - the PCM class. However, if the ABC audio card can play PCM, MIDI, and ADPCM, then it would have three classes. The VSD should fill in the ulClassfield with the class that is appropriate for this mode.
The keyword RESOURCEUNITSindicates 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 for this card would be three. In contrast, the ABC card can only play one PCM file and one MIDI file at any one time. Therefore, its resource units should be two. The VSD should fill in the ulResUnitsfield with the correct number of resources for the current mode (typically, one).
VSD_RESOURCE - Example Code
The following code illustrates how to determine the number of resources consumed for a particular mode on an audio VSD.
HVSD hvsd;
rc = pInstance->pfnAUDIOIF( hvsd,
VSD_RESOURCE,
0L,
(PVOID)&vsdResourceParms );
pInstance->ulResourcesUsed = vsdResourceParms.ulResUnits;
pInstance->ulClass = vsdResourceParms.ulClass;
VSD_RESOURCE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_RESTORE
Select an item:
Syntax Returns Remarks Example Code Glossary
This command restores the current state of the device. VSD_RESTORE is a required function and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_RESTORE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used with this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command completed successfully.
VSD_RESTORE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_RESTORE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_RESTORE.
VSD_RESTORE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_RESTORE Parameter - pRequest
pRequest(PVOID) Not used with this command.
VSD_RESTORE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command completed successfully.
VSD_RESTORE - Syntax
This command restores the current state of the device. VSD_RESTORE is a required function and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_RESTORE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used with this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command completed successfully.
VSD_RESTORE - Remarks
MMPM/2 supports the concept of suspending and resuming the state of a device at any point in time. Unlike other environments, multiple applications can simultaneously have a device open and the Media Device Manager will cooperate with the VSD in order to manage the device. The VSD is responsible for saving and restoring the actual hardware device. For further information, see the OS/2 Multimedia Programming Reference(MCI_ RESTORE).
VSD_RESTORE - Example Code
The following code illustrates how to activate an audio VSD using VSD_ RESTORE.
ULONG rc;
HVSD hvsd;
rc = pInstance->pfnAUDIOIF( hvsd,
VSD_RESTORE,
0L,
0 );
return(rc)
VSD_RESTORE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_SAVE
Select an item:
Syntax Returns Remarks Example Code Glossary
This command saves the current state of the device. VSD_SAVE is a required function and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_SAVE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used with this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SAVE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SAVE Parameter - ulFunc
ulFunc(ULONG) Set to VSD_SAVE.
VSD_SAVE Parameter - ulFlags
ulFlags(ULONG) No flags used for this command.
VSD_SAVE Parameter - pRequest
pRequest(PVOID) Not used with this command.
VSD_SAVE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SAVE - Syntax
This command saves the current state of the device. VSD_SAVE is a required function and must be implemented by all VSD writers.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_SAVE.
ulFlags(ULONG) No flags used for this command.
pRequest(PVOID) Not used with this command.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SAVE - Remarks
MMPM/2 supports the concept of suspending and resuming the state of a device at any point in time. Unlike other environments, multiple applications can simultaneously have a device open and the Media Device Manager will cooperate with the VSD in order to manage the device. The VSD is responsible for saving and restoring the actual hardware device. For further information, see the OS/2 Multimedia Programming Reference(MCIDRV_ SAVE).
VSD_SAVE - Example Code
The following code illustrates how to deactivate an audio VSD using VSD_ SAVE.
ULONG rc;
HVSD hvsd;
rc = pInstance->pfnAUDIOIF( hvsd,
VSD_SAVE,
0L,
0 );
return(rc);
VSD_SAVE - Topics
Select an item:
Syntax Returns Remarks Example Code Glossary
VSD_SET
Select an item:
Syntax Returns Remarks Glossary
This command allows an application to modify the settings of the VSD.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to VSD.
ulFunc(ULONG) Set to VSD_SET.
ulFlags(ULONG) The following flags can be used with VSD_SET.
VSD_SETAUDIOATTRIBUTES See VSD_SETAUDIOATTRIBUTES
VSD_SETCONNECTOR See VSD_SETCONNECTOR
VSD_SETDATATYPE See VSD_SETDATATYPE
VSD_SETMIXCONNECTIONS See VSD_SETMIXCONNECTIONS
VSD_SETMIXCONTROL See VSD_SETMIXCONTROL
VSD_SETMONITOR See VSD_SETMONITOR
VSD_SETVOLUME See VSD_SETVOLUME
pRequest(PVOID) Pointer value varies according to the value of ulFlags.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_HVSD The hvsd(VSD handle) is not valid. Verify that the hvsdmatches the one provided on the VSD_OPEN.
VSD_SET Parameter - hvsd
hvsd(HVSD) Handle to VSD.
VSD_SET Parameter - ulFunc
ulFunc(ULONG) Set to VSD_SET.
VSD_SET Parameter - ulFlags
ulFlags(ULONG) The following flags can be used with VSD_SET.
VSD_SETAUDIOATTRIBUTES See VSD_SETAUDIOATTRIBUTES
VSD_SETCONNECTOR See VSD_SETCONNECTOR
VSD_SETDATATYPE See VSD_SETDATATYPE
VSD_SETMIXCONNECTIONS See VSD_SETMIXCONNECTIONS
VSD_SETMIXCONTROL See VSD_SETMIXCONTROL
VSD_SETMONITOR See VSD_SETMONITOR
VSD_SETVOLUME See VSD_SETVOLUME
VSD_SET Parameter - pRequest
pRequest(PVOID) Pointer value varies according to the value of ulFlags.
VSD_SET Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_HVSD The hvsd(VSD handle) is not valid. Verify that the hvsdmatches the one provided on the VSD_OPEN.
VSD_SET - Syntax
This command allows an application to modify the settings of the VSD.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to VSD.
ulFunc(ULONG) Set to VSD_SET.
ulFlags(ULONG) The following flags can be used with VSD_SET.
VSD_SETAUDIOATTRIBUTES See VSD_SETAUDIOATTRIBUTES
VSD_SETCONNECTOR See VSD_SETCONNECTOR
VSD_SETDATATYPE See VSD_SETDATATYPE
VSD_SETMIXCONNECTIONS See VSD_SETMIXCONNECTIONS
VSD_SETMIXCONTROL See VSD_SETMIXCONTROL
VSD_SETMONITOR See VSD_SETMONITOR
VSD_SETVOLUME See VSD_SETVOLUME
pRequest(PVOID) Pointer value varies according to the value of ulFlags.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_INVALID_HVSD The hvsd(VSD handle) is not valid. Verify that the hvsdmatches the one provided on the VSD_OPEN.
VSD_SET - Remarks
This messages uses flags to specify what to set on the adapter.
VSD_SET - Topics
Select an item:
Syntax Returns Remarks Glossary
VSD_SETAUDIOATTRIBUTES
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand sets the audio attribute settings. A valid length must be placed in the ulLengthfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure. The audio setting to modify (such as treble, bass, and so on) must be placed in the ulFlagsfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure with the actual corresponding setting in the ulValuefield. The value should be between 0 and 100. The ulDelayindicates the length of time over which this effect should take place.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_SET.
ulFlags(ULONG) Set to VSD_SETAUDIOATTRIBUTES.
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_SETAUDIOATTRIBUTES Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETAUDIOATTRIBUTES Parameter - ulFunc
ulFunc(ULONG) Set to VSD_SET.
VSD_SETAUDIOATTRIBUTES Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETAUDIOATTRIBUTES.
VSD_SETAUDIOATTRIBUTES Parameter - pRequest
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
VSD_SETAUDIOATTRIBUTES Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_SETAUDIOATTRIBUTES - Syntax
This subcommand of the VSD_SETcommand sets the audio attribute settings. A valid length must be placed in the ulLengthfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure. The audio setting to modify (such as treble, bass, and so on) must be placed in the ulFlagsfield of the VSD_ AUDIOATTRIBUTES_PARMSstructure with the actual corresponding setting in the ulValuefield. The value should be between 0 and 100. The ulDelayindicates the length of time over which this effect should take place.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFunc(ULONG) Set to VSD_SET.
ulFlags(ULONG) Set to VSD_SETAUDIOATTRIBUTES.
pRequest(PVSD_AUDIOATTRIBUTES_PARMS) Pointer to the VSD_AUDIOATTRIBUTES_ PARMSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSD_SETAUDIOATTRIBUTES - Example Code
The following code illustrates how to set audio attribute information.
VSD_AUDIOATTRIBUTES_PARMS vsdAttr;
/* Prime the structure with necessary values */
vsdAttr.ulLength = sizeof (VSD_AUDIOATTRIBUTES_PARMS);
vsdAttr.ulFlags = VSD_BASS;
vsdAttr.ulValue = 100;
/*---------------------------------------------
* Ask the VSD to either set or query an audio
* attribute. The caller determines whether
* to set or query via the command variable.
*---------------------------------------------*/
rc = pInstance->pfnAUDIOIF((HVSD)pInstance->hvsd,
VSD_SET,
VSD_SETAUDIOATTRIBUTES,
(PVOID)&vsdAttr);
VSD_SETAUDIOATTRIBUTES - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETCONNECTOR
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand enables or disables a connector. (A connector can be a hardware or software connection on the device the VSD is controlling.) Note that enabling a connector can by default, disable another connector. For further information regarding connectors, refer to the MCI_CONNECTOR command in the OS/2 Multimedia Programming Reference. Additional connectors can be found in MCIOS2.H.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETCONNECTOR.
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the fEnabledfield. A valid connector must be placed in the ulConn_Typefield and a valid index in the ulIndexfield.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.
VSDERR_INVALID_CONNECTOR Connector setting is invalid.
VSD_SETCONNECTOR Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETCONNECTOR Parameter - ulFunc
VSD_SETCONNECTOR Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETCONNECTOR.
VSD_SETCONNECTOR Parameter - pRequest
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the fEnabledfield. A valid connector must be placed in the ulConn_Typefield and a valid index in the ulIndexfield.
VSD_SETCONNECTOR Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.
VSDERR_INVALID_CONNECTOR Connector setting is invalid.
VSD_SETCONNECTOR - Syntax
This subcommand of the VSD_SETcommand enables or disables a connector. (A connector can be a hardware or software connection on the device the VSD is controlling.) Note that enabling a connector can by default, disable another connector. For further information regarding connectors, refer to the MCI_CONNECTOR command in the OS/2 Multimedia Programming Reference. Additional connectors can be found in MCIOS2.H.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETCONNECTOR.
pRequest(PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMSstructure.
The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the fEnabledfield. A valid connector must be placed in the ulConn_Typefield and a valid index in the ulIndexfield.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_UNSUPPORTED_CONNECTOR Connector setting is not supported.
VSDERR_INVALID_CONNECTOR Connector setting is invalid.
VSD_SETCONNECTOR - Example Code
The following code illustrates how to set the state of the connector.
HVSD hvsd;
VSD_CONNECTOR_PARMS vsdConn;
vsdConn.ulConn_Type = pConnector->ulConnectorType;
vsdConn.ulIndex = pConnector->ulConnectorIndex;
vsdConn.fEnabled = VSD_DISABLE;
/*--------------------------------------------------
* Tell the VSD that we want to disable a connector.
*--------------------------------------------------*/
lError = pInstance->pfnNewVSD(hvsd,
VSD_SET,
VSD_SETCONNECTOR,
(PVOID)&vsdConn);
VSD_SETCONNECTOR - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETDATATYPE
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand sets the current data type that the device is dealing with.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETDATATYPE.
pRequest(PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_ PARMSstructure.
Note:Every field in the VSD_AUDIODATATYPE_PARMSstructure contains a numeric value except for ulOperation. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ulBlockAlignment, ulDataSubType, and ulAverageBytesPerSecfields in the VSD_AUDIODATATYPE_PARMSstructure.
The ulFlagsfield of the VSD_AUDIODATATYPE_PARMSstructure contains a flag for each field in the structure that can be set. Every field has a flag except for the ulOperationfield. The ulOperationfield is valid for every call.
The VSD_AUDIODATATYPE_PARMSstructure must contain at least one of the following flags:
�VSD_MODE
�VSD_CHANNELS
�VSD_SAMPLESPERSEC
�VSD_OPERATION
�VSD_BITSPERSAMPLE
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SETDATATYPE Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETDATATYPE Parameter - ulFunc
VSD_SETDATATYPE Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETDATATYPE.
VSD_SETDATATYPE Parameter - pRequest
pRequest(PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_ PARMSstructure.
Note:Every field in the VSD_AUDIODATATYPE_PARMSstructure contains a numeric value except for ulOperation. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ulBlockAlignment, ulDataSubType, and ulAverageBytesPerSecfields in the VSD_AUDIODATATYPE_PARMSstructure.
The ulFlagsfield of the VSD_AUDIODATATYPE_PARMSstructure contains a flag for each field in the structure that can be set. Every field has a flag except for the ulOperationfield. The ulOperationfield is valid for every call.
The VSD_AUDIODATATYPE_PARMSstructure must contain at least one of the following flags:
�VSD_MODE
�VSD_CHANNELS
�VSD_SAMPLESPERSEC
�VSD_OPERATION
�VSD_BITSPERSAMPLE
VSD_SETDATATYPE Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SETDATATYPE - Syntax
This subcommand of the VSD_SETcommand sets the current data type that the device is dealing with.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETDATATYPE.
pRequest(PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_ PARMSstructure.
Note:Every field in the VSD_AUDIODATATYPE_PARMSstructure contains a numeric value except for ulOperation. This field contains either VSD_ PRODUCE for recording or VSD_CONSUME for playback. The VSD is responsible for filling in the ulBlockAlignment, ulDataSubType, and ulAverageBytesPerSecfields in the VSD_AUDIODATATYPE_PARMSstructure.
The ulFlagsfield of the VSD_AUDIODATATYPE_PARMSstructure contains a flag for each field in the structure that can be set. Every field has a flag except for the ulOperationfield. The ulOperationfield is valid for every call.
The VSD_AUDIODATATYPE_PARMSstructure must contain at least one of the following flags:
�VSD_MODE
�VSD_CHANNELS
�VSD_SAMPLESPERSEC
�VSD_OPERATION
�VSD_BITSPERSAMPLE
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSD_SETDATATYPE - Example Code
The following code illustrates how to set the data type, sampling rate, channels, and bits per sample for an audio VSD.
HVSD hvsd;
VSD_AUDIODATATYPE_PARMS AudioDatatype;
PMMAUDIOHEADER pmmaudioheader;
AudioDatatype.ulDataType = pmmaudioheader->mmXWAVHeader.WAVEHeader.usFormatTag;
AudioDatatype.ulBitsPerSample = pmmaudioheader->mmXWAVHeader.WAVEHeader.usBitsPerSample;
AudioDatatype.ulSamplingRate = pmmaudioheader->mmXWAVHeader.WAVEHeader.usSamplesPerSec;
AudioDatatype.ulChannels = pmmaudioheader->mmXWAVHeader.WAVEHeader.usChannels;
AudioDatatype.ulOperation = VSD_PLAY;
AudioDatatype.ulFlags = VSD_MODE|VSD_CHANNELS|VSD_SAMPLESPERSEC|
VSD_OPERATION|VSD_BITSPERSAMPLE;
rc = pInstance->pfnNewVSD(hvsd,
VSD_SET,
VSD_SETDATATYPE,
(PVOID)&AudioDatatype);
if(rc)
{
return(rc)
}
VSD_SETDATATYPE - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETMIXCONNECTIONS
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand routes the audio output of a connector to a particular output circuitry (that is, pass thru, internal mixer circuitry, and so on). For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMIXCONNECTIONS.
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
The caller must fill in the ulConnectionsand the ulLinefields of the LINECONNECTIONSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONNECTIONS Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETMIXCONNECTIONS Parameter - ulFunc
VSD_SETMIXCONNECTIONS Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETMIXCONNECTIONS.
VSD_SETMIXCONNECTIONS Parameter - pRequest
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
The caller must fill in the ulConnectionsand the ulLinefields of the LINECONNECTIONSstructure.
VSD_SETMIXCONNECTIONS Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONNECTIONS - Syntax
This subcommand of the VSD_SETcommand routes the audio output of a connector to a particular output circuitry (that is, pass thru, internal mixer circuitry, and so on). For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMIXCONNECTIONS.
pRequest(PLINECONNECTIONS) A pointer to the LINECONNECTIONSstructure.
The caller must fill in the ulConnectionsand the ulLinefields of the LINECONNECTIONSstructure.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONNECTIONS - Example Code
The following code illustrates how to route the output of a connector to the internal mixer circuitry.
LINECONNECTIONS mixinfo;
mixinfo.ulLine = SOURCE_SYNTHESIZER;
mixinfo.ulConnection = SINK_SPEAKER;
rc = pInstance->((HVSD)pInstance->hvsd,
VSD_SET,
VSD_SETMIXCONNECTIONS,
(PVOID)&mixinfo);
return(rc);
VSD_SETMIXCONNECTIONS - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETMIXCONTROL
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand enables an application to set the current state of a particular line. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMIXCONTROL.
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
The ulControlfield of the MIXERCONTROLstructure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting 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. The ulLinefield must also be filled in.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONTROL Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETMIXCONTROL Parameter - ulFunc
VSD_SETMIXCONTROL Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETMIXCONTROL.
VSD_SETMIXCONTROL Parameter - pRequest
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
The ulControlfield of the MIXERCONTROLstructure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting 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. The ulLinefield must also be filled in.
VSD_SETMIXCONTROL Return Value - rc
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONTROL - Syntax
This subcommand of the VSD_SETcommand enables an application to set the current state of a particular line. For further information about VSD mixer support and functions, see Audio Sample for Vendor-Specific Driversand Mixer IOCtl Functions Introduction
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMIXCONTROL.
pRequest(PMIXERCONTROL) A pointer to the MIXERCONTROLstructure.
The ulControlfield of the MIXERCONTROLstructure must be filled in with the desired setting. For stereo controls, the high-order word of this field contains the left channel setting 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. The ulLinefield must also be filled in.
rc(ULONG) Error code indicating success or the type of failure:
VSDERR_MISSING_PARAMETER One or more parameters are missing.
VSDERR_INVALID_SOURCE Invalid source.
VSDERR_INVALID_SINK Invalid sink.
VSDERR_INVALID_CONNECTION Invalid connection.
VSD_SETMIXCONTROL - Example Code
The following code illustrates how to query the settings of an audio attributes for a particular connector.
MIXERCONTROL MixerControl;
USHORT usBass;
MixerControl.ulControl = MIX_SUPPORT_VOLUME;
MixerControl.ulLine = SINK_LINE_OUT;
MixerControl.ulSetting = 100;
lError = pInstance->((HVSD)pInstance->hvsd,
VSD_SET,
VSD_SETMIXCONTROL,
(PVOID)&MixerControl);
return(lError);
VSD_SETMIXCONTROL - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETMONITOR
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMONITOR.
pRequest(PULONG) Input. Set to MCI_TRUE or MCI_FALSE.
rc(ULONG) Error code indicating success.
VSDERR_SUCCESS The command was successful.
VSD_SETMONITOR Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETMONITOR Parameter - ulFunc
VSD_SETMONITOR Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETMONITOR.
VSD_SETMONITOR Parameter - pRequest
pRequest(PULONG) Input. Set to MCI_TRUE or MCI_FALSE.
VSD_SETMONITOR Return Value - rc
rc(ULONG) Error code indicating success.
VSDERR_SUCCESS The command was successful.
VSD_SETMONITOR - Syntax
This subcommand of the VSD_SETcommand enables (MCI_TRUE) or disables (MCI_ FALSE) the audio monitor feature of the device.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETMONITOR.
pRequest(PULONG) Input. Set to MCI_TRUE or MCI_FALSE.
rc(ULONG) Error code indicating success.
VSDERR_SUCCESS The command was successful.
VSD_SETMONITOR - Example Code
The following code illustrates how to set the state of the VSD monitor.
ULONG ulSetOn;
ulSetOn = MCI_TRUE;
/* Tell the VSD to change monitor status */
lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
VSD_SET,
VSD_SETMONITOR,
(PVOID)lSetOn);
VSD_SETMONITOR - Topics
Select an item:
Syntax Returns Example Code Glossary
VSD_SETVOLUME
Select an item:
Syntax Returns Example Code Glossary
This subcommand of the VSD_SETcommand sets the volume level as a percentage (0 - 100). If the value is not one of the supported volume levels, it is rounded up to the nearest supported level. The ulFlagsfield indicates which fields are to be used.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETVOLUME.
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
The caller must fill in the ulVolumefield if VSD_VOLUME is specified. The caller must fill in the ulMasterAudiofield if VSD_MASTERVOLUME is specified. The caller must fill in the fMutefield with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.
rc(ULONG) Error codes indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_VOL_OUT_OF_RANGE Invalid volume level.
VSD_SETVOLUME Parameter - hvsd
hvsd(HVSD) Handle to a VSD.
VSD_SETVOLUME Parameter - ulFunc
VSD_SETVOLUME Parameter - ulFlags
ulFlags(ULONG) Set to VSD_SETVOLUME.
VSD_SETVOLUME Parameter - pRequest
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
The caller must fill in the ulVolumefield if VSD_VOLUME is specified. The caller must fill in the ulMasterAudiofield if VSD_MASTERVOLUME is specified. The caller must fill in the fMutefield with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.
VSD_SETVOLUME Return Value - rc
rc(ULONG) Error codes indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_VOL_OUT_OF_RANGE Invalid volume level.
VSD_SETVOLUME - Syntax
This subcommand of the VSD_SETcommand sets the volume level as a percentage (0 - 100). If the value is not one of the supported volume levels, it is rounded up to the nearest supported level. The ulFlagsfield indicates which fields are to be used.
This command is sent using VSDEntryas follows:
VSDEntry(hvsd, ulFunc, ulFlags, pRequest)
hvsd(HVSD) Handle to a VSD.
ulFlags(ULONG) Set to VSD_SETVOLUME.
pRequest(PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMSstructure.
The caller must fill in the ulVolumefield if VSD_VOLUME is specified. The caller must fill in the ulMasterAudiofield if VSD_MASTERVOLUME is specified. The caller must fill in the fMutefield with a boolean if VSD_ MUTE is specified. TRUE mutes the device; FALSE unmutes the device.
rc(ULONG) Error codes indicating success or the type of failure:
VSDERR_SUCCESS The command was successful.
VSDERR_VOL_OUT_OF_RANGE Invalid volume level.
VSD_SETVOLUME - Example Code
The following code illustrates how to set the volume on an audio VSD.
VSD_VOLUME_PARMS vsdVol;
vsdVol.ulVolume = pInstance->ulVolume;
vsdVol.ulMasterAudio = pInstance->ulMasterVolume;
vsdVol.fMute = pInstance->fMute;
vsdVol.ulVectoredVolume = pInstance->ulTime;
vsdVol.ulFlags = VSD_VOLUME | VSD_MASTERVOLUME;
lError = prInstance->pfnAUDIOIF((HVSD)prInstance->pMix->hvsd
VSD_SET,
VSD_SETVOLUME,
(PVOID)&vsdVol);
VSD_SETVOLUME - Topics
Select an item:
Syntax Returns Example Code Glossary
IOCtl Functions
OS/2 device drivers are used to access the I/O hardware. The IOCtlfunctions 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 notfor passing audio data from an MMPM/2 application to the PDD. The preferred method of passing audio data is for the application to issue playand recordcommands 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 Messagesand 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
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_INIT (40h)
Description:
Initialize Audio Device Driver
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
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_INITfields to the desired values and calling AUDIO_ INIT.
AUDIO_INIT (40h) - Description
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_INITfields 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 structureThe 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_INITfields with the supported values that most closely approximate the values specified by the user, sets the BESTFIT _PROVIDED bit in ulFlags, and returns 0to the application.
Refer to the OS/2 Control Program Guide and Referencefor 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_INITstructure 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 appearto 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 sReturnCodefield.
Note:It is critical that the application check the returned ulFlagsand sReturnCodefields 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_INIT (40h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_INIT (40h)
Description:
Initialize Audio Device Driver
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
AUDIO_STATUS (41h) - Obtain Status of Audio Hardware
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_STATUS (41h)
Description:
Obtain Status of Audio Hardware
Select an item:
Description Parameter Packet Format Data Packet Format Returns
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) - Description
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 ulFlagsof the MCI_AUDIO_STATUSstructure. The MCI_AUDIO_CHANGEdata structure contains the current input, output, monitor, volume, balance, and tone control settings.
Refer to the OS/2 Control Program Guide and Referencefor more information on the return code for DosDevIOCtl.
AUDIO_STATUS (41h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_STATUS (41h)
Description:
Obtain Status of Audio Hardware
Select an item:
Description Parameter Packet Format Data Packet Format Returns
AUDIO_CONTROL (42h) - Control Audio Adapter
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_CONTROL (42h)
Description:
Control Audio Adapter
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The adapter stateis 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 characteristicsare changed by the usIOCtlRequestvalue AUDIO_ CHANGE.
AUDIO_CONTROL (42h) - Description
This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The adapter stateis 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 characteristicsare changed by the usIOCtlRequestvalue AUDIO_ CHANGE.
AUDIO_CONTROL (42h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_CONTROL (42h) - Pointer to structure
Pointer to structureThe 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, sReturnCodeis set and an error returned.
Refer to the OS/2 Control Program Guide and Referencefor 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_INITis issued.
AUDIO_CONTROL (42h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_CONTROL (42h)
Description:
Control Audio Adapter
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
AUDIO_BUFFER (43h) - Determine Buffer Status
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_BUFFER (43h)
Description:
Determine Buffer Status
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
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 onin the ulFlagsfield.
AUDIO_BUFFER (43h) - Description
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 onin the ulFlagsfield.
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 ulReadBufTimeand 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 ulReadBufMaxand 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_BUFFER (43h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_BUFFER (43h)
Description:
Determine Buffer Status
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
AUDIO_LOAD (44h) - Load DSP Code
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_LOAD (44h)
Description:
Load DSP Code
Select an item:
Description Parameter Packet Format Data Packet Format Remarks
If the LOAD_CODE bit is set in the ulFlagsfield of the MCI_AUDIO_INITstructure on an AUDIO_INITrequest, the application must load the DSP code (specified by the device driver in the abLoadPathfield of MCI_AUDIO_INIT) into a buffer and issue an AUDIO_LOAD IOCtl request.
AUDIO_LOAD (44h) - Description
If the LOAD_CODE bit is set in the ulFlagsfield of the MCI_AUDIO_INITstructure on an AUDIO_INITrequest, the application must load the DSP code (specified by the device driver in the abLoadPathfield 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 pbBufferfield of the MCI_AUDIO_LOADstructure must point to the start of the buffer where the code is loaded. The ulSizefield must be set to the number of bytes of loaded code (which is the size of the file). The ulFlagsfield 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_LOAD (44h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_LOAD (44h)
Description:
Load DSP Code
Select an item:
Description Parameter Packet Format Data Packet Format Remarks
AUDIO_WAIT (45h) - Suspend program operation
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_WAIT (45h)
Description:
Suspend program operation
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
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) - Description
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 Referencefor 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_WAIT (45h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_WAIT (45h)
Description:
Suspend program operation
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
AUDIO_HPI (46h) - Access high-performance interface
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_HPI (46h)
Description:
Access high-performance interface
Select an item:
Description Parameter Packet Format Data Packet Format Returns
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) - Description
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 structureThe 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_HPIstructure 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_HPI (46h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_HPI (46h)
Description:
Access high-performance interface
Select an item:
Description Parameter Packet Format Data Packet Format Returns
AUDIO_UPDATE (47h) - Update Buffer Information
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_UPDATE (47h)
Description:
Update Buffer Information
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
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_IOBUFFERdata 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_updatestructure.
AUDIO_UPDATE (47h) - Description
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_IOBUFFERdata 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_updatestructure.
AUDIO_UPDATE (47h) - Parameter Packet Format
Not used. The packet pointer must be NULL.
AUDIO_UPDATE (47h) - Pointer to structure
Pointer to structureThe 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, rcof the audio_updatestructure 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 Referencefor 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_HPIcalls the device driver, an MCI_AUDIO_IOBUFFERstructure with the maximum number of buffers that can be present must be passed. The iobuf->num_buffersfield 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 _IOBUFFERstructure 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_buffersto this number. All internal variables are initialized to allow access to that number of buffers. AUDIO_ HPImust be called again if this number changes.
When AUDIO_UPDATE is called, it removes all buffers in the current MCI_ AUDIO_IOBUFFERbuffer array that have been processed. It then recalculates iobuf->num_buffersand 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_IOBUFFERstructure to be updated is to be transmitted, it is assumed that the buffer passed is full of data to be played. The pHeadpointer is updated to point to the beginning of the buffer following the buffer just added to the chain. The lCountfield is also updated by the device driver to include this buffer of data.
If buffer_addressis 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_UPDATE (47h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_UPDATE (47h)
Description:
Update Buffer Information
Select an item:
Description Parameter Packet Format Data Packet Format Returns Remarks
AUDIO_CAPABILITY (48h) - Determine If a Group of Audio Settings is Supported
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_CAPABILITY (48h)
Description:
Determine If a Group of Audio Settings is Supported
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code Remarks
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) - Description
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 structureThe 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 ulDataTypefields of the MCI_AUDIO_CAPSstructure must be filled in by the caller. The device driver will return SUPPORT_SUCCESS in the ulSupportfield if it supports the combination and non-zeroif it does not. If SUPPORT_SUCCESS is returned, the driver must also fill in the following fields of the MCI_ AUDIO_CAPSstructure:
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 ulSupportcontains a non-zero value, the driver should fill in the MCI_ AUDIO_CAPSstructure 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 RESOURCECLASSESindicates 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 RESOURCEUNITSindicates 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 VALIDCOMBINATIONSinforms 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.
AUDIO_CAPABILITY (48h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
AUDIO_CAPABILITY (48h)
Description:
Determine If a Group of Audio Settings is Supported
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code Remarks
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
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETCONNECTIONS (60h)
Description:
Determine if Line is Enabled
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
This IOCtl enables an application to determine if a particular mixer line is enabled.
MIX_GETCONNECTIONS (60h) - Description
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 ulLinefield of the LINECONNECTIONSstructure.
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 ulConnectionswill 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_GETCONNECTIONS (60h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_GETCONNECTIONS (60h)
Description:
Determine if Line is Enabled
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
MIX_SETCONNECTIONS (61h) - Connect an Input Line to an Output Line
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_SETCONNECTIONS (61h)
Description:
Connect an Input Line to an Output Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
This IOCtl enables an application to connect an input line to an output line.
MIX_SETCONNECTIONS (61h) - Description
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 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 ulLineand ulConnectionsfields of the LINECONNECTIONSstructure.
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_SETCONNECTIONS (61h) -
Category:
AUDIO_IOCTL_CAT (80h)
Function:
MIX_SETCONNECTIONS (61h)
Description:
Connect an Input Line to an Output Line
Select an item:
Description Parameter Packet Format Data Packet Format Returns Example Code
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 ulLinefield of the MIXERLINEINFOstructure.
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 MIXERCONTROLstructure.
The device driver should return the current setting of the line in the ulSettingfield of the MIXERCONTROLstructure. 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 MIXERCONTROLstructure. 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_FORMATand/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_FORMATand/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_PLAYIOCtl.
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_PLAYIOCtl.
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_GETIMAGESCALEand on the SHD_READ_COMPLETE flag (of the ulFlagparameter of the SHD_REPORTINTstructure) 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_GETIMAGESCALEand on the SHD_READ_COMPLETE flag (of the ulFlagparameter of the SHD_REPORTINTstructure) 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_FORMATIOCtl and the source and destination image size is determined by the VCAI_SETCAPTRECTIf the device supports this command, the CanRestoreflag in the VCADEVINFOstructure 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_FORMATIOCtl and the source and destination image size is determined by the VCAI_SETCAPTRECTIf the device supports this command, the CanRestoreflag in the VCADEVINFOstructure 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 VCADEVINFOstructure.
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 VCADEVINFOstructure.
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_READmessage. 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 DDCMDCONTROLstructure.
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_PLAYIOCtl.
VCAI_SETCAPTRECT (6Bh) - Description
This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the DDCMD_READmessage. 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 DDCMDCONTROLstructure.
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_PLAYIOCtl.
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
MMPM/2 Device Driver Reference:Data Types
MMPM/2 Device Driver Reference:Types of MIDI Messages
Addendums
OS/2 Version Compatibility Considerations
The following table lists items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.
| Item Added or Changed | Date Item Added or Changed | Compatibility of Addition or Change |
|---|---|---|
| MIDI Driver | November 1995 | OS/2 Warp, Version 3.0 and Later |
| Timer Device Driver | November 1995 | OS/2 Warp, Version 3.0 and Later |
| VSD Updates | November 1995 | OS/2 Warp, Version 3.0 and Later |
MMPM/2 Device Driver Reference:Notices
MMPM/2 Device Driver Reference:Glossary
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation