Click or drag to resize
DpiCompensationEffect Class
[NoComposition] Scales a bitmap to match a different DPI. This is usually handled automatically, but DpiCompensationEffect can also be used directly if you want to customize the compensation behavior.
Inheritance Hierarchy
SystemObject
  Microsoft.Graphics.Canvas.EffectsDpiCompensationEffect

Namespace:  Microsoft.Graphics.Canvas.Effects
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
Copy
public sealed class DpiCompensationEffect : ICanvasEffect, 
	IGraphicsEffect, IGraphicsEffectSource, ICanvasImage, IDisposable

The DpiCompensationEffect type exposes the following members.

Constructors
  NameDescription
Public methodDpiCompensationEffect
Initializes a new instance of the DpiCompensationEffect class.
Top
Properties
  NameDescription
Public propertyBorderMode
Border mode for edge pixels. Default value Soft.
Public propertyBufferPrecision
Specifies what precision to use for intermediate buffers when drawing this effect.
Public propertyCacheOutput
Enables caching the output from drawing this effect.
Public propertyInterpolationMode
Interpolation mode. Default value Linear.
Public propertyName
Attaches a user-defined name string to the effect.
Public propertySource
Gets or sets the input source for DpiCompensation effect.
Public propertySourceDpi
Specifies the new DPI. Default value (96, 96).
Top
Methods
  NameDescription
Public methodDispose
Releases all resources used by the effect.
Public methodGetBounds(ICanvasResourceCreator)
Retrieves the bounds of this DpiCompensationEffect.
Public methodGetBounds(ICanvasResourceCreator, Matrix3x2)
Retrieves the bounds of this DpiCompensationEffect.
Public methodGetInvalidRectangles
Queries what regions of the effect output have changed since it was last drawn.
Public methodCode exampleGetRequiredSourceRectangle
Queries what part of an effect source image is needed to draw an output region.
Public methodGetRequiredSourceRectangles
Queries what parts of the effect source images are needed to draw an output region.
Public methodInvalidateSourceRectangle
Notifies the effect that one of its source images has changed.
Top
Remarks

Supported by Win2D but not Windows.UI.Composition.

When a bitmap of different DPI than the target drawing session is used as an effect source image, an internal DpiCompensationEffect is automatically inserted in between the bitmap and the effect. This scales the bitmap to match the target DPI, which is usually what you want.

In a few cases, this automatic DPI scaling may not be desirable. For example, consider a 96 DPI bitmap which as part of an effect graph is being scaled up 16x using nearest neighbor image interpolation. The intent is to produce a crisply pixelated output, but if this app is run on a 144 DPI display, first the automatically inserted DpiCompensationEffect will scale up the image by a factor of 1.5 (to adjust for 144/96 DPI). This compensation uses linear interpolation, after which the 16x scale will be fed an undesirably blurry source image.

In situations like this, automatic DPI compensation can be overridden by inserting your own instance of DpiCompensationEffect in between the bitmap and the rest of the effect graph. There are two possible approaches:

  1. Set DpiCompensationEffect.SourceDpi to match the DPI of your bitmap, which will exactly reproduce the automatic default compensation behavior. Then adjust other properties of the DpiCompensationEffect (eg. InterpolationMode or BorderMode) to suit your needs.
  2. Alternatively, set DpiCompensationEffect.SourceDpi to match the DPI of the target drawing session. This will disable DPI compensation entirely, which means your bitmap will appear the wrong size if its DPI is not the same as the target. You must therefore explicitly include a DPI scaling factor (targetDPI/sourceDPI) at a suitable point in your effect graph.

This Windows Runtime type corresponds to the D2D DPI compensation effect.

See Also