1 // Copyright (c) 2016 The vulkano developers 2 // Licensed under the Apache License, Version 2.0 3 // <LICENSE-APACHE or 4 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT 5 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, 6 // at your option. All files in the project carrying such 7 // notice may not be copied, modified, or distributed except 8 // according to those terms. 9 10 //! Describes a graphical or compute operation. 11 //! 12 //! In Vulkan, before you can add a draw or a compute command to a command buffer you have to 13 //! create a *pipeline object* that describes this command. 14 //! 15 //! When you create a pipeline object, the implementation will usually generate some GPU machine 16 //! code that will execute the operation (similar to a compiler that generates an executable for 17 //! the CPU). Consequently it is a CPU-intensive operation that should be performed at 18 //! initialization or during a loading screen. 19 //! 20 //! There are two kinds of pipelines: 21 //! 22 //! - `ComputePipeline`s, for compute operations (general-purpose operations that read/write data 23 //! in buffers or raw pixels in images). 24 //! - `GraphicsPipeline`s, for graphical operations (operations that take vertices as input and 25 //! write pixels to a framebuffer). 26 //! 27 //! # Creating a compute pipeline. 28 //! 29 //! In order to create a compute pipeline, you first need a *shader entry point*. 30 //! 31 //! TODO: write the rest 32 //! For now vulkano has no "clean" way to create shaders ; everything's a bit hacky 33 //! 34 //! # Creating a graphics pipeline 35 //! 36 //! A graphics operation takes vertices or vertices and indices as input, and writes pixels to a 37 //! framebuffer. It consists of multiple steps: 38 //! 39 //! - A *shader* named the *vertex shader* is run once for each vertex of the input. 40 //! - Vertices are assembled into primitives. 41 //! - Optionally, a shader named the *tessellation control shader* is run once for each primitive 42 //! and indicates the tessellation level to apply for this primitive. 43 //! - Optionally, a shader named the *tessellation evaluation shader* is run once for each vertex, 44 //! including the ones newly created by the tessellation. 45 //! - Optionally, a shader named the *geometry shader* is run once for each line or triangle. 46 //! - The vertex coordinates (as outputted by the geometry shader, or by the tessellation 47 //! evaluation shader if there's no geometry shader, or by the vertex shader if there's no 48 //! geometry shader nor tessellation evaluation shader) are turned into screen-space coordinates. 49 //! - The list of pixels that cover each triangle are determined. 50 //! - A shader named the fragment shader is run once for each pixel that covers one of the 51 //! triangles. 52 //! - The depth test and/or the stencil test are performed. 53 //! - The output of the fragment shader is written to the framebuffer attachments, possibly by 54 //! mixing it with the existing values. 55 //! 56 //! All the sub-modules of this module (with the exception of `cache`) correspond to the various 57 //! stages of graphical pipelines. 58 //! 59 //! > **Note**: With the exception of the addition of the tessellation shaders and the geometry 60 //! > shader, these steps haven't changed in the past decade. If you are familiar with shaders in 61 //! > OpenGL 2 for example, don't worry as it works in the same in Vulkan. 62 //! 63 //! > **Note**: All the stages that consist in executing a shader are performed by a microprocessor 64 //! > (unless you happen to use a software implementation of Vulkan). As for the other stages, 65 //! > some hardware (usually desktop graphics cards) have dedicated chips that will execute them 66 //! > while some other hardware (usually mobile) perform them with the microprocessor as well. In 67 //! > the latter situation, the implementation will usually glue these steps to your shaders. 68 //! 69 //! Creating a graphics pipeline follows the same principle as a compute pipeline, except that 70 //! you must pass multiple shaders alongside with configuration for the other steps. 71 //! 72 //! TODO: add an example 73 74 // TODO: graphics pipeline params are deprecated, but are still the primary implementation in order 75 // to avoid duplicating code, so we hide the warnings for now 76 #![allow(deprecated)] 77 78 pub use self::compute_pipeline::ComputePipeline; 79 pub use self::compute_pipeline::ComputePipelineAbstract; 80 pub use self::compute_pipeline::ComputePipelineCreationError; 81 pub use self::compute_pipeline::ComputePipelineSys; 82 pub use self::graphics_pipeline::GraphicsPipeline; 83 pub use self::graphics_pipeline::GraphicsPipelineAbstract; 84 pub use self::graphics_pipeline::GraphicsPipelineBuilder; 85 pub use self::graphics_pipeline::GraphicsPipelineCreationError; 86 pub use self::graphics_pipeline::GraphicsPipelineSys; 87 88 pub mod blend; 89 pub mod cache; 90 mod compute_pipeline; 91 pub mod depth_stencil; 92 mod graphics_pipeline; 93 pub mod input_assembly; 94 pub mod layout; 95 pub mod multisample; 96 pub mod raster; 97 pub mod shader; 98 pub mod vertex; 99 pub mod viewport; 100 101 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] 102 #[repr(i32)] 103 pub enum PipelineBindPoint { 104 Compute = ash::vk::PipelineBindPoint::COMPUTE.as_raw(), 105 Graphics = ash::vk::PipelineBindPoint::GRAPHICS.as_raw(), 106 } 107 108 impl From<PipelineBindPoint> for ash::vk::PipelineBindPoint { 109 #[inline] from(val: PipelineBindPoint) -> Self110 fn from(val: PipelineBindPoint) -> Self { 111 Self::from_raw(val as i32) 112 } 113 } 114