Merge pull request #21337 from mansourmoufid:videocapture-get-property-return

Make cv::VideoCapture::get return cv::CAP_PROP_UNKNOWN (-1) for unsupported properties #21337

The return value indicating an unsupported property is not consistent across backends.

I stumbled on this issue because my code was determining if a property value is valid if it's non-zero (like the documentation says), which worked fine on macOS, but not on Android.

For example, auto-exposure is not supported on macOS, so get() returns 0. But it is supported on Android and 0 means auto-exposure is off.

I think -1 is the better return value to indicate unsupported properties.

I made changes to all the backends. I think I got every case. This breaks API compatibility for some backends, so I based this on branch 3.4.

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or other license that is incompatible with OpenCV
- [x] The PR is proposed to proper branch
- [ ] There is reference to original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

modules/videoio/include/opencv2/videoio.hpp

@@ -129,6 +129,7 @@ enum VideoCaptureAPIs {
  @sa videoio_flags_others, VideoCapture::get(), VideoCapture::set()
 */
 enum VideoCaptureProperties {
+       CAP_PROP_UNKNOWN        =-1, //!< Returned by VideoCapture::get if the requested property is unknown or unsupported
        CAP_PROP_POS_MSEC       =0, //!< Current position of the video file in milliseconds.
        CAP_PROP_POS_FRAMES     =1, //!< 0-based index of the frame to be decoded/captured next. When the index i is set in RAW mode (CAP_PROP_FORMAT == -1) this will seek to the key frame k, where k <= i.
        CAP_PROP_POS_AVI_RATIO  =2, //!< Relative position of the video file: 0=start of the film, 1=end of the film.
@@ -213,6 +214,7 @@ enum VideoCaptureProperties {
  @sa VideoWriter::get(), VideoWriter::set()
 */
 enum VideoWriterProperties {
+  VIDEOWRITER_PROP_UNKNOWN = -1, //!< Returned by VideoWriter::get if the requested property is unknown or unsupported
   VIDEOWRITER_PROP_QUALITY = 1,    //!< Current quality (0..100%) of the encoded videostream. Can be adjusted dynamically in some codecs.
   VIDEOWRITER_PROP_FRAMEBYTES = 2, //!< (Read-only): Size of just encoded video frame. Note that the encoding order may be different from representation order.
   VIDEOWRITER_PROP_NSTRIPES = 3,   //!< Number of stripes for parallel encoding. -1 for auto detection.
@@ -999,7 +1001,7 @@ public:
 
     @param propId Property identifier from cv::VideoCaptureProperties (eg. cv::CAP_PROP_POS_MSEC, cv::CAP_PROP_POS_FRAMES, ...)
     or one from @ref videoio_flags_others
-    @return Value for the specified property. Value 0 is returned when querying a property that is
+    @return Value for the specified property. Value cv::CAP_PROP_UNKNOWN is returned when querying a property that is
     not supported by the backend used by the VideoCapture instance.
 
     @note Reading / writing properties involves many layers. Some unexpected result might happens