Crate rusty_d3d12

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§

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

Structs§

Adapter: Wrapper around IDXGIAdapter3 interface
AdapterDesc: Wrapper around DXGI_ADAPTER_DESC1 structure
BlendDesc: Wrapper around D3D12_BLEND_DESC structure
Blob: Wrapper around ID3DBlob interface
Box: Wrapper around D3D12_BOX structure
BufferSrv: Wrapper around D3D12_BUFFER_SRV structure
BufferSrvFlags
BufferUav: Wrapper around D3D12_BUFFER_UAV structure
ByteCount: A newtype around u64 made to distinguish between element counts and byte sizes in APIs
CachedPipelineState: Wrapper around D3D12_CACHED_PIPELINE_STATE structure
ClearFlags
ClearValue: Wrapper around D3D12_CLEAR_VALUE structure
ColorWriteEnable
CommandAllocator
CommandList
CommandQueue
CommandQueueDesc: Wrapper around D3D12_COMMAND_QUEUE_DESC structure
CommandQueueFlags
ComputePipelineStateDesc: Wrapper around D3D12_COMPUTE_PIPELINE_STATE_DESC structure
ConstantBufferViewDesc: Wrapper around D3D12_CONSTANT_BUFFER_VIEW_DESC structure
CpuDescriptorHandle
CreateFactoryFlags
Debug
DebugDevice
DepthStencilDesc: Wrapper around D3D12_DEPTH_STENCIL_DESC structure
DepthStencilOpDesc: Wrapper around D3D12_DEPTH_STENCILOP_DESC structure
DepthStencilValue: Wrapper around D3D12_DEPTH_STENCIL_VALUE structure
DepthStencilViewDesc: Wrapper around D3D12_DEPTH_STENCIL_VIEW_DESC structure
DescriptorHeap
DescriptorHeapDesc: Wrapper around D3D12_DESCRIPTOR_HEAP_DESC structure
DescriptorHeapFlags
DescriptorRange: Wrapper around D3D12_DESCRIPTOR_RANGE1 structure
DescriptorRangeFlags
DescriptorRangeOffset: Newtype around u32 since it has a special value of DESCRIPTOR_RANGE_OFFSET_APPEND
Device
DeviceChild
DsvFlags
DxError
Factory
FeatureDataOptions: Wrapper around D3D12_FEATURE_DATA_D3D12_OPTIONS structure
FeatureDataRootSignature: Wrapper around D3D12_FEATURE_DATA_ROOT_SIGNATURE structure
FeatureDataShaderModel: Wrapper around D3D12_FEATURE_DATA_SHADER_MODEL structure
Fence
FenceFlags
GpuDescriptorHandle
GpuVirtualAddress: Wrapper around D3D12_GPU_VIRTUAL_ADDRESS structure
GraphicsPipelineStateDesc: Wrapper around D3D12_GRAPHICS_PIPELINE_STATE_DESC structure
Handle
Heap
HeapDesc: Wrapper around D3D12_HEAP_DESC structure
HeapFlags
HeapProperties: Wrapper around D3D12_HEAP_PROPERTIES structure
IndexBufferView: Wrapper around D3D12_INDEX_BUFFER_VIEW structure
InfoQueue
InputElementDesc: Wrapper around D3D12_INPUT_ELEMENT_DESC structure
InputLayoutDesc: Wrapper around D3D12_INPUT_LAYOUT_DESC structure
MakeWindowAssociationFlags
MeshShaderPipelineStateDesc: Mesh shader pipeline description struct (a convenience struct that does not have C counterpart)
Message: Wrapper around D3D12_MESSAGE structure
PIXSupport
PipelineState
PipelineStateFlags
PipelineStateStreamDesc: Wrapper around D3D12_PIPELINE_STATE_STREAM_DESC structure
PipelineStateSubobject: An element of a pipeline subobject stream (element type + subobject itself)
PlacedSubresourceFootprint: Wrapper around D3D12_PLACED_SUBRESOURCE_FOOTPRINT structure
PresentFlags
QueryHeap
QueryHeapDesc: Wrapper around D3D12_QUERY_HEAP_DESC structure
Range: Wrapper around D3D12_RANGE structure
RasterizerDesc: Wrapper around D3D12_RASTERIZER_DESC structure
RaytracingAccelerationStructureSrv: Wrapper around D3D12_RAYTRACING_ACCELERATION_STRUCTURE_SRV structure
Rect: Wrapper around D3D12_RECT structure
RenderTargetBlendDesc: Wrapper around D3D12_RENDER_TARGET_BLEND_DESC structure
Resource
ResourceAliasingBarrier: Wrapper around D3D12_RESOURCE_ALIASING_BARRIER structure
ResourceAllocationInfo: Wrapper around D3D12_RESOURCE_ALLOCATION_INFO structure
ResourceBarrier: Wrapper around D3D12_RESOURCE_BARRIER structure. Note this type is not Clone since it contains a raw pointer
ResourceBarrierFlags
ResourceDesc: Wrapper around D3D12_RESOURCE_DESC structure
ResourceFlags
ResourceStates
ResourceTransitionBarrier: Wrapper around D3D12_RESOURCE_TRANSITION_BARRIER structure
ResourceUavBarrier: Wrapper around D3D12_RESOURCE_UAV_BARRIER structure
RootConstants: Wrapper around D3D12_ROOT_CONSTANTS structure
RootDescriptor: Wrapper around D3D12_ROOT_DESCRIPTOR1 structure
RootDescriptorFlags
RootDescriptorTable: Wrapper around D3D12_ROOT_DESCRIPTOR_TABLE1 structure
RootParameter: Wrapper around D3D12_ROOT_PARAMETER1 structure
RootSignature
RootSignatureDesc: Wrapper around D3D12_ROOT_SIGNATURE_DESC1 structure
RootSignatureFlags
RtFormatArray: Wrapper around D3D12_RT_FORMAT_ARRAY structure
SampleDesc: Wrapper around DXGI_SAMPLE_DESC structure
SamplerDesc: Wrapper around D3D12_SAMPLER_DESC structure
ShaderBytecode: Wrapper around D3D12_SHADER_BYTECODE structure
ShaderComponentMapping
ShaderResourceViewDesc: Wrapper around D3D12_SHADER_RESOURCE_VIEW_DESC structure
SoDeclarationEntry: Wrapper around D3D12_SO_DECLARATION_ENTRY structure
StaticSamplerDesc: Wrapper around D3D12_STATIC_SAMPLER_DESC structure
StreamOutputDesc: Wrapper around D3D12_STREAM_OUTPUT_DESC structure
SubresourceData: Wrapper around D3D12_SUBRESOURCE_DATA structure
SubresourceFootprint: Wrapper around D3D12_SUBRESOURCE_FOOTPRINT structure
SwapChainDesc: Wrapper around DXGI_SWAP_CHAIN_DESC1 structure
SwapChainFlags
Swapchain
Tex1DArrayDsv: Wrapper around D3D12_TEX1D_ARRAY_DSV structure
Tex1DArraySrv: Wrapper around D3D12_TEX1D_ARRAY_SRV structure
Tex1DArrayUav: Wrapper around D3D12_TEX1D_ARRAY_UAV structure
Tex1DDsv: Wrapper around D3D12_TEX1D_DSV structure
Tex1DSrv: Wrapper around D3D12_TEX1D_SRV structure
Tex1DUav: Wrapper around D3D12_TEX1D_UAV structure
Tex2DArrayDsv: Wrapper around D3D12_TEX2D_ARRAY_DSV structure
Tex2DArraySrv: Wrapper around D3D12_TEX2D_ARRAY_SRV structure
Tex2DArrayUav: Wrapper around D3D12_TEX2D_ARRAY_UAV structure
Tex2DDsv: Wrapper around D3D12_TEX2D_DSV structure
Tex2DMsArraySrv: Wrapper around D3D12_TEX2DMS_ARRAY_SRV structure
Tex2DMsSrv: Wrapper around D3D12_TEX2DMS_SRV structure
Tex2DSrv: Wrapper around D3D12_TEX2D_SRV structure
Tex2DUav: Wrapper around D3D12_TEX2D_UAV structure
Tex2DmsArrayDsv: Wrapper around D3D12_TEX2DMS_ARRAY_DSV structure
Tex2DmsDsv: Wrapper around D3D12_TEX2DMS_DSV structure
Tex3DSrv: Wrapper around D3D12_TEX3D_SRV structure
Tex3DUav: Wrapper around D3D12_TEX3D_UAV structure
TexcubeArraySrv: Wrapper around D3D12_TEXCUBE_ARRAY_SRV structure
TexcubeSrv: Wrapper around D3D12_TEXCUBE_SRV structure
TextureCopyLocation: Wrapper around D3D12_TEXTURE_COPY_LOCATION structure
UnorderedAccessViewDesc: Wrapper around D3D12_UNORDERED_ACCESS_VIEW_DESC structure
Usage
VersionedRootSignatureDesc: Wrapper around D3D12_VERSIONED_ROOT_SIGNATURE_DESC structure
VertexBufferView: Wrapper around D3D12_VERTEX_BUFFER_VIEW structure
Viewport: Wrapper around D3D12_VIEWPORT structure
Win32Event