added doc on supported Kinect properties (#1251)

doc/user_guide/ug_highgui.rst

@@ -53,7 +53,7 @@ VideoCapture can retrieve the following Kinect data:
 
 In order to get depth map from Kinect use ``VideoCapture::operator >>``, e. g. ::
 
-    VideoCapture capture(0); // or CV_CAP_OPENNI
+    VideoCapture capture( CV_CAP_OPENNI );
     for(;;)
     {
         Mat depthMap;    
@@ -80,4 +80,46 @@ For getting several Kinect maps use ``VideoCapture::grab`` and ``VideoCapture::r
             break;
     }
 
+For setting and getting some property of Kinect data generators use ``VideoCapture::set`` and ``VideoCapture::get`` methods respectively, e.g. ::
+
+    VideoCapture capture( CV_CAP_OPENNI );    
+    capture.set( CV_CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE, CV_CAP_OPENNI_VGA_30HZ );
+    cout << "FPS    " << capture.get( CV_CAP_OPENNI_IMAGE_GENERATOR+CV_CAP_PROP_FPS ) << endl;
+
+Since two types of Kinect's data generators are supported (image generator and depth generator), there are two flags that should be used to set/get property of the needed generator:
+
+* CV_CAP_OPENNI_IMAGE_GENERATOR -- A flag for access to the image generator properties.
+
+* CV_CAP_OPENNI_DEPTH_GENERATOR -- A flag for access to the depth generator properties. This flag value is assumed by default if neither of the two possible values of the property is not set.
+
+Flags specifing the needed generator type must be used in combination with particular generator property. The following properties of cameras available through OpenNI interfaces are supported:
+
+* 
+  For image generator:
+  
+  - ``CV_CAP_PROP_OPENNI_OUTPUT_MODE`` -- Two output modes are supported: ``CV_CAP_OPENNI_VGA_30HZ`` used by default (image generator returns images in VGA resolution with 30 FPS) or ``CV_CAP_OPENNI_SXGA_15HZ`` (image generator returns images in SXGA resolution with 15 FPS); depth generator's maps are always in VGA resolution.
+  
+
+* 
+  For depth generator:
+
+  - ``CV_CAP_PROP_OPENNI_REGISTRATION`` -- Flag that synchronizes the remapping depth map to image map  by changing depth generator's view point (if the flag is ``"on"``) or sets this view point to its normal one (if the flag is ``"off"``).
+  
+    Next properties are available for getting only:
+  
+  - ``CV_CAP_PROP_OPENNI_FRAME_MAX_DEPTH`` -- A maximum supported depth of Kinect in mm.
+  - ``CV_CAP_PROP_OPENNI_BASELINE`` -- Baseline value in mm. 
+  - ``CV_CAP_PROP_OPENNI_FOCAL_LENGTH`` -- A focal length in pixels. 
+  - ``CV_CAP_PROP_FRAME_WIDTH`` -- Frame width in pixels.
+  - ``CV_CAP_PROP_FRAME_HEIGHT`` -- Frame height in pixels.
+  - ``CV_CAP_PROP_FPS`` -- Frame rate in FPS.
+
+*
+  Some typical flags combinations "generator type + property" are defined as single flags:
+  
+    - ``CV_CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE = CV_CAP_OPENNI_IMAGE_GENERATOR + CV_CAP_PROP_OPENNI_OUTPUT_MODE``
+    - ``CV_CAP_OPENNI_DEPTH_GENERATOR_BASELINE = CV_CAP_OPENNI_DEPTH_GENERATOR + CV_CAP_PROP_OPENNI_BASELINE``
+    - ``CV_CAP_OPENNI_DEPTH_GENERATOR_FOCAL_LENGTH = CV_CAP_OPENNI_DEPTH_GENERATOR + CV_CAP_PROP_OPENNI_FOCAL_LENGTH``
+    - ``CV_CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION_ON = CV_CAP_OPENNI_DEPTH_GENERATOR + CV_CAP_PROP_OPENNI_REGISTRATION_ON``
+    
 For more information please refer to a Kinect example of usage ``kinect_maps.cpp`` in ``opencv/samples/cpp`` folder.