MCI_FREEZE
This message freezes the motion video on an area of the display.
Syntax
param1 ULONG ulParam1; /* Flags for freeze operation. */ param2 PMCI_OVLY_RECT_PARMS pParam2; /* Pointer to the MCI_OVLY_RECT_PARMS data structure. */
Parameters
- ulParam1 (ULONG) - input
- This parameter can contain 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.
- Video Overlay Extensions
- The following additional items apply to video overlay devices:
- MCI_OVLY_FREEZE_RECT Specifies that the rc field of the MCI_OVLY_RECT_PARMS data structure contains a valid rectangle. If this flag is not specified, the entire image is frozen.
- MCI_OVLY_FREEZE_RECT_OUTSIDE Specifies that the area outside the specified rectangle is to be affected. If this flag is not specified then the area inside is affected. This flag must be specified with the MCI_OVLY_FREEZE_RECT flag.
- pParam2 (PMCI_OVLY_RECT_PARMS) - input
- A pointer to the MCI_OVLY_RECT_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_INSTANCE_INACTIVE Instance inactive.
- 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
MCI_FREEZE differs from MCI_PAUSE in that it causes the video overlay device to cease updating the video image without affecting the state of the image source device (external video device). For example, if a motion video is being played and MCI_FREEZE is issued, the motion video continues to play but its display is frozen.
Freezing or unfreezing an area outside the current video destination rectangle has no effect.
Multiple freeze and unfreeze commands, which specify rectangles to be affected, can be issued sequentially to build up a complex region of frozen and unfrozen video.
Default Processing
If MCI_OVLY_FREEZE_RECT is not specified, the entire image is frozen. If MCI_OVLY_FREEZE_RECT_OUTSIDE is not specified, the default is the area inside the rectangle.
Example Code
MCI_VID_RECT_PARMS mciFreezeParms;
USHORT usUserParm = 0;
ULONG ulReturn;
/* Freezing OUTSIDE a sub-rectangle of the window */
memset (&mciFreezeParms, 0x00, sizeof (MCI_VID_RECT_PARMS));
mciFreezeParms.hwndCallback = hwndNotify;
mciFreezeParms.rc.xLeft = lX1;
mciFreezeParms.rc.yBottom = lY1;
mciFreezeParms.rc.xRight = lX2;
mciFreezeParms.rc.yTop = lY2;
ulReturn = mciSendCommand(usDeviceID,
MCI_FREEZE,
MCI_WAIT |
MCI_OVLY_FREEZE_RECT_OUTSIDE |
MCI_OVLY_FREEZE,
(PVOID)&mciFreezeParms,
usUserParm);