═══ 1. How To Use the Programming Reference ═══ The IBM(TM) ActionMedia(TM) II Programming Reference for MMPM/2(TM) is for application programmers using Multimedia Presentation Manager/2 (MMPM/2) Version 1.00 who want to include digital video function in their OS/2 multimedia applications. This book provides information on the Media Control Interface logical digital video device implemented for ActionMedia II and supplements Media Control Interface information in the MMPM/2 Programming Guide and MMPM/2 Programming Reference. For example, the reference section in this book contains syntax descriptions of new commands (and extensions to existing commands) that comprise the digital video support implemented for both the string and message interfaces. Use the MMPM/2 Programming Reference to review commands that have not changed. Before you begin to use this reference, it is 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 and view the additional topics, select the + if you are using a mouse; if you are using a keyboard, use the Up Arrow and Down Arrow keys to highlight the topic, and then press the plus key (+). To see the complete list of commands, click on the plus sign or highlight that 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. 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 the Enter key. Additional information will appear in a window. How To Use Menu-Bar Choices Choices are available in the menu bar and in the Services menu that help you manage the guide and reference information. Select any of the choices below to learn about these features. Bookmark Sets a place holder so you can retrieve information of interest to you. (This choice is available from the Services menu.) Search Finds occurrences of a word or phrase in the current topic, selected topics, or all topics. (This choice is available from the Services menu.) Print Prints one or more topics. (This choice is available from the Services menu.) Copy Copies a topic you are viewing to a file you can edit. (This choice is available from the Services menu.) Options Changes the way the Contents is displayed. OTHER INFORMATION Notices Trademarks ═══ 2. ActionMedia II Digital Video for MMPM/2 ═══ Application developers who are using the Multimedia Presentation Manager/2(TM) (MMPM/2) programming toolkit are already acquainted with the multimedia device support made available to OS/2 applications with MMPM/2 Version 1.0. The Version 1.0 support is primarily for audio devices. Now, with the ActionMedia(TM) II implementation of the MMPM/2 Media Control Interface, you can add digital video to the list of multimedia devices supported for OS/2 applications. ═══ 2.1. ActionMedia II Logical Digital Video Device ═══ The digitizing and compression of motion video, using the DVI(TM) (Digital Video Interactive) technology, combined with the ActionMedia II implementation of the MMPM/2 Media Control Interface, enables video to be treated like any other MMPM/2 data object. Digital video can be mixed with digital audio and still images and stored on standard peripheral devices, such as CD-ROM drives and hard disks. Digital video has a requirement that hardware devices be able to transfer data directly to and from display memory. OS/2 2.0 also has a requirement that these devices coexist with the OS/2 Presentation Manager (PM) in the graphical user interface environment. These requirements are met by the ActionMedia II multimedia adapters and by the ActionMedia II MMPM/2 media driver. The driver uses the resources of PM-its user interface and windowing and graphical output-and the functions of the Media Control Interface to provide interactive video output to OS/2 applications. The ActionMedia II implementation of the Media Control Interface supports data streaming of motion video from any device that can appear as a logical drive (for example, a hard disk, CD-ROM drive, or network file server). However, streaming of video data to and from system memory is not supported. ═══ 2.2. Audio-Video Subsystem Files ═══ The ActionMedia II MMPM/2 Media Control Interface supports playback and recording of Digital Video Interactive (DVI) Audio-Video Subsystem (AVSS) format motion video, and capture and display of AVSS format images. An AVSS file contains one or more streams of data. Each stream typically has the digital data to describe the playback of a single audio or video stream. In general, there can be several such streams, all of which are intended for playback that is perceived by the user as simultaneous. To reduce head movement on the storage device, the data from the various streams is interleaved. A frame is the unit of interleaving. AVSS format files that are processed by the ActionMedia II digital video device can have the following types of data: o Video and audio o Video only o Audio only o Image, with only one still image in a file Files that have only audio, only video, or both audio and video data are all considered to be video file types. ═══ 2.3. Digital Video Device Contexts ═══ Digital video device contexts can be of type video, still image, uncommitted, or both video and still image. When an existing file is opened, the device context becomes the same type as that of the file, either video or still image. When a new file is opened, the device context is uncommitted and can become either a video or a still type. A device context can also be of both types. For example, a capture command can be issued during playback of motion video, resulting in both a video and still element existing simultaneously in the same device context. Because the ActionMedia II MMPM/2 Media Control Interface supports multiple instances of the digital video device, multiple video and still device contexts can be displayed simultaneously. Only one video device context can be active at a time (that is, playing, recording, or monitoring). If more than one video device context is displayed, the video device context in the window with the input focus is active, while the other video device contexts are paused. Multiple still image device elements can be open simultaneously, and stills can be open at the same time as a video instance that is playing a motion video file or monitoring live video. However, no other still or video device contexts can be open while a recording instance is open. The following table shows the combinations of loaded video and image elements that are allowed at any given time by the ActionMedia II MMPM/2 Media Control Interface. ┌─────────────────────────┬─────────────────────────┐ │Video Element │Image Element │ ├─────────────────────────┼─────────────────────────┤ │0 │5 │ ├─────────────────────────┼─────────────────────────┤ │1 │3 │ ├─────────────────────────┼─────────────────────────┤ │2 │2 │ ├─────────────────────────┼─────────────────────────┤ │3 │1 │ ├─────────────────────────┼─────────────────────────┤ │4 │0 │ ├─────────────────────────┼─────────────────────────┤ │5 │0 │ └─────────────────────────┴─────────────────────────┘ These numbers and combinations are based on the 2MB of video RAM (VRAM) on the ActionMedia II display adapter. ═══ 2.4. Displaying Video Output in a PM Window ═══ The ActionMedia II MMPM/2 driver creates a default window for display when a device context is created with MCI_OPEN. The window is not displayed until an MCI_CUE, MCI_RECORD, MCI_PLAY, MCI_RESTORE, or MCI_SET_MONITOR_ON is issued. The video device directs its output to the default window unless a different window is specified with the MCI_WINDOW message. Some window-style control functions are also exported as flags to the MCI_WINDOW message, primarily for the convenience of applications that are using the string interface. Whether the default window or an application-defined window is used for output, the digital video device confines its output to the device coordinates of the specified window. In addition, the device restricts its output to (and overwriting of) pixels set to the logical transparent color within the coordinates. The transparency color for ActionMedia II is always black. These restrictions allow the PM application to continue to draw graphics or output text into a window, so that the output overlays the video image. The digital video device can stretch the image produced by the ActionMedia II adapter so that the dimensions or extents of the source rectangle that is transferred to the display can be varied. To determine whether a device can vary its extents, an application uses the capability command, as shown in the following example. open dolphins.avs type digitalvideo alias myvideo capability myvideo can stretch wait capability myvideo horizontal video extent wait capability myvideo vertical video extent wait play myvideo wait close myvideo For devices with variable source extents, capability returns the maximum source extents of which the device is capable, and status returns the source extents of the currently loaded element, if applicable. ═══ 2.5. ActionMedia II Multimedia Adapter Specifics ═══ The IBM PS/2 ActionMedia II product consists of two hardware elements-a display adapter, and an optional capture adapter, referred to as the capture option. The capture option is used with the display adapter to capture and digitize video and audio input signals. All connection with the capture option is through the display adapter. There are no user-accessible connectors on the capture option. ═══ 2.5.1. Connector Model ═══ The ActionMedia II MMPM/2 Media Control Interface does not support enabling and disabling of connectors; however, it does support a limited subset of the connector model, including the querying of device connections. Connections allow the MMPM/2 to model the physical connections that exist between the multimedia devices in the system. In general, connectors can be enabled and disabled, which means turning an input or output on or off. However, the ActionMedia II implementation has all connectors permanently enabled. The number of available connectors varies with the number of physical connectors provided by the hardware that are used to implement the digital video player, as well as configuration-specific information, such as composite or S-video connections. The connectors for ActionMedia II hardware are shown in the following table. ┌─────────────────────────┬───────────────┬────────────────────┐ │Connector Type │Name │Description │ ├─────────────────────────┼───────────────┼────────────────────┤ │MCI_VIDEO_IN_CONNECTOR │video in │Video signal input │ ├─────────────────────────┼───────────────┼────────────────────┤ │MCI_VIDEO_OUT_CONNECTOR │video out │Video signal output │ ├─────────────────────────┼───────────────┼────────────────────┤ │MCI_AUDIO_IN_CONNECTOR │audio in │Audio signal input │ ├─────────────────────────┼───────────────┼────────────────────┤ │MCI_AUDIO_OUT_CONNECTOR │audio out │Audio signal output │ └─────────────────────────┴───────────────┴────────────────────┘ ═══ 2.5.2. High and Low Resolution Modes ═══ The ActionMedia II MMPM/2 Media Control Interface provides two resolutions, low and high, to VGA and XGA adapters for displaying motion video and still images, and for monitoring live video. The following table shows the ActionMedia II support for these adapter modes. Note that there is no support for the IBM 8514/A Adapter and Image Adapter/A. ┌────────────────────┬────────────────────┬────────────────────┐ │Display Adapter Type│High Resolution │Low Resolution │ ├────────────────────┼────────────────────┼────────────────────┤ │VGA at 640x480 │512x480 │256x240 │ ├────────────────────┼────────────────────┼────────────────────┤ │XGA at 640x480 │512x480 │256x240 │ ├────────────────────┼────────────────────┼────────────────────┤ │XGA at 1024x768 │410x384 │256x192 │ └────────────────────┴────────────────────┴────────────────────┘ There are three factors that determine whether the device switches the display of a video or still image from high to low resolution: o Size of the image in relation to its default size o Size of the window in relation to the display area o Activation of a device context requiring low resolution The default size of a video or still image is its size when displayed unscaled and uncropped in a high resolution view. This size is also referred to as the natural size. If a video or still image is sized so that it is greater than its default size when displayed at high resolution, the digital video device switches to low resolution. If a video or still is sized even further, so that it is greater than its default size when displayed at low resolution, the display window will be restricted to the maximum size of the window at low resolution. The ActionMedia II MMPM/2 Media Control Interface will scale video to fit in any size window from one pixel square to the entire display area. If either the horizontal or vertical dimension exceeds half the display dimension, then the video will be displayed using the low resolution mode of the ActionMedia II. Otherwise, the high resolution mode will be used. When video is being monitored during recording, the ActionMedia II MMPM/2 Media Control Interface can scale video into a window only when both its dimensions are equal to half or less than half of both dimensions of the display. That is, the window is no larger than a quarter of the screen size. Attempting to display into windows greater than this size will result in the window being resized to the maximum size of the image at low resolution. On an XGA adapter, the breakpoint is 5/8 rather than half the display dimensions. Note: Scaling calculations assume that video is compressed at 256x240. For other resolutions, the calculations are different, and with smaller sizes it is not possible to fill the display. When multiple device contexts are visible on the display, the digital video device selects high resolution only if all the contexts can be displayed at high resolution. If any of the contexts require low resolution, the driver switches all of the contexts to low resolution. These checks are carried out continuously. For example, if there are two contexts, A and B, and A looks best at high resolution but B requires low resolution, then low resolution is selected. If B is closed and A remains open, the driver then switches to high resolution to display A. The current implementation of the ActionMedia II OS/2 device driver Audio-Video Kernel (AVK) requires that video playback be momentarily paused when switching between low and high resolution modes. ═══ 2.5.3. Video Display Mode ═══ The only supported video display mode is 9-bit YUV. YUV refers to a color-image encoding scheme that separates luminance (Y) and two color signals: red minus Y (U), and blue minus Y (V). Transmission of YUV takes advantage of the eye's greater sensitivity to luminance detail rather than color detail. All videos and stills are displayed using this mode. The 16-bit YUV mode is not supported, so 16-bit stills are converted to 9-bit before being displayed. This avoids conflicts when simultaneously displaying 9-bit YUV video and multiple 9-bit and 16-bit stills. ═══ 2.5.4. Motion Video Compression Formats ═══ The ActionMedia II digital video display hardware uses a coprocessor for compression and decompression of a digital image in a video display plane. The compression techniques used for motion video are Real-Time Video and Production Level Video. Real-Time Video (RTV) compression is available on the user's system. Analog video, typically from a VCR or camera, is streamed into the capture card, digitized, and compressed in real time. The data can then be stored on a hard disk. Production Level Video (PLV) compression is produced offline by a DVI technology compression facility. Analog video tape is digitized and compressed, using a sophisticated algorithm on a powerful computer. PLV files can be kept on magnetic tape or transferred to CD-ROM. The ActionMedia II adapter supports both the American and European television broadcast standards for analog video signals. The American standard is National Television Standard Committee (NTSC), and the European standard is Phase Alternation by Line (PAL). For a description of how to configure your system, see the ActionMedia II Device Drivers booklet. The following table lists the compression formats and transfer rates that are supported for motion video playback and recording. Compression formats are supported in the ActionMedia II OS/2 device driver Audio-Video Kernel (AVK). ┌───────────────┬──────────────────┬───────────────────────────┐ │Operation │Compression Type │Transfer Rates │ ├───────────────┼──────────────────┼───────────────────────────┤ │Playback │RTV 1.0, 1.5, 2.0,│NTSC 256x240 pixels at │ │ │PLV 1.0, 1.5, 2.0 │ │ │ │ │PAL 256x240 pixels at │ ├───────────────┼──────────────────┼───────────────────────────┤ │Recording │RTV 2.0 and 2.1 │NTSC 128x240 at 30 FPS │ │ │ │ 256x240 DVI pixels│ │ │ │ │ │ │ │PAL 128x240 at 25 FPS │ │ │ │ 256x240 DVI pixels│ └───────────────┴──────────────────┴───────────────────────────┘ Playback of motion video is supported into a PM desktop window but not to an external NTSC or PAL monitor. When PAL video is recorded, it is taken from a cropped view of 153x288 DVI pixels, so part of the source image is lost. ═══ 2.5.5. Audio Compression Formats ═══ Pulse Code Modulation (PCM) and Adaptive Differential Pulse Code Modulation (ADPCM) are techniques used for sampling digital audio. Generally, the higher the sampling rate and resolution, the higher the perceived quality. The ActionMedia II device supports three different sampling rates for ADPCM4 and PCM8 resolutions. These rates are selectable as quality settings. ┌────────────────────┬────────────────────────────────────────┐ │Format │Sampling Rates │ ├────────────────────┼────────────────────────────────────────┤ │ADPCM4 │33.075kHz, 11.129kHz, and 8.268kHz │ ├────────────────────┼────────────────────────────────────────┤ │PCM8 │44.100kHz, 22.050kHz, and 11.025kHz │ └────────────────────┴────────────────────────────────────────┘ Mono audio playback is supported. The signal is sent to both left and right speakers. ═══ 2.5.6. Image Compression Formats ═══ The following table lists the compression formats supported for image capture and display. There is some support for display of older AVK formats to provide compatibility with previous media. ┌─────────────────────────┬─────────────────────────┐ │Display Formats │Capture Formats │ ├─────────────────────────┼─────────────────────────┤ │PIC 1.0 9-bit and 16-bit │PIC 1.0 9-bit │ │JPEG 1.0 9-bit │JPEG 1.0 9-bit │ └─────────────────────────┴─────────────────────────┘ ═══ 2.6. Quality Settings for Video, Audio, and Image ═══ By specifying a preset quality level of low, medium, or high for audio, video, or still images with the set command, you can adjust the compression algorithm parameters currently in effect. For example, you can set the quality level for ADPCM audio to low, as shown below. open marlins.avs type digitalvideo alias myvideo set myvideo audio compression ADPCM4 wait set myvideo audio quality low wait play myvideo wait close myvideo The low setting ensures the best compression (lowest data size and rate) possible and sacrifices the quality of the audio, video, or still image. The high setting ensures the best quality possible for audio, video, and still images, at the expense of a high data rate. The medium setting is the nominal CD-ROM data rate (150KB per second), with mostly intra-coded frames for video. The medium setting is the default. ═══ 2.6.1. Video Quality Levels ═══ The following table lists the quality levels for video, which are obtained by varying the parameters of the RTV compression algorithm. ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Quality Level │Still Period │Prefilter │Still and Rel. │ │ │ │ │Quantization │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │HIGH │16 │No │0 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │MEDIUM │64 │Yes │2 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │LOW │128 │Yes │3 │ └───────────────┴───────────────┴───────────────┴───────────────┘ In successive frames of motion video, very little of the image changes from one frame to the next. To avoid storage of all this redundant data, the AVK compresses the data by saving only the changes from one frame to the next using intraframe and interframe encoding. A frame that is compressed by being encoded entirely within itself is called an intracoded-frame (I-frame) or still image. The still period algorithm parameter specifies the minimum rate at which digitized images are compressed using intraframe encoding. For example, if the still period is set to 1, every frame is an I-frame. In the table the still period value of 16 indicates that every sixteenth frame of compressed motion video is an I-frame. Frames in between the I-frames are compressed using interframe encoding. Each of these frames are stored as a set of differences in relation to a previous frame. The prefilter parameter performs some noise reduction at the cost of blurring the original images. Specifying this parameter causes approximately a 2:1 reduction in the amount of compressed data generated per image. Still and relative quantization specify the level of quantization to use for intraframe and interframe encoded images, respectively. A value of zero means minimum quantization, which provides the best quality. Generally speaking, parameter values less than 3 produce acceptable images. Larger values can be used when there is a lot of motion that conceals the blockiness or contouring of the image that occurs. For more information on ActionMedia II video algorithm characteristics, see the ActionMedia II Technical Reference. ═══ 2.6.2. Audio Quality Levels ═══ The following table lists the audio quality levels for ADPCM4 and PCM8, which are obtained by varying the sampling rates of the digital audio data. ┌────────────────────┬────────────────────┬────────────────────┐ │Quality Level │ADPCM4 Format │PCM8 Format │ ├────────────────────┼────────────────────┼────────────────────┤ │HIGH │33075 4-bit SPS │44100 8-bit SPS │ ├────────────────────┼────────────────────┼────────────────────┤ │MEDIUM │11129 4-bit SPS │22050 8-bit SPS │ ├────────────────────┼────────────────────┼────────────────────┤ │LOW │8268 4-bit SPS │11025 8-bit SPS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 2.6.3. Data Rates for Video and Audio Quality ═══ The following table lists the approximate data rates for video and audio quality levels. Use these data rates to determine what the best quality level is for your machine configuration. ┌────────────────────┬────────────────────────────────────────┐ │Quality Level │Data Rate in Bytes Per Second (BPS) │ ├────────────────────┼────────────────────────────────────────┤ │HIGH │350 000 BPS │ ├────────────────────┼────────────────────────────────────────┤ │MEDIUM │135 000 BPS │ ├────────────────────┼────────────────────────────────────────┤ │LOW │110 000 BPS │ └────────────────────┴────────────────────────────────────────┘ ═══ 2.6.4. Image Quality Levels ═══ PIC 1.0 9-bit YUV images are captured at 512x480 DVI pixels. The quality of image capture is varied by varying the algorithm and quantization values. The following table shows the filtering and quantization values that are set for quality levels when capturing these images. ┌────────────────────┬────────────────────┬────────────────────┐ │Quality Level │Filtering │Quantization │ ├────────────────────┼────────────────────┼────────────────────┤ │HIGH │10 │0 │ ├────────────────────┼────────────────────┼────────────────────┤ │MEDIUM │15 │5 │ ├────────────────────┼────────────────────┼────────────────────┤ │LOW │20 │8 │ └────────────────────┴────────────────────┴────────────────────┘ JPEG 1.0 9-bit YUV images are captured at 512x480 DVI pixels. The quality of image capture is varied by varying the values in the quantization table used by the AVK compression API. These values are multiplied by the constants shown in the following table to achieve the high, medium and low quality levels. If you are interested in more information about the AVK API, see the ActionMedia II Technical Reference. ┌────────────────────┬────────────────────────────────────────┐ │Quality Level │Constant │ ├────────────────────┼────────────────────────────────────────┤ │HIGH │0.5 │ ├────────────────────┼────────────────────────────────────────┤ │MEDIUM │1.0 │ ├────────────────────┼────────────────────────────────────────┤ │LOW │1.5 │ └────────────────────┴────────────────────────────────────────┘ ═══ 3. Using the ActionMedia II Digital Video Device ═══ The MMPM/2 digital video device implemented for ActionMedia II provides support to OS/2 Presentation Manager applications for: o Playing motion video o Recording motion video o Capturing still images from live and recorded video o Displaying still images o Monitoring the incoming video signal o Displaying video and images in a default window or application window This chapter describes ActionMedia II digital video functions and provides examples using Media Control Interface string commands. For more information about the Media Control Interface string command syntax, see the MMPM/2 Programming Guide. ═══ 3.1. Playing Motion Video Files ═══ By default, playback of digital motion video is displayed in a window supplied by the ActionMedia II digital video device. The default window is created when the device is opened, but the window is not made visible until a cue, play, record, set monitor on, or restore command is issued. The example shown below illustrates playing an entire motion video AVSS format file. Because to and from parameters are not specified, the file is played from the current position to the end of the file. When a motion video device element is opened, the current position in the media is the first playable area after any header or table of contents information. open seaworld.avs type digitalvideo alias myvideo wait play myvideo wait close myvideo Each frame in a motion video file has a number associated with it. From the perspective of the digital video device, each file is zero-based. That is, the first frame is frame 0, the second frame is frame 1, and so on. This means the number of the last frame in a file is 1 less than the total number of frames in the file. The current position always indicates the frame that is about to be displayed, rather than the frame that is currently displayed. When a play position in motion video is specified with the from parameter of the play command, the actual position reached is accurate only to the nearest intracoded frame (I-frame). However, a position specified with the to parameter is exact. If you need to specify an exact position in the video file to play from, you can issue the seek command, which moves the current position in a file to an exact point. The following example illustrates moving the current position to frame 100 and then playing to frame 2000. open seaworld.avs type digitalvideo alias myvideo set myvideo time format frames wait seek myvideo to 100 wait play myvideo to 2000 wait close myvideo ═══ 3.2. Recording Motion Video ═══ The ActionMedia II MMPM/2 digital video device supports recording of motion video into AVSS-format motion video files. The supported compression algorithms for recording video are RTV 2.0 and 2.1, with RTV 2.1 being the default setting for video compression. The associated sound track can be recorded in the PCM8 or ADPCM4 format. ADPCM4 is the default for audio compression. Video input types are PAL and NTSC. Recording into new and existing files is supported. The following example illustrates recording live video. As recording takes place, the digital audio and video data is stored in the temporary file created for the video device element. After the recording operation is complete, the device element is played back so it can be viewed before it is saved as a permanent file on disk. To save the data as a video file, you can specify an existing file name or a new file name with the save command. If you indicate an existing file name, the data in the disk file will be completely replaced by the data in the temporary file. You can also indicate that the file being saved is a video file; however, it is not necessary because this is the default. In the example, monitoring is set on, so that the incoming video signal can be viewed in the default video window before it is recorded. Monitoring of live video can also be done without recording. open digitalvideo alias myvideo wait set myvideo video quality low wait set myvideo audio quality low wait set myvideo time format frames wait set myvideo monitor on wait record myvideo to 99 wait play myvideo wait save myvideo newvid.avs video wait close myvideo In the following example low quality levels are specified for audio and video, which means that audio and video quality will be sacrificed for low data rates. The initial settings for audio, video, and image quality are the medium quality levels, which are the nominal CD-ROM rates. Applications can specify that only video or only audio is to be recorded. In the following example video recording is turned off, so that only audio will be recorded. open digitalvideo alias myaudio wait set myaudio video record off wait set myaudio audio compression pcm8 wait set myaudio audio quality high wait set myaudio time format hms wait cue myaudio input wait record myaudio to 00:10:00 wait play myaudio wait save myaudio newaud.avs wait close myaudio In the following example the audio quality for recording PCM8 digital audio is set to high. This means that the best quality audio will be produced, at the expense of a high data rate. Specifying the cue input command causes the default window to become visible, so it is not necessary to set the monitoring function on. As in the previous example, the device element is played back before it is saved as a file on disk. ═══ 3.3. Displaying Image Files ═══ The ActionMedia II MMPM/2 digital video device supports display of DVI AVSS-format still image files. In the following example, issuing the restore command causes the MANATEE.AVS data object to be transferred from the device element temporary buffer to the display surface. open manatee.avs type digitalvideo alias myimage wait restore myimage wait close myimage Because the ActionMedia II MMPM/2 driver supports multiple device contexts, multiple still image device elements can be open simultaneously. As shown in the example below, up to five stills can be displayed at one time. open manatee.avs type digitalvideo alias image1 shareable wait open dolphin.avs type digitalvideo alias image2 shareable wait open whale.avs type digitalvideo alias image3 shareable wait open snapper.avs type digitalvideo alias image4 shareable wait open catfish.avs type digitalvideo alias image5 shareable wait restore image1 wait restore image2 wait restore image3 wait restore image4 wait restore image5 wait close image1 close image2 close image3 close image4 close image5 ═══ 3.4. Capturing Images ═══ The ActionMedia II driver captures DVI AVSS-format still files from live video and from replayed digital video files. For a still to be captured, monitoring of an incoming video signal must be set to on, or playback of a DVI AVSS-format file must be in progress. The example shown below illustrates capturing a still image from live video. Monitoring is set on so that the live video can be viewed in the default video window. The capture command stores the current image as a device element in a temporary file. The restore command enables the device element to be viewed before it is saved as a permanent image file with the save command. To save the device element as an image file, you must specify the image parameter. Note that the capture temporary file is located in the subdirectory specified by the multimedia work path. This path can be set using the Multimedia Setup program. open digitalvideo alias vid shareable set vid monitor on wait capture vid wait restore vid wait save vid birds.avs image wait close vid The following example demonstrates capturing a still from a motion video file as follows: 1. The first still is captured as a device element and then displayed. 2. The motion video file is repositioned to the beginning and played again so another capture can be made. 3. The second capture overwrites the first capture in the temporary buffer provided for the device element. 4. The device element is saved in a file. Capturing a Still from a Video File open motion.avs type digitalvideo alias myvideo wait set myvideo image compression jpeg9_10 wait play myvideo notify capture myvideo wait restore myvideo wait rewind myvideo wait play myvideo notify capture myvideo wait restore myvideo wait save myvideo image mystill.avs wait close myvideo Note in the above example that the image compression format is set to jpeg9_10. The initial setting for image compression is pic9_10. ═══ 3.5. Digital Video PM Windows ═══ The ActionMedia II MMPM/2 Media Control Interface supports two types of window: default and application-defined. The default window is used if no other window handle is specified. It provides a basic top-level desktop window in which to display video and images that can be moved, sized, and iconized by the user. When the window is iconized, the icon is simply a scaled-down version of the video that continues to be updated at the video frame rate. Assuming the source DVI video is 256x240, the default size of the default window is 320x240 VGA pixels on a VGA display, and 640x480 XGA pixels on an XGA display. The position of the default window is determined by the Presentation Manager shell. The default window has a default size option on the system menu pull-down. Selection of this option causes the window to be resized so that the image or video in the client area is displayed at its default size in a high-resolution view. ═══ 3.5.1. Application-Defined Window ═══ An application-defined window can be used when the application requires more control over the window. The application has the freedom to place video in its own client area or in a child window, to add menus, and so on. If the parent of the application-defined window is not the PM desktop, its parent window handle must be supplied with the MCI_OPEN request. Color keying of the PM video window is on black. This has the implication that when displaying overlay graphics in a video window, an application cannot use black as a graphics color. If an application specifies a parent window handle when opening the device, it must close the logical video device before destroying the parent window. Otherwise, video can continue to be keyed into an area where the child window once was. ═══ 3.5.2. Application Window Subclassing ═══ When an application-defined window is used for video or stills display, the driver subclasses the window to ensure that video updating is maintained correctly. Subclassing the window has the following effects: o Positions and sizes the window so that its boundaries are coincident with DVI pixel boundaries. o Ensures that the window cannot be sized above the maximum size of the displayed video or image. o Modifies the tracking rectangle so that the user cannot drag the size border beyond the maximum size of the displayed video image. Subclassing is also used to inform the AVK when other windows overlap so that any areas that are painted in the transparency color can be repainted. The transparency color indicates the area of the video window where video is to show through the VGA or XGA image from the DVI plane behind it. Because the ActionMedia II transparency color is black, video could show through any portion of a window that is painted black which overlaps the video window. Therefore, the AVK must repaint these areas of the DVI plane in black to prevent the video from showing through. ═══ 4. Media Control Interface String Commands ═══ Following are the digital video string commands supported by the ActionMedia II MMPM/2 media driver for the string interface of the Media Control Interface. An application thread that calls the ActionMedia II media driver using mciSendString must create a PM message queue before calling the driver. Command Description CAPABILITY item Requests additional information about the capabilities of the digital video driver. The item is one of the following: can eject Returns FALSE. The device cannot eject media. can lockeject Returns FALSE. The device cannot disable manual eject. can play Returns TRUE. The device can play. can reverse Returns FALSE. The device cannot play in reverse. can record Returns TRUE if the ActionMedia II capture option is installed. Returns FALSE if the ActionMedia II capture option is not installed, or if the capture option is not configured. For configuration information, refer to the ActionMedia II Device Drivers booklet. can insert Returns FALSE. The device cannot insert recorded data into an existing file. can save Returns TRUE. The device can save data. can stretch Returns TRUE. The device can stretch frames to fill the display rectangle. can distort Returns TRUE. The device can independently stretch the horizontal and vertical dimensions of the image. overlay graphics Returns TRUE. The device supports the display by an application of overlay graphics in the video window. The application cannot use the color black as a graphics color, because this is the color key color that causes video to show through on the DVI plane. compound device Returns TRUE. The device requires an element name. device type Returns Digitalvideo. normal play rate Returns the normal play rate for the device in frames per second (fps). The normal play rate for the ActionMedia II device is 30 fps when configured for NTSC and 25 fps when configured for PAL. fast play rate Returns the normal play rate. The ActionMedia II device cannot play fast. slow play rate Returns the normal play rate. The ActionMedia II device cannot play slowly. maximum play rate Returns the normal play rate. minimum play rate Returns the normal play rate. has audio Returns TRUE. The device supports audio playback. has video Returns TRUE. The device supports video playback. has image Returns TRUE. The device supports still image functions. horizontal video extent Returns the horizontal (X) source extent for the video source. vertical video extent Returns the vertical (Y) source extent for the video source. horizontal image extent Returns the horizontal (X) source extent for images. vertical image extent Returns the vertical (Y) source extent for images. uses files Returns TRUE. The device element is a file path name. windows Returns 5 as the maximum number of windows the device can support. can setvolume Returns TRUE. The device supports software control of volume level. preroll type Returns deterministic as the preroll type. preroll time Returns 0, indicating the preroll time is not bounded. message item Returns TRUE if the device supports the message specified by item. CAPTURE Captures the current video image. The current video image is the video image created while monitoring live video or playing a video file. A capture operation does not cause the image or bit map to be saved; the application must subsequently issue save to save the device element. The image device element is placed in a temporary file. Repeated capture operations will overwrite the image contained in the temporary file. Note that the temporary file is located in the subdirectory specified by the multimedia work path. This path can be set using the Multimedia Setup program. CLOSE Closes the device element and any resources associated with it. CONNECTOR items Queries the status of connectors on a device. The following items modify the basic command: Indicates the operation to perform on the specified connector. Possible values are: query Queries the status of the indicated connector. The returned value of TRUE or FALSE indicates enabled or disabled respectively. Use of this option requires that the number and/or type options also be specified. number Indicates the connector number on which to perform the requested action. If the type item is included, then the connector number is interpreted as a relative offset within the specified connector type; otherwise, it is interpreted as an absolute index number. If omitted, an index of 1 is assumed. type Indicates the type of connector to which the requested action applies. The connector types are defined in the MMPM/2 Programming Guide. CUE item Prepares for playback or recording. The CUE command does not have to be issued before playback or recording. However, for the ActionMedia II interface it reduces the delay associated with the PLAY or RECORD command. If play is in progress and cue output is issued, the command is ignored. Similarly, if record is in progress and cue input is issued, the command is ignored. The item is one of the following: input Prepares for recording. output Prepares for playback. INFO item Fills a user-supplied buffer with information. This command can be used to determine whether the file just loaded is an image or a video file by comparing the returned file name with the loaded file name. The item is one of the following: image file Returns the file name of the currently loaded image file. video file Returns the file name of the currently loaded digital video file. product Returns the product name and model of the current digital video device. window text Returns the caption of the display window. LOAD item Loads a new device element (or file name) into an already open device context. filename File name to load. By convention, the file name has an extension of AVS. OPEN items Initializes the device. The following optional items modify open: alias device_alias An alternate name for the device. If specified, it must also be used for subsequent references. parent hwnd The window handle of the parent window. shareable Initializes the device as shareable. Specifying shareable makes the resources of the device available to other device contexts. If shareable is not specified on open, the resource will be exclusively acquired when the device is opened. type device_type The compound device used to control a device element. As an alternative to type, the Media Control Interface can use the file extensions associated with the file to select the controlling device. PAUSE Pauses playing. PLAY items Starts a play operation on the device. The following optional items modify play: from pos to pos The frame at which to start or stop playing. The position to start playing from is accurate only to the nearest intracoded frame (I-frame). The position to play to is exact. If from is omitted, play starts at the current position; if to is omitted, play continues to the end frame. If you want to start play from an exact position, use the seek command to move to the position and then play from the current position. RECORD items Starts recording digital motion video into a temporary file. Subsequent record commands overwrite the data in the file. The temporary file is located in the subdirectory specified by the multimedia work path. This path can be set using the Multimedia Setup program. Recording is supported into new and existing files. A new or existing file name must be specified with the save command. If an existing file name is specified, the save command completely replaces the data in the file on disk with the data in the temporary file. This command is supported only if capability can record returns TRUE. The following optional item modifies RECORD: to pos The position to stop recording. The device starts recording at the current position; if to is omitted, the device records until a stop, pause, or any other state-changing command is received. RESTORE Restores the still image from the currently loaded image. RESUME Resumes playing or recording from a paused state, keeping previously specified play or record parameters in effect. REWIND Rewinds or seeks the device element to the first playable position (beginning). SAVE item Saves the captured or recorded data for the device. The device transfers the image or video in the device element to a file. The save command causes a transition to the stopped state. The following items modify save: filename The destination path and file name of a new or existing file. If an existing file name is specified, the save command completely replaces the data in the file on disk with the data in the temporary file. By convention, the file name has an extension of .AVS. If path is not specified, the file will be located in the current subdirectory. video The motion video device element is to be saved. (Default) image The still image device element is to be saved. If neither video nor image is specified, the recorded data will be saved as a video file. SEEK item Moves to the specified position in the file. The ActionMedia II driver supports seeking for playback only. The function is not supported in the record paused state. to pos The final position for the seek. to start Seek to the start of the file. to end Seek to the end of the file. This puts the device in a stopped state. SET items The various control and attribute items: audio items The audio attributes of the device context specified by items. on Enables audio output. (Default) all Applies to both or all the channels. (Default) left Applies to the left channel. right Applies to the right channel. off Disables audio output. all Applies to both or all the channels. (Default) left Applies to the left channel. right Applies to the right channel. volume percentage Sets the volume level. all Applies to both or all the channels. (Default) left Applies to the left channel. right Applies to the right channel. record Applies to audio input. Enables only video to be recorded. on Enables audio input. (Default) off Disables audio input. monitor state Sets monitoring as specified by state. Monitoring will display the incoming video signal when you are not playing a video file, recording a file, or restoring an image. Once monitoring is set to on, audio and video settings are static and cannot be modified until monitoring is set to off. on Enables monitoring. off Disables monitoring. (Default) time format type The time format type to be used in subsequent commands. frames Sets time format to frames. All position information is specified in frames following this command. milliseconds Sets time format to milliseconds. The word "milliseconds" can be abbreviated to ms. All position information is specified in this format following this command. hms Sets time format to Hours:Minutes:Seconds. All position information is specified in this format following this command. mmtime Sets time format to MMTIME. (Default) audio compression type The compression type used for recording the associated soundtrack for motion video. adpcm4 4-bit Adaptive Differential Pulse Code Modulation. (Default) pcm8 8-bit Pulse Code Modulation. video compression type The compression type used for recording motion video. rtv20 Real-time Video 2.0. rtv21 Real-time Video 2.1. (Default) image compression type The compression type used for saving still images. pic9_10 PIC 9-bit still image 1.0. (Default) jpeg9_10 Joint Photographic Experts Group 9-bit still image 1.0. video items The video attributes of the device context specified by items. on Enables video output. (Default) off Disables video output. record Applies to video input. If set to off, only audio is recorded. on Enables video input. (Default) off Disables video input. audio quality level The specified audio quality level. low minimal data size/rate medium nominal CD-ROM data rate. (Default) high best audio quality video quality level The specified motion video quality level. low minimal data size/rate medium nominal CD-ROM data rate. (Default) high best video image quality image quality level The specified still image quality level. high maximize image quality medium compromise between image quality and compression. (Default) low maximize compression SETCUEPOINT items Sets a cue point. on Enables the given cue point. off Disables the given cue point. at position The cue point location in the currently set device units. return value A value to be returned on the cue point message. STATUS item Obtains status information for the device. One of the following items modifies STATUS: audio compression Returns the current compression type for recording the audio sound track. video compression Returns the current compression type for recording motion video. image compression Returns the current compression type for saving still images. audio quality Returns the current quality level for recording audio. video quality Returns the current quality level for recording motion video. image quality Returns the current quality level for saving still images. forward Returns TRUE. The play direction is forward. length Returns the length in the current time format. mode Returns paused, playing, recording, seeking, or stopped for the current mode. monitor Returns on if monitoring is set on; otherwise, returns off. position Returns the current position in the current time format. ready Returns TRUE if the digital video device is ready. speed format Returns fps as the current speed format of the device. start Returns zero as the start position. time format Returns the time format. volume Returns the current volume setting. The volume is returned as a string in the format left:right where left and right are percentages of the maximum achievable effect for the left and right channels respectively. Leading zeros are suppressed for the volume level in each channel. window handle Returns as a string the handle of the window used for digital video. horizontal video extent Returns the horizontal (X) extent of the currently loaded motion video. vertical video extent Returns the vertical (Y) extent of the currently loaded motion video. horizontal image extent Returns the horizontal (X) extent of the currently loaded image. vertical image extent Returns the vertical (Y) extent of the currently loaded image. STEP Steps one frame forward and displays the frame. If the ActionMedia II device is in a play-paused state when the step is issued, the next frame is displayed. If the ActionMedia II device is in a stopped state when the step is issued, the position is updated, but the frame is not displayed. STOP Stops playing or recording. WINDOW item Tells the digital video driver to use a given window to display video instead of the default window created by the driver. The driver subclasses the window to ensure that video update is maintained correctly. By default, the driver creates a window when opened but does not display it until the driver receives the CUE, SET monitor on, PLAY, RECORD, or RESTORE command. Applications providing window handles should manage the display issues that result when the window is sized. Several flags manipulate the window. Since the STATUS command can obtain the handle to the current display window, you can use the standard window functions instead. The following items modify WINDOW: handle window_handle The handle of the destination window used as an alternate to the default window. handle default This flag can be used to set the display back to the driver's default window. state hide Hides the current display window. state maximize Maximizes the current display window. This indicator has no effect if the window is in a maximized state, and is also mutually exclusive with MINIMIZE and RESTORE. state minimize Minimizes the window. This indicator has no effect if the window is in a minimized state, and is also mutually exclusive with MAXIMIZE and RESTORE. state show Shows the current display window. state restore Restores the current display window. This indicator has no effect if currently in a window and is mutually exclusive with MAXIMIZE and MINIMIZE. state activate Activates the window if it is a frame window. This has no other effect on other windows. The frame window is made the topmost window. state deactivate Deactivates the window if it is a frame window. This has no effect on other windows. The frame window is made the bottommost window. text caption The caption for the default window. The text flag will not modify the caption for the user-defined window; the application must do this through a Presentation Manager window command. ═══ 5. Media Control Interface Messages ═══ Applications control devices in the multimedia environment by sending command messages using the Media Control Interface function mciSendCommand. An application thread that calls the ActionMedia II media driver must create a PM message queue before calling the device. All command messages (except system messages) perform asynchronously without notification unless either MCI_NOTIFY or MCI_WAIT is specified in the first parameter of the message. These two flags are mutually exclusive; if both are used, the error MCIERR_FLAGS_NOT_COMPATIBLE is returned. If MCI_NOTIFY is used, control is returned immediately to the caller and then the command is completed. If MCI_WAIT is used, control is not returned to the caller until the command is completed. A notification is sent to the application if MCIERR_SUCCESS was returned on the call. The second parameter specified for a command message is a pointer to a control block structure associated with that message, which is to be put in the dwParam2 field of mciSendCommand. Following is a list of all the command messages supported by the ActionMedia II digital video device. Following the table are detailed syntax descriptions of the new and changed messages that comprise the ActionMedia II digital video support. For descriptions of other Media Control Interface commands used by the digital video device that are not changed by the ActionMedia II implementation, see the MMPM/2 Programming Reference. ┌──────────────────┬──────────────────────────────────────────┐ │Command │Description │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_CAPTURE │Captures the current video image and │ │ │stores it in a temporary buffer. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_CLOSE │Closes the current device context. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_CONNECTOR │Queries the status of a connector. Note │ │ │that connectors for the ActionMedia II │ │ │digital video device are permanently │ │ │enabled. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_CUE │Readies a device so that playback or │ │ │recording can begin with minimum delay. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_GETDEVCAPS │Returns information about a device's │ │ │capabilities. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_INFO │Returns names of files loaded for the │ │ │current device context. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_LOAD │Loads an AVSS file for the current device │ │ │context. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_OPEN │Opens a device context. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_PAUSE │Pauses recording or playback. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_PLAY │Signals the device to begin playing. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_RECORD │Signals the device to begin recording. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_RESTORE │Transfers an image device element from a │ │ │temporary buffer to the display surface. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_RESUME │Resumes a recording or playback operation.│ ├──────────────────┼──────────────────────────────────────────┤ │MCI_REWIND │Changes the position in the media to the │ │ │first playable position. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_SAVE │Saves the currently loaded device element │ │ │in a file with the specified file name. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_SEEK │Moves to a new position in the media. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_SET │Sets device information. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_SET_CUEPOINT │Sets a cuepoint on or off. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_STATUS │Queries information about the device │ │ │status. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_STEP │Steps the playback of the video device │ │ │element forward by one frame. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_STOP │Stops the playing or recording operation. │ ├──────────────────┼──────────────────────────────────────────┤ │MCI_WINDOW │Specifies an application window in which │ │ │to display digital video output. │ └──────────────────┴──────────────────────────────────────────┘ ═══ 5.1. MCI_CAPTURE ═══ ═══ Topics - MCI_CAPTURE ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_CAPTURE ═══ This message causes the ActionMedia II device to capture the current video image and store it in the image device element. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_CAPTURE_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_CAPTURE ═══ The captured image is retained as a still image device element of the digital video device. The format of the captured image is specified by the currently set image compression type. Repeated capture operations overwrite the image in the device element buffer. If the application wants to transfer the image data to a permanent file, it must issue MCI_SAVE. ═══ Default Processing - MCI_CAPTURE ═══ None. ═══ Parameters - MCI_CAPTURE ═══ dwParam1 (DWORD) This parameter can contain the following standard flags, which can be used with any type of device: MCI_NOTIFY Posts a notification message to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Does not return control until the action indicated by this message is completed. dwParam2 (LPMCI_CAPTURE_PARMS) A pointer to an MCI_CAPTURE_PARMS data structure. ═══ Return Values - MCI_CAPTURE ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS Capture operation succeeded. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INVALID_MODE Must be monitoring or playing to do a capture. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_UNSUPPORTED_FUNCTION No capture card installed or configured. MCIERR_MISSING_FLAG Missing item flag if neither ITEM nor MESSAGE flags given. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is not correct. ═══ dwParam1 ═══ dwParam1 (DWORD) This parameter can contain the following standard flags, which can be used with any type of device: MCI_NOTIFY Posts a notification message to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Does not return control until the action indicated by this message is completed. ═══ dwParam2 ═══ dwParam2 (LPMCI_CAPTURE_PARMS) A pointer to an MCI_CAPTURE_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS Capture operation succeeded. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INVALID_MODE Must be monitoring or playing to do a capture. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_UNSUPPORTED_FUNCTION No capture card installed or configured. MCIERR_MISSING_FLAG Missing item flag if neither ITEM nor MESSAGE flags given. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is not correct. ═══ Example Code - MCI_CAPTURE ═══ The following code illustrates capturing an image with MCI_CAPTURE. WORD wDeviceID; HWND hwndMyWindow; MCI_CAPTURE_PARMS mciCaptureParms; /* generic message parms structure */ /* Capture a still image */ /* Assign dwCallback the handle to the PM Window routine */ mciCaptureParms.dwCallback = (DWORD) hwndMyWindow; mciSendCommand( wDeviceID, /* Device ID */ MCI_CAPTURE, /* MCI capture message */ MCI_NOTIFY, /* Flag for this message */ (DWORD) mciCaptureParms, /* Data structure */ 0); ═══ 5.2. MCI_GETDEVCAPS ═══ ═══ Topics - MCI_GETDEVCAPS ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_GETDEVCAPS ═══ This message returns static information about the ActionMedia II digital video device. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_GETDEVCAPS_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_GETDEVCAPS ═══ The MCI_GETDEVCAPS_ITEM and MCI_GETDEVCAPS_MESSAGE flags are mutually exclusive. Only a single item or message can be specified with the mciSendCommand function. ═══ Default Processing - MCI_GETDEVCAPS ═══ None. ═══ Parameters - MCI_GETDEVCAPS ═══ dwParam1 (DWORD) Following are standard flags that can be used regardless of the type of device: MCI_NOTIFY Posts a notification message to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Does not return control until the action indicated by this message is completed. MCI_GETDEVCAPS_MESSAGE The wMessage field of the data structure identified by dwParam2 contains a constant specifying the message to be queried. If the device supports the message, MCI_TRUE is returned; otherwise, MCI_FALSE is returned. Note: The string parser converts unrecognized strings into a message ID value of 0. This message value is defined as not being supported by any driver. Other messages are converted to their corresponding message ID value. MCI_GETDEVCAPS_ITEM The dwItem field of the data structure identified by dwParam2 contains a constant specifying the device capabilities to be queried. Following are item values that can be used for the dwItem field of the data structure pointed to by dwParam2. Values returned by the ActionMedia II digital are indicated. MCI_GETDEVCAPS_CAN_EJECT Returns MCI_FALSE. The device cannot eject media. MCI_GETDEVCAPS_CAN_LOCKEJECT. REturns MCI_FALSE. The device cannot disable manual eject. MCI_GETDEVCAPS_CAN_PLAY Returns MCI_TRUE. The device can play media. The device supports MCI_PLAY, MCI_PAUSE, MCI_RESUME, and MCI_STOP. MCI_GETDEVCAPS_CAN_RECORD Returns MCI_TRUE if the ActionMedia II capture option is installed and configured. Otherwise, returns MCI_FALSE. For configuration information, see the ActionMedia II Device Drivers booklet. MCI_GETDEVCAPS_CAN_RECORD_INSERT Returns MCI_FALSE. MCI_GETDEVCAPS_CAN_REVERSE Returns MCI_FALSE. The device cannot play in reverse. MCI_GETDEVCAPS_CAN_SAVE Returns MCI_TRUE. The device can save files; the MCI_SAVE command must be issued to save changes in the media element. MCI_GETDEVCAPS_DEVICE_TYPE Returns the device type constant for digital video. MCI_GETDEVCAPS_HAS_AUDIO Returns MCI_TRUE. The device is capable of playing audio. MCI_GETDEVCAPS_HAS_VIDEO Returns MCI_TRUE. The device is capable of playing video. MCI_GETDEVCAPS_USES_FILES Returns MCI_TRUE. The compound device requires a file name. MCI_GETDEVCAPS_CAN_STREAM Returns MCI_FALSE. MCI_GETDEVCAPS_CAN_SETVOLUME Returns MCI_TRUE. The device can set the audio volume level. MCI_GETDEVCAPS_PREROLL_TYPE Returns MCI_PREROLL_DETERMINISTIC. MCI_GETDEVCAPS_PREROLL_TIME The ActionMedia II device returns a value of zero for the maximum notified preroll time, which indicates that an upper boundary to the preroll time is not known. Digital Video Extensions The following additional items apply to digital video devices. Values returned by the ActionMedia II digital video device are indicated. MCI_DGV_GETDEVCAPS_HAS_IMAGE Returns MCI_TRUE. The device supports still images in its device context. MCI_DGV_GETDEVCAPS_OVERLAY_GRAPHICS Returns MCI_TRUE. The device supports the display by an application of overlay graphics in the video window. The application cannot use the color black as a graphics color, because this is the color key color that causes video to show through on the DVI plane. MCI_DGV_GETDEVCAPS_CAN_REVERSE Returns MCI_FALSE. The device cannot play in reverse. MCI_DGV_GETDEVCAPS_CAN_STRETCH Returns MCI_TRUE. The device can stretch the image to fill the frame. MCI_DGV_GETDEVCAPS_CAN_DISTORT Returns MCI_TRUE. The device can stretch the image independently in horizontal and vertical dimensions. MCI_DGV_GETDEVCAPS_FAST_RATE Returns the normal play rate. The ActionMedia II device cannot play fast. MCI_DGV_GETDEVCAPS_SLOW_RATE Returns the normal play rate. The ActionMedia II device cannot play slowly. MCI_DGV_GETDEVCAPS_NORMAL_RATE Returns the normal play rate for the device in frames-per-second. The normal play rate for the ActionMedia device is 30 fps when configured for NTSC and 25 fps when configured for PAL. MCI_DGV_GETDEVCAPS_MAXIMUM_RATE Returns the normal play rate. MCI_DGV_GETDEVCAPS_MINIMUM_RATE Returns the normal play rate. MCI_DGV_GETDEVCAPS_VIDEO_X_EXTENT Returns the nominal horizontal (X) extent of the digital motion video image. MCI_DGV_GETDEVCAPS_VIDEO_Y_EXTENT Returns the nominal vertical (Y) extent of the digital motion video image. MCI_DGV_GETDEVCAPS_IMAGE_X_EXTENT Returns the nominal horizontal (X) extent of images, if applicable. MCI_DGV_GETDEVCAPS_IMAGE_Y_EXTENT Returns the nominal vertical (Y) extent of images, if applicable. MCI_DGV_GETDEVCAPS_MAX_WINDOWS Returns the maximum number of windows that the device can handle simultaneously. dwParam2 (LPMCI_GETDEVCAPS_PARMS) A pointer to the MCI_GETDEVCAPS_PARMS data structure. ═══ Return Values - MCI_GETDEVCAPS ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_ITEM_FLAG Invalid getdevcaps item flag given. MCIERR_MISSING_ITEM Missing getdevcaps item flag. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ dwParam1 ═══ dwParam1 (DWORD) Following are standard flags that can be used regardless of the type of device: MCI_NOTIFY Posts a notification message to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Does not return control until the action indicated by this message is completed. MCI_GETDEVCAPS_MESSAGE The wMessage field of the data structure identified by dwParam2 contains a constant specifying the message to be queried. If the device supports the message, MCI_TRUE is returned; otherwise, MCI_FALSE is returned. Note: The string parser converts unrecognized strings into a message ID value of 0. This message value is defined as not being supported by any driver. Other messages are converted to their corresponding message ID value. MCI_GETDEVCAPS_ITEM The dwItem field of the data structure identified by dwParam2 contains a constant specifying the device capabilities to be queried. Following are item values that can be used for the dwItem field of the data structure pointed to by dwParam2. Values returned by the ActionMedia II digital are indicated. MCI_GETDEVCAPS_CAN_EJECT Returns MCI_FALSE. The device cannot eject media. MCI_GETDEVCAPS_CAN_LOCKEJECT. REturns MCI_FALSE. The device cannot disable manual eject. MCI_GETDEVCAPS_CAN_PLAY Returns MCI_TRUE. The device can play media. The device supports MCI_PLAY, MCI_PAUSE, MCI_RESUME, and MCI_STOP. MCI_GETDEVCAPS_CAN_RECORD Returns MCI_TRUE if the ActionMedia II capture option is installed and configured. Otherwise, returns MCI_FALSE. For configuration information, see the ActionMedia II Device Drivers booklet. MCI_GETDEVCAPS_CAN_RECORD_INSERT Returns MCI_FALSE. MCI_GETDEVCAPS_CAN_REVERSE Returns MCI_FALSE. The device cannot play in reverse. MCI_GETDEVCAPS_CAN_SAVE Returns MCI_TRUE. The device can save files; the MCI_SAVE command must be issued to save changes in the media element. MCI_GETDEVCAPS_DEVICE_TYPE Returns the device type constant for digital video. MCI_GETDEVCAPS_HAS_AUDIO Returns MCI_TRUE. The device is capable of playing audio. MCI_GETDEVCAPS_HAS_VIDEO Returns MCI_TRUE. The device is capable of playing video. MCI_GETDEVCAPS_USES_FILES Returns MCI_TRUE. The compound device requires a file name. MCI_GETDEVCAPS_CAN_STREAM Returns MCI_FALSE. MCI_GETDEVCAPS_CAN_SETVOLUME Returns MCI_TRUE. The device can set the audio volume level. MCI_GETDEVCAPS_PREROLL_TYPE Returns MCI_PREROLL_DETERMINISTIC. MCI_GETDEVCAPS_PREROLL_TIME The ActionMedia II device returns a value of zero for the maximum notified preroll time, which indicates that an upper boundary to the preroll time is not known. Digital Video Extensions The following additional items apply to digital video devices. Values returned by the ActionMedia II digital video device are indicated. MCI_DGV_GETDEVCAPS_HAS_IMAGE Returns MCI_TRUE. The device supports still images in its device context. MCI_DGV_GETDEVCAPS_OVERLAY_GRAPHICS Returns MCI_TRUE. The device supports the display by an application of overlay graphics in the video window. The application cannot use the color black as a graphics color, because this is the color key color that causes video to show through on the DVI plane. MCI_DGV_GETDEVCAPS_CAN_REVERSE Returns MCI_FALSE. The device cannot play in reverse. MCI_DGV_GETDEVCAPS_CAN_STRETCH Returns MCI_TRUE. The device can stretch the image to fill the frame. MCI_DGV_GETDEVCAPS_CAN_DISTORT Returns MCI_TRUE. The device can stretch the image independently in horizontal and vertical dimensions. MCI_DGV_GETDEVCAPS_FAST_RATE Returns the normal play rate. The ActionMedia II device cannot play fast. MCI_DGV_GETDEVCAPS_SLOW_RATE Returns the normal play rate. The ActionMedia II device cannot play slowly. MCI_DGV_GETDEVCAPS_NORMAL_RATE Returns the normal play rate for the device in frames-per-second. The normal play rate for the ActionMedia device is 30 fps when configured for NTSC and 25 fps when configured for PAL. MCI_DGV_GETDEVCAPS_MAXIMUM_RATE Returns the normal play rate. MCI_DGV_GETDEVCAPS_MINIMUM_RATE Returns the normal play rate. MCI_DGV_GETDEVCAPS_VIDEO_X_EXTENT Returns the nominal horizontal (X) extent of the digital motion video image. MCI_DGV_GETDEVCAPS_VIDEO_Y_EXTENT Returns the nominal vertical (Y) extent of the digital motion video image. MCI_DGV_GETDEVCAPS_IMAGE_X_EXTENT Returns the nominal horizontal (X) extent of images, if applicable. MCI_DGV_GETDEVCAPS_IMAGE_Y_EXTENT Returns the nominal vertical (Y) extent of images, if applicable. MCI_DGV_GETDEVCAPS_MAX_WINDOWS Returns the maximum number of windows that the device can handle simultaneously. ═══ dwParam2 ═══ dwParam2 (LPMCI_GETDEVCAPS_PARMS) A pointer to the MCI_GETDEVCAPS_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_ITEM_FLAG Invalid getdevcaps item flag given. MCIERR_MISSING_ITEM Missing getdevcaps item flag. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ Example Code - MCI_GETDEVCAPS ═══ The following code illustrates how to determine if a device has audio capability. WORD wDeviceID; DWORD rc; BOOL fHas_audio; /* Set to TRUE by this example if device has audio */ MCI_GETDEVCAPS_PARMS mgdcp; /* Determine if device has audio capability */ mgdcp.dwItem = MCI_GETDEVCAPS_HAS_AUDIO; rc = mciSendCommand(wDeviceID, /* Device ID */ MCI_GETDEVCAPS, /* Get device capability message */ MCI_WAIT | MCI_GETDEVCAPS_ITEM, /* Flags for this message */ (DWORD) mgdcp, /* Data structure */ 0); /* No user parm */ if (rc == MCIERR_SUCCESS) { fHas_audio = (BOOL) mgdcp.dwReturn; /* Return if device has audio */ } ═══ 5.3. MCI_INFO ═══ ═══ Topics - MCI_INFO ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_INFO ═══ This message returns string information from a media device. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_INFO_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_INFO ═══ This command can be used to determine whether the file just loaded is a video or an image file by setting the MCI_INFO_VIDEO_FILE or MCI_INFO_IMAGE_FILE flag, and then comparing the file name returned with the loaded file name. If the size of the specified buffer is too small to hold all the data, the dwRetSize field contains the required buffer size and the error code MCIERR_INVALID_BUFFER is returned. The buffer contains as much of the INFO data as its size permits. Only one flag can be used per MCI_INFO message. If more than one flag is specified, the error MCIERR_FLAGS_NOT_COMPATIBLE is returned. If no flags are specified, the error MCIERR_MISSING_FLAG is returned. ═══ Default Processing - MCI_INFO ═══ None. ═══ Parameters - MCI_INFO ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_INFO_PRODUCT Returns a description of the particular hardware associated with a device. Digital Video Extensions The following additional flags apply to digital video devices: MCI_INFO_VIDEO_FILE Returns the file name of the current motion video file used by the device. MCI_INFO_IMAGE_FILE Returns the file name of the current image file used by the device. MCI_DGV_INFO_TEXT Returns the caption of the window in which the digital video is currently displayed. dwParam2 (LPMCI_INFO_PARMS) A pointer to the MCI_INFO_PARMS data structure. ═══ Return Values - MCI_INFO ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_BUFFER Invalid return buffer given. MCIERR_FILE_NOT_FOUND Information requested for MCI_INFO_VIDEO_FILE or MCI_INFO_IMAGE_FILE does not exist. MCIERR_MISSING_FLAG No flag specified. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ dwParam1 ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_INFO_PRODUCT Returns a description of the particular hardware associated with a device. Digital Video Extensions The following additional flags apply to digital video devices: MCI_INFO_VIDEO_FILE Returns the file name of the current motion video file used by the device. MCI_INFO_IMAGE_FILE Returns the file name of the current image file used by the device. MCI_DGV_INFO_TEXT Returns the caption of the window in which the digital video is currently displayed. ═══ dwParam2 ═══ dwParam2 (LPMCI_INFO_PARMS) A pointer to the MCI_INFO_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_BUFFER Invalid return buffer given. MCIERR_FILE_NOT_FOUND Information requested for MCI_INFO_VIDEO_FILE or MCI_INFO_IMAGE_FILE does not exist. MCIERR_MISSING_FLAG No flag specified. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ Example Code - MCI_INFO ═══ The following code illustrates returning string information from a media device. #define RETBUFSIZE 128 WORD wDeviceID; CHAR InfoRet [RETBUFSIZE ]; /* Return string buffer */ MCI_INFO_PARMS infoparms; /* Get the file name of the currently loaded image file */ infoparms.lpstrReturn = (LPSTR) InfoRet; /* Pointer to return buffer */ infoparms.dwRetSize = RETBUFSIZE; /* Return buffer size */ mciSendCommand( wDeviceID, /* Device ID */ MCI_INFO, /* MCI info message */ MCI_WAIT | MCI_INFO_IMAGE_FILE, /* Flags for this message */ (DWORD) infoparms, /* Data structure */ 0); /* No user parm */ /* infoparms.lpstrReturn now contains name of current image file */ ═══ 5.4. MCI_OPEN ═══ ═══ Topics - MCI_OPEN ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_OPEN ═══ This message is sent to create a new device context. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_DGV_OPEN_PARMS dwParam2 returns DWORD dwRC ═══ Notes - MCI_OPEN ═══ If motion video is to be displayed in an application window specified with the MCI_WINDOW command, a parent window handle must be supplied with the MCI_OPEN request. Otherwise, the ActionMedia II digital video device opens the default video window, whose parent is the PM desktop. The window will not be visible until a cue, play, record, or monitoring operation begins. ═══ Default Processing - MCI_OPEN ═══ If MCI_OPEN_SHAREABLE is not specified, the device will be opened for exclusive use. If MCI_OPEN_TYPE_ID is not specified and lpstrDeviceName in dwParam2 is not NULL, then the system attempts to open the device specified by the lpstrDeviceName string. If lpstrDeviceName is NULL and the MCI_OPEN_ELEMENT flag is specified, the system attempts to select and open a device based on the element extension. If lpstrDeviceName is a device type ID with a null ordinal or a string device name with no ordinals, then the default device of the specified type is opened. The default device may be selected using the Multimedia Setup application. ═══ Parameters - MCI_OPEN ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_OPEN_SHAREABLE The device is opened as shareable, enabling other applications to share the device if necessary. Omitting this flag causes the device to be opened for exclusive use. MCI_OPEN_ELEMENT An element name is included. The element name can be a file name. The element name will be in the lpstrElementName field. If a nonexistent element name is specified, a temporary element is created for subsequent use with MCI_RECORD. The temporary file can be made permanent by providing a name using the MCI_SAVE message. MCI_OPEN_ALIAS An alias is included in the lpstrAlias field. MCI_OPEN_TYPE_ID The lpstrDeviceType field of the next parameter is to be interpreted as follows: The low-order word is a standard device type, and the high-order word is the ordinal index for the device. If MCI_OPEN_TYPE_ID is not specified and lpstrDeviceName in dwParam2 is not NULL, then the system attempts to open the device specified by the lpstrDeviceName string. If MCI_OPEN_TYPE_ID is not specified and lpstrDeviceName is NULL and MCI_OPEN_ELEMENT is specified, the system attempts to select and open a device based on the element extension. Digital Video Extensions The following additional flag applies to digital video devices: MCI_DGV_OPEN_PARENT Indicates the parent window handle is specified in the hwndParent field of the data structure identified by lpOpen. If not specified, HWND_DESKTOP is assumed to be the parent. dwParam2 (LPMCI_DGV_OPEN_PARMS) A pointer to the MCI_DGV_OPEN_PARMS data structure. ═══ Return Values - MCI_OPEN ═══ dwRC (DWORD) Return codes indicating success or type of failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_CANNOT_ADD_ALIAS Alias cannot be added. MCIERR_DUPLICATE_ALIAS Alias already exists. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback or parent handle is invalid. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_CONNECTION Connection requested is not correct. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FILE_NOT_FOUND Given file could not be found. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_DEVICE_OPEN Device is already open and is not shareable. MCIERR_CANNOT_LOAD_DRIVER Driver could not be loaded. MCIERR_DEVICE_LOCKED Device is acquired for exclusive use. MCIERR_OUT_OF_MEMORY Out of memory. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_RESOURCE_NOT_AVAILABLE Required resource not available. ═══ dwParam1 ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_OPEN_SHAREABLE The device is opened as shareable, enabling other applications to share the device if necessary. Omitting this flag causes the device to be opened for exclusive use. MCI_OPEN_ELEMENT An element name is included. The element name can be a file name. The element name will be in the lpstrElementName field. If a nonexistent element name is specified, a temporary element is created for subsequent use with MCI_RECORD. The temporary file can be made permanent by providing a name using the MCI_SAVE message. MCI_OPEN_ALIAS An alias is included in the lpstrAlias field. MCI_OPEN_TYPE_ID The lpstrDeviceType field of the next parameter is to be interpreted as follows: The low-order word is a standard device type, and the high-order word is the ordinal index for the device. If MCI_OPEN_TYPE_ID is not specified and lpstrDeviceName in dwParam2 is not NULL, then the system attempts to open the device specified by the lpstrDeviceName string. If MCI_OPEN_TYPE_ID is not specified and lpstrDeviceName is NULL and MCI_OPEN_ELEMENT is specified, the system attempts to select and open a device based on the element extension. Digital Video Extensions The following additional flag applies to digital video devices: MCI_DGV_OPEN_PARENT Indicates the parent window handle is specified in the hwndParent field of the data structure identified by lpOpen. If not specified, HWND_DESKTOP is assumed to be the parent. ═══ dwParam2 ═══ dwParam2 (LPMCI_DGV_OPEN_PARMS) A pointer to the MCI_DGV_OPEN_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_CANNOT_ADD_ALIAS Alias cannot be added. MCIERR_DUPLICATE_ALIAS Alias already exists. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback or parent handle is invalid. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_CONNECTION Connection requested is not correct. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FILE_NOT_FOUND Given file could not be found. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_DEVICE_OPEN Device is already open and is not shareable. MCIERR_CANNOT_LOAD_DRIVER Driver could not be loaded. MCIERR_DEVICE_LOCKED Device is acquired for exclusive use. MCIERR_OUT_OF_MEMORY Out of memory. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_RESOURCE_NOT_AVAILABLE Required resource not available. ═══ Example Code - MCI_OPEN ═══ The following code illustrates opening a digital video device context and specifying the device element PLAY.AVS. DWORD rc; MCI_DGV_OPEN_PARMS mop; mop.dwCallback = (DWORD) NULL; /* N/A - we're waiting */ mop.wDeviceID = (WORD) NULL; /* This is returned */ mop.lpstrDeviceType = (LPSTR) "digitalvideo"; /* Using default device type */ mop.lpstrElementName = (LPSTR) "play.avs"; /* File name to open */ rc = mciSendCommand( 0, /* Don't know device yet */ MCI_OPEN, /* MCI open message */ MCI_WAIT | MCI_OPEN_ELEMENT | MCI_OPEN_SHAREABLE,/* Flags for this message */ (DWORD) mop, /* Data structure */ 0); /* No user parm */ if (rc == MCI_SUCCESS) { wDeviceID = mop.wDeviceID; /* Return device ID */ } ═══ 5.5. MCI_RESTORE ═══ ═══ Topics - MCI_RESTORE ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_RESTORE ═══ This message transfers the image currently in the image device element to the display surface. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_RESTORE_PARMS dwParam2 returns DWORD dwRC ═══ Notes - MCI_RESTORE ═══ The image is restored from the still image device element of the digital video device. This message can be used to view an image that has just been captured with the MCI_CAPTURE command or has been loaded from an image file stored on a logical drive. This function fails if there is no image device element currently loaded. ═══ Default Processing - MCI_RESTORE ═══ None. ═══ Parameters - MCI_RESTORE ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. dwParam2 (LPMCI_RESTORE_PARMS) A pointer to an MCI_RESTORE_PARMS data structure. ═══ Return Values - MCI_RESTORE ═══ dwRC (DWORD) MCIERR_SUCCESS If the function succeeds. MCI_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_FILE_NOT_FOUND No image yet captured or loaded. MCIERR_INVALID_FLAG Flag is invalid. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ dwParam1 ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. ═══ dwParam2 ═══ dwParam2 (LPMCI_RESTORE_PARMS) A pointer to an MCI_RESTORE_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) MCIERR_SUCCESS If the function succeeds. MCI_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_FILE_NOT_FOUND No image yet captured or loaded. MCIERR_INVALID_FLAG Flag is invalid. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ Example Code - MCI_RESTORE ═══ The following code illustrates the use of MCI_RESTORE. WORD wDeviceID; HWND hwndMyWindow; MCI_RESTORE_PARMS mciRestore Parms; /* Generic message parms structure */ /* Display a still image using the default window. */ /* Assign dwCallback the handle to the PM Window routine. */ mciRestoreParms.dwCallback = (DWORD) hwndMyWindow; mciSendCommand( wDeviceID, /* Device ID */ MCI_RESTORE, /* MCI restore message */ MCI_NOTIFY, /* Flag for this message */ (DWORD) mciRestoreParms, /* Data structure */ 0); /* No user parm */ ═══ 5.6. MCI_REWIND ═══ ═══ Topics - MCI_REWIND ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_REWIND ═══ This message changes the position in the media to the beginning point. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_GENERIC_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_REWIND ═══ The beginning point in the media is defined as the first playable area, beyond any header or table-of-contents data. This message is equivalent to MCI_SEEK with the MCI_TO_START flag specified. ═══ Default Processing - MCI_REWIND ═══ None. ═══ Parameters - MCI_REWIND ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. dwParam2 (LPMCI_GENERIC_PARMS) A pointer to a default parameter data structure. ═══ Return Values - MCI_REWIND ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is not correct. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_FILE_NOT_FOUND File has not been loaded. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ dwParam1 ═══ dwParam1 (DWORD) The following standard flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. ═══ dwParam2 ═══ dwParam2 (LPMCI_GENERIC_PARMS) A pointer to a default parameter data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is not correct. MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_FILE_NOT_FOUND File has not been loaded. MCIERR_MISSING_PARAMETER Required parameter is missing. ═══ Example Code - MCI_REWIND ═══ The following code illustrates MCI_REWIND. WORD wDeviceID; HWND hwndMyWindow; MCI_GENERIC_PARMS mciGenericParms; /* Generic message parms structure */ /* Rewind; seek the media to the beginning point */ /* Assign dwCallback the handle to the PM Window routine */ mciGenericParms.dwCallback = (DWORD) hwndMyWindow; mciSendCommand( wDeviceID, /* Device ID */ MCI_REWIND, /* MCI rewind message */ MCI_NOTIFY, /* Flag for this message */ (DWORD) mciGenericParms, /* Data structure */ 0); /* No user parm */ ═══ 5.7. MCI_SAVE ═══ ═══ Topics - MCI_SAVE ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_SAVE ═══ This message saves the current image or recorded motion video device element in a file. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_SAVE_PARMS dwParam2 returns DWORD dwRC ═══ Notes - MCI_SAVE ═══ To perform a save operation, you can specify the name of a new or existing file to which the save can be made. If you specify an existing file, the data in the device element completely replaces the data in the existing file. You should also specify whether video or image data is being saved. If you do not specify MCI_DGV_SAVE_VIDEO_FILE or MCI_DGV_SAVE_IMAGE_FILE, the device element is saved as a video file. If the MCI_SAVE_FILE flag is specified, the device element is saved in the file name specified in lpFileName. ═══ Default Processing - MCI_SAVE ═══ None. ═══ Parameters - MCI_SAVE ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_SAVE_FILE The lpFilename field of the data structure identified by dwParam2 contains a pointer to a buffer containing the destination file name. If a file name is not specified, the original file opened or the most recently loaded file name is assumed. Digital Video Extensions The following additional flags apply to digital video drivers: MCI_DGV_SAVE_VIDEO_FILE Saves the motion video device element. MCI_DGV_SAVE_IMAGE_FILE Saves the still image device element. dwParam2 (LPMCI_SAVE_PARMS) A pointer to the MCI_SAVE_PARMS data structure. ═══ Return Values - MCI_SAVE ═══ dwRC (DWORD) Return codes indicating success or failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INSTANCE_INACTIVE Device is currently inactive. Issue an MCI_ACQUIREDEVICE message to make device context active. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_FILE_NOT_FOUND File has not been loaded. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_OUT_OF_MEMORY Device out of memory. MCIERR_TARGET_DEVICE_FULL Target device is full. ═══ dwParam1 ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_SAVE_FILE The lpFilename field of the data structure identified by dwParam2 contains a pointer to a buffer containing the destination file name. If a file name is not specified, the original file opened or the most recently loaded file name is assumed. Digital Video Extensions The following additional flags apply to digital video drivers: MCI_DGV_SAVE_VIDEO_FILE Saves the motion video device element. MCI_DGV_SAVE_IMAGE_FILE Saves the still image device element. ═══ dwParam2 ═══ dwParam2 (LPMCI_SAVE_PARMS) A pointer to the MCI_SAVE_PARMS data structure. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INSTANCE_INACTIVE Device is currently inactive. Issue an MCI_ACQUIREDEVICE message to make device context active. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_FILE_NOT_FOUND File has not been loaded. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_OUT_OF_MEMORY Device out of memory. MCIERR_TARGET_DEVICE_FULL Target device is full. ═══ Example Code - MCI_SAVE ═══ The following code illustrates how to save a device element in a new video file and receive notification when the save is complete. WORD wDeviceID; HWND hwndMyWindow; MCI_SAVE_PARMS msp; /* Assign dwCallback the handle to the PM Window */ msp.dwCallback = (DWORD) hwndMyWindow; msp.lpFileName = (DWORD) "rebuttal.avs"; /* File name to save */ mciSendCommand( wDeviceID, /* Device ID */ MCI_SAVE, /* MCI save messge */ MCI_NOTIFY | MCI_DGV_SAVE_VIDEO_FILE, /* Flags for message */ (DWORD) msp, /* Data structure */ 0); /* No user parm */ ═══ 5.8. MCI_SET ═══ ═══ Topics - MCI_SET ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_SET ═══ This message sets device information. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_DGV_SET_PARMS dwParam2 returns DWORD dwRC ═══ Notes - MCI_SET ═══ Quality levels can be set individually for audio, video, and image. These preset quality levels enable applications to alter a specified compression algorithm to improve the quality of image capture and motion video and audio recording. ═══ Default Processing - MCI_SET ═══ None. ═══ Parameters - MCI_SET ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device. With the exception of the MCI_WAIT and MCI_NOTIFY flags, all other flags are mutually exclusive unless otherwise described. MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_SET_AUDIO Sets audio attributes of the device context. A device with audio capabilities may support both left and right channels. The channel is specified in the dwAudio field of the data structure specified by dwParam2. The action to be taken is specified with the flags MCI_SET_ON (which enables audio output at the current volume level), MCI_SET_OFF (which mutes audio output), or MCI_SET_VOLUME. Specifying MCI_SET_VOLUME does not enable audio output if MCI_SET_OFF has been previously specified. MCI_SET_RECORD Sets the audio or video input on or off. This flag must be used with either MCI_SET_AUDIO or MCI_SET_VIDEO and MCI_SET_ON or MCI_SET_OFF. To record audio only, use with the flags MCI_SET_VIDEO and MCI_SET_OFF. To record video only, use with the flags MCI_SET_AUDIO and MCI_SET_OFF. MCI_SET_VOLUME Sets the level of audio as a percentage of the maximum audio level as indicated in the dwLevel field. The volume level that can be set on the device might be of coarser granularity than that specified. In this case, the actual level can be obtained by issuing a MCI_STATUS message. If a number greater than 100 is given, then 100 will be used as the volume setting, and no error will be returned. MCI_SET_VIDEO Sets the video output signal on or off. This flag must be used with either MCI_SET_ON or MCI_SET_OFF. MCI_SET_ON Sets the video or specified audio channel on. The following values can be specified with MCI_SET_ON: MCI_SET_AUDIO_ALL MCI_SET_AUDIO_LEFT MCI_SET_AUDIO_RIGHT MCI_SET_OFF Sets the video or specified audio channel off. The following values can be specified with MCI_SET_OFF: MCI_SET_AUDIO_ALL MCI_SET_AUDIO_LEFT MCI_SET_AUDIO_RIGHT MCI_SET_MONITOR Enables monitoring. Must be used in conjunction with MCI_SET_ON or MCI_SET_OFF. MCI_SET_TIME_FORMAT Specifies a time format to be used on subsequent commands. A time-format parameter must be indicated in the dwTimeFormat field of the data structure specified by dwParam2 if this flag is used. The following time formats are supported by digital video devices: MCI_FORMAT_MMTIME Changes the time format to MMTIME. MCI_FORMAT_MILLISECONDS Changes the time format to milliseconds. MCI_FORMAT_FRAMES Changes the time format to frames. MCI_FORMAT_HMS Changes the time format to hours, minutes, seconds. MCI_SET_ITEM Specifies that an item to be set is specified in the dwItem field of the data structure pointed to by dwParam2. Any value associated with the item is contained in the dwValue field. Each item defines the use (if any) and meaning of the value in the dwValue field. dwParam2 (LPMCI_DGV_SET_PARMS) A pointer to a MCI_DGV_SET_PARMS data structure. This parameter replaces the standard default parameter data structure dwParm2(LPMCI_SET_PARMS). Digital Video Extensions The following additional flags apply to digital video devices: MCI_DGV_SET_VIDEO_COMPRESSION Sets the compression format used for recording digital motion video. MCI_VID_COMP_RTV_2_1 MCI_VID_COMP_RTV_2_0 MCI_DGV_SET_IMAGE_COMPRESSION Sets the compression type used for saving still bit maps or images. Values used are: MCI_IMG_COMP_PIC9_1_0 MCI_IMG_COMP_JPEG9_1_0 MCI_DGV_SET_AUDIO_COMPRESSION Sets the compression type used for recording of the associated digital audio soundtrack. Values used are: MCI_AUD_COMP_ADPCM4 MCI_AUD_COMP_PCM8 MCI_DGV_SET_IMAGE_QUALITY Sets the specified image quality level. Values used are: MCI_IMG_QUALITY_HIGH MCI_IMG_QUALITY_MED MCI_IMG_QUALITY_LOW MCI_DGV_SET_VIDEO_QUALITY Sets the specified video quality level. Values used are: MCI_VID_QUALITY_HIGH MCI_VID_QUALITY_MED MCI_VID_QUALITY_LOW MCI_DGV_SET_AUDIO_QUALITY Sets the specified audio quality level. Values used are: MCI_AUD_QUALITY_HIGH MCI_AUD_QUALITY_MED MCI_AUD_QUALITY-LOW ═══ Return Values - MCI_SET ═══ dwRC (DWORD) Return codes indicating success or type of failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INSTANCE_INACTIVE Device ID is currently inactive. Issue an MCI_ACQUIREDEVICE message to make the ID active. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_INVALID_MODE Current mode of the device prevents the message from being accepted. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Function is not supported. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATABLE Flags cannot be used together. MCIERR_INVALID_TIME_FORMAT_FLAG Invalid time format flag given. MCIERR_INVALID_AUDIO_FLAG Invalid audio flag given. MCIERR_OUT_OF_MEMORY Out of memory. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_CANNOT_CHANGE_CHANNEL Cannot change channel. MCIERR_INVALID_ITEM_FLAG Given flag is not correct. MCIERR_MISSING_ITEM Missing set item flag. ═══ dwParam1 ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device. With the exception of the MCI_WAIT and MCI_NOTIFY flags, all other flags are mutually exclusive unless otherwise described. MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_SET_AUDIO Sets audio attributes of the device context. A device with audio capabilities may support both left and right channels. The channel is specified in the dwAudio field of the data structure specified by dwParam2. The action to be taken is specified with the flags MCI_SET_ON (which enables audio output at the current volume level), MCI_SET_OFF (which mutes audio output), or MCI_SET_VOLUME. Specifying MCI_SET_VOLUME does not enable audio output if MCI_SET_OFF has been previously specified. MCI_SET_RECORD Sets the audio or video input on or off. This flag must be used with either MCI_SET_AUDIO or MCI_SET_VIDEO and MCI_SET_ON or MCI_SET_OFF. To record audio only, use with the flags MCI_SET_VIDEO and MCI_SET_OFF. To record video only, use with the flags MCI_SET_AUDIO and MCI_SET_OFF. MCI_SET_VOLUME Sets the level of audio as a percentage of the maximum audio level as indicated in the dwLevel field. The volume level that can be set on the device might be of coarser granularity than that specified. In this case, the actual level can be obtained by issuing a MCI_STATUS message. If a number greater than 100 is given, then 100 will be used as the volume setting, and no error will be returned. MCI_SET_VIDEO Sets the video output signal on or off. This flag must be used with either MCI_SET_ON or MCI_SET_OFF. MCI_SET_ON Sets the video or specified audio channel on. The following values can be specified with MCI_SET_ON: MCI_SET_AUDIO_ALL MCI_SET_AUDIO_LEFT MCI_SET_AUDIO_RIGHT MCI_SET_OFF Sets the video or specified audio channel off. The following values can be specified with MCI_SET_OFF: MCI_SET_AUDIO_ALL MCI_SET_AUDIO_LEFT MCI_SET_AUDIO_RIGHT MCI_SET_MONITOR Enables monitoring. Must be used in conjunction with MCI_SET_ON or MCI_SET_OFF. MCI_SET_TIME_FORMAT Specifies a time format to be used on subsequent commands. A time-format parameter must be indicated in the dwTimeFormat field of the data structure specified by dwParam2 if this flag is used. The following time formats are supported by digital video devices: MCI_FORMAT_MMTIME Changes the time format to MMTIME. MCI_FORMAT_MILLISECONDS Changes the time format to milliseconds. MCI_FORMAT_FRAMES Changes the time format to frames. MCI_FORMAT_HMS Changes the time format to hours, minutes, seconds. MCI_SET_ITEM Specifies that an item to be set is specified in the dwItem field of the data structure pointed to by dwParam2. Any value associated with the item is contained in the dwValue field. Each item defines the use (if any) and meaning of the value in the dwValue field. ═══ dwParam2 ═══ dwParam2 (LPMCI_DGV_SET_PARMS) A pointer to a MCI_DGV_SET_PARMS data structure. This parameter replaces the standard default parameter data structure dwParm2(LPMCI_SET_PARMS). Digital Video Extensions The following additional flags apply to digital video devices: MCI_DGV_SET_VIDEO_COMPRESSION Sets the compression format used for recording digital motion video. MCI_VID_COMP_RTV_2_1 MCI_VID_COMP_RTV_2_0 MCI_DGV_SET_IMAGE_COMPRESSION Sets the compression type used for saving still bit maps or images. Values used are: MCI_IMG_COMP_PIC9_1_0 MCI_IMG_COMP_JPEG9_1_0 MCI_DGV_SET_AUDIO_COMPRESSION Sets the compression type used for recording of the associated digital audio soundtrack. Values used are: MCI_AUD_COMP_ADPCM4 MCI_AUD_COMP_PCM8 MCI_DGV_SET_IMAGE_QUALITY Sets the specified image quality level. Values used are: MCI_IMG_QUALITY_HIGH MCI_IMG_QUALITY_MED MCI_IMG_QUALITY_LOW MCI_DGV_SET_VIDEO_QUALITY Sets the specified video quality level. Values used are: MCI_VID_QUALITY_HIGH MCI_VID_QUALITY_MED MCI_VID_QUALITY_LOW MCI_DGV_SET_AUDIO_QUALITY Sets the specified audio quality level. Values used are: MCI_AUD_QUALITY_HIGH MCI_AUD_QUALITY_MED MCI_AUD_QUALITY-LOW ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure: MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_INSTANCE_INACTIVE Device ID is currently inactive. Issue an MCI_ACQUIREDEVICE message to make the ID active. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_INVALID_MODE Current mode of the device prevents the message from being accepted. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Function is not supported. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATABLE Flags cannot be used together. MCIERR_INVALID_TIME_FORMAT_FLAG Invalid time format flag given. MCIERR_INVALID_AUDIO_FLAG Invalid audio flag given. MCIERR_OUT_OF_MEMORY Out of memory. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_CANNOT_CHANGE_CHANNEL Cannot change channel. MCIERR_INVALID_ITEM_FLAG Given flag is not correct. MCIERR_MISSING_ITEM Missing set item flag. ═══ Example Code - MCI_SET ═══ The following code illustrates setting audio attributes. In this example both left and right channels are specified, and the volume level is set at 50%. WORD wDeviceID; MCI_DGV_SET_PARMS mwsp; HWND hwndMyWindow; /* Assign dwCallback the handle to the PM Window */ mwsp.dwCallback = (DWORD) hwndMyWindow; mwsp.dwAudio = MCI_SET_AUDIO_ALL; /* Set both left and right */ mwsp.dwLevel = (DWORD) 50; /* volume level 50% */ mciSendCommand( wDeviceID, /* Device ID */ MCI_SET, /* MCI set message */ MCI_NOTIFY | MCI_SET_AUDIO | MCI_SET_VOLUME, /* Flags for this message */ (DWORD) mwsp, /* Data structure */ 0); /* No user parm */ ═══ 5.9. MCI_STATUS ═══ ═══ Topics - MCI_STATUS ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_STATUS ═══ This message obtains information about the status of the ActionMedia II device. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_STATUS_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_STATUS ═══ The parameters and flags for this message vary according to the selected device. All devices support this message, and the applicable status items for each device are listed with each parameter. ═══ Default Processing - MCI_STATUS ═══ None. ═══ Parameters - MCI_STATUS ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_STATUS_START Returns the starting position of the media. MCI_STATUS_ITEM Indicates that the dwItem field of the data structure identified by dwParam2 contains a constant specifying the status item in question. dwParam2 (LPMCI_STATUS_PARMS) A pointer to the MCI_STATUS_PARMS data structure. The following flags are standard item values that can be used in the dwItem field of the LPMCI_STATUS_PARMS data structure regardless of the type of device: MCI_STATUS_LENGTH Returns the total media length in units as specified in the MCI_SET message and the MCI_SET_TIME_FORMAT flag. If the media length cannot be determined, MCIERR_INDETERMINATE_LENGTH is returned. MCI_STATUS_MODE Returns the current mode of the device. Possible values are: MCI_MODE_PAUSE MCI_MODE_PLAY MCI_MODE_STOP MCI_MODE_RECORD MCI_MODE_SEEK MCI_STATUS_MONITOR Returns MCI_ON or MCI_OFF to indicate whether monitoring of the incoming video signal is set on or off. MCI_STATUS_POSITION Returns the current position. MCI_STATUS_READY Returns MCI_TRUE if the device is ready; otherwise, returns MCI_FALSE. MCI_STATUS_SPEED_FORMAT Returns the currently set speed format. The only speed format that can be set is: MCI_FORMAT_FPS MCI_STATUS_TIME_FORMAT Returns the currently set time format. Possible values are: MCI_FORMAT_MILLISECONDS MCI_FORMAT_MMTIME MCI_FORMAT_FRAMES MCI_FORMAT_HMS MCI_STATUS_VOLUME Returns the actual volume level set in the device as a percentage of the maximum achievable effect. The left channel is returned in the low-order word, and the right channel is returned in the high-order word. Digital Video Extensions The following additional status items apply to digital video devices: MCI_DGV_STATUS_HWND Returns the handle of the playback window. MCI_DGV_STATUS_AUDIO_COMPRESSION Returns the current compression format for playback or recording the associated audio sound track. MCI_DGV_STATUS_VIDEO_COMPRESSION Returns the current compression format for playback or recording of motion video. MCI_DGV_STATUS_IMAGE_COMPRESSION Returns the compression format currently set for capturing a loaded image. MCI_DGV_STATUS_AUDIO_QUALITY Returns the currently set audio quality level for recording the associated audio sound track. MCI_DGV_STATUS_VIDEO_QUALITY Returns the currently set video quality level for recording of motion video. MCI_DGV_STATUS_IMAGE_QUALITY Returns the currently set quality level for saving image data. MCI_DGV_STATUS_FORWARD Returns MCI_TRUE. MCI_DGV_STATUS_VIDEO_X_EXTENT Returns the horizontal (X) extent of the digital motion video image for the currently loaded motion video device element. MCI_DGV_STATUS_VIDEO_Y_EXTENT Returns the vertical (Y) extent of the digital motion video image for the currently loaded motion video device element. MCI_DGV_STATUS_IMAGE_X_EXTENT Returns the horizontal (X) extent of the currently loaded still image device element. MCI_DGV_STATUS_IMAGE_Y_EXTENT Returns the vertical (Y) extent of the currently loaded still image device element. ═══ Return Values - MCI_STATUS ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_ITEM_FLAG Invalid status item flag given. MCIERR_MISSING_ITEM Missing status item flag. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_INVALID_BUFFER Invalid return buffer given. ═══ dwParam1 ═══ dwParam1 (DWORD) The following flags can be used regardless of the type of device: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. MCI_STATUS_START Returns the starting position of the media. MCI_STATUS_ITEM Indicates that the dwItem field of the data structure identified by dwParam2 contains a constant specifying the status item in question. ═══ dwParam2 ═══ dwParam2 (LPMCI_STATUS_PARMS) A pointer to the MCI_STATUS_PARMS data structure. The following flags are standard item values that can be used in the dwItem field of the LPMCI_STATUS_PARMS data structure regardless of the type of device: MCI_STATUS_LENGTH Returns the total media length in units as specified in the MCI_SET message and the MCI_SET_TIME_FORMAT flag. If the media length cannot be determined, MCIERR_INDETERMINATE_LENGTH is returned. MCI_STATUS_MODE Returns the current mode of the device. Possible values are: MCI_MODE_PAUSE MCI_MODE_PLAY MCI_MODE_STOP MCI_MODE_RECORD MCI_MODE_SEEK MCI_STATUS_MONITOR Returns MCI_ON or MCI_OFF to indicate whether monitoring of the incoming video signal is set on or off. MCI_STATUS_POSITION Returns the current position. MCI_STATUS_READY Returns MCI_TRUE if the device is ready; otherwise, returns MCI_FALSE. MCI_STATUS_SPEED_FORMAT Returns the currently set speed format. The only speed format that can be set is: MCI_FORMAT_FPS MCI_STATUS_TIME_FORMAT Returns the currently set time format. Possible values are: MCI_FORMAT_MILLISECONDS MCI_FORMAT_MMTIME MCI_FORMAT_FRAMES MCI_FORMAT_HMS MCI_STATUS_VOLUME Returns the actual volume level set in the device as a percentage of the maximum achievable effect. The left channel is returned in the low-order word, and the right channel is returned in the high-order word. Digital Video Extensions The following additional status items apply to digital video devices: MCI_DGV_STATUS_HWND Returns the handle of the playback window. MCI_DGV_STATUS_AUDIO_COMPRESSION Returns the current compression format for playback or recording the associated audio sound track. MCI_DGV_STATUS_VIDEO_COMPRESSION Returns the current compression format for playback or recording of motion video. MCI_DGV_STATUS_IMAGE_COMPRESSION Returns the compression format currently set for capturing a loaded image. MCI_DGV_STATUS_AUDIO_QUALITY Returns the currently set audio quality level for recording the associated audio sound track. MCI_DGV_STATUS_VIDEO_QUALITY Returns the currently set video quality level for recording of motion video. MCI_DGV_STATUS_IMAGE_QUALITY Returns the currently set quality level for saving image data. MCI_DGV_STATUS_FORWARD Returns MCI_TRUE. MCI_DGV_STATUS_VIDEO_X_EXTENT Returns the horizontal (X) extent of the digital motion video image for the currently loaded motion video device element. MCI_DGV_STATUS_VIDEO_Y_EXTENT Returns the vertical (Y) extent of the digital motion video image for the currently loaded motion video device element. MCI_DGV_STATUS_IMAGE_X_EXTENT Returns the horizontal (X) extent of the currently loaded still image device element. MCI_DGV_STATUS_IMAGE_Y_EXTENT Returns the vertical (Y) extent of the currently loaded still image device element. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds, 0 is returned. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG A required flag is missing. MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid. MCIERR_HARDWARE Device hardware error. MCIERR_UNSUPPORTED_FUNCTION Unsupported function. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together. MCIERR_INVALID_ITEM_FLAG Invalid status item flag given. MCIERR_MISSING_ITEM Missing status item flag. MCIERR_MISSING_PARAMETER Required parameter is missing. MCIERR_INVALID_BUFFER Invalid return buffer given. ═══ Example Code - MCI_STATUS ═══ The following code illustrates getting the current position in the file. WORD wDeviceID; DWORD dwerror; DWORD dwPosition; /* Value for current position */ MCI_STATUS_PARMS mstatusp; mstatusp.dwItem = MCI_STATUS_POSITION; dwError = mciSendCommand( wDeviceID, /* Device ID */ MCI_STATUS, /* MCI status message */ MCI_WAIT | MCI_STATUS_ITEM, /* Flags for this message */ (DWORD) mstatusp,/* Data structure */ 0); /* No user parm */ if (dwError == MCIERR_SUCCESS) { dwPosition = mstatusp.dwReturn; /* Position status */ } ═══ 5.10. MCI_WINDOW ═══ ═══ Topics - MCI_WINDOW ═══ Select an item: Main Panel Parameters Return Values Notes Default Processing Example ═══ Main - MCI_WINDOW ═══ This message specifies an application window to be used by the ActionMedia II device for displaying digital video. Parameters: dwParam1 DWORD dwParam1 dwParam2 LPMCI_DGV_WINDOW_PARMS dwParam2 returns DWORD dwRC Return codes indicating success or type of failure. ═══ Notes - MCI_WINDOW ═══ By default, the ActionMedia II digital video device creates a window when an application opens the device, but it does not display the window until an MCI_CUE, MCI_PLAY, MCI_RECORD, or MCI_SET_MONITOR_ON command is received. The MCI_WINDOW command tells the device to use the specified application window instead of the default window to display motion video or still images. Applications that supply window handles to the digital video device must be prepared to update an invalid rectangle on the window. Several flags are provided to allow users to manipulate the window. Since the MCI_STATUS command can be used to obtain the current window handle, programmers may opt to use the standard window APIs instead. The flags are provided so applications that use the string interface can perform standard operations. ═══ Default Processing - MCI_WINDOW ═══ None. ═══ Parameters - MCI_WINDOW ═══ dwParam1 (DWORD) The following flags apply to all devices supporting MCI_WINDOW: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. dwParam2 (LPMCI_DGV_WINDOW_PARMS) A pointer to a MCI_DGV_WINDOW_PARMS data structure. The following flags apply to digital video devices: MCI_DGV_WINDOW_HWND Indicates that the handle of the client window used for the destination is included in the hwndDest field of the data structure. MCI_DGV_WINDOW_DEFAULT Indicates a return to the default window. MCI_DGV_WINDOW_STATE Indicates that the wCmdShow field of the data structure contains a parameter for setting the window state. The following standard Presentation Manager flags can be used: SWP_HIDE SWP_MAXIMIZE SWP_MINIMIZE SWP_SHOW SWP_RESTORE SWP_ACTIVATE SWP_DEACTIVATE MCI_DGV_WINDOW_TEXT Indicates that the lpstrText field of the data structure pointed to by dwParam2 contains a pointer to a buffer containing the caption used for the window. ═══ Return Values - MCI_WINDOW ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Callback or client window handle invalid. ═══ dwParam1 ═══ dwParam1 (DWORD) The following flags apply to all devices supporting MCI_WINDOW: MCI_NOTIFY A notification message is to be posted to the window specified in the dwCallback parameter of the data structure identified by dwParam2 when the action indicated by this message is completed. MCI_WAIT Control is not to be returned until the action indicated by this message is completed. ═══ dwParam2 ═══ dwParam2 (LPMCI_DGV_WINDOW_PARMS) A pointer to a MCI_DGV_WINDOW_PARMS data structure. The following flags apply to digital video devices: MCI_DGV_WINDOW_HWND Indicates that the handle of the client window used for the destination is included in the hwndDest field of the data structure. MCI_DGV_WINDOW_DEFAULT Indicates a return to the default window. MCI_DGV_WINDOW_STATE Indicates that the wCmdShow field of the data structure contains a parameter for setting the window state. The following standard Presentation Manager flags can be used: SWP_HIDE SWP_MAXIMIZE SWP_MINIMIZE SWP_SHOW SWP_RESTORE SWP_ACTIVATE SWP_DEACTIVATE MCI_DGV_WINDOW_TEXT Indicates that the lpstrText field of the data structure pointed to by dwParam2 contains a pointer to a buffer containing the caption used for the window. ═══ dwRC ═══ dwRC (DWORD) Return codes indicating success or type of failure. MCIERR_SUCCESS If the function succeeds. MCIERR_INVALID_DEVICE_ID Device ID is not valid. MCIERR_MISSING_FLAG Required flag is missing. MCIERR_INVALID_FLAG Flag is invalid (dwParam1). MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device. MCIERR_INVALID_CALLBACK_HANDLE Callback or client window handle invalid. ═══ Example Code - MCI_WINDOW ═══ The following code illustrates creating an application window that will be used for displaying motion video and images. MCI_DGV_WINDOW_PARMS mdgvwindowp; HWND hwndFrame, hwndClient; WORD wDeviceID; DWORD dwError; ULONG ulCtlData; ulCtlData = FCF_STANDARD; hwndFrame = WinCreateStdWindow( HWND_DESKTOP, 0L, ulCtlData, (PSZ)"Digital Video", (PSZ)"Digital Video Window", WS_VISIBLE, (HMODULE)NULL, ID_RESOURCE, (PHWND)hwndClient ); if( hwndFrame != NULLHANDLE ){ /* Set up the window structure so that the driver displays video in the client window */ mdgvwindowp.dwCallback = NULLHANDLE; mdgvwindowp.hwndDest = hwndClient; mdgvwindowp.wCmdShow = 0; mdgvwindowp.wReserved1 = 0; mdgvwindowp.lpstrText = (LPSTR)NULL; mdgvwindowp.lpstrAlias = (LPSTR)NULL; /* Issue MCI_WINDOW command */ dwError = mciSendCommand( wDeviceID, MCI_WINDOW, MCI_DGV_WINDOW_HWND | MCI_WAIT, (DWORD)mdgvwindowp, 0 ); } ═══ 6. Media Control Interface Data Structures ═══ This chapter contains the data structures for the digital video command messages that are supported by the ActionMedia II Media Control Interface. All other command message data structures for the Media Control Interface are described in the MMPM/2 Programming Reference. The following table lists the command messages and associated data structures used by the ActionMedia II digital video device. ┌─────────────────────────┬───────────────────────────────────┐ │Command Message │Description │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_CAPTURE │MCI_CAPTURE_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_CLOSE │MCI_GENERIC_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_CONNECTOR │MCI_CONNECTOR_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_CUE │MCI_GENERIC_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_GETDEVCAPS │MCI_GETDEVCAPS_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_INFO │MCI_INFO_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_LOAD │MCI_LOAD_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_OPEN │MCI_DGV_OPEN_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_PLAY │MCI_DGV_PLAY_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_PAUSE │MCI_GENERIC_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_RECORD │MCI_RECORD_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_RESTORE │MCI_RESTORE_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_RESUME │MCI_GENERIC_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_REWIND │MCI_GENERIC_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_SAVE │MCI_SAVE_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_SEEK │MCI_SEEK_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_SET │MCI_DGV_SET_PARMS (This structure │ │ │is the equivalent of │ │ │MCI_SET_PARMS.) │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_STEP │MCI_STEP_PARMS │ ├─────────────────────────┼───────────────────────────────────┤ │MCI_WINDOW │MCI_DGV_WINDOW_PARMS │ └─────────────────────────┴───────────────────────────────────┘ The following table lists the fields in Release 1.0 data structures that are not used in the current ActionMedia implementation of the Media Control Interface. ┌────────────────────┬────────────────────────────────────────┐ │Data Structure │Field Not Used │ ├────────────────────┼────────────────────────────────────────┤ │MCI_RECORD_PARMS │dwFrom │ ├────────────────────┼────────────────────────────────────────┤ │MCI_SET_PARMS │dwOver │ ├────────────────────┼────────────────────────────────────────┤ │MCI_STATUS │dwTrack │ ├────────────────────┼────────────────────────────────────────┤ │MCI_STEP │dwStep │ └────────────────────┴────────────────────────────────────────┘ ═══ 6.1. MCI_CAPTURE_PARMS ═══ MCI_CAPTURE_PARMS The MCI_CAPTURE_PARMS structure contains parameters for the MCI_CAPTURE message. typedef struct _MCI_CAPTURE_PARMS { DWORD dwCallback; /* */ RECT rect; /* */ } MCI_CAPTURE_PARMS; ═══ dwCallback ═══ dwCallback (DWORD) A window handle cast to a DWORD to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ rect ═══ rect (RECT) A rectangle array specifying the area to be captured. Note: This field is not used in the current ActionMedia II implementation. ═══ 6.2. MCI_DGV_OPEN_PARMS ═══ MCI_DGV_OPEN_PARMS The MCI_DGV_OPEN_PARMS structure contains information for the MCI_OPEN message for digital video devices. typedef struct _MCI_DGV_OPEN_PARMS { DWORD dwCallback; /* */ WORD wDeviceID; /* */ WORD wReserved0; /* */ LPSTR lpstrDeviceType; /* */ LPSTR lpstrElementName; /* */ LPSTR lpstrAlias; /* */ HWND hwndParent; /* */ } MCI_DGV_OPEN_PARMS; ═══ dwCallback ═══ dwCallback (DWORD) A window handle cast to a DWORD to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ wDeviceID ═══ wDeviceID (WORD) The device ID returned to the user. ═══ wReserved0 ═══ wReserved0 (WORD) Reserved. ═══ lpstrDeviceType ═══ lpstrDeviceType (LPSTR) The name or constant ID of the device type. ═══ lpstrElementName ═══ lpstrElementName (LPSTR) The device element name (usually a path name) or NULL. ═══ lpstrAlias ═══ lpstrAlias (LPSTR) An optional device alias. ═══ hwndParent ═══ hwndParent (HWND) The handle to use as the window parent. ═══ 6.3. MCI_DGV_PLAY_PARMS ═══ MCI_DGV_PLAY_PARMS The MCI_DGV_PLAY_PARMS structure contains parameters for the MCI_PLAY message for digital video devices. typedef struct _MCI_DGV_PLAY_PARMS { DWORD dwCallback; /* */ DWORD dwFrom; /* */ DWORD dwTo; /* */ DWORD dwSpeed; /* */ } MCI_DGV_PLAY_PARMS; ═══ dwCallback ═══ dwCallback (DWORD) A window handle cast to a DWORD to be used in returning asynchronous notification messages. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ dwFrom ═══ dwFrom (DWORD) The position to play from. ═══ dwTo ═══ dwTo (DWORD) The position to play to. ═══ dwSpeed ═══ dwSpeed (DWORD) The play rate in frames per second. Note: This field is not used in the current ActionMedia II implementation. ═══ 6.4. MCI_DGV_WINDOW_PARMS ═══ MCI_DGV_WINDOW_PARMS The MCI_DGV_WINDOW_PARMS structure contains parameters for the MCI_WINDOW message for digital video devices. typedef struct _MCI_DGV_WINDOW_PARMS { DWORD dwCallback; /* */ HWND hwndDest; /* */ WORD wReserved1; /* */ WORD wCmdShow; /* */ LPSTR lpstrText; /* */ LPSTR lpstrAlias; /* */ } MCI_DGV_WINDOW_PARMS; ═══ dwCallback ═══ dwCallback (DWORD) A window handle cast to a DWORD for the MCI callback function. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ hwndDest ═══ hwndDest (HWND) A handle to the client window used for the destination of the digital video. ═══ wReserved1 ═══ wReserved1 (WORD) Reserved. ═══ wCmdShow ═══ wCmdShow (WORD) Specifies how the window is displayed. ═══ lpstrText ═══ lpstrText (LPSTR) The text to use as the window caption. ═══ lpstrAlias ═══ lpstrAlias (LPSTR) The window alias for the display window. Note: This field is not used in the current ActionMedia II implementation. ═══ 6.5. MCI_RESTORE_PARMS ═══ MCI_RESTORE_PARMS The MCI_RESTORE_PARMS structure contains parameters for the MCI_RESTORE message. typedef struct _MCI_RESTORE_PARMS { DWORD dwCallback; /* */ RECT SrcRect; /* */ RECT DestRect; /* */ } MCI_RESTORE_PARMS; ═══ dwCallback ═══ dwCallback (DWORD) A window handle cast to a DWORD for the MCI callback function. This parameter must be specified if the MCI_NOTIFY flag is specified. ═══ SrcRect ═══ SrcRect (RECT) The source image rectangle array of the area to restore. Note: This field is not used in the current ActionMedia II implementation. ═══ DestRect ═══ DestRect (RECT) The destination window rectangle array of the area to restore. Note: This field is not used in the current ActionMedia II implementation. ═══ ═══ 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. 5. Select OK. The bookmark is then added to the bookmark list. ═══ ═══ 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 on the Contents list. To search for a word or phrase in all topics, do the following: 1. Select the Search option from the Services menu. 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. ═══ ═══ 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. ═══ ═══ 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. ═══ ═══ 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. ═══ ═══ Notices 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 protectible 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. ═══ ═══ Trademarks and Service Marks The following terms, denoted by an asterisk (*) in this information, are trademarks of the International Business Machines Corporation in the United States and/or other countries: AVC Audio Visual Connection CUA Common User Access OS/2 Operating System/2 PS/2 Personal System/2 IBM M-Motion Multimedia Presentation Manager/2 Multimedia Presentation Manager Toolkit/2 Presentation Manager Workplace Shell The following terms, denoted by a double asterisk (**) in this publication are the trademarks of other companies as follows: DVI Intel Corporation. ActionMedia Intel Corporation.