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