IWiaPreview::DetectRegions method

Invokes the driver segmentation filter and passes the unfiltered image cached by the IWiaPreview::GetNewPreview method to the filter.

Syntax

HRESULT DetectRegions(
  [in] LONG lFlags
);

Parameters

lFlags [in]

Type: LONG

Not used. Set to zero (0).

Return value

Type: HRESULT

This method can return one of these values.

Remarks

An application must call IWiaPreview::GetNewPreview before it calls this function.

When the Windows Image Acquisition (WIA) 2.0 Preview Component calls IWiaPreview::DetectRegions, it invokes the driver segmentation filter and passes the IWiaItem2 interface that was previously passed to IWiaPreview::GetNewPreview. It also passes the internally cached image to the filter. The segmentation filter uses the cached image to create the child extents.

If an application changes any properties of the IWiaItem2 interface after it calls IWiaPreview::GetNewPreview, then the original properties must be restored before the application calls IWiaPreview::DetectRegions. Use GetPropertyStream and SetPropertyStream to restore the original properties.

IWiaPreview::DetectRegions is used to determine the "sub-regions" of the cached image. For each sub-region detected, a new child WIA 2.0 item is created under the IWiaItem2 interface. For each child item, the segmentation filter must set the values for the following WIA 2.0 properties: WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT, and WIA_IPS_YEXTENT. A more advanced filter sets other WIA 2.0 properties, such as WIA_IPS_DESKEW_X and WIA_IPS_DESKEW_Y, if the driver supports de-skewing. The WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT, and WIA_IPS_YEXTENT properties represent the bounding rectangle of the area to scan.

The driver might not support segmentation. Before calling IWiaPreview::DetectRegions, an application typically checks whether the driver supports the WIA_IPS_SEGMENTATION property. If the property is not implemented, segmentation is not supported, and IWiaPreview::DetectRegions fails and returns E_NOTIMPL.

The application must clean up the child items that are created by calling IWiaPreview::DetectRegions. For example, if an application makes an additional call to IWiaPreview::DetectRegions on the same item, it must clean up the previous child items.

Requirements