MCI CAPTURE

This message requests the digital video device to capture the current movie frame and store it as an image device element.

Syntax

param1
ULONG ulParam1; /* Flags for capture operation. */

param2
PMCI_CAPTURE_PARMS pParam2; /* Pointer to the MCI_CAPTURE_PARMS data structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags:

• MCI_NOTIFY A notification message will be posted to the window specified in the hwndCallback parameter of the data structure pointed to by the pParam2 parameter. The notification will be posted when the action indicated by this message is completed or when an error occurs.
• MCI_WAIT Control is not to be returned until the action indicated by this message is completed or an error occurs.
• MCI_CAPTURE_RECT Indicates that a region of the screen to be captured is provided in the rect field of the MCI_CAPTURE_PARMS structure pointed to by pParam2.
• MCI_CONVERT Specifies that the captured image data will be converted to the OS/2 bit-map format when it is saved to disk.

pParam2 (PMCI_CAPTURE_PARMS) - input

A pointer to an MCI_CAPTURE_PARMS data structure.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• MCIERR_SUCCESS MMPM/2 command completed successfully.
• MCIERR_OUT_OF_MEMORY System out of memory.
• MCIERR_INVALID_DEVICE_ID Invalid device ID given.
• MCIERR_MISSING_PARAMETER Missing parameter for this command.
• MCIERR_DRIVER Internal MMPM/2 driver error.
• MCIERR_INVALID_FLAG Invalid flag specified for this command.
• MCIERR_UNSUPPORTED_FLAG Flag not supported by this MMPM2 driver for this command.
• MCIERR_INSTANCE_INACTIVE The device has been opened as shareable and is currently in use by another application.
• MCIERR_OVLY_INVALID_RECT An invalid rectangle parameter was specified.
• MCIERR_OVLY_NOT_AVAILABLE The requested action is not available (For example, because video has been set off).

Remarks

• • Note**: **MCI_CAPTURE** captures bit maps from movies rather than hardware. See MCI_GETIMAGEBUFFER for a description of how to capture from hardware with a video capture card.

This command is not supported by all devices. Use the MCI_GETDEVCAPS command to determine whether the device supports **MCI_CAPTURE**.

Repeated capture commands overwrite the image in the device element buffer. If the application wants to transfer the image data to a permanent file, it can use the MCI_SAVE message with the **MCI_DGV_SAVE_IMAGE_FILE** flag set. If the application wants the image copied to its address space, it issues MCI_GETIMAGEBUFFER.

The captured image is retained as the device element. With overlay video devices implemented on dual-plane video hardware, the image is captured from the video or image layer.

The media control device can perform the following operations:

• Freeze the motion temporarily, if needed, to capture the image.
• Obtain image data from the device and place the data into the capture and restore buffer.
• Perform an "unfreeze" (if necessary) to return to the original state.

It will **not** convert, translate, or change the data from the internal format into another format.

If no rectangle is specified, the entire video image in the video window is captured.

Example Code

    MCI_CAPTURE_PARMS mciCaptureParms;
    USHORT usUserParm = 0;
    ULONG ulReturn;
    USHORT usDeviceID;
    HWND hwndNotify;
    ULONG ulX1, ulY1, ulX2, ulY2; /* Define rectangle coordinates */

    /* Without a rectangle */
    memset (&mciCaptureParms, 0x00, sizeof (MCI_CAPTURE_PARMS));
    mciCaptureParms.hwndCallback = hwndNotify;
    /* mciCaptureParms.rect remains 0 */

    ulReturn = mciSendCommand(usDeviceID, MCI_CAPTURE,
                      MCI_WAIT,
                      (PVOID)&mciCaptureParms,
                      usUserParm);

    /* With a rectangle */
    memset (&mciCaptureParms, 0x00, sizeof (MCI_CAPTURE_PARMS));
    mciCaptureParms.hwndCallback = hwndNotify;
    mciCaptureParms.rect.xLeft  = ulX1;
    mciCaptureParms.rect.yBottom = ulY1;
    mciCaptureParms.rect.xRight  = ulX2;
    mciCaptureParms.rect.yTop    = ulY2;


    ulReturn = mciSendCommand(usDeviceID, MCI_CAPTURE,
                      MCI_WAIT | MCI_CAPTURE_RECT,
                      (PVOID)&mciCaptureParms,
                      usUserParm);

Related Methods

• MCI_GETIMAGEBUFFER