[Breaking change]: Graphics.GetContextInfo() is obsolete and marked as Windows only.

[safern]

Description

Graphics.GetContextInfo() is a very costly API, so instead we added 2 GetContextInfo() overrides:

https://docs.microsoft.com/dotnet/api/system.drawing.graphics.getcontextinfo?view=dotnet-plat-ext-6.0#System_Drawing_Graphics_GetContextInfo_System_Drawing_PointF__
https://docs.microsoft.com/dotnet/api/system.drawing.graphics.getcontextinfo?view=dotnet-plat-ext-6.0#System_Drawing_Graphics_GetContextInfo_System_Drawing_PointF__System_Drawing_Region__

These new overrides calculate just the information needed based on what was requested by the caller depending on the override used, making it lower in allocations and time. Also, instead of returning an object (that represents an array of object containing the data) we are returning the structs needed to represent this data, making it easier for the consumer to access that data.

Version

6.0.0-preview4

Version

Other (please put exact version in description textbox)

Previous behavior

No warnings when compiling.

New behavior

When compiling on Windows:

warning SYSLIB0016: 'Graphics.GetContextInfo()' is obsolete: 'Use the Graphics.GetContextInfo overloads that accept arguments for better performance and fewer allocations.'

When compiling on non-Windows:

warning CA1416: This call site is reachable on all platforms. 'Graphics.GetContextInfo()' is only supported on: 'windows'.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

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.

Recommended action

Use the overload that is most appropriate for the scenario from the new overloads replacing the obsolete API.

Feature area

Extensions

Affected APIs

• System.Drawing.Graphics.GetContextInfo()

[gewarren]

@safern Between these two breaking change articles, I think we can consider this to be documented already:

• https://docs.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/6.0/system-drawing-common-windows-only
• https://docs.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/6.0/obsolete-apis-with-custom-diagnostics

[safern]

Thanks @gewarren didn't know we had an entry for the obsoleted type 😄