API Proposal: More performant overloads for Graphics.GetContextInfo

[JeremyKuhne]

Background and Motivation

Graphics.GetContextInfo exists to allow WinForms to apply cumulative Graphics transform translation and clipping to the underlying HDC so that rendering via GDI has similar output. This method currently returns an object array of [ Region, Matrix ]. (Note that the Matrix is the current Transform with only the cumulative offset applied.)

This API is called many times during rendering of WinForms applications. Avoiding the array allocation would make a significant difference in rendering allocations. A much greater allocation reduction would be obtained if Graphics tracked if the .Clip and .Transform setters are ever accessed to allow an early out in the method logic.

WinForms also don't always need both values. System.Drawing can't calculate the clipping region without the offset, but it can calculate the offset without the Region. Making the Region optional will save significant overhead.

In .NET 5.0 we added a lot of logic to WinForms to try and track and avoid getting this data. Tracking the "dirty" state in System.Drawing covers far more scenarios and allows significantly simpler code in WinForms.

Proposed API

namespace System.Drawing
{
    public sealed class Graphics
    {
         public object GetContextInfo();
+        public void GetContextInfo(out PointF offset);
+        public void GetContextInfo(out PointF offset, out Region clip);
    }
}

• out Region clip would return null when Clip and Transform have never been set.
• out Region clip would return null if the cumulative region ends up .IsInfinite() (meaningless)
• out Point offset will return an empty (default) PointF when Transform has never been set.
• existing GetContextInfo behavior won't change for compat

Usage Examples

The existing method is used in WinForms here.

Risks

If we missed a case where early out is inappropriate we'd have to adjust for that, but that is an internal detail.

More Details

• GDI+ "layers" its clip and transform on top of the underlying GDI HDC. So a newly created Graphics object always has an infinite clip and identity matrix.
• Restriction to translation in the Matrix is probably due to lack of Win9x support for rotation (not positive).

cc: @RussKie @merriemcgaw

Tagging subscribers to this area: @safern, @tannergooding
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

Graphics.GetContextInfo exists to allow WinForms to apply cumulative Graphics transform translation and clipping to the underlying HDC so that rendering via GDI has similar output. This method currently returns an object array of [ Region, Matrix ].

This API is called many times during rendering of WinForms applications. Avoiding the array allocation would make a significant difference in rendering allocations. A much greater allocation reduction would be obtained if Graphics tracked if the .Clip and .Transform setters are ever accessed to allow an early out in the method logic.

WinForms also don't always need both values. System.Drawing can't calculate the clipping region without the offset, but it can calculate the offset without the Region. Making the Region optional will save significant overhead.

In .NET 5.0 we added a lot of logic to WinForms to try and track and avoid getting this data. Tracking the "dirty" state in System.Drawing covers far more scenarios and allows significantly simpler code in WinForms.

Proposed API

namespace System.Drawing
{
    public sealed class Graphics
    {
         public object GetContextInfo();
+        public void GetContextInfo(out Point offset);
+        public void GetContextInfo(out Point offset, out Region clip);
    }
}

• out Region clip would return null when Clip and Transform have never been set.
• out Region clip would return null if the cumulative region ends up .IsInfinite() (meaningless)
• out Point offset will return an empty (default) Point when Transform has never been set.
• existing GetContextInfo behavior won't change for compat

Usage Examples

The existing method is used in WinForms here.

Risks

No known risks.

cc: @RussKie @merriemcgaw

Author:	JeremyKuhne
Assignees:	-
Labels:	api-suggestion, area-System.Drawing, tenet-performance
Milestone:	6.0.0

[safern]

We've previously discussed this offline and makes sense, the current GetContextInfo is pretty expensive.

[tannergooding]

Is returning via out preferred to returning a value tuple here?

[safern]

Is returning via out preferred to returning a value tuple here?

You mean an out value tuple? We wouldn't be able to add a parameter-less overload that returns a value tuple as that conflicts with the existing override.

[tannergooding]

You mean an out value tuple? We wouldn't be able to add a parameter-less overload that returns a value tuple as that conflicts with the existing override.

Right, although I imagine we could also something like:

• have a different overload
• have something like T GetContextInfo<T>() where T : struct and then specialize based on what info we need
• have explicit Point GetContextOffset and Region GetContextClip

I think the most interesting thing here is that GetContextInfo returned object so that we could have public surface area while also having that info be "opaque".
Having these new methods means that the context info is no longer opaque and so it might be worth exposing that info slightly differently or via a proper struct if we expect it might change in the future.

[safern]

I think I like that idea better and might be more extensible.

@JeremyKuhne thoughts?