[meta][ll] Vulkan portability issues

[kvark]

Khronos - Vulkan Portability Initiative

Here is a rough list of areas where Vulkan translation to other next-gen APIs is not straightforward.
Related to #1226, #1241, and #1102
cc @msiglreith @JohnColanduoni

The following Vulkan pipeline states are not represented in D3D12 and Metal (see gpuweb/gpuweb#26 for detailed PSO comparison):

• VK_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN

Direct3D 12

• [ll] Descriptor heaps #1376: vkDescriptorPool can't be mapped to ID3D12DescriptorHeap, because only one of the latter can be active (for each type: samplers and non-samplers) at any given time during command encoding.
• Allocating heap memory for low level DX12 backend fails #1379: CreateHeap requires the resource type specified in advance on Tier-1 hardware, while vkAllocateMemory is typeless.
• [ll][d3d12] Buffer to Image copy alignment #1352: CopyTextureRegion from a source buffer requires minimum alignment of 0x100 for the rows and 0x200 for the depth slices, while Vulkan supports tight packing.
• vkCmdSetStencil* supports face selection, while OMSetStencilRef and stencil descriptors only support a single value for the reference and masks.
• vkCmdBlitImage unsupported, only 1:1 copying possible
• vkCmdClearColorImage/vkCmdClearDepthStencilImage: Only clearing via RenderTargetView/DepthStencilViews possible
• vkCmdFillBuffer: Only clearing via UAVs possible
• vkCmdUpdateBuffer: Unsupported, d3d12 only allows map/unmap and copying
• vkCmdResolveImage: ResolveSubresource doens't allow to specify offset+extent for subresources, only whole subresources can be resolved. Format compatibility needs to be enforced.
• Only one ID3D12GraphicsCommandList can be recorded at same time for each ID3D12CommandAllocator
  (source: https://msdn.microsoft.com/en-us/library/windows/desktop/dn899205(v=vs.85).aspx#recording_command_lists)
• Format on SRV creation can only differ in ChannelType but not SurfaceType
• Only mapping of Resources is allowed, but not directly the underlying memory

Metal

• no sample mask
• [ll] Metal heaps and offsets/aliasing #1384: Metal heaps do not give us much control over allocations, other than specifying what heap to make the allocation within.
• vkCmdClearColorImage/vkCmdClearDepthStencilImage: Clearing seems to be only possible via renderpasses. Potential issue with clearing multiple subregions.
• vkCmdUpdateBuffer: Unsupported
• Fix copying images of different formats on Metal #2026: vkCmdCopyImage doesn't work with non-equal but compatible formats
• Support mipmapped 1D images on Metal #2050: 1D textures can't have mipmaps
• Support vertex attribute offsets higher than the strides in Metal #2054: vertex attributes can't have offset exceeding the stride
• Metal vertex buffer stride #2077: vertex buffer stride has to be a multiple of 4

TODO

Sort the remaining of #1241:

• swapchain only support incremental updates for frames
• pipeline barriers?
  • currently leaning towards explicitly set resource states (dx12), layouts(vk) and access masks(vk)

Suggested new feature flags

• triangle fans
• separate stencil references for front/back
• events

[JohnColanduoni]

The SwapChain implementation I wrote uses an API that is considered private by Apple on iOS prior to the upcoming iOS 11. If we want to support Metal 1 on iOS that's another sticking point.

[msiglreith]

Events will probably be hard to implement for both APIs, requiring to split command buffers.

[kvark]

I think we should migrate all the points from #1241 here, describe them in great detail, and close the other issue as a duplicate.

[Kangz]

Not sure if this is the right place to share some of our findings so let me know if I should move this.

• vkQueueWaitIdle that can be translated to D3D12 by adding a Signal to a queue, linking it to an Event object and waiting on the event. In Metal you can have a callback when a command buffer finishes executing, and have that trigger a condition variable. glFinish for OpenGL.
• The placed footprint in D3D12 force an alignment of 512 for the offset from the start of the buffer. We have found that it is possible to work around this by sometimes doing two copies instead of one (for 2D textures).

[kvark]

@Kangz Thanks for chiming in! I split your comment into corresponding issues (#1383 and #1352). I'd prefer to leave this space for more general concerns.

[msiglreith]

Issues (Portability API)

Aspects where vulkan portability is not straightforward. In particular, hard to map towards D3D12, which exposes a smaller and more restricted API surface:

Memory mapping

Summary: Vulkan allows to map arbitrary slices of Heap/DeviceMemory. in other APIs mapping is coupled with (sub)resources.

Vulkan

• Allocate Heap/DeviceMemory via AllocateMemory, which can be bound to Buffer or Image.
• Map/Unmap DeviceMemory via (Un)MapBuffer to read/write data to buffers or images.
• DeviceMemory can be only mapped once until it's unmapped again.

D3D12

• Allocate memory in heaps and create placed resources inside the heaps, similar to vulkan
• ID3D12Resource::Map to map the underlying memory of a resource.
• Nested mapping calls are allowed.

Metal

(Metal uses contents for mapping MTLBuffer afaik, whicb basically maps the whole buffer.)

API Design

We currently follow D3D12 in core by mapping Buffers instead of directly memory, which is a clear restriction compared to vulkans model.

Resource views

Summary:

• Differ between type of the underlying resource (buffer/view) and usage (SRV/CBV/UAV/..).
• Restrictions in compatible formats for views

Vulkan

• Vulkan differs between BufferViews and ImageViews.
• Additional flag required to create views with different (compatible) format
• Compatible format must only match pixel size but can differ in SurfaceType and ChannelType(+ some restrictions for depth-stencil formats)

D3D12

• Differ between usage of the views but not in resource type: SRV, CBV (new!), UAV, RTV and DSV
• Views can only differ in ChannelType but not in SurfaceType, SurfaceType can only be changed for UAVs

Metal

• No real views, but allows to create MTLTexture with shared memory
• Format must only match in pixel size

API Design

We currently follow D3D12 in core by exposing SRV/CBV/UAV/RTV/DSV and use enums on Vulkan.