Removed INativeWindowPlatformSurface and added some docs

src/Avalonia.Controls/Avalonia.Controls.csproj

@@ -59,7 +59,6 @@
     <Compile Include="IScrollable.cs" />
     <Compile Include="Platform\Surfaces\IFramebufferPlatformSurface.cs" />
     <Compile Include="Platform\Surfaces\ILockedFramebuffer.cs" />
-    <Compile Include="Platform\Surfaces\INativeWindowPlatformSurface.cs" />
     <Compile Include="Platform\Surfaces\PixelFormat.cs" />
     <Compile Include="PointEventArgs.cs" />
     <Compile Include="Embedding\EmbeddableControlRoot.cs" />

src/Avalonia.Controls/Platform/ITopLevelImpl.cs

@@ -39,8 +39,15 @@ namespace Avalonia.Platform
         IPlatformHandle Handle { get; }
 
         /// <summary>
-        /// Supported methods of image output
+        /// The list of native platform's surfaces that can be consumed by rendering subsystems.
-        /// </summary>
+        /// </summary>
+        /// <remarks>
+        /// Rendering platform will check that list and see if it can utilize one of them to output.
+        /// It should be enough to expose a native window handle via IPlatformHandle
+        /// and add support for framebuffer (even if it's emulated one) via IFramebufferPlatformSurface.
+        /// If you have some rendering platform that's tied to your particular windowing platform,
+        /// just expose some toolkit-specific object (e. g. Func&lt;Gdk.Drawable&gt; in case of GTK#+Cairo)
+        /// </remarks>
         IEnumerable<object> Surfaces { get; }
 
         /// <summary>

src/Avalonia.Controls/Platform/Surfaces/IFramebufferPlatformSurface.cs

@@ -8,6 +8,12 @@ namespace Avalonia.Controls.Platform.Surfaces
 {
     public interface IFramebufferPlatformSurface
     {
+        /// <summary>
+        /// Provides a framebuffer descriptor for drawing.
+        /// </summary>
+        /// <remarks>
+        /// Contents should be drawn on actual window after disposing
+        /// </remarks>
         ILockedFramebuffer Lock();
     }
 }

src/Avalonia.Controls/Platform/Surfaces/ILockedFramebuffer.cs

@@ -8,11 +8,29 @@ namespace Avalonia.Controls.Platform.Surfaces
 {
     public interface ILockedFramebuffer : IDisposable
     {
+        /// <summary>
+        /// Address of the first pixel
+        /// </summary>
         IntPtr Address { get; }
+        /// <summary>
+        /// Framebuffer width
+        /// </summary>
         int Width { get; }
+        /// <summary>
+        /// Framebuffer height
+        /// </summary>
         int Height { get; }
+        /// <summary>
+        /// Number of bytes per row
+        /// </summary>
         int RowBytes { get; }
+        /// <summary>
+        /// DPI of underling screen
+        /// </summary>
         Size Dpi { get; }
+        /// <summary>
+        /// Pixel format
+        /// </summary>
         PixelFormat Format { get; }
     }
 }

src/Avalonia.Controls/Platform/Surfaces/INativeWindowPlatformSurface.cs

@@ -1,23 +0,0 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace Avalonia.Controls.Platform.Surfaces
-{
-    public interface INativeWindowPlatformSurface
-    {
-        IntPtr Handle { get; }
-    }
-
-    public class NativeWindowPlatformSurface : INativeWindowPlatformSurface
-    {
-        public NativeWindowPlatformSurface(IntPtr handle)
-        {
-            Handle = handle;
-        }
-
-        public IntPtr Handle { get; }
-    }
-}

src/Avalonia.Visuals/Platform/IPlatformRenderInterface.cs

@@ -41,7 +41,7 @@ namespace Avalonia.Platform
         /// <summary>
         /// Creates a renderer.
         /// </summary>
-        /// <param name="surfaces">The list of surfaces that can be used for output.</param>
+        /// <param name="surfaces">The list of native platform's surfaces that can be used for output.</param>
         /// <returns>An <see cref="IRenderTarget"/>.</returns>
         IRenderTarget CreateRenderTarget(IEnumerable<object> surfaces);
 

src/Gtk/Avalonia.Gtk/WindowImplBase.cs

@@ -322,24 +322,9 @@ namespace Avalonia.Gtk
             _window = null;
         }
 
-
-        //We need that for DrawingArea which does not have an HWND until parent window is realized
-        //and could also *change* it's HWND
-        class DynamicNativeWindowSurface : INativeWindowPlatformSurface
-        {
-            private readonly IPlatformHandle _handle;
-
-            public DynamicNativeWindowSurface(IPlatformHandle handle)
-            {
-                _handle = handle;
-            }
-
-            public IntPtr Handle => _handle.Handle;
-        }
-
         public IEnumerable<object> Surfaces => new object[]
         {
-            new DynamicNativeWindowSurface(Handle), 
+            Handle, 
             new Func<Gdk.Drawable>(() => CurrentDrawable),
             _framebuffer
         };

src/Skia/Avalonia.Skia.Android/AndroidPlatformRenderInterface.cs

@@ -19,7 +19,7 @@ namespace Avalonia.Skia
         {
             var surfaceView = surfaces?.OfType<SurfaceView>().FirstOrDefault();
             if (surfaceView == null)
-                throw new ArgumentException("Avalonia.Skia.Android is only capable to draw on SurfaceView");
+                throw new ArgumentException("Avalonia.Skia.Android is only capable of drawing on SurfaceView");
             return new WindowRenderTarget(surfaceView);
         }
     }

src/Windows/Avalonia.Direct2D1/Direct2D1Platform.cs

@@ -104,10 +104,11 @@ namespace Avalonia.Direct2D1
 
         public IRenderTarget CreateRenderTarget(IEnumerable<object> surfaces)
         {
-            var nativeWindow = surfaces?.OfType<INativeWindowPlatformSurface>().FirstOrDefault();
+            var nativeWindow = surfaces?.OfType<IPlatformHandle>().FirstOrDefault();
-
             if (nativeWindow != null)
             {
+                if(nativeWindow.HandleDescriptor != "HWND")
+                    throw new NotSupportedException("Don't know how to create a Direct2D1 renderer from " + nativeWindow.HandleDescriptor);
                 return new HwndRenderTarget(nativeWindow);
             }
             throw new NotSupportedException("Don't know how to create a Direct2D1 renderer from any of provided surfaces");

src/Windows/Avalonia.Direct2D1/HwndRenderTarget.cs

@@ -4,6 +4,7 @@ using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
 using Avalonia.Controls.Platform.Surfaces;
+using Avalonia.Platform;
 using Avalonia.Win32.Interop;
 using SharpDX;
 using SharpDX.DXGI;
@@ -12,9 +13,9 @@ namespace Avalonia.Direct2D1
 {
     class HwndRenderTarget : SwapChainRenderTarget
     {
-        private readonly INativeWindowPlatformSurface _window;
+        private readonly IPlatformHandle _window;
 
-        public HwndRenderTarget(INativeWindowPlatformSurface window)
+        public HwndRenderTarget(IPlatformHandle window)
         {
             _window = window;
         }

src/Windows/Avalonia.Win32/WindowImpl.cs

@@ -767,7 +767,7 @@ namespace Avalonia.Win32
 
         public IEnumerable<object> Surfaces => new object[]
         {
-            new NativeWindowPlatformSurface(_hwnd), _framebuffer 
+            Handle, _framebuffer 
         };
     }
 }