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 -> get_tex_surface
 166 CreateRenderTargetView -> get_tex_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         - Gallium lacks array textures
 225         ! D3D11 supports specifying hardware modes and other stuff here for scanout resources
 226         + Gallium allows specifying minimum buffer alignment
 227         ! D3D11 implements cube maps as 2D array textures
 228
 229 CreateSampler
 230         - D3D11 supports a monochrome convolution filter for "text filtering"
 231         + Gallium supports non-normalized coordinates
 232         + Gallium supports CLAMP, MIRROR_CLAMP and MIRROR_CLAMP_TO_BORDER
 233         + Gallium supports setting min/max/mip filters and anisotropy independently
 234
 235 CreateShaderResourceView (extended in D3D10.1) -> create_sampler_view
 236         - Gallium lacks sampler views over buffers
 237         - Gallium lacks texture arrays, and cube map views over texture arrays
 238         + Gallium supports specifying a swizzle
 239         ! D3D11 implements "cube views" as views into a 2D array texture
 240
 241 CsSetConstantBuffers (D3D11 only)
 242 CsSetSamplers (D3D11 only)
 243 CsSetShader (D3D11 only)
 244 CsSetShaderResources (D3D11 only)
 245 CsSetShaderWithIfaces (D3D11 only)
 246 CsSetUnorderedAccessViews (D3D11 only)
 247         - Gallium does not support compute shaders
 248
 249 DestroyBlendState
 250 DestroyCommandList (D3D11 only)
 251 DestroyDepthStencilState
 252 DestroyDepthStencilView
 253 DestroyDevice
 254 DestroyElementLayout
 255 DestroyQuery
 256 DestroyRasterizerState
 257 DestroyRenderTargetView
 258 DestroyResource
 259 DestroySampler
 260 DestroyShader
 261 DestroyShaderResourceView
 262 DestroyUnorderedAccessView (D3D11 only)
 263         # these are trivial
 264
 265 Dispatch (D3D11 only)
 266         - Gallium does not support compute shaders
 267
 268 DispatchIndirect (D3D11 only)
 269         - Gallium does not support compute shaders
 270
 271 Draw -> draw_vbo
 272         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 273
 274 DrawAuto -> draw_auto
 275
 276 DrawIndexed -> draw_vbo
 277         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 278         + D3D11 lacks explicit range, which is required for OpenGL
 279
 280 DrawIndexedInstanced -> draw_vbo
 281         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 282
 283 DrawIndexedInstancedIndirect (D3D11 only)
 284         # this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls
 285         - Gallium does not support draw call parameter buffers and indirect draw
 286
 287 DrawInstanced -> draw_vbo
 288         ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better
 289
 290 DrawInstancedIndirect (D3D11 only)
 291         # this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls
 292         - Gallium does not support draw call parameter buffers and indirect draws
 293
 294 DsSetConstantBuffers (D3D11 only)
 295 DsSetSamplers (D3D11 only)
 296 DsSetShader (D3D11 only)
 297 DsSetShaderResources (D3D11 only)
 298 DsSetShaderWithIfaces (D3D11 only)
 299         - Gallium does not support domain shaders
 300
 301 Flush -> flush
 302         ! Gallium supports fencing and several kinds of flushing here, D3D11 just has a dumb glFlush-like function
 303
 304 GenMips
 305         - Gallium lacks a mipmap generation interface, and does this manually with the 3D engine
 306         * 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
 307
 308 GsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_GEOMETRY, i, phBuffers[i])
 309
 310 GsSetSamplers
 311         - Gallium does not support sampling in geometry shaders
 312
 313 GsSetShader -> bind_gs_state
 314
 315 GsSetShaderWithIfaces (D3D11 only)
 316         - Gallium does not support shader interfaces
 317
 318 GsSetShaderResources
 319         - Gallium does not support sampling in geometry shaders
 320
 321 HsSetConstantBuffers (D3D11 only)
 322 HsSetSamplers (D3D11 only)
 323 HsSetShader (D3D11 only)
 324 HsSetShaderResources (D3D11 only)
 325 HsSetShaderWithIfaces (D3D11 only)
 326         - Gallium does not support hull shaders
 327
 328 IaSetIndexBuffer -> set_index_buffer
 329         + Gallium supports 8-bit indices
 330         # the D3D11 interface allows index-size-unaligned byte offsets into the index buffer; most drivers will abort with an assertion
 331
 332 IaSetInputLayout -> bind_vertex_elements_state
 333
 334 IaSetTopology
 335         ! Gallium passes the topology = primitive type to the draw calls
 336         * may want to add an interface for this
 337         - Gallium lacks support for DirectX 11 tessellated primitives
 338         + Gallium supports line loops, triangle fans, quads, quad strips and polygons
 339
 340 IaSetVertexBuffers -> set_vertex_buffers
 341         + Gallium allows to specify a max_index here
 342         - Gallium only allows setting all vertex buffers at once, while D3D11 supports setting a subset
 343
 344 OpenResource -> texture_from_handle
 345
 346 PsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_FRAGMENT, i, phBuffers[i])
 347         * may want to split into fragment/vertex-specific versions
 348
 349 PsSetSamplers -> bind_fragment_sampler_states
 350         * may want to allow binding subsets instead of all at once
 351
 352 PsSetShader -> bind_fs_state
 353
 354 PsSetShaderWithIfaces (D3D11 only)
 355         - Gallium does not support shader interfaces
 356
 357 PsSetShaderResources -> set_fragment_sampler_views
 358         * may want to allow binding subsets instead of all at once
 359
 360 QueryBegin -> begin_query
 361
 362 QueryEnd -> end_query
 363
 364 QueryGetData -> get_query_result
 365         - D3D11 supports reading an arbitrary data chunk for query results, Gallium only supports reading a 64-bit integer
 366         + D3D11 doesn't seem to support actually waiting for the query result (?!)
 367         - D3D11 supports optionally not flushing command buffers here and instead returning DXGI_DDI_ERR_WASSTILLDRAWING
 368
 369 RecycleCommandList (D3D11 only)
 370 RecycleCreateCommandList (D3D11 only)
 371 RecycleDestroyCommandList (D3D11 only)
 372         - Gallium does not support command lists
 373
 374 RecycleCreateDeferredContext (D3D11 only)
 375         - Gallium does not support deferred contexts
 376
 377 RelocateDeviceFuncs
 378         - Gallium does not support moving pipe_context, while D3D11 seems to, using this
 379
 380 ResetPrimitiveID (D3D10.1+ only, #ifdef D3D10PSGP)
 381         # 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)
 382         # presumably this resets the primitive id system value
 383         - Gallium does not support vertex pipeline bypass anymore
 384
 385 ResourceCopy
 386 ResourceCopyRegion
 387 ResourceConvert (D3D10.1+ only)
 388 ResourceConvertRegion (D3D10.1+ only)
 389         -> resource_copy_region
 390         - Gallium does not support hardware buffer copies
 391         - Gallium does not support copying 3D texture subregions in a single call
 392
 393 ResourceIsStagingBusy -> is_texture_referenced, is_buffer_referenced
 394         - Gallium does not support checking reference for a whole texture, but only a specific surface
 395
 396 ResourceReadAfterWriteHazard
 397         ! Gallium specifies hides this, except for the render and texture caches
 398
 399 ResourceResolveSubresource -> resource_resolve
 400
 401 ResourceMap
 402 ResourceUnmap
 403 DynamicConstantBufferMapDiscard
 404 DynamicConstantBufferUnmap
 405 DynamicIABufferMapDiscard
 406 DynamicIABufferMapNoOverwrite
 407 DynamicIABufferUnmap
 408 DynamicResourceMapDiscard
 409 DynamicResourceUnmap
 410 StagingResourceMap
 411 StagingResourceUnmap
 412         -> buffer_map / buffer_unmap
 413         -> transfer functions
 414         ! Gallium and D3D have different semantics for transfers
 415         * D3D separates vertex/index buffers from constant buffers
 416         ! D3D separates some buffer flags into specialized calls
 417
 418 ResourceUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
 419 DefaultConstantBufferUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources
 420
 421 SetBlendState -> bind_blend_state, set_blend_color and set_sample_mask
 422         ! D3D11 fuses bind_blend_state, set_blend_color and set_sample_mask in a single function
 423
 424 SetDepthStencilState -> bind_depth_stencil_alpha_state and set_stencil_ref
 425         ! D3D11 fuses bind_depth_stencil_alpha_state and set_stencil_ref in a single function
 426
 427 SetPredication -> render_condition
 428         # here both D3D11 and Gallium seem very limited (hardware is too, probably though)
 429         # ideally, we should support nested conditional rendering, as well as more complex tests (checking for an arbitrary range, after an AND with arbitrary mask )
 430         # of couse, hardware support is probably as limited as OpenGL/D3D11
 431         + Gallium, like NV_conditional_render, supports by-region and wait flags
 432         - D3D11 supports predication conditional on being equal any value (along with occlusion predicates); Gallium only supports on non-zero
 433
 434 SetRasterizerState -> bind_rasterizer_state
 435
 436 SetRenderTargets (extended in D3D11) -> set_framebuffer_state
 437         ! Gallium passed a width/height here, D3D11 does not
 438         ! Gallium lacks ClearTargets (but this is redundant and the driver can trivially compute this if desired)
 439         - Gallium does not support unordered access views
 440         - Gallium does not support geometry shader selection of texture array image / 3D texture zslice
 441
 442 SetResourceMinLOD (D3D11 only)
 443         - Gallium does not support min lod directly on textures
 444
 445 SetScissorRects
 446         - Gallium lacks support for multiple geometry-shader-selectable scissor rectangles D3D11 has
 447
 448 SetTextFilterSize
 449         - Gallium lacks support for text filters
 450
 451 SetVertexPipelineOutput (D3D10.1+ only)
 452         # 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)
 453         - Gallium does not support vertex pipeline bypass anymore
 454
 455 SetViewports
 456         - Gallium lacks support for multiple geometry-shader-selectable viewports D3D11 has
 457
 458 ShaderResourceViewReadAfterWriteHazard -> flush(PIPE_FLUSH_RENDER_CACHE)
 459         - Gallium does not support specifying this per-render-target/view
 460
 461 SoSetTargets -> set_stream_output_buffers
 462
 463 VsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_VERTEX, i, phBuffers[i])
 464         * may want to split into fragment/vertex-specific versions
 465
 466 VsSetSamplers -> bind_vertex_sampler_states
 467         * may want to allow binding subsets instead of all at once
 468
 469 VsSetShader -> bind_vs_state
 470
 471 VsSetShaderWithIfaces (D3D11 only)
 472         - Gallium does not support shader interfaces
 473
 474 VsSetShaderResources  -> set_fragment_sampler_views
 475         * may want to allow binding subsets instead of all at once