IWiaPreview::UpdatePreview method

Article
01/07/2021

Gets the unfiltered image cached by the IWiaPreview::GetNewPreview method.

Syntax

HRESULT UpdatePreview(
  [in] LONG      lOptions,
  [in] IWiaItem2 *pChildWiaItem
);

Parameters

lOptions [in]

Type: LONG

Specifies whether the application requires the WIA 2.0 Preview Component to pass a sub-region of the cached image or the entire cached image to the image processing filter.

WiaPreviewReturnOriginalImage

Pass the entire cached image to the image processing filter.

pChildWiaItem [in]

Type: IWiaItem2*

Specifies a pointer to the IWiaItem2 item, which is a child of the IWiaItem2 item specified by the pWiaItem2 parameter of the IWiaPreview::GetNewPreview method. Or, if the application requires a preview of the whole flatbed, specifies a pointer to the pWiaItem2 parameter of the IWiaPreview::GetNewPreview method. When pChildWiaItem is a child of IWiaPreview::GetNewPreview's pWiaItem2 parameter, this child item is typically created by the segmentation filter.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method passes the cached, unfiltered image through the image processing filter, which then writes the filtered data to the application-provided stream. The WIA 2.0 Preview Component retrieves this stream by calling the image processing filter's GetNextStream method, which then calls the application callback's GetNextStream implementation. Before calling IWiaPreview::UpdatePreview, an application must first call IWiaPreview::GetNewPreview to acquire the image from the scanner; otherwise, the method returns an error.

The WIA 2.0 Preview Component stores the unfiltered image downloaded from the driver. It is possible that the WIA 2.0 item passed into IWiaPreview::UpdatePreview represents only a small region of the image downloaded from the driver. If this is the case the WIA 2.0 Preview Component actually cuts out this region from the cached image before it passes it to the image processing filter, which in turn passes the filtered image data back to the application.

For an application to pass the entire cached image to the image processing filter (which in turn passes it to the application), it must set the lOptions to WiaPreviewReturnOriginalImage when calling IWiaPreview::UpdatePreview. When setting lOptions to WiaPreviewReturnOriginalImage, the application must ensure that the extent settings (WIA_IPS_XEXTENT and WIA_IPS_YEXTENT) of the item passed into IWiaPreview::UpdatePreview matches the full-cached image. The image processing filter need not do anything different in this case; it simply filters the image, based on the properties of pChildWiaItem (typically in this case pChildWiaItem is the same item that was passed to IWiaPreview::GetNewPreview). The different sub-regions are ignored and the whole image is filtered using the same settings. There are a couple of reasons why an application would do this.

The application may not support changing the settings (like WIA_IPS_BRIGHTNESS and WIA_IPS_CONTRAST) individually for each region that the segmentation filter detects (or it may not even want to use the segmentation filter). It is easier for the application to call IWiaPreview::UpdatePreview with WiaPreviewReturnOriginalImage so that it always receives the full image from the WIA 2.0 Preview Component.
The WIA 2.0 Preview Component does not support the image format of the preview image, in which case it cannot perform the actions to cut out the desired region. The WIA 2.0 Preview Component's image format support is limited to formats for which there are Windows GDI+ 1.1 encoders and decoders. These formats are bitmap (BMP) (a bitmap that includes the BITMAPFILEHEADER), Graphics Interchange Format (GIF), JPEG, Portable Network Graphics (PNG), and Tagged Image File Format (TIFF).

Note that if the application passes WiaPreviewReturnOriginalImage into IWiaPreview::UpdatePreview, the WIA 2.0 Preview Component can support any image or pixel format.

IWiaPreview::UpdatePreview sets the WIA_DPS_PREVIEW property (and resets it before it returns, unless it was set before). This lets the driver (and hardware) as well as the image processing filter, know that the item is a preview scan.

An application must ensure that pChildWiaItem has the same image format (WIA_IPA_FORMAT) and resolution (WIA_IPS_XRES and WIA_IPS_YRES) as pWiaItem had when it was passed into IWiaPreview::GetNewPreview. The format of the child item must correspond to the format of the WIA 2.0 Preview Component's cached image (the WIA 2.0 Preview Component performs no image conversion).

Examples

UpdateRegion should be called each time a user changes, for example, the brightness or contrast for the child item represented by dwRegionNumber. This child item has previously been created by the segmentation filter (IWiaSegmentationFilter. The image written to the IStream is returned by the transfer callback interface's GetNextStream method. The code for GetSubRegionItem is omitted in this example.

After this function has been called, an application would typically redraw the region on the screen.

HRESULT
UpdateRegion(
   IN  DWORD dwRegionNumber)
{
   IWiaItem2 *pSubRegion = GetSubRegionItem(dwRegionNumber);

   return m_pWiaPreview->UpdatePreview(0,pSubRegion);
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Wia.h
IDL	Wia.idl

Share via