Doc fixes (#1007)

* Use 'greater than' instead of 'superior to'.

Using 'X is superior to Y' to mean 'X > Y' is not standard mathematical usage. I
think I've seen 'superior to' used in lattice theory, but that's not relevant to
these cases.

* trait RenderPassDesc: Correctly describe when `None` is returned.

This seems to be an off-by-one error in the documentation. Looking at the
implementations generated in `src/framebuffer/macros.rs`, for example,
the various elements of each sequence are numbered from 0 to n-1.

* Typo: 'anistropic' -> 'anisotropic'.

* sampler::MipmapMode::Linear: Clarify description.

The docs seem to suggest that if the dimensions match a given level D, then
`Linear` would use levels D-1 and D+1, which is senseless. The new wording is
meant to be closer to the calculation described in Vulkan 1.1.82 §15.6.7.

* Typo: 'transitionned' -> 'transitioned', and similar.

* Doc fix: 'more optimal' -> 'more efficient'

Rationale for the curious:

'Optimal' is an absolute; once something is optimal, it cannot be made more so.
Absolutes can be weakened, as in 'almost optimal', but not strengthened, as in
'more optimal' or 'very optimal'. 'Efficient' is not an absolute: one thing
might be 'more efficient' than another.

* Minor doc fixes.

* Doc fix: 'performances' -> 'performance' throughout.

vulkano-shaders/src/descriptor_sets.rs

@@ -61,7 +61,7 @@ pub fn write_descriptor_sets(doc: &parse::Spirv) -> String {
             .next()
             .expect(&format!("Uniform `{}` is missing a binding", name));
 
-        // Find informations about the kind of binding for this descriptor.
+        // Find information about the kind of binding for this descriptor.
         let (desc_ty, readonly, array_count) = descriptor_infos(doc, pointed_ty, false)
             .expect(&format!("Couldn't find relevant type for uniform `{}` (type {}, maybe \
                               unimplemented)",

vulkano/src/command_buffer/auto.rs

@@ -582,7 +582,7 @@ impl<P> AutoCommandBufferBuilder<P> {
     ///   the extent. Same for the Y coordinate for one-dimensional images.
     /// - For non-array images, the base array layer must be 0 and the number of layers must be 1.
     ///
-    /// If `layer_count` is superior to 1, the copy will happen between each individual layer as
+    /// If `layer_count` is greater than 1, the copy will happen between each individual layer as
     /// if they were separate images.
     ///
     /// # Panic
@@ -667,7 +667,7 @@ impl<P> AutoCommandBufferBuilder<P> {
     ///   the bottom-right offset. Same for the Y coordinate for one-dimensional images.
     /// - For non-array images, the base array layer must be 0 and the number of layers must be 1.
     ///
-    /// If `layer_count` is superior to 1, the blit will happen between each individual layer as
+    /// If `layer_count` is greater than 1, the blit will happen between each individual layer as
     /// if they were separate images.
     ///
     /// # Panic

vulkano/src/command_buffer/mod.rs

@@ -25,7 +25,7 @@
 //!   commands (ie. everything but drawing, clearing, etc.) and cannot enter a render pass. They
 //!   can only be called from a primary command buffer outside of a render pass.
 //!
-//! Using secondary command buffers leads to slightly lower performances on the GPU, but they have
+//! Using secondary command buffers leads to slightly lower performance on the GPU, but they have
 //! two advantages on the CPU side:
 //!
 //! - Building a command buffer is a single-threaded operation, but by using secondary command

vulkano/src/command_buffer/synced/base.rs

@@ -459,7 +459,7 @@ impl<P> SyncCommandBufferBuilder<P> {
     // `exclusive`, `stages` and `access` must match the way the resource has been used.
     //
     // `start_layout` and `end_layout` designate the image layout that the image is expected to be
-    // in when the command starts, and the image layout that the image will be transitionned to
+    // in when the command starts, and the image layout that the image will be transitioned to
     // during the command. When it comes to buffers, you should pass `Undefined` for both.
     pub(super) fn prev_cmd_resource(&mut self, resource_ty: KeyTy, resource_index: usize,
                                     exclusive: bool, stages: PipelineStages,

vulkano/src/format.rs

@@ -790,7 +790,7 @@ impl FormatTy {
 }
 
 /// Describes a uniform value that will be used to fill an image.
-// TODO: should have the same layout as `vk::ClearValue` for performances
+// TODO: should have the same layout as `vk::ClearValue` for performance
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub enum ClearValue {
     /// Entry for attachments that aren't cleared.

vulkano/src/framebuffer/desc.rs

@@ -48,7 +48,7 @@ pub unsafe trait RenderPassDesc: RenderPassDescClearValues<Vec<ClearValue>> {
 
     /// Returns the description of an attachment.
     ///
-    /// Returns `None` if `num` is superior to `num_attachments()`.
+    /// Returns `None` if `num` is greater than or equal to `num_attachments()`.
     fn attachment_desc(&self, num: usize) -> Option<LayoutAttachmentDescription>;
 
     /// Returns an iterator to the list of attachments.
@@ -67,7 +67,7 @@ pub unsafe trait RenderPassDesc: RenderPassDescClearValues<Vec<ClearValue>> {
 
     /// Returns the description of a subpass.
     ///
-    /// Returns `None` if `num` is superior to `num_subpasses()`.
+    /// Returns `None` if `num` is greater than or equal to `num_subpasses()`.
     fn subpass_desc(&self, num: usize) -> Option<LayoutPassDescription>;
 
     /// Returns an iterator to the list of subpasses.
@@ -86,7 +86,7 @@ pub unsafe trait RenderPassDesc: RenderPassDescClearValues<Vec<ClearValue>> {
 
     /// Returns the description of a dependency.
     ///
-    /// Returns `None` if `num` is superior to `num_dependencies()`.
+    /// Returns `None` if `num` is greater than or equal to `num_dependencies()`.
     fn dependency_desc(&self, num: usize) -> Option<LayoutPassDependencyDescription>;
 
     /// Returns an iterator to the list of dependencies.
@@ -443,10 +443,10 @@ pub struct LayoutAttachmentDescription {
     /// 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 optimal to set this to the correct value.
+    /// is more efficient to set this to the correct value.
     pub initial_layout: ImageLayout,
 
-    /// Layout that the image will be transitionned to at the end of the renderpass.
+    /// Layout that the image will be transitioned to at the end of the renderpass.
     pub final_layout: ImageLayout,
 }
 

vulkano/src/framebuffer/sys.rs

@@ -376,7 +376,7 @@ impl<D> RenderPass<D> {
     /// Returns the granularity of this render pass.
     ///
     /// If the render area of a render pass in a command buffer is a multiple of this granularity,
-    /// then the performances will be optimal. Performances are always optimal for render areas
+    /// then the performance will be optimal. Performances are always optimal for render areas
     /// that cover the whole framebuffer.
     pub fn granularity(&self) -> [u32; 2] {
         let mut granularity = self.granularity.lock().unwrap();

vulkano/src/image/attachment.rs

@@ -69,7 +69,7 @@ use sync::Sharing;
 /// In other words, if you are going to read from the image after drawing to it, use a regular
 /// image. If you don't need to read from it (for example if it's some kind of intermediary color,
 /// or a depth buffer that is only used once) then use a transient image as it may improve
-/// performances.
+/// performance.
 ///
 // TODO: forbid reading transient images outside render passes?
 #[derive(Debug)]

vulkano/src/image/layout.rs

@@ -17,14 +17,14 @@ use vk;
 ///
 /// In the Vulkan API, each mipmap level of each array layer is in one of the layouts of this enum.
 ///
-/// Unless you use some short of high-level shortcut function, an image always starts in either
+/// Unless you use some sort of high-level shortcut function, an image always starts in either
 /// the `Undefined` or the `Preinitialized` layout.
 /// Before you can use an image for a given purpose, you must ensure that the image in question is
 /// in the layout required for that purpose. For example if you want to write data to an image, you
 /// must first transition the image to the `TransferDstOptimal` layout. The `General` layout can
 /// also be used as a general-purpose fit-all layout, but using it will result in slower operations.
 ///
-/// Transitionning between layouts can only be done through a GPU-side operation that is part of
+/// Transitioning between layouts can only be done through a GPU-side operation that is part of
 /// a command buffer.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[repr(u32)]

vulkano/src/image/mod.rs

@@ -7,10 +7,10 @@
 // notice may not be copied, modified, or distributed except
 // according to those terms.
 
-//! Images storage (1D, 2D, 3D, arrays, etc.).
+//! Image storage (1D, 2D, 3D, arrays, etc.).
 //!
-//! An *image* is a location in memory whose purpose is to store multi-dimensional data. Its
-//! most common usage is to store a 2D array of color pixels (in other words an *image* in the
+//! An *image* is a region of memory whose purpose is to store multi-dimensional data. Its
+//! most common use is to store a 2D array of color pixels (in other words an *image* in
 //! everyday language), but it can also be used to store arbitrary data.
 //!
 //! The advantage of using an image compared to a buffer is that the memory layout is optimized
@@ -22,8 +22,8 @@
 //!
 //! # Images and image views
 //!
-//! There is a distinction between *images* and *image views*. As its name tells, an image view
-//! describes how the GPU must interpret the image.
+//! There is a distinction between *images* and *image views*. As its name suggests, an image
+//! view describes how the GPU must interpret the image.
 //!
 //! Transfer and memory operations operate on images themselves, while reading/writing an image
 //! operates on image views. You can create multiple image views from the same image.
@@ -41,7 +41,7 @@
 //! - An `ImmutableImage` stores data which never need be changed after the initial upload,
 //!   like a texture.
 //!
-//! # Low-level informations
+//! # Low-level information
 //!
 //! To be written.
 //!

vulkano/src/image/sys.rs

@@ -50,7 +50,7 @@ use vk;
 /// - The memory that you bind to the image must be manually kept alive.
 /// - The queue family ownership must be manually enforced.
 /// - The usage must be manually enforced.
-/// - The image layout must be manually enforced and transitionned.
+/// - The image layout must be manually enforced and transitioned.
 ///
 pub struct UnsafeImage {
     image: vk::Image,

vulkano/src/image/traits.rs

@@ -189,7 +189,7 @@ pub unsafe trait ImageAccess {
 
     /// Unlocks the resource previously acquired with `try_gpu_lock` or `increase_gpu_lock`.
     ///
-    /// If the GPU operation that we unlock from transitionned the image to another layout, then
+    /// If the GPU operation that we unlock from transitioned the image to another layout, then
     /// it should be passed as parameter.
     ///
     /// A layout transition requires exclusive access to the image, which means two things:
@@ -202,11 +202,11 @@ pub unsafe trait ImageAccess {
     /// # Safety
     ///
     /// - Must only be called once per previous lock.
-    /// - The transitionned layout must be supported by the image (eg. the layout shouldn't be
+    /// - The transitioned layout must be supported by the image (eg. the layout shouldn't be
     ///   `ColorAttachmentOptimal` if the image wasn't created with the `color_attachment` usage).
-    /// - The transitionned layout must not be `Undefined`.
+    /// - The transitioned layout must not be `Undefined`.
     ///
-    unsafe fn unlock(&self, transitionned_layout: Option<ImageLayout>);
+    unsafe fn unlock(&self, transitioned_layout: Option<ImageLayout>);
 }
 
 /// Inner information about an image.
@@ -274,8 +274,8 @@ unsafe impl<T> ImageAccess for T
     }
 
     #[inline]
-    unsafe fn unlock(&self, transitionned_layout: Option<ImageLayout>) {
-        (**self).unlock(transitionned_layout)
+    unsafe fn unlock(&self, transitioned_layout: Option<ImageLayout>) {
+        (**self).unlock(transitioned_layout)
     }
 }
 

vulkano/src/instance/instance.rs

@@ -52,7 +52,7 @@ use version::Version;
 ///
 /// A layer is a component that will hook and potentially modify the Vulkan function calls.
 /// For example, activating a layer could add a frames-per-second counter on the screen, or it
-/// could send informations to a debugger that will debug your application.
+/// could send information to a debugger that will debug your application.
 ///
 /// > **Note**: From an application's point of view, layers "just exist". In practice, on Windows
 /// > and Linux layers can be installed by third party installers or by package managers and can

vulkano/src/memory/mod.rs

@@ -140,7 +140,7 @@ impl MemoryRequirements {
 
 /// Indicates whether we want to allocate memory for a specific resource, or in a generic way.
 ///
-/// Using dedicated allocations can yield faster performances, but requires the
+/// Using dedicated allocations can yield better performance, but requires the
 /// `VK_KHR_dedicated_allocation` extension to be enabled on the device.
 ///
 /// If a dedicated allocation is performed, it must only be bound to any resource other than the

vulkano/src/pipeline/graphics_pipeline/creation_error.rs

@@ -117,7 +117,7 @@ pub enum GraphicsPipelineCreationError {
     /// The minimum or maximum bounds of viewports have been exceeded.
     ViewportBoundsExceeded,
 
-    /// The `wide_lines` feature must be enabled in order to use a line width superior to 1.0.
+    /// The `wide_lines` feature must be enabled in order to use a line width greater than 1.0.
     WideLinesFeatureNotEnabled,
 
     /// The `depth_clamp` feature must be enabled in order to use depth clamping.
@@ -257,7 +257,7 @@ impl error::Error for GraphicsPipelineCreationError {
             },
             GraphicsPipelineCreationError::WideLinesFeatureNotEnabled => {
                 "the `wide_lines` feature must be enabled in order to use a line width \
-                 superior to 1.0"
+                 greater than 1.0"
             },
             GraphicsPipelineCreationError::DepthClampFeatureNotEnabled => {
                 "the `depth_clamp` feature must be enabled in order to use depth clamping"

vulkano/src/sampler.rs

@@ -152,12 +152,12 @@ impl Sampler {
     ///
     /// `mip_lod_bias` is a value to add to .
     ///
-    /// `max_anisotropy` must be superior or equal to 1.0. If superior to 1.0, the implementation
-    /// will use anistropic filtering. Using a value superior to 1.0 requires the
-    /// `sampler_anisotropy` feature to be enabled when creating the device.
+    /// `max_anisotropy` must be greater than or equal to 1.0. If greater than 1.0, the
+    /// implementation will use anisotropic filtering. Using a value greater than 1.0 requires
+    /// the `sampler_anisotropy` feature to be enabled when creating the device.
     ///
     /// `min_lod` and `max_lod` are respectively the minimum and maximum mipmap level to use.
-    /// `max_lod` must always be superior or equal to `min_lod`.
+    /// `max_lod` must always be greater than or equal to `min_lod`.
     ///
     /// # Panic
     ///
@@ -527,8 +527,8 @@ pub enum MipmapMode {
     /// Use the mipmap whose dimensions are the nearest to the dimensions of the destination.
     Nearest = vk::SAMPLER_MIPMAP_MODE_NEAREST,
 
-    /// Take the two mipmaps whose dimensions are immediately inferior and superior to the
-    /// dimensions of the destination, calculate the value for both, and interpolate them.
+    /// Take the mipmap whose dimensions are no greater than that of the destination together
+    /// with the next higher level mipmap, calculate the value for both, and interpolate them.
     Linear = vk::SAMPLER_MIPMAP_MODE_LINEAR,
 }
 
@@ -658,8 +658,8 @@ pub enum SamplerCreationError {
     /// Note the specs guarantee that at least 4000 samplers can exist simultaneously.
     TooManyObjects,
 
-    /// Using an anisotropy superior to 1.0 requires enabling the `sampler_anisotropy` feature when
-    /// creating the device.
+    /// Using an anisotropy greater than 1.0 requires enabling the `sampler_anisotropy` feature
+    /// when creating the device.
     SamplerAnisotropyFeatureNotEnabled,
 
     /// The requested anisotropy level exceeds the device's limits.

vulkano/src/swapchain/swapchain.rs

@@ -192,7 +192,7 @@ pub struct Swapchain<W> {
 struct ImageEntry {
     // The actual image.
     image: UnsafeImage,
-    // If true, then the image is still in the undefined layout and must be transitionned.
+    // If true, then the image is still in the undefined layout and must be transitioned.
     undefined_layout: AtomicBool,
 }
 

vulkano/src/sync/future/mod.rs

@@ -319,7 +319,7 @@ pub enum AccessError {
         requested: ImageLayout,
     },
 
-    /// Trying to use an image without transitionning it from the "undefined" or "preinitialized"
+    /// Trying to use an image without transitioning it from the "undefined" or "preinitialized"
     /// layouts first.
     ImageNotInitialized {
         /// The layout that was requested for the image.
@@ -347,7 +347,7 @@ impl error::Error for AccessError {
                 unimplemented!() // TODO: find a description
             },
             AccessError::ImageNotInitialized { .. } => {
-                "trying to use an image without transitionning it from the undefined or \
+                "trying to use an image without transitioning it from the undefined or \
                  preinitialized layouts first"
             },
             AccessError::BufferNotInitialized => {