Order Number: AA-QN8HC-TE

This guide contains information about the Compaq Multimedia Services for OpenVMS. This application programming interface develops applications that use multimedia features for AlphaStations running the OpenVMS Alpha operating system.

Revision/Update Information: This document supercedes the Multimedia Services OpenVMS Alpha Programmer's Guide, Version 2.0.

Operating System: OpenVMS Alpha Version 7.1-2 or OpenVMS Alpha Version 7.2-1 or higher

Software Version: MMS Version 2.2 for OpenVMS Alpha

Compaq Computer Corporation Houston, Texas

© 2000 Compaq Computer Corporation

Compaq, AlphaStation, StorageWorks, VAX, VMS, the Compaq logo, and the DIGITAL logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation.

X Window System is a trademark of The Open Group.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq or authorized sublicensor required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein.

The information in this publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.

The limited warranties for Compaq products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

ZK6626

Contents

Index

This document contains information about using Multimedia Services Version 2.2 for OpenVMS Alpha.

Compaq Multimedia Services for OpenVMS Alpha is Compaq's implementation of the Microsoft multimedia application programming interface (API). The interface is used to develop applications that use multimedia features for AlphaStations running the OpenVMS Alpha operating system.

Intended Audience

This document is intended for multimedia application developers, including Independent Software Vendors (ISVs) and customers writing their own applications. Readers are expected to be familiar with the following:

• OpenVMS Alpha operating system
• C programming language
• Advanced programming concepts and techniques
• Multimedia application development concepts and techniques
• X Window System programming concepts and techniques

Knowledge of multimedia concepts, techniques, and terminology is helpful.

Document Structure

This document contains the following:

Chapter 1 introduces Compaq Multimedia Services for OpenVMS Alpha and describes how it differs from the Microsoft implementation.

Chapter 2 presents the general services for allocating memory, managing callback events, and representing time.

Chapter 3 describes the audio services available to applications.

Chapter 4 explains the video capture and playback services available to applications.

Chapter 5 presents the video compression and decompression services available to applications.

Chapter 6 describes the file I/O services available to applications.

Chapter 7 provides the supported image formats, including the device-independent bitmap (DIB) file format, DIB extensions for JPEG, XIMAGE, and YUV video data, and the X image format.

Chapter 8 provides the supported file formats, which are in the Resource Interchange File Format (RIFF) and include the Waveform Audio (WAVE) file format and the Audio/Video Interleaved (AVI) file format.

Appendix A describes the online sample application programs that are included in the software kit. These programs show how to use the Compaq Multimedia Services for OpenVMS Alpha functions. The appendix also contains a pointer to the installed location of these programs and instructions for building them.

Appendix B describes volume support, specific device details of the FullVideo Supreme and FullVideo Supreme JPEG option modules, and the Software JPEG CODEC.

The Glossary presents terms associated with multimedia that are used in this document.

Related Documents

Developing applications that use Compaq Multimedia Services for OpenVMS Alpha requires programmers to gain knowledge in a variety of areas. One way to acquire this knowledge is to have the following categories of documentation available:

• Compaq Multimedia Services for OpenVMS Alpha documentation
• X Window System documentation
• Multimedia hardware documentation
• OpenVMS Alpha system management documentation
• Technical notes

For additional information about the OpenVMS products and services, access the following World Wide Web address:

http://www.compaq.com

The following sections list the documentation associated with each of these categories.

Multimedia Services for OpenVMS Alpha Documentation

In addition to this guide, the Compaq Multimedia Services for OpenVMS Alpha documentation set includes the following:

• Compaq Multimedia Services for OpenVMS Alpha Run-Time Environment Guide, which contains instructions for using the utilities included in the Compaq Multimedia Services for OpenVMS Alpha run-time-only environment. The run-time-only environment is bundled free with all AlphaStations running the OpenVMS Alpha operating system.
• Compaq Multimedia Services for OpenVMS Alpha Installation Guide, which contains the software installation procedure and information about the prerequisites to installation, such as required hardware and an installation verification procedure (IVP).
• Compaq Multimedia Services for OpenVMS Alpha Release Notes, which are installed during the software installation. The release notes contain information that you may need before developing programs using the Compaq Multimedia Services for OpenVMS Alpha API.
  The release notes are located in the SYS$HELP directory.

X Window System Documentation

Refer to the following document for additional information about X Window System programming concepts and techniques not covered in this guide:

Scheifler, Robert W. and James Gettys. X Window System: The Complete Reference, Third Edition. Digital Press. 1992.

Multimedia Hardware Documentation

Refer to the FullVideo Supreme and FullVideo Supreme JPEG Owner's Guide for additional information about this hardware device.

OpenVMS Alpha System Management Documentation

Refer to the OpenVMS documentation set for information about the OpenVMS Alpha operating system.

Technical Notes

The following technical notes provide further information on the JPEG and MJPG format extensions discussed in Section 7.7:

• Microsoft Multimedia Technical Note JPEG DIB Format, May 26, 1993
• JPEG, ISO/IEC IS 10918-1: 1992 (E)

Support

If errors occur during product installation, the system displays failure messages. For descriptions of error messages, see the OpenVMS Alpha documentation on system messages, recovery procedures, and software installation.

If an error occurs while Compaq Multimedia Services for OpenVMS Alpha is in use and you believe the error is caused by a problem with the product, contact your Compaq support representative.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.compaq.com/

Click Documentation under Quick Links.

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

This document uses the following conventions:

Convention	Description
Multimedia Services for OpenVMS	Refers to the Multimedia Services Version 2.2 for OpenVMS Alpha product.
bold text	Boldface text indicates data structures, data types, arrays, and field names, and user input in interactive examples. New terms also appear in boldface text the first time they are introduced.
italic text	Italic text indicates function arguments and emphasizes important information.
monospaced text	Monospaced type is used in code segments and programming examples, and to indicate function names, chunk names, subchunks, and fields.
literalString	Literal strings that appear in text, examples, and syntax descriptions must be entered exactly as shown (for example, waveInSetVolume ).
n	A lowercase italic n indicates the generic use of a number.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.

This chapter presents an introduction to Multimedia Services for OpenVMS, describes how it differs from the Microsoft multimedia application programming interface (API) specification, and presents application development notes.

1.1 What is Multimedia Services for OpenVMS?

Multimedia Services for OpenVMS is Compaq's standard application programming interface (API) to multimedia functionality on AlphaStations running the OpenVMS operating system. It is a set of software services and tools for developing applications that use multimedia features on these systems.

Currently, Multimedia Services for OpenVMS provides software support for the FullVideo Supreme and FullVideo Supreme JPEG option modules. It also provides support for standard IBM and Microsoft Resource Interchange File Format (RIFF) file I/O, which is independent of any device. See your workstation documentation for the specific audio capabilities of your model. See the FullVideo Supreme and FullVideo Supreme JPEG Owner's Guide for more information about the FullVideo Supreme option modules.

Multimedia Services for OpenVMS is designed to minimize the device-specific code that application designers must include in their multimedia application programs. Multimedia Services for OpenVMS includes low-level device drivers, device-independent run-time services, and the API. The API and file formats are compatible with the multimedia programming interface defined by Microsoft for Windows and Windows NT. This compatibility eases porting of multimedia applications from Windows platforms to Alpha systems by reducing the programmer's learning curve and the coding changes required for a successful port.

Multimedia Services for OpenVMS has a client/server architecture that uses shared memory transport to communicate between the client applications and the server levels controlling the multimedia hardware. The multimedia services include the following:

• Waveform audio recording and playback
  An application uses waveform audio services to manage the recording and playback of waveform audio. The primary waveform audio functions give an application the ability to record audio (encode audio signals and capture digitized audio in buffers) and to play audio (generate output audio waveforms from digitized audio contained in buffers).
  The waveform audio services also include supporting functions that allow an application to query device capabilities and to open, close, and configure devices.
  The waveform audio services provide a device-independent interface to the audio hardware in Alpha systems, including the built-in audio hardware and the Microsoft Sound Board.
  Chapter 3 describes the waveform audio services.
• Video capture and playback
  An application uses the low-level video services for video capture and playback. The video capture services allow an application to capture incoming video signals, either single frames or real-time streams, into memory buffers. For the FullVideo Supreme JPEG option module, selectable capture formats include JPEG, YUV, 8-bit dithered, and 24-bit true color. For the FullVideo Supreme (AV301) option, selectable capture formats include YUV, 8-bit dithered, and 24-bit true color. For all options, video input can be NTSC, PAL, SECAM, SVIDEO 525, and SVIDEO 625 formats.
  The video playback services allow an application to play back digitized video from memory buffers to the FullVideo Supreme and FullVideo Supreme JPEG option module video output. Video output can be NTSC and PAL formats.
  The video capture and playback services also include supporting functions that allow an application to query device capabilities and to open, close, and configure devices.
  Chapter 4 describes the video capture and playback services. Chapter 7 describes the supported video image formats.

• Video compression and decompression
  An application uses video compression and decompression services to compress or decompress video data. These services provide access to multimedia hardware and software support for JPEG compression and decompression and for dithering on the FullVideo Supreme and FullVideo Supreme JPEG option modules.
  The source of video frames for compression and the destination of decompressed video frames can be either buffers in system memory or the video ports on the FullVideo Supreme and FullVideo Supreme JPEG option modules. Support is also provided for software compression and decompression of JPEG formats.
  The video compression and decompression services also include functions for managing devices and for controlling the compression parameters that affect the appearance of compressed video image data.
  Chapter 5 describes the video compression and decompression services. Chapter 7 describes the supported video compression and decompression formats.
• Multimedia file I/O
  An application uses file I/O services in conjunction with the other multimedia functions to create, read, and write disk files that store audio and video data. The files are in RIFF format and include the Waveform Audio (WAVE) file format and the Audio/Video Interleaved (AVI) file format.
  Chapter 6 describes the file I/O services. Chapter 8 describes the supported multimedia file formats.

Figure 1-1 shows how the various components of a Multimedia Services for OpenVMS system work together.

Figure 1-1 Multimedia System Architecture

1.2 Compaq Extensions to the Microsoft Multimedia Programming Interface

Table 1-1 New Multimedia Functions

Category	Extensions
Callback Services	Functions for managing callbacks: mmeCheckForCallbacks mmeProcessCallbacks mmeServerFileDescriptor mmeWaitForCallbacks
Memory Allocation Services	Functions for allocating memory: mmeAllocBuffer mmeAllocBufferAndGetShminfo mmeAllocMem Functions for freeing previously allocated memory: mmeFreeBuffer mmeFreeMem
Video Capture and Playback Services	Functions for modifying the rendering attributes of uncompressed rendered images: videoGetBrightness videoGetContrast videoGetMirror videoGetSaturation videoGetSharpening videoSetBrightness videoSetContrast videoSetMirror videoSetSaturation videoSetSharpening Functions for modifying the quality of video data: videoGetQuality videoSetQuality Functions for retrieving and specifying the hardware port: videoGetPortNum videoSetPortNum Functions for retrieving and specifying the video standard type: videoGetStandard videoSetStandard Video data formats: BICOMP_DECYUVDIB BICOMP_DECXIMAGEDIB Functions for obtaining and setting the video field mode: videoGetFieldMode videoSetFieldMode
Video Capture and Playback Services (Continued)	Function for setting the current LUT controls for YUV data to video output: videoj300SetVideoOutYUVLut
Video Compression and Decompression Services	Functions for modifying the rendering attributes of uncompressed rendered images: ICGetBrightness ICGetContrast ICGetMirror ICGetSaturation ICGetSharpening ICSetBrightness ICSetContrast ICSetMirror ICSetSaturation ICSetSharpening Functions for preparing and unpreparing buffers: ICCompressPrepareHeader ICCompressUnprepareHeader ICDecompressPrepareHeader ICDecompressUnprepareHeader
Callback Services	Function for registering a callback procedure for streaming video compression or decompression: ICCallbackProc
Waveform Audio Services	Functions for retrieving and specifying record volume: waveInGetVolume waveInSetVolume Functions for determining and selecting ports: waveInGetPorts waveInSelectPorts waveOutGetPorts waveOutSelectPorts Functions for querying waveform audio input and output device capabilites: waveInGetDevCapsEx waveOutGetDevCapsEx Functions for querying waveform audio input and output device formats: waveInFormatDetails waveInGetFormatInfo waveOutFormatDetails waveOutGetFormatInfo

Table 1-2 Multimedia Extensions Supplied by Compaq

Category	Functions
Video Capture and Playback Services	Function for opening a video capture device: videoOpen Function for controlling the configuration of a video capture device: videoConfigure Function for controlling video capture streaming: videoStreamAddBuffer videoStreamPrepareHeader Function for operating on a single frame: videoFrame
Video Compression and Decompression Services	Function for obtaining the palette for the output format of a decompressor: ICDecompressGetPalette
Waveform Audio Services	Functions for querying waveform audio input and output devices: waveInGetDevCaps waveOutGetDevCaps Functions for opening waveform audio input and output devices: waveInOpen waveOutOpen