What is the purpose of IVideoCapture class

Question

I am writing a class that will use cv::VideoCapture class for various purposes: processing live video stream, processing offline image sequences, processing some other fake data. My version of OpenCV is 3.4. Obviously, the first solution I thought about is to provide the pointer to some cv::VideoCapture interface for my class:

class MyClass {
public:
    MyClass(std::shared_ptr<SomeInterfaceToVideoCapture> camera);
}

I looked in the OpenCV docs and I actually found out, that indeed in the header videoio.hpp there is a forward declaration for IVideoCapture (which is the standard naming convention for the interfaces). Even though it seems that cv::VideoCapture doesn't actually inherit that cv::IVideoCapture, I gave it a try:

class MyClass {
public:
    MyClass(std::shared_ptr<cv::IVideoCapture> camera) {
        if (camera->isOpened()) {
            std::cerr << "VideoCapture device is not working" << std::endl;
        }
    }
}
// and later in GTest I create the instance like this:
MyClass myCl(new cv::VideoCapture(0));

And I got the error:

error: invalid use of incomplete type ‘class cv::IVideoCapture’
             if (camera->isOpened()) {
/usr/local/include/opencv2/videoio.hpp:581:7: note: forward declaration of ‘class cv::IVideoCapture’
 class IVideoCapture;

So, obviously this cv::IVideoCapture interface is never defined. However, in the same header in the class cv::VideoCapture there are two protected fields:

protected:
    Ptr<CvCapture> cap;
    Ptr<IVideoCapture> icap;

I couldn't find any documentation on how this icap field can be used. Of course, technically I can inherit cv::VideoCapture and then have access to icap but I don't see the purpose.

Since in the class cv::VideoCapture all methods are virtual, I can still override the default behavior for testing, simulation, or whatever applications, which is good. But, just out of curiosity: my question is: what is the purpose of the forward declaration of cv::IVideoCapture and what is the purpose of the protected field icap. What kind of pattern is that?

Answer 1

It seems that IVideoCapture class is used inside the VideoCapture as a pimpl idiom, and at the same time is the actual interface. Classes like VideoCapture_IntelPerC implement it and are used inside VideoCapture The difference is that is was declared public, but of course I cannot find any reason for OpenCV user to actually use this IVideoCapture interface.