Table 1-3 shows the services that are part of the Microsoft multimedia programming interface and are not implemented in Multimedia Services for OpenVMS.

Table 1-3 Unimplemented Services and Functions

Category	Unsupported Functions
Auxiliary Audio Services	All
DrawDib Functions	All
Joystick Services	All
Loadable Third-Party Device Support Modules	All
MCI Services	All
MIDI Services	All
Multimedia File I/O Services	Buffered file I/O Custom I/O procedures The following functions: mmioAdvance mmioFlush mmioInstallIOProc mmioSendMessage mmioSetBuffer mmioSetInfo
Timer Services	All
Video Capture and Playback Services	The following functions: videoConfigureStorage videoDialog videoMessage videoUpdate
Video Compression and Decompression Services	Functions relating to the frame buffer drawing operations: ICDraw ICDrawBegin ICDrawEnd ICDrawFlush ICDrawGetTime ICDrawQuery ICDrawRealize ICDrawSetTime ICDrawStart ICDrawStop ICDrawWindow ICGetBuffersWanted ICGetDisplayFormat ICInstall ICQueryAbout ICQueryConfigure ICRemove ICSendMessage Functions for displaying dialog boxes: ICAbout ICConfigure
Waveform Audio Services	The following functions: waveInMessage waveInPrepareHeader waveInUnprepareHeader waveOutGetPitch waveOutGetPlaybackRate waveOutMessage waveOutPrepareHeader waveOutSetPitch waveOutSetPlaybackRate waveOutUnprepareHeader
Audio Compression Manager Services Driver Group	The following functions: acmDriverAdd acmDriverMessage acmDriverPriority acmDriverProc acmDriverRemove
Audio Compression Manager Services Format Group	All
Audio Compression Manager Services Filter Group	All
Audio Compression Manager Services Stream Group	The following function: acmFormatSuggest

1.4 Multimedia Hardware Support

Audio services are provided by the Microsoft Sound Board driver.

Video services are provided by the FullVideo Supreme and FullVideo Supreme JPEG option modules. The FullVideo Supreme JPEG also supports JPEG compression and decompression of video data.

1.5 Application Development Notes

This section describes characteristics of the multimedia software and hardware environments that application programmers need to understand to ensure successful development and execution of multimedia applications using Multimedia Services for OpenVMS.

Be familiar with these characteristics before beginning application development.

1.5.1 Server Process

The server process, MMOV$SERVER , must be running before executing any application program that uses the multimedia API. The server process is located at SYS$SYSTEM:MMOV$SERVER.EXE . Run the server process from the SYSTEM account.

To start the server process, log in to the SYSTEM account and enter the following command:

$ @SYS$STARTUP:MMOV$STARTUP

To stop the server process, enter the following command:

$ @SYS$STARTUP:MMOV$SHUTDOWN

The server may be delayed briefly, possibly up to two seconds, during the setup of a palette (or colormap) associated with the video capture and playback or video compression and decompression interfaces. Because starting video applications typically involves setting palettes, expect all applications to pause when a video application is started.

1.5.2 Multimedia Services Library

The Multimedia Services library, SYS$LIBRARY:MMOV.OLB , is not thread safe or reentrant. Unpredictable results may occur if multiple threads attempt to use the library functions concurrently.

1.5.3 Header Files

The function prototypes, constants, flags, and data structures required to access Multimedia Services for OpenVMS are provided in header files located in the MMOV$INCLUDE directory. Application programs need to include only the mme_api.h header file, as follows:

#include <mme/mme_api.h>

1.5.4 Compiling and Linking Applications

Use the following command procedure as a template to compile applications:

$ if p1 .eqs. "" then inquire p1 "Enter path were common library was built" $ define/nolog mme sys$common:[mmov_includes],'p1',[] $ define/nolog decc$user_include mme,decw$include: $ define/nolog sys decc$user_include $ define/nolog decc$system_include decc$user_include $ cc := "cc/define=(mme_BLD,IPC_VMS,Long_bit=64,DEC)/standard=vaxc" $ set ver $ cc vidplay $ cc common $ cc color_utils $ cc readavi $ cc avieasy

Use the following command procedure as a template to link applications. The following example is used to build the example programs provided with the installation kit.

$ link /sysshr /exe=vidplay.exe - vidplay.obj,- avieasy.obj,- common.obj,- readavi.obj,- color_utils.obj,- 'p1'commonlib.olb/lib,- sys$library:mmov.olb/lib, sys$input:/option sys$share:cma$open_rtl.exe/share sys$share:decw$xlibshr.exe/share sys$share:IPC$SHARE.exe/share

In the previous example, p1 is the path to the directory where the common library is built.

In the SYS$COMMON:[SYSHLP.EXAMPLES.MMOV] examples directory, the subdirectories are:

• [.COMMON]
  Contains the source files to the common modules used by the example programs.
• [.AUDIO]
  Contains the source files to the audio example programs.
• [.VIDEO]
  Contains the source files to the video example programs.
• [.SAMPLE]
  Contains sample video and audio clips.

Each subdirectory contains a command procedure that you can use to build the example programs called BUILD_XXX , where XXX is the name of the subdirectory.

1.5.5 Waveform Audio Device Restrictions

Keep in mind the following information about waveform audio devices:

• The waveform audio devices in the server mix the audio streams from multiple audio clients for output. There may be a device-imposed maximum number of simultaneous connections to waveform audio output devices.
• The waveform audio drivers do not support all 16 bits of the value used for setting the volume. Hence, the volume value returned by the waveOutGetVolume routine does not match the volume value passed to the waveOutSetVolume routine, due to rounding. For this reason, the setvolume example program does not display the same volume value as used to set the volume.

See Appendix B for specific device details.

1.5.6 Video Capture and Playback Restrictions

The following device restrictions apply to video capture and playback:

• A callback function is required in a call to the videoStreamInit function. A callback must be used with the videoStreamInit function to get information about the state of the video capture buffers. The dwFlags field of the VIDEOHDR data structure is not updated dynamically when a buffer is returned to the application.
• The colormap used with the video functions must always be a 256-element RGBQUAD array.
• The desired video format must be set using the videoConfigure function before performing any video capture and playback operations. The videoConfigure function should be called with the dwFlags argument set to VIDEO_CONFIGURE_SET and appropriate BITMAPINFOHEADER data structures.
  The video capture sample applications show how to set up the formats. See the sample programs viddualrecord.c , vidstreamin.c , and vidframein.c in the MMOV$EXAMPLES:[VIDEO] directory.
• The colormap (palette) must be set using the videoConfigure function before performing any video capture or playback operations involving 8-bit BICOMP_DECXIMAGEDIB output.

  Note The videoConfigure function must be called to set up the capture or playback formats before configuring the colormap.

  
  The video capture sample applications show how to set up the palettes and the X Window System colormaps. See the sample programs viddualrecord.c , vidstreamin.c , or vidframein.c in the MMOV$EXAMPLES:[VIDEO] directory.
• Memory buffers or region usage should be minimized to allow maximum use of the device. See Section 1.5.8 and Section 2.1 for more information about memory optimization and allocation.
• Image sizes are restricted for video capture and playback.
• Note that mirroring is a slow operation because it is done in software.
• Response time to some video capture and playback functions might be slow.
• Some FullVideo Supreme and FullVideo Supreme JPEG operations overwrite the incoming data.

See Appendix B for specific device details.

1.5.7 Video Compression and Decompression Restrictions

The following device restrictions apply to video compression and decompression, unless otherwise noted:

• The ICDecompress function requires that you call the ICDecompressBegin function before calling ICDecompress . If you change any of the fields but the biSizeImage field in the BITMAPINFOHEADER data structures that you pass to ICDecompress , you need to call the ICDecompressEnd function followed by ICDecompressBegin to reconfigure the decompression device. Changing only the biSizeImage field allows this field to indicate different size JPEG images, for example, without restarting the decompressor for each image.
  Some video devices may choose to check ICDecompress parameters, detect a change in parameters, and execute the ICDecompressEnd and ICDecompressBegin functions for you. Therefore, ICDecompress may return error codes normally associated with ICDecompressBegin and ICDecompressEnd . Future releases may not have this functionality; therefore, changes in parameters to ICDecompress without calling ICDecompressEnd and ICDecompressBegin may result in an ICERR_BADPARAM error code.
  The ICCompress functions have the same characteristics.
• The ICDecompressBegin function returns an ICERR_ERROR error code if you are decompressing to 8-bit BICOMP_DECXIMAGEDIB format and you have not yet negotiated a palette using the ICDecompressGetPalette function. Palettes are not required for BICOMP_DECYUVDIB or 24-bit BICOMP_DECXIMAGEDIB output formats.
• Memory buffers or region usage should be minimized to allow maximum use of the device. See Section 1.5.8 and Section 2.1 for more information about memory optimization and allocation.
• Image sizes are restricted for compression.
• Note that mirroring is a slow operation because it is done in software.
• Response time to some video compression and decompression functions might be slow.
• Some FullVideo Supreme and FullVideo Supreme JPEG operations overwrite the incoming data.
• The Software JPEG CODEC (Compressor and Decompressor) is always available with Multimedia Services.
• The Software JPEG CODEC only supports scaling during decompression to the 8-bit BICOMP_DECXIMAGEDIB format. Only scaling by 2X is allowed for this data format.
• Mirroring and sharpening are not supported by the Software JPEG CODEC.
• To compress with the Software JPEG Compressor, the input image width must be a multiple of 16, and the input image height must be a multiple of 8.

See Appendix B for specific device details.

Compaq has extended the Microsoft interfaces for video capture and playback, and compression and decompression to provide an optimization for certain classes of hardware devices. Some hardware devices must lock down physical pages of memory to allow direct memory access (DMA) between the hardware device and the host computer.

The standard compression and decompression interfaces do not require the buffers passed for each call to remain the same over time, and thus the lower layers of software and hardware cannot assume what addresses will be passed. In addition, if the application uses sets of buffers for video capture and playback or compression and decompression, the lower layers have no way of knowing (aside from making intelligent guesses) whether these buffers are from contiguous memory regions and thus can be more efficiently managed at the hardware level.

To facilitate this, the functions ICCompressPrepareHeader and ICDecompressPrepareHeader have been added. They, and the videoStreamPrepareHeader function, can now take on different semantics. Instead of passing individual buffers to each of these functions, an application can pass regions of memory that will be used for multiple buffers. For example, if the video streaming interface is being used and the application is using three buffers, then the application would call videoStreamPrepareHeader with a pointer to a memory region three times the size of a single buffer. The memory buffers must be aligned on a system page boundary and each of the three buffer sizes must be padded to a system page size.

When the videoStreamAddBuffer function is called by the application, the pointer would be set to one of the three subbuffers in the region of memory passed to the videoStreamPrepareHeader function and the size would be the size of a single buffer. This allows the hardware device, if applicable, to lock down and manage one region of memory, while allowing the application to maintain the throughput of three buffers. See the sample program vidstreamin.c in the MMOV$EXAMPLES:[VIDEO] directory for an example.

Each region of memory must be used for the same purpose, that is, for the ICDecompress function, one region of memory must be specified for the input data and one region of memory must be specified for the output data.