IWiaImageFilter interface
The IWiaImageFilter interface is an extension interface implemented by image processing filter developers and called by Windows Image Acquisition (WIA) 2.0.
Members
The IWiaImageFilter interface inherits from the IUnknown interface. IWiaImageFilter also has these types of members:
Methods
The IWiaImageFilter interface has these methods.
| Method | Description |
|---|---|
| ApplyProperties | Enables the image processing filter to write properties back to the driver (and device). |
| FilterPreviewImage | Filters the preview image. |
| InitializeFilter | Initializes the filter. Called by WIA 2.0 before each image download. |
| SetNewCallback | Sets a new application callback for the image processing filter to use for forwarding calls. |
Remarks
Image processing filter developers should implement this interface and the IWiaTransferCallback interface.
WIA 2.0 calls filter methods. They are never called directly from an application.
Microsoft supplies the WIA 2.0 Preview Component, which caches the original, unfiltered preview image that is acquired from the scanner. An application uses CoCreateInstance to co-create an instance of the WIA 2.0 Preview Component (CLSID_WiaPreview), which loads the filter using IWiaItem2::GetExtension. The filter is called automatically when the application calls IWiaTransfer::Download.
The image processing filter is always executed when an image is scanned. An application cannot acquire an image from the scanner without having the imaging filter applied first.
A filter must implement brightness and contrast at a minimum. The common UI, which provides brightness and contrast controls to the user, can display accurate previews to the user.
An image processing filter should never modify the lMessage member of the WiaTransferParams structure.
To read the required properties the image processing filter should call IWiaPropertyStorage::GetPropertyStream on the IWiaPropertyStorage interface that it gets from the item by calling IWiaImageFilter::QueryInterface. The filter can then instantiate an IPropertyStorage instance on this stream to read the items properties. The image processing filter should not call IWiaPropertyStorage::ReadMultiple directly because this method calls into the driver's drvReadItemProperties, but the WIA 2.0 service has already locked the driver in the drvAcquireItemData call so this call will timeout and fail.
The properties that the filter is interested in could for example be the brightness and contrast settings. The filter typically also needs to read the image format as well as the preview property, WIA_DPS_PREVIEW, from pWiaItem2. These properties are all used in the filtering process.
The WIA 2.0 components always writes unfiltered data into the image processing filter. The image processing algorithm implemented by the filter's stream can filter the data more than once and does not have to be concerned with producing the same results as filtering the data once.
The filter must pay attention to the WIA_DPS_PREVIEW property, especially if some filter related tasks are handled in hardware. For example, a certain driver can change the brightness of the lamp in the scanner hardware depending on how the application has set the brightness into a WIA 2.0 item. During the final scan (when the application calls IWiaTransfer::Download) the driver would typically modify the physical lamp of the scanner. In this case the image processing filter may not have to perform any brightness processing at all. During a preview scan, however, the driver should not modify the brightness of the lamp—instead this should be taken care of solely in the image processing filter. It is important that the WIA 2.0 Preview Component and the image processing filter return accurate images based on the properties set into the item.
An image processing filter must support all image formats that the driver supports.
The image processing filter is always given an image corresponding to the selection area set into the item for which we are acquiring the image. Note, however, that the image may have been rotated by the driver in case it supports the WIA_IPS_ROTATION property.
The image processing filter is created through IWiaItem2::GetExtension, typically not by the application but by WIA 2.0 components when an application calls IWiaPreview::GetNewPreview or IWiaTransfer::Download.
The IWiaImageFilter interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods.
| IUnknown Methods | Description |
|---|---|
| IUnknown::QueryInterface | Returns pointers to supported interfaces. |
| IUnknown::AddRef | Increments reference count. |
| IUnknown::Release | Decrements reference count. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows Vista [desktop apps only] |
| Minimum supported server |
Windows Server 2008 [desktop apps only] |
| Header |
|
| IDL |
|
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for