Expand description

This project provides low-level bindings for D3D12 API. It utilizes rust-bindgen for generating raw bindings (unlike d3d12-rs crate), but aims for providing idiomatic APIs (unlike the raw D3D12 wrappers from winapi or windows-rs crates).

Features

  • wrappers for ID3D12* interfaces and POD structs. The latter are marked as #[repr(transparent)] so that they can be used as a drop-in replacement for the native types, but expose type-safe getters and setters. The setters have two forms: with_*(mut self, ...) -> Self and set_*(&mut self, ...) -> &mut Self and are intended for building new structures and modifying the existing ones, respectively
  • type-safe wrappers for D3D12 enumerations and bit flags (see enum_wrappers.rs for details)
  • D3D12 and DXGI prefixes have been stripped from all types, functions and enum variants (e.g. this library exposes CommandListType::Direct instead of D3D12_COMMAND_LIST_TYPE_DIRECT) since it’s very likely that people who use it already know the name of the API it wraps (it’s mentioned in the crate name after all), and do not need to be constantly reminded about it :) Also all type and function names have been reshaped with respect to the official Rust code style (e.g. get_gpu_descriptor_handle_for_heap_start instead of GetGPUDescriptorHandleForHeapStart). Note that most, but not all the enum variant names have been converted yet, so some of them will be changed in future versions
  • D3D12 Agility SDK is integrated into the library and shipped along with it (see heterogeneous_multiadapter.rs for an example of exporting required symbols). Current SDK version is 1.600.10
  • PIX markers (they require enabling pix feature which is off by default not to introduce a dependency on WinPixEventRuntime.dll for people who don’t need it)
  • automatic COM object reference counting via Clone and Drop traits implementations with optional logging possibilities (e.g. see impl_com_object_refcount_named macro)
  • D3D12 debug callback support (please note that debug_callback feature needs to be activated explicitly since ID3D12InfoQueue1 interface is only supported on Windows 11), object autonaming and GPU validation
  • convenience macros for wrapping API calls (dx_call! and dx_try!)
  • not yet covered APIs can be accessed through raw bindings exports, and new APIs can be wrapped in semi-automatic mode with the help of conversion_assist.py script
  • most of the APIs provided by rusty-d3d12 are not marked as unsafe since it pollutes client code while giving little in return: obviously, a lot of bad things can happen due to misusing D3D12, but guarding against something like that is a task for a high-level graphics library or engine. So unsafe is reserved for something unsafe that happens on Rust side, e.g. accessing unions (see ClearValue::color())

Examples

  • create debug controller and enable validations:
let debug_controller = Debug::new().expect("cannot create debug controller");
debug_controller.enable_debug_layer();
debug_controller.enable_gpu_based_validation();
debug_controller.enable_object_auto_name();
  • create a descriptor heap:
let rtv_heap = device
    .create_descriptor_heap(
        &DescriptorHeapDesc::default()
            .with_heap_type(DescriptorHeapType::Rtv)
            .with_num_descriptors(FRAMES_IN_FLIGHT),
    )
    .expect("Cannot create RTV heap");
rtv_heap
    .set_name("RTV heap")
    .expect("Cannot set RTV heap name");
  • check if cross-adapter textures are supported:
let mut feature_data = FeatureDataOptions::default();
device
    .check_feature_support(Feature::D3D12Options, &mut feature_data)
    .expect("Cannot check feature support");

let cross_adapter_textures_supported = feature_data.cross_adapter_row_major_texture_supported();
  • create mesh shader PSO:
let ms_bytecode = ShaderBytecode::new(&mesh_shader);
let ps_bytecode = ShaderBytecode::new(&pixel_shader);

let pso_subobjects_desc = MeshShaderPipelineStateDesc::default()
    .with_root_signature(root_signature)
    .with_ms_bytecode(&ms_bytecode)
    .with_ps_bytecode(&ps_bytecode)
    .with_rasterizer_state(
        RasterizerDesc::default().with_depth_clip_enable(false),
    )
    .with_blend_state(BlendDesc::default())
    .with_depth_stencil_state(
        DepthStencilDesc::default().with_depth_enable(false),
    )
    .with_primitive_topology_type(PrimitiveTopologyType::Triangle)
    .with_rtv_formats(&[Format::R8G8B8A8Unorm]);

let pso_desc = PipelineStateStreamDesc::default()
    .with_pipeline_state_subobject_stream(
        pso_subobjects_desc.as_byte_stream(),
    );

let pso = device
    .create_pipeline_state(&pso_desc)
    .expect("Cannot create PSO");

Please see the project repository for more info, including runnable examples.

Macros

A macro similar to std::mem::size_of function, but returns ByteCount instead of usize

Structs

Wrapper around IDXGIAdapter3 interface

Wrapper around DXGI_ADAPTER_DESC1 structure

Wrapper around D3D12_BLEND_DESC structure

Wrapper around ID3DBlob interface

Wrapper around D3D12_BOX structure

Wrapper around D3D12_BUFFER_SRV structure

Wrapper around D3D12_BUFFER_UAV structure

A newtype around u64 made to distinguish between element counts and byte sizes in APIs

Wrapper around D3D12_CACHED_PIPELINE_STATE structure

Wrapper around D3D12_CLEAR_VALUE structure

Wrapper around D3D12_COMMAND_QUEUE_DESC structure

Wrapper around D3D12_COMPUTE_PIPELINE_STATE_DESC structure

Wrapper around D3D12_CONSTANT_BUFFER_VIEW_DESC structure

Wrapper around D3D12_DEPTH_STENCIL_DESC structure

Wrapper around D3D12_DEPTH_STENCILOP_DESC structure

Wrapper around D3D12_DEPTH_STENCIL_VALUE structure

Wrapper around D3D12_DEPTH_STENCIL_VIEW_DESC structure

Wrapper around D3D12_DESCRIPTOR_HEAP_DESC structure

Wrapper around D3D12_DESCRIPTOR_RANGE1 structure

Newtype around u32 since it has a special value of DESCRIPTOR_RANGE_OFFSET_APPEND

Wrapper around D3D12_FEATURE_DATA_D3D12_OPTIONS structure

Wrapper around D3D12_FEATURE_DATA_ROOT_SIGNATURE structure

Wrapper around D3D12_FEATURE_DATA_SHADER_MODEL structure

Wrapper around D3D12_GPU_VIRTUAL_ADDRESS structure

Wrapper around D3D12_GRAPHICS_PIPELINE_STATE_DESC structure

Wrapper around D3D12_HEAP_DESC structure

Wrapper around D3D12_HEAP_PROPERTIES structure

Wrapper around D3D12_INDEX_BUFFER_VIEW structure

Wrapper around D3D12_INPUT_ELEMENT_DESC structure

Wrapper around D3D12_INPUT_LAYOUT_DESC structure

Mesh shader pipeline description struct (a convenience struct that does not have C counterpart)

Wrapper around D3D12_MESSAGE structure

Wrapper around D3D12_PIPELINE_STATE_STREAM_DESC structure

An element of a pipeline subobject stream (element type + subobject itself)

Wrapper around D3D12_PLACED_SUBRESOURCE_FOOTPRINT structure

Wrapper around D3D12_QUERY_HEAP_DESC structure

Wrapper around D3D12_RANGE structure

Wrapper around D3D12_RASTERIZER_DESC structure

Wrapper around D3D12_RAYTRACING_ACCELERATION_STRUCTURE_SRV structure

Wrapper around D3D12_RECT structure

Wrapper around D3D12_RENDER_TARGET_BLEND_DESC structure

Wrapper around D3D12_RESOURCE_ALIASING_BARRIER structure

Wrapper around D3D12_RESOURCE_ALLOCATION_INFO structure

Wrapper around D3D12_RESOURCE_BARRIER structure. Note this type is not Clone since it contains a raw pointer

Wrapper around D3D12_RESOURCE_DESC structure

Wrapper around D3D12_RESOURCE_TRANSITION_BARRIER structure

Wrapper around D3D12_RESOURCE_UAV_BARRIER structure

Wrapper around D3D12_ROOT_CONSTANTS structure

Wrapper around D3D12_ROOT_DESCRIPTOR1 structure

Wrapper around D3D12_ROOT_DESCRIPTOR_TABLE1 structure

Wrapper around D3D12_ROOT_PARAMETER1 structure

Wrapper around D3D12_ROOT_SIGNATURE_DESC1 structure

Wrapper around D3D12_RT_FORMAT_ARRAY structure

Wrapper around DXGI_SAMPLE_DESC structure

Wrapper around D3D12_SAMPLER_DESC structure

Wrapper around D3D12_SHADER_BYTECODE structure

Wrapper around D3D12_SHADER_RESOURCE_VIEW_DESC structure

Wrapper around D3D12_SO_DECLARATION_ENTRY structure

Wrapper around D3D12_STATIC_SAMPLER_DESC structure

Wrapper around D3D12_STREAM_OUTPUT_DESC structure

Wrapper around D3D12_SUBRESOURCE_DATA structure

Wrapper around D3D12_SUBRESOURCE_FOOTPRINT structure

Wrapper around DXGI_SWAP_CHAIN_DESC1 structure

Wrapper around D3D12_TEX1D_ARRAY_DSV structure

Wrapper around D3D12_TEX1D_ARRAY_SRV structure

Wrapper around D3D12_TEX1D_ARRAY_UAV structure

Wrapper around D3D12_TEX1D_DSV structure

Wrapper around D3D12_TEX1D_SRV structure

Wrapper around D3D12_TEX1D_UAV structure

Wrapper around D3D12_TEX2D_ARRAY_DSV structure

Wrapper around D3D12_TEX2D_ARRAY_SRV structure

Wrapper around D3D12_TEX2D_ARRAY_UAV structure

Wrapper around D3D12_TEX2D_DSV structure

Wrapper around D3D12_TEX2DMS_ARRAY_SRV structure

Wrapper around D3D12_TEX2DMS_SRV structure

Wrapper around D3D12_TEX2D_SRV structure

Wrapper around D3D12_TEX2D_UAV structure

Wrapper around D3D12_TEX2DMS_ARRAY_DSV structure

Wrapper around D3D12_TEX2DMS_DSV structure

Wrapper around D3D12_TEX3D_SRV structure

Wrapper around D3D12_TEX3D_UAV structure

Wrapper around D3D12_TEXCUBE_ARRAY_SRV structure

Wrapper around D3D12_TEXCUBE_SRV structure

Wrapper around D3D12_TEXTURE_COPY_LOCATION structure

Wrapper around D3D12_UNORDERED_ACCESS_VIEW_DESC structure

Wrapper around D3D12_VERSIONED_ROOT_SIGNATURE_DESC structure

Wrapper around D3D12_VERTEX_BUFFER_VIEW structure

Wrapper around D3D12_VIEWPORT structure

Enums

Constants

Functions

Type Definitions