Update Vulkan docs

site/user/special/vulkan.md

-Building the Vulkan backend
-===========================
+Vulkan
+======
 
-Introduction
-------------
+Skis has a Vulkan implementation of its GPU backend. The Vulkan backend can be built alongside the OpenGL backend. The client can select between the OpenGL and Vulkan implementation at runtime. The Vulkan backend has reached feature parity with the OpenGL backend. At this time we find that many Vulkan drivers have bugs that Skia triggers for which we have no workaround. We are reporting bugs to vendors as we find them.
 
-The Vulkan backend is experimental and not built by default. It currently replaces the 'gpu' config in the dm tool rather than running in addition to OpenGL. Vulkan has been built on Windows and Linux.
+Build for Windows and Linux
+--------------------------------
+To build the Vulkan backend add skia_vulkan to your GYP_DEFINES:
 
-Details
--------
+<!--?prettify lang=sh?-->
+     export GYP_DEFINES="$GYP_DEFINES skia_vulkan=1"

[jvanverth1, 2016/09/06 14:09:00]

Don't we need skia_arch_width=64 skia_arch_type=x86_64 (on Windows and Linux)?

[bsalomon, 2016/09/06 14:27:47]

Do we only support vulkan for 64bit builds?

 
-Add `skia_vulkan=1` to your `GYP_DEFINES` environment variable. Ensure cmake is installed and in your path. On Windows install the prebuilt cmake from https://cmake.org/download/. The Vulkan SDK must also be installed.
+The Vulkan SDK must be installed and the VULKAN_SDK environment variable must point to the installation location.

[egdaniel, 2016/09/06 14:07:38]

Not sure if its worth saying, but windows will set VULKAN_SDK (and VK_SDK_PATH,
which was the old variable used for windows and what we check for) automatically
when you install the sdk. For linux you must manually set VULKAN_SDK

[bsalomon, 2016/09/06 14:27:47]

I'll add something about windows setting it up automatically and doing it
manually on linux. I'll put up a CL to update the windows build to use the new
variable before landing this.

 
-On Windows the 'msvs' gyp generator will not work. Use msvs-ninja for MSVS integration.
+Build as usual for your platform.
 
-Run:
 
-    python gyp_skia
+Build for Android
+----------------------
+The Vulkan backend will run on a device running the N release with Vulkan drivers. To build the Vulkan backend simply add --vulkan to the flags passed to ./platform_tools/android/bin/android_ninja
 
-and build Skia as usual.
+
+Using the Vulkan Backend
+------------------------
+
+To create a GrContext that is backend by Vulkan the client creates a Vulkan device and queue, initializes a GrVkBackendContext to describe the context, and then calls GrContext::Create:

[jvanverth1, 2016/09/06 14:09:00]

backend -> backed

[bsalomon, 2016/09/06 14:27:47]

Done.

+
+<!--?prettify lang=c++?-->
+    sk_sp<GrVkBackendContext> vkContext = new GrVkBackendContext;
+    vkBackendContext.fInstance = vkInstance;
+    vkBackendContext.fPhysicalDevice = vkPhysDevice;
+    ...
+    vkBackendContext.fInteface.reset(GrVkCreateInterface(instance, vkPhysDevice, extensionFlags);

[bsalomon, 2016/09/06 13:52:42]

Should/do we require the client to create this GrVkInterface? It seems like
everything passed in here is already on the GrVkBackendContext and we could just
as easily call GrVkCreateInterface.

[egdaniel, 2016/09/06 14:07:38]

I guess it is left like this so that it could be used in a command buffer type
thing where they want to have their own function pointers for the interface.

[jvanverth1, 2016/09/06 14:09:00]

fInterface.reset(). And I'm not sure on the need for creation, I'll check.

[bsalomon, 2016/09/06 14:27:47]

Fixed the spelling. I see Greg's point about custom bindings. But perhaps we
could say if this this null we'll call GrVkCreateInterface.

[jvanverth1, 2016/09/06 14:32:53]

The client is filling in the rest of the struct -- I don't think it's too much
to ask them to create the interface. And I'm not sure where we'd create it -- in
GrContext::Create? That seems like an odd side effect.

[bsalomon, 2016/09/06 16:01:52]

I was thinking we'd store a GrVkInterface pointer in GrVkGpu separately from
GrVkBackendContext. But I don't feel strongly about this. We can leave as is.

+    ...
+  
+    sk_sp<GrContext> context = GrContext::Create(kVulkan_GrBackend, (GrBackendContext) vkContext);
+
+When using the Vulkan backend the GrBackendObject field in GrBackendRenderTargetDesc and GrBackendTextureDesc is interpeted as a pointer to a GrVkImageInfo object. GrVkImage specifies a VkImage and associated state (tiling, layout, format, etc). This allows the client to import externally created Vulkan images as destinations for Skia rendering via SkSurface factory functions or for to composite Skia rendered content using SkImage::getTextureHandle().

[egdaniel, 2016/09/06 14:07:38]

GrVkImageInfo

[jvanverth1, 2016/09/06 14:09:00]

GrVkImageInfo specifies a VkImage [...]

[bsalomon, 2016/09/06 14:27:47]

Done.

+

[egdaniel, 2016/09/06 14:07:39]

Should we add the following to the doc or just leave it in the comments for the
code:

"When getting a GrVkImageInfo* via getTextureHandle() or
getRenderTargetHandle(), the client should check the fImageLayout field to know
what layout Skia left the VkImage in before using the VkImage. If the client
changes the layout of the VkImage, they should call
GrVkImageInfo::updateImageLayout(VkImageLayout layout) before issuing any future
commands to Skia with that VkImage."

[egdaniel, 2016/09/06 14:21:57]

Also should we add something along the lines of, "The client is responsible for
any synchronization or barriers needed before handing Skia an GrVkImageInfo.
Skia will assume it can start issues commands with the corresponding VkImage
without the need for adding additional synchronization at the start."

[bsalomon, 2016/09/06 14:27:47]

Done.