Crate rusty_d3d12
source · [−]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
andset_*(&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
andDXGI
prefixes have been stripped from all types, functions and enum variants (e.g. this library exposesCommandListType::Direct
instead ofD3D12_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 ofGetGPUDescriptorHandleForHeapStart
). 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 is1.600.10
- PIX markers (they require enabling
pix
feature which is off by default not to introduce a dependency onWinPixEventRuntime.dll
for people who don’t need it) - automatic COM object reference counting via
Clone
andDrop
traits implementations with optional logging possibilities (e.g. seeimpl_com_object_refcount_named
macro) - D3D12 debug callback support (please note that
debug_callback
feature needs to be activated explicitly sinceID3D12InfoQueue1
interface is only supported on Windows 11), object autonaming and GPU validation - convenience macros for wrapping API calls (
dx_call!
anddx_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 asunsafe
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. Sounsafe
is reserved for something unsafe that happens on Rust side, e.g. accessing unions (seeClearValue::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
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