From 45e1d587af370a274442c583b35839dcbc0e2a23 Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Thu, 2 Feb 2017 11:23:52 +0100 Subject: [PATCH] More color space doc improvement --- vulkano/src/swapchain/surface.rs | 43 ++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/vulkano/src/swapchain/surface.rs b/vulkano/src/swapchain/surface.rs index 0e6821e23..8d6ba171d 100644 --- a/vulkano/src/swapchain/surface.rs +++ b/vulkano/src/swapchain/surface.rs @@ -835,9 +835,7 @@ impl Iterator for SupportedCompositeAlphaIter { /// > words it is the way the value should be interpreted. /// /// The most commonly used color space today is sRGB. Most monitors today use this color space, -/// and most images files are encoded in this color space. What this means is that the RGB values -/// sent from the computer to the monitor are expected to be in sRGB, and the RGB values loaded -/// from an image file are supposed to be in sRGB as well. +/// and most images files are encoded in this color space. /// /// ## Pixel formats and linear vs non-linear /// @@ -845,8 +843,8 @@ impl Iterator for SupportedCompositeAlphaIter { /// consists of pixels in RGB but contains no information about the color space (or lack thereof) /// of these pixels. You are free to store them in whatever color space you want. /// -/// But one big practical problem with color spaces is that they are usually not linear, and in -/// particular the popular sRGB color space is not linear. I a non-linear color space, a value of +/// But one big practical problem with color spaces is that they are sometimes not linear, and in +/// particular the popular sRGB color space is not linear. In a non-linear color space, a value of /// `[0.6, 0.6, 0.6]` for example is **not** twice as bright as a value of `[0.3, 0.3, 0.3]`. This /// is problematic, because operations such as taking the average of two colors or calculating the /// lighting of a texture with a dot product are mathematically incorrect and will produce @@ -859,36 +857,43 @@ impl Iterator for SupportedCompositeAlphaIter { /// expected to contain RGB data in the sRGB color space. When you sample an image with such a /// format from a shader, the implementation will automatically turn the pixel values into a linear /// color space that is suitable for linear operations (such as additions or multiplications). -/// When you write to an image with such a format, the implementation will automatically perform -/// the opposite conversion. These conversions are most of the time performed by the hardware and -/// incur no additional cost. +/// When you write to a framebuffer attachment with such a format, the implementation will +/// automatically perform the opposite conversion. These conversions are most of the time performed +/// by the hardware and incur no additional cost. /// /// ## Color space of the swapchain /// /// The color space that you specify when you create a swapchain is how the implementation will /// interpret the raw data inside of the image. /// -/// > **Note**: The implementaiton can choose to send the data in the swapchain image directly to +/// > **Note**: The implementation can choose to send the data in the swapchain image directly to /// > the monitor, but it can also choose to write it in an intermediary buffer that is then read -/// > by the operating system or windowing system. Therefore the color space that is supported by -/// > the implementation is not necessarily the same as the one supported by the monitor. +/// > by the operating system or windowing system. Therefore the color space that the +/// > implementation supports is not necessarily the same as the one supported by the monitor. /// /// It is *your* job to ensure that the data in the swapchain image is in the color space -/// that is specified here (for example by doing the conversion in a fragment shader if necessary), -/// otherwise colors will be incorrect. The implementation will never perform any additional -/// conversion after the colors have been written to the swapchain image. +/// that is specified here, otherwise colors will be incorrect. +/// The implementation will never perform any additional automatic conversion after the colors have +/// been written to the swapchain image. /// /// # How do I handle this correctly? /// -/// When you write a cross-platform program, you should: +/// The easiest way to handle color spaces in a cross-platform program is: /// /// - Always request the `SrgbNonLinear` color space when creating the swapchain. -/// - Images loaded from files (such as PNG, JPEG, etc.) should be put in an image whose format -/// has the `Srgb` suffix. +/// - Make sure that all your image files use the sRGB color space, and load them in images whose +/// format has the `Srgb` suffix. Only use non-sRGB image formats for intermediary computations +/// or to store non-color data. /// - Swapchain images should have a format with the `Srgb` suffix. /// -/// If you follow these three rules, then everything should go well and render the same way on all -/// platforms. +/// > **Note**: It is unclear whether the `SrgbNonLinear` color space is always supported by the +/// > the implementation or not. See https://github.com/KhronosGroup/Vulkan-Docs/issues/442. +/// +/// > **Note**: Lots of developers are confused by color spaces. You can sometimes find articles +/// > talking about gamma correction and suggestion to put your colors to the power 2.2 for +/// > example. These are all hacks and you should use the sRGB pixel formats intead. +/// +/// If you follow these three rules, then everything should render the same way on all platforms. /// /// Additionally you can try detect whether the implementation supports any additional color space /// and perform a manual conversion to that color space from inside your shader.