gfx/
lib.rs

1// Copyright 2015 The Gfx-rs Developers.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![deny(missing_docs)]
16
17//! # gfx
18//!
19//! An efficient, low-level, bindless graphics API for Rust.
20//!
21//! # Overview
22//!
23//! ## Command buffers and encoders
24//!
25//! A command buffer is a serialized list of drawing and compute commands.
26//! Unlike with vulkan, command buffers are not what you use to create commands, but only
27//! the result of creating these commands. Gfx, borrowing metal's terminology, uses
28//! encoders to build command buffers. This means that, in general, users of the gfx crate
29//! don't manipulate command buffers directly much and interact mostly with encoders.
30//!
31//! Manipulating an `Encoder` in gfx corresponds to interacting with:
32//!
33//! - a `VkCommandBuffer` in vulkan,
34//! - a `MTLCommandEncoder` in metal,
35//! - an `ID3D12GraphicsCommandList` in D3D12.
36//!
37//! OpenGL and earlier versions of D3D don't have an explicit notion of command buffers
38//! or encoders (with the exception of draw indirect commands in late versions of OpenGL,
39//! which can be seen as a GPU-side command buffer). They are managed implicitly by the driver.
40//!
41//! See:
42//!
43//! - The [`Encoder` struct documentation](struct.Encoder.html).
44//! - The [`Command buffer` trait documentation](trait.CommandBuffer.html).
45//!
46//! ## Factory
47//!
48//! The factory is what lets you allocate GPU resources such as buffers and textures.
49//!
50//! Each gfx backend provides its own factory type which implements both:
51//!
52//! - The [`Factory` trait](traits/trait.Factory.html#overview).
53//! - The [`FactoryExt` trait](traits/trait.FactoryExt.html).
54//!
55//! `gfx::Factory` is roughly equivalent to:
56//!
57//! - `VkDevice` in vulkan,
58//! - `ID3D11Device` in D3D11,
59//! - `MTLDevice` in metal.
60//!
61//! OpenGL does not have a notion of factory (resources are created directly off of the global
62//! context). D3D11 has a DXGI factory but it is only used to interface with other processes
63//! and the window manager, resources like textures are usually created using the device.
64//!
65//! ## Device
66//!
67//! See [the `gfx::Device` trait](trait.Device.html).
68//!
69//! ## Pipeline state (PSO)
70//!
71//! See [the documentation of the gfx::pso module](pso/index.html).
72//!
73//! ## Memory management
74//!
75//! Handles internally use atomically reference counted pointers to deal with memory management.
76//! GPU resources are not destroyed right away when all references to them are gone. Instead they
77//! are destroyed the next time [Device::cleanup](trait.Device.html#tymethod.cleanup) is called.
78//!
79//! # Examples
80//!
81//! See [the examples in the repository](https://github.com/gfx-rs/gfx/tree/master/examples).
82//!
83//! # Useful resources
84//!
85//!  - [Documentation for some of the technical terms](doc/terminology/index.html)
86//! used in the API.
87//!  - [Learning gfx](https://wiki.alopex.li/LearningGfx) tutorial.
88//!  - See [the blog](http://gfx-rs.github.io/) for more explanations and annotated examples.
89//!
90
91#[cfg(feature = "mint")]
92extern crate mint;
93
94extern crate log;
95extern crate draw_state;
96extern crate gfx_core as core;
97
98/// public re-exported traits
99pub mod traits {
100    pub use core::{Device, Factory};
101    pub use core::memory::Pod;
102    pub use factory::FactoryExt;
103}
104
105// draw state re-exports
106pub use draw_state::{preset, state};
107pub use draw_state::target::*;
108
109// public re-exports
110pub use core::{Device, Primitive, Resources, SubmissionError, SubmissionResult};
111pub use core::{VertexCount, InstanceCount};
112pub use core::{ShaderSet, VertexShader, HullShader, DomainShader, GeometryShader, PixelShader};
113pub use core::{buffer, format, handle, mapping, memory, texture};
114pub use core::factory::{Factory, ResourceViewError, TargetViewError, CombinedError};
115pub use core::command::{Buffer as CommandBuffer, InstanceParams};
116pub use core::shade::{ProgramInfo, UniformValue};
117
118pub use encoder::{CopyBufferResult, CopyBufferTextureResult, CopyError,
119                  CopyTextureBufferResult, Encoder, UpdateError};
120pub use factory::PipelineStateError;
121pub use slice::{Slice, IntoIndexBuffer, IndexBuffer};
122pub use pso::{PipelineState};
123pub use pso::buffer::{VertexBuffer, InstanceBuffer, RawVertexBuffer,
124                      ConstantBuffer, RawConstantBuffer, Global, RawGlobal};
125pub use pso::resource::{ShaderResource, RawShaderResource, UnorderedAccess,
126                        Sampler, TextureSampler};
127pub use pso::target::{DepthStencilTarget, DepthTarget, StencilTarget,
128                      RenderTarget, RawRenderTarget, BlendTarget, BlendRef, Scissor};
129pub use pso::bundle::{Bundle};
130
131/// Render commands encoder
132mod encoder;
133/// Factory extensions
134mod factory;
135/// Slices
136mod slice;
137// Pipeline states
138pub mod pso;
139/// Shaders
140pub mod shade;
141/// Convenience macros
142pub mod macros;
gfx/lib.rs

gfx/
lib.rs
