[AppKit] Make NSGraphics.NSBestDepth P/Invoke blittable. (#19614)

Also introduce a few other improvements:

* Add an varation that takes an 'out bool' instead of a 'ref bool'. According
  to the documentation the value is out-only.
* Name this variation according to our guidelines (with a verb).
* Deprecate the old version.

Contributes towards #15684.

Author: rolfbjarne

src/AppKit/NSGraphics.cs

@@ -24,6 +24,7 @@
 #if !__MACCATALYST__
 
 using System;
+using System.ComponentModel;
 using System.Runtime.InteropServices;
 
 using ObjCRuntime;
@@ -47,14 +48,38 @@ public static class NSGraphics {
 		public static readonly float DarkGray = (float) 1 / 3.0f;
 
 		[DllImport (Constants.AppKitLibrary)]
-		extern static NSWindowDepth NSBestDepth (IntPtr colorspaceHandle, nint bitsPerSample, nint bitsPerPixel, [MarshalAs (UnmanagedType.I1)] bool planar, [MarshalAs (UnmanagedType.I1)] ref bool exactMatch);
+		extern unsafe static NSWindowDepth NSBestDepth (IntPtr colorspaceHandle, nint bitsPerSample, nint bitsPerPixel, byte planar, byte* exactMatch);
 
-		public static NSWindowDepth BestDepth (NSString colorspace, nint bitsPerSample, nint bitsPerPixel, [MarshalAs (UnmanagedType.I1)] bool planar, [MarshalAs (UnmanagedType.I1)] ref bool exactMatch)
+#if !XAMCORE_5_0
+		[EditorBrowsable (EditorBrowsableState.Never)]
+		[Obsolete ("Call 'GetBestDepth' instead.")]
+		public static NSWindowDepth BestDepth (NSString colorspace, nint bitsPerSample, nint bitsPerPixel, bool planar, ref bool exactMatch)
 		{
 			if (colorspace is null)
-				throw new ArgumentNullException ("colorspace");
+				throw new ArgumentNullException (nameof (colorspace));
 
-			return NSBestDepth (colorspace.Handle, bitsPerSample, bitsPerPixel, planar, ref exactMatch);
+			var exactMatchValue = (byte) (exactMatch ? 1 : 0);
+			NSWindowDepth rv;
+			unsafe {
+				rv = NSBestDepth (colorspace.Handle, bitsPerSample, bitsPerPixel, (byte) (planar ? 1 : 0), &exactMatchValue);
+			}
+			exactMatch = exactMatchValue != 0;
+			return rv;
+		}
+#endif
+
+		public static NSWindowDepth GetBestDepth (NSString colorspace, nint bitsPerSample, nint bitsPerPixel, bool planar, out bool exactMatch)
+		{
+			if (colorspace is null)
+				throw new ArgumentNullException (nameof (colorspace));
+
+			byte exactMatchValue = 0;
+			NSWindowDepth rv;
+			unsafe {
+				rv = NSBestDepth (colorspace.Handle, bitsPerSample, bitsPerPixel, (byte) (planar ? 1 : 0), &exactMatchValue);
+			}
+			exactMatch = exactMatchValue != 0;
+			return rv;
 		}
 
 		[DllImport (Constants.AppKitLibrary)]

tests/cecil-tests/BlittablePInvokes.KnownFailures.cs

@@ -17,7 +17,6 @@
 namespace Cecil.Tests {
 	public partial class BlittablePInvokes {
 		static HashSet<string> knownFailuresPInvokes = new HashSet<string> {
-			"AppKit.NSWindowDepth AppKit.NSGraphics::NSBestDepth(System.IntPtr,System.IntPtr,System.IntPtr,System.Boolean,System.Boolean&)",
 			"AudioToolbox.AudioConverterError AudioToolbox.AudioConverter::AudioConverterGetPropertyInfo(System.IntPtr,AudioToolbox.AudioConverterPropertyID,System.Int32&,System.Boolean&)",
 			"AudioToolbox.AudioFileError AudioToolbox.AudioFile::AudioFileWritePackets(System.IntPtr,System.Boolean,System.Int32,AudioToolbox.AudioStreamPacketDescription[],System.Int64,System.Int32&,System.IntPtr)",
 			"AudioToolbox.AudioFileStreamStatus AudioToolbox.AudioFileStream::AudioFileStreamGetPropertyInfo(System.IntPtr,AudioToolbox.AudioFileStreamProperty,System.Int32&,System.Boolean&)",

tests/monotouch-test/AppKit/NSGraphics.cs

@@ -0,0 +1,34 @@
+#if __MACOS__
+using System;
+using System.Threading.Tasks;
+using NUnit.Framework;
+
+using AppKit;
+using Foundation;
+
+namespace Xamarin.Mac.Tests {
+	[TestFixture]
+	[Preserve (AllMembers = true)]
+	public class NSGraphicsTest {
+#if !XAMCORE_5_0
+		[Test]
+		public void BestDepth ()
+		{
+			bool exactMatch = false;
+			var rv = NSGraphics.BestDepth (NSColorSpace.DeviceRGB, 8, 8, false, ref exactMatch);
+			Assert.AreEqual (NSWindowDepth.TwentyfourBitRgb, rv, "BestDepth");
+			Assert.IsTrue (exactMatch, "ExactMatch");
+		}
+#endif
+
+		[Test]
+		public void GetBestDepth ()
+		{
+			var rv = NSGraphics.GetBestDepth (NSColorSpace.DeviceRGB, 8, 8, false, out var exactMatch);
+			Assert.AreEqual (NSWindowDepth.TwentyfourBitRgb, rv, "GetBestDepth");
+			Assert.IsTrue (exactMatch, "ExactMatch");
+		}
+	}
+}
+
+#endif // __MACOS__