[Mesa-dev] [PATCH 1/5] gallium/docs: remove out-of-date document about D3D11 features

[Brian Paul]

Series LGTM.  Reviewed-by: Brian Paul <brianp at vmware.com>

On 06/26/2015 12:22 PM, Marek Olšák wrote:
> From: Marek Olšák <marek.olsak at amd.com>
>
> ---
>   src/gallium/docs/d3d11ddi.txt | 462 ------------------------------------------
>   1 file changed, 462 deletions(-)
>   delete mode 100644 src/gallium/docs/d3d11ddi.txt
>
> diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt
> deleted file mode 100644
> index a703648..0000000
> --- a/src/gallium/docs/d3d11ddi.txt
> +++ /dev/null
> @@ -1,462 +0,0 @@
> -This document compares the D3D10/D3D11 device driver interface with Gallium.
> -It is written from the perspective of a developer implementing a D3D10/D3D11 driver as a Gallium state tracker.
> -
> -Note that naming and other cosmetic differences are not noted, since they don't really matter and would severely clutter the document.
> -Gallium/OpenGL terminology is used in preference to D3D terminology.
> -
> -NOTE: this document tries to be complete but most likely isn't fully complete and also not fully correct: please submit patches if you spot anything incorrect
> -
> -Also note that this is specifically for the DirectX 10/11 Windows Vista/7 DDI interfaces.
> -DirectX 9 has both user-mode (for Vista) and kernel mode (pre-Vista) interfaces, but they are significantly different from Gallium due to the presence of a lot of fixed function functionality.
> -
> -The user-visible DirectX 10/11 interfaces are distinct from the kernel DDI, but they match very closely.
> -
> -* Accessing Microsoft documentation
> -
> -See http://msdn.microsoft.com/en-us/library/dd445501.aspx ("D3D11DDI_DEVICEFUNCS") for D3D documentation.
> -
> -Also see http://download.microsoft.com/download/f/2/d/f2d5ee2c-b7ba-4cd0-9686-b6508b5479a1/direct3d10_web.pdf ("The Direct3D 10 System" by David Blythe) for an introduction to Direct3D 10 and the rationale for its design.
> -
> -The Windows Driver Kit contains the actual headers, as well as shader bytecode documentation.
> -
> -To get the headers from Linux, run the following, in a dedicated directory:
> -wget http://download.microsoft.com/download/4/A/2/4A25C7D5-EFBE-4182-B6A9-AE6850409A78/GRMWDK_EN_7600_1.ISO
> -sudo mount -o loop GRMWDK_EN_7600_1.ISO /mnt/tmp
> -cabextract -x /mnt/tmp/wdk/headers_cab001.cab
> -rename 's/^_(.*)_[0-9]*$/$1/' *
> -sudo umount /mnt/tmp
> -
> -d3d10umddi.h contains the DDI interface analyzed in this document: note that it is much easier to read this online on MSDN.
> -d3d{10,11}TokenizedProgramFormat.hpp contains the shader bytecode definitions: this is not available on MSDN.
> -d3d9types.h contains DX9 shader bytecode, and DX9 types
> -d3dumddi.h contains the DirectX 9 DDI interface
> -
> -* Glossary
> -
> -BC1: DXT1
> -BC2: DXT3
> -BC3: DXT5
> -BC5: RGTC1
> -BC6H: BPTC float
> -BC7: BPTC
> -CS = compute shader: OpenCL-like shader
> -DS = domain shader: tessellation evaluation shader
> -HS = hull shader: tessellation control shader
> -IA = input assembler: primitive assembly
> -Input layout: vertex elements
> -OM = output merger: blender
> -PS = pixel shader: fragment shader
> -Primitive topology: primitive type
> -Resource: buffer or texture
> -Shader resource (view): sampler view
> -SO = stream out: transform feedback
> -Unordered access view: view supporting random read/write access (usually from compute shaders)
> -
> -* Legend
> -
> --: features D3D11 has and Gallium lacks
> -+: features Gallium has and D3D11 lacks
> -!: differences between D3D11 and Gallium
> -*: possible improvements to Gallium
> ->: references to comparisons of special enumerations
> -#: comment
> -
> -* Gallium functions with no direct D3D10/D3D11 equivalent
> -
> -clear
> -	+ Gallium supports clearing both render targets and depth/stencil with a single call
> -
> -fence_signalled
> -fence_finish
> -	+ D3D10/D3D11 don't appear to support explicit fencing; queries can often substitute though, and flushing is supported
> -
> -set_clip_state
> -	+ Gallium supports fixed function user clip planes, D3D10/D3D11 only support using the vertex shader for them
> -
> -set_polygon_stipple
> -	+ Gallium supports polygon stipple
> -
> -clearRT/clearDS
> -	+ Gallium supports subrectangle fills of surfaces, D3D10 only supports full clears of views
> -
> -* DirectX 10/11 DDI functions and Gallium equivalents
> -
> -AbandonCommandList (D3D11 only)
> -	- Gallium does not support deferred contexts
> -
> -CalcPrivateBlendStateSize
> -CalcPrivateDepthStencilStateSize
> -CalcPrivateDepthStencilViewSize
> -CalcPrivateElementLayoutSize
> -CalcPrivateGeometryShaderWithStreamOutput
> -CalcPrivateOpenedResourceSize
> -CalcPrivateQuerySize
> -CalcPrivateRasterizerStateSize
> -CalcPrivateRenderTargetViewSize
> -CalcPrivateResourceSize
> -CalcPrivateSamplerSize
> -CalcPrivateShaderResourceViewSize
> -CalcPrivateShaderSize
> -CalcDeferredContextHandleSize (D3D11 only)
> -CalcPrivateCommandListSize (D3D11 only)
> -CalcPrivateDeferredContextSize (D3D11 only)
> -CalcPrivateTessellationShaderSize (D3D11 only)
> -CalcPrivateUnorderedAccessViewSize (D3D11 only)
> -	! D3D11 allocates private objects itself, using the size computed here
> -	* Gallium could do something similar to be able to put the private data inline into state tracker objects: this would allow them to fit in the same cacheline and improve performance
> -
> -CheckDeferredContextHandleSizes (D3D11 only)
> -	- Gallium does not support deferred contexts
> -
> -CheckFormatSupport -> screen->is_format_supported
> -	! Gallium passes usages to this function, D3D11 returns them
> -	- Gallium does not differentiate between blendable and non-blendable render targets
> -	! Gallium includes sample count directly, D3D11 uses additional query
> -
> -CheckMultisampleQualityLevels
> -	! is merged with is_format_supported
> -
> -CommandListExecute (D3D11 only)
> -	- Gallium does not support command lists
> -
> -CopyStructureCount (D3D11 only)
> -	- Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders)
> -
> -ClearDepthStencilView -> clear_depth_stencil
> -ClearRenderTargetView -> clear_render_target
> -	# D3D11 is not totally clear about whether this applies to any view or only a "currently-bound view"
> -	+ Gallium allows to clear both depth/stencil and render target(s) in a single operation
> -	+ Gallium supports double-precision depth values (but not rgba values!)
> -	* May want to also support double-precision rgba or use "float" for "depth"
> -
> -ClearUnorderedAccessViewFloat (D3D11 only)
> -ClearUnorderedAccessViewUint (D3D11 only)
> -	- Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders)
> -
> -CreateBlendState (extended in D3D10.1) -> create_blend_state
> -	# D3D10 does not support per-RT blend modes (but per-RT blending), only D3D10.1 does
> -	+ Gallium supports logic ops
> -	+ Gallium supports dithering
> -	+ Gallium supports using the broadcast alpha component of the blend constant color
> -
> -CreateCommandList (D3D11 only)
> -	- Gallium does not support command lists
> -
> -CreateComputeShader (D3D11 only)
> -	- Gallium does not support compute shaders
> -
> -CreateDeferredContext (D3D11 only)
> -	- Gallium does not support deferred contexts
> -
> -CreateDomainShader (D3D11 only)
> -	- Gallium does not support domain shaders
> -
> -CreateHullShader (D3D11 only)
> -	- Gallium does not support hull shaders
> -
> -CreateUnorderedAccessView (D3D11 only)
> -	- Gallium does not support unordered access views
> -
> -CreateDepthStencilState -> create_depth_stencil_alpha_state
> -	! D3D11 has both a global stencil enable, and front/back enables; Gallium has only front/back enables
> -	+ Gallium has per-face writemask/valuemasks, D3D11 uses the same value for back and front
> -	+ Gallium supports the alpha test, which D3D11 lacks
> -
> -CreateDepthStencilView -> create_surface
> -CreateRenderTargetView -> create_surface
> -	! Gallium merges depthstencil and rendertarget views into pipe_surface
> -	- lack of render-to-buffer support
> -	+ Gallium supports using 3D texture zslices as a depth/stencil buffer (in theory)
> -
> -CreateElementLayout -> create_vertex_elements_state
> -	! D3D11 allows sparse vertex elements (via InputRegister); in Gallium they must be specified sequentially
> -	! D3D11 has an extra flag (InputSlotClass) that is the same as instance_divisor == 0
> -
> -CreateGeometryShader -> create_gs_state
> -CreateGeometryShaderWithStreamOutput -> create_gs_state + create_stream_output_state
> -CreatePixelShader -> create_fs_state
> -CreateVertexShader -> create_vs_state
> -	> bytecode is different (see D3d10tokenizedprogramformat.hpp)
> -	! D3D11 describes input/outputs separately from bytecode; Gallium has the tgsi_scan.c module to extract it from TGSI
> -	@ TODO: look into DirectX 10/11 semantics specification and bytecode
> -
> -CheckCounter
> -CheckCounterInfo
> -CreateQuery -> create_query
> -	! D3D11 implements fences with "event" queries
> -	* others are performance counters, we may want them but they are not critical
> -
> -CreateRasterizerState
> -	+ Gallium, like OpenGL, supports PIPE_POLYGON_MODE_POINT
> -	+ Gallium, like OpenGL, supports per-face polygon fill modes
> -	+ Gallium, like OpenGL, supports culling everything
> -	+ Gallium, like OpenGL, supports two-side lighting; D3D11 only has the facing attribute
> -	+ Gallium, like OpenGL, supports per-fill-mode polygon offset enables
> -	+ Gallium, like OpenGL, supports polygon smoothing
> -	+ Gallium, like OpenGL, supports polygon stipple
> -	+ Gallium, like OpenGL, supports point smoothing
> -	+ Gallium, like OpenGL, supports point sprites
> -	+ Gallium supports specifying point quad rasterization
> -	+ Gallium, like OpenGL, supports per-point point size
> -	+ Gallium, like OpenGL, supports line smoothing
> -	+ Gallium, like OpenGL, supports line stipple
> -	+ Gallium supports line last pixel rule specification
> -	+ Gallium, like OpenGL, supports provoking vertex convention
> -	+ Gallium supports D3D9 rasterization rules
> -	+ Gallium supports fixed line width
> -	+ Gallium supports fixed point size
> -
> -CreateResource -> texture_create or buffer_create
> -	! D3D11 passes the dimensions of all mipmap levels to the create call, while Gallium has an implicit floor(x/2) rule
> -	# Note that hardware often has the implicit rule, so the D3D11 interface seems to make little sense
> -	# Also, the D3D11 API does not allow the user to specify mipmap sizes, so this really seems a dubious decision on Microsoft's part
> -	- D3D11 supports specifying initial data to write in the resource
> -	- Gallium does not support unordered access buffers
> -	! D3D11 specifies mapping flags (i.e. read/write/discard);:it's unclear what they are used for here
> -	- D3D11 supports odd things in the D3D10_DDI_RESOURCE_MISC_FLAG enum (D3D10_DDI_RESOURCE_MISC_DISCARD_ON_PRESENT, D3D11_DDI_RESOURCE_MISC_BUFFER_ALLOW_RAW_VIEWS, D3D11_DDI_RESOURCE_MISC_BUFFER_STRUCTURED)
> -	- Gallium does not support indirect draw call parameter buffers
> -	! D3D11 supports specifying hardware modes and other stuff here for scanout resources
> -	! D3D11 implements cube maps as 2D array textures
> -
> -CreateSampler
> -	- D3D11 supports a monochrome convolution filter for "text filtering"
> -	+ Gallium supports non-normalized coordinates
> -	+ Gallium supports CLAMP, MIRROR_CLAMP and MIRROR_CLAMP_TO_BORDER
> -	+ Gallium supports setting min/max/mip filters and anisotropy independently
> -
> -CreateShaderResourceView (extended in D3D10.1) -> create_sampler_view
> -	+ Gallium supports specifying a swizzle
> -	! D3D11 implements "cube views" as views into a 2D array texture
> -
> -CsSetConstantBuffers (D3D11 only)
> -CsSetSamplers (D3D11 only)
> -CsSetShader (D3D11 only)
> -CsSetShaderResources (D3D11 only)
> -CsSetShaderWithIfaces (D3D11 only)
> -CsSetUnorderedAccessViews (D3D11 only)
> -	- Gallium does not support compute shaders
> -
> -DestroyBlendState
> -DestroyCommandList (D3D11 only)
> -DestroyDepthStencilState
> -DestroyDepthStencilView
> -DestroyDevice
> -DestroyElementLayout
> -DestroyQuery
> -DestroyRasterizerState
> -DestroyRenderTargetView
> -DestroyResource
> -DestroySampler
> -DestroyShader
> -DestroyShaderResourceView
> -DestroyUnorderedAccessView (D3D11 only)
> -	# these are trivial
> -
> -Dispatch (D3D11 only)
> -	- Gallium does not support compute shaders
> -
> -DispatchIndirect (D3D11 only)
> -	- Gallium does not support compute shaders
> -
> -Draw -> draw_vbo
> -	! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
> -
> -DrawAuto -> draw_auto
> -
> -DrawIndexed -> draw_vbo
> -	! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
> -	+ D3D11 lacks explicit range, which is required for OpenGL
> -
> -DrawIndexedInstanced -> draw_vbo
> -	! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
> -
> -DrawIndexedInstancedIndirect (D3D11 only)
> -	# this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls
> -	- Gallium does not support draw call parameter buffers and indirect draw
> -
> -DrawInstanced -> draw_vbo
> -	! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
> -
> -DrawInstancedIndirect (D3D11 only)
> -	# this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls
> -	- Gallium does not support draw call parameter buffers and indirect draws
> -
> -DsSetConstantBuffers (D3D11 only)
> -DsSetSamplers (D3D11 only)
> -DsSetShader (D3D11 only)
> -DsSetShaderResources (D3D11 only)
> -DsSetShaderWithIfaces (D3D11 only)
> -	- Gallium does not support domain shaders
> -
> -Flush -> flush
> -	! Gallium supports fencing, D3D11 just has a dumb glFlush-like function
> -
> -GenMips
> -	- Gallium lacks a mipmap generation interface, and does this manually with the 3D engine
> -	* it may be useful to add a mipmap generation interface, since the hardware (especially older cards) may have a better way than using the 3D engine
> -
> -GsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_GEOMETRY, i, phBuffers[i])
> -
> -GsSetSamplers
> -	- Gallium does not support sampling in geometry shaders
> -
> -GsSetShader -> bind_gs_state
> -
> -GsSetShaderWithIfaces (D3D11 only)
> -	- Gallium does not support shader interfaces
> -
> -GsSetShaderResources
> -	- Gallium does not support sampling in geometry shaders
> -
> -HsSetConstantBuffers (D3D11 only)
> -HsSetSamplers (D3D11 only)
> -HsSetShader (D3D11 only)
> -HsSetShaderResources (D3D11 only)
> -HsSetShaderWithIfaces (D3D11 only)
> -	- Gallium does not support hull shaders
> -
> -IaSetIndexBuffer -> set_index_buffer
> -	+ Gallium supports 8-bit indices
> -	# the D3D11 interface allows index-size-unaligned byte offsets into the index buffer; most drivers will abort with an assertion
> -
> -IaSetInputLayout -> bind_vertex_elements_state
> -
> -IaSetTopology
> -	! Gallium passes the topology = primitive type to the draw calls
> -	* may want to add an interface for this
> -	- Gallium lacks support for DirectX 11 tessellated primitives
> -	+ Gallium supports line loops, triangle fans, quads, quad strips and polygons
> -
> -IaSetVertexBuffers -> set_vertex_buffers
> -	- Gallium only allows setting all vertex buffers at once, while D3D11 supports setting a subset
> -
> -OpenResource -> texture_from_handle
> -
> -PsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_FRAGMENT, i, phBuffers[i])
> -	* may want to split into fragment/vertex-specific versions
> -
> -PsSetSamplers -> bind_fragment_sampler_states
> -	* may want to allow binding subsets instead of all at once
> -
> -PsSetShader -> bind_fs_state
> -
> -PsSetShaderWithIfaces (D3D11 only)
> -	- Gallium does not support shader interfaces
> -
> -PsSetShaderResources -> set_sampler_views
> -	* may want to allow binding subsets instead of all at once
> -
> -QueryBegin -> begin_query
> -
> -QueryEnd -> end_query
> -
> -QueryGetData -> get_query_result
> -	- D3D11 supports reading an arbitrary data chunk for query results, Gallium only supports reading a 64-bit integer
> -	+ D3D11 doesn't seem to support actually waiting for the query result (?!)
> -	- D3D11 supports optionally not flushing command buffers here and instead returning DXGI_DDI_ERR_WASSTILLDRAWING
> -
> -RecycleCommandList (D3D11 only)
> -RecycleCreateCommandList (D3D11 only)
> -RecycleDestroyCommandList (D3D11 only)
> -	- Gallium does not support command lists
> -
> -RecycleCreateDeferredContext (D3D11 only)
> -	- Gallium does not support deferred contexts
> -
> -RelocateDeviceFuncs
> -	- Gallium does not support moving pipe_context, while D3D11 seems to, using this
> -
> -ResetPrimitiveID (D3D10.1+ only, #ifdef D3D10PSGP)
> -	# used to do vertex processing on the GPU on Intel G45 chipsets when it is faster this way (see www.intel.com/Assets/PDF/whitepaper/322931.pdf)
> -	# presumably this resets the primitive id system value
> -	- Gallium does not support vertex pipeline bypass anymore
> -
> -ResourceCopy
> -ResourceCopyRegion
> -ResourceConvert (D3D10.1+ only)
> -ResourceConvertRegion (D3D10.1+ only)
> -	-> resource_copy_region
> -
> -ResourceIsStagingBusy ->
> -	- Gallium lacks this
> -	+ Gallium can use fences
> -
> -ResourceReadAfterWriteHazard
> -	- Gallium lacks this
> -
> -ResourceResolveSubresource -> blit
> -
> -ResourceMap
> -ResourceUnmap
> -DynamicConstantBufferMapDiscard
> -DynamicConstantBufferUnmap
> -DynamicIABufferMapDiscard
> -DynamicIABufferMapNoOverwrite
> -DynamicIABufferUnmap
> -DynamicResourceMapDiscard
> -DynamicResourceUnmap
> -StagingResourceMap
> -StagingResourceUnmap
> -	-> transfer functions
> -	! Gallium and D3D have different semantics for transfers
> -	* D3D separates vertex/index buffers from constant buffers
> -	! D3D separates some buffer flags into specialized calls
> -
> -ResourceUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
> -DefaultConstantBufferUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
> -
> -SetBlendState -> bind_blend_state, set_blend_color and set_sample_mask
> -	! D3D11 fuses bind_blend_state, set_blend_color and set_sample_mask in a single function
> -
> -SetDepthStencilState -> bind_depth_stencil_alpha_state and set_stencil_ref
> -	! D3D11 fuses bind_depth_stencil_alpha_state and set_stencil_ref in a single function
> -
> -SetPredication -> render_condition
> -	# here both D3D11 and Gallium seem very limited (hardware is too, probably though)
> -	# ideally, we should support nested conditional rendering, as well as more complex tests (checking for an arbitrary range, after an AND with arbitrary mask )
> -	# of couse, hardware support is probably as limited as OpenGL/D3D11
> -	+ Gallium, like NV_conditional_render, supports by-region and wait flags
> -	- D3D11 supports predication conditional on being equal any value (along with occlusion predicates); Gallium only supports on non-zero
> -
> -SetRasterizerState -> bind_rasterizer_state
> -
> -SetRenderTargets (extended in D3D11) -> set_framebuffer_state
> -	! Gallium passed a width/height here, D3D11 does not
> -	! Gallium lacks ClearTargets (but this is redundant and the driver can trivially compute this if desired)
> -	- Gallium does not support unordered access views
> -	- Gallium does not support geometry shader selection of texture array image / 3D texture zslice
> -
> -SetResourceMinLOD (D3D11 only) -> pipe_sampler_view::tex::first_level
> -
> -SetScissorRects
> -	- Gallium lacks support for multiple geometry-shader-selectable scissor rectangles D3D11 has
> -
> -SetTextFilterSize
> -	- Gallium lacks support for text filters
> -
> -SetVertexPipelineOutput (D3D10.1+ only)
> -	# used to do vertex processing on the GPU on Intel G45 chipsets when it is faster this way (see www.intel.com/Assets/PDF/whitepaper/322931.pdf)
> -	- Gallium does not support vertex pipeline bypass anymore
> -
> -SetViewports
> -	- Gallium lacks support for multiple geometry-shader-selectable viewports D3D11 has
> -
> -ShaderResourceViewReadAfterWriteHazard
> -	- Gallium lacks support for this
> -	+ Gallium has texture_barrier
> -
> -SoSetTargets -> set_stream_output_buffers
> -
> -VsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_VERTEX, i, phBuffers[i])
> -	* may want to split into fragment/vertex-specific versions
> -
> -VsSetSamplers -> bind_vertex_sampler_states
> -	* may want to allow binding subsets instead of all at once
> -
> -VsSetShader -> bind_vs_state
> -
> -VsSetShaderWithIfaces (D3D11 only)
> -	- Gallium does not support shader interfaces
> -
> -VsSetShaderResources  -> set_sampler_views
> -	* may want to allow binding subsets instead of all at once
>