src/gallium/docs/d3d11ddi.txt

   1 This document compares the D3D10/D3D11 device driver interface with Gallium.
   2 It is written from the perspective of a developer implementing a D3D10/D3D11 driver as a Gallium state tracker.
   3
   4 Note that naming and other cosmetic differences are not noted, since they don't really matter and would severely clutter the document.
   5 Gallium/OpenGL terminology is used in preference to D3D terminology.
   6
   7 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
   8
   9 Also note that this is specifically for the DirectX 10/11 Windows Vista/7 DDI interfaces.
  10 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.
  11
  12 The user-visible DirectX 10/11 interfaces are distinct from the kernel DDI, but they match very closely.
  13
  14 * Accessing Microsoft documentation
  15
  16 See http://msdn.microsoft.com/en-us/library/dd445501.aspx ("D3D11DDI_DEVICEFUNCS") for D3D documentation.
  17
  18 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.
  19
  20 The Windows Driver Kit contains the actual headers, as well as shader bytecode documentation.
  21
  22 To get the headers from Linux, run the following, in a dedicated directory:
  23 wget http://download.microsoft.com/download/4/A/2/4A25C7D5-EFBE-4182-B6A9-AE6850409A78/GRMWDK_EN_7600_1.ISO
  24 sudo mount -o loop GRMWDK_EN_7600_1.ISO /mnt/tmp
  25 cabextract -x /mnt/tmp/wdk/headers_cab001.cab
  26 rename 's/^_(.*)_[0-9]*$/$1/' *
  27 sudo umount /mnt/tmp
  28
  29 d3d10umddi.h contains the DDI interface analyzed in this document: note that it is much easier to read this online on MSDN.
  30 d3d{10,11}TokenizedProgramFormat.hpp contains the shader bytecode definitions: this is not available on MSDN.
  31 d3d9types.h contains DX9 shader bytecode, and DX9 types
  32 d3dumddi.h contains the DirectX 9 DDI interface
  33
  34 * Glossary
  35
  36 BC1: DXT1
  37 BC2: DXT3
  38 BC3: DXT5
  39 BC5: RGTC
  40 BC6H: BPTC float
  41 BC7: BPTC
  42 CS = compute shader: OpenCL-like shader
  43 DS = domain shader: tessellation evaluation shader
  44 HS = hull shader: tessellation control shader
  45 IA = input assembler: primitive assembly
  46 Input layout: vertex elements
  47 OM = output merger: blender
  48 PS = pixel shader: fragment shader
  49 Primitive topology: primitive type
  50 Resource: buffer or texture
  51 Shader resource (view): sampler view
  52 SO = stream out: transform feedback
  53 Unordered access view: view supporting random read/write access (usually from compute shaders)
  54
  55 * Legend
  56
  57 -: features D3D11 has and Gallium lacks
  58 +: features Gallium has and D3D11 lacks
  59 !: differences between D3D11 and Gallium
  60 *: possible improvements to Gallium
  61 >: references to comparisons of special enumerations
  62 #: comment
  63
  64 * Gallium functions with no direct D3D10/D3D11 equivalent
  65
  66 clear
  67         + Gallium supports clearing both render targets and depth/stencil with a single call
  68
  69 draw_range_elements
  70         + Gallium supports indexed draw with explicit range
  71
  72 fence_signalled
  73 fence_finish
  74         + D3D10/D3D11 don't appear to support explicit fencing; queries can often substitute though, and flushing is supported
  75
  76 set_clip_state
  77         + Gallium supports fixed function user clip planes, D3D10/D3D11 only support using the vertex shader for them
  78
  79 set_polygon_stipple
  80         + Gallium supports polygon stipple
  81
  82 resource_fill_region
  83         + Gallium supports subrectangle fills of surfaces, D3D10 only supports full clears of views
  84
  85 * DirectX 10/11 DDI functions and Gallium equivalents
  86
  87 AbandonCommandList (D3D11 only)
  88         - Gallium does not support deferred contexts
  89
  90 CalcPrivateBlendStateSize
  91 CalcPrivateDepthStencilStateSize
  92 CalcPrivateDepthStencilViewSize
  93 CalcPrivateElementLayoutSize
  94 CalcPrivateGeometryShaderWithStreamOutput
  95 CalcPrivateOpenedResourceSize
  96 CalcPrivateQuerySize
  97 CalcPrivateRasterizerStateSize
  98 CalcPrivateRenderTargetViewSize
  99 CalcPrivateResourceSize
 100 CalcPrivateSamplerSize
 101 CalcPrivateShaderResourceViewSize
 102 CalcPrivateShaderSize
 103 CalcDeferredContextHandleSize (D3D11 only)
 104 CalcPrivateCommandListSize (D3D11 only)
 105 CalcPrivateDeferredContextSize (D3D11 only)
 106 CalcPrivateTessellationShaderSize (D3D11 only)
 107 CalcPrivateUnorderedAccessViewSize (D3D11 only)
 108         ! D3D11 allocates private objects itself, using the size computed here
 109         * 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
 110
 111 CheckDeferredContextHandleSizes (D3D11 only)
 112         - Gallium does not support deferred contexts
 113
 114 CheckFormatSupport -> screen->is_format_supported
 115         ! Gallium passes usages to this function, D3D11 returns them
 116         - Gallium does not differentiate between blendable and non-blendable render targets
 117         ! Gallium includes sample count directly, D3D11 uses additional query
 118
 119 CheckMultisampleQualityLevels
 120         ! is merged with is_format_supported
 121
 122 CommandListExecute (D3D11 only)
 123         - Gallium does not support command lists
 124
 125 CopyStructureCount (D3D11 only)
 126         - Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders)
 127
 128 ClearDepthStencilView -> clear
 129 ClearRenderTargetView -> clear
 130         # D3D11 is not totally clear about whether this applies to any view or only a "currently-bound view"
 131         + Gallium allows to clear both depth/stencil and render target(s) in a single operation
 132         + Gallium supports double-precision depth values (but not rgba values!)
 133         * May want to also support double-precision rgba or use "float" for "depth"
 134
 135 ClearUnorderedAccessViewFloat (D3D11 only)
 136 ClearUnorderedAccessViewUint (D3D11 only)
 137         - Gallium does not support unordered access views (views that can be written to arbitrarily from compute shaders)
 138
 139 CreateBlendState (extended in D3D10.1) -> create_blend_state
 140         # D3D10 does not support per-RT blend modes (but per-RT blending), only D3D10.1 does
 141         + Gallium supports logic ops
 142         + Gallium supports dithering
 143         + Gallium supports using the broadcast alpha component of the blend constant color
 144
 145 CreateCommandList (D3D11 only)
 146         - Gallium does not support command lists
 147
 148 CreateComputeShader (D3D11 only)
 149         - Gallium does not support compute shaders
 150
 151 CreateDeferredContext (D3D11 only)
 152         - Gallium does not support deferred contexts
 153
 154 CreateDomainShader (D3D11 only)
 155         - Gallium does not support domain shaders
 156
 157 CreateHullShader (D3D11 only)
 158         - Gallium does not support hull shaders
 159
 160 CreateUnorderedAccessView (D3D11 only)
 161         - Gallium does not support unordered access views
 162
 163 CreateDepthStencilState -> create_depth_stencil_alpha_state
 164         ! D3D11 has both a global stencil enable, and front/back enables; Gallium has only front/back enables
 165         + Gallium has per-face writemask/valuemasks, D3D11 uses the same value for back and front
 166         + Gallium supports the alpha test, which D3D11 lacks
 167
 168 CreateDepthStencilView -> get_tex_surface
 169 CreateRenderTargetView -> get_tex_surface
 170         ! Gallium merges depthstencil and rendertarget views into pipe_surface, which also doubles as a 2D surface abstraction
 171         - lack of texture array support
 172         - lack of render-to-buffer support
 173         + Gallium supports using 3D texture zslices as a depth/stencil buffer (in theory)
 174
 175 CreateElementLayout -> create_vertex_elements_state
 176         ! D3D11 allows sparse vertex elements (via InputRegister); in Gallium they must be specified sequentially
 177         ! D3D11 has an extra flag (InputSlotClass) that is the same as instance_divisor == 0
 178
 179 CreateGeometryShader -> create_gs_state
 180 CreateGeometryShaderWithStreamOutput -> create_gs_state
 181 CreatePixelShader -> create_fs_state
 182 CreateVertexShader -> create_vs_state
 183         > bytecode is different (see D3d10tokenizedprogramformat.hpp)
 184         ! D3D11 describes input/outputs separately from bytecode; Gallium has the tgsi_scan.c module to extract it from TGSI
 185         @ TODO: look into DirectX 10/11 semantics specification and bytecode
 186
 187 CheckCounter
 188 CheckCounterInfo
 189 CreateQuery -> create_query
 190         - Gallium only supports occlusion, primitives generated and primitives emitted queries
 191         ! D3D11 implements fences with "event" queries
 192         * TIMESTAMP could be implemented as an additional fields for other queries: some cards have hardware support for exactly this
 193         * OCCLUSIONPREDICATE is required for the OpenGL v2 occlusion query functionality
 194         * others are performance counters, we may want them but they are not critical
 195
 196 CreateRasterizerState
 197         - Gallium lacks clamping of polygon offset depth biases
 198         - Gallium lacks support to disable depth clipping
 199         + Gallium, like OpenGL, supports PIPE_POLYGON_MODE_POINT
 200         + Gallium, like OpenGL, supports per-face polygon fill modes
 201         + Gallium, like OpenGL, supports culling everything
 202         + Gallium, like OpenGL, supports two-side lighting; D3D11 only has the facing attribute
 203         + Gallium, like OpenGL, supports per-fill-mode polygon offset enables
 204         + Gallium, like OpenGL, supports polygon smoothing
 205         + Gallium, like OpenGL, supports polygon stipple
 206         + Gallium, like OpenGL, supports point smoothing
 207         + Gallium, like OpenGL, supports point sprites
 208         + Gallium supports specifying point quad rasterization
 209         + Gallium, like OpenGL, supports per-point point size
 210         + Gallium, like OpenGL, supports line smoothing
 211         + Gallium, like OpenGL, supports line stipple
 212         + Gallium supports line last pixel rule specification
 213         + Gallium, like OpenGL, supports provoking vertex convention
 214         + Gallium supports D3D9 rasterization rules
 215         + Gallium supports fixed line width
 216         + Gallium supports fixed point size
 217
 218 CreateResource -> texture_create or buffer_create
 219         ! D3D11 passes the dimensions of all mipmap levels to the create call, while Gallium has an implicit floor(x/2) rule
 220         # Note that hardware often has the implicit rule, so the D3D11 interface seems to make little sense
 221         # Also, the D3D11 API does not allow the user to specify mipmap sizes, so this really seems a dubious decision on Microsoft's part
 222         - D3D11 supports specifying initial data to write in the resource
 223         - Gallium lacks support for stream output buffer usage
 224         - Gallium does not support unordered access buffers
 225         ! D3D11 specifies mapping flags (i.e. read/write/discard);:it's unclear what they are used for here
 226         - 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)
 227         - Gallium does not support indirect draw call parameter buffers
 228         - Gallium lacks array textures
 229         ! D3D11 supports specifying hardware modes and other stuff here for scanout resources
 230         + Gallium allows specifying minimum buffer alignment
 231         ! D3D11 implements cube maps as 2D array textures
 232
 233 CreateSampler
 234         - D3D11 supports a monochrome convolution filter for "text filtering"
 235         + Gallium supports non-normalized coordinates
 236         + Gallium supports CLAMP, MIRROR_CLAMP and MIRROR_CLAMP_TO_BORDER
 237         + Gallium supports setting min/max/mip filters and anisotropy independently
 238
 239 CreateShaderResourceView (extended in D3D10.1) -> create_sampler_view
 240         - Gallium lacks sampler views over buffers
 241         - Gallium lacks texture arrays, and cube map views over texture arrays
 242         + Gallium supports specifying a swizzle
 243         ! D3D11 implements "cube views" as views into a 2D array texture
 244
 245 CsSetConstantBuffers (D3D11 only)
 246 CsSetSamplers (D3D11 only)
 247 CsSetShader (D3D11 only)
 248 CsSetShaderResources (D3D11 only)
 249 CsSetShaderWithIfaces (D3D11 only)
 250 CsSetUnorderedAccessViews (D3D11 only)
 251         - Gallium does not support compute shaders
 252
 253 DestroyBlendState
 254 DestroyCommandList (D3D11 only)
 255 DestroyDepthStencilState
 256 DestroyDepthStencilView
 257 DestroyDevice
 258 DestroyElementLayout
 259 DestroyQuery
 260 DestroyRasterizerState
 261 DestroyRenderTargetView
 262 DestroyResource
 263 DestroySampler
 264 DestroyShader
 265 DestroyShaderResourceView
 266 DestroyUnorderedAccessView (D3D11 only)
 267         # these are trivial
 268
 269 Dispatch (D3D11 only)
 270         - Gallium does not support compute shaders
 271
 272 DispatchIndirect (D3D11 only)
 273         - Gallium does not support compute shaders
 274
 275 Draw -> draw_arrays
 276         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 277
 278 DrawAuto
 279         - Gallium lacks stream out and DrawAuto
 280
 281 DrawIndexed -> draw_elements
 282         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 283         * may want to add a separate set_index_buffer
 284         - Gallium lacks base vertex for indexed draw calls
 285         + D3D11 lacks draw_range_elements functionality, which is required for OpenGL
 286
 287 DrawIndexedInstanced -> draw_elements_instanced
 288         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 289         * may want to add a separate set_index_buffer
 290         - Gallium lacks base vertex for indexed draw calls
 291
 292 DrawIndexedInstancedIndirect (D3D11 only) -> call draw_elements_instanced multiple times in software
 293         # this allows to use an hardware buffer to specify the parameters for multiple draw_elements_instanced calls
 294         - Gallium does not support draw call parameter buffers and indirect draw
 295
 296 DrawInstanced -> draw_arrays_instanced
 297         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 298
 299 DrawInstancedIndirect (D3D11 only) -> call draw_arrays_instanced multiple times in software
 300         # this allows to use an hardware buffer to specify the parameters for multiple draw_arrays_instanced calls
 301         - Gallium does not support draw call parameter buffers and indirect draws
 302
 303 DsSetConstantBuffers (D3D11 only)
 304 DsSetSamplers (D3D11 only)
 305 DsSetShader (D3D11 only)
 306 DsSetShaderResources (D3D11 only)
 307 DsSetShaderWithIfaces (D3D11 only)
 308         - Gallium does not support domain shaders
 309
 310 Flush -> flush
 311         ! Gallium supports fencing and several kinds of flushing here, D3D11 just has a dumb glFlush-like function
 312
 313 GenMips
 314         - Gallium lacks a mipmap generation interface, and does this manually with the 3D engine
 315         * 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
 316
 317 GsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_GEOMETRY, i, phBuffers[i])
 318
 319 GsSetSamplers
 320         - Gallium does not support sampling in geometry shaders
 321
 322 GsSetShader -> bind_gs_state
 323
 324 GsSetShaderWithIfaces (D3D11 only)
 325         - Gallium does not support shader interfaces
 326
 327 GsSetShaderResources
 328         - Gallium does not support sampling in geometry shaders
 329
 330 HsSetConstantBuffers (D3D11 only)
 331 HsSetSamplers (D3D11 only)
 332 HsSetShader (D3D11 only)
 333 HsSetShaderResources (D3D11 only)
 334 HsSetShaderWithIfaces (D3D11 only)
 335         - Gallium does not support hull shaders
 336
 337 IaSetIndexBuffer
 338         ! Gallium passes this to the draw_elements or draw_elements_instanced calls
 339         + Gallium supports 8-bit indices
 340         ! the D3D11 interface allows index-size-unaligned byte offsets into index buffers; it's not clear whether they actually work
 341
 342 IaSetInputLayout -> bind_vertex_elements_state
 343
 344 IaSetTopology
 345         ! Gallium passes the topology = primitive type to the draw calls
 346         * may want to add an interface for this
 347         - Gallium lacks support for DirectX 11 tessellated primitives
 348         + Gallium supports line loops, triangle fans, quads, quad strips and polygons
 349
 350 IaSetVertexBuffers -> set_vertex_buffers
 351         + Gallium allows to specify a max_index here
 352         - Gallium only allows setting all vertex buffers at once, while D3D11 supports setting a subset
 353
 354 OpenResource -> texture_from_handle
 355
 356 PsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_FRAGMENT, i, phBuffers[i])
 357         * may want to split into fragment/vertex-specific versions
 358
 359 PsSetSamplers -> bind_fragment_sampler_states
 360         * may want to allow binding subsets instead of all at once
 361
 362 PsSetShader -> bind_fs_state
 363
 364 PsSetShaderWithIfaces (D3D11 only)
 365         - Gallium does not support shader interfaces
 366
 367 PsSetShaderResources -> set_fragment_sampler_views
 368         * may want to allow binding subsets instead of all at once
 369
 370 QueryBegin -> begin_query
 371
 372 QueryEnd -> end_query
 373
 374 QueryGetData -> get_query_result
 375         - D3D11 supports reading an arbitrary data chunk for query results, Gallium only supports reading a 64-bit integer
 376         + D3D11 doesn't seem to support actually waiting for the query result (?!)
 377         - D3D11 supports optionally not flushing command buffers here and instead returning DXGI_DDI_ERR_WASSTILLDRAWING
 378
 379 RecycleCommandList (D3D11 only)
 380 RecycleCreateCommandList (D3D11 only)
 381 RecycleDestroyCommandList (D3D11 only)
 382         - Gallium does not support command lists
 383
 384 RecycleCreateDeferredContext (D3D11 only)
 385         - Gallium does not support deferred contexts
 386
 387 RelocateDeviceFuncs
 388         - Gallium does not support moving pipe_context, while D3D11 seems to, using this
 389
 390 ResetPrimitiveID (D3D10.1+ only, #ifdef D3D10PSGP)
 391         # 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)
 392         # presumably this resets the primitive id system value
 393         - Gallium does not support vertex pipeline bypass anymore
 394
 395 ResourceCopy
 396 ResourceCopyRegion
 397 ResourceConvert (D3D10.1+ only)
 398 ResourceConvertRegion (D3D10.1+ only)
 399         -> resource_copy_region
 400         - Gallium does not support hardware buffer copies
 401         - Gallium does not support copying 3D texture subregions in a single call
 402
 403 ResourceIsStagingBusy -> is_texture_referenced, is_buffer_referenced
 404         - Gallium does not support checking reference for a whole texture, but only a specific surface
 405
 406 ResourceReadAfterWriteHazard
 407         ! Gallium specifies hides this, except for the render and texture caches
 408
 409 ResourceResolveSubresource -> resource_resolve
 410
 411 ResourceMap
 412 ResourceUnmap
 413 DynamicConstantBufferMapDiscard
 414 DynamicConstantBufferUnmap
 415 DynamicIABufferMapDiscard
 416 DynamicIABufferMapNoOverwrite
 417 DynamicIABufferUnmap
 418 DynamicResourceMapDiscard
 419 DynamicResourceUnmap
 420 StagingResourceMap
 421 StagingResourceUnmap
 422         -> buffer_map / buffer_unmap
 423         -> transfer functions
 424         ! Gallium and D3D have different semantics for transfers
 425         * D3D separates vertex/index buffers from constant buffers
 426         ! D3D separates some buffer flags into specialized calls
 427
 428 ResourceUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
 429 DefaultConstantBufferUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
 430
 431 SetBlendState -> bind_blend_state, set_blend_color and set_sample_mask
 432         ! D3D11 fuses bind_blend_state, set_blend_color and set_sample_mask in a single function
 433
 434 SetDepthStencilState -> bind_depth_stencil_alpha_state and set_stencil_ref
 435         ! D3D11 fuses bind_depth_stencil_alpha_state and set_stencil_ref in a single function
 436
 437 SetPredication -> render_condition
 438         # here both D3D11 and Gallium seem very limited (hardware is too, probably though)
 439         # ideally, we should support nested conditional rendering, as well as more complex tests (checking for an arbitrary range, after an AND with arbitrary mask )
 440         # of couse, hardware support is probably as limited as OpenGL/D3D11
 441         + Gallium, like NV_conditional_render, supports by-region and wait flags
 442         - D3D11 supports predication conditional on being equal any value (along with occlusion predicates); Gallium only supports on non-zero
 443
 444 SetRasterizerState -> bind_rasterizer_state
 445
 446 SetRenderTargets (extended in D3D11) -> set_framebuffer_state
 447         ! Gallium passed a width/height here, D3D11 does not
 448         ! Gallium lacks ClearTargets (but this is redundant and the driver can trivially compute this if desired)
 449         - Gallium does not support unordered access views
 450         - Gallium does not support geometry shader selection of texture array image / 3D texture zslice
 451
 452 SetResourceMinLOD (D3D11 only)
 453         - Gallium does not support min lod directly on textures
 454
 455 SetScissorRects
 456         - Gallium lacks support for multiple geometry-shader-selectable scissor rectangles D3D11 has
 457
 458 SetTextFilterSize
 459         - Gallium lacks support for text filters
 460
 461 SetVertexPipelineOutput (D3D10.1+ only)
 462         # 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)
 463         - Gallium does not support vertex pipeline bypass anymore
 464
 465 SetViewports
 466         - Gallium lacks support for multiple geometry-shader-selectable viewports D3D11 has
 467
 468 ShaderResourceViewReadAfterWriteHazard -> flush(PIPE_FLUSH_RENDER_CACHE)
 469         - Gallium does not support specifying this per-render-target/view
 470
 471 SoSetTargets
 472         - Gallium does not support stream out
 473
 474 VsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_VERTEX, i, phBuffers[i])
 475         * may want to split into fragment/vertex-specific versions
 476
 477 VsSetSamplers -> bind_vertex_sampler_states
 478         * may want to allow binding subsets instead of all at once
 479
 480 VsSetShader -> bind_vs_state
 481
 482 VsSetShaderWithIfaces (D3D11 only)
 483         - Gallium does not support shader interfaces
 484
 485 VsSetShaderResources  -> set_fragment_sampler_views
 486         * may want to allow binding subsets instead of all at once