Merge pull request #7165 from PkLab:doc_videoio

modules/core/doc/intro.markdown

@@ -22,7 +22,7 @@ libraries. The following modules are available:
 -   **objdetect** - detection of objects and instances of the predefined classes (for example,
     faces, eyes, mugs, people, cars, and so on).
 -   **highgui** - an easy-to-use interface to simple UI capabilities.
--   **videoio** - an easy-to-use interface to video capturing and video codecs.
+-   @ref videoio - an easy-to-use interface to video capturing and video codecs.
 -   **gpu** - GPU-accelerated algorithms from different OpenCV modules.
 -   ... some other helper modules, such as FLANN and Google test wrappers, Python bindings, and
     others.

modules/videoio/doc/videoio_overview.markdown

+Video I/O with OpenCV Overview {#videoio_overview}
+===================================
+
+### See also:
+  - @ref videoio "Video I/O Code Reference"
+  - Tutorials: @ref tutorial_table_of_content_videoio
+
+General Information
+===================
+
+The OpenCV @ref videoio module is a set of classes and functions to read and write video or images sequence.
+
+Basically, the module provides the cv::VideoCapture and cv::VideoWriter classes as 2-layer interface to many video
+I/O APIs used as backend.
+
+![Video I/O with OpenCV](pics/videoio_overview.svg)
+
+Some backends such as (DSHOW) Direct Show, Video For Windows (VFW), Microsoft Media Foundation (MSMF),
+Video 4 Linux (V4L), etc... are interfaces to the video I/O library provided by the operating system.
+
+Some others backends like OpenNI2 for Kinect, Intel Perceptual Computing SDK, GStreamer,
+XIMEA Camera API, etc...  are interfaces to proprietary drivers or to external library.
+
+See the list of supported backends here: cv::VideoCaptureAPIs
+
+@warning Some backends are experimental use them at your own risk
+@note Each backend supports devices properties (cv::VideoCaptureProperties) in a different way or might not support any property at all.
+
+
+Select the backend at runtime
+-----------------------------
+
+OpenCV automatically selects and uses first available backend (`apiPreference=cv::CAP_ANY`).
+
+As advanced usage you can select the backend to use at runtime. Currently this option is
+available only with %VideoCapture.
+
+For example to grab from default camera using Direct Show as backend
+
+```cpp
+//declare a capture object
+cv::VideoCapture cap(0 + cv::CAP_DSHOW);
+
+//or specify the apiPreference with open
+cap.open(0 + cv::CAP_DSHOW);
+```
+
+If you want to grab from a file using the Direct Show as backend:
+
+```cpp
+//declare a capture object
+cv::VideoCapture cap(filename, cv::CAP_DSHOW);
+
+//or specify the apiPreference with open
+cap.open(filename, cv::CAP_DSHOW);
+```
+
+@sa cv::VideoCapture::open() , cv::VideoCapture::VideoCapture()
+
+#### Enable backends
+
+Backends are available only if they have been built with your OpenCV binaries.
+
+Check in `opencv2/cvconfig.h` to know which APIs are currently available
+(e.g. `HAVE_MSMF, HAVE_VFW, HAVE_LIBV4L`, etc...).
+
+To enable/disable APIs, you have to:
+  1. re-configure OpenCV using appropriates CMake switches
+     (e.g. `-DWITH_MSMF=ON -DWITH_VFW=ON ... `) or checking related switch in cmake-gui
+  2. rebuild OpenCV itself
+
+#### Use 3rd party drivers or cameras
+
+Many industrial cameras or some video I/O devices don't provide standard driver interfaces
+for the operating system. Thus you can't use  VideoCapture or VideoWriter with these devices.
+
+To get access to their devices, manufactures provide their own C++ API and library that you have to
+include and link with your OpenCV application.
+
+Is common case that this libraries read/write images from/to a memory buffer. If it so, it is
+possible to make a `Mat` header for memory buffer (user-allocated data) and process it
+in-place using OpenCV functions. See cv::Mat::Mat() for more details.
+
+The FFmpeg library
+------------------
+
+OpenCV can use the FFmpeg library (http://ffmpeg.org/) as backend to record, convert and stream audio and video.
+FFMpeg is a complete, cross-reference solution. If you enable FFmpeg while configuring OpenCV than
+CMake will download and install the binaries in `OPENCV_SOURCE_CODE/3rdparty/ffmpeg/`. To use
+FFMpeg at runtime, you must deploy the FFMepg binaries with your application.
+
+@note FFmpeg is licensed under the GNU Lesser General Public License (LGPL) version 2.1 or later.
+See `OPENCV_SOURCE_CODE/3rdparty/ffmpeg/readme.txt` and http://ffmpeg.org/legal.html for details and
+licensing information

modules/videoio/include/opencv2/videoio/videoio_c.h

@@ -57,13 +57,18 @@ extern "C" {
 *                         Working with Video Files and Cameras                           *
 \****************************************************************************************/
 
-/* "black box" capture structure */
+/** @brief "black box" capture structure
+
+In C++ use cv::VideoCapture
+*/
 typedef struct CvCapture CvCapture;
 
-/* start capturing frames from video file */
+/** @brief start capturing frames from video file
+*/
 CVAPI(CvCapture*) cvCreateFileCapture( const char* filename );
 
-/* start capturing frames from video file. allows specifying a preferred API to use */
+/** @brief start capturing frames from video file. allows specifying a preferred API to use
+*/
 CVAPI(CvCapture*) cvCreateFileCaptureWithPreference( const char* filename , int apiPreference);
 
 enum
@@ -120,24 +125,32 @@ enum
     CV_CAP_IMAGES = 2000     // OpenCV Image Sequence (e.g. img_%02d.jpg)
 };
 
-/* start capturing frames from camera: index = camera_index + domain_offset (CV_CAP_*) */
+/** @brief start capturing frames from camera: index = camera_index + domain_offset (CV_CAP_*)
+*/
 CVAPI(CvCapture*) cvCreateCameraCapture( int index );
 
-/* grab a frame, return 1 on success, 0 on fail.
-  this function is thought to be fast               */
+/** @brief grab a frame, return 1 on success, 0 on fail.
+
+  this function is thought to be fast
+*/
 CVAPI(int) cvGrabFrame( CvCapture* capture );
 
-/* get the frame grabbed with cvGrabFrame(..)
+/** @brief get the frame grabbed with cvGrabFrame(..)
+
   This function may apply some frame processing like
   frame decompression, flipping etc.
-  !!!DO NOT RELEASE or MODIFY the retrieved frame!!! */
+  @warning !!!DO NOT RELEASE or MODIFY the retrieved frame!!!
+*/
 CVAPI(IplImage*) cvRetrieveFrame( CvCapture* capture, int streamIdx CV_DEFAULT(0) );
 
-/* Just a combination of cvGrabFrame and cvRetrieveFrame
-   !!!DO NOT RELEASE or MODIFY the retrieved frame!!!      */
+/** @brief Just a combination of cvGrabFrame and cvRetrieveFrame
+
+  @warning !!!DO NOT RELEASE or MODIFY the retrieved frame!!!
+*/
 CVAPI(IplImage*) cvQueryFrame( CvCapture* capture );
 
-/* stop capturing/reading and free resources */
+/** @brief stop capturing/reading and free resources
+*/
 CVAPI(void) cvReleaseCapture( CvCapture** capture );
 
 enum
@@ -498,48 +511,71 @@ enum
     CV_CAP_PROP_VIEWFINDER                = 17010  // Enter liveview mode.
 };
 
-/* retrieve or set capture properties */
+/** @brief retrieve capture properties
+*/
 CVAPI(double) cvGetCaptureProperty( CvCapture* capture, int property_id );
+/** @brief set capture properties
+*/
 CVAPI(int)    cvSetCaptureProperty( CvCapture* capture, int property_id, double value );
 
-// Return the type of the capturer (eg, CV_CAP_V4W, CV_CAP_UNICAP), which is unknown if created with CV_CAP_ANY
+/** @brief Return the type of the capturer (eg, ::CV_CAP_VFW, ::CV_CAP_UNICAP)
+
+It is unknown if created with ::CV_CAP_ANY
+*/
 CVAPI(int)    cvGetCaptureDomain( CvCapture* capture);
 
-/* "black box" video file writer structure */
+/** @brief "black box" video file writer structure
+
+In C++ use cv::VideoWriter
+*/
 typedef struct CvVideoWriter CvVideoWriter;
 
+//! Macro to construct the fourcc code of the codec. Same as CV_FOURCC()
 #define CV_FOURCC_MACRO(c1, c2, c3, c4) (((c1) & 255) + (((c2) & 255) << 8) + (((c3) & 255) << 16) + (((c4) & 255) << 24))
 
+/** @brief Constructs the fourcc code of the codec function
+
+Simply call it with 4 chars fourcc code like `CV_FOURCC('I', 'Y', 'U', 'V')`
+
+List of codes can be obtained at [Video Codecs by FOURCC](http://www.fourcc.org/codecs.php) page.
+FFMPEG backend with MP4 container natively uses other values as fourcc code:
+see [ObjectType](http://www.mp4ra.org/codecs.html).
+*/
 CV_INLINE int CV_FOURCC(char c1, char c2, char c3, char c4)
 {
     return CV_FOURCC_MACRO(c1, c2, c3, c4);
 }
 
-#define CV_FOURCC_PROMPT -1  /* Open Codec Selection Dialog (Windows only) */
-#define CV_FOURCC_DEFAULT CV_FOURCC('I', 'Y', 'U', 'V') /* Use default codec for specified filename (Linux only) */
+//! (Windows only) Open Codec Selection Dialog
+#define CV_FOURCC_PROMPT -1
+//! (Linux only) Use default codec for specified filename
+#define CV_FOURCC_DEFAULT CV_FOURCC('I', 'Y', 'U', 'V')
 
-/* initialize video file writer */
+/** @brief initialize video file writer
+*/
 CVAPI(CvVideoWriter*) cvCreateVideoWriter( const char* filename, int fourcc,
                                            double fps, CvSize frame_size,
                                            int is_color CV_DEFAULT(1));
 
-/* write frame to video file */
+/** @brief write frame to video file
+*/
 CVAPI(int) cvWriteFrame( CvVideoWriter* writer, const IplImage* image );
 
-/* close video file writer */
+/** @brief close video file writer
+*/
 CVAPI(void) cvReleaseVideoWriter( CvVideoWriter** writer );
 
-/****************************************************************************************\
-*                              Obsolete functions/synonyms                               *
-\****************************************************************************************/
-
-#define cvCaptureFromFile cvCreateFileCapture
-#define cvCaptureFromCAM cvCreateCameraCapture
-#define cvCaptureFromAVI cvCaptureFromFile
-#define cvCreateAVIWriter cvCreateVideoWriter
-#define cvWriteToAVI cvWriteFrame
-
-/** @} videoio_c */
+// ***************************************************************************************
+//! @name Obsolete functions/synonyms
+//! @{
+#define cvCaptureFromCAM cvCreateCameraCapture //!< @deprecated use cvCreateCameraCapture() instead
+#define cvCaptureFromFile cvCreateFileCapture  //!< @deprecated use cvCreateFileCapture() instead
+#define cvCaptureFromAVI cvCaptureFromFile     //!< @deprecated use cvCreateFileCapture() instead
+#define cvCreateAVIWriter cvCreateVideoWriter  //!< @deprecated use cvCreateVideoWriter() instead
+#define cvWriteToAVI cvWriteFrame              //!< @deprecated use cvWriteFrame() instead
+//!  @} Obsolete...
+
+//! @} videoio_c
 
 #ifdef __cplusplus
 }

samples/cpp/videocapture_basic.cpp

+/**
+  @file videocapture_basic.cpp
+  @brief A very basic sample for using VideoCapture and VideoWriter
+  @author PkLab.net
+  @date Aug 24, 2016
+*/
+
+#include <opencv2/opencv.hpp>
+#include <iostream>
+#include <stdio.h>
+
+using namespace cv;
+using namespace std;
+
+int main(int, char**)
+{
+    Mat frame;
+    //--- INITIALIZE VIDEOCAPTURE
+    VideoCapture cap;
+    // open the default camera using default API
+    cap.open(0);
+    // OR advance usage: select any API backend
+    int deviceID = 0;             // 0 = open default camera
+    int apiID = cv::CAP_ANY;      // 0 = autodetect default API
+    // open selected camera using selected API
+    cap.open(deviceID + apiID);
+    // check if we succeeded
+    if (!cap.isOpened()) {
+        cerr << "ERROR! Unable to open camera\n";
+        return -1;
+    }
+
+    //--- GRAB AND WRITE LOOP
+    cout << "Start grabbing" << endl
+        << "Press any key to terminate" << endl;
+    for (;;)
+    {
+        // wait for a new frame from camera and store it into 'frame'
+        cap.read(frame);
+        // check if we succeeded
+        if (frame.empty()) {
+            cerr << "ERROR! blank frame grabbed\n";
+            break;
+        }
+        // show live and wait for a key with timeout long enough to show images
+        imshow("Live", frame);
+        if (waitKey(5) >= 0)
+            break;
+    }
+    // the camera will be deinitialized automatically in VideoCapture destructor
+    return 0;
+}
\ No newline at end of file

samples/cpp/starter_video.cpp → samples/cpp/videocapture_starter.cpp

-/*
-* starter_video.cpp
+/**
+* @file videocapture_starter.cpp
+* @brief A starter sample for using OpenCV VideoCapture with capture devices, video files or image sequences
+* easy as CV_PI right?
 *
 *  Created on: Nov 23, 2010
 *      Author: Ethan Rublee
 *
 *  Modified on: April 17, 2013
 *      Author: Kevin Hughes
-*
-* A starter sample for using OpenCV VideoCapture with capture devices, video files or image sequences
-* easy as CV_PI right?
 */
 
 #include <opencv2/imgcodecs.hpp>

samples/cpp/videowriter_basic.cpp

+/**
+  @file videowriter_basic.cpp
+  @brief A very basic sample for using VideoWriter and VideoCapture
+  @author PkLab.net
+  @date Aug 24, 2016
+*/
+
+#include <opencv2/opencv.hpp>
+#include <iostream>
+#include <stdio.h>
+
+using namespace cv;
+using namespace std;
+
+int main(int, char**)
+{
+    Mat src;
+    // use default camera as video source
+    VideoCapture cap(0);
+    // check if we succeeded
+    if (!cap.isOpened()) {
+        cerr << "ERROR! Unable to open camera\n";
+        return -1;
+    }
+    // get one frame from camera to know frame size and type
+    cap >> src;
+    // check if we succeeded
+    if (src.empty()) {
+        cerr << "ERROR! blank frame grabbed\n";
+        return -1;
+    }
+    bool isColor = (src.type() == CV_8UC3);
+
+    //--- INITIALIZE VIDEOWRITER
+    VideoWriter writer;
+    int codec = CV_FOURCC('M', 'J', 'P', 'G');  // select desired codec (must be available at runtime)
+    double fps = 25.0;                          // framerate of the created video stream
+    string filename = "./live.avi";             // name of the output video file
+    writer.open(filename, codec, fps, src.size(), isColor);
+    // check if we succeeded
+    if (!writer.isOpened()) {
+        cerr << "Could not open the output video file for write\n";
+        return -1;
+    }
+
+    //--- GRAB AND WRITE LOOP
+    cout << "Writing videofile: " << filename << endl
+         << "Press any key to terminate" << endl;
+    for (;;)
+    {
+        // check if we succeeded
+        if (!cap.read(src)) {
+            cerr << "ERROR! blank frame grabbed\n";
+            break;
+        }
+        // encode the frame into the videofile stream
+        writer.write(src);
+        // show live and wait for a key with timeout long enough to show images
+        imshow("Live", src);
+        if (waitKey(5) >= 0)
+            break;
+    }
+    // the videofile will be closed and released automatically in VideoWriter destructor
+    return 0;
+}
\ No newline at end of file