The video overlay command set provides a common method for displaying overlay video in the Windows environment. Video overlay devices must support the following set of commands:
Video Overlay Commands
| Command | Description |
| capability item | Requests information about the capabilities of the video overlay device. The item is one of the following: | |
| can eject Returns false. Video overlay devices have no media to eject. | ||
| can freeze Returns true if the device can freeze data in the frame buffer. | ||
| can play Returns false. | ||
| can record Returns false. | ||
| can save Returns true if the device can save the current contents of the frame buffer to disk. | ||
| can stretch Returns true if the device can stretch frames to fill a given display rectangle. | ||
| compound device Returns true if the device requires an element name. Video overlay devices which support multiple windows may be compound devices. | ||
| device type Returns overlay. | ||
| has audio Returns false if the device supports audio playback. | ||
| has video Returns true. Video overlay devices are video devices. | ||
| uses files Returns true if the element of a compound device is a file pathname. | ||
| windows Returns the number of simultaneous display windows the device can support. | ||
| close | Closes a video overlay element and any resources associated with it. | |
| freeze item | Disables video acquisition to the frame buffer. This is supported only if capability can freeze returns true. The following optional item modifies freeze: | |
| at rectangle Specifies the rectangular region that will have video acquisition disabled. Irregular acquisition regions can be specified using the freeze and unfreeze commands. (Some video overlay devices will place limitations on the complexity of the region used for acquisition.) The rectangle region is relative to the video buffer origin and is specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner and the coordinates X2, Y2 specify the width and height of the rectangle. | ||
| info item | Fills a user-supplied buffer with information. The following optional item modifies info: | |
| file Returns the name of the file used by the video overlay device. | ||
| product Returns the product name and model of the current video overlay device. | ||
| window text Returns the caption of the window used by the video overlay device. | ||
| load item | Loads the contents of the video buffer in a device specific format. The following optional items modify load: | |
| filename Specifies the file and pathname used to load the data. | ||
| at rectangle Specifies a rectangle relative to the video buffer origin. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner and the coordinates X2, Y2 specify the width and height of the rectangle. | ||
| open items | Initializes the video overlay device. The following optional items modify open: | |
| alias device_ alias Specifies an alternate name for the device element. If specified, it must also be used for subsequent references. | ||
| parent hwnd Specifies the window handle of the parent window. | ||
| shareable Initializes the device element as shareable. Subsequent attempts to open it fail unless you specify shareable in both the original and subsequent open commands. MCI returns an error if it is already open and not shareable. | ||
| style style_type Indicates a window style. | ||
| style child Opens a window with a child window style. | ||
| style overlapped Opens a window with an overlapped window style. | ||
| style popup Opens a window with a popup window style. | ||
| type device_ type Specifies the device type of the device element. MCI reserves overlay for the video overlay device type. As an alternative to type, MCI can use the [mci extension] entries in the SYSTEM.INI file to select the controlling device based on the extension used by the device element. | ||
| put items | Defines the source, destination, and frame windows. One of the following items modify put: | |
| destination Sets the whole window as the destination window. | ||
| destination at rectangle Specifies a rectangle for the area of the window used to display the image. The rectangle coordinates are relative to the window origin and are specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner, and the coordinates X2, Y2 specify the width and height of the rectangle. When an area of the display window is specified, and the device supports stretching, the source image is stretched to the destination offset and extent. | ||
| frame Specifies that the whole video buffer is used to capture the video image. | ||
| frame at rectangle Specifies a rectangle for the area of the video buffer used to capture the video image. The rectangle coordinates are relative to the video buffer origin and are specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner, and the coordinates X2, Y2 specify the width and height of the rectangle. If the device supports stretching, the video image is stretched to the frame extent. | ||
| source Selects the whole video buffer for display in the destination window. | ||
| source at rectangle Specifies a rectangle for the video buffer area used to obtain the image for display. The rectangle coordinates are relative to the video buffer origin and are specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner, and the coordinates X2, Y2 specify the width and height of the rectangle. When an area of the source image is specified, and the device supports stretching, the source image is stretched to the destination offset and extent. | ||
| video Selects the whole input video source for display in the destination window. | ||
| video at rectangle Specifies a rectangle for the input video source area used to obtain the image for display. The rectangle coordinates are relative to the video origin and are specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner, and the coordinates X2, Y2 specify the width and height of the rectangle. When an area of the source image is specified, and the device supports stretching, the source image is stretched to the destination offset and extent. | ||
| save item | Saves the contents of the video buffer in a device specific format. The following optional item modifies save: | |
| filename Specifies the file and pathname used to save the data. | ||
| at rectangle Specifies a rectangle relative to the video buffer origin. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner and the coordinates X2, Y2 specify the width and height of the rectangle. | ||
| set items Sets the various control items: | ||
| audio all off, audio all on Video overlay devices do not support this option. | ||
| audio left off, audio left on Video overlay devices do not support this option. | ||
| audio right off, audio right on Video overlay devices do not support this option. | ||
| time format milliseconds Video overlay devices do not support this option. | ||
| video off, video on Enables or disables video output. | ||
| status item | Obtains status information for the device. One of the following items modifies status: | |
| media present Returns true. | ||
| mode Returns not ready, recording, or stopped for the current mode. | ||
| ready Returns true if the video overlay device is ready. | ||
| window handle Returns the handle of the window used for the video overlay display in the low word of the return value. | ||
| unfreeze item | Enables the frame buffer to acquire video data. This is supported only if capability can freeze returns true. The following optional item modifies unfreeze: | |
| at rectangle Specifies a rectangle relative to the video buffer origin. The rectangle is specified as X1 Y1 X2 Y2. The coordinates X1, Y1 specify the top, left corner and the coordinates X2, Y2 specify the width and height of the rectangle. | ||
| where | Obtains the rectangle specifying the source, destination, or frame area. One of the following items modifies where: | |
| destination Requests the offset and extent of the destination rectangle. | ||
| frame Requests the offset and extent of the frame buffer rectangle. | ||
| source Requests the offset and extent of the source rectangle. | ||
| video Requests the offset and extent of the video rectangle. | ||
| window item | Tells the video overlay device to use a given window for display instead of the default window created by the driver. By default, video overlay devices should create a window when opened but should not display it until the device receives the play command. Applications providing window handles should manage the display issues that result when the window is sized or when the window handle is switched during play. 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 Specifies the handle of the destination window used as an alternate to the default window. | ||
| handle default Specifies that the video overlay device should create and manage its own window. This flag can be used to set the display back to the driver's default window. | ||
| state hide Hides the current display window. | ||
| state iconic Displays the window as an icon. | ||
| state maximized Maximizes the current display window. | ||
| state minimize Minimizes the specified window and activates the top-level window in the window-manager's list. | ||
| state minimized Minimizes the current display window. | ||
| state no action Displays the display window in its current state. The window currently active remains active. | ||
| state no activate Displays the display window in its most recent size and state. The window that is currently active remains active. | ||
| state normal Displays the current display window as it was created. | ||
| state show Shows the current display window. | ||
| text caption Specifies the caption for the display window. | ||