MCI_RESTORE

This message causes a video device to transfer an image from the element buffer to the display surface. To ensure that the image is displayed, the device automatically performs a freeze operation where necessary.

Syntax

param1
ULONG ulParam1; /* Message flags. */

param2
PMCI_RESTORE_PARMS pParam2; /* Pointer to the MCI_RESTORE_PARMS structure. */

Parameters

ulParam1 (ULONG) - input

The following flags can be used:

MCI_NOTIFY Posts a notification message when the action completes.
MCI_WAIT Does not return control until the action is completed.
MCI_RESTORE_SRC_RECT The SrcRect field of the parameter structure contains a rectangle specifying the area to be restored from the capture device element. If omitted, the entire image is restored.
MCI_RESTORE_DEST_RECT The DestRect field of the parameter structure contains a rectangle specifying the destination area of the window. If omitted, the destination size is assumed to be the same as the image size in device coordinates, placed at the lower-left corner of the window.

pParam2 (PMCI_RESTORE_PARMS) - input: A pointer to the MCI_RESTORE_PARMS data structure.

Returns

rc (ULONG) - returns

This function fails if nothing is currently in the capture device element.

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 driver.
MCIERR_INSTANCE_INACTIVE The device is currently inactive.
MCIERR_OVLY_INVALID_RECT An invalid rectangle was specified.
MCIERR_OVLY_NOT_AVAILABLE Requested action not available (e.g., video set off).

Remarks

The image is restored from the device element in an overlay video device or from the still image device element of a digital video device.

In dual-plane video hardware, the image is restored to the video or image layer. Devices capable of scaling will attempt to scale the output to the destination rectangle. If the device cannot scale, the output is clipped to the destination rectangle.

Example Code

  MCI_IMAGE_PARMS mciImageParms;
  MCI_RESTORE_PARMS mciRestoreParms;
  USHORT  usUserParm = 0;
  ULONG   ulReturn;

  /* Restore without a specific rectangle */
  memset (&mciRestoreParms, 0x00, sizeof (MCI_RESTORE_PARMS));
  mciRestoreParms.hwndCallback = hwndNotify;

  ulReturn = mciSendCommand(usDeviceID, MCI_RESTORE,
                   MCI_WAIT,
                   (PVOID)&mciRestoreParms,
                   usUserParm);

  /* Restore with a specific destination rectangle */
  memset (&mciRestoreParms, 0x00, sizeof (MCI_RESTORE_PARMS));
  mciRestoreParms.hwndCallback = hwndNotify;
  mciRestoreParms.DestRect.xLeft   = lX1;
  mciRestoreParms.DestRect.yBottom = lY1;
  mciRestoreParms.DestRect.xRight  = lX2;
  mciRestoreParms.DestRect.yTop    = lY2;

  ulReturn = mciSendCommand(usDeviceID, MCI_RESTORE,
                   MCI_WAIT | MCI_RESTORE_DEST_RECT,
                   (PVOID)&mciRestoreParms,
                   usUserParm);

Related Messages