added variant of cv::imdecode with the specified output matrix

modules/highgui/doc/reading_and_writing_images_and_video.rst

@@ -9,6 +9,8 @@ Reads an image from a buffer in memory.
 
 .. ocv:function:: Mat imdecode( InputArray buf,  int flags )
 
+.. ocv:function:: Mat imdecode( InputArray buf,  int flags, Mat* dst )
+
 .. ocv:cfunction:: IplImage* cvDecodeImage( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
 
 .. ocv:cfunction:: CvMat* cvDecodeImageM( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
@@ -17,7 +19,9 @@ Reads an image from a buffer in memory.
 
     :param buf: Input array or vector of bytes.
 
-    :param flags: The same flags as in  :ocv:func:`imread` .
+    :param flags: The same flags as in :ocv:func:`imread` .
+    
+    :param dst: The optional output placeholder for the decoded matrix. It can save the image reallocations when the function is called repeatedly for images of the same size.
 
 The function reads an image from the specified buffer in the memory.
 If the buffer is too short or contains invalid data, the empty matrix/image is returned.
@@ -25,6 +29,8 @@ If the buffer is too short or contains invalid data, the empty matrix/image is r
 See
 :ocv:func:`imread` for the list of supported formats and flags description.
 
+.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
+
 imencode
 ------------
 Encodes an image into a memory buffer.
@@ -68,6 +74,12 @@ Loads an image from a file.
     :param filename: Name of file to be loaded.
 
     :param flags: Flags specifying the color type of a loaded image:
+    
+        * 1 - 
+        * CV_LOAD_IMAGE_ANYDEPTH - 
+        CV_LOAD_IMAGE_COLOR
+        CV_LOAD_IMAGE_GRAYSCALE
+        
 
         * **>0**  Return a 3-channel color image
 
@@ -99,6 +111,8 @@ The function ``imread`` loads an image from the specified file and returns it. I
 
     * On Linux*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for codecs supplied with an OS image. Install the relevant packages (do not forget the development 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.
 
+.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
+
 imwrite
 -----------
 Saves an image to a specified file.
@@ -124,7 +138,7 @@ Saves an image to a specified file.
         *  For PPM, PGM, or PBM, it can be a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1. Default value is 1.
 
 The function ``imwrite`` saves the image to the specified file. The image format is chosen based on the ``filename`` extension (see
-:ocv:func:`imread` for the list of extensions). Only 8-bit (or 16-bit 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
+:ocv:func:`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
 :ocv:func:`Mat::convertTo` , and
 :ocv:func:`cvtColor` to convert it before saving. Or, use the universal XML I/O functions to save the image to XML or YAML format.
 

modules/highgui/include/opencv2/highgui/highgui.hpp

@@ -189,6 +189,7 @@ CV_EXPORTS_W Mat imread( const string& filename, int flags=1 );
 CV_EXPORTS_W bool imwrite( const string& filename, InputArray img,
               const vector<int>& params=vector<int>());
 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags );
+CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst );
 CV_EXPORTS_W bool imencode( const string& ext, InputArray img,
                             CV_OUT vector<uchar>& buf,
                             const vector<int>& params=vector<int>());

modules/highgui/src/loadsave.cpp

@@ -395,6 +395,14 @@ Mat imdecode( InputArray _buf, int flags )
     return img;
 }
 
+Mat imdecode( InputArray _buf, int flags, Mat* dst )
+{
+    Mat buf = _buf.getMat(), img;
+    dst = dst ? dst : &img;
+    imdecode_( buf, flags, LOAD_MAT, dst );
+    return *dst;
+}
+    
 bool imencode( const string& ext, InputArray _image,
                vector<uchar>& buf, const vector<int>& params )
 {