BOOLEAN
SetOverlayRectsFunc(
PDEVICE_INFO pDevInfo,
POVERLAY_RECTS pOR
);
The SetOverlayRectsFunc function sets the overlay region. The function is provided by the kernel-mode driver, and the SetOverlayRectsFunc name is a placeholder for a driver-specified function name.
Returns TRUE if the operation succeeds. Otherwise returns FALSE. If FALSE, VCKernel.lib sets the Win32 error code value to STATUS_DEVICE_CONFIGURATION_ERROR.
The VCKernel.lib library calls a kernel-mode driver’s SetOverlayRectsFunc function when the driver receives an IOCTL_VIDC_OVERLAY_RECTS control code. User-mode drivers using VCUser.lib send this control code by calling VC_SetOverlayRect.
After the user-mode driver enables overlay by calling VC_Overlay, the kernel-mode driver should display captured video source images inside the overlay area of the output display. (If the device supports color keying, then the user-mode driver typically repaints the overlay area with the key color when it receives a DVM_UPDATE message.)
Drivers for devices that support scaling generally do not scale the video source image to the overlay area. Instead, scaling of the captured image is typically based on the capture format and controlled by the ConfigFormatFunc function. Thus, the image might not fit into the overlay rectangle. If the driver’s SetOverlayOffsetFunc function has not been called to set an offset rectangle, the driver should align the top left corner of the video source with the top left corner of the overlay region. If the source rectangle is larger than the overlay rectangle, the driver should crop the source as necessary at the bottom and right sides.
If a format has not been specified, the sample driver, bravado.sys, does scale the captured image to the overlay rectangle, in order to support applications that only overlay the source image without capturing frames.
Support for a SetOverlayRectsFunc function is required, if the device supports overlay. If a driver does support the function, it must place its address in the VC_CALLBACK structure supplied by VCKernel.lib. If a driver that does not support a SetOverlayRectsFunc function receives an IOCTL_VIDC_OVERLAY_RECTS control code, VCKernel.lib sets the Win32 error code value to STATUS_INVALID_DEVICE_REQUEST.