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

Marek Olšák maraeo at gmail.com
Fri Jun 26 11:22:14 PDT 2015 

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
-- 
2.1.0

More information about the mesa-dev mailing list