Merge pull request #12805 from drkoller:imwritedoc

modules/imgcodecs/include/opencv2/imgcodecs.hpp

@@ -140,19 +140,18 @@ returns an empty matrix ( Mat::data==NULL ).
 Currently, the following file formats are supported:
 
 -   Windows bitmaps - \*.bmp, \*.dib (always supported)
--   JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section)
--   JPEG 2000 files - \*.jp2 (see the *Notes* section)
--   Portable Network Graphics - \*.png (see the *Notes* section)
--   WebP - \*.webp (see the *Notes* section)
+-   JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Note* section)
+-   JPEG 2000 files - \*.jp2 (see the *Note* section)
+-   Portable Network Graphics - \*.png (see the *Note* section)
+-   WebP - \*.webp (see the *Note* section)
 -   Portable image format - \*.pbm, \*.pgm, \*.ppm \*.pxm, \*.pnm (always supported)
 -   Sun rasters - \*.sr, \*.ras (always supported)
--   TIFF files - \*.tiff, \*.tif (see the *Notes* section)
--   OpenEXR Image files - \*.exr (see the *Notes* section)
+-   TIFF files - \*.tiff, \*.tif (see the *Note* section)
+-   OpenEXR Image files - \*.exr (see the *Note* section)
 -   Radiance HDR - \*.hdr, \*.pic (always supported)
--   Raster and Vector geospatial data supported by Gdal (see the *Notes* section)
+-   Raster and Vector geospatial data supported by GDAL (see the *Note* section)
 
 @note
-
 -   The function determines the type of an image by the content, not by the file extension.
 -   In the case of color images, the decoded images will have the channels stored in **B G R** order.
 -   When using IMREAD_GRAYSCALE, the codec's internal grayscale conversion will be used, if available.
@@ -167,11 +166,12 @@ Currently, the following file formats are supported:
     files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn
     on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake.
 -   In the case you set *WITH_GDAL* flag to true in CMake and @ref IMREAD_LOAD_GDAL to load the image,
-    then [GDAL](http://www.gdal.org) driver will be used in order to decode the image by supporting
+    then the [GDAL](http://www.gdal.org) driver will be used in order to decode the image, supporting
     the following formats: [Raster](http://www.gdal.org/formats_list.html),
     [Vector](http://www.gdal.org/ogr_formats.html).
 -   If EXIF information are embedded in the image file, the EXIF orientation will be taken into account
     and thus the image will be rotated accordingly except if the flag @ref IMREAD_IGNORE_ORIENTATION is passed.
+
 @param filename Name of file to be loaded.
 @param flags Flag that can take values of cv::ImreadModes
 */
@@ -190,18 +190,23 @@ CV_EXPORTS_W bool imreadmulti(const String& filename, CV_OUT std::vector<Mat>& m
 /** @brief Saves an image to a specified file.
 
 The function imwrite saves the image to the specified file. The image format is chosen based on the
-filename extension (see cv::imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV_16U)
-in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images
-can be saved using this function. If the format, depth or channel order is different, use
-Mat::convertTo , and cv::cvtColor to convert it before saving. Or, use the universal FileStorage I/O
-functions to save the image to XML or YAML format.
-
-It is possible to store PNG images with an alpha channel using this function. To do this, create
+filename extension (see cv::imread for the list of extensions). In general, only 8-bit
+single-channel or 3-channel (with 'BGR' channel order) images
+can be saved using this function, with these exceptions:
+
+- 16-bit unsigned (CV_16U) images can be saved in the case of PNG, JPEG 2000, and TIFF formats
+- 32-bit float (CV_32F) images can be saved in TIFF, OpenEXR, and Radiance HDR formats; 3-channel
+(CV_32FC3) TIFF images will be saved using the LogLuv high dynamic range encoding (4 bytes per pixel)
+- PNG images with an alpha channel can be saved using this function. To do this, create
 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels
-should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535.
+should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535 (see the code sample below).
+
+If the format, depth or channel order is different, use
+Mat::convertTo and cv::cvtColor to convert it before saving. Or, use the universal FileStorage I/O
+functions to save the image to XML or YAML format.
 
-The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom
-compression parameters :
+The sample below shows how to create a BGRA image and save it to a PNG file. It also demonstrates how to set custom
+compression parameters:
 @include snippets/imgcodecs_imwrite.cpp
 @param filename Name of the file.
 @param img Image to be saved.