Some documentation

vulkano/src/image/layout.rs

@@ -9,6 +9,23 @@
 
 use vk;
 
+/// Layout of an image.
+///
+/// > **Note**: In vulkano, image layouts are mostly a low-level detail. You can ignore them,
+/// > unless you use an unsafe function that states in its documentation that you must take care of
+/// > an image's layout.
+///
+/// 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
+/// 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
+/// a command buffer.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[repr(u32)]
 pub enum ImageLayout {