Crate gfx

gfx

An efficient, low-level, bindless graphics API for Rust.

Overview

Command buffers and encoders

A command buffer is a serialized list of drawing and compute commands. Unlike with vulkan, command buffers are not what you use to create commands, but only the result of creating these commands. Gfx, borrowing metal’s terminology, uses encoders to build command buffers. This means that, in general, users of the gfx crate don’t manipulate command buffers directly much and interact mostly with encoders.

Manipulating an Encoder in gfx corresponds to interacting with:

• a VkCommandBuffer in vulkan,
• a MTLCommandEncoder in metal,
• an ID3D12GraphicsCommandList in D3D12.

OpenGL and earlier versions of D3D don’t have an explicit notion of command buffers or encoders (with the exception of draw indirect commands in late versions of OpenGL, which can be seen as a GPU-side command buffer). They are managed implicitly by the driver.

See:

• The Encoder struct documentation.
• The Command buffer trait documentation.

Factory

The factory is what lets you allocate GPU resources such as buffers and textures.

Each gfx backend provides its own factory type which implements both:

• The Factory trait.
• The FactoryExt trait.

gfx::Factory is roughly equivalent to:

• VkDevice in vulkan,
• ID3D11Device in D3D11,
• MTLDevice in metal.

OpenGL does not have a notion of factory (resources are created directly off of the global context). D3D11 has a DXGI factory but it is only used to interface with other processes and the window manager, resources like textures are usually created using the device.

Device

See the gfx::Device trait.

Pipeline state (PSO)

See the documentation of the gfx::pso module.

Memory management

Handles internally use atomically reference counted pointers to deal with memory management. GPU resources are not destroyed right away when all references to them are gone. Instead they are destroyed the next time Device::cleanup is called.

Examples

See the examples in the repository.

Useful resources

• Documentation for some of the technical terms used in the API.
• Learning gfx tutorial.
• See the blog for more explanations and annotated examples.

Re-exports

• pub use pso::PipelineState;
• pub use pso::buffer::VertexBuffer;
• pub use pso::buffer::InstanceBuffer;
• pub use pso::buffer::RawVertexBuffer;
• pub use pso::buffer::ConstantBuffer;
• pub use pso::buffer::RawConstantBuffer;
• pub use pso::buffer::Global;
• pub use pso::buffer::RawGlobal;
• pub use pso::resource::ShaderResource;
• pub use pso::resource::RawShaderResource;
• pub use pso::resource::UnorderedAccess;
• pub use pso::resource::Sampler;
• pub use pso::resource::TextureSampler;
• pub use pso::target::DepthStencilTarget;
• pub use pso::target::DepthTarget;
• pub use pso::target::StencilTarget;
• pub use pso::target::RenderTarget;
• pub use pso::target::RawRenderTarget;
• pub use pso::target::BlendTarget;
• pub use pso::target::BlendRef;
• pub use pso::target::Scissor;
• pub use pso::bundle::Bundle;

Modules

• buffer
  Memory buffers
• format
  Universal format specification. Applicable to textures, views, and vertex buffers.
• handle
  Resource handles
• macros
  Convenience macros Various helper macros.
• mapping
  Memory mapping
• memory
  Types to describe the properties of memory allocated for gfx resources.
• preset
  State presets
• pso
  A typed high-level graphics pipeline interface.
• shade
  Shaders Shader parameter handling.
• state
  Fixed-function hardware state.
• texture
  Texture creation and modification.
• traits
  public re-exported traits

Macros

• gfx_constant_struct
  Defines a structure that is used in a constant buffer.
• gfx_defines
  Defines vertex, constant and pipeline formats in one block.
• gfx_format
  Defines a shorthand for a format.
• gfx_pipeline
  Defines a set of pipeline-associated structures, and also adds new constuctor for the Init structure.
• gfx_pipeline_base
  Defines a set of pipeline-associated structures.
• gfx_vertex_struct
  Defines a structure that is used in a vertex buffer.

Structs

• DomainShader
• Encoder
  Graphics Command Encoder
• GeometryShader
• HullShader
• Mirror
  Mirroring flags, used for blitting
• PixelShader
• ProgramInfo
  Metadata about a program.
• Rect
  A screen space rectangle
• Slice
  A Slice dictates in which and in what order vertices get processed. It is required for processing a PSO.
• VertexShader

Enums

• CombinedError
  An error from creating textures with views at the same time.
• CopyError
  An error occuring in memory copies.
• IndexBuffer
  Type of index-buffer used in a Slice.
• PipelineStateError
  Error creating a PipelineState
• Primitive
  Describes what geometric primitives are created from vertex data.
• ResourceViewError
  Error creating either a ShaderResourceView, or UnorderedAccessView.
• ShaderSet
  A complete set of shaders to link a program. TODO: TransformFeedback
• SubmissionError
• TargetViewError
  Error creating either a RenderTargetView, or DepthStencilView.
• UniformValue
  A value that can be uploaded to the device as a uniform.
• UpdateError
  An error occuring in buffer/texture updates.

Traits

• CommandBuffer
  An interface of the abstract command buffer. It collects commands in an efficient API-specific manner, to be ready for execution on the device.
• Device
  A Device is responsible for submitting CommandBuffers to the GPU.
• Factory
  Overview
• IntoIndexBuffer
  A helper trait to create IndexBuffers from different kinds of data.
• Resources
  Different types of a specific API.

Type Definitions

• ColorValue
  A color with floating-point components.
• CopyBufferResult
  Result type returned when copying a buffer into another buffer.
• CopyBufferTextureResult
  Result type returned when copying buffer data into a texture.
• CopyTextureBufferResult
  Result type returned when copying texture data into a buffer.
• Depth
  A single depth value from a depth buffer.
• InstanceCount
  Draw number of instances
• InstanceParams
  Optional instance parameters: (instance count, buffer offset)
• Layer
  A depth value, specifying which plane to select out of a 3D texture.
• Level
  Mipmap level to select in a texture.
• Stencil
  A single value from a stencil stencstencil buffer.
• SubmissionResult
• VertexCount
  Draw vertex count.