1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
// Copyright (c) 2016 The vulkano developers // Licensed under the Apache License, Version 2.0 // <LICENSE-APACHE or // https://www.apache.org/licenses/LICENSE-2.0> or the MIT // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, // at your option. All files in the project carrying such // notice may not be copied, modified, or distributed except // according to those terms. use crate::format::ClearValue; use crate::format::Format; use crate::image::ImageLayout; use crate::image::SampleCount; use crate::pipeline::shader::ShaderInterface; use crate::sync::AccessFlags; use crate::sync::PipelineStages; /// The description of a render pass. #[derive(Clone, Debug)] pub struct RenderPassDesc { attachments: Vec<AttachmentDesc>, subpasses: Vec<SubpassDesc>, dependencies: Vec<SubpassDependencyDesc>, multiview: Option<MultiviewDesc>, } impl RenderPassDesc { /// Creates a description of a render pass. pub fn new( attachments: Vec<AttachmentDesc>, subpasses: Vec<SubpassDesc>, dependencies: Vec<SubpassDependencyDesc>, ) -> RenderPassDesc { RenderPassDesc { attachments, subpasses, dependencies, multiview: None, } } /// Creates a description of a render pass that uses the multiview feature. /// See [`MultiviewDesc`] for an explanation of possible configuration options. pub fn with_multiview( attachments: Vec<AttachmentDesc>, subpasses: Vec<SubpassDesc>, dependencies: Vec<SubpassDependencyDesc>, multiview: MultiviewDesc, ) -> RenderPassDesc { RenderPassDesc { attachments, subpasses, dependencies, multiview: Some(multiview), } } /// Creates a description of an empty render pass, with one subpass and no attachments. pub fn empty() -> RenderPassDesc { RenderPassDesc { attachments: vec![], subpasses: vec![SubpassDesc { color_attachments: vec![], depth_stencil: None, input_attachments: vec![], resolve_attachments: vec![], preserve_attachments: vec![], }], dependencies: vec![], multiview: None, } } // Returns the attachments of the description. #[inline] pub fn attachments(&self) -> &[AttachmentDesc] { &self.attachments } // Returns the subpasses of the description. #[inline] pub fn subpasses(&self) -> &[SubpassDesc] { &self.subpasses } // Returns the dependencies of the description. #[inline] pub fn dependencies(&self) -> &[SubpassDependencyDesc] { &self.dependencies } // Returns the multiview configuration of the description. #[inline] pub fn multiview(&self) -> &Option<MultiviewDesc> { &self.multiview } /// Decodes `I` into a list of clear values where each element corresponds /// to an attachment. The size of the returned iterator must be the same as the number of /// attachments. /// /// When the user enters a render pass, they need to pass a list of clear values to apply to /// the attachments of the framebuffer. This method is then responsible for checking the /// correctness of these values and turning them into a list that can be processed by vulkano. /// /// The format of the clear value **must** match the format of the attachment. Attachments /// that are not loaded with `LoadOp::Clear` must have an entry equal to `ClearValue::None`. pub fn convert_clear_values<I>(&self, values: I) -> impl Iterator<Item = ClearValue> where I: IntoIterator<Item = ClearValue>, { // FIXME: safety checks values.into_iter() } /// Returns `true` if the subpass of this description is compatible with the shader's fragment /// output definition. pub fn is_compatible_with_shader( &self, subpass: u32, shader_interface: &ShaderInterface, ) -> bool { let pass_descr = match self.subpasses.get(subpass as usize) { Some(s) => s, None => return false, }; for element in shader_interface.elements() { for location in element.location.clone() { let attachment_id = match pass_descr.color_attachments.get(location as usize) { Some(a) => a.0, None => return false, }; let attachment_desc = &self.attachments[attachment_id]; // FIXME: compare formats depending on the number of components and data type /*if attachment_desc.format != element.format { return false; }*/ } } true } /// Returns `true` if this description is compatible with the other description, /// as defined in the `Render Pass Compatibility` section of the Vulkan specs. // TODO: return proper error pub fn is_compatible_with_desc(&self, other: &RenderPassDesc) -> bool { if self.attachments().len() != other.attachments().len() { return false; } for (my_atch, other_atch) in self.attachments.iter().zip(other.attachments.iter()) { if !my_atch.is_compatible_with(&other_atch) { return false; } } return true; // FIXME: finish } } impl Default for RenderPassDesc { fn default() -> Self { Self::empty() } } /// Describes an attachment that will be used in a render pass. #[derive(Debug, Clone, Copy)] pub struct AttachmentDesc { /// Format of the image that is going to be bound. pub format: Format, /// Number of samples of the image that is going to be bound. pub samples: SampleCount, /// What the implementation should do with that attachment at the start of the render pass. pub load: LoadOp, /// What the implementation should do with that attachment at the end of the render pass. pub store: StoreOp, /// Equivalent of `load` for the stencil component of the attachment, if any. Irrelevant if /// there is no stencil component. pub stencil_load: LoadOp, /// Equivalent of `store` for the stencil component of the attachment, if any. Irrelevant if /// there is no stencil component. pub stencil_store: StoreOp, /// Layout that the image is going to be in at the start of the renderpass. /// /// The vulkano library will automatically switch to the correct layout if necessary, but it /// is more efficient to set this to the correct value. pub initial_layout: ImageLayout, /// Layout that the image will be transitioned to at the end of the renderpass. pub final_layout: ImageLayout, } impl AttachmentDesc { /// Returns true if this attachment is compatible with another attachment, as defined in the /// `Render Pass Compatibility` section of the Vulkan specs. #[inline] pub fn is_compatible_with(&self, other: &AttachmentDesc) -> bool { self.format == other.format && self.samples == other.samples } } /// Describes one of the subpasses of a render pass. /// /// # Restrictions /// /// All these restrictions are checked when the `RenderPass` object is created. /// TODO: that's not the case ^ /// /// - The number of color attachments must be less than the limit of the physical device. /// - All the attachments in `color_attachments` and `depth_stencil` must have the same /// samples count. /// - If any attachment is used as both an input attachment and a color or /// depth/stencil attachment, then each use must use the same layout. /// - Elements of `preserve_attachments` must not be used in any of the other members. /// - If `resolve_attachments` is not empty, then all the resolve attachments must be attachments /// with 1 sample and all the color attachments must have more than 1 sample. /// - If `resolve_attachments` is not empty, all the resolve attachments must have the same format /// as the color attachments. /// - If the first use of an attachment in this renderpass is as an input attachment and the /// attachment is not also used as a color or depth/stencil attachment in the same subpass, /// then the loading operation must not be `Clear`. /// // TODO: add tests for all these restrictions // TODO: allow unused attachments (for example attachment 0 and 2 are used, 1 is unused) #[derive(Debug, Clone)] pub struct SubpassDesc { /// Indices and layouts of attachments to use as color attachments. pub color_attachments: Vec<(usize, ImageLayout)>, // TODO: Vec is slow /// Index and layout of the attachment to use as depth-stencil attachment. pub depth_stencil: Option<(usize, ImageLayout)>, /// Indices and layouts of attachments to use as input attachments. pub input_attachments: Vec<(usize, ImageLayout)>, // TODO: Vec is slow /// If not empty, each color attachment will be resolved into each corresponding entry of /// this list. /// /// If this value is not empty, it **must** be the same length as `color_attachments`. pub resolve_attachments: Vec<(usize, ImageLayout)>, // TODO: Vec is slow /// Indices of attachments that will be preserved during this pass. pub preserve_attachments: Vec<usize>, // TODO: Vec is slow } /// Describes a dependency between two subpasses of a render pass. /// /// The implementation is allowed to change the order of the subpasses within a render pass, unless /// you specify that there exists a dependency between two subpasses (ie. the result of one will be /// used as the input of another one). #[derive(Debug, Clone, Copy)] pub struct SubpassDependencyDesc { /// Index of the subpass that writes the data that `destination_subpass` is going to use. pub source_subpass: usize, /// Index of the subpass that reads the data that `source_subpass` wrote. pub destination_subpass: usize, /// The pipeline stages that must be finished on the previous subpass before the destination /// subpass can start. pub source_stages: PipelineStages, /// The pipeline stages of the destination subpass that must wait for the source to be finished. /// Stages that are earlier of the stages specified here can start before the source is /// finished. pub destination_stages: PipelineStages, /// The way the source subpass accesses the attachments on which we depend. pub source_access: AccessFlags, /// The way the destination subpass accesses the attachments on which we depend. pub destination_access: AccessFlags, /// If false, then the whole subpass must be finished for the next one to start. If true, then /// the implementation can start the new subpass for some given pixels as long as the previous /// subpass is finished for these given pixels. /// /// In other words, if the previous subpass has some side effects on other parts of an /// attachment, then you should set it to false. /// /// Passing `false` is always safer than passing `true`, but in practice you rarely need to /// pass `false`. pub by_region: bool, } /// Describes what the implementation should do with an attachment after all the subpasses have /// completed. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] #[repr(i32)] pub enum StoreOp { /// The attachment will be stored. This is what you usually want. /// /// While this is the most intuitive option, it is also slower than `DontCare` because it can /// take time to write the data back to memory. Store = ash::vk::AttachmentStoreOp::STORE.as_raw(), /// What happens is implementation-specific. /// /// This is purely an optimization compared to `Store`. The implementation doesn't need to copy /// from the internal cache to the memory, which saves memory bandwidth. /// /// This doesn't mean that the data won't be copied, as an implementation is also free to not /// use a cache and write the output directly in memory. In other words, the content of the /// image will be undefined. DontCare = ash::vk::AttachmentStoreOp::DONT_CARE.as_raw(), } impl From<StoreOp> for ash::vk::AttachmentStoreOp { #[inline] fn from(val: StoreOp) -> Self { Self::from_raw(val as i32) } } /// Describes what the implementation should do with an attachment at the start of the subpass. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] #[repr(i32)] pub enum LoadOp { /// The content of the attachment will be loaded from memory. This is what you want if you want /// to draw over something existing. /// /// While this is the most intuitive option, it is also the slowest because it uses a lot of /// memory bandwidth. Load = ash::vk::AttachmentLoadOp::LOAD.as_raw(), /// The content of the attachment will be filled by the implementation with a uniform value /// that you must provide when you start drawing. /// /// This is what you usually use at the start of a frame, in order to reset the content of /// the color, depth and/or stencil buffers. /// /// See the `draw_inline` and `draw_secondary` methods of `PrimaryComputeBufferBuilder`. Clear = ash::vk::AttachmentLoadOp::CLEAR.as_raw(), /// The attachment will have undefined content. /// /// This is what you should use for attachments that you intend to entirely cover with draw /// commands. /// If you are going to fill the attachment with a uniform value, it is better to use `Clear` /// instead. DontCare = ash::vk::AttachmentLoadOp::DONT_CARE.as_raw(), } impl From<LoadOp> for ash::vk::AttachmentLoadOp { #[inline] fn from(val: LoadOp) -> Self { Self::from_raw(val as i32) } } /// Describes the `multiview` configuration for the render pass which is used to draw /// to multiple layers of a framebuffer inside of a single render pass. #[derive(Debug, Clone)] pub struct MultiviewDesc { /// The view masks indicate which layers of the framebuffer should be rendered for each subpass. /// Values are bit masks which means that for example `0b11` will draw to the first two layers /// and `0b101` will draw to the first and third layer. pub view_masks: Vec<u32>, /// The correlation masks indicate sets of views that may be more efficient to render /// concurrently (usually because they show the same geometry from almost the same perspective). /// Values are bit masks which means that for example `0b11` means the first two layers are /// highly correlated and `0b101` means the first and third layer are highly correlated. pub correlation_masks: Vec<u32>, /// The view offsets contain additional information for each subpass dependency that indicate /// which views in the source subpass the views of the destination subpass depend on. pub view_offsets: Vec<i32>, } impl MultiviewDesc { /// Returns the index of the layer with the biggest index that is /// referred to by a mask in the multiview description. pub fn highest_used_layer(&self) -> u32 { self.view_masks .iter() .chain(self.correlation_masks.iter()) .map(|&mask| 32 - mask.leading_zeros()) // the highest set bit corresponds to the highest used layer .max() .unwrap_or(0) } /// Returns the amount of layers that are used in the multiview description. pub fn used_layer_count(&self) -> u32 { self.view_masks .iter() .chain(self.correlation_masks.iter()) .fold(0, |acc, &mask| acc | mask) .count_ones() } } /// Possible resolve modes for depth and stencil attachments. #[derive(Clone, Copy, Debug, PartialEq, Eq)] #[repr(u32)] pub enum ResolveMode { None = ash::vk::ResolveModeFlags::NONE.as_raw(), SampleZero = ash::vk::ResolveModeFlags::SAMPLE_ZERO.as_raw(), Average = ash::vk::ResolveModeFlags::AVERAGE.as_raw(), Min = ash::vk::ResolveModeFlags::MIN.as_raw(), Max = ash::vk::ResolveModeFlags::MAX.as_raw(), } #[derive(Clone, Copy, Debug)] pub struct ResolveModes { pub none: bool, pub sample_zero: bool, pub average: bool, pub min: bool, pub max: bool, } impl From<ash::vk::ResolveModeFlags> for ResolveModes { #[inline] fn from(val: ash::vk::ResolveModeFlags) -> Self { Self { none: val.intersects(ash::vk::ResolveModeFlags::NONE), sample_zero: val.intersects(ash::vk::ResolveModeFlags::SAMPLE_ZERO), average: val.intersects(ash::vk::ResolveModeFlags::AVERAGE), min: val.intersects(ash::vk::ResolveModeFlags::MIN), max: val.intersects(ash::vk::ResolveModeFlags::MAX), } } }