nordic-dev.net/vulkano
nordic-dev.net/vulkano
2
0
Fork 0
mirror of https://github.com/vulkano-rs/vulkano.git synced 2024-11-29 18:24:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

More color space doc improvement

Browse Source
This commit is contained in:
Pierre Krieger 2017-02-02 11:23:52 +01:00
parent 35d02e621f
commit 45e1d587af
1 changed files with 24 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
vulkano/src/swapchain/surface.rs
View File

@ -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.