Add DrawingImage.Viewbox

[TomEdwardsEnscape]

This is a new property which gets or sets a rectangular region of Drawing, in device independent pixels, to display when rendering the image.

The value can be used to display only part of Drawing, or to surround it with empty space. If null, Drawing will provide its own frame, the same as before.

What is the current behavior?

The drawing is framed with a tight bounding box defined by a union of the bounds of each component of the drawing. Expanding the frame requires adding invisible drawing elements. It's not possible to reduce the size of the frame, only to crop the rasterised output later.

What is the updated/expected behavior with this PR?

The following XAML (which is the test case of #18871, plus Viewbox and a border) now produces the pictured output. The arc in the drawing is framed with enough space for the entire circle, because a frame starting at 0,0 has been defined.

<Border BorderBrush="Green" BorderThickness="2" VerticalAlignment="Center" HorizontalAlignment="Center">
  <Image>
    <DrawingImage Viewbox="0 0 32 32">
      <GeometryDrawing>
        <GeometryDrawing.Pen>
          <Pen Brush="Black" LineJoin="Miter" Thickness="2.0"/>
        </GeometryDrawing.Pen>
        <GeometryDrawing.Geometry>
          <PathGeometry Figures="M 31.082 16 A 15.082 15.0815 0 0 1 25.8947 27.3822" FillRule="NonZero" />
        </GeometryDrawing.Geometry>
      </GeometryDrawing>
    </DrawingImage>
  </Image>
</Border>

How was the solution implemented (if it's not obvious)?

At first I added the property to GeometryGroup per the bug reports, but then I realised that if I used DrawingGroup to add an image to the drawing, the geometry began to draw at the intended position. The problem was higher up the tree, with DrawingImage itself, which automatically crops the image to the bounds of the drawing. It still does, but now you can override those bounds and have them start and end wherever you like.

I wanted to use the equivalent SVG attribute name for the property, but unfortunately ViewBox is already the name of an Avalonia control. I also decided against "bounds", because the frame is explicitly NOT the bounds of the drawing. That name is also already in use with Visual.Bounds, a read-only property, which could become a source of confusion. Viewbox is now used at the request of the Avalonia team.

Breaking changes

None.

Obsoletions / Deprecations

None.

Fixed issues

Fixes #18871
Fixes #18512

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0056671-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0060277-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[MrJul]

Notes from the API review: rename Frame to Viewbox.
Also, unrelated to the API itself, please add one or two render tests, plus a test with the drawing as the source of a DrawingBrush.

[TomEdwardsEnscape]

I wasn't able to extend the feature to brushes. I can clip and translate the output, but this doesn't alter tiling. It looks like doing so would require low-level changes to the rendering system.

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0061183-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[MrJul]

LGTM, thank you!