═══ 1. Notices ═══ Fourth Edition (April 1995) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM authorized reseller or IBM marketing representative. ═══ 1.1. Copyright Notices ═══ COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface. Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved." (C) Copyright International Business Machines Corporation 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 1.2. Disclaimers ═══ References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 1.3. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries: IBM Multimedia Presentation Manager/2 OS/2 Ultimotion The following terms are trademarks of other companies: Helvetica Linotype Company MASM Microsoft Corporation Mitsumi Mitsumi Denki Kabushki Kaisha Panasonic Matsushita Electric Industrial Co., Ltd. OPTi OPTi, Inc. Pioneer Pioneer Electric Corporation ProAudio Spectrum Media Vision, Inc. ProAudio Spectrum 16 Media Vision, Inc. QuickVia Jovian Logic Corp. ReelMagic Sigma Designs, Inc. Sound Blaster Creative Technology Ltd. SuperVia Jovian Logic Corp. Super VideoWindows New Media Graphics Corporation Video Blaster Creative Technology, Inc. Yamaha Yamaha Corporation Windows is a trademark of Microsoft Corporation. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others. ═══ 2. About This Book ═══ The MMPM/2 Device Driver Reference 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 (MMPM/2) system. Note: Multimedia Presentation Manager/2 (or MMPM/2) is also referred to as OS/2 Multimedia. The IBM Developer Connection Device Driver Kit for OS/2 provides PDD and VDD source code, which serves as a template that can be modified easily to meet your hardware requirements. Tools to test your device drivers are also available. ═══ 2.1. Summary of Changes ═══ Following is a list of the changes made to the MMPM/2 Device Driver Reference (Third Edition) since it was provided in online format in October 1994. o MPEG driver documenation was added. o MAD16 driver documentation was added. o A DDCMD/VSD state diagram and information about device states was added. o Information about 0 length buffers was added to DDCMD_READ and DDCMD_WRITE. o VSD_INSERTSETTINGSPAGE was added. ═══ 2.2. 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 -(10G6266) 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 - (10G6310) 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. ═══ 2.3. Using the Online Reference ═══ Before you begin to use this reference, it would be helpful to understand how you can: o Expand the Contents to see all available topics o Obtain additional information for a highlighted word or phrase o 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: 1. Select a topic from the Contents. 2. When that topic appears, choose the Bookmark option from the Services menu. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Select the Place radio button (or press the Up or Down Arrow key to select it). 5. 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: 1. Choose the Search option from the Services pull-down. 2. Type the word or words to be searched. 3. Select All sections. 4. Select Search to begin the search. 5. The list of topics where the word or phrase appears is displayed. Print 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: 1. Select Print from the Services menu. 2. Select Contents. 3. Select Print. 4. 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: 1. Expand the Contents list and select a topic. 2. 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. ═══ 2.4. Assistance ═══ Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE." You are encouraged to use the DUDE 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 DUDE, dial 407-982-3217 (using a modem) to register and access the support system. For voice support in the United States, call 407-982-4239. Additional assistance is available through the IBM Developer Assistance Program. For membership information: Telephone: 407-982-6408 Fax: 407-988-7610 (U.S.A.) or Fax: 407-982-4259 (worldwide) ═══ 2.5. Ordering Information ═══ For an illustration of OS/2 Technical Publications and other related product documents, see the following figure. The IBM Developer Connection Device Driver Kit for OS/2 on CD-ROM contains actual source code for sample device drivers, as well as the complete text of the books in online form. To order any of the publications shown in the illustration, call: ┌────────────────────┬─────────────────────┬─────────────────────┐ │U.S.A.: │1-800-633-8266 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Canada: │1-800-561-5293 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Europe, Middle East,│ English language │(+45) 48101500 │ │Africa, and │ French language │(+45) 48101200 │ │Latin America: │ Italian language │(+45) 48101600 │ │ │ German language │(+45) 48101000 │ │ │ Spanish language │(+45) 48101100 │ │ │ Dutch language │(+45) 48101400 │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Asia/Pacific: │ All except Japan │(61) 2-354-7684 │ │ │ Japan │(81) 3-3495-2045(Fax)│ │ │ │Fax request to: │ │ │ │DAP-J, IBM Japan │ ├────────────────────┼─────────────────────┼─────────────────────┤ │SE Brazil: │(021) 800-6120(Voice)│ │ │ │(021) 800-6936(Fax) │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Mexico: │ Mexico City │627-2444 │ │ │ Country │91-800-00639 │ └────────────────────┴─────────────────────┴─────────────────────┘ ═══ 3. 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: o Specifying parameters in a resource file (.RC). The resource file is compiled to create the resource DLL. o Modifying control files that tell MINSTALL how to install your adapter. o 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. For additional information about adding support for an audio adapter, see Audio Adapter Installation or for adding support for a video adapter, see Video Adapter Installation. ═══ 3.1. 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: o Asks the user for any information needed to install your adapter, such as the interrupt level. o Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements. o Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver. o 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. ═══ 3.1.1. 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. ═══ 3.1.2. 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. ═══ 3.1.3. 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: 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). ═══ 3.1.3.1. Resource File Layout ═══ The following is the format of the vendor-specific driver (VSD) resource file: BEGIN RCDATA , , , , , 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 ASCIIZ 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: o RIFF Data Type o RIFF Data Subtype o Samples per Second o Bits per Sample o Channels o Sampling Descriptions o Play Resource Class o Play Resource Units Used o Record Resource Class o 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, ═══ 3.1.4. 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 ssdllinputparms keyword 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: o The maximum number of this type of audio adapter that can be installed at one time. The maximum is six adapters. o 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. o 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". o 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". o 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. o 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$ o 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. o The name of the adapter as it is displayed to the user. o The version number of the device driver. o 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$. o The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'. o 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: o 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). o The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory. o 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. o The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD "AUDIOMCD." o The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD "AUDIOIF." o 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. o 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. o The number of resource units supported by this driver. For more information, see Resource Units and Classes. o 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. o The resource classes. For more information, see Resource Units and Classes. o The number of valid combinations of resource classes. The maximum is 81 combinations. For more information, see Resource Units and Classes. o 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. o 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. o 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. o 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. o The file-name extensions associated with this driver. o 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. o 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. o 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: o 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. o The title of the prompt text as it is displayed to the user. o The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field. o The valid answers to your prompt. These answers are displayed to the user. The user can select one. o 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". o 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 ═══ 3.1.4.1. 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 ═══ 3.1.5. 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. ═══ 3.1.6. 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. ═══ 3.1.7. 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. ═══ 3.1.8. 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 not listed 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. ═══ 3.1.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. ═══ 3.1.10. 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 uStyle field 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 uDrums10 or 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. ═══ 3.1.11. Step 10. Creating the Installation Diskette ═══ Create a diskette that contains the following files: o CONTROL.SCR o AUDFILES.SCR o MIDIMAP.SCR (if you created one) o MIDIMAP.DLL (if you created one) o CARDINFO.DLL o AUDHELP.HLP o GENIN.DLL o GENINMRI.DLL o Your device drivers ═══ 3.1.12. 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 MINSTALL on 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. ═══ 3.2. 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: o Asks the user for any information needed to install your adapter, such as the interrupt level. o Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements. o Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver. o 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. ═══ 3.2.1. 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. ═══ 3.2.2. 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. ═══ 3.2.3. 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 ssdllinputparms keyword 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: o The maximum number of this type of video adapter that can be installed at one time. The maximum is six adapters. o 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. o 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." o 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." o 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. o 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 o 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. o The name of the adapter as it is displayed to the user. o The version number of the device driver. o 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$. o The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'. o 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: o 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). o The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory. o 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. o The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD 'SVMC'. o The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD 'VIDVCI'. o 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. o 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. o The number of resource units supported by this driver. For more information, see Resource Units and Classes. o 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. o The resource classes. For more information, see Resource Units and Classes. o The number of valid combinations of resource classes. For more information, see Resource Units and Classes. o 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. o 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. o 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. o 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. o 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" o 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. o 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. o 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: o 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. o The title of the prompt text as it is displayed to the user. o The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field. o The valid answers to your prompt. These answers are displayed to the user. The user can select one. o 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." o 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 ═══ 3.2.3.1. 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 ═══ 3.2.4. 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. ═══ 3.2.5. 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. ═══ 3.2.6. 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. ═══ 3.2.7. 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. ═══ 3.2.8. 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. ═══ 3.2.9. Step 8. Creating the Installation Diskette ═══ Create a diskette that contains the following files: o CONTROL.SCR o VIDFILES.SCR o CARDINFO.DLL o VIDHELP.HLP o Your device drivers ═══ 3.2.10. 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: o OS/2 Version 2.1 (or later) o MMPM/2 o 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. ═══ 3.3. 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 ═══ 4. Audio Physical Device Driver Template ═══ This DDK provides two complete working samples for writing your own audio physical device drivers for the MMPM/2 environment. The first is the Media Vision PAS-16 sample. It is the production code for the Media Vision MMPM/2 Audio PDD. The second is IBM-written Analog Devices AD1848 Business Audio MMPM/2 Audio PDD. This sample is the production level Media Vision** code for the ProAudio Spectrum** device driver. The ProAudio Spectrum 16 driver includes all the code required for communication with MMPM/2 and the ProAudio Spectrum 16 adapter. This includes 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 Reference provided in this package. This reference describes the types of physical device drivers, their interfaces, and available system services. ═══ 4.1. Source Code for PAS-16 ═══ Source code for the ProAudio Spectrum device driver is located in the \MMOS2\MMTOOLKT\SAMPLES\PASTK subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module. ┌─────────────────────────┬───────────────────────────────────┐ │Source File │Description │ ├─────────────────────────┼───────────────────────────────────┤ │STARTUP.ASM │Sixteen-bit entry points into the │ │ │physical device driver from │ │ │external code. The PDD is written │ │ │primarily in C language, but │ │ │Assembler is required for │ │ │communication with the OS/2 kernel │ │ │or the MMPM/2 audio stream handler.│ │ │It also provides Assembler to C │ │ │language conversion for parameters │ │ │received from the OS/2 kernel or │ │ │MMPM/2 audio stream handler. │ ├─────────────────────────┼───────────────────────────────────┤ │CDEVHLP.ASM │Sixteen-bit Assembler calls to OS/2│ │ │DevHlp services from 16-bit │ │ │C-compiler code. The C file │ │ │provides callable functions that │ │ │map to OS/2 defined PDD DevHlp │ │ │function. │ ├─────────────────────────┼───────────────────────────────────┤ │MVPRODD.C │Main routines accessed through │ │ │incoming request packet IOCtls. │ ├─────────────────────────┼───────────────────────────────────┤ │AUDIODAT.C │Global data. │ ├─────────────────────────┼───────────────────────────────────┤ │AUDSUBS.C │Various device specific │ │ │subroutines. │ ├─────────────────────────┼───────────────────────────────────┤ │AUDINTR.C │Interrupt handler routines with │ │ │support code to call back to the │ │ │stream handler through the IDC. │ ├─────────────────────────┼───────────────────────────────────┤ │AUDIOVDM.C │Support routines for VDD-PDD │ │ │communication (for example, DOS │ │ │serialization support). The │ │ │PDDInternalEntryPoint() routine is │ │ │called through the IDC from the │ │ │virtual device driver. │ │ │The VDMInterruptTime() routine is │ │ │called at hardware interrupt time. │ │ │The PDD calls the VDD so that it │ │ │can virtualize the interrupt for │ │ │the VDM. │ │ │The CallVDD() function is in │ │ │STARTUP.ASM. │ ├─────────────────────────┼───────────────────────────────────┤ │MMDDCMDS.C │Main routines for incoming stream │ │ │handler requests through the IDC. │ │ │This function is called from the │ │ │STARTUP.ASM file and receives │ │ │control from the MMPM/2 Stream │ │ │Handler. Based on the DDCMD, the │ │ │appropriate sub-function is called.│ ├─────────────────────────┼───────────────────────────────────┤ │COMMDBG.C │Routines to send debug information │ │ │to COM: ports during execution of │ │ │device driver. The routines provide│ │ │'C' printf like functions that send│ │ │their output to the serial port │ │ │rather than stdout. The calls to │ │ │these routines are only called for │ │ │debug versions of the driver. See │ │ │the DEBUG.H file for flags to turn │ │ │on or off different debug options. │ ├─────────────────────────┼───────────────────────────────────┤ │GLOBALS.C │Variables global to execution of │ │ │device driver. GLOBALS.C includes │ │ │variables for indexing stream │ │ │buffers and pointers for │ │ │calculating stream position. │ ├─────────────────────────┼───────────────────────────────────┤ │INITC.C │Hardware initialization functions. │ ├─────────────────────────┼───────────────────────────────────┤ │PARSE.C │Parses the command line arguments │ │ │from the CONFIG.SYS command line. │ │ │This code is discarded from the │ │ │device driver after it is invoked. │ │ │Parameters switches can be │ │ │uppercase or lowercase. The '-' │ │ │character is not supported. │ ├─────────────────────────┼───────────────────────────────────┤ │ANLDIV.ASM │Implements a C callable routine for│ │ │a long divide. This implementation │ │ │prevents using the C runtime │ │ │routine. │ ├─────────────────────────┼───────────────────────────────────┤ │ANLMUL.ASM │Assembler multiplication routines. │ │ │This file implements a C callable │ │ │routine for long multiplication. │ │ │This implementation prevents using │ │ │the C runtime routine │ ├─────────────────────────┼───────────────────────────────────┤ │ANNALDIV.ASM │Implements the /= function for C │ │ │language. │ ├─────────────────────────┼───────────────────────────────────┤ │ANNALMUL.ASM │Implements the *= function for 'C'.│ └─────────────────────────┴───────────────────────────────────┘ The following files are specific to the ProAudio Spectrum adapter: o 2OP_CDRM.C o 4_CMP_P.C o ADLIB.C o ASSIGN2.C o CMP_DRUM.C o DO.C o FINDPAS.C o FMMAIN.C o FMPARSE.C o MIXINITC.C o MIXSUBS.C o MVMIX.C o MVMIXER.C o NAMEDAT.C o NAMER.C o OUTCHIP.C o PATCHER.C o INITA.ASM o MIDIA.ASM o MVMIXA.ASM o MVSOUND.ASM ═══ 4.2. Source Code for AD1848 PDD ═══ Source code for the AD1848 device driver is located in the \MMOS2\MMTOOLKT\SAMPLES\PASTK 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. │ ├─────────────────────────┼───────────────────────────────────┤ │ECHO.C │This file contains functions that │ │ │interface with the ECHO personal │ │ │sound system asic. │ ├─────────────────────────┼───────────────────────────────────┤ │HEADER.C │This file contains device driver │ │ │header information and routines. │ ├─────────────────────────┼───────────────────────────────────┤ │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. │ ├─────────────────────────┼───────────────────────────────────┤ │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 │ │ │stea 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 4.3. PDD Architecture ═══ The MMPM/2 audio PDD is a standard OS/2 PDD. Audio PDDs communicate with MMPM/2 via strategy entry point and via Inter-Device Driver Communication (IDC) Interface. These interfaces provide the foundation for sharing of the audio device by MMPM/2 applications and media drivers. The audio IOCtl interface is 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 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 imitated 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 the audio device. The following graphic shows the audio physical device driver architecture. The IDC Interface Two entry points are provided for the two device drivers participating in the IDC interface, DDCMDEntryPoint and SHDEntryPoint. DDCMDEntryPoint allows the stream handler device driver to call to the PDD, and SHDEntryPoint allows 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. Communication to the PDD DDCMD Messages are 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 SHDEntryPoint contains 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_INT The 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_EVENT The 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_CONTROL message, 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_CONTROL has 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: o 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. o 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. ═══ 4.4. 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 buffers to 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. ═══ 4.5. 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 hStream and ulSysFileNum. The hStream comes from the stream handler during stream registration while the ulSysFileNum comes 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 │ │ │ │ └────────┴────────┴──────┴─────┴───────┘ ═══ 4.6. Roadmaps ═══ The following figures illustrate the routines and IOCtls included in the audio physical device driver files. ═══ 4.6.1. STARTUP.ASM ═══ STARTUP.ASM File ┌─────────────────────┐ OS/2 IOCtls ────────── │ AUDIODD.C │ │ │ Stream Handler IDC ─── │ MMDDCMDS.C │ │ │ VDD IDC ────────────── │ AUDIOVDM.C │ │ │ VDD ──────────────── │ CallVDD() │ └─────────────────────┘ ═══ 4.6.2. 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() │ └──────────────────────────────────────────┘ ═══ 4.6.3. MMDDCMDS.C ═══ MMDDCMDS.C File ┌──────────────────────────────────────────┐ │ DDCMDInternalEntryPoint() │ │ │ │ │ ├─ DDCMDSetup() │ │ ├─ DDCMDRead() │ │ ├─ DDCMDWrite() │ │ ├─ DDCMDStatus() │ │ ├─ DDCMDControl() │ │ ├─ DDCMDRegister() │ │ └─ DDCMDDeRegister() │ │ │ │ GetStreamEntry() │ └──────────────────────────────────────────┘ ═══ 4.6.4. AUDIOVDM.C ═══ AUDIOVDM.C File ┌──────────────────────────────────────────┐ │ PDDInternalEntryPoint() │ │ │ │ VDMInterruptTime () │ │ │ │ │ └─ CallVDD() │ │ │ │ VDMClose() │ │ │ │ │ └─ CallVDD() │ └──────────────────────────────────────────┘ ═══ 4.6.5. AUDINTR.C ═══ AUDINTR.C File ┌─────────────────────────────────────────────────┐ │ InterruptHandler() │ │ │ │ │ ├─ VDMInterruptTime() │ │ ├─ WriteDatatoCard() │ │ ├─ SHDEntryPoint() call back to stream handler│ │ └─ EOI() │ └─────────────────────────────────────────────────┘ ═══ 4.6.6. 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() │ └──────────────────────────────┘ ═══ 5. Audio Virtual Device Driver Template ═══ The IBM Developer Connection Device Driver Kit for OS/2 includes full source for the MMPM/2 provided Virtual Device Driver, AUDIOVDD.SYS. Use AUDIOVDD.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. With a consistent API on the part of the PDDs (and similar hardware), it is possible for the AUDIOVDD.SYS driver to support up to eight hardware devices. However, where the services of AUDIOVDD.SYS are not sufficient, you can modify the audio VDD template to meet your device driver requirements. You can code you Physical Device Driver to meet the interfaces of AUDIOVDD as an initial stop toward virtualization. Because AUDIOVDD has no knowledge of how it projects, its functionality is limited. You can expand this functionality by copying and changing AUDIOVDD 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 Reference provided in this package. This reference describes the types of virtual device drivers, their interfaces, and available kernel services. ═══ 5.1. Source Code ═══ The VDD template is written using MASM Version 6.0 and linked with the 32-bit OS/2 linker. Source code for the audio VDD sample is located in the \MMOS2\MMTOOLKT\SAMPLES\AUDIOVDD subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module. To follow the VDD execution flow, begin with the VDDINIT.ASM file, which contains the VDD initialization routine. Next, progress to AUDIOVDD.ASM to watch the session hooks, and continue with AUDIOREQ.ASM for hardware sharing between the PDD and VDD. ┌────────────────────────────┬────────────────────────────────┐ │Source File │Description │ ├────────────────────────────┼────────────────────────────────┤ │VDDINIT.ASM │Initializes the VDD during │ │ │system startup. │ ├────────────────────────────┼────────────────────────────────┤ │AUDIOVDD.ASM │Catches DOS session event hooks.│ ├────────────────────────────┼────────────────────────────────┤ │AUDIOREQ.ASM │Requests/frees access to the │ │ │shared hardware. │ ├────────────────────────────┼────────────────────────────────┤ │AUDIOEOI.ASM │Handles end of interrupt │ │ │notifications. │ ├────────────────────────────┼────────────────────────────────┤ │GLOBDATA.ASM │Defines global (common) data │ │ │segments. │ ├────────────────────────────┼────────────────────────────────┤ │INSTDATA.ASM │Defines instance data segments │ │ │(per-DOS session data). │ ├────────────────────────────┼────────────────────────────────┤ │AUDIOVDD.INC │Defines functions for │ │ │AUDIOVDD.ASM. │ ├────────────────────────────┼────────────────────────────────┤ │AUDIOREQ.INC │Contains function definitions │ │ │for AUDIOREQ.ASM. │ ├────────────────────────────┼────────────────────────────────┤ │AUDIOEOI.INC │Contains function definitions │ │ │for AUDIOEOI.ASM. │ ├────────────────────────────┼────────────────────────────────┤ │VDDDATA.INC │Defines EXTERNs for the │ │ │GLOBDATA.ASM and INSTDATA.ASM │ │ │files. │ ├────────────────────────────┼────────────────────────────────┤ │VDDSTRUC.INC │Contains structure declarations │ │ │for the GLOBDATA.ASM and │ │ │INSTDATA.ASM files. │ ├────────────────────────────┼────────────────────────────────┤ │DEVHELP.INC │Defines EXTERNs for OS/2 virtual│ │ │Device Helper (DevHlp) │ │ │functions. │ └────────────────────────────┴────────────────────────────────┘ ═══ 5.2. VDD Architecture ═══ The AUDIOVDD.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. AUDIOVDD.SYS supports multiple adapters by using a protocol for PDD-VDD communication where the PDD defines the characteristics of its device at system startup. 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=AUDIOVDD.SYS parameters on the CONFIG.SYS statement. In the case where a single PDD supports multiple devices, the PDD should register multiple IDC names and entry points (specifying the names on the DEVICE=AUDIOVDD.SYS statement). During initialization, the VDD calls all the PDDs 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 Operations for further information. ═══ 5.3. 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. Often, with similar PDDs, the VDD implementations are similar. Rather than write multiple VDDs, the MMPM/2 product uses a generic driver, AUDIOVDD.SYS. The PDDs are written to its interface allowing a single VDD to support multiple adapters and codes the PDDs to its interface. The PDD names are given on the CONFIG.SYS command line. (Actually, the name given is the name the PDD registers during PDD initialization. This is not necessarily the same as the PDD name given in its device handler.) For each listed device, the VDD establishes communication and queries the information describing the adapter. That is, it asks the PDD to return information dictating I/O port ranges and IRQ levels. 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: o End - Terminate the DOS session o Retry - Block until hardware becomes free o 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. ═══ 5.4. 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. ═══ 6. 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 ═══ 6.1. 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. ═══ 6.2. 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. ═══ 6.3. 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. ═══ 6.4. 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 6.5. 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 7. 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). ═══ 7.1. 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 7.2. 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. ═══ 7.3. 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 └─────────────┘ ═══ 7.4. 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. │ └───────────┴──────────────────────────────┘ ═══ 8. 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. ═══ 8.1. 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 8.2. 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 PDDname and VSDname in 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 PDDname with 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 called VREEL.BIN. 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: The MPEG audio data has an 8-byte header. The first 4 bytes contain the initial audio system clock reference (SCR) and the second 4 bytes contain the buffers' SCR from the MPEG data stream. 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. ═══ 8.3. Audio and Video Synchronization ═══ The MPEGDC is a decompressor that does not require the MMPM/2 subsystem to control or time the flow of images to the decompressor. (Contrast the MPEGDC with the Ultimotion CODEC. 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 location in time of the audio. Because the audio and video have separate hardware with different clocks, the PDD will need the audio time to keep the audio and video synchronized. 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 intial 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 video and audio are not synchronized with the video hardware, the 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. ═══ 8.4. 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. ═══ 9. Audio Sample for Vendor-Specific Drivers ═══ OS/2 Version 3 provides sample files that assist in the creation of vendor-specific drivers (VSDs). The VSD defines a generic device driver-like interface which effectively decomposes high-level media control interface functions into more fundamental operations at the Ring 3 level. The following figure illustrates the program flow from the Media Device Manager (MDM) through the VSD and finally on to the audio adapter. 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 the 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. 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 device driver. ═══ 9.1. 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 which 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 device. 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 │ │ │ini 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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 9.2. 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. A VSD has the following characteristics: o Does not deal with media control interface notifications. o Usually uses a single standard time format (MMTIME). o Usually does not have to deal with file management. ═══ 9.3. 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 ═══ 9.4. 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 - 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 - Not Applicable ═══ 9.5. Device States ═══ Media devices that transport data are considered to be in one of the following states at any given time: o Registered o Deregistered o Saved o Restored o Closed When a device is opened and restored, the device context is assumed to be in the restored state. The closed state 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. 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. ═══ 10. 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. ═══ 10.1. Setting Up the Program ═══ Before using PMADDE, OS/2 2.x with 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 PMADDE from the command line to start the program. The Audio Device Driver Exerciser window is displayed. The PMADDE program defaults to the first waveform audio device it locates. To change the default option, select Options. Select Change Device to display the Change Audio Device window. 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. ═══ 10.2. PMADDE Functions ═══ The PMADDE tool uses Stream Programming Interface Functions to test your audio device driver. The Data Stream menu on the Audio Device Driver Exerciser window includes the following choices: (See Stream Setup and Control for 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_STREAM message, 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 object with 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 protocol in 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_STREAM messages 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_STATUS message to the audio device driver to report the current stream time in milliseconds. ═══ 10.3. 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 Control for detailed information on the phases of operation for a data stream. ═══ 10.3.1. Step 1 ═══ To get a handler ID, select Data Stream. Select SpiGet Handler for a list of MMPM/2 installed handlers. 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. 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. ═══ 10.3.2. Step 2 ═══ To create the stream, select Data Stream. Select SpiCreate to display the Create Data Stream window. 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. ═══ 10.3.3. Step 3 ═══ To associate the stream with an audio file, select Data Stream. Select SpiAssociate to display the Associate Data Stream window. 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. ═══ 10.3.4. Step 4 ═══ To start the stream, select Data Stream. Select SpiStart to display the Start Stream window. 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 SpiStop to display the Stop Stream window. 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 SpiStart from the Data Stream menu. The program restarts the stream and informs you when an end-of-stream (EOS) is reached. ═══ 10.3.5. Step 5 ═══ To get the stream time, select SpiQuery Time from the Data Stream menu. Type the input stream number and select OK. The stream time is displayed in milliseconds. ═══ 10.4. PMADDE Script Interface ═══ To pipe a test script that already exists into the program, select Run Script File from the Options menu. 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 name Specifies the physical device name. CREATE hidSource hidTarget datatype Creates a data stream of datatype from hidSource to hidTarget. Select SpiCreate from the Data Stream menu 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 # filename Associates a data stream with a data object. START stream# startflags Starts a data stream. The startflags can be one of the following: o PREROLL o START STOP stream# stopflags Stops a data stream. The stopflags can be one of the following: o FLUSH o DISCARD o PAUSE SEEK stream# mode units position Seeks to the specified position in the data stream using the specified units and specified mode. DESTROY stream# Destroys the specified stream. QRYTIME stream# Queries the stream time of the specified stream. SLEEP sleepinterval Suspends 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. ═══ 10.5. 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. 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.) 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. 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. 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 slave streams 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 master or 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 ulType field in the SPCBKEY data structure). The application can modify a stream protocol by installing a new SPCB and deinstalling the old SPCB. ═══ 10.6. 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. │ └──────────────────────────┴──────────────────────────────────┘ ═══ 11. AP2/P2STRING Tool ═══ This chapter describes the AP2 and P2STRING tools. ═══ 11.1. 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 compatabilities, 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. │ ├─────────────────────────┼───────────────────────────────────┤ │[-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. │ └─────────────────────────┴───────────────────────────────────┘ ═══ 11.1.1. 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. The Start Test button tests the selected scripts. To test scripts, highlight the selected scripts and click on the Start Test button. 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 Output button. 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. ═══ 11.2. 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. 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. ═══ 11.2.1. 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. ═══ 11.2.2. 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_file Specifies the script file name you want to process. Note: Refer to P2STRING Script Language for information on the contents of a script file and how to interpret the script language. [-a]out_file Specifies 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 Directives for 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. ═══ 11.2.3. 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: o Comments o Tool Directives o MMPM/2 String Commands o Expected Return Strings o Expected Error Messages o 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 ═══ 11.2.3.1. 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. ═══ 11.2.3.2. 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: o Initialization o 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 not considered a failure. Directive Description @THREAD x Specifies that the script lines following this directive belong to thread number x until the next @THREAD directive is encountered. @PROCESS x Specifies that the script lines following this directive belong to process number x until the next @PROCESS directive is encountered. @SET_EVENT name 0|1 Sets the event name to 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 name is 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 alias gains 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 comment to 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 message text. 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 message and 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 secs. Ready to time it? play cdaudio notify @PAUSE 5000 @CHECK Did it play? ═══ 11.2.3.3. 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. ═══ 11.2.3.4. 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. ═══ 11.2.3.5. 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. ═══ 11.2.3.6. 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: o Command completion/error notifications o Event notifications o 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 message instruction. +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-parameter as part of the message, which is essential for the tracking of related notifications. ═══ 11.2.4. 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 position given 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) ═══ 11.3. 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. ═══ 11.4. 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: o Set up the environment for running the test suites o Run the test suites o Analyze the test ═══ 11.4.1. 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= SET MMDATA-AUD= SET TESTDATA= 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/2 HWCODE.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 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. ═══ 11.4.1.1. 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 │ └────────────────────┴────────────────────────────────────────┘ ═══ 11.4.2. 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. ═══ 11.4.3. 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. ═══ 12. 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-only algorithms. 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. ═══ 12.1. 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. ═══ 12.1.1. 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. ═══ 12.1.2. 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: o 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. o 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. ═══ 12.1.3. 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 and the processing capabilities of the playback system. The factors affecting the data stream at creation time are: o Resolution - width and height of video o Frame duration - frequency at which frames are to be displayed o I-frame rate - frequency at which reference frames are to occur o Data rate - average amount of data allowed for an interval of video Factors affecting the playback of a video are: o Processing power of the CPU o Throughput of data storage (for example, CD-ROM, hard disk, and LAN) o 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: o Data rate o Quality of motion during scanning o Performance of seek operations o Ability to maintain smooth motion when frames are dropped to maintain audio synchronization o 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: o Reduce throughput requirements with smaller delta frames o Provide points in the stream at which the entire image exists (good for seeking and scanning) o 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. ═══ 12.1.4. 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. ═══ 12.2. 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: o Variable chrominance subsampling o Luminance transition coding o Statistical luminance image coding ═══ 12.2.1. 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. ═══ 12.2.2. 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. 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 header that 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. ═══ 12.2.3. 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 t of 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: o 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. o 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. o 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. ═══ 12.2.4. 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 increasing luminance 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. ═══ 12.2.5. Format of Block Header ═══ The encoding for a block begins with a block header specifying 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: o 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. o 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: o 00: Unchanged quadrant o 01: Homogeneous/shallow LTC quadrant o 10: LTC quadrant o 11: Statistical/extended LTC quadrant The following combination of quadrant types are defined for mode 1 stream interpretation: o 00: Unchanged quadrant o 01: Homogenous quadrant o 10: Subsampled 4-luminance quadrant o 11: 16-luminance quadrant ═══ 12.2.6. 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: o 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 o 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: o 16 bits of pattern in raster scan order (MSB = 0) o 2 bits undefined (decoder must mask) o 6 bits Y1 o 2 bits undefined (decoder must mask) o 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: o 1 bit = 1 o 3 bits angle 0-157.5 degrees ( 000 = 0 degrees, 22.5 degree increments) o 6 bits Y1 o 6 bits Y2 o 2 bits undefined (decoder must mask) o 6 bits Y3 o 2 bits undefined (decoder must mask) o 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 quadrant is 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: o 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 o 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 quadrant is 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: o 6 bits Y1 o 6 bits Y2 o 6 bits Y3 o 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 quadrant is 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: o 6 bits Y1 o 6 bits Y2 o 6 bits Y3 o 6 bits Y4 . . . o 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. ═══ 12.2.7. 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: o Normal/unique chrominance mode toggle This escape toggles the chrominance mode between normal and unique. o Single unique chrominance mode This escape causes the following block to be interpreted in unique chrominance mode. The current chrominance mode is unchanged. o 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. o 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. o 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. ═══ 12.3. 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: o Linear Total Y delta = 2 3 4 5 6 7 8 11 14 17 20 o Low-contrast Edge Total Y delta = 4 5 6 7 8 11 14 17 20 23 26 29 32 36 o 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: o 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. o 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. o Regions with larger changes in luminance (8 < x < 32) can be represented with an edge-to-edge error not exceeding one luminance level. o 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: o Transitions with Y delta values less than two are encoded with the one-byte encoding (resulting in a quantized direction). o Edge transitions with Y delta values less than 4 are deemed perceptually similar to a linear transition. o Edge transitions with Y delta values less than 6 are deemed perceptually similar with regard to edge type, that is, low or high contrast. o 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 o 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 == ) ; if (Ydelta == ) { ; ; ; } if (Ydelta == ) { ; ; ; } } } ═══ 12.4. Data Stream Escape Value Constants ═══ Escape values defined in the data stream are one-byte values, in the range 70H - 77H (01110xxx). ═══ 12.4.1. 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 o 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 o 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 ═══ 12.4.2. 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. ═══ 12.4.3. 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. ═══ 12.4.4. Frame Guard Byte Value - 73H ═══ This escape assists the decoder in determining if invalid data has been encountered in the input stream. See Escape Values for a more detailed explanation. ═══ 12.4.5. 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. ═══ 12.4.6. Reserved Escape Values - 75H, 76H, 77H ═══ These escape values are reserved. ═══ 13. 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 ulFunction field, of the parameter structure passed on the call, to indicate which function is being requested by the stream handler. ┌────────┬──────────────────────────┬──────────────────────────┐ │Message │Message │Description │ │Numbers │ │ │ ├────────┼──────────────────────────┼──────────────────────────┤ │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. │ └────────┴──────────────────────────┴──────────────────────────┘ ═══ 13.1. DDCMDEntryPoint ═══ ═══ DDCMDEntryPoint - Syntax ═══ /*******************************************/ /* This function enables device driver */ /* stream handlers to interface with the */ /* hardware physical device driver (PDD). */ /*******************************************/ #include PDDCMDCOMMON pParmIn; /* Pointer to DDCMDCOMMON. */ ULONG rc; /* Return codes. */ rc = DDCMDEntryPoint(pParmIn); ═══ DDCMDEntryPoint Parameter - pParmIn ═══ pParmIn (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 ═══ pParmIn (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 ═══ 13.2. DDCMD_CONTROL ═══ ═══ DDCMD_CONTROL - Syntax ═══ This message performs a device-specific command. pParmIn PDDCMDCONTROL pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_CONTROL Parameter - pParmIn ═══ pParmIn (PDDCMDCONTROL) A pointer to a DDCMDCONTROL data structure. The pParm and ulParmSize fields refer to the CONTROL_PARM data structure. Values for ulCmd include: 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 ulCmd of DDCMDCONTROL is 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 - Parameters ═══ pParmIn (PDDCMDCONTROL) A pointer to a DDCMDCONTROL data structure. The pParm and ulParmSize fields refer to the CONTROL_PARM data structure. Values for ulCmd include: 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 ulCmd of DDCMDCONTROL is 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 Parameters Returns Remarks Example Code Glossary ═══ 13.3. DDCMD_DEREG_STREAM ═══ ═══ 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 pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_DEREG_STREAM Parameter - pParmIn ═══ pParmIn (PDDCMDDEREGISTER) A pointer to a DDCMDDEREGISTER data 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 - Parameters ═══ pParmIn (PDDCMDDEREGISTER) A pointer to a DDCMDDEREGISTER data 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 ═══ o 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. o 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 Parameters Returns Remarks Example Code Glossary ═══ 13.4. DDCMD_READ ═══ ═══ DDCMD_READ - Syntax ═══ This message performs a read from the device into a buffer. pParmIn PDDCMDREADWRITE pParmIn /* Input/Output. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_READ Parameter - pParmIn ═══ pParmIn (PDDCMDREADWRITE) A pointer to a DDCMDREADWRITE data 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 - Parameters ═══ pParmIn (PDDCMDREADWRITE) A pointer to a DDCMDREADWRITE data 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 empty buffer 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 pBuffer parameter 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 Parameters Returns Remarks Example Code Glossary ═══ 13.5. DDCMD_REG_STREAM ═══ ═══ DDCMD_REG_STREAM - Syntax ═══ This message registers a stream instance with a device driver for the first time. pParmIn PDDCMDREGISTER pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_REG_STREAM Parameter - pParmIn ═══ pParmIn (PDDCMDREGISTER) A pointer to a DDCMDREGISTER data structure. Values for ulStreamOperation include: o STREAM_OPERATION_CONSUME o STREAM_OPERATION_PRODUCE Values for ulAddressType include: o ADDRESS_TYPE_VIRTUAL o ADDRESS_TYPE_PHYSICAL o 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 - Parameters ═══ pParmIn (PDDCMDREGISTER) A pointer to a DDCMDREGISTER data structure. Values for ulStreamOperation include: o STREAM_OPERATION_CONSUME o STREAM_OPERATION_PRODUCE Values for ulAddressType include: o ADDRESS_TYPE_VIRTUAL o ADDRESS_TYPE_PHYSICAL o 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 Parameters Returns Remarks Example Code Glossary ═══ 13.6. DDCMD_SETUP ═══ ═══ DDCMD_SETUP - Syntax ═══ This message performs device-specific stream instance setup. pParmIn PDDCMDSETUP pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_SETUP Parameter - pParmIn ═══ pParmIn (PDDCMDSETUP) A pointer to a DDCMDSETUP data structure. The pSetupParm and ulSetupParmSize fields refer to the SETUP_PARM data 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 - Parameters ═══ pParmIn (PDDCMDSETUP) A pointer to a DDCMDSETUP data structure. The pSetupParm and ulSetupParmSize fields refer to the SETUP_PARM data 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 pSetupParm field 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 Parameters Returns Remarks Example Code Glossary ═══ 13.7. DDCMD_STATUS ═══ ═══ DDCMD_STATUS - Syntax ═══ This message requests status from the device. pParmIn PDDCMDSTATUS pParmIn /* Input/Output. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_STATUS Parameter - pParmIn ═══ pParmIn (PDDCMDSTATUS) A pointer to a DDCMDSTATUS data structure. The pStatus and ulStatusSize fields refer to the STATUS_PARM data 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 - Parameters ═══ pParmIn (PDDCMDSTATUS) A pointer to a DDCMDSTATUS data structure. The pStatus and ulStatusSize fields refer to the STATUS_PARM data 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 Parameters Returns Remarks Example Code Glossary ═══ 13.8. DDCMD_WRITE ═══ ═══ DDCMD_WRITE - Syntax ═══ This message performs a write from the buffer to the device. pParmIn PDDCMDREADWRITE pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ DDCMD_WRITE Parameter - pParmIn ═══ pParmIn (PDDCMDREADWRITE) A pointer to a DDCMDREADWRITE data 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 - Parameters ═══ pParmIn (PDDCMDREADWRITE) A pointer to a DDCMDREADWRITE data 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 pBuffer parameter 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 Parameters Returns Remarks Example Code Glossary ═══ 14. 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 ulFunction field, 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: ┌─────┬────────────────────┬───────────────────────────────────┐ │Messa│Message │Description │ │Numbe│ │ │ ├─────┼────────────────────┼───────────────────────────────────┤ │0L │SHD_REPORT_EVENT │Reports an event to the stream │ │ │ │handler. │ ├─────┼────────────────────┼───────────────────────────────────┤ │1L │SHD_REPORT_INT │Reports an interrupt from a device.│ └─────┴────────────────────┴───────────────────────────────────┘ ═══ 14.1. SHDEntryPoint ═══ ═══ SHDEntryPoint - Syntax ═══ /*******************************************/ /* Each stream handler must provide this */ /* entry point, which is used for the PDD */ /* to communicate back to the stream */ /* handler. */ /*******************************************/ #include PSHD_COMMON ParmIn; /* Pointer to SHD_COMMON. */ ULONG rc; /* Return codes. */ rc = SHDEntryPoint(ParmIn); ═══ SHDEntryPoint Parameter - ParmIn ═══ ParmIn (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 ═══ ParmIn (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_INT command 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 ═══ 14.2. SHD_REPORT_EVENT ═══ ═══ SHD_REPORT_EVENT - Syntax ═══ This message reports an event to the stream handler. pParmIn PSHD_REPORTEVENT pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ SHD_REPORT_EVENT Parameter - pParmIn ═══ pParmIn (PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENT data 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 - Parameters ═══ pParmIn (PSHD_REPORTEVENT) A pointer to an SHD_REPORTEVENT data 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 Parameters Returns Remarks Example Code Glossary ═══ 14.3. SHD_REPORT_INT ═══ ═══ 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 pParmIn /* Input. */ returns ULONG rc /* Return codes. */ ═══ SHD_REPORT_INT Parameter - pParmIn ═══ pParmIn (PSHD_REPORTINT) A pointer to a SHD_REPORTINT data 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 - Parameters ═══ pParmIn (PSHD_REPORTINT) A pointer to a SHD_REPORTINT data 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. 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 Parameters Returns Remarks Example Code Glossary ═══ 15. 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 VSDEntry entry point. ═══ 15.1. VSDEntry ═══ ═══ 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 #include 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 ulFlags parameter 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 ulFunc parameter. ═══ 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. ═══ 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 ulFlags parameter 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 ulFunc parameter. 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. ═══ VSDEntry - Topics ═══ Select an item: Syntax Parameters Returns Glossary ═══ 15.2. VSD_CLOSE ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to the VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVOID pRequest /* Not used. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 hvsd handle 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 Parameters Returns Remarks Example Code Glossary ═══ 15.3. VSD_DDCMD ═══ ═══ 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 Reference for more detailed information on stream handler command (SHC) messages. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flags for this command. */ pRequest PVOID pRequest /* Pointer to data structure. */ returns ULONG rc /* Return codes. */ ═══ 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. pRequest is a pointer to the DDCMDCONTROL structure. DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequest is a pointer to DDCMDDEREGISTER structure. DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an empty buffer 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_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller. pRequest is a pointer to DDCMDREADWRITE structure. DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequest is a pointer to DDCMDREGISTER structure. DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequest is a pointer to DDCMDSETUP structure. DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. pRequest is a pointer to DDCMDSTATUS structure. DDCMD_WRITE This VSD subcommand is used by a stream handler to give a full buffer 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_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller. pRequest is a pointer to DDCMDREADWRITE structure. ═══ VSD_DDCMD Parameter - pRequest ═══ pRequest (PVOID) The value of pRequest varies according to the ulFlags value. See each particular ulFlags value for the definition of pRequest. ═══ VSD_DDCMD Return Value - rc ═══ rc (ULONG) Possible error codes vary according to the value of ulFlags. ═══ VSD_DDCMD - Parameters ═══ 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. pRequest is a pointer to the DDCMDCONTROL structure. DDCMD_DEREG_STREAM This subcommand of VSD_DDCMD deregisters a stream instance with the device driver. pRequest is a pointer to DDCMDDEREGISTER structure. DDCMD_READ This subcommand of VSD_DDCMD is used by a stream handler to give an empty buffer 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_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller. pRequest is a pointer to DDCMDREADWRITE structure. DDCMD_REG_STREAM This subcommand of VSD_DDCMD registers a stream instance with the device driver. pRequest is a pointer to DDCMDREGISTER structure. DDCMD_SETUP This subcommand of VSD_DDCMD performs device-specific stream instance setup. pRequest is a pointer to DDCMDSETUP structure. DDCMD_STATUS This VSD subcommand requests streaming status from a device. Typically, it is called to request the current stream time. pRequest is a pointer to DDCMDSTATUS structure. DDCMD_WRITE This VSD subcommand is used by a stream handler to give a full buffer 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_REPORTINT structure to the pSHDEntryPoint in DDCMDREGISTER to inform the caller. pRequest is a pointer to DDCMDREADWRITE structure. pRequest (PVOID) The value of pRequest varies according to the ulFlags value. See each particular ulFlags value 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 pProcessLin field of the DDCMDREADWRITE structure. VSDs should use this pointer if they want to operate on the data while they are not in protect mode. The pBuffer field of the DDCMDREADWRITE structure contains 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 pBuffer and not by pProcessLin. ═══ VSD_DDCMD - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 15.4. VSD_GETDEVCAPS ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to the VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVSD_GETDEVCAPS_PARMS pRequest /* Pointer to VSD_GETDEVCAPS_PARMS */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS data structure. ═══ VSD_GETDEVCAPS Return Value - rc ═══ rc (ULONG) Error code indicating success or the type of failure: VSDERR_REQUEST_BUF_TOO_SMALL The ulLength in the request packet is too small. VSDERR_MISSING_PARAMETER One or more parameters are missing. VSDERR_HARDWARE A hardare error occurred. ═══ VSD_GETDEVCAPS - Parameters ═══ 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_PARMS data structure. rc (ULONG) Error code indicating success or the type of failure: VSDERR_REQUEST_BUF_TOO_SMALL The ulLength in the request packet is too small. VSDERR_MISSING_PARAMETER One or more parameters are missing. VSDERR_HARDWARE A hardare 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_PARMS structure 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 Parameters Returns Remarks Example Code Glossary ═══ 15.5. VSD_ESCAPE ═══ ═══ VSD_ESCAPE - Syntax ═══ This optional command sends a buffer to the driver. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to the VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVSD_ESCAPE_PARMS pRequest /* Pointer to VSD_ESCAPE_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 Parameters Returns Glossary ═══ 15.6. VSD_INSERTSETTINGSPAGE ═══ ═══ VSD_INSERTSETTINGSPAGE - Syntax ═══ This command enables a VSD to insert device-specific settings pages into the system configuration application. hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PMCI_DEVICESETTINGS_PARMS pRequest /* Pointer to MCI_DEVICESETTINGS_PARMS */ returns HWND hwndRC /* Return codes. */ ═══ 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_PARMS data 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 - Parameters ═══ 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_PARMS data 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 Parameters Returns Glossary ═══ 15.7. VSD_OPEN ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Not used. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVSD_OPEN_PARMS pRequest /* Pointer to VSD_OPEN_PARMS */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS data 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 pRequest is not valid. ═══ VSD_OPEN - Parameters ═══ 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_PARMS data 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 pRequest is 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 pDevInfo pointer points to a VSD_AUDIOOPEN_PARMS structure. This structure contains enough information to initialize the audio device. The VSD is responsible for filling in the ulDataSubType field of the VSD_AUDIOOPEN_PARMS structure 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 Parameters Returns Remarks Example Code Glossary ═══ 15.8. VSD_QUERY ═══ ═══ VSD_QUERY - Syntax ═══ This command allows an application to query the status of the VSD. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flags for this command. */ returns PVOID pRequest /* Pointer varies according to ulFlags. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 Parameters Returns Remarks Glossary ═══ 15.9. VSD_QUERYAUDIOATTRIBUTES ═══ ═══ VSD_QUERYAUDIOATTRIBUTES - Syntax ═══ This subcommand of the VSD_QUERY command queries the current audio settings and capabilities. A valid length must be placed in the ulLength field of the VSD_AUDIOATTRIBUTES_PARMS structure and the audio setting (such as treble, bass, and so on) must be placed in the ulFlags field of the VSD_AUDIOATTRIBUTES_PARMS structure. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag for this command. */ pRequest PVSD_AUDIOATTRIBUTES_PARMS pRequest /* Pointer to VSD_AUDIOATTRIBUTES_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 ulValue field 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 Parameters Returns Remarks Example Code Glossary ═══ 15.10. VSD_QUERYCONNECTOR ═══ ═══ VSD_QUERYCONNECTOR - Syntax ═══ This subcommand of the VSD_QUERY command 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 fEnabled field of the VSD_CONNECTOR_PARMS structure 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PVSD_CONNECTOR_PARMS pRequest /* Pointer to VSD_CONNECTOR_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 Parameters Returns Example Code Glossary ═══ 15.11. VSD_QUERYDATATYPE ═══ ═══ VSD_QUERYDATATYPE - Syntax ═══ This subcommand of the VSD_QUERY command queries if a particular set of data types are supported. The ulSamplingRate, ulBitsPerSample, ulChannels, and ulDataType will be filled in on input. The ulDataSubType is filled in by the VSD on output. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PVSD_AUDIODATATYPE_PARMS pRequest /* Output. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 Parameters Returns Remarks Example Code Glossary ═══ 15.12. VSD_QUERYMIXCONNECTIONS ═══ ═══ VSD_QUERYMIXCONNECTIONS - Syntax ═══ This subcommand of the VSD_QUERY command 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 Drivers and Mixer IOCtl Functions Introduction This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PLINECONNECTIONS pRequest /* Pointer LINECONNECTIONS. */ returns ULONG rc /* Return codes. */ ═══ 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 LINECONNECTIONS structure. ═══ 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_QUERY. ulFlags (ULONG) Set to VSD_QUERYMIXCONNECTIONS. pRequest (PLINECONNECTIONS) A pointer to the LINECONNECTIONS structure. 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 ulConnections field of the LINECONNECTIONS structure returns the particular output that a line is routed to. The ulLine field of the LINECONNECTIONS structure must contain a valid line on input. For more information on the values for ulLine and ulConnections, see the LINECONNECTIONS structure. ═══ 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 Parameters Returns Remarks Example Code Glossary ═══ 15.13. VSD_QUERYMIXCONTROL ═══ ═══ VSD_QUERYMIXCONTROL - Syntax ═══ This subcommand of the VSD_QUERY command 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 Drivers and Mixer IOCtl Functions Introduction This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PMIXERCONTROL pRequest /* Pointer MIXERCONTROL. */ returns ULONG rc /* Return codes. */ ═══ 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 MIXERCONTROL structure. ═══ 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_QUERY. ulFlags (ULONG) Set to VSD_QUERYMIXCONTROL. pRequest (PMIXERCONTROL) A pointer to the MIXERCONTROL structure. 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 ulLine field of the MIXERCONTROL structure must be filled in with one of the VSD sources/sinks in the low-order byte of the low word. The ulControl field of the MIXERCONTROL structure 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 Parameters Returns Remarks Example Code Glossary ═══ 15.14. VSD_QUERYMIXLINE ═══ ═══ VSD_QUERYMIXLINE - Syntax ═══ This subcommand of the VSD_QUERY command 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 Drivers and Mixer IOCtl Functions Introduction This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PMIXERLINEINFO pRequest /* A pointer to the MIXERLINEINFO structure. */ returns ULONG rc /* Return codes. */ ═══ 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 MIXERLINEINFO structure. The ulSupport field will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ulLine field 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_QUERY. ulFlags (ULONG) Set to VSD_QUERYMIXLINE. pRequest (PMIXERLINEINFO) A pointer to the MIXERLINEINFO structure. The ulSupport field will be filled by the VSD with the supported setting or settings if the line supports multiple settings. The ulLine field 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 Parameters Returns Example Code Glossary ═══ 15.15. VSD_QUERYMONITOR ═══ ═══ VSD_QUERYMONITOR - Syntax ═══ This subcommand of the VSD_QUERY command 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PULONG pRequest /* Output. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 Parameters Returns Example Code Glossary ═══ 15.16. VSD_QUERYSTATUSLEVEL ═══ ═══ VSD_QUERYSTATUSLEVEL - Syntax ═══ This subcommand of the VSD_QUERY command queries the status of the audio input level (percentage). This command is optional. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PULONG pRequest /* Output. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 Parameters Returns Glossary ═══ 15.17. VSD_QUERYVOLUME ═══ ═══ VSD_QUERYVOLUME - Syntax ═══ This subcommand of the VSD_QUERY command queries the volume level. The volume is returned as a percentage between 0% and 100% This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag for this command. */ pRequest PVSD_VOLUME_PARMS pRequest /* Pointer to VSD_VOLUME_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 ulVolume field of the VSD_VOLUME_PARMS structure. ═══ 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 Parameters Returns Remarks Example Code Glossary ═══ 15.18. VSD_RESOURCE ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVSD_RESOURCE_PARMS pRequest /* Pointer to VSD_RESOURCE_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS data structure. The driver is responsible for filling in the ulResUnits and ulClass fields. The caller is responsible for filling in the ulDataType field. ═══ 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 - Parameters ═══ 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_PARMS data structure. The driver is responsible for filling in the ulResUnits and ulClass fields. The caller is responsible for filling in the ulDataType field. 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: o RESOURCEUNITS= o RESOURCECLASS= o 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 RESOURCECLASSES indicates 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 ulClass field with the class that is appropriate for this mode. The keyword RESOURCEUNITS indicates the maximum number of instances that can be active on the card at any particular time. For example, if the XYZ card mentioned above had the ability to play three PCM files at the same time, the RESOURCEUNITS 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 ulResUnits field 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 Parameters Returns Remarks Example Code Glossary ═══ 15.19. VSD_RESTORE ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVOID pRequest /* Not used. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 Parameters Returns Remarks Example Code Glossary ═══ 15.20. VSD_SAVE ═══ ═══ 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Not used. */ pRequest PVOID pRequest /* Not used. */ returns ULONG rc /* Return codes. */ ═══ 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 - Parameters ═══ 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 Parameters Returns Remarks Example Code Glossary ═══ 15.21. VSD_SET ═══ ═══ VSD_SET - Syntax ═══ This command allows an application to modify the settings of the VSD. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command message. */ ulFlags ULONG ulFlags /* Flags for this message. */ pRequest PVOID pRequest /* Pointer value that varies according to */ returns ULONG rc /* Return codes. */ ═══ 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 hvsd matches the one provided on the VSD_OPEN. ═══ VSD_SET - Parameters ═══ 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 hvsd matches 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 Parameters Returns Remarks Glossary ═══ 15.22. VSD_SETAUDIOATTRIBUTES ═══ ═══ VSD_SETAUDIOATTRIBUTES - Syntax ═══ This subcommand of the VSD_SET command sets the audio attribute settings. A valid length must be placed in the ulLength field of the VSD_AUDIOATTRIBUTES_PARMS structure. The audio setting to modify (such as treble, bass, and so on) must be placed in the ulFlags field of the VSD_AUDIOATTRIBUTES_PARMS structure with the actual corresponding setting in the ulValue field. The value should be between 0 and 100. The ulDelay indicates the length of time over which this effect should take place. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag for this command. */ pRequest PVSD_AUDIOATTRIBUTES_PARMS pRequest /* Pointer to VSD_AUDIOATTRIBUTES_PARMS. */ returns ULONG rc /* Return codes. */ ═══ 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_PARMS structure. ═══ 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 - Parameters ═══ 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_PARMS structure. 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 Parameters Returns Example Code Glossary ═══ 15.23. VSD_SETCONNECTOR ═══ ═══ VSD_SETCONNECTOR - Syntax ═══ This subcommand of the VSD_SET command 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 VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PVSD_CONNECTOR_PARMS pRequest /* Pointer to VSD_CONNECTOR_PARMS. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETCONNECTOR Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETCONNECTOR Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ VSD_SETCONNECTOR Parameter - ulFlags ═══ ulFlags (ULONG) Set to VSD_SETCONNECTOR. ═══ VSD_SETCONNECTOR Parameter - pRequest ═══ pRequest (PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMS structure. The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the fEnabled field. A valid connector must be placed in the ulConn_Type field and a valid index in the ulIndex field. ═══ 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. ulFlags (ULONG) Set to VSD_SETCONNECTOR. pRequest (PVSD_CONNECTOR_PARMS) A pointer to the VSD_CONNECTOR_PARMS structure. The status of the connector, enable (VSD_ENABLE) or disable (VSD_DISABLE) must be indicated in the fEnabled field. A valid connector must be placed in the ulConn_Type field and a valid index in the ulIndex field. 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 Parameters Returns Example Code Glossary ═══ 15.24. VSD_SETDATATYPE ═══ ═══ VSD_SETDATATYPE - Syntax ═══ This subcommand of the VSD_SET command sets the current data type that the device is dealing with. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PVSD_AUDIODATATYPE_PARMS pRequest /* Input. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETDATATYPE Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETDATATYPE Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ VSD_SETDATATYPE Parameter - ulFlags ═══ ulFlags (ULONG) Set to VSD_SETDATATYPE. ═══ VSD_SETDATATYPE Parameter - pRequest ═══ pRequest (PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_PARMS structure. Note: Every field in the VSD_AUDIODATATYPE_PARMS structure 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 ulAverageBytesPerSec fields in the VSD_AUDIODATATYPE_PARMS structure. The ulFlags field of the VSD_AUDIODATATYPE_PARMS structure contains a flag for each field in the structure that can be set. Every field has a flag except for the ulOperation field. The ulOperation field is valid for every call. The VSD_AUDIODATATYPE_PARMS structure must contain at least one of the following flags: o VSD_MODE o VSD_CHANNELS o VSD_SAMPLESPERSEC o VSD_OPERATION o 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. ulFlags (ULONG) Set to VSD_SETDATATYPE. pRequest (PVSD_AUDIODATATYPE_PARMS) Input. Pointer to a VSD_AUDIODATATYPE_PARMS structure. Note: Every field in the VSD_AUDIODATATYPE_PARMS structure 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 ulAverageBytesPerSec fields in the VSD_AUDIODATATYPE_PARMS structure. The ulFlags field of the VSD_AUDIODATATYPE_PARMS structure contains a flag for each field in the structure that can be set. Every field has a flag except for the ulOperation field. The ulOperation field is valid for every call. The VSD_AUDIODATATYPE_PARMS structure must contain at least one of the following flags: o VSD_MODE o VSD_CHANNELS o VSD_SAMPLESPERSEC o VSD_OPERATION o 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 bitspersample 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 Parameters Returns Example Code Glossary ═══ 15.25. VSD_SETMIXCONNECTIONS ═══ ═══ VSD_SETMIXCONNECTIONS - Syntax ═══ This subcommand of the VSD_SET command 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 Drivers and Mixer IOCtl Functions Introduction This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PLINECONNECTIONS pRequest /* Pointer LINECONNECTIONS. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETMIXCONNECTIONS Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETMIXCONNECTIONS Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ VSD_SETMIXCONNECTIONS Parameter - ulFlags ═══ ulFlags (ULONG) Set to VSD_SETMIXCONNECTIONS. ═══ VSD_SETMIXCONNECTIONS Parameter - pRequest ═══ pRequest (PLINECONNECTIONS) A pointer to the LINECONNECTIONS structure. The caller must fill in the ulLine and the ulLine fields of the LINECONNECTIONS structure. ═══ 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. ulFlags (ULONG) Set to VSD_SETMIXCONNECTIONS. pRequest (PLINECONNECTIONS) A pointer to the LINECONNECTIONS structure. The caller must fill in the ulLine and the ulLine fields of the LINECONNECTIONS structure. 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 Parameters Returns Example Code Glossary ═══ 15.26. VSD_SETMIXCONTROL ═══ ═══ VSD_SETMIXCONTROL - Syntax ═══ This subcommand of the VSD_SET command 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 Drivers and Mixer IOCtl Functions Introduction This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PMIXERCONTROL pRequest /* Pointer to MIXERCONTROL. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETMIXCONTROL Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETMIXCONTROL Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ VSD_SETMIXCONTROL Parameter - ulFlags ═══ ulFlags (ULONG) Set to VSD_SETMIXCONTROL. ═══ VSD_SETMIXCONTROL Parameter - pRequest ═══ pRequest (PMIXERCONTROL) A pointer to the MIXERCONTROL structure. The ulControl field of the MIXERCONTROL structure 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 ulLine field 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. ulFlags (ULONG) Set to VSD_SETMIXCONTROL. pRequest (PMIXERCONTROL) A pointer to the MIXERCONTROL structure. The ulControl field of the MIXERCONTROL structure 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 ulLine field 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 Parameters Returns Example Code Glossary ═══ 15.27. VSD_SETMONITOR ═══ ═══ VSD_SETMONITOR - Syntax ═══ This subcommand of the VSD_SET command enables (MCI_TRUE) or disables (MCI_FALSE) the audio monitor feature of the device. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag indicating subcommand. */ pRequest PULONG pRequest /* Input. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETMONITOR Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETMONITOR Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. 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 Parameters Returns Example Code Glossary ═══ 15.28. VSD_SETVOLUME ═══ ═══ VSD_SETVOLUME - Syntax ═══ This subcommand of the VSD_SET command 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 ulFlags field indicates which fields are to be used. This command is sent using VSDEntry as follows: VSDEntry(hvsd, ulFunc, ulFlags, pRequest) hvsd HVSD hvsd /* Handle to VSD. */ ulFunc ULONG ulFunc /* VSD command. */ ulFlags ULONG ulFlags /* Flag for this command. */ pRequest PVSD_VOLUME_PARMS pRequest /* Pointer to VSD_VOLUME_PARMS. */ returns ULONG rc /* Return codes. */ ═══ VSD_SETVOLUME Parameter - hvsd ═══ hvsd (HVSD) Handle to a VSD. ═══ VSD_SETVOLUME Parameter - ulFunc ═══ ulFunc (ULONG) Set to VSD_SET. ═══ VSD_SETVOLUME Parameter - ulFlags ═══ ulFlags (ULONG) Set to VSD_SETVOLUME. ═══ VSD_SETVOLUME Parameter - pRequest ═══ pRequest (PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMS structure. The caller must fill in the ulVolume field if VSD_VOLUME is specified. The caller must fill in the ulMasterAudio field if VSD_MASTERVOLUME is specified. The caller must fill in the fMute field 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 - Parameters ═══ hvsd (HVSD) Handle to a VSD. ulFunc (ULONG) Set to VSD_SET. ulFlags (ULONG) Set to VSD_SETVOLUME. pRequest (PVSD_VOLUME_PARMS) Pointer to the VSD_VOLUME_PARMS structure. The caller must fill in the ulVolume field if VSD_VOLUME is specified. The caller must fill in the ulMasterAudio field if VSD_MASTERVOLUME is specified. The caller must fill in the fMute field 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 Parameters Returns Example Code Glossary ═══ 16. IOCtl Functions ═══ OS/2 device drivers are used to access the I/O hardware. The IOCtl functions provide a method for an application, or subsystem, to send device-specific control commands to a physical device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl function request. The DosDevIOCtl request can be used only by OS/2 applications; the INT 21h IOCtl request can be used only by DOS applications. This reference describes audio (category 80h) and video (category 140h) IOCtls. ═══ 16.1. Audio IOCtl Functions ═══ Audio device drivers are controlled through input/output control (IOCtl) calls, which are used to instruct the audio device driver on the type of audio to use (for example, MIDI, 8- or 16-bit PCM, and so forth) and which operation to perform (for example, record, play, start, or pause). During audio playback, data is written to an audio device driver using standard file I/O functions. MIDI data is written in blocks containing timing information that enables the device driver to synchronize the data with its internal time base. Sampled audio data is output, sample-by-sample, at the specified sample rate. Therefore, data written to the device driver is queued until the correct time for it to be processed. It is in the best interest of OS/2, MMPM/2, and the application that the audio IOCtls be used only for setting audio attributes and not for passing audio data from an MMPM/2 application to the PDD. The preferred method of passing audio data is for the application to issue play and record commands using the media control interface. A logical media device is called, which in turn calls the stream programming interface. Data transfer takes place between a stream handler device driver and the PDD by means of the inter-device driver communications (IDC) interface. Using the IDC method of data transfer relieves applications from the burden of allocating data buffer memory and monitoring the flow of data. The messages that comprise the IDC interface can be found in DDCMD Messages and SHD Messages. Audio IOCtl parameters are passed to and from a device driver in a data area containing one or more 16-bit USHORT parameters. The first parameter always is the Request ID. Subsequent USHORTs pass data to, or receive data from, the device driver. The generic IOCtl interface uses two data-passing parameters, the parameter packet and the data packet. For audio IOCtls, the data packet parameter is a pointer to a data structure containing the data necessary to perform the command. The parameter packet is not used. The audio IOCtls listed in the following table are category 80h (user defined): ┌──────────────┬─────────────────────┬────────────────────────────┐ │Function No. │Function │Description │ ├──────────────┼─────────────────────┼────────────────────────────┤ │40h │AUDIO_INIT │Initialize audio device │ │ │ │driver. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │41h │AUDIO_STATUS │Obtain status of audio │ │ │ │hardware. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │42h │AUDIO_CONTROL │Control audio adapter. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │43h │AUDIO_BUFFER │Determine buffer status. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │44h │AUDIO_LOAD │Load DSP code. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │45h │AUDIO_WAIT │Suspend program operation. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │46h │AUDIO_HPI │Access high-performance │ │ │ │interface. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │47h │AUDIO_UPDATE │Update buffer information. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │48H │AUDIO_CAPABILITY │Determine supported audio │ │ │ │settings. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │52H │ │reserved │ ├──────────────┼─────────────────────┼────────────────────────────┤ │53H │ │reserved │ ├──────────────┼─────────────────────┼────────────────────────────┤ │54H │ │reserved │ ├──────────────┼─────────────────────┼────────────────────────────┤ │55H │ │reserved │ ├──────────────┼─────────────────────┼────────────────────────────┤ │60H │MIX_GETCONNECTIONS │Determine if line is │ │ │ │enabled. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │61H │MIX_SETCONNECTIONS │Enable a line to the │ │ │ │Record/monitor circuitry. │ ├──────────────┼─────────────────────┼────────────────────────────┤ │62H │MIX_GETLINEINFO │Determine line capabilities.│ ├──────────────┼─────────────────────┼────────────────────────────┤ │63H │MIX_GETCONTROL │Get current state of a line.│ ├──────────────┼─────────────────────┼────────────────────────────┤ │64H │MIX_SETCONTROL │Set current state of a line.│ └──────────────┴─────────────────────┴────────────────────────────┘ Note: This chapter documents AudioDD IOCTLs that could be sent to MMPM/2 device drivers. To support MMPM/2 the following IOCTLs are necessary: AUDIO_INIT Required for all MMPM/2 device drivers. AUDIO_CONTROL Required for all MMPM/2 device drivers. AUDIO_LOAD Optional, used to load DSP tasks. MIXDM_GETCONNECTIONS Enhanced mixing IOCTLs (new) MIXDM_SETCONNECTIONS MIXDM_GETLINEONFO MIXDM_GETCONTROL MIXDM_SETCONTROL AUDIO_CAPABILITY Used to simplify install (new) The remaining IOCtls documented in this chapter are provided as reference for device driver writers who wish to support AudioDD knowledgeable applications. These applications include IBM Linkway Live and early versions of IBM AVC (Audio Visual Connection). ═══ 16.1.1. AUDIO_INIT (40h) - Initialize Audio Device Driver ═══ ═══ 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_INIT fields to the desired values and calling AUDIO_INIT. ═══ AUDIO_INIT (40h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_INIT (40h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _init { LONG lSRate; LONG lBitsPerSRate; LONG lBsize; SHORT sMode; SHORT sChannels; LONG lResolution; CHAR abLoadPath[LOAD_PATH]; ULONG ulFlags; ULONG ulOperation; SHORT sReturnCode; SHORT sSlotNumber; SHORT sDeviceID; VOID FAR *pvReserved; ULONG ulVersionLevel; } MCI_AUDIO_INIT; typedef MCI_AUDIO_INIT FAR *LPMCI_AUDIO_INIT; ═══ AUDIO_INIT (40h) - Data Packet Format ═══ ┌─────────────────────────────────────────────┐ │Field C Datatype │ ├─────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_INIT │ └─────────────────────────────────────────────┘ ═══ AUDIO_INIT (40h) - Returns ═══ If the audio device driver can satisfy the request as specified, it returns 0. If the request cannot be performed as specified, the audio device driver fills in the MCI_AUDIO_INIT fields with the supported values that most closely approximate the values specified by the user, sets the BESTFIT_PROVIDED bit in ulFlags, and returns 0 to the application. Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl. ═══ AUDIO_INIT (40h) - Remarks ═══ Before calling AUDIO_INIT, the application must have opened the audio device driver. If the application specifies invalid data in the MCI_AUDIO_INIT, the device driver probably will not return an error. Instead, one of its supported modes will return with the BESTFIT_PROVIDED bit set in ulFlags of the MCI_AUDIO_INIT structure and the fields filled in. If, after examination of the returned values, the application is satisfied with the approximation, it can continue. Otherwise, it should use other values and reissue AUDIO_INIT. Some audio devices are capable of performing more than one audio operation at a time. Therefore, the device driver for such devices can permit more than one application to use the device at one time by allowing multiple Opens to be active. If the device can perform the operations requested by two applications at the same time, it will appear to be two different audio devices. If the device cannot perform a requested operation because that operation is being performed for another application, it will return the OVERLOADED flag set in the sReturnCode field. Note: It is critical that the application check the returned ulFlags and sReturnCode fields before proceeding. If an application is going to perform audio simultaneously on more than one track, the application should perform OPENs and AUDIO_INITs for both devices before issuing AUDIO_START for either device. This enables the device to select the correct DSP load module to support both tasks, when possible. ═══ AUDIO_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 ═══ 16.1.2. AUDIO_STATUS (41h) - Obtain Status of Audio Hardware ═══ ═══ 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _stat { LONG lSRate; LONG lBitsPerSRate; LONG lBsize; SHORT sMode; SHORT sChannels; ULONG ulFlags; ULONG ulOperation; MCI_AUDIO_CHANGE rAudioChange; } MCI_AUDIO_STATUS; typedef MCI_AUDIO_STATUS FAR *LPMCI_AUDIO_STATUS; ═══ AUDIO_STATUS (41h) - Data Packet Format ═══ ┌───────────────────────────────────────────────┐ │Field C Datatype │ ├───────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_STATUS │ └───────────────────────────────────────────────┘ ═══ AUDIO_STATUS (41h) - Returns ═══ The values associated with the current audio mode are returned in the fields, lSRate, lBitsPerSRate, lBsize, sMode, sChannels, and ulFlags of the MCI_AUDIO_STATUS structure. The MCI_AUDIO_CHANGE data structure contains the current input, output, monitor, volume, balance, and tone control settings. Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl. ═══ AUDIO_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 ═══ 16.1.3. AUDIO_CONTROL (42h) - Control Audio Adapter ═══ ═══ AUDIO_CONTROL (42h) - Description ═══ This IOCtl is used to change the state of the adapter or selected characteristics of the adapter. The adapter state is changed by the following usIOCtlRequest values: o AUDIO_START o AUDIO_STOP o AUDIO_PAUSE o AUDIO_RESUME Adapter characteristics are changed by the usIOCtlRequest value AUDIO_CHANGE. ═══ AUDIO_CONTROL (42h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_CONTROL (42h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _MCI_AUDIO_CONTROL { USHORT usIOCtlRequest; VOID *pbRequestInfo; ULONG ulPosition; SHORT sReturnCode; } MCI_AUDIO_CONTROL; typedef MCI_AUDIO_CONTROL FAR *LPMCI_AUDIO_CONTROL ═══ AUDIO_CONTROL (42h) - Data Packet Format ═══ ┌────────────────────────────────────────────────┐ │Field C Datatype │ ├────────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_CONTROL │ └────────────────────────────────────────────────┘ ═══ AUDIO_CONTROL (42h) - Returns ═══ If a requested input or output device is not supported by the audio device, sReturnCode is set and an error returned. Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl. ═══ AUDIO_CONTROL (42h) - Remarks ═══ The K12 version does not support ulPosition values except for 0. Any pending AUDIO_CHANGE requests are discarded when AUDIO_INIT is 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 ═══ 16.1.4. AUDIO_BUFFER (43h) - Determine Buffer Status ═══ ═══ 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 on in the ulFlags field. ═══ AUDIO_BUFFER (43h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_BUFFER (43h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _buffer { ULONG ulFlags; ULONG ulReadBufSize; ULONG ulWriteBufSize; ULONG ulReadBufTime; ULONG ulWriteBufTime; ULONG ulReadBufMax; ULONG ulWriteBufMax; ULONG ulPosition; ULONG ulPositionType; LONG lReadBufCap; LONG lWriteBufCap; LONG lRequestBufCap; } MCI_AUDIO_BUFFER; typedef MCI_AUDIO_BUFFER FAR *LPMCI_AUDIO_BUFFER; ═══ AUDIO_BUFFER (43h) - Data Packet Format ═══ ┌───────────────────────────────────────────────┐ │Field C Datatype │ ├───────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_BUFFER │ └───────────────────────────────────────────────┘ ═══ AUDIO_BUFFER (43h) - Returns ═══ The amount of data is expressed as the number of bytes currently in the queues. Notice that the amount of queue data that this IOCtl returns is accurate only at the point in time this value is determined. The amount of queued data can be different at any other point in time. If the size of the buffer contents can be represented as an amount of time, that amount of time is returned in the fields ulReadBufTime and ulWriteBufTime. If not, the values returned are -1. To help determine the optimal size of the Read and Write kernel buffer queues, the maximum number of bytes that these queues have ever contained is returned in ulReadBufMax and ulWriteBufMax. Refer to the OS/2 Control Program Guide and Reference for 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 ═══ 16.1.5. AUDIO_LOAD (44h) - Load DSP Code ═══ ═══ AUDIO_LOAD (44h) - Description ═══ If the LOAD_CODE bit is set in the ulFlags field of the MCI_AUDIO_INIT structure on an AUDIO_INIT request, the application must load the DSP code (specified by the device driver in the abLoadPath field of MCI_AUDIO_INIT) into a buffer and issue an AUDIO_LOAD IOCtl request. ═══ AUDIO_LOAD (44h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_LOAD (44h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _load { CHAR FAR *pbBuffer; ULONG ulSize; ULONG ulFlags; } MCI_AUDIO_LOAD; typedef MCI_AUDIO_LOAD FAR *LPMCI_AUDIO_LOAD; ═══ AUDIO_LOAD (44h) - Data Packet Format ═══ ┌─────────────────────────────────────────────┐ │Field C Datatype │ ├─────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_LOAD │ └─────────────────────────────────────────────┘ ═══ AUDIO_LOAD (44h) - Remarks ═══ The pbBuffer field of the MCI_AUDIO_LOAD structure must point to the start of the buffer where the code is loaded. The ulSize field must be set to the number of bytes of loaded code (which is the size of the file). The ulFlags field permits loading the file in multiple pieces. To do this, the first piece is written with the LOAD_START flag set and the last piece with the LOAD_END flag set. All intermediate pieces have both flags cleared. To load the file in a single piece, both flags are set. Notice that the first buffer written must be at least 128 bytes in length. ═══ AUDIO_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 ═══ 16.1.6. AUDIO_WAIT (45h) - Suspend program operation ═══ ═══ 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 Reference for a description of the return code for DosDevIOCtl. ═══ AUDIO_WAIT (45h) - Remarks ═══ The actual playing of audio data by the audio device can occur after the Write call is returned to the caller. If the caller does not want to continue program execution until all data is actually played by the device, it can issue AUDIO_WAIT. Some audio devices play audio data in discrete blocks. Data is not played unless at least a full block of data is available. If less than a block of data remains to be played, AUDIO_WAIT can be called, which causes the audio device driver to pad the data with silence, thus permitting the data to be played. The amount of data in the buffers can be determined using AUDIO_BUFFER. AUDIO_WAIT does nothing if there are no prior calls to Write or AUDIO_HPI. Instead, it returns immediately to the caller. ═══ AUDIO_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 ═══ 16.1.7. AUDIO_HPI (46h) - Access high-performance interface ═══ ═══ 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 deivce driver's internal input and output buffers for higher bandwidth audio modes. ═══ AUDIO_HPI (46h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_HPI (46h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _hpi { VOID FAR *pvEntry (); VOID FAR *pvCallBack (); LPMCI_AUDIO_IOBUFFER prXBuff; LPMCI_AUDIO_IOBUFFER prRBuff; USHORT usFlags; } MCI_AUDIO_HPI; typedef MCI_AUDIO_HPI FAR *LPMCI_AUDIO_HPI; ═══ AUDIO_HPI (46h) - Data Packet Format ═══ ┌────────────────────────────────────────────┐ │Field C Datatype │ ├────────────────────────────────────────────┤ │Pointer to structure LPMCI_AUDIO_HPI │ └────────────────────────────────────────────┘ ═══ AUDIO_HPI (46h) - Returns ═══ An address is returned in pvEntry () in the MCI_AUDIO_HPI structure that can be used to invoke audio device driver functions directly. NULL is returned if this function is not available in the current environment. Refer to the OS/2 Control Program Guide and Reference for 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 ═══ 16.1.8. AUDIO_UPDATE (47h) - Update Buffer Information ═══ ═══ 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: o To condense the array of buffers by removing all buffers that have been processed from the array of buffers in the MCI_AUDIO_IOBUFFER data structure. o To add a buffer to the list. The address and length of the buffer is passed down to the device driver in the audio_update structure. ═══ AUDIO_UPDATE (47h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ AUDIO_UPDATE (47h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _audio_update { CHAR iobuf_type; CHAR FAR *buffer_address; ULONG buffer_length; USHORT rc; void FAR *reserved; } audio_update; typedef struct audio_update FAR *UPDATE; ═══ AUDIO_UPDATE (47h) - Data Packet Format ═══ ┌─────────────────────────────────────┐ │Field C Datatype │ ├─────────────────────────────────────┤ │Pointer to structure UPDATE │ └─────────────────────────────────────┘ ═══ AUDIO_UPDATE (47h) - Returns ═══ On exit, rc of the audio_update structure contains an error code if one of the DevHlp calls failed or the maximum number of buffers have already been queued. Refer to the OS/2 Control Program Guide and Reference for more information on the return code for DosDevIOCtl. ═══ AUDIO_UPDATE (47h) - Remarks ═══ To use this IOCtl, the application must use the high-performance interface. When AUDIO_HPI calls the device driver, an MCI_AUDIO_IOBUFFER structure with the maximum number of buffers that can be present must be passed. The iobuf->num_buffers field should have the maximum number of buffers in it. Notice that there is a limit of 16 buffers that can be present. It is not necessary for buffers passed in the buffer array of the MCI_AUDIO_IOBUFFER structure to contain addresses to buffers. Any or all of the buffers can point to NULL addresses and have lengths of 0. The device driver searches the list of the buffers, counts the number of non-NULL buffers, and sets the iobuf->num_buffers to this number. All internal variables are initialized to allow access to that number of buffers. AUDIO_HPI must be called again if this number changes. When AUDIO_UPDATE is called, it removes all buffers in the current MCI_AUDIO_IOBUFFER buffer array that have been processed. It then recalculates iobuf->num_buffers and iobuf->size (the total of all the buffer lengths). Notice that the buffer size must be an even number of bytes and less than 64KB in length. If the MCI_AUDIO_IOBUFFER structure to be updated is to be transmitted, it is assumed that the buffer passed is full of data to be played. The pHead pointer is updated to point to the beginning of the buffer following the buffer just added to the chain. The lCount field is also updated by the device driver to include this buffer of data. If buffer_address is NULL, this IOCtl simply frees processed buffers and returns. To free a buffer, the device driver unlocks it if it is locked and sets the length to 0. ═══ AUDIO_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 ═══ 16.1.9. AUDIO_CAPABILITY (48h) - Determine If a Group of Audio Settings is Supported ═══ ═══ 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _MCI_AUDIO_CAPS { ULONG ulLength; ULONG ulSamplingRate; ULONG ulChannels; ULONG ulBitsPerSample; ULONG ulDataType; ULONG ulOperation; ULONG ulSupport; ULONG ulDataSubType; ULONG ulResourceUnits; ULONG ulResourceClass; ULONG ulBlockAlign; BOOL fCanRecord; ULONG ulFlags; ULONG ulCapability; } MCI_AUDIO_CAPS; typedef MCI_AUDIO_CAPS FAR *PAUDIO_CAPS; ═══ AUDIO_CAPABILITY (48h) - Data Packet Format ═══ ┌────────────────────────────────────────┐ │Field C Datatype │ ├────────────────────────────────────────┤ │Pointer to structure PAUDIO_CAPS │ └────────────────────────────────────────┘ ═══ AUDIO_CAPABILITY (48h) - Returns ═══ SUPPORT_SUCCESS UNSUPPORTED_RATE UNSUPPORTED_CHANNELS UNSUPPORTED_BPS UNSUPPORTED_DATATYPE UNSUPPORTED_OPERATION ═══ AUDIO_CAPABILITY (48h) - Example Code ═══ The following example code illustrates an application querying the audio device driver for its capabilities. If the device supports the desired mode, the application saves the information. AUDIOCAPS audiocaps; audiocaps.ulSamplingRate = 11025; audiocaps.ulBitsPerSample = 16; audiocaps.ulChannels = 2; audiocaps.ulDataType = DATATYPE_WAVEFORM; MAKE1616(&audiocaps); rc = DosDevIOCtl( handle, AUDIO_IOCTL_CAT, AUDIO_CAPABILITY, 0, 0, 0, sizeof (audiocaps), &audiocaps, (PVOID) &ulParmLengthMax); if ( audiocaps.ulReturn ) { // process success } else // process failure ═══ AUDIO_CAPABILITY (48h) - Remarks ═══ This information supercedes the information found in the VSD resource file. If this IOCtl is supported, a VSD resource DLL is not necessary. The ulSamplingRate, ulChannels, ulBitsPerSample, and ulDataType fields of the MCI_AUDIO_CAPS structure must be filled in by the caller. The device driver will return SUPPORT_SUCCESS in the ulSupport field if it supports the combination and non-zero if it does not. If SUPPORT_SUCCESS is returned, the driver must also fill in the following fields of the MCI_AUDIO_CAPS structure: ulDataSubType. See valid subtypes in os2medef.h. ulResourceClass. See Resource Classes and Resource Units for more information. ulResourceUnits. See Resource Classes and Resource Units for more information. ulBlockAlign. Block alignment of the data. If ulSupport contains a non-zero value, the driver should fill in the MCI_AUDIO_CAPS structure with the nearest mode that matches the user's request (e.g. best-fit). The following fields must be updated for a best-fit: o ulSamplingRate o ulChannels o ulBitsPerSample o 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: o RESOURCEUNITS= o RESOURCECLASSES= o VALIDCOMBINATIONS= Because MMPM/2 allows many applications to simultaneously open the audio card, it uses the following keywords to determine which applications can simultaneously use the audio device. Although the numbers are arbitrary and are defined on a device-by-device basis, device driver writers should use the numbering scheme described below: The keyword RESOURCECLASSES indicates the different resource types available on the audio device. Vendors should provide a class for each data type that they support. For example, if the XYZ audio card can only play only PCM files, it would only have one resource class in the MMPM2.INI file, the PCM class. However, if the ABC card could play PCM, MIDI and ADPCM, it would have three classes in the MMPM2.INI file. The device driver should fill in the ulResourceClass field with the correct class for the current mode. The keyword RESOURCEUNITS indicates the maximum number of instances that can be active on the card at any particular time. For example, if the XYZ card mentioned above had the ability to play three PCM files at the same time, the RESOURCEUNITS in the MMPM2.INI file for this card would be three. In contrast, the ABC card can only play one PCM and one MIDI at any one time. Therefore, its resource units should be two in the MMPM2.INI file. The device driver should fill in the ulResourceUnits field of the AUDIO_CAPABILITY structure with the correct number of resources for the current mode (typically, one). The keyword VALIDCOMBINATIONS informs MMPM/2 which RESOURCECLASS can be active at the same time on the audio device. For example, the XYZ card mentioned above can only play PCM files so it has no valid combinations. By contrast, the ABC card can play MDI and PCM at the same time; therefore, the VALIDCOMBINATIONS statement would state that the MIDI class could be active at the same time the PCM class is active and vise-versa. The valid combinations information is static and does not need to be returned by the device driver. ═══ 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 ═══ 16.1.10. 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, head phones). The following IOCtls are new additions to the AUDIO IOCTL category: o MIX_GETCONNECTIONS o MIX_SETCONNECTIONS o MIX_GETLINEINFO o MIX_GETCONTROL o MIX_SETCONTROL ═══ 16.1.11. MIX_GETCONNECTIONS (60h) - Determine if 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _LINECONNECTIONS { ULONG ulLength; ULONG ulConnections; ULONG ulLine; } LINECONNECTIONS; typedef LINECONNECTIONS FAR *PLINECONNECTIONS; The caller is responsible for filling in the ulLine field of the LINECONNECTIONS structure. A bitmap describing the current connection structure will be returned in the ulConnections field. Each on bit indicates a connector which is enabled. For example, if the input line to be queried was set to 0 (i.e. the first line) and if that input line is connected to output line #0, bit 0 of ulConnections will be set. Logically, connection information can only be maintained for a mixer with a maximum of 32 inputs and 32 outputs. ═══ MIX_GETCONNECTIONS (60h) - Data Packet Format ═══ ┌─────────────────────────────────────────────┐ │Field C Datatype │ ├─────────────────────────────────────────────┤ │Pointer to structure PLINECONNECTIONS │ └─────────────────────────────────────────────┘ ═══ MIX_GETCONNECTIONS (60h) - Returns ═══ MIX_SUCCESS Successful operation. MIXERR_INVALIDSOURCE Invalid source specified. MIXERR_INVALIDSINK Invalid sink specified. MIXERR_INVALIDHANDLE Invalid handle specified. ═══ 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 ═══ 16.1.12. MIX_SETCONNECTIONS (61h) - 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _LINECONNECTIONS { ULONG ulLength; ULONG ulConnections; ULONG ulLine; } LINECONNECTIONS; typedef LINECONNECTIONS FAR *PLINECONNECTIONS; The caller is responsible for filling in the ulLine and ulConnections fields of the LINECONNECTIONS structure. ═══ MIX_SETCONNECTIONS (61h) - Data Packet Format ═══ ┌─────────────────────────────────────────────┐ │Field C Datatype │ ├─────────────────────────────────────────────┤ │Pointer to structure PLINECONNECTIONS │ └─────────────────────────────────────────────┘ ═══ MIX_SETCONNECTIONS (61h) - Returns ═══ MIX_SUCCESS Successful operation. MIXERR_INVALIDSOURCE Invalid source specified. MIXERR_INVALIDSINK Invalid sink specified. ═══ 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 ═══ 16.1.13. MIX_GETLINEINFO (62h) - Determine the Capabilities of a Line ═══ ═══ 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _MIXERLINEINFO { ULONG ulLength; ULONG ulNumChannels; ULONG ulSupport; ULONG ulConnectionsPossible; ULONG ulLine; } MIXERLINEINFO; typedef MIXERLINEINFO FAR *PMIXERLINEINFO; The caller is responsible for filling in the ulLine field of the MIXERLINEINFO structure. ═══ MIX_GETLINEINFO (62h) - Data Packet Format ═══ ┌──────────────────────────────────────────┐ │Field C Datatype │ ├──────────────────────────────────────────┤ │Pointer to structure MIXERLINEINFO │ └──────────────────────────────────────────┘ ═══ MIX_GETLINEINFO (62h) - Returns ═══ MIX_SUCCESS Successful operation. MIXERR_INVALIDSOURCE Invalid source specified. MIXERR_INVALIDSINK Invalid sink specified. ═══ 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 ═══ 16.1.14. MIX_GETCONTROL (63h) - Get Current State of a 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _MIXERCONTROL { ULONG ulLength; ULONG ulLine; ULONG ulControl; ULONG ulSetting; } MIXERCONTROL; typedef MIXERCONTROL FAR *PMIXERCONTROL; The caller is responsible for filling in the ulLine field of the MIXERCONTROL structure. The device driver should return the current setting of the line in the ulSetting field of the MIXERCONTROL structure. For stereo controls, the high-order word should contain information for the left-channel and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout. ═══ MIX_GETCONTROL (63h) - Data Packet Format ═══ ┌──────────────────────────────────────────┐ │Field C Datatype │ ├──────────────────────────────────────────┤ │Pointer to structure PMIXERCONTROL │ └──────────────────────────────────────────┘ ═══ MIX_GETCONTROL (63h) - Returns ═══ MIX_SUCCESS Successful operation. MIXERR_INVALIDSOURCE Invalid source specified. MIXERR_INVALIDSINK Invalid sink specified. ═══ 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 ═══ 16.1.15. MIX_SETCONTROL (64h) - Set State of a Mixer 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _MIXERCONTROL { ULONG ulLength; ULONG ulLine; ULONG ulControl; ULONG ulSetting; } MIXERCONTROL; typedef MIXERCONTROL FAR *PMIXERCONTROL; The caller is responsible for filling in the ulControl, the ulLine, and the ulSetting, fields of the MIXERCONTROL. The device driver should return the current setting of the line in ulSetting of the MIXERCONTROL structure. For stereo controls, the high-order word should contain information for the left-channel and the low-order word contains the right channel setting. A value of 0xFFFF represents full intensity and a value of 0x0000 is full cutout. ═══ MIX_SETCONTROL (64h) - Data Packet Format ═══ ┌──────────────────────────────────────────┐ │Field C Datatype │ ├──────────────────────────────────────────┤ │Pointer to structure PMIXERCONTROL │ └──────────────────────────────────────────┘ ═══ MIX_SETCONTROL (64h) - Returns ═══ MIX_SUCCESS Successful operation. MIXERR_INVALIDSOURCE Invalid source specified. MIXERR_INVALIDSINK Invalid sink specified. ═══ 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 ═══ 16.2. 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_INIT example. #define INCL_DOSDEVICES #include #include #include /* Defines for flags, and so forth */ init_adpcmv(Handle) /* Initialize to record ADPCM voice */ HFILE Handle; /* Handle returned from DosOpen() */ { struct audio_init buffer; /* I/O buffer (defined in audiodd.h) */ USHORT rc; buffer.srate = 11025; /* Set rate = Voice mode */ buffer.bits_per_sample = 16; /* 16-bits per sample */ buffer.bsize = 576; /* Size of Voice mode data block */ buffer.mode = ADPCM; /* ADPCM mode */ buffer.channels = 1; /* Mono */ buffer.flags = FIXED; /* Fixed block size data */ buffer.operation = RECORD; /* Set up to record */ buffer.version_level = 0x01000018; /* Set version level */ rc = DosDevIOCtl(Handle, AUDIO_IOCTL_CAT, AUDIO_INIT, NULL, 0L, &ParmLengthInOut, &buffer, (LONG)sizeof(buffer), &lDataLengthInOut); if(rc) return(rc); } Under DOS, IOCtls are called by using INT 21h Function 44h. The following is a DOS IOCtl example. INCLUDE AUDIODD.INC ; Audio DD equates /abort ; Read the queue status using AUDIO_BUFFER IOCtl Handle DW ? ; Handle to open device (MIDIn$) Buffer ; I/O Buffer FLAGS DD 0 ; Error condition flags READ_BUF_SIZE DD 0 ; Number of bytes currently in ; Receive queue WRITE_BUF_SIZE DD 0 ; Number of bytes currently in ; Transmit queue READ_BUF_TIME DD 0 ; Amount of data in Receive queue ; in millisecs WRITE_BUF_TIME DD 0 ; Amount of data in Transmit queue ; in millisecs READ_BUF_MAX DD 0 ; Maximum number of bytes ever in ; Read queue WRITE_BUF_MAX DD 0 ; Maximum number of bytes ever in ; Write queue POSITION DD 0 ; Time count since beginning of ; operation POSITION_TYPE DD 0 ; Specifies the type of position ; units READ_BUF_CAP DD 0 ; Capacity of Receive queue; -1 if ; variable WRITE_BUF_CAP DD 0 ; Capacity of Write queue; -1 if ; variable REQUEST_BUF_CAP DD 0 ; Maximum number of requests that ; can be queued Query_Q_Status: MOV AH,44h ; Function call - IOCtl MOV AL,0Ch ; Indicate generic IOCtl request MOV BX,Handle ; Select audio device handle (from ; previous OPEN) MOV CH,80h ; Generic IOCtl category MOV CL,40h+AUDIO_BUFFER ; Generic IOCtl Function ID MOV DX,Offset Buffer ; DS:DX points to buffer INT 21h ; Issue request to DOS JC Error ; Error code in AX if C set . . . ═══ 16.3. M-Audio MCI_AUDIO_INIT Parameters ═══ The following table lists the MCI_AUDIO_INIT parameters for the operating modes currently supported by the IBM M-Audio Capture and Playback Adapter. ┌───────────────┬───────────────┬────┬───────────────┬───┬──────┬──────────┐ │Description │Mode │Bits│Sample rate │No.│Block │Flags │ │ │ │per │ │Cha│size │ │ │ │ │Samp│ │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │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 │ADPCM │16 │44100 │1 │1128 │Fixed │ │Quality │ │ │ │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │8 bit PCM │PCM │8 │8000, 11025, │1 │560 │0 │ │ │ │ │22050, 44100 │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │8 bit PCM │PCM │8 │8000, 11025, │2 │560 │0 │ │stereo │ │ │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 │MU_LAW │8 │8000, 11025, │1 │560 │0 │ │mono │ │ │22050, 44100 │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │8 bit mu-law │MU_LAW │8 │8000, 11025, │2 │560 │0 │ │stereo │ │ │22050 │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │8 bit A-law │A_LAW │8 │8000, 11025, │1 │560 │0 │ │mono │ │ │22050, 44100 │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │8 bit A-law │A_LAW │8 │8000, 11025, │2 │560 │0 │ │stereo │ │ │22050 │ │ │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │Claim Hardware │CLAIM_HDWR │- │- │- │- │- │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │Source Mix │SOURCE_MIX │- │- │- │- │- │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │Speech Viewer/2│SPV2BCPCM │16 │14700 │- │426 tx│0 │ │BCPCM │ │ │ │ │/ 426 │ │ │ │ │ │ │ │rx │ │ ├───────────────┼───────────────┼────┼───────────────┼───┼──────┼──────────┤ │Speech Viewer/2│SPV2PCM │16 │14700 │- │964 tx│0 │ │PCM │ │ │ │ │/ 2 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 │ └───────────────┴───────────────┴────┴───────────────┴───┴──────┴──────────┘ ═══ 16.4. Video IOCtl Functions ═══ The video IOCtls are used to set video attributes (such as brightness, hue, and saturation). 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. Video images can be captured one frame at a time when directed by the application. This type of capture mode is referred to as asymmetric capture because the time between successive frames is not constant. The frame rate is determined by the length of time that the application delays between taking image snapshots. Asymmetric capture is performed with IOCtls only; the MMPM/2 streaming mechanism is not used. Typically, a stream is established to read a series of moving images from the device. This continuous capture mode is called symmetric or real-time capture, and is done at a constant frame rate and constant frame size. When established, a stream captures images continuously without assistance from the application code. A running stream cannot dynamically alter frame rate or size, but video quality attributes such as brightness, hue, and contrast can be altered dynamically. Streaming capture is used to make real-time movies and to monitor live video on frame-grabber cards. 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. ═══ 16.4.1. VCAI_INIINFO (60h) - Setup Information from 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 ═══ 16.4.2. VCAI_SAVE (61h) - Save Device State ═══ ═══ 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 ownership of the device at any time. This IOCtl is issued when a process is about to lose ownership of the device and needs to save the state of the device before relinquishing ownership. ═══ 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 ═══ 16.4.3. VCAI_RESTORE (62h) - Restore Device State ═══ ═══ 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 ═══ 16.4.4. VCAI_LOAD_MICROCODE (63h) - Query/Load/Unload Microcode ═══ ═══ VCAI_LOAD_MICROCODE (63h) - Description ═══ This IOCtl allows the device to be loaded with micro code, if needed. As soon as the current image format is set via VCAI_RESTORE_FORMAT and/or VCAI_CAPTURE_FORMAT, the device may require micro code to be loaded onto the card. The command allows the micro code's file name to be queried and the micro code to be loaded and later unloaded, if needed. The VSD (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 structure The data packet parameter is a pointer to the following data structure. typedef struct _VCALOAD { ULONG ulflags; CHAR ProdInfo[256]; LONG ulLoadID; ULONG ulLength; PVOID pLoadData; } VCALOAD; typedef VCALOAD FAR * PVCALOAD; ═══ 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 ═══ 16.4.5. VCAI_RESTORE_FORMAT (64h) - Query/Set Image Restore Format ═══ ═══ VCAI_RESTORE_FORMAT (64h) - Description ═══ This IOCtl is used to query the image formats supported by the device and to query the current image format. It may also be used to set the current image format. Note: Image format (fourCC) refers to the type of data that will be passed to the device on the VCAI_PLAY IOCtl. ═══ VCAI_RESTORE_FORMAT (64h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_RESTORE_FORMAT (64h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _VCAIMAGERF { ULONG ulFlags; ULONG ulNumFormats; ULONG ulCurIndex; ULONG FourCC[64]; } VCAIMAGERF; typedef VCAIMAGERF FAR * PVCAIMAGERF; ═══ 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 ═══ 16.4.6. VCAI_CAPTURE_FORMAT (65h) - Query/Set Image Capture Format ═══ ═══ VCAI_CAPTURE_FORMAT (65h) - Description ═══ This IOCtl is used to query the devices supported image capture formats, query the current image capture format, and set the current image capture format. This image format will be returned on VCAI_GETIMAGESCALE and on the SHD_READ_COMPLETE flag (of the ulFlag parameter of the SHD_REPORTINT structure) through the IDC streaming interface. ═══ VCAI_CAPTURE_FORMAT (65h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_CAPTURE_FORMAT (65h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _VCAIMAGECF { ULONG ulFlags; ULONG ulNumFormats; ULONG ulCurIndex; ULONG FourCC[64]; } VCAIMAGECF; typedef VCAIMAGECF FAR * PVCAIMAGECF; ═══ 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 ═══ 16.4.7. VCAI_PLAY (67h) - Restore/Play Image to the Screen ═══ ═══ 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 pImageData is determined by the VCAI_RESTORE_FORMAT IOCtl and the source and destination image size is determined by the VCAI_SETCAPTRECT If the device supports this command, the CanRestore flag in the VCADEVINFO structure should be set to 1. ═══ VCAI_PLAY (67h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_PLAY (67h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCASTREAM { ULONG ulLength; PVOID pImageData; ULONG ulFlags; ULONG ulSCR; ULONG ulPTS; ULONG ulAudioTime; } VCASTREAM; typedef VCASTREAM FAR * PVCASTREAM; ═══ 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 ═══ 16.4.8. VCAI_QUERYVIDEOSIGNAL (68h) - Query Video Input Connector's Signal ═══ ═══ 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. ═══ 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 ═══ 16.4.9. VCAI_TUNERCHANNEL (69h) - Set/Query Tuner Channel ═══ ═══ VCAI_TUNERCHANNEL (69h) - Description ═══ This IOCtl is used to change channels on the TV tuner or query the correct tuner frequency. If the device support TV tuner functions, the HasTuner flag should be set to 1 in the VCADEVINFO structure. ═══ VCAI_TUNERCHANNEL (69h) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_TUNERCHANNEL (69h) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCATUNCHAN { ULONG ulFlags; ULONG ulOptions; USHORT usResv01; USHORT usResv02; LONG lFineTune; ULONG ulFrequency; } VCATUNCHAN; typedef VCATUNCHAN FAR * PVCATUNCHAN; ═══ 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_SKIP 8 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 ═══ 16.4.10. VCAI_VIDEOINPUT (6Ah) - Set/Query Video Input Source Connector ═══ ═══ VCAI_VIDEOINPUT (6Ah) - Description ═══ This IOCtl sets or queries the 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 structure The 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 ═══ 16.4.11. VCAI_SETCAPTRECT (6Bh) - Set Source and Destination Capture/Restore Rectangles ═══ ═══ VCAI_SETCAPTRECT (6Bh) - Description ═══ This IOCtl sets up streaming capture of images from the video capture device to buffers provided by the DDCMD_READ message. The portion of the source image to be captured is determined by the size of the destination image. This command does not start the capture. It specifies the source and destination. Streaming capture is started using the DDCMD_START flag of the ulCmd parameter of the DDCMDCONTROL structure. The destination X_LEFT and Y_TOP are used only for overlay adapters to control where the overlay image is placed on the screen. If the device is being used for play back instead of capture as discussed above, source refers to the size of the image that is to be restored and dest (destination) refers to where the image is to be placed. Instead of the DDCMD message discussed above, the image data is passed to the device driver via the VCAI_PLAY IOCtl. ═══ VCAI_SETCAPTRECT (6Bh) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_SETCAPTRECT (6Bh) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following data structure. typedef struct _VCASETCAPTURERECT { ULONG Source_X_Left; ULONG Source_Y_Top; ULONG Source_Y_Height; ULONG Source_X_Width; ULONG Dest_X_Left; ULONG Dest_Y_Top; ULONG Dest_Y_Height; ULONG Dest_X_Width; } VCASETCAPTURERECT; typedef VCASETCAPTURERECT FAR * PVCASETCAPTURERECT; ═══ 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 ═══ 16.4.12. VCAI_GETIMAGESCALE (6Ch) - Get Image and Scale into RAM Buffer ═══ ═══ 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 must ensure that the source and destination frame dimensions are less than or equal to the maximum size of the capture frame. Use VCAI_GETDEVINFO to determine the maximum image extents. Specific device drivers might place restrictions on how scaling from the source frame to the destination frame can occur. ═══ VCAI_GETIMAGESCALE (6Ch) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_GETIMAGESCALE (6Ch) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCAGETIMAGESCALE { ULONG Capture_Buf_Len; ULONG Capture_Buf_Ptr; ULONG Source_X_Left; ULONG Source_Y_Top; ULONG Source_Y_Height; ULONG Source_X_Width; ULONG Dest_X_Left; ULONG Dest_Y_Top; ULONG Dest_Y_Height; ULONG Dest_X_Width; } VCAGETIMAGESCALE; typedef VCAGETIMAGESCLAE FAR * PVCAGETIMAGESCALE; ═══ 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 not support all the transposition and scaling possibilities supported with this IOCtl. Consult the specific device driver's documentation for limitations, or use VCAI_GETDEVINFO to determine its capabilities. ═══ VCAI_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 ═══ 16.4.13. VCAI_GETDEVINFO (6Dh) - Get Device Information ═══ ═══ 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 structure The data packet parameter is a pointer to the following data structure. typedef struct _vcadevinfo { ULONG Length; CHAR ProdInfo[30]; CHAR ManInfo[30]; CHAR Version[10]; ULONG ImgFormat; USHORT BitsPerPEL; USHORT Overlay; ULONG Brightness; ULONG hue; ULONG saturation; ULONG contrast; ULONG Sharpness; ULONG unused1; ULONG S_X_Left; ULONG S_Y_Top; ULONG S_Y_Height; ULONG S_X_Width; ULONG D_X_Left; ULONG D_Y_Top; ULONG D_Y_Height; ULONG D_X_Width; ULONG D_ScaleFactor; ULONG S_X_MAX; ULONG S_Y_MAX; ULONG D_X_MAX; ULONG D_Y_MAX; ULONG O_X_MAX; ULONG O_Y_MAX; USHORT VideoInputs; USHORT CanRestore; USHORT CanStretch; USHORT CanDistort; USHORT HasVolume; USHORT HasBalance; USHORT CanScale; USHORT CanStream; ULONG DI_ulFilenum; BYTE HasTuner; BYTE HasTeleTex; LONG Delay_Time; BYTE HasAFC; BYTE HasPolarization; } VCADEVINFO; typedef VCADEVINFO FAR * PVCADEVINFO; ═══ 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 ═══ 16.4.14. VCAI_VALIDRECT (6Eh) - Validate Video Rectangle ═══ ═══ VCAI_VALIDRECT (6Eh) - Description ═══ This IOCtl modifies the source X_Width and source Y_Height to a valid size determined by the destination rectangle information. This IOCtl compensates for video capture adapters that do not support scaling images from a given source destination rectangle. The media control driver uses this information to center the source rectangle on the area in the original source rectangle. ═══ VCAI_VALIDRECT (6Eh) - Parameter Packet Format ═══ Not used. The packet pointer must be NULL. ═══ VCAI_VALIDRECT (6Eh) - Pointer to structure ═══ Pointer to structure The data packet parameter is a pointer to the following structure. typedef struct _VCACAPISIZE { ULONG X_Left; ULONG Y_Top; ULONG Y_Height; ULONG X_Width; ULONG ScaleFactor; } VCACAPISIZE; typedef VCACAPISIZE FAR * PVCACAPISIZE; ═══ 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 ═══ 16.4.15. VCAI_UNFREEZE (72h) - Unfreeze the Image Digitizer ═══ ═══ 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 ═══ 16.4.16. VCAI_FREEZE (74h) - Freeze the Image Digitizer ═══ ═══ VCAI_FREEZE (74h) - Description ═══ This IOCtl tells the video device to capture/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 ═══ 16.4.17. VCAI_VIDEOADJ (75h) - Set/Query Video Adjustments ═══ ═══ 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 structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETVIDEO { ULONG set_brightness; ULONG set_hue; ULONG set_saturation; ULONG set_contrast; ULONG ret_brightness; ULONG ret_hue; ULONG ret_saturation; ULONG ret_contrast; } VCASETVIDEO; typedef VCASETVIDEO FAR * PVCASETVIDEO; ═══ 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 ═══ 16.4.18. VCAI_SETFPS (76h) - Set Frame Rate for Streaming ═══ ═══ 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 structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETFPS { ULONG set_FPS; ULONG ulFlags; } VCASETFPS; typedef VCASETFPS FAR * PVCASETFPS; ═══ 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 ═══ 16.4.19. VCAI_USER (79h) - Pass Device-Specific Commands to Device Driver ═══ ═══ 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 ═══ 16.4.20. VCAI_SETMONITOR (80h) - Enable/Disable Overlay Monitor ═══ ═══ 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 structure The data packet parameter is a pointer to the following structure. typedef struct _VCASETMONITOR { BOOL bMonitor; } VCASETMONITOR; typedef VCASETMONITOR FAR * PVCASETMONITOR; ═══ VCAI_SETMONITOR (80h) - Data Packet Format ═══ ┌───────────────────────────────────────────┐ │Field C Datatype │ ├───────────────────────────────────────────┤ │Pointer to structure PVCASETMONITOR │ └───────────────────────────────────────────┘ ═══ VCAI_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 ═══ 16.4.21. VCAI_EDCOLORKEY (81h) - Enable/Disable Transparent Color ═══ ═══ 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 structure The 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 ═══ 16.4.22. VCAI_SETCOLORKEY (82h) - Set Color Key/Transparent Color ═══ ═══ 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 structure The 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 ═══ 17. Data Types ═══ This section describes data types in C language. ═══ 17.1. audio_update ═══ This structure contains fields for the AUDIO_UPDATE IOCtl. typedef struct _audio_update { CHAR iobuf_type; /* Transmit or receive. */ CHAR FAR *buffer_address; /* Address of buffer be added. */ ULONG buffer_length; /* Length of buffer to be added. */ USHORT rc; /* Return code. */ void FAR *reserved; /* Reserved. */ } audio_update; typedef struct audio_update FAR *UPDATE; ═══ audio_update Parameter - iobuf_type ═══ iobuf_type (CHAR) Transmit or receive iobuf. The defined values for this field are: XMIT_IOBUF 0 REC_IOBUF 1 ═══ audio_update Parameter - buffer_address ═══ buffer_address (CHAR FAR *) Address of buffer be added. ═══ audio_update Parameter - buffer_length ═══ buffer_length (ULONG) Length of buffer to be added. ═══ audio_update Parameter - rc ═══ rc (USHORT) Return code. The following values are defined for rc. MAX_NUM_BUFFERS_REACHED 9 UPDATE_GENERAL_FAILURE 10 INVALID_BUFFER_LENGTH 11 ═══ audio_update Parameter - reserved ═══ reserved (void FAR *) Reserved. ═══ 17.2. BOOL ═══ Boolean. Valid values are FALSE, which is 0, and TRUE, which is 1. typedef unsigned long BOOL; ═══ 17.3. BYTE ═══ A byte. typedef unsigned char BYTE; ═══ 17.4. CHAR ═══ Single-byte character. #define CHAR char ═══ 17.5. CONTROL_PARM ═══ This data structure contains fields for the pParm and ulParmSize fields of the DDCMDCONTROL data structure. typedef struct _CONTROL_PARM { ULONG ulTime; /* Time in milliseconds. */ } CONTROL_PARM; ═══ CONTROL_PARM Parameter - ulTime ═══ ulTime (ULONG) Specifies the time in milliseconds. The stream handler sets the cue time when the ulCmd field of the DDCMDCONTROL data structure is DDCMD_ENABLE_EVENT. The PDD returns the current time for DDCMD_STOP and DDCMD_PAUSE. ═══ 17.6. DDCMDCOMMON ═══ This data structure contains common fields between all DDCMD data structures. typedef struct _ddcmd_common_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Data stream instance. */ } DDCMDCOMMON; ═══ DDCMDCOMMON Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDCOMMON Parameter - hStream ═══ hStream (HSTREAM) Specifies the data stream instance for this event. ═══ 17.7. DDCMDCONTROL ═══ This data structure contains fields for the DDCMD_CONTROL message. typedef struct _ddcmd_control_parm { ULONG ulFunction; /* Function requested. */ HSTREAM hStream; /* Stream handle. */ HEVENT hEvent; /* Event handle. */ ULONG ulCmd; /* Flags. */ PVOID pParm; /* Pointer to CONTROL_PARM. */ ULONG ulParmSize; /* See CONTROL_PARM. */ } DDCMDCONTROL; ═══ DDCMDCONTROL Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDCONTROL Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event. ═══ DDCMDCONTROL Parameter - hEvent ═══ hEvent (HEVENT) Event handle. ═══ DDCMDCONTROL Parameter - ulCmd ═══ ulCmd (ULONG) Defines the following flags: DDCMD_START Starts a device. DDCMD_STOP Stops a device and returns the current stream time in milliseconds. All buffers in the PDD are flushed and everything is reset to 0. The device driver sends the current stream time back to the stream handler in milliseconds (using the pParm and ulParmSize fields). For example, return a ULONG of stream time (in milliseconds) and the ULONG of 4 bytes is input in the ulParmSize field. DDCMD_PAUSE Pauses the device and returns the current stream time in milliseconds. Unlike DDCMD_STOP, DDCMD_PAUSE is not destructive. The device driver is able to resume its function at a later time, exactly where it was paused. DDCMD_ PAUSE returns the current stream time in milliseconds within the pParm field. DDCMD_RESUME Resumes a currently paused stream. DDCMD_RESUME is only honored if the stream was paused previously. If the stream was stopped and the stream handler issues DDCMD_RESUME, an ERROR_INVALID_SEQUENCE is returned. DDCMD_ENABLE_EVENT Enables event detection if your PDD supports events. The event message is sent to the device driver and reviews the structure. The hEvent field is a unique handle that signifies the event. pParm contains the stream time with which the event should be detected. This command would be honored whether currently in a streaming state, pause, or stop. For example, a stream handler is programmed to be detected at 1000 milliseconds in the stream. It sends a DDCMD_ENABLE_EVENT to the device driver with a unique handle event (hEvent) and 1000 milliseconds stated in the pParm field. The device driver obtains the handle event, makes sure there are no duplicate entries, and adds the hEvent to a link list or array (depending on how the device driver is implemented). The device driver now knows it must report an event back to the stream handler when 1000 milliseconds has been reached in the stream. See SHD_REPORT_EVENT for further information. DDCMD_DISABLE_EVENT Disables event detection in the device driver. An event handle is passed from the structure. The device driver searchs its linked list or array to find the matching event handle and deletes it from the list. DDCMD_PAUSE_TIME Pauses the time but not the stream. DDCMD_RESUME_TIME Resumes the time. ═══ DDCMDCONTROL Parameter - pParm ═══ pParm (PVOID) Pointer to the CONTROL_PARM data structure. ═══ DDCMDCONTROL Parameter - ulParmSize ═══ ulParmSize (ULONG) Size of the CONTROL_PARM data structure. ═══ 17.8. DDCMDDEREGISTER ═══ This data structure contains fields for the DDCMD_DEREG_STREAM message. typedef struct _ddcmd_deregister_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Stream handle. */ } DDCMDDEREGISTER; ═══ DDCMDDEREGISTER Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDDEREGISTER Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle needed at interrupt time. ═══ 17.9. DDCMDREADWRITE ═══ This data structure contains fields for the DDCMD_READ and DDCMD_WRITE messages. typedef struct _ddcmd_readwrite_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Stream handle. */ PVOID pBuffer; /* Buffer pointer. */ ULONG ulBufferSize; /* Buffer size. */ PVOID pProcessLin; /* Process linear record pointer. */ } DDCMDREADWRITE; ═══ DDCMDREADWRITE Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDREADWRITE Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event. ═══ DDCMDREADWRITE Parameter - pBuffer ═══ pBuffer (PVOID) Buffer pointer of the empty buffer that the device driver fills from its record operation. ═══ DDCMDREADWRITE Parameter - ulBufferSize ═══ ulBufferSize (ULONG) Specifies the buffer size of the empty buffer. ═══ DDCMDREADWRITE Parameter - pProcessLin ═══ pProcessLin (PVOID) Provides the 32-bit process linear address to a Ring 3 stream handler so the stream handler will have access to the buffers if a GDT or physical address is requested. ═══ 17.10. DDCMDREGISTER ═══ This data structure contains fields for the DDCMD_REG_STREAM message. typedef struct _ddcmd_register_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Stream handle. */ ULONG ulSysFileNum; /* Device handle. */ PSHDFN pSHDEntryPoint; /* Stream handler entry point. */ ULONG ulStreamOperation; /* Stream operation. */ SPCBKEY spcbkey; /* Input to the VSD or PDD (optional) buffer size. */ ULONG ulBufSize; /* VSD or PDD output (optional) buffer size in bytes. */ ULONG ulNumBufs; /* VSD or PDD output (optional) # of buffers for SPCB. */ ULONG ulAddressType; /* VSD or PDD output (required) addr ptr type to data buffer. */ ULONG ulBytesPerUnit; /* VSD or PDD output (unused, set to zero). */ MMTIME mmtimePerUnit; /* VSD or PDD output (Unused, set to zero). */ E_DCB dcbAudio; /* Stream handler DCB. */ HID hid; /* Stream handler ID. */ } DDCMDREGISTER; ═══ DDCMDREGISTER Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDREGISTER Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle needed at interrupt time. ═══ DDCMDREGISTER Parameter - ulSysFileNum ═══ ulSysFileNum (ULONG) Specifies the device handle so the VSD or PDD can map the device instance to hStream. This field has to map with how the device has been initialized during AUDIO_INIT. ═══ DDCMDREGISTER Parameter - pSHDEntryPoint ═══ pSHDEntryPoint (PSHDFN) Specifies the stream handler entry point so that the device driver can call back into the stream handler during streaming time to report interrupts and events. ═══ DDCMDREGISTER Parameter - ulStreamOperation ═══ ulStreamOperation (ULONG) Specifies the stream operation (record or playback). The device driver should verify with how it has been initialized through IOCtls. The following stream operations are defined (VSDs should verify with VSD_SET or VSD_OPEN settings): STREAM_OPERATION_CONSUME Playback. STREAM_OPERATION_PRODUCE Record. ═══ DDCMDREGISTER Parameter - spcbkey ═══ spcbkey (SPCBKEY) Specifies input to the VSD or PDD (optional) buffer size. ═══ DDCMDREGISTER Parameter - ulBufSize ═══ ulBufSize (ULONG) Specifies VSD or PDD output (optional) buffer size in bytes for SPCB. ═══ DDCMDREGISTER Parameter - ulNumBufs ═══ ulNumBufs (ULONG) Specifies VSD or PDD output (optional) number of buffers for SPCB. ═══ DDCMDREGISTER Parameter - ulAddressType ═══ ulAddressType (ULONG) Specifies VSD or PDD output (required) address pointer type to data buffer. The VSD or PDD tells the stream handler what type of address pointer it expects the data buffer to be. The stream handler then requests this address type to the SSM, so that the Sync/Stream Manager will send the correct type for each buffer request. ADDRESS_TYPE_VIRTUAL 0 ADDRESS_TYPE_PHYSICAL 1 ADDRESS_TYPE_LINEAR 2 ═══ DDCMDREGISTER Parameter - ulBytesPerUnit ═══ ulBytesPerUnit (ULONG) Specifies VSD or PDD output (unused, set to zero). Device driver timing. ═══ DDCMDREGISTER Parameter - mmtimePerUnit ═══ mmtimePerUnit (MMTIME) Specifies VSD or PDD output. Device driver timing. (Unused, set to zero.) ═══ DDCMDREGISTER Parameter - dcbAudio ═══ dcbAudio (E_DCB) Specifies the input stream handler device control block (DCB). ═══ DDCMDREGISTER Parameter - hid ═══ hid (HID) Specifies the input stream handler ID. ═══ 17.11. DDCMDSETUP ═══ This data structure contains fields for the DDCMD_SETUP message. typedef struct _ddcmd_setup_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Stream handle. */ PSETUP_PARM pSetupParm; /* Pointer to SETUP_PARM. */ ULONG ulSetupParmSize; /* Size of SETUP_PARM. */ } DDCMDSETUP; ═══ DDCMDSETUP Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDSETUP Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event. ═══ DDCMDSETUP Parameter - pSetupParm ═══ pSetupParm (PSETUP_PARM) Points to the SETUP_PARM data structure. ═══ DDCMDSETUP Parameter - ulSetupParmSize ═══ ulSetupParmSize (ULONG) The size of the SETUP_PARM data structure. ═══ 17.12. DDCMDSTATUS ═══ This data structure contains fields for the DDCMD_STATUS message. typedef struct _ddcmd_status_parm { ULONG ulFunction; /* Function requested by stream handler. */ HSTREAM hStream; /* Stream handle. */ PSTATUS_PARM pStatus; /* Pointer to STATUS_PARM. */ ULONG ulStatusSize; /* Size or position time. */ } DDCMDSTATUS; ═══ DDCMDSTATUS Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the stream handler. ═══ DDCMDSTATUS Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle that identifies the stream instance for this event. ═══ DDCMDSTATUS Parameter - pStatus ═══ pStatus (PSTATUS_PARM) A pointer to the current position time as output. See STATUS_PARM. ═══ DDCMDSTATUS Parameter - ulStatusSize ═══ ulStatusSize (ULONG) Specifies the size or position time as output. ═══ 17.13. E_DCB ═══ This structure contains device-specific information. It is used at stream creation by the application media control device to deliver device-specific information to the source or target stream handlers. typedef struct _E_DCB { ULONG ulDCBLen; /* Length of structure. */ SZ szDevName[MAX_SPI_NAME]; /* Device driver name. */ ULONG ulSysFileNum; /* File handle number. */ } E_DCB; typedef E_DCB FAR *PE_DCB; ═══ E_DCB Parameter - ulDCBLen ═══ ulDCBLen (ULONG) Length of the device control block. ═══ E_DCB Parameter - szDevName[MAX_SPI_NAME] ═══ szDevName[MAX_SPI_NAME] (SZ) Identifies the device driver that the stream handler connects to for a particular stream instance. For stream handler device drivers, inter-device communication (IDC) is used to call the physical device driver. The device driver name must not be more than eight characters (excluding the file extension). ═══ E_DCB Parameter - ulSysFileNum ═══ ulSysFileNum (ULONG) File handle number. ═══ 17.14. HEVENT ═══ Event handle. typedef ULONG HEVENT; ═══ 17.15. HID ═══ Stream handler ID. typedef ULONG HID; ═══ 17.16. HSTREAM ═══ Stream handle. typedef ULONG HSTREAM; ═══ 17.17. HVSD ═══ VSD handle. typedef PVOID HVSD; ═══ 17.18. HWND ═══ Window handle. typedef LHANDLE HWND; ═══ 17.19. LINECONNECTIONS ═══ This structure contains data for the VSD_QUERYMIXCONNECTIONS and the VSD_SETMIXCONNECTIONS messages, and the MIX_GETCONNECTIONS and MIX_SETCONNECTIONS IOCtls. typedef struct _LINECONNECTIONS { ULONG ulLength; /* Length of the structure. */ ULONG ulConnections; /* Connection information. */ ULONG ulLine; /* Line to get connections information for. */ } LINECONNECTIONS; typedef LINECONNECTIONS FAR *PLINECONNECTIONS; ═══ LINECONNECTIONS Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ LINECONNECTIONS Parameter - ulConnections ═══ ulConnections (ULONG) Line(s) that ulLine is connected to. Valid flags are: SINK_LINE_OUT Line out connection. SINK_SPEAKER Speaker connection. SINK_HEADPHONES Headphones connection. SINK_GENERIC Generic connection. SINK_NULL Null connection. ═══ LINECONNECTIONS Parameter - ulLine ═══ ulLine (ULONG) Line to get connections information for. The line described in ulLine field can have the following values: SOURCE_SYNTHESIZER Midi connection. SOURCE_MIXER Source mixer connection. SOURCE_LINE Line connection. SOURCE_INTERNAL_AUDIO Internal audio connection. SOURCE_MICROPHONE Microphone connection. SOURCE_WAVE Wave connection. SOURCE_PC_SPEAKER PC speaker connection. ═══ 17.20. LONG ═══ Signed integer in the range -2 147 483 648 through 2 147 483 647. #define LONG long Note: Where this data type represents a graphic coordinate in world or model space, its value is restricted to -134 217 728 through 134 217 727. A graphic coordinate in device or screen coordinates is restricted to -32 768 through 32 767. The value of a graphic coordinate may be further restricted by any transforms currently in force, including the positioning of the origin of the window on the screen. In particular, coordinates in world or model space must not generate coordinate values after transformation (that is, in device or screen space) outside the range -32 768 through 32 767. ═══ 17.21. MCI_AUDIO_BUFFER ═══ This structure contains fields for the AUDIO_BUFFER function. typedef struct _buffer { ULONG ulFlags; /* Indicates error condition. */ ULONG ulReadBufSize; /* Data in Read queue. */ ULONG ulWriteBufSize; /* Data in Write queue. */ ULONG ulReadBufTime; /* Data in Read queue (in ms). */ ULONG ulWriteBufTime; /* Data in Write queue (in ms). */ ULONG ulReadBufMax; /* Max. data in Read queue. */ ULONG ulWriteBufMax; /* Max. data in Write queue. */ ULONG ulPosition; /* Position. */ ULONG ulPositionType; /* Type of position units. */ LONG lReadBufCap; /* Capacity of Read queue. */ LONG lWriteBufCap; /* Capacity of Write queue. */ LONG lRequestBufCap; /* Max. # of requests. */ } MCI_AUDIO_BUFFER; typedef MCI_AUDIO_BUFFER FAR *LPMCI_AUDIO_BUFFER; ═══ MCI_AUDIO_BUFFER Parameter - ulFlags ═══ ulFlags (ULONG) Indicates an error condition occurred. The possible error states that can be flagged are: AUDIO_UNDERRUN 1 AUDIO_OVERRUN 2 ═══ MCI_AUDIO_BUFFER Parameter - ulReadBufSize ═══ ulReadBufSize (ULONG) Amount of data in Read queue in bytes. ═══ MCI_AUDIO_BUFFER Parameter - ulWriteBufSize ═══ ulWriteBufSize (ULONG) Amount of data in Write queue in bytes. ═══ MCI_AUDIO_BUFFER Parameter - ulReadBufTime ═══ ulReadBufTime (ULONG) Amount of data in Read queue in milliseconds. ═══ MCI_AUDIO_BUFFER Parameter - ulWriteBufTime ═══ ulWriteBufTime (ULONG) Amount of data in Write queue in milliseconds. ═══ MCI_AUDIO_BUFFER Parameter - ulReadBufMax ═══ ulReadBufMax (ULONG) Maximum number of bytes ever in Read queue. ═══ MCI_AUDIO_BUFFER Parameter - ulWriteBufMax ═══ ulWriteBufMax (ULONG) Maximum number of bytes ever in Write queue. ═══ MCI_AUDIO_BUFFER Parameter - ulPosition ═══ ulPosition (ULONG) Time count since beginning of operation. ═══ MCI_AUDIO_BUFFER Parameter - ulPositionType ═══ ulPositionType (ULONG) Specifies the type of position units. The defined values for this field are: POS_MSECS 0 /* Position units in milliseconds since start */ MIDI_CLOCKS 1 /* Position units in # of MIDI clocks since start */ POS_BYTES 2 /* Position data in bytes */ SMPTE_24 24 /* Position corresponds with SMPTE 24 frames/sec */ SMPTE_25 25 /* Position corresponds with SMPTE 25 frames/sec */ SMPTE_30DF 29 /* Position corresponds with SMPTE 30 drop frame */ SMPTE_30 30 /* Position corresponds with SMPTE 30 frames/sec */ ═══ MCI_AUDIO_BUFFER Parameter - lReadBufCap ═══ lReadBufCap (LONG) Capacity of Read queue; -1 if variable. ═══ MCI_AUDIO_BUFFER Parameter - lWriteBufCap ═══ lWriteBufCap (LONG) Capacity of Write queue; -1 if variable. ═══ MCI_AUDIO_BUFFER Parameter - lRequestBufCap ═══ lRequestBufCap (LONG) Maximum number of requests that can be queued. ═══ 17.22. MCI_AUDIO_CAPS ═══ This structure contains fields for the AUDIO_CAPABILITY function. typedef struct _MCI_AUDIO_CAPS { ULONG ulLength; /* Input. Structure length. */ ULONG ulSamplingRate; /* Input/Output. Sampling rate to query. */ ULONG ulChannels; /* Input/Output. Channels to query. */ ULONG ulBitsPerSample; /* Input/Output. Bits per sample to query. */ ULONG ulDataType; /* Input/Output. RIFF data type to query. */ ULONG ulOperation; /* Input/Output. OPERATION_PLAY or OPERATION_RECORD. */ ULONG ulSupport; /* Output. Boolean. */ ULONG ulDataSubType; /* Output. Data subtype to use. */ ULONG ulResourceUnits; /* Output. Resource units in this mode. */ ULONG ulResourceClass; /* Output. Resource class for this mode. */ ULONG ulBlockAlign; /* Output. Block alignment for this mode. */ BOOL fCanRecord; /* Unused */ ULONG ulFlags; /* Output. Flags. */ ULONG ulCapability; /* Output. Capability of the device. */ } MCI_AUDIO_CAPS; typedef MCI_AUDIO_CAPS FAR *PAUDIO_CAPS; ═══ MCI_AUDIO_CAPS Parameter - ulLength ═══ ulLength (ULONG) Input. Structure length. ═══ MCI_AUDIO_CAPS Parameter - ulSamplingRate ═══ ulSamplingRate (ULONG) Input/Output. Sampling rate to query. ═══ MCI_AUDIO_CAPS Parameter - ulChannels ═══ ulChannels (ULONG) Input/Output. Channels to query. ═══ MCI_AUDIO_CAPS Parameter - ulBitsPerSample ═══ ulBitsPerSample (ULONG) Input/Output. Bits per sample to query. ═══ MCI_AUDIO_CAPS Parameter - ulDataType ═══ ulDataType (ULONG) Input/Output. RIFF data type to query. Defines are found in MCIOS2.H. A sample data type would be DATATYPE_WAVEFORM. ═══ MCI_AUDIO_CAPS Parameter - ulOperation ═══ ulOperation (ULONG) Input/Output. OPERATION_PLAY or OPERATION_RECORD. ═══ MCI_AUDIO_CAPS Parameter - ulSupport ═══ ulSupport (ULONG) Output. Boolean. Indicates if the device driver supports this mode. Following are the valid return codes for ulSupport: SUPPORT_SUCCESS Device supports this mode. UNSUPPORTED_RATE Unsupported sampling rate. UNSUPPORTED_CHANNELS Unsupported sampling rate. UNSUPPORTED_BPS Unsupported bits per sample. UNSUPPORTED_DATATYPE Unsupported data type. UNSUPPORTED_OPERATION Unsupported operation. ═══ MCI_AUDIO_CAPS Parameter - ulDataSubType ═══ ulDataSubType (ULONG) Output. Data subtype to use. Returned by device. ═══ MCI_AUDIO_CAPS Parameter - ulResourceUnits ═══ ulResourceUnits (ULONG) Output. Data subtype to use. Returned by device. ═══ MCI_AUDIO_CAPS Parameter - ulResourceClass ═══ ulResourceClass (ULONG) Output. Resource class for this mode. Returned by device. ═══ MCI_AUDIO_CAPS Parameter - ulBlockAlign ═══ ulBlockAlign (ULONG) Output. Block alignment for this mode. Returned by device. ═══ MCI_AUDIO_CAPS Parameter - fCanRecord ═══ fCanRecord (BOOL) Unused ═══ MCI_AUDIO_CAPS Parameter - ulFlags ═══ ulFlags (ULONG) Output. Flags. Returned by device. ═══ MCI_AUDIO_CAPS Parameter - ulCapability ═══ ulCapability (ULONG) Output. Capability of the device. Returned by device. ulCapability can contain the following driver capabilities:+ SUPPORTED_MIX Supports mixing capabilities. SUPPORTED_RIFF_MODES Supports Riff data types on audio init. SUPPORTED_CAP Supports capability IOCtls. ═══ 17.23. MCI_AUDIO_CHANGE ═══ This structure contains fields for the AUDIO_STATUS function. typedef struct _MCI_AUDIO_CHANGE { VOID FAR *pvDevInfo; /* Pointer to information. */ LONG lInput; /* Reserved. */ LONG lOutput; /* Reserved. */ LONG lMonitor; /* Record monitor level. */ LONG lVolume; /* Volume setting. */ LONG lVolumeDelay; /* Volume delay. */ LONG lBalance; /* Balance setting. */ LONG lBalanceDelay; /* Balance delay. */ LONG lTreble; /* Treble tone-control setting. */ LONG lBass; /* Base tone-control setting. */ LONG lPitch; /* Pitch control setting. */ MCI_AUDIO_DEVID rInputList[8]; /* Input list. */ MCI_AUDIO_DEVID rOutputList[8]; /* Output list. */ LPMCI_AUDIO_DEVID prMoreInputs; /* Pointer to additional input. */ LPMCI_AUDIO_DEVID prMoreOutputs; /* Pointer to additional output. */ LONG lGain; /* Gain control setting. */ VOID FAR *pvModeInfo; /* Pointer to mode-specific info. */ } MCI_AUDIO_CHANGE; typedef MCI_AUDIO_CHANGE FAR *LPMCI_AUDIO_CHANGE; ═══ MCI_AUDIO_CHANGE Parameter - pvDevInfo ═══ pvDevInfo (VOID FAR *) Pointer to a data structure containing device-dependent information. For example, for the M-ACPA card, pvDevInfo points to a MCI_TRACK_INFO structure. This field is ignored if its value is NULL. ═══ MCI_AUDIO_CHANGE Parameter - lInput ═══ lInput (LONG) Reserved. Used in v0 for input select. ═══ MCI_AUDIO_CHANGE Parameter - lOutput ═══ lOutput (LONG) Reserved. Used in v0 for output select. ═══ MCI_AUDIO_CHANGE Parameter - lMonitor ═══ lMonitor (LONG) Record monitor level. ═══ MCI_AUDIO_CHANGE Parameter - lVolume ═══ lVolume (LONG) Volume setting; linear 0 min to 0x7FFFFFFF. ═══ MCI_AUDIO_CHANGE Parameter - lVolumeDelay ═══ lVolumeDelay (LONG) Number of milliseconds over which change occurs. ═══ MCI_AUDIO_CHANGE Parameter - lBalance ═══ lBalance (LONG) Balance setting 0 = left, 0x7FFFFFFF = right. ═══ MCI_AUDIO_CHANGE Parameter - lBalanceDelay ═══ lBalanceDelay (LONG) Number of milliseconds over which change occurs. ═══ MCI_AUDIO_CHANGE Parameter - lTreble ═══ lTreble (LONG) Treble tone-control setting. ═══ MCI_AUDIO_CHANGE Parameter - lBass ═══ lBass (LONG) Base tone-control setting. ═══ MCI_AUDIO_CHANGE Parameter - lPitch ═══ lPitch (LONG) Pitch control setting. ═══ MCI_AUDIO_CHANGE Parameter - rInputList[8] ═══ rInputList[8] (MCI_AUDIO_DEVID) Input devices are specified using an array of MCI_AUDIO_DEVID data structures in the rInputList field. Unused entries are set to NULL_INPUT. The MCI_AUDIO_DEVID structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line input, set: rInputList[0].ulDevType = STEREO_LINE_INPUT rInputList[0].ulDevNum = 1 ═══ MCI_AUDIO_CHANGE Parameter - rOutputList[8] ═══ rOutputList[8] (MCI_AUDIO_DEVID) Output devices are specified using an array of MCI_AUDIO_DEVID data structures in the rOutputList field. Unused entries are set to NULL_OUTPUT. The MCI_AUDIO_DEVID structure permits device specification by type and ordinal number (for those audio adapters that support more than one device of a specific type). For example, to specify stereo line output, set: rOutputList[0].ulDevType = STEREO_LINE_OUTPUT rOutputList[0].ulDevNum = DEVICE_1. ═══ MCI_AUDIO_CHANGE Parameter - prMoreInputs ═══ prMoreInputs (LPMCI_AUDIO_DEVID) Pointer to additional input device IDs. ═══ MCI_AUDIO_CHANGE Parameter - prMoreOutputs ═══ prMoreOutputs (LPMCI_AUDIO_DEVID) Pointer to additional output device IDs. ═══ MCI_AUDIO_CHANGE Parameter - lGain ═══ lGain (LONG) Input (record) gain-control setting. ═══ MCI_AUDIO_CHANGE Parameter - pvModeInfo ═══ pvModeInfo (VOID FAR *) Pointer to a mode-specific data structure. For MIDI, this points to a MIDI_INFO structure. ═══ 17.24. MCI_AUDIO_CONTROL ═══ This structure contains fields for the AUDIO_CONTROL function. typedef struct _MCI_AUDIO_CONTROL { USHORT usIOCtlRequest; VOID *pbRequestInfo; ULONG ulPosition; SHORT sReturnCode; } MCI_AUDIO_CONTROL; typedef MCI_AUDIO_CONTROL FAR *LPMCI_AUDIO_CONTROL ═══ MCI_AUDIO_CONTROL Parameter - usIOCtlRequest ═══ usIOCtlRequest (USHORT) IOCtl request to be executed. The defined values for this field are: AUDIO_CHANGE (0) Enables an application to change adapter characteristics. It is issued while the audio device is open. The characteristics contained in the MCI_AUDIO_CHANGE structure such as input source can be changed by this request. Note: AUDIO_CHANGE requests have the potential to break the data flow. Some audio devices might require that input, output, and monitor selections be performed prior to starting a change operation. To change an adapter's characteristics, the desired values should be placed in the respective fields and the request issued. Notice that all possible combinations of these fields are not necessarily supported by the device driver. Invalid combinations result in an error returned by AUDIO_CHANGE. The effects of issuing this request can vary for each requested change. If a given field is to remain unchanged, set that field to AUDIO_IGNORE (-1). AUDIO_START (1) Initiates the flow of audio data to or from the adapter. It also causes the internal position and timing values to be set to the value contained in ulPosition. Therefore, an immediate call to AUDIO_BUFFER returns a position value equal to the ulPosition value specified in AUDIO_START. The audio device must be opened and initialized (through OPEN and AUDIO_INIT requests) before calling AUDIO_START. Otherwise, an error is returned. There is no pbRequestInfo field for AUDIO_START. AUDIO_STOP (2) Stops the current activity in progress on the audio device. For example, if the device was recording, the recording activity would be stopped. This operation does not change the current configuration (such as sampling rate, input source, and so forth) of the device; it simply terminates the current operation. Consequently, it also stops data flow between the device driver and the application. Any data left in the buffers is discarded. Notice that the Write buffers can be drained using the AUDIO_WAIT request. Use the AUDIO_PAUSE operation instead of AUDIO_STOP if the operation must be resumed at the point it left off. The ulPosition value is used to specify when the stop is to occur. A value of less than the current position or 0 results in an immediate execution of the stop. There is no pbRequestInfo field for AUDIO_STOP. AUDIO_PAUSE (3) Used to suspend all data flow between the application and the adapter. This request does not flush the kernel buffers or the adapter buffers. Data flow can be resumed by using AUDIO_RESUME. If recording, data is lost during the time that the device driver is paused. The pbRequestInfo value is used to specify when the pause is to occur. A value of less than the current position results in an immediate pause. There is no pbRequestInfo field for AUDIO_PAUSE. AUDIO_RESUME (4) Used to resume the flow of data that was suspended by AUDIO_PAUSE. Notice that an ulPosition value of non-zero is not currently defined and should not be used. There is no pbRequestInfo field for AUDIO_RESUME. ═══ MCI_AUDIO_CONTROL Parameter - pbRequestInfo ═══ pbRequestInfo Pointer to a structure that contains information specific to each type of IOCtl request. See the IOCtl request descriptions above for specifics on what pbRequestInfo points to for each request. Notice that these requests are executed at a point in time specified by the caller. ═══ MCI_AUDIO_CONTROL Parameter - ulPosition ═══ ulPosition (ULONG) Number of units before the request should be executed. This value is used to specify cue points. Caller requests are executed ulPosition number of units from the beginning of the first Write operation after opening a track. Depending on the DSP code loaded and the current mode of operation, units can be bytes, time, or some other unit of measure. For example, to increase the volume of a track after the first 1,000 milliseconds of data have been written to the adapter, issue an AUDIO_CHANGE request with ulPosition set to 1000. This example assumes that the track information pointed to by pbRequestInfo has been initialized appropriately, and that MCI_AUDIO_BUFFER.ulPositionType = POS_MSECS. If a request is made for a position number that has already occurred, it is processed immediately. Requests with a position number of 0 are also processed immediately. ═══ MCI_AUDIO_CONTROL Parameter - sReturnCode ═══ sReturnCode (SHORT) Used to return any error code. The defined values for this field are: AC_UNINITED 1 /* Device must be initialized or loaded first */ FULL_QUEUE 2 /* Max. number of requests exceeded */ AC_UNPAUSED 3 /* Resume issued, but device not paused */ INVALID_REQUEST 4 /* Bad MCI_AUDIO_CONTROL.usIOCtlRequest */ AC_UNSTARTED 5 /* Device must be started first */ INVALID_INPUT_LIST 7 /* Device in MCI_AUDIO_CHANGE.input_list is not supported */ INVALID_OUTPUT_LIST 8 /* Device in MCI_AUDIO_CHANGE.output_list is not supported */ ═══ 17.25. MCI_AUDIO_DEVID ═══ typedef struct _MCI_AUDIO_DEVID { ULONG ulDevType; ULONG ulDevNum; } MCI_AUDIO_DEVID; typedef MCI_AUDIO_DEVID FAR *LPMCI_AUDIO_DEVID; ═══ MCI_AUDIO_DEVID Parameter - ulDevType ═══ ulDevType (ULONG) Defined values for ulDevType are shown for input and output devices: /* Input Devices */ #define NULL_INPUT 0 #define STEREO_LINE_INPUT 1 #define LEFT_LINE_INPUT 2 #define RIGHT_LINE_INPUT 3 #define MIC_INPUT 4 #define BOOSTED_MIC_INPUT 5 #define PHONE_LINE_INPUT 6 #define HANDSET_INPUT 7 #define SYNTH_INPUT 8 #define DIGITAL_PHONE_LINE_INPUT 9 #define DIGITAL_HANDSET_INPUT 10 #define MIDI_IN_PORT 11 #define LOOPBACK 12 #define DEFAULT_INPUT 0xFFFFFFFF /* Values between 0x20000000 and 0xFFFFFFFE are reserved */ /* Output Devices */ #define NULL_OUTPUT 0 #define STEREO_LINE_OUTPUT 1 #define LEFT_LINE_OUTPUT 2 #define RIGHT_LINE_OUTPUT 3 #define SPEAKER_OUTPUT 4 #define HEADPHONES_OUTPUT 5 #define PHONE_LINE_OUTPUT 6 #define HANDSET_OUTPUT 7 #define SYNTH_OUTPUT 8 #define DIGITAL_PHONE_LINE_OUTPUT 9 #define DIGITAL_HANDSET_OUTPUT 10 #define MIDI_OUT_PORT 11 #define DEFAULT_OUTPUT 0xFFFFFFFF /* Values between 0x20000000 and 0xFFFFFFFE are reserved */ ═══ MCI_AUDIO_DEVID Parameter - ulDevNum ═══ ulDevNum (ULONG) The defined values for ulDevNum are: #define DEFAULT_DEVICE 0 #define DEVICE_1 1 #define DEVICE_2 2 ═══ 17.26. MCI_AUDIO_HPI ═══ This structure contains fields for the AUDIO_HPI function. typedef struct _hpi { VOID FAR *pvEntry (); /* Pointer to direct-call entry point. */ VOID FAR *pvCallBack (); /* Pointer to callback routine. */ LPMCI_AUDIO_IOBUFFER prXBuff; /* Pointer to new Transmit buffer. */ LPMCI_AUDIO_IOBUFFER prRBuff; /* Pointer to new Receive buffer. */ USHORT usFlags; /* Reserved. */ } MCI_AUDIO_HPI; typedef MCI_AUDIO_HPI FAR *LPMCI_AUDIO_HPI; ═══ MCI_AUDIO_HPI Parameter - pvEntry () ═══ pvEntry () (VOID FAR *) Pointer to the direct-call entry point. The direct call interface is defined below. void (far *iobuf.ep)(short funcid, void far *data, short len); /* Definitions for funcid */ EP_OPEN 0 EP_CLOSE 1 EP_READ 2 EP_WRITE 3 EP_INIT 4 EP_STATUS 5 EP_CONTROL 6 EP_BUFFER 7 EP_LOAD 8 EP_WAIT 9 EP_HPI 10 EP_UPDATE 11 /* On return, AX contains an error code, or 0 if successful */ ═══ MCI_AUDIO_HPI Parameter - pvCallBack () ═══ pvCallBack () (VOID FAR *) Pointer to the callback routine. The application passes the address of a callback routine (under DOS) or system semaphore handle (under OS/2) in pvCallBack (). Notice that the DOS callback routine must be an interrupt routine, that is, it must return with an IRET, not a RET instruction. Care must be taken not to re-enter DOS. For example, the interrupt can occur while executing a DOS call. Any call to DOS made in the callback routine will result in DOS being entered a second time and will probably cause a system halt. If not NULL, the address is called (under DOS) or the semaphore is cleared (under OS/2) based on the state of the CBDATA, CBBLOCK, CBIOBUF, and CBERROR flags in usRunFlags: CBDATA The address is called (under DOS) or the semaphore is cleared (under OS/2) for each data byte sent to, or received from, the device. Notice that some devices transfer data to and from the host only in blocks, in which case this bit has the same effect as CBBLOCK. CBBLOCK The address is called or the semaphore is cleared for each complete block of data sent to, or received from, the device. CBIOBUF The address is called or the semaphore is cleared each time the entire contents of IOBUF are sent to, or received from, the device. CBERROR The address is called or the semaphore is cleared each time a device error is detected by the device. CBUNDERRUN The address is called or the semaphore is cleared each time an underrun or overrun is detected by the device. This process will continue until either the device is stopped (or closed) or the AUDIO_HPI function is called again with pvCallBack () set to NULL. The device interrupt rate generally corresponds with the position resolution returned in lResolution of the MCI_AUDIO_INIT structure. ═══ MCI_AUDIO_HPI Parameter - prXBuff ═══ prXBuff (LPMCI_AUDIO_IOBUFFER) Pointer to new Transmit buffer to use. Set prXBuff to NULL to use the default internal buffers. ═══ MCI_AUDIO_HPI Parameter - prRBuff ═══ prRBuff (LPMCI_AUDIO_IOBUFFER) Pointer to new Receive buffer to use. Set prRBuff to NULL to use the default internal buffers. By default, the internal buffer sizes are usually 512 bytes. Any buffers provided must be an even number of bytes in length. ═══ MCI_AUDIO_HPI Parameter - usFlags ═══ usFlags (USHORT) Reserved. ═══ 17.27. MCI_AUDIO_INIT ═══ This structure contains fields for the AUDIO_INIT function. typedef struct _init { LONG lSRate; /* Sampling rate. */ LONG lBitsPerSRate; /* # of bits per sample. */ LONG lBsize; /* Block size. */ SHORT sMode; /* Audio mode. */ SHORT sChannels; /* Number of audio channels. */ LONG lResolution; /* Resolution of position data. */ CHAR abLoadPath[LOAD_PATH]; /* Path of DSP code to load. */ ULONG ulFlags; /* Fixed, signed, and so on. */ ULONG ulOperation; /* Desired operation. */ SHORT sReturnCode; /* Return code for operation. */ SHORT sSlotNumber; /* Slot number of adapter. */ SHORT sDeviceID; /* Adapter type ID. */ VOID FAR *pvReserved; /* Reserved field. */ ULONG ulVersionLevel; /* Version level of device driver. */ } MCI_AUDIO_INIT; typedef MCI_AUDIO_INIT FAR *LPMCI_AUDIO_INIT; ═══ MCI_AUDIO_INIT Parameter - lSRate ═══ lSRate (LONG) Indicates the sampling rate in Hz, if applicable. ═══ MCI_AUDIO_INIT Parameter - lBitsPerSRate ═══ lBitsPerSRate (LONG) Indicates the number of bits per sample, if applicable. ═══ MCI_AUDIO_INIT Parameter - lBsize ═══ lBsize (LONG) Indicates the data block size for blocked data. Some devices perform I/O in fixed block amounts. For these devices, a full block of data must be written to the device driver before it is written to the device (during playback). During Record operations, a full block of data must be received before it becomes available to the application. The lBsize field should be less than or equal to 1024 bytes, however, it cannot be guaranteed not to exceed that size. ═══ MCI_AUDIO_INIT Parameter - sMode ═══ sMode (SHORT) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The defined values for sMode are: ADPCM 1 /* AVC type ADPCM */ PCM 2 /* PCM */ MU_LAW 3 /* Mu-law */ MIDI 4 /* MIDI */ A_LAW 5 /* A-law */ SOURCE_MIX 6 /* External analog audio source */ SPV2 7 /* Reserved (Speech Viewer/2) */ ADPCMXA 8 /* XA CD ROM */ DSSM 9 /* DS201 Standard mode */ DSMM 10 /* DS201 Movie mode */ CVSD 11 /* CVSD */ SPV2BCPCM 25 /* Reserved (Speech Viewer/2) */ SPV2PCM 26 /* Reserved (Speech Viewer/2) */ SPV2NONE 27 /* Reserved (Speech Viewer/2) */ IDLE 999 /* Deinitialize the track */ CLAIM_HDWR 32000 /* Claim hardware for other use */ ═══ MCI_AUDIO_INIT Parameter - sChannels ═══ sChannels (SHORT) Indicates the number of audio channels, for example, mono is 1, stereo is 2. ═══ MCI_AUDIO_INIT Parameter - lResolution ═══ lResolution (LONG) Set to indicate the resolution of position data returned by the device driver. For example, the M-ACPA device driver can return position data rounded to the nearest 100 milliseconds when playing AVC ADPCM (.1-second blocked) data. ═══ MCI_AUDIO_INIT Parameter - abLoadPath[LOAD_PATH] ═══ abLoadPath[LOAD_PATH] (CHAR) If the digital signal processor (DSP) code must be loaded before the operation can be performed, the device driver sets the LOAD_CODE bit in ulFlags. In this case, the name of the DSP file to be loaded is specified in the abLoadPath field. Notice that the application must call AUDIO_LOAD before trying to perform Read or Write operations. Keep a single copy of each DSP load module maintained and grouped together in a single subdirectory. This subdirectory can be referenced in the DOS APPEND command or the OS/2 DPATH CONFIG.SYS statement. The maximum path length available for DSP code modules in abLoadPath is: LOAD_PATH 260 /* DOS and OS/2 length is 260 */ ═══ MCI_AUDIO_INIT Parameter - ulFlags ═══ ulFlags (ULONG) A bit flag indicating several pieces of information. The defined values for ulFlags are: FIXED (0x00000001l) Specify that the data is fixed, as opposed to variable rate or size. LEFT_ALIGNED (0x00000002l) Specify that the data is left aligned on a byte boundary. This field is applicable only if lBitsPerSRate is not a multiple of 8. RIGHT_ALIGNED (0x00000004l) Specify that the data is right aligned on a byte boundary. This bit is applicable only if lBitsPerSRate is not a multiple of 8. TWOS_COMPLEMENT (0x00000008l) Specify that the data is represented by using TWOS_COMPLEMENT signed format. If this bit and the SIGNED bit are both 0, the data is in unsigned format. SIGNED (0x00000010l) Specify that the data is represented using signed magnitude format, whereby the highest bit is set to 1 to indicate a negative value, and the lower bits specify the absolute value. If this bit and the TWOS_COMPLEMENT bit are both 0, the data is in unsigned format. BIG_ENDIAN (0x00000020l) Specifies that the most significant bytes precede the least significant bytes. This bit is applicable only if lBitsPerSRate is greater than 8 (multibyte values). RIFF_DATATYPE (0x00000040l) sMode contains a RIFF datatype. PITCH (0x00100000l) Specifies that pitch control is supported. INPUT (0x00200000l) Specifies that input select is supported. OUTPUT (0x00400000l) Specifies that output select is supported. MONITOR (0x00800000l) Specifies that monitor select is supported. VOLUME (0x01000000l) Specifies that volume select is supported. VOLUME_DELAY (0x02000000l) Specifies that volume delay is supported. BALANCE (0x04000000l) Specifies that balance control is supported. BALANCE_DELAY (0x08000000l) Specifies that balance delay is supported. TREBLE (0x10000000l) Specifies that treble control is supported BASS (0x20000000l) Specifies that bass control is supported. BESTFIT_PROVIDED (0x40000000l) Indicates that the best fit is returned. LOAD_CODE (0x80000000l) Indicates that a DSP load is needed. ═══ MCI_AUDIO_INIT Parameter - ulOperation ═══ ulOperation (ULONG) Specifies the desired operation. The defined values for this field are: OPERATION_PLAY 0x80000001 OPERATION_RECORD 0x80000002 PLAY_AND_RECORD 0x80000003 ANALYSIS 0x80000006 /* Speech Viewer/2 */ DISTANCE 0x80000007 /* Speech Viewer/2 */ MIGRATION 0x80000008 /* Speech Viewer/2 */ Notice that the high-order bit is set in all cases. ═══ MCI_AUDIO_INIT Parameter - sReturnCode ═══ sReturnCode (SHORT) Return code for the operation. The defined values for sReturnCode are: NO_PLAY 1 /* Cannot play */ NO_RECORD 2 /* Cannot record */ NO_RECORD_AND_PLAY 3 /* Cannot both play and record */ INVALID_REQUEST 4 /* Request was not valid */ CONFLICT 5 /* Conflicting information was found */ OVERLOADED 6 /* Out of DSP MIPS or Memory */ DOWNLEVEL_DD 7 /* DD is an earlier version than the version requested by the application */ DSP_LOAD_PENDING_ON_OTHER_TRK 8 /* Other track hasn't loaded DSP */ ═══ MCI_AUDIO_INIT Parameter - sSlotNumber ═══ sSlotNumber (SHORT) If the call is successful, the slot number of the device is returned in the sSlotNumber field. ═══ MCI_AUDIO_INIT Parameter - sDeviceID ═══ sDeviceID (SHORT) If the call is successful, the type of device is returned in the sDeviceID field. The defined values used by sDeviceID are: MINIDD 0 /* Minimal device driver */ ACPA 1 /* IBM ACPA */ MACPA 2 /* IBM M-ACPA */ MPU401 3 /* Roland MPU-401 or compatible */ SOUND_BLASTER 4 /* Creative Labs Sound Blaster */ IMF 5 /* IBM Music Feature */ PS1 6 /* IBM Personal System/1 audio feature */ PAS16 7 /* Media Vision ProAudio Spectrum 16 */ DS201 9 /* DS201 audio adapter */ ═══ MCI_AUDIO_INIT Parameter - pvReserved ═══ pvReserved (VOID FAR *) Reserved field. ═══ MCI_AUDIO_INIT Parameter - ulVersionLevel ═══ ulVersionLevel (ULONG) Specifies the audio device driver version. As audio device drivers evolve, some changes are sure to occur. The ulVersionLevel field is used to allow new functions to be added to audio device drivers without losing compatibility with existing applications. When an application calls AUDIO_INIT, it specifies the version level of the requested device driver. The audio device driver compares its version level with that passed by the application and ensures that they are compatible. If the device driver is an earlier version than that required by the application, it returns an error. If the version level of the device driver is newer than the application, the driver ensures that calls from the application are handled in a manner consistent with the version level of the application. The value specified in ulVersionLevel is the binary-coded decimal representation of the version and build level. For example, Version 1.0 Build 15 is coded 0x01000015. The high-order byte is the version, the next byte is the revision number, and the least significant two bytes are the build number. ═══ 17.28. MCI_AUDIO_IOBUFFER ═══ This structure contains fields for the AUDIO_HPI function. typedef struct _MCI_AUDIO_IOBUFFER { LONG lSize; /* Size of data buffers. */ CHAR FAR *pHead; /* Queue head pointer. */ CHAR FAR *pTail; /* Queue tail pointer. */ LONG lCount; /* # of bytes queued. */ ULONG ulPosition; /* Position counter. */ LONG lDelay; /* # of units before next I/O. */ USHORT usRunFlags; /* Start/stop/pause bits. */ USHORT usSelInc; CHAR FAR *pBuffer; /* Array of pointers. */ } MCI_AUDIO_IOBUFFER; typedef MCI_AUDIO_IOBUFFER FAR *LPMCI_AUDIO_IOBUFFER; ═══ MCI_AUDIO_IOBUFFER Parameter - lSize ═══ lSize (LONG) Total size in bytes of the data buffers. ═══ MCI_AUDIO_IOBUFFER Parameter - pHead ═══ pHead (CHAR FAR *) Queue head pointer (data added here). ═══ MCI_AUDIO_IOBUFFER Parameter - pTail ═══ pTail (CHAR FAR *) Queue tail pointer (data removed here) ═══ MCI_AUDIO_IOBUFFER Parameter - lCount ═══ lCount (LONG) Total number of data bytes currently queued. ═══ MCI_AUDIO_IOBUFFER Parameter - ulPosition ═══ ulPosition (ULONG) Position counter. ═══ MCI_AUDIO_IOBUFFER Parameter - lDelay ═══ lDelay (LONG) Number of pos units before the next I/O. ═══ MCI_AUDIO_IOBUFFER Parameter - usRunFlags ═══ usRunFlags (USHORT) Start/stop/pause bits. ═══ MCI_AUDIO_IOBUFFER Parameter - usSelInc ═══ usSelInc (USHORT) ═══ MCI_AUDIO_IOBUFFER Parameter - pBuffer ═══ pBuffer (CHAR FAR *) Array of pointers describing buffers. ═══ 17.29. MCI_AUDIO_LOAD ═══ This structure contains fields for the AUDIO_LOAD function. typedef struct _load { CHAR FAR *pbBuffer; /* Pointer to buffer. */ ULONG ulSize; /* Size of DSP code (in bytes). */ ULONG ulFlags; /* Indicates start or end of operation. */ } MCI_AUDIO_LOAD; typedef MCI_AUDIO_LOAD FAR *LPMCI_AUDIO_LOAD; ═══ MCI_AUDIO_LOAD Parameter - pbBuffer ═══ pbBuffer (CHAR FAR *) Pointer to buffer containing DSP code. ═══ MCI_AUDIO_LOAD Parameter - ulSize ═══ ulSize (ULONG) Size of DSP code (in bytes). ═══ MCI_AUDIO_LOAD Parameter - ulFlags ═══ ulFlags (ULONG) Indicates start or end of operation. The defined values for this field are: LOAD_START 1 /* Indicates that this is the first block */ LOAD_END 2 /* Indicates that this is the last block */ LOAD_32BIT 10 ═══ 17.30. MCI_AUDIO_STATUS ═══ This structure contains fields for the AUDIO_STATUS function. typedef struct _stat { LONG lSRate; /* Sampling rate. */ LONG lBitsPerSRate; /* # of bits per sample. */ LONG lBsize; /* Block size. */ SHORT sMode; /* Mode. */ SHORT sChannels; /* # of channels. */ ULONG ulFlags; /* Flags. */ ULONG ulOperation; /* Operation. */ MCI_AUDIO_CHANGE rAudioChange; /* MCI_AUDIO_CHANGE structure. */ } MCI_AUDIO_STATUS; typedef MCI_AUDIO_STATUS FAR *LPMCI_AUDIO_STATUS; ═══ MCI_AUDIO_STATUS Parameter - lSRate ═══ lSRate (LONG) Indicates the sampling rate in Hz (if applicable). ═══ MCI_AUDIO_STATUS Parameter - lBitsPerSRate ═══ lBitsPerSRate (LONG) Indicates the number of bits per sample (if applicable). ═══ MCI_AUDIO_STATUS Parameter - lBsize ═══ lBsize (LONG) Indicates the data block size for blocked data. ═══ MCI_AUDIO_STATUS Parameter - sMode ═══ sMode (SHORT) Indicates the general audio mode, for example, PCM, ADPCM, or MIDI. The possible values are listed under the sMode field of MCI_AUDIO_INIT. ═══ MCI_AUDIO_STATUS Parameter - sChannels ═══ sChannels (SHORT) Indicates the number of audio channels, for example, mono is 1, stereo is 2. ═══ MCI_AUDIO_STATUS Parameter - ulFlags ═══ ulFlags (ULONG) A bit flag. The possible values are listed under the ulFlags field of MCI_AUDIO_INIT. ═══ MCI_AUDIO_STATUS Parameter - ulOperation ═══ ulOperation (ULONG) Specifies the desired operation. The defined values for this field are: STOPPED 0x80000000 PLAYING 0x80000001 RECORDING 0x80000002 PLAYING_AND_RECORDING 0x80000003 UNINITIALIZED 0xFFFFFFFF Notice that the value associated with the current operation is returned in the ulOperation field. ═══ MCI_AUDIO_STATUS Parameter - rAudioChange ═══ rAudioChange (MCI_AUDIO_CHANGE) An MCI_AUDIO_CHANGE data structure. ═══ 17.31. MCI_DEVICESETTINGS_PARMS ═══ This structure contains fields for the MCI_DEVICESETTINGS message. typedef struct _MCI_DEVICESETTINGS_PARMS { HWND hwndCallback; /* Window handle. */ HWND hwndNotebook; /* Handle to notebook window. */ USHORT usDeviceType; /* Device type. */ PSZ pszDeviceName; /* Logical device name. */ } MCI_DEVICESETTINGS_PARMS; typedef MCI_DEVICESETTINGS_PARMS *PMCI_DEVICESETTINGS_PARMS; ═══ MCI_DEVICESETTINGS_PARMS Parameter - hwndCallback ═══ hwndCallback (HWND) A window handle to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ MCI_DEVICESETTINGS_PARMS Parameter - hwndNotebook ═══ hwndNotebook (HWND) Handle to notebook window. ═══ MCI_DEVICESETTINGS_PARMS Parameter - usDeviceType ═══ usDeviceType (USHORT) Device type. ═══ MCI_DEVICESETTINGS_PARMS Parameter - pszDeviceName ═══ pszDeviceName (PSZ) Logical device name. ═══ 17.32. MCI_TRACK_INFO ═══ typedef struct _info { USHORT usMasterVolume; /* Master volume control. */ USHORT usDitherPct; /* Dither percent control. */ USHORT usMasterVolumeDelay; /* Master volume delay. */ USHORT usMasterBalance; /* Master balance control. */ } MCI_TRACK_INFO; typedef MCI_TRACK_INFO FAR *LPMCI_TRACK_INFO; ═══ MCI_TRACK_INFO Parameter - usMasterVolume ═══ usMasterVolume (USHORT) Master volume control. ═══ MCI_TRACK_INFO Parameter - usDitherPct ═══ usDitherPct (USHORT) Dither percent control. ═══ MCI_TRACK_INFO Parameter - usMasterVolumeDelay ═══ usMasterVolumeDelay (USHORT) Master volume delay. ═══ MCI_TRACK_INFO Parameter - usMasterBalance ═══ usMasterBalance (USHORT) Master balance control. ═══ 17.33. MIDI_INFO ═══ This structure contains MIDI-mode information. typedef struct _mode_info { SHORT sTempo; /* Tempo. */ SHORT sCPQN; /* Timing. */ SHORT sMidiSwitches; /* Common MIDI switches. */ SHORT sReserved[5]; /* Reserved field. */ } MIDI_INFO; ═══ MIDI_INFO Parameter - sTempo ═══ sTempo (SHORT) Tempo in 1/10 beats per minute (nominally 120). ═══ MIDI_INFO Parameter - sCPQN ═══ sCPQN (SHORT) Timing clocks per quarter note (nominally 96). ═══ MIDI_INFO Parameter - sMidiSwitches ═══ sMidiSwitches (SHORT) The following MIDI switches are defined: MIDI_THRU_OUT 1 /* Configure MIDI-Thru connector as MIDI-Out */ MIDI_THRU_THRU 0 /* Configure MIDI-Thru connector as MIDI-Thru */ ═══ MIDI_INFO Parameter - sReserved[5] ═══ sReserved[5] (SHORT) Reserved field. ═══ 17.34. MIXERCONTROL ═══ This structure contains fields for the VSD_QUERYMIXCONTROL and the VSD_SETMIXCONTROL messages and the MIX_GETCONTROL and MIX_SETCONTROL IOCtls. typedef struct _MIXERCONTROL { ULONG ulLength; /* Length of the structure. */ ULONG ulLine; /* Line to control. */ ULONG ulControl; /* Input. Mixer attribute to control. */ ULONG ulSetting; /* Setting for mixer attribute. */ } MIXERCONTROL; typedef MIXERCONTROL FAR *PMIXERCONTROL; ═══ MIXERCONTROL Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ MIXERCONTROL Parameter - ulLine ═══ ulLine (ULONG) Line to control. This field can contain the following sources or sinks: SOURCE_SYNTHESIZER Midi connection. SOURCE_MIXER Source mixer connection. SOURCE_LINE Line connection. SOURCE_INTERNAL_AUDIO Internal audio connection. SOURCE_MICROPHONE Microphone connection. SOURCE_WAVE Wave connection. SOURCE_PC_SPEAKER PC speaker connection. SINK_LINE_OUT Line out connection. SINK_SPEAKER Speaker connection. SINK_HEADPHONES Headphones connection. SINK_GENERIC Generic connection. SINK_NULL Null connection. ═══ MIXERCONTROL Parameter - ulControl ═══ ulControl (ULONG) Attribute to modify line. This field can contain: MIX_BALANCE Separate balance control. MIX_ALC Auto level control. MIX_MONITOR Monitor control. MIX_CROSSOVER Crossover change. MIX_LOUDNESS Loudness equalization. MIX_MUTE Channel mute. MIX_REVERB Reverb. MIX_STEREOENHANCE Stereo enhance. MIX_CUSTOM1 Custom effect #1. MIX_CUSTOM2 Custom effect #2. MIX_CUSTOM3 Custom effect #3. MIX_BASS Bass. MIX_TREBLE Treble. MIX_PITCH Pitch modifications. MIX_CHORUS Chorus. MIX_VOLUME Volume controls. ═══ MIXERCONTROL Parameter - ulSetting ═══ ulSetting (ULONG) Setting for mixer attribute. Can range from 0 to 0xFFFF. for mono controls to 0xFFFFFFFF for stereo controls. ═══ 17.35. MIXERLINEINFO ═══ This structure contains fields for the VSD_QUERYMIXLINE message and the MIX_GETLINEINFO IOCtl. typedef struct _MIXERLINEINFO { ULONG ulLength; /* Length of the structure. */ ULONG ulNumChannels; /* Input. Number of channels. */ ULONG ulSupport; /* Supported mixer attributes. */ ULONG ulConnectionsPossible; /* Possible connections. */ ULONG ulLine; /* Input/Output. */ } MIXERLINEINFO; typedef MIXERLINEINFO FAR *PMIXERLINEINFO; ═══ MIXERLINEINFO Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ MIXERLINEINFO Parameter - ulNumChannels ═══ ulNumChannels (ULONG) Input. Number of channels. ═══ MIXERLINEINFO Parameter - ulSupport ═══ ulSupport (ULONG) Supported mixer attributes. The following values are defined for ulSupport: MIX_BALANCE Separate balance control. MIX_ALC Auto level control. MIX_MONITOR Monitor control. MIX_CROSSOVER Crossover change. MIX_LOUDNESS Loudness equalization. MIX_MUTE Channel mute. MIX_REVERB Reverb. MIX_STEREOENHANCE Stereo enhance. MIX_CUSTOM1 Custom effect #1. MIX_CUSTOM2 Custom effect #2. MIX_CUSTOM3 Custom effect #3. MIX_BASS Bass. MIX_TREBLE Treble. MIX_PITCH Pitch modifications. MIX_CHORUS Chorus. MIX_VOLUME Volume controls. ═══ MIXERLINEINFO Parameter - ulConnectionsPossible ═══ ulConnectionsPossible (ULONG) Lines ulLine can connect to. ═══ MIXERLINEINFO Parameter - ulLine ═══ ulLine (ULONG) Input/Output. Line to set or query information. The ulLine field must be filled in by the caller with one of the following VSD lines: SOURCE_SYNTHESIZER Midi connection. SOURCE_MIXER Mixer connection. SOURCE_LINE Line connection. SOURCE_INTERNAL_AUDIO Internal audio connection. SOURCE_MICROPHONE Microphone connection. SOURCE_WAVE Wave connection. SOURCE_PC_SPEAKER PC speaker connection. ═══ 17.36. MMTIME ═══ Universal Chinatown time (1/3000 second). typedef ULONG MMTIME; ═══ 17.37. MSG_REPORTEVENT ═══ This structure contains fields for the SHC_REPORT_EVENT message (passed with SpiSendMsg). typedef struct _MSG_REPORTEVENT { ULONG ulMsgLen; /* Length of structure. */ HEVENT hevent; /* Event handle. */ ULONG ulStreamTime; /* Time in milliseconds of stream position. */ } MSG_REPORTEVENT; typedef MSG_REPORTEVENT FAR *PMSG_REPORTEVENT; ═══ MSG_REPORTEVENT Parameter - ulMsgLen ═══ ulMsgLen (ULONG) Length of structure. ═══ MSG_REPORTEVENT Parameter - hevent ═══ hevent (HEVENT) Event handle passed back to stream handler. ═══ MSG_REPORTEVENT Parameter - ulStreamTime ═══ ulStreamTime (ULONG) Time in milliseconds of stream position. ═══ 17.38. MSG_REPORTINT ═══ This structure contains fields for the SHC_REPORT_INT message (passed with SpiSendMsg). typedef struct _MSG_REPORTINT { ULONG ulMsgLen; /* Length of structure. */ PVOID pBuffer; /* Return pointer. */ ULONG ulFlag; /* Reason for interrupt. */ ULONG ulStatus; /* Bytes read or written. */ ULONG ulStreamTime; /* Stream time in milliseconds. */ } MSG_REPORTINT; typedef MSG_REPORTINT FAR *PMSG_REPORTINT; ═══ MSG_REPORTINT Parameter - ulMsgLen ═══ ulMsgLen (ULONG) Length of structure. ═══ MSG_REPORTINT Parameter - pBuffer ═══ pBuffer (PVOID) Pointer to buffer being returned (or null for no buffer to return). ═══ MSG_REPORTINT Parameter - ulFlag ═══ ulFlag (ULONG) Specifies the reason for the interrupt. This field defines the following flags: ERROR STREAM_STOP_NOW SHD_READ_COMPLETE SHD_WRITE_COMPLETE Note: 1. ERROR must be ORed with SHD_READ_COMPLETE or SHD_WRITE_COMPLETE. 2. Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer. ═══ MSG_REPORTINT Parameter - ulStatus ═══ ulStatus (ULONG) Return code or bytes read or written. ═══ MSG_REPORTINT Parameter - ulStreamTime ═══ ulStreamTime (ULONG) Stream time in milliseconds. ═══ 17.39. PFN ═══ Pointer to a procedure. typedef _PFN *PFN; In the header file, this is a two-part definition as shown below: typedef int (APIENTRY _PFN) (); typedef _PFN *PFN; ═══ 17.40. PSHDFN ═══ Pointer to a function prototype for a stream handler device entry routine. typedef ULONG (FAR *PSHDFN) (PVOID pParmIn); In the header file, this is a two-part defintion as shown below: typedef ULONG (FAR *PSHDFN) (PVOID pParmIn); typedef PVOID PSHDFN; ═══ 17.41. PSZ ═══ Pointer to a null-terminated string. If you are using C++ **, you may need to use PCSZ. typedef unsigned char *PSZ; ═══ 17.42. SETUP_PARM ═══ This data structure contains fields for the pSetupParm and ulSetupParmSize fields of the DDCMDSETUP data structure. typedef struct _SETUP_PARM { ULONG ulStreamTime; /* Stream time in milliseconds. */ ULONG ulFlags; /* Flags (input/output). */ } SETUP_PARM; ═══ SETUP_PARM Parameter - ulStreamTime ═══ ulStreamTime (ULONG) Specifies the stream time in milliseconds. ═══ SETUP_PARM Parameter - ulFlags ═══ ulFlags (ULONG) Device drivers should ignore this field. ═══ 17.43. SHD_COMMON ═══ This data structure contains common fields between all SHD data structures. typedef struct _shd_common_parm { ULONG ulFunction; /* Function requested by PDD. */ HSTREAM hStream; /* Stream handle. */ } SHD_COMMON; typedef SHD_COMMON *PSHD_COMMON; ═══ SHD_COMMON Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the PDD. ═══ SHD_COMMON Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle needed at interrupt time. ═══ 17.44. SHD_REPORTEVENT ═══ This data structure contains fields for the SHD_REPORT_EVENT message. typedef struct _shd_reportevent_parm { ULONG ulFunction; /* Function requested by PDD. */ HSTREAM hStream; /* Stream handle. */ HEVENT hEvent; /* Event handle. */ ULONG ulStreamTime; /* Time in milliseconds of stream position. */ } SHD_REPORTEVENT; typedef SHD_REPORTEVENT *PSHD_REPORTEVENT; ═══ SHD_REPORTEVENT Parameter - ulFunction ═══ ulFunction (ULONG) Function requested by PDD. ═══ SHD_REPORTEVENT Parameter - hStream ═══ hStream (HSTREAM) Stream handle. ═══ SHD_REPORTEVENT Parameter - hEvent ═══ hEvent (HEVENT) Event handle passed back to stream handlers. ═══ SHD_REPORTEVENT Parameter - ulStreamTime ═══ ulStreamTime (ULONG) Time in milliseconds of stream position. ═══ 17.45. SHD_REPORTINT ═══ This data structure contains fields for the SHD_REPORT_INT message. typedef struct _shd_reportint_parm { ULONG ulFunction; /* Function requested by PDD. */ HSTREAM hStream; /* Stream handle. */ PVOID pBuffer; /* Return pointer to last used buffer. */ ULONG ulFlag; /* Reason for interrupt. */ ULONG ulStatus; /* Return code or bytes read/written. */ ULONG ulStreamTime; /* Time in milliseconds of stream position. */ } SHD_REPORTINT; typedef SHD_REPORTINT *PSHD_REPORTINT; ═══ SHD_REPORTINT Parameter - ulFunction ═══ ulFunction (ULONG) Specifies the function requested by the PDD. ═══ SHD_REPORTINT Parameter - hStream ═══ hStream (HSTREAM) Specifies the stream handle so the stream handler knows which stream to process. ═══ SHD_REPORTINT Parameter - pBuffer ═══ pBuffer (PVOID) Returns the pointer to the last used buffer. ═══ SHD_REPORTINT Parameter - ulFlag ═══ ulFlag (ULONG) Specifies the reason for the interrupt. This field defines the following flags: o ERROR o STREAM_STOP_NOW o SHD_READ_COMPLETE o SHD_WRITE_COMPLETE Note: Do not set SHD_READ_COMPLETE or SHD_WRITE_COMPLETE if not returning a buffer. The STREAM_STOP_NOW flag is required. It forces the stream handler to release all buffers that have not been returned. Issue this flag if DDCMD_STOP or if the VSD has remaining buffers. ═══ SHD_REPORTINT Parameter - ulStatus ═══ ulStatus (ULONG) Specifies the status for the return code or the bytes read or written. ═══ SHD_REPORTINT Parameter - ulStreamTime ═══ ulStreamTime (ULONG) Specifies the time in milliseconds of stream position. ═══ 17.46. SHORT ═══ Signed integer in the range -32 768 through 32 767. #define SHORT short ═══ 17.47. SPCB ═══ This structure describes a stream protocol of a specific data type. typedef struct _SPCB { ULONG ulSPCBLen; /* SPCB length. */ SPCBKEY spcbkey; /* SPCB key. */ ULONG ulDataFlags; /* Data type flags. */ ULONG ulNumRec; /* Maximum number for records/buffers. */ ULONG ulBlockSize; /* Block size. */ ULONG ulBufSize; /* Buffer size. */ ULONG ulMinBuf; /* Minimum number of buffers. */ ULONG ulMaxBuf; /* Maximum number of buffers. */ ULONG ulSrcStart; /* Number of empty buffers. */ ULONG ulTgtStart; /* Number of full buffers. */ ULONG ulBufFlags; /* Buffer flags. */ ULONG ulHandFlags; /* Stream handler flags. */ MMTIME mmtimeTolerance; /* Resync tolerance value. */ MMTIME mmtimeSync; /* Sync pulse granularity. */ ULONG ulBytesPerUnit; /* Bytes per unit. */ MMTIME mmtimePerUnit; /* MMTIME per unit. */ } SPCB; typedef SPCB FAR *PSPCB; ═══ SPCB Parameter - ulSPCBLen ═══ ulSPCBLen (ULONG) Specifies the length of the stream protocol control block. ═══ SPCB Parameter - spcbkey ═══ spcbkey (SPCBKEY) Data stream type and internal key. The internal key is used to differentiate between multiple SPCBs of the same data stream type. User defines should be addressed to 8,000,000(h) and higher. ═══ SPCB Parameter - ulDataFlags ═══ ulDataFlags (ULONG) Attributes of the data type (that is, it specifies whether data or time cue points are supported by this data type). SPCBDATA_CUEDATA This data type can support data cue-point events. SPCBDATA_CUETIME This data type can support time cue-point events. SPCBDATA_NOSEEK Seeking cannot be done on this data type. SPCBDATA_YIELDTIME This flag indicates that the ulBytesPerUnit field of the SPCB is interpreted as a millisecond yield time value. This yield takes place in between each I/O read operation. The yield time will also dynamically lower during data streaming depending on how many buffers in the stream are full. This flag is mutually exclusive with the SPCBHAND_GENTIME flag and it can only be used with the SPCBBUF_INTERLEAVED flag. The maximum yield time is 1 second. ═══ SPCB Parameter - ulNumRec ═══ ulNumRec (ULONG) Maximum number of records per buffer. (This is valid only for split streams). ═══ SPCB Parameter - ulBlockSize ═══ ulBlockSize (ULONG) This field can be interpreted in two ways. If the SPCBBUF_INTERLEAVED flag is set, then this field is interpreted as the size of the I/O read operation. This is used to request a read buffer of a smaller size than the ulBufSize field. The source stream handler will take the buffer of ulBufSize and break up the actual I/O reads into ulBlockSize chunks. If ulBlockSize is 1, then the ulBufSize is used as the default I/O read buffer size. Otherwise, ulBlockSize will be the I/O read buffer size. The ulBufSize value must be a multiple of the ulBlockSize value. The second interpretation of this field is for non-interleaved streams, when the SPCBBUF_INTERLEAVED is not set. The ulBlockSize field represents the atom size of a data item. For example, for digital audio data type PCM 16-bit stereo at a 44.1KB sampling rate, the block size is 4 bytes. ═══ SPCB Parameter - ulBufSize ═══ ulBufSize (ULONG) Size of buffer to be used while streaming. Maximum buffer size is 64KB. ═══ SPCB Parameter - ulMinBuf ═══ ulMinBuf (ULONG) Minimum number of buffers needed to maintain a constant data stream. ═══ SPCB Parameter - ulMaxBuf ═══ ulMaxBuf (ULONG) Maximum (ideal) number of buffers needed. For normal streams, this means the number of buffers that are allocated for the stream. For user-provided buffer streaming, this means the number of buffers that the Sync/Stream Manager can queue for a consumer. This can be used by a source stream handler that gives the same set of buffers to the Sync/Stream Manager repeatedly. If the number of buffers is set to the number of buffers in the set -1, the source stream handler will be able to detect when the target has consumed a buffer so it can be reused. It is assumed that the set of buffers is an ordered set and each buffer is used in the same order each time. ═══ SPCB Parameter - ulSrcStart ═══ ulSrcStart (ULONG) Number of empty buffers required to start the source stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the source stream handler. ═══ SPCB Parameter - ulTgtStart ═══ ulTgtStart (ULONG) Number of full buffers required to start the target stream handler. The value must be at least as big as the maximum number of buffers that would be requested by the target stream handler. Usually, a target requires at least two buffers at the start of the stream. ═══ SPCB Parameter - ulBufFlags ═══ ulBufFlags (ULONG) Buffer attributes (that is, the user provides buffers, fixed block size, interleaved data type, maximum buffer size). SPCBBUF_16MEG The stream buffers can be allocated above the 16MB line. This is used by stream handler device drivers that can support greater than 16MB addresses. SPCBBUF_FIXEDBUF The buffer size for this stream handler must be a particular fixed size (for this data type). The SPCBBUF_INTERLEAVED flag (split stream) implies SPCBBUF_FIXEDBUF. SPCBBUF_INTERLEAVED This is a split stream. It consists of one input stream of interleaved data that is split into multiple streams of individual data types. Only the source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_USERPROVIDED flag. SPCBBUF_FIXEDBUF cannot be used with this flag set. SPCBBUF_MAXSIZE The ulBufSize field contains the maximum size buffer that this stream handler can handle. SPCBBUF_NONCONTIGUOUS Each data buffer is allocated contiguously in physical memory unless both stream handlers set the non-contiguous flag (SPCBBUF_NONCONTIGUOUS). This flag provides the system flexibility in allocating memory. A device driver stream handler might require contiguous memory, while a DLL stream handler might not. SPCBBUF_USERPROVIDED The user provides buffers for streaming. The Sync/Stream Manager does not allocate buffers but attempts to lock down user-provided buffers or copy the data to locked buffers. Using this flag affects the performance of streaming. Only a source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_INTERLEAVED flag. ═══ SPCB Parameter - ulHandFlags ═══ ulHandFlags (ULONG) Stream handler flags (that is, handlers can generate/receive sync pulses, use the Sync/Stream Manager timer as master, and use the non-streaming handler as a NULL handler). SPCBHAND_GENSYNC This stream handler can generate sync pulses. SPCBHAND_GENTIME This stream handler can keep track of the real stream time. This handler also supports the SpiGetTime function and cue point events. SPCBHAND_NOPREROLL This stream handler cannot preroll its device (that is, for recording streams, the source stream handler cannot be prerolled). If asked to preroll this stream, the Sync/Stream Manager treats this stream as if it were prerolled. SPCBHAND_NONSTREAM This stream handler is a non-streaming handler (that is, it is a stream handler that can participate in synchronization but does not stream). SPCBHAND_NOSYNC This stream handler can be in a sync group but does not receive or generate sync pulses. (It is useful to group streams so that they can be manipulated as a group). SPCBHAND_PHYS_SEEK This stream handler does a seek to a physical device. Other stream handlers adjust stream time only on a seek request. The Sync/Stream Manager always calls this stream handler first in an SpiSeekStream call. SPCBHAND_RCVSYNC This stream handler can receive sync pulses. SPCBHAND_TIMER This stream handler or the device (driver) it communicates with cannot support generation of sync pulses on a granularity necessary for synchronization. Therefore, use the stream manager sync timer as the master timer in a sync group. ═══ SPCB Parameter - mmtimeTolerance ═══ mmtimeTolerance (MMTIME) It is used to determine whether to send a sync pulse to a specific slave stream handler. ═══ SPCB Parameter - mmtimeSync ═══ mmtimeSync (MMTIME) Time interval in Chinatown units between sync pulses. Used to save sync pulse generation granularity if this stream handler is a master but cannot generate its own sync pulse. ═══ SPCB Parameter - ulBytesPerUnit ═══ ulBytesPerUnit (ULONG) Bytes per unit of time. This is used to do a seek on linear data that is not compressed or of variable length. Also used for SHC_GET_TIME queries in a stream handler. ═══ SPCB Parameter - mmtimePerUnit ═══ mmtimePerUnit (MMTIME) The amount of MMTIME each unit represents. This also is used for the SHC_SEEK and SHC_GETTIME messages. ═══ 17.48. SPCBKEY ═══ This structure identifies a stream protocol. typedef struct _SPCBKEY { ULONG ulDataType; /* Data type. */ ULONG ulDataSubType; /* Data subtype. */ ULONG ulIntKey; /* Internal key. */ } SPCBKEY; typedef SPCBKEY FAR *PSPCBKEY; ═══ SPCBKEY Parameter - ulDataType ═══ ulDataType (ULONG) Data type. ═══ SPCBKEY Parameter - ulDataSubType ═══ ulDataSubType (ULONG) Data subtype. ═══ SPCBKEY Parameter - ulIntKey ═══ ulIntKey (ULONG) Contains a unique value used to identify one of several stream protocols of the same data type and subtype. ═══ 17.49. STATUS_PARM ═══ This data structure contains fields for the pStatus and ulStatusSize fields of the DDCMDSTATUS data structure. typedef struct _STATUS_PARM { ULONG ulTime; /* Current position time in milliseconds. */ } STATUS_PARM; ═══ STATUS_PARM Parameter - ulTime ═══ ulTime (ULONG) Specifies the current position time in milliseconds. ═══ 17.50. SZ ═══ Null-terminated string (also known as a zero-terminated string). typedef CHAR SZ[]; ═══ 17.51. ULONG ═══ Unsigned integer in the range 0 through 4 294 967 295. typedef unsigned long ULONG; ═══ 17.52. USHORT ═══ Unsigned integer in the range 0 through 65 535. typedef unsigned short USHORT; ═══ 17.53. VCACAPISIZE ═══ typedef struct _VCACAPISIZE { ULONG X_Left; ULONG Y_Top; ULONG Y_Height; ULONG X_Width; ULONG ScaleFactor; } VCACAPISIZE; typedef VCACAPISIZE FAR * PVCACAPISIZE; ═══ VCACAPISIZE Parameter - X_Left ═══ X_Left (ULONG) ═══ VCACAPISIZE Parameter - Y_Top ═══ Y_Top (ULONG) ═══ VCACAPISIZE Parameter - Y_Height ═══ Y_Height (ULONG) ═══ VCACAPISIZE Parameter - X_Width ═══ X_Width (ULONG) ═══ VCACAPISIZE Parameter - ScaleFactor ═══ ScaleFactor (ULONG) ═══ 17.54. VCADEVINFO ═══ typedef struct _vcadevinfo { ULONG Length; /* Length of structure. */ CHAR ProdInfo[30]; /* Describes product information. */ CHAR ManInfo[30]; /* Describes manufacturer information. */ CHAR Version[10]; /* Describes version information. */ ULONG ImgFormat; /* Image format supported by the card. */ USHORT BitsPerPEL; /* Bits per pel in this image format. */ USHORT Overlay; /* Device has overlay support. */ ULONG Brightness; /* Default brightness value. */ ULONG hue; /* Default hue value. */ ULONG saturation; /* Default saturation value. */ ULONG contrast; /* Default contrast value. */ ULONG Sharpness; /* Default sharpness value. */ ULONG unused1; /* Reserved. */ ULONG S_X_Left; /* Source frame: default left coordinate. */ ULONG S_Y_Top; /* Source frame: default top coordinate. */ ULONG S_Y_Height; /* Source frame: default height coordinate. */ ULONG S_X_Width; /* Source frame: default width coordinate. */ ULONG D_X_Left; /* Destination frame: default left coordinate. */ ULONG D_Y_Top; /* Destination frame: default top coordinate. */ ULONG D_Y_Height; /* Destination frame: default height coordinate. */ ULONG D_X_Width; /* Destination frame: default width coordinate. */ ULONG D_ScaleFactor; ULONG S_X_MAX; /* Maximum X size for the digitized source. */ ULONG S_Y_MAX; /* Maximum Y size for the digitized source. */ ULONG D_X_MAX; /* Maximum X size for the destination. */ ULONG D_Y_MAX; /* Maximum Y size for the destination. */ ULONG O_X_MAX; /* Maximum X size for the overlay destination. */ ULONG O_Y_MAX; /* Maximum Y size for the overlay destination. */ USHORT VideoInputs; /* Number of software switchable video inputs. */ USHORT CanRestore; /* Can restore an image on the device. */ USHORT CanStretch; /* Can scale image from source to destination. */ USHORT CanDistort; /* Can scale image without maintaining aspect ratio. */ USHORT HasVolume; /* Video device has volume control. */ USHORT HasBalance; /* Video device has balance control. */ USHORT CanScale; /* Can scale down source image on GetImage IOCtl. */ USHORT CanStream; /* Can do streaming of images to stream handler. */ ULONG DI_ulFilenum; /* File number associated with this instance/open of the device. */ BYTE HasTuner; /* Card has a channel tuner. */ BYTE HasTeleTex; /* Card has teletex support. */ LONG Delay_Time; /* Delay (ms) between connector change/query signal. */ BYTE HasAFC; /* Automatic Frequency Control/FineTune. */ BYTE HasPolarization; /* Support video frequency polarization. */ } VCADEVINFO; typedef VCADEVINFO FAR * PVCADEVINFO; ═══ VCADEVINFO Parameter - Length ═══ Length (ULONG) Specifies the length, in bytes, of this structure. ═══ VCADEVINFO Parameter - ProdInfo[30] ═══ ProdInfo[30] (CHAR) String describing product information. ═══ VCADEVINFO Parameter - ManInfo[30] ═══ ManInfo[30] (CHAR) String describing manufacturer information. ═══ VCADEVINFO Parameter - Version[10] ═══ Version[10] (CHAR) String describing version information. ═══ VCADEVINFO Parameter - ImgFormat ═══ ImgFormat (ULONG) Indicates image format supported by the card. Valid image formats are: DI_IMAGEFORMAT_RGB_565 5 bits of red, 6 bits of green, 5 bits of blue. DI_IMAGEFORMAT_YUV_411 YUV_411 bit-interleaved format. ═══ VCADEVINFO Parameter - BitsPerPEL ═══ BitsPerPEL (USHORT) Specifies bits per pel in this image format. ═══ VCADEVINFO Parameter - Overlay ═══ Overlay (USHORT) Specifies if the device has overlay support (TRUE or FALSE). ═══ VCADEVINFO Parameter - Brightness ═══ Brightness (ULONG) Specifies the default brightness value (0 to 255). ═══ VCADEVINFO Parameter - hue ═══ hue (ULONG) Specifies the default hue value (0 to 255). ═══ VCADEVINFO Parameter - saturation ═══ saturation (ULONG) Specifies the default saturation value (0 to 255). ═══ VCADEVINFO Parameter - contrast ═══ contrast (ULONG) Specifies the default contrast value (0 to 255). ═══ VCADEVINFO Parameter - Sharpness ═══ Sharpness (ULONG) Specifies the default sharpness value (0 to 255). ═══ VCADEVINFO Parameter - unused1 ═══ unused1 (ULONG) Reserved. Set to zero. ═══ VCADEVINFO Parameter - S_X_Left ═══ S_X_Left (ULONG) Specifies the default source frame default left coordinate. ═══ VCADEVINFO Parameter - S_Y_Top ═══ S_Y_Top (ULONG) Specifies the default source frame default top coordinate. ═══ VCADEVINFO Parameter - S_Y_Height ═══ S_Y_Height (ULONG) Specifies the default source frame default height coordinate. ═══ VCADEVINFO Parameter - S_X_Width ═══ S_X_Width (ULONG) Specifies the default source frame default width coordinate. ═══ VCADEVINFO Parameter - D_X_Left ═══ D_X_Left (ULONG) Specifies the default destination frame default left coordinate. ═══ VCADEVINFO Parameter - D_Y_Top ═══ D_Y_Top (ULONG) Specifies the default destination frame default top coordinate. ═══ VCADEVINFO Parameter - D_Y_Height ═══ D_Y_Height (ULONG) Specifies the default destination frame default height coordinate. ═══ VCADEVINFO Parameter - D_X_Width ═══ D_X_Width (ULONG) Specifies the default destination frame default width coordinate. ═══ VCADEVINFO Parameter - D_ScaleFactor ═══ D_ScaleFactor (ULONG) Specifies the default scale factor on a copy action. ═══ VCADEVINFO Parameter - S_X_MAX ═══ S_X_MAX (ULONG) Indicates the maximum X size for the digitized source. ═══ VCADEVINFO Parameter - S_Y_MAX ═══ S_Y_MAX (ULONG) Indicates the maximum Y size for the digitized source. ═══ VCADEVINFO Parameter - D_X_MAX ═══ D_X_MAX (ULONG) Indicates the maximum X size for the destination. ═══ VCADEVINFO Parameter - D_Y_MAX ═══ D_Y_MAX (ULONG) Indicates the maximum Y size for the destination. ═══ VCADEVINFO Parameter - O_X_MAX ═══ O_X_MAX (ULONG) Indicates the maximum X size for the overlay destination. ═══ VCADEVINFO Parameter - O_Y_MAX ═══ O_Y_MAX (ULONG) Indicates the maximum Y size for the overlay destination. ═══ VCADEVINFO Parameter - VideoInputs ═══ VideoInputs (USHORT) Specifies the number of software switchable video inputs. ═══ VCADEVINFO Parameter - CanRestore ═══ CanRestore (USHORT) Indicates if an image can be restored on the device (TRUE or FALSE). ═══ VCADEVINFO Parameter - CanStretch ═══ CanStretch (USHORT) Indicates if the image can be scaled from source to destination (TRUE or FALSE). ═══ VCADEVINFO Parameter - CanDistort ═══ CanDistort (USHORT) Indicates if the image can be scaled without maintaining aspect ratio (TRUE or FALSE). ═══ VCADEVINFO Parameter - HasVolume ═══ HasVolume (USHORT) Indicates if the video device has volume control (TRUE or FALSE). ═══ VCADEVINFO Parameter - HasBalance ═══ HasBalance (USHORT) Indicates if the video device has balance control (TRUE or FALSE). ═══ VCADEVINFO Parameter - CanScale ═══ CanScale (USHORT) Indicates if the image can be scaled down on GetImage IOCtl (TRUE or FALSE). ═══ VCADEVINFO Parameter - CanStream ═══ CanStream (USHORT) Indicates if the device supports streaming of images to stream handler (TRUE or FALSE). ═══ VCADEVINFO Parameter - DI_ulFilenum ═══ DI_ulFilenum (ULONG) This file number is used to associate the stream creation with a particular open instance. ═══ VCADEVINFO Parameter - HasTuner ═══ HasTuner (BYTE) Card has a channel tuner. ═══ VCADEVINFO Parameter - HasTeleTex ═══ HasTeleTex (BYTE) Card has teletex support. ═══ VCADEVINFO Parameter - Delay_Time ═══ Delay_Time (LONG) Delay (ms) between connector change/query signal. ═══ VCADEVINFO Parameter - HasAFC ═══ HasAFC (BYTE) Automatic Frequency Control/FineTune. ═══ VCADEVINFO Parameter - HasPolarization ═══ HasPolarization (BYTE) Support video frequency polarization. ═══ 17.55. VCAEDCOLORKEY ═══ typedef struct _VCAEDCOLORKEY { BOOL bColorKeying; /* 1=TRUE=ON, 0=FALSE=OFF. */ } VCAEDCOLORKEY; typedef VCAEDCOLORKEY FAR * PVCAEDCOLORKEY; ═══ VCAEDCOLORKEY Parameter - bColorKeying ═══ bColorKeying (BOOL) 1=TRUE=ON, 0=FALSE=OFF. ═══ 17.56. VCAGETIMAGESCALE ═══ typedef struct _VCAGETIMAGESCALE { ULONG Capture_Buf_Len; /* Length, in bytes, of capture buffer. */ ULONG Capture_Buf_Ptr; /* Pointer to the capture buffer. */ ULONG Source_X_Left; /* Leftmost pel offset in source frame. */ ULONG Source_Y_Top; /* Topmost pel offset in source frame. */ ULONG Source_Y_Height; /* Height of source frame, in pels. */ ULONG Source_X_Width; /* Width of source frame, in pels. */ ULONG Dest_X_Left; /* Destination frame's left transpose offset. */ ULONG Dest_Y_Top; /* Destination frame's top transpose offset. */ ULONG Dest_Y_Height; /* Height of destination frame in pels. */ ULONG Dest_X_Width; /* Width of destination frame in pels. */ } VCAGETIMAGESCALE; typedef VCAGETIMAGESCLAE FAR * PVCAGETIMAGESCALE; ═══ VCAGETIMAGESCALE Parameter - Capture_Buf_Len ═══ Capture_Buf_Len (ULONG) Specifies the length, in bytes, of the capture buffer. ═══ VCAGETIMAGESCALE Parameter - Capture_Buf_Ptr ═══ Capture_Buf_Ptr (ULONG) Specifies a pointer to the capture buffer. ═══ VCAGETIMAGESCALE Parameter - Source_X_Left ═══ Source_X_Left (ULONG) Specifies the leftmost pel offset in the source frame. ═══ VCAGETIMAGESCALE Parameter - Source_Y_Top ═══ Source_Y_Top (ULONG) Specifies the topmost pel offset in the source frame. ═══ VCAGETIMAGESCALE Parameter - Source_Y_Height ═══ Source_Y_Height (ULONG) Specifies the height of the source frame, in pels. ═══ VCAGETIMAGESCALE Parameter - Source_X_Width ═══ Source_X_Width (ULONG) Specifies the width of the source frame, in pels. ═══ VCAGETIMAGESCALE Parameter - Dest_X_Left ═══ Dest_X_Left (ULONG) Specifies the destination frame's left transpose offset. ═══ VCAGETIMAGESCALE Parameter - Dest_Y_Top ═══ Dest_Y_Top (ULONG) Specifies the destination frame's top transpose offset. ═══ VCAGETIMAGESCALE Parameter - Dest_Y_Height ═══ Dest_Y_Height (ULONG) Specifies the height of the destination frame in pels. ═══ VCAGETIMAGESCALE Parameter - Dest_X_Width ═══ Dest_X_Width (ULONG) Specifies the width of the destination frame in pels. ═══ 17.57. VCALOAD ═══ This structure contains fields for the VCAI_LOAD_MICROCODE function. typedef struct _VCALOAD { ULONG ulflags; /* 1=Query, 2=Load, 3=Unload. */ CHAR ProdInfo[256]; /* Path and name of microcode load. */ LONG ulLoadID; /* Load ID (returned on a load). */ ULONG ulLength; /* Length of load data. */ PVOID pLoadData; /* Pointer to microcode load data. */ } VCALOAD; typedef VCALOAD FAR * PVCALOAD; ═══ VCALOAD Parameter - ulflags ═══ ulflags (ULONG) The following flags are defined. VCALOAD_QUERY 0x01 VCALOAD_LOAD 0x02 VCALOAD_UNLOAD 0x03 ═══ VCALOAD Parameter - ProdInfo[256] ═══ ProdInfo[256] (CHAR) Path and name of microcode load. ═══ VCALOAD Parameter - ulLoadID ═══ ulLoadID (LONG) Load ID (returned on a load). ═══ VCALOAD Parameter - ulLength ═══ ulLength (ULONG) Length of load data. ═══ VCALOAD Parameter - pLoadData ═══ pLoadData (PVOID) Pointer to microcode load data. ═══ 17.58. VCAIMAGERF ═══ This structure contains fields for the VCAI_RESTORE_FORMAT function. typedef struct _VCAIMAGERF { ULONG ulFlags; /* 0=Query, 1=Set. */ ULONG ulNumFormats; /* Number of supported formats. */ ULONG ulCurIndex; /* Current format (or format to set to). */ ULONG FourCC[64]; /* Name of format. */ } VCAIMAGERF; typedef VCAIMAGERF FAR * PVCAIMAGERF; ═══ VCAIMAGERF Parameter - ulFlags ═══ ulFlags (ULONG) The following values are defined for ulFlags. VCAIRF_Query 0x00 VCAIRF_Set 0x01 ═══ VCAIMAGERF Parameter - ulNumFormats ═══ ulNumFormats (ULONG) Number of supported formats. ═══ VCAIMAGERF Parameter - ulCurIndex ═══ ulCurIndex (ULONG) Current format (or format to set to). ═══ VCAIMAGERF Parameter - FourCC[64] ═══ FourCC[64] (ULONG) Name of format. ═══ 17.59. VCAIMAGECF ═══ This structure contains fields for the VCAI_CAPTURE_FORMAT function. typedef struct _VCAIMAGECF { ULONG ulFlags; /* 0=Query, 1=Set. */ ULONG ulNumFormats; /* Number of supported formats. */ ULONG ulCurIndex; /* Current format (or format to set to). */ ULONG FourCC[64]; /* Name of format. */ } VCAIMAGECF; typedef VCAIMAGECF FAR * PVCAIMAGECF; ═══ VCAIMAGECF Parameter - ulFlags ═══ ulFlags (ULONG) The following values are defined for ulFlags. VCAICF_Query 0x00 VCAICF_Set 0x01 ═══ VCAIMAGECF Parameter - ulNumFormats ═══ ulNumFormats (ULONG) Number of supported formats. ═══ VCAIMAGECF Parameter - ulCurIndex ═══ ulCurIndex (ULONG) Current format (or format to set to). ═══ VCAIMAGECF Parameter - FourCC[64] ═══ FourCC[64] (ULONG) Name of format. ═══ 17.60. VCASETCAPTURERECT ═══ typedef struct _VCASETCAPTURERECT { ULONG Source_X_Left; /* Leftmost pel offset in source frame. */ ULONG Source_Y_Top; /* Topmost pel offset in source frame. */ ULONG Source_Y_Height; /* Height of source frame, in pels. */ ULONG Source_X_Width; /* Width of source frame, in pels. */ ULONG Dest_X_Left; /* Destination frame's left transpose offset. */ ULONG Dest_Y_Top; /* Destination frame's top transpose offset. */ ULONG Dest_Y_Height; /* Height of destination frame in pels. */ ULONG Dest_X_Width; /* Width of destination frame in pels. */ } VCASETCAPTURERECT; typedef VCASETCAPTURERECT FAR * PVCASETCAPTURERECT; ═══ VCASETCAPTURERECT Parameter - Source_X_Left ═══ Source_X_Left (ULONG) Specifies the leftmost pel offset in the source frame. ═══ VCASETCAPTURERECT Parameter - Source_Y_Top ═══ Source_Y_Top (ULONG) Specifies the topmost pel offset in the source frame. ═══ VCASETCAPTURERECT Parameter - Source_Y_Height ═══ Source_Y_Height (ULONG) Specifies the height of source frame, in pels. ═══ VCASETCAPTURERECT Parameter - Source_X_Width ═══ Source_X_Width (ULONG) Specifies the width of source frame, in pels. ═══ VCASETCAPTURERECT Parameter - Dest_X_Left ═══ Dest_X_Left (ULONG) Specifies the destination frame's left transpose offset. ═══ VCASETCAPTURERECT Parameter - Dest_Y_Top ═══ Dest_Y_Top (ULONG) Specifies the destination frame's top transpose offset. ═══ VCASETCAPTURERECT Parameter - Dest_Y_Height ═══ Dest_Y_Height (ULONG) Specifies the height of the destination frame in pels. ═══ VCASETCAPTURERECT Parameter - Dest_X_Width ═══ Dest_X_Width (ULONG) Specifies the width of the destination frame in pels. ═══ 17.61. VCASETCOLORKEY ═══ typedef struct _VCASETCOLORKEY { ULONG ulColorKey; /* Transparent color. */ } VCASETCOLORKEY; typedef VCASETCOLORKEY FAR * PVCASETCOLORKEY; ═══ VCASETCOLORKEY Parameter - ulColorKey ═══ ulColorKey (ULONG) Transparent color. ═══ 17.62. VCASETFPS ═══ This structure contains fields for the VCAI_SETFPS function. typedef struct _VCASETFPS { ULONG set_FPS; /* Frames per second to stream. */ ULONG ulFlags; /* Frames or microseconds. */ } VCASETFPS; typedef VCASETFPS FAR * PVCASETFPS; ═══ VCASETFPS Parameter - set_FPS ═══ set_FPS (ULONG) Frames per second to stream to the stream handler. ═══ VCASETFPS Parameter - ulFlags ═══ ulFlags (ULONG) The following ulFlags are defined: VCASF_FRAMES 0x0 VCASF_MICROSECONDS 0x1 ═══ 17.63. VCASETMONITOR ═══ typedef struct _VCASETMONITOR { BOOL bMonitor; /* 1=TRUE=ON, 0=FALSE=OFF. */ } VCASETMONITOR; typedef VCASETMONITOR FAR * PVCASETMONITOR; ═══ VCASETMONITOR Parameter - bMonitor ═══ bMonitor (BOOL) 1=TRUE=ON, 0=FALSE=OFF. ═══ 17.64. VCASETVIDEO ═══ typedef struct _VCASETVIDEO { ULONG set_brightness; /* New overall image brightness setting. */ ULONG set_hue; /* New image hue (color) setting. */ ULONG set_saturation; /* New color intensity setting. */ ULONG set_contrast; /* New contrast setting. */ ULONG ret_brightness; /* Current overall image brightness setting. */ ULONG ret_hue; /* Current image hue (color) setting. */ ULONG ret_saturation; /* Current color intensity setting. */ ULONG ret_contrast; /* Current contrast setting. */ } VCASETVIDEO; typedef VCASETVIDEO FAR * PVCASETVIDEO; ═══ VCASETVIDEO Parameter - set_brightness ═══ set_brightness (ULONG) Specifies the new overall image brightness setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT. ═══ VCASETVIDEO Parameter - set_hue ═══ set_hue (ULONG) Specifies the new image hue (color) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT. ═══ VCASETVIDEO Parameter - set_saturation ═══ set_saturation (ULONG) Specifies the new saturation (color intensity) setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT. ═══ VCASETVIDEO Parameter - set_contrast ═══ set_contrast (ULONG) Specifies the new luminance contrast setting. Valid values are 0 to 255, NO_CHANGE, or DEFAULT. ═══ VCASETVIDEO Parameter - ret_brightness ═══ ret_brightness (ULONG) Specifies the current overall image brightness setting. Valid values are 0 to 255 or NOT_SUPPORTED. ═══ VCASETVIDEO Parameter - ret_hue ═══ ret_hue (ULONG) Specifies the current image hue (color) setting. Valid values are 0 to 255 or NOT_SUPPORTED. ═══ VCASETVIDEO Parameter - ret_saturation ═══ ret_saturation (ULONG) Specifies the current color intensity setting. Valid values are 0 to 255 or NOT_SUPPORTED. ═══ VCASETVIDEO Parameter - ret_contrast ═══ ret_contrast (ULONG) Specifies the current luminance contrast setting. Valid values are 0 to 255 or NOT_SUPPORTED. ═══ 17.65. VCASETVIDEOINPUT ═══ typedef struct _VCASETVIDEOINPUT { ULONG INPUT_CONNECTOR; /* Connector value. */ } VCASETVIDEOINPUT; typedef VCASETVIDEOINPUT FAR * PVCASETVIDEOINPUT; ═══ VCASETVIDEOINPUT Parameter - INPUT_CONNECTOR ═══ INPUT_CONNECTOR (ULONG) Sets or queries the input connector value. A value of -1 performs a query and returns the current connector value. A value of -2 sets the video input source connector to the default value. ═══ 17.66. VCASTREAM ═══ This structure contains fields for the VCAI_PLAY function. typedef struct _VCASTREAM { ULONG ulLength; /* Length of image data. */ PVOID pImageData; /* Pointer to image data. */ ULONG ulFlags; /* Flag information. */ ULONG ulSCR; /* MPEG system clock reference (SCR). */ ULONG ulPTS; /* MPEG system clock reference (SCR). */ ULONG ulAudioTime; /* Current audio stream time. */ } VCASTREAM; typedef VCASTREAM FAR * PVCASTREAM; ═══ VCASTREAM Parameter - ulLength ═══ ulLength (ULONG) Length of image data. ═══ VCASTREAM Parameter - pImageData ═══ pImageData (PVOID) Pointer to image data. ═══ VCASTREAM Parameter - ulFlags ═══ ulFlags (ULONG) The following flags are defined. VCA_PLAY_START 0x01 VCA_PLAY_DATA 0x02 VCA_PLAY_STOP 0x04 VCA_PLAY_FLUSH 0x08 ═══ VCASTREAM Parameter - ulSCR ═══ ulSCR (ULONG) MPEG System clock reference (SCR). Set to 0 if current packet does not contain a PTS or SCR. CODEC-specific, currently used only in MPEG playback. ═══ VCASTREAM Parameter - ulPTS ═══ ulPTS (ULONG) MPEG System clock reference (SCR). Set to 0 if current packet does not contain a PTS or SCR. CODEC-specific, currently used only in MPEG playback. ═══ VCASTREAM Parameter - ulAudioTime ═══ ulAudioTime (ULONG) Current audio stream time in MMTIME on latest sync pulse. CODEC-specific, currently used only in MPEG playback. ═══ 17.67. VCATUNCHAN ═══ This structure contains fields for the VCAI_TUNERCHANNEL function. typedef struct _VCATUNCHAN { ULONG ulFlags; /* 1=Set, 2=Query. */ ULONG ulOptions; /* Options. */ USHORT usResv01; /* Reserved. */ USHORT usResv02; /* Reserved. */ LONG lFineTune; /* Fine tune value for channel. */ ULONG ulFrequency; /* Frequency instead of channel/region. */ } VCATUNCHAN; typedef VCATUNCHAN FAR * PVCATUNCHAN; ═══ VCATUNCHAN Parameter - ulFlags ═══ ulFlags (ULONG) The following flags are defined. TUC_SET_CHANNEL 1 TUC_QUERY_CHANNEL 2 ═══ VCATUNCHAN Parameter - ulOptions ═══ ulOptions (ULONG) The ulOptions field is a bit-sensitive field. The following values are defined for ulOptions. TUC_AFC_ON 4 TUC_AFC_OFF 0 TUC_FREQUENCY 8 TUC_CHANNEL 0 TUC_POLOARIZATION_VERT 16 TUC_POLOARIZATION_HORI 32 ═══ VCATUNCHAN Parameter - usResv01 ═══ usResv01 (USHORT) Resv01 set to 0. ═══ VCATUNCHAN Parameter - usResv02 ═══ usResv02 (USHORT) Resv02 set to 0. ═══ VCATUNCHAN Parameter - lFineTune ═══ lFineTune (LONG) Fine tune value for channel. ═══ VCATUNCHAN Parameter - ulFrequency ═══ ulFrequency (ULONG) Frequency instead of channel/region. ═══ 17.68. VSD_AUDIOATTRIBUTES_PARMS ═══ This structure contains fields for the VSD_QUERYAUDIOATTRIBUTES command. typedef struct _VSD_AUDIOATTRIBUTES_PARMS { ULONG ulLength; /* Length of the structure. */ ULONG ulFlags; /* Attribute to set. */ ULONG ulValue; /* Input/Output. Value for attribute setting. */ ULONG ulDelay; /* Input. Delay for attribute setting. */ } VSD_AUDIOATTRIBUTES_PARMS; typedef VSD_AUDIOATTRIBUTES_PARMS *PVSD_AUDIOATTRIBUTES_PARMS; ═══ VSD_AUDIOATTRIBUTES_PARMS Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ VSD_AUDIOATTRIBUTES_PARMS Parameter - ulFlags ═══ ulFlags (ULONG) Input. The following values are defined for ulFlags. VSD_BALANCE Set or query balance. VSD_BASS Set or query bass. VSD_GAIN Set or query gain. VSD_TREBLE Set or query treble. VSD_PITCH Set or query pitch. ═══ VSD_AUDIOATTRIBUTES_PARMS Parameter - ulValue ═══ ulValue (ULONG) Input/Output. Value for attribute setting. ═══ VSD_AUDIOATTRIBUTES_PARMS Parameter - ulDelay ═══ ulDelay (ULONG) Delay for attribute setting to take place in mmtime units. ═══ 17.69. VSD_AUDIODATATYPE_PARMS ═══ This structure contains fields for the VSD_OPEN command. typedef struct _VSD_AUDIODATATYPE_PARMS { ULONG ulLength; /* Length of the structure. */ ULONG ulFlags; /* Flags. */ ULONG ulSamplingRate; /* Input. Sampling rate setting. */ ULONG ulBitsPerSample; /* Input. Bits per sample setting. */ ULONG ulChannels; /* Input. Channels setting. */ ULONG ulBlockAlignment; /* Output. Block alignment. */ ULONG ulAverageBytesPerSec; /* Output. Average bytes per second throughput. */ ULONG ulDataType; /* Input. Data type to set or query. */ ULONG ulDataSubType; /* Output. Data subtype info. */ ULONG ulReserved1; /* Reserved. */ ULONG ulOperation; /* Input. VSD_PRODUCE or VSD_CONSUME. */ ULONG ulDeviceID; /* Input. Device ID of the amp-mixer. */ PVOID pDevInfo; /* Device-specific information. */ } VSD_AUDIODATATYPE_PARMS; typedef VSD_AUDIODATATYPE_PARMS *PVSD_AUDIODATATYPE_PARMS; ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulFlags ═══ ulFlags (ULONG) Flags indicating which fields are to be queried or modified. The VSD_AUDIODATATYPE_PARMS structure must contain at least one of the following flags. Note: More than one flag can be specified. VSD_MODE Set/query mode. VSD_CHANNELS Set/query channels. VSD_SAMPLESPERSEC Set/query sampling rate. VSD_BITSPERSAMPLE Set/query bits per sample. VSD_OPERATION Set/query VSD operation field. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulSamplingRate ═══ ulSamplingRate (ULONG) Input. Sampling rate setting. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulBitsPerSample ═══ ulBitsPerSample (ULONG) Input. Bits per sample setting. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulChannels ═══ ulChannels (ULONG) Input. Channels setting. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulBlockAlignment ═══ ulBlockAlignment (ULONG) Output. Block alignment. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulAverageBytesPerSec ═══ ulAverageBytesPerSec (ULONG) Output. Average bytes per second throughput. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulDataType ═══ ulDataType (ULONG) Input. Data type to set or query. This value is a RIFF datatype (such as DATATYPE_WAVEFORM) defined in OS2MEDEF.H. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulDataSubType ═══ ulDataSubType (ULONG) Output. Data subtype info. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulReserved1 ═══ ulReserved1 (ULONG) Reserved. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulOperation ═══ ulOperation (ULONG) Input. Operation to perform; set to either VSD_PRODUCE or VSD_CONSUME. ═══ VSD_AUDIODATATYPE_PARMS Parameter - ulDeviceID ═══ ulDeviceID (ULONG) Input. Device ID of the amp-mixer. ═══ VSD_AUDIODATATYPE_PARMS Parameter - pDevInfo ═══ pDevInfo (PVOID) Device-specific information. ═══ 17.70. VSD_AUDIOOPEN_PARMS ═══ This structure contains fields for the VSD_OPEN command. typedef struct _VSD_AUDIOOPEN_PARMS { ULONG ulLength; /* Input. Length of the structure. */ ULONG ulFlags; /* Input. Flags. */ ULONG ulSamplingRate; /* Input. Sampling rate. */ ULONG ulBitsPerSample; /* Input. Bits per sample. */ ULONG ulChannels; /* Input. Channels. */ ULONG ulBlockAlignment; /* Input. Block alignment. */ ULONG ulAverageBytesPerSec; /* Output. Average bytes per second throughput. */ ULONG ulDataType; /* Input. Data type to set or query. */ ULONG ulDataSubType; /* Output. Data subtype info. */ ULONG hidSource; /* Input. Source stream handler for VSD. (Unused) */ ULONG hidTarget; /* Input. Target stream handler for VSD. (Unused) */ ULONG ulOperation; /* Input. Operation to perform. */ ULONG ulReserved1; /* Reserved. */ ULONG ulDeviceID; /* Input. Device ID of the amp-mixer. */ PVOID pHeader; /* Pointer to media-specific header. */ PVOID pParmString; /* Input. Device-specific parm string. */ PVOID pDevInfo; /* Device-specific information. */ ULONG ulReserved2; /* Reserved. */ PCHAR pResourceDLL; /* Input. Resource DLL from MMPM2.INI file. */ ULONG ulResourceId; /* Input. Resource ID to use in Resource DLL. */ } VSD_AUDIOOPEN_PARMS; typedef VSD_AUDIOOPEN_PARMS *PVSD_AUDIOOPEN_PARMS; ═══ VSD_AUDIOOPEN_PARMS Parameter - ulLength ═══ ulLength (ULONG) Input. Length of the structure. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulFlags ═══ ulFlags (ULONG) Input. Flags indicating which fields are to be queried or modified. (Unused) ═══ VSD_AUDIOOPEN_PARMS Parameter - ulSamplingRate ═══ ulSamplingRate (ULONG) Input. Sampling rate. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulBitsPerSample ═══ ulBitsPerSample (ULONG) Input. Bits per sample. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulChannels ═══ ulChannels (ULONG) Input. Channels. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulBlockAlignment ═══ ulBlockAlignment (ULONG) Input. Block alignment. (Unused) ═══ VSD_AUDIOOPEN_PARMS Parameter - ulAverageBytesPerSec ═══ ulAverageBytesPerSec (ULONG) Output. Average bytes per second throughput. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulDataType ═══ ulDataType (ULONG) Input. Data type to set or query. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulDataSubType ═══ ulDataSubType (ULONG) Output. Data subtype info. ═══ VSD_AUDIOOPEN_PARMS Parameter - hidSource ═══ hidSource (ULONG) Input. Source stream handler for VSD. (Unused) ═══ VSD_AUDIOOPEN_PARMS Parameter - hidTarget ═══ hidTarget (ULONG) Input. Target stream handler for VSD. (Unused) ═══ VSD_AUDIOOPEN_PARMS Parameter - ulOperation ═══ ulOperation (ULONG) Input. Operation to perform. Defined values for ulOperation include VSD_PRODUCE and VSD_CONSUME. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulReserved1 ═══ ulReserved1 (ULONG) Reserved. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulDeviceID ═══ ulDeviceID (ULONG) Input. Device ID of the amp-mixer. This ID is necessary if media control interface calls must be made by the VSD. ═══ VSD_AUDIOOPEN_PARMS Parameter - pHeader ═══ pHeader (PVOID) Pointer to media-specific header. For audio, it is an MMAUDIOHEADER. For further information, see the OS/2 Multimedia Programming Reference. (Unused) ═══ VSD_AUDIOOPEN_PARMS Parameter - pParmString ═══ pParmString (PVOID) Input. Pointer to device-specific parmstring in MMPM2.INI file. ═══ VSD_AUDIOOPEN_PARMS Parameter - pDevInfo ═══ pDevInfo (PVOID) Device-specific information. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulReserved2 ═══ ulReserved2 (ULONG) Reserved. ═══ VSD_AUDIOOPEN_PARMS Parameter - pResourceDLL ═══ pResourceDLL (PCHAR) Input. Resource DLL from MMPM2.INI file. VSD can use this file to retrieve VSD-specific setup information. ═══ VSD_AUDIOOPEN_PARMS Parameter - ulResourceId ═══ ulResourceId (ULONG) Input. Resource ID to use in Resource DLL. ═══ 17.71. VSD_CONNECTOR_PARMS ═══ This structure contains fields for the VSD_QUERYCONNECTOR message. typedef struct _VSD_CONNECTOR_PARMS { ULONG ulLength; /* Input. Length of the structure. */ ULONG ulFlags; /* Flags to be queried or modified. */ CHAR ulConn_Type; /* Input. Type of connector. */ ULONG ulIndex; /* Input. Connector number. */ BOOL fEnabled; /* Input/Output. Indicates enabled or disabled. */ } VSD_CONNECTOR_PARMS; typedef VSD_CONNECTOR_PARMS *PVSD_CONNECTOR_PARMS; ═══ VSD_CONNECTOR_PARMS Parameter - ulLength ═══ ulLength (ULONG) Input. Length of the structure. ═══ VSD_CONNECTOR_PARMS Parameter - ulFlags ═══ ulFlags (ULONG) Flags to be queried or modified. ═══ VSD_CONNECTOR_PARMS Parameter - ulConn_Type ═══ ulConn_Type (CHAR) Input. Type of connector. ═══ VSD_CONNECTOR_PARMS Parameter - ulIndex ═══ ulIndex (ULONG) Input. Connector number. ═══ VSD_CONNECTOR_PARMS Parameter - fEnabled ═══ fEnabled (BOOL) Input. Indicates if connector is enabled or disabled. ═══ 17.72. VSD_ESCAPE_PARMS ═══ This structure contains fields for the VSD_ESCAPE message. typedef struct _VSD_ESCAPE_PARMS { ULONG ulLength; /* Length of the structure. */ PVOID pBuffer; /* Information for VSD. */ ULONG ulBufferLength; /* Length of pBuffer. */ } VSD_ESCAPE_PARMS; typedef VSD_ESCAPE_PARMS *PVSD_ESCAPE_PARMS; ═══ VSD_ESCAPE_PARMS Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ VSD_ESCAPE_PARMS Parameter - pBuffer ═══ pBuffer (PVOID) Information to pass to the VSD. ═══ VSD_ESCAPE_PARMS Parameter - ulBufferLength ═══ ulBufferLength (ULONG) Length of pBuffer. ═══ 17.73. VSD_GETDEVCAPS_PARMS ═══ This structure contains fields for the VSD_GETDEVCAPS message. typedef struct _VSD_GETDEVCAPS_PARMS { ULONG ulLength; /* Input. Length of the structure. */ ULONG ulMax_Caps; /* Output. Returns maximum capabilities supported. */ ULONG ulNum_Caps; /* Output. Returns number of capabilities returned. */ ULONG ulResv01; /* Reserved. */ ULONG ulResv02; /* Reserved. */ ULONG ulResv03; /* Reserved. */ ULONG ulResv04; /* Reserved. */ ULONG bSupports[DC_MAX_DEVCAP]; /* Output. Capability entries. */ } VSD_GETDEVCAPS_PARMS; typedef VSD_GETDEVCAPS_PARMS *PVSD_GETDEVCAPS_PARMS; ═══ VSD_GETDEVCAPS_PARMS Parameter - ulLength ═══ ulLength (ULONG) Input. Length of the structure. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulMax_Caps ═══ ulMax_Caps (ULONG) Output. Returns maximum capabilities supported. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulNum_Caps ═══ ulNum_Caps (ULONG) Output. Returns number of capabilities returned. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulResv01 ═══ ulResv01 (ULONG) Reserved. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulResv02 ═══ ulResv02 (ULONG) Reserved. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulResv03 ═══ ulResv03 (ULONG) Reserved. ═══ VSD_GETDEVCAPS_PARMS Parameter - ulResv04 ═══ ulResv04 (ULONG) Reserved. ═══ VSD_GETDEVCAPS_PARMS Parameter - bSupports[DC_MAX_DEVCAP] ═══ bSupports[DC_MAX_DEVCAP] (ULONG) The following table lists the valid device capabilities. ┌─────────────────────────┬─────────────────────────┐ │Device Capabilities │Supported Command │ ├─────────────────────────┼─────────────────────────┤ │DC_HASAUDIO │All audio functions │ ├─────────────────────────┼─────────────────────────┤ │DC_HASVIDEO │All video functions │ ├─────────────────────────┼─────────────────────────┤ │DC_HASVOLUME │VSD_QUERYVOLUME │ │ │VSD_SETVOLUME │ ├─────────────────────────┼─────────────────────────┤ │DC_HASDISPLAY │VSD_QUERYDISPLAY │ │ │VSD_SETDISPLAY │ ├─────────────────────────┼─────────────────────────┤ │DC_HASAUDIOATTRIBUTES │VSD_QUERYAUDIOATTRIBUTES │ │ │VSD_SETAUDIOATTRIBUTES │ ├─────────────────────────┼─────────────────────────┤ │DC_HASAUDIOCAPABILITIES │VSD_QUERYDATATYPE │ │ │VSD_SETDATATYPE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASVIDEOATTRIBUTES │VSD_QUERYVIDEOATTRIBUTES │ │ │VSD_SETVIDEOATTRIBUTES │ ├─────────────────────────┼─────────────────────────┤ │DC_HASIMAGEATTRIBUTES │VSD_QUERYIMAGEATTRIBUTES │ │ │VSD_SETIMAGEATTRIBUTES │ ├─────────────────────────┼─────────────────────────┤ │DC_HASESCAPE │VSD_ESCAPE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASINPUTLEVEL │VSD_QUERYINPUTLEVEL │ │ │VSD_SETINPUTLEVEL │ ├─────────────────────────┼─────────────────────────┤ │DC_HASSTATUSLEVEL │VSD_QUERYSTATUSLEVEL │ ├─────────────────────────┼─────────────────────────┤ │DC_HASMONITOR │VSD_QUERYMONITOR │ │ │VSD_SETMONITOR │ ├─────────────────────────┼─────────────────────────┤ │DC_CANEJECT │VSD_EJECT │ ├─────────────────────────┼─────────────────────────┤ │DC_CANLOAD │VSD_LOAD │ ├─────────────────────────┼─────────────────────────┤ │DC_HASDOOR │VSD_QUERYDOOR │ │ │VSD_SETDOOR │ ├─────────────────────────┼─────────────────────────┤ │DC_HASTRACKS │VSD_QUERYTRACKS │ │ │VSD_SETTRACKS │ ├─────────────────────────┼─────────────────────────┤ │DC_HASMEDIA │VSD_QUERYMEDIATYPE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASCOMSETTINGS │VSD_QUERYCOMMSETTINGS │ │ │VSD_SETCOMSETTINGS │ ├─────────────────────────┼─────────────────────────┤ │DC_HASMEDIATYPE │VSD_QUERYMEDIATYPE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASKEYLOCK │VSD_QUERYKEYLOCK │ │ │VSD_SETKEYLOCK │ ├─────────────────────────┼─────────────────────────┤ │DC_CANCUE │VSD_QUERYCUE │ │ │VSD_SETCUE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASCOUNTER │VSD_QUERYCOUNTER │ │ │VSD_SETCOUNTER │ ├─────────────────────────┼─────────────────────────┤ │DC_CANRESET │VSD_RESET │ ├─────────────────────────┼─────────────────────────┤ │DC_HASPOSITION │VSD_QUERYPOSITION │ │ │VSD_SETPOSITION │ ├─────────────────────────┼─────────────────────────┤ │DC_HASLENGTH │VSD_QUERYLENGTH │ │ │VSD_SETLENGTH │ ├─────────────────────────┼─────────────────────────┤ │DC_CANPARK │VSD_PARK │ ├─────────────────────────┼─────────────────────────┤ │DC_HASCONNECTOR │VSD_QUERYCONNECTOR │ │ │VSD_SETCONNECTOR │ ├─────────────────────────┼─────────────────────────┤ │DC_HASEVENTS │VSD_EVENT │ ├─────────────────────────┼─────────────────────────┤ │DC_HASDIRECTION │VSD_QUERYDIRECTION │ │ │VSD_SETDIRECTION │ ├─────────────────────────┼─────────────────────────┤ │DC_HASVIEWPORT │VSD_QUERYVIEWPORT │ │ │VSD_SETVIEWPORT │ ├─────────────────────────┼─────────────────────────┤ │DC_CANCAPTUREIMAGE │VSD_CAPTUREIMAGE │ ├─────────────────────────┼─────────────────────────┤ │DC_CANRESTOREIMAGE │VSD_RESTOREIMAGE │ ├─────────────────────────┼─────────────────────────┤ │DC_HASRAM │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_AUDIOSETTINGS │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_IMAGESETTINGS │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_QUERYMINSEEKTIME │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_QUERYTIME │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_STEP │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_CAN_MIX │Mixer functions are │ │ │available │ ├─────────────────────────┼─────────────────────────┤ │DC_HASCLOCK │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASPOWER │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASZOOM │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASFOCUS │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASCHANNELS │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_CANSTREAM │VSD_DDCMD │ ├─────────────────────────┼─────────────────────────┤ │DC_CANSCALE │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_CANDISTORT │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_CANSTRETCH │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASTUNER │Informational │ ├─────────────────────────┼─────────────────────────┤ │DC_HASTELETEX │Informational │ └─────────────────────────┴─────────────────────────┘ Note: Informational in the above table indicates the device has the capability, but does not indicate that a particular command is supported. ═══ 17.74. VSD_OPEN_PARMS ═══ This structure contains fields for the VSD_OPEN message. typedef struct _VSD_OPEN_PARMS { ULONG ulLength; /* Input. Length of the structure. */ ULONG ulCategory; /* Name of unit to open. */ CHAR szInstallName[MAX_DEVICE_NAME]; /* Installation name of MCD. */ CHAR szPDDName[MAX_DEVICE_NAME]; /* Name of PDD to open. */ HVSD hvsd; /* Output. Handle to the VSD driver. */ PFN pfEvent; /* Output. (Unused) */ PVOID pDevInfo; /* Device-specific info. */ ULONG ulDDStream; /* Input. Device driver stream identifier. (Unused) */ } VSD_OPEN_PARMS; typedef VSD_OPEN_PARMS *PVSD_OPEN_PARMS; ═══ VSD_OPEN_PARMS Parameter - ulLength ═══ ulLength (ULONG) Input. Length of the structure. ═══ VSD_OPEN_PARMS Parameter - ulCategory ═══ ulCategory (ULONG) Input. Name of unit to open. (Currently unused) ═══ VSD_OPEN_PARMS Parameter - szInstallName[MAX_DEVICE_NAME] ═══ szInstallName[MAX_DEVICE_NAME] (CHAR) Input. Installation name of the MCD. This field contains information that can be optionally ignored. (Unused) ═══ VSD_OPEN_PARMS Parameter - szPDDName[MAX_DEVICE_NAME] ═══ szPDDName[MAX_DEVICE_NAME] (CHAR) Input. Name of PDD to open. This field contains information that can be optionally ignored. ═══ VSD_OPEN_PARMS Parameter - hvsd ═══ hvsd (HVSD) Output. Handle to the VSD driver. ═══ VSD_OPEN_PARMS Parameter - pfEvent ═══ pfEvent (PFN) Output. (Unused) ═══ VSD_OPEN_PARMS Parameter - pDevInfo ═══ pDevInfo (PVOID) Input/Output. Device-specific or media-specific information. For audio, it points to VSD_AUDIOOPEN_PARMS ═══ VSD_OPEN_PARMS Parameter - ulDDStream ═══ ulDDStream (ULONG) Input. Device driver stream identifier. (Unused) ═══ 17.75. VSD_RESOURCE_PARMS ═══ This structure contains fields for the VSD_RESOURCE command. typedef struct _VSD_RESOURCE_PARMS { ULONG ulLength; /* Length of the structure. */ CHAR szPDDName[MAX_DEVICE_NAME]; /* Input. Device driver name. */ ULONG ulDevType; /* Input. Device type to open. */ ULONG ulDataType; /* Input. Data type to open. */ ULONG ulResUnits; /* Output. Resouce units. */ ULONG ulClass; /* Output. Resource class. */ } VSD_RESOURCE_PARMS; typedef VSD_RESOURCE_PARMS *PVSD_RESOURCE_PARMS; ═══ VSD_RESOURCE_PARMS Parameter - ulLength ═══ ulLength (ULONG) Length of the structure. ═══ VSD_RESOURCE_PARMS Parameter - szPDDName[MAX_DEVICE_NAME] ═══ szPDDName[MAX_DEVICE_NAME] (CHAR) Input. Name of device driver to open. ═══ VSD_RESOURCE_PARMS Parameter - ulDevType ═══ ulDevType (ULONG) Input. Device type to open. ═══ VSD_RESOURCE_PARMS Parameter - ulDataType ═══ ulDataType (ULONG) Input. Data type to open. ═══ VSD_RESOURCE_PARMS Parameter - ulResUnits ═══ ulResUnits (ULONG) Output. Resouce units consumed for requested mode. ═══ VSD_RESOURCE_PARMS Parameter - ulClass ═══ ulClass (ULONG) Output. Resource class for requested mode (where mode is PCM, MIDI, etc.). ═══ 17.76. VSD_VOLUME_PARMS ═══ This structure contains fields for the VSD_QUERYVOLUME and the VSD_SETVOLUME commands. typedef struct _VSD_VOLUME_PARMS { ULONG ulLength; /* Length of structure. */ ULONG ulFlags; /* Volume item to operate on. */ ULONG ulRequest; /* Unused. */ ULONG ulVectoredVol; /* Input. Time for volume change to take place. */ ULONG ulMasterAudio; /* Input. Master audio setting. */ ULONG ulVolume; /* Input/Output. Volume for connector. */ ULONG hConn; /* Handle to connector. (Unused) */ BOOL fMute; /* Input/Output. Muted or not muted. */ } VSD_VOLUME_PARMS; typedef VSD_VOLUME_PARMS *PVSD_VOLUME_PARMS; ═══ VSD_VOLUME_PARMS Parameter - ulLength ═══ ulLength (ULONG) Length of structure. ═══ VSD_VOLUME_PARMS Parameter - ulFlags ═══ ulFlags (ULONG) Input. Volume item to operate on. The following flags (subcommands) are defined for this command: VSD_VOLUME Instance volume. VSD_MASTERVOLUME System-wide volume setting. VSD_MUTE Flag indicating mute setting. ═══ VSD_VOLUME_PARMS Parameter - ulRequest ═══ ulRequest (ULONG) Unused. ═══ VSD_VOLUME_PARMS Parameter - ulVectoredVol ═══ ulVectoredVol (ULONG) Input. Time for volume change to take place. ═══ VSD_VOLUME_PARMS Parameter - ulMasterAudio ═══ ulMasterAudio (ULONG) Input. Master audio setting. ═══ VSD_VOLUME_PARMS Parameter - ulVolume ═══ ulVolume (ULONG) Input/Output. Volume for connector. ═══ VSD_VOLUME_PARMS Parameter - hConn ═══ hConn (ULONG) Handle to connector to operate on. (Unused) ═══ VSD_VOLUME_PARMS Parameter - fMute ═══ fMute (BOOL) Input/Output. Indicates if volume should be muted. ═══ 17.77. VOID ═══ A data area of undefined format. #define VOID void ═══ 18. Glossary ═══ ═══ Glossary ═══ Select the starting letter of the glossary term you want to locate. ═══ A ═══ ACPA Audio capture and playback adapter. aliasing In multimedia applications, the phenomenon of generating a false (alias) frequency, along with the correct one, as an artifact of sampling a signal at discrete points. In imaging, it produces a jagged edge, or stair-step effect. In audio, it produces a 'buzz'. amp See amplifier. amplifier A device that delivers an enlarged reproduction of the essential characteristics of the received wave by enabling the wave to control a local source of power. amp-mixer (1) A combination amplifier and mixer that is used to control the characteristics of an audio signal from one or more audio sources. (2) Also referred to as an amplifier-mixer. analog Pertaining to data that consist of continuously variable physical quantities. analog audio (1) Audio in which all information representing sounds is stored or transmitted in a continuous-scale electrical signal, such as line level audio in stereo components. (2) See also digital audio. analog video (1) Video in which all the information representing images is in a continuous-scale electrical signal for both amplitude and time. (2) See also digital video. API See Application Programming Interface. Application Programming Interface (API) A functional interface supplied by the operating system or by a separately orderable licensed program that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program. audio Pertaining to the portion of recorded information that can be heard. ═══ B ═══ buffer A routine or storage used to compensate for a difference in rate of flow of data, or time of occurrence of events, when transferring data from one device to another. ═══ C ═══ command message interface This programming interface is used for sending messages to the media control interface from an application using the mciSendCommand function. Each time a message is sent to the Media Device Manager with the mciSendCommand, flags are set and a pointer to a data structure is passed. The message interface is normally used by application developers wishing to access device-specific features. command string interface This character string interface is used for sending command language statements to the media control interface from an application using the mciSendString. These statements must be converted to the message format understood by the media driver. The Media Device Manager calls the MMPM/2 string parser to interpret the string. The string interface provides a simple English-like command language that enables users to control media control interface devices. Common User Access (CUA) Guidelines for the dialog between a human and a workstation or terminal. This includes the visual display, and keyboard and mouse interfaces and actions. CUA See Common User Access. cue point (1) A discrete location or time position in a media device. (2) A point the system recognizes as a signal to release a blocked application thread. ═══ D ═══ data streaming The uninterrupted transfer of information over an interface in order to achieve high data transfer rates. device capabilities The functionality of a device, including supported component functions. device context The device status and characteristics associated with an opened instance of an media control interface device. device driver A file that contains the code needed to use an attached device. device sharing (1) The ability to share a device among many different applications simultaneously. If a device is opened shareable, the device context will be saved when going from one application to another application. (2) Allowing a device context to be switched between media control interface devices. device-specific format The storage or transmission format used by a device, especially if it is different from an accepted standard. digital audio In multimedia applications, audio data that has been converted to digital form. See also analog audio. direct memory access The transfer of data between memory and input/output units without microprocessor intervention. discard stop In data streaming, requests that the data stream be stopped and the data remaining in the stream buffers be discarded. DLL See dynamic-link library. DMA See direct memory access. doubleword (DWORD) A contiguous sequence of bits or characters that comprises two computer words and is capable of being addressed as a unit. dynamic-link library (DLL) A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously. dynamic linking In the OS/2* operating system, the delayed connection of a program to a routine until load time or run time. ═══ E ═══ event An occurrence of significance to a task; for example, the completion of an asynchronous operation such as I/O. event semaphore (1) Used when one or more threads must wait for a single event to occur. (2) A blocking flag used to signal when an event has occurred. explicit event An event supported by only some handlers, such as a custom event unique to a particular type of data. ═══ F ═══ file format A language construct that specifies the representation, in character form, of data objects in a file. For example, MIDI, M-Motion (MMOT), or AVC. The file format defines how data is stored in the file, and how the data should be interpreted. flush stop In data streaming, requests that the source stream handler be stopped but the target stream handler continue until the last buffer held at the time the stop was requested is consumed by the target stream handler. FOURCC See Four-character code. Four-character code A 32-bit quantity representing a sequence of one to four ASCII alphanumeric characters (padded on the right with blank characters). Four-character codes are unique identifiers that represent the file format and IOProc. ═══ G ═══ graphic push button A push button control with graphic, two-state, and animation capabilities. grouping For media control interface devices, refers to the ability to associate dissimilar devices for a common purpose. Grouping media control interface devices aids resource management by insuring that all devices in a group are kept together. ═══ H ═══ HID Handler identification. HMS (1) Hours-minutes-seconds. (2) A time format for videodisc players. HMSF (1) Hours-minutes-seconds-frames. (2) A time format for videodisc players. ═══ I ═══ IDC Inter-device driver communication mechanism. identifier One or more characters used to identify or name a data element and possibly to indicate certain properties of that data element. (A) In programming languages, a token that names a data object such as a variable, an array, a record, a subprogram, or a function. implicit event An event that all stream handlers always must support, such as end-of stream (EOS) or preroll complete.) input/output control (IOCtl) A system service that provides a way for an application to send device-specific control commands to a device driver. installable I/O procedure A file format handler that provides functions that operate on the media object of a particular data format. These functions include opening, reading, writing, seeking, and closing elements. inter-device driver communication (IDC) A mechanism that enables a physical device driver to communicate with another physical device driver. internal SPCB key The internal key is used to differentiate between multiple Stream Protocol Control Blocks (SPCBs) of the same data stream type. IOCtl Input/output control. ═══ J ═══ journal A chronological record of changes made in a set of data; the record may be used to reconstruct a previous version of the set. ═══ K ═══ kilobyte (KB) 1024 bytes. ═══ L ═══ LIB A collection (or library) of object modules available for static linking with other modules. These modules physically become part of the program's .EXE file. line audio The standard type of audio signal distributed between most components of an audio system. ═══ M ═══ M-ACPA M-Audio Capture and Playback Adapter. master stream handler Controls the behavior of one or more subordinate objects (the slave streams). M-Audio Capture and Playback Adapter (M-ACPA) An adapter card (for use with the IBM PS/2 product line) that provides the ability to record and play back high quality sound. The adapter converts the audio input (analog) signals to a digital format that is compressed and stored for later use. MDM See Media Device Manager. media control interface (MCI) A generalized interface to control multimedia devices. Each device has its own media control interface driver that implements a standard set of media control interface functions. In addition, each media driver can implement functions that are specific to the particular device. media device A processor of audiovisual information or media. Media components can be either internal or external physical devices or defined mechanisms for effecting higher-level function from internal hardware and software subsystems. (An example is a waveform player component that utilizes the DSP (Digital Signal Processor) subsystem and data-streaming services to effect audio-playback functions.) media device capabilities The functionality of a media component, including supported component functions. media device connection A physical or logical link between media component connectors for a particular set of media component instances. media device connector A physical or logical input or output on a media component. Media Device Manager (MDM) A system service that, when two or more applications attempt to control a media device, determines which process gains access. media driver (1) A device driver for a multimedia device. (2) See also device driver. message interface See command message interface. millisecond One thousandth of a second. mix In multimedia applications, the combination of audio or video sources during postproduction. mixer A device that selects, combines, or blends audio or video signals. MMIO See Multimedia Input/Output. MMIO file services System services that enable an application to access and manipulate multimedia data files. MMIO manager The Multimedia Input/Output Manager provides services to find, query, and access multimedia data objects. It also supports the functions of memory allocation and file compaction. The MMIO manager uses IOProcs to direct the input and output associated with reading from and writing to different types of storage systems or file formats. MMPM/2 Multimedia Presentation Manager/2. See OS/2 Multimedia. MMTIME Standard time and media position format supported by the Media Control Interface. This time unit is 1/3000 of a second. multimedia The combining of different elements of media (for example, text, graphics, audio, and still images) for display and control from a personal computer. multimedia data object In an application, an element of a data structure (such as a file, an array, or an operand) that is needed for program execution and that is named or otherwise specified by the allowable character set of the language in which the program is coded. Multimedia File I/O Services System services that provide a generalized interface to manipulate multimedia data. The services support buffered and unbuffered file I/O, standard RIFF files, and installable I/O procedures. Multimedia Input/Output (MMIO) (1) System services that provide a variety of functions for media file access and manipulation. (2) A consistent programming interface where an application, media driver, or stream handler can refer to multimedia files, read and write data to the files, and query the contents of the files, while remaining independent of the underlying file formats or the storage systems that contain the files. OS/2 Multimedia A subsystem service of OS/2 that provides a software platform for multimedia applications. It defines standard interfaces between multimedia devices and OS/2 multimedia applications. multimedia system A system capable of presenting multimedia material in its entirety. mux (1) An abbreviation for multiplexer. (2) See also mixer. ═══ N ═══ National Television Standard Committee (NTSC) A committee that defines the video standard in the United States. NTSC (1) The video standard in the United States, Canada, Mexico, and Japan. (2) 525 lines of resolution at 30 frames per second. (3) See also National Television Standard Committee. ═══ O ═══ overrun Loss of data because a receiving device is unable to accept data at the rate it is transmitted. ═══ P ═══ pause stop In data streaming, a stop that pauses the data stream but does not disturb any data. PDD Physical device driver. physical device driver (PDD) A system interface that handles hardware interrupts and supports a set of input and output functions. preroll The process of preparing a device to begin a playback or recording function with minimal latency. During a multimedia sequence, it might require that two devices be cued (prerolled) to start playing and recording at the same time. proc A custom procedure, called by the particular utility manager, to handle input or output to files of a format different from DOS, MEM, or BND; for example, MMOT (M-Motion) or TIFF. By installing custom procedures, existing applications no longer need to store multiple copies of the same media file for running on various platforms using different file formats. ═══ R ═══ RGB (1) Color coding in which the brightness of the additive primary colors of light, red, green, and blue, are specified as three distinct values of white light. (2) Pertaining to a color display that accepts signals representing red, green, and blue. ═══ S ═══ simple device A media control interface device that does not require a device element. single plane video system (1) Refers to when video and graphics are combined into one buffer. This may appear the same as a dual plane video system, but since all the data is in one buffer, capture and restore operations will obtain both graphics and video components in one operation. (2) See also dual plane video system. SPCB Stream protocol control block. SPI Stream programming interface. split streaming A mechanism provided by the Sync/Stream Manager to create one data stream source with multiple targets. standard multimedia device controls These controls provide the application developer with a CUA compliant interface for controlling audio attributes, video attributes, and videodisc players. These controls simplify the programming task required to create the interface and handle the presentation of the interface and all interaction with the user. They also send the media control interface (MCI) commands to the Media Device Manager (MDM) for processing. stream To send data from one source to another. stream object The data resource or device channel that represents either the data source or target for a stream. stream programming interface (SPI) A system service that supports continual flow of data between physical devices. stream protocol control block (SPCB) The system service that controls the behavior of a specified stream type. This enables you to subclass a stream's data type, change data buffering characteristics, and alter synchronization behavior and other stream events. string commands See command string interface. subclassing The act of intercepting messages and passing them on to their original intended recipient. S-Video input connector A special connector that separates the chrominance from the luminance signal. sync group A master stream and all its slaves that can be started, stopped, and searched as a group by using the slaves flag on each of the following SPI functions: o SpiStartStream o SpiStopStream o SpiSeekStream sync pulse A system service that enables each slave stream handler to adjust the activity of that stream so that synchronization can be maintained. Sync pulses are introduced by transmission equipment into the receiving equipment to keep the two equipments operating in step. synchronization The action of forcing certain points in the execution sequences of two or more asynchronous procedures to coincide in time. synchronous Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals. ═══ T ═══ tearing Refers to when video is displaced horizontally. This may be caused by sync problems. transport device A device that plays, records, and positions a media element, and either presents the result directly or sends the material to a transform device. Examples are videodisc players, CD-ROMs, and digital audio (wave) player. ═══ U ═══ underrun Loss of data caused by inability of a transmitting device or channel to provide data to the communication control logic at a rate that is fast enough for the attached link or loop. ═══ V ═══ videodisc A disc with information stored in the form of pits along a spiral track. The information is decoded by a videodisc player and converted to an analog signal. viewport A predefined part of the display space; a rectangular portion of the screen where the video is displayed. ═══ W ═══ window coordinates The size and location of a window. ═══ X Y Z ═══ Y Refers to the luminance portion of a Y/C video signal. Y/C Color image encoding scheme that separates luminance (Y) from phase encoded chroma (C). Synonymous with S-video. zooming The progressive scaling of an image in order to give the visual impression of movement of all or part of a display group toward or away from an observer.