C API for libbackscrub

[phlash]

Originally posted by @BenBE in #86 (comment)

I think we can do a somewhat hybrid API: Most functions can be exposed as wrappers with C compatibility and some direct C++ API when C++ is supported. In the worst case this just means, that some C++ API may be hidden for plain C usage, which is not great, but allows for easy fallback in such usecases. But more on this in a proper issue.

[BenBE]

The biggest issues we currently have with C++ compat are with the OpenCV types. As we mostly just use cv::Size and cv::Mat we could define some minimal look-alikes for the C-API that just hold the data (and pointers so the C interface can access things):

typedef struct cvp_size {
    union {
        size_t v[4];
        struct {
            size_t x, y, z;
        };
    };
} cvp_size_t;

Or similar to what we need to process of the cv::Size type.

For the cv::Mat type it's a bit mor complicated, but still manageable:

typedef struct cvp_mat {
    void* reserved; // opaque pointer to internal `cv::Mat` object.
    cvp_size_t size;
    void* data;
} cvp_mat_t;

cvp_mat_t* cvp_mat_new(cvp_size_t size);
void cvp_mat_free(cvp_mat_t* v);

bool cvp_mat_resize(cvp_mat_t* v, cvp_size_t* s);
// ...

All functions in our C API will take the wrapper types and convert them transparently to the matching OpenCV types internally. For reading/writing the matrix data, cvp_mat_t::data is set to the cvp_mat_t::reserved::data() value on any updates, so C code can just use that pointer, without needing to query it through the C++ code (alternatively a wrapper void* cvp_mat_getdata(cvp_mat_t* v) could return this value, if this has to be queried every time.

[phlash]

I've done a bit more digging into the old OpenCV C API, which has the image structures CvMat & IplImage, and a function to convert to cv::Mat. Not sure this would be useful though, as it assumes our C caller is using old OpenCV stuff, which may be unlikely?

I'm going to suggest we leave this unless/until we have a use case 😺 ?