Data Structures

class oclMat

OpenCV C++ 1-D or 2-D dense array class

class CV_EXPORTS oclMat
{
public:
    //! default constructor
    oclMat();
    //! constructs oclMatrix of the specified size and type (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
    oclMat(int rows, int cols, int type);
    oclMat(Size size, int type);
    //! constucts oclMatrix and fills it with the specified value _s.
    oclMat(int rows, int cols, int type, const Scalar &s);
    oclMat(Size size, int type, const Scalar &s);
    //! copy constructor
    oclMat(const oclMat &m);

    //! constructor for oclMatrix headers pointing to user-allocated data
    oclMat(int rows, int cols, int type, void *data, size_t step = Mat::AUTO_STEP);
    oclMat(Size size, int type, void *data, size_t step = Mat::AUTO_STEP);

    //! creates a matrix header for a part of the bigger matrix
    oclMat(const oclMat &m, const Range &rowRange, const Range &colRange);
    oclMat(const oclMat &m, const Rect &roi);

    //! builds oclMat from Mat. Perfom blocking upload to device.
    explicit oclMat (const Mat &m);

    //! destructor - calls release()
    ~oclMat();

    //! assignment operators
    oclMat &operator = (const oclMat &m);
    //! assignment operator. Perfom blocking upload to device.
    oclMat &operator = (const Mat &m);


    //! pefroms blocking upload data to oclMat.
    void upload(const cv::Mat &m);


    //! downloads data from device to host memory. Blocking calls.
    operator Mat() const;
    void download(cv::Mat &m) const;


    //! returns a new oclMatrix header for the specified row
    oclMat row(int y) const;
    //! returns a new oclMatrix header for the specified column
    oclMat col(int x) const;
    //! ... for the specified row span
    oclMat rowRange(int startrow, int endrow) const;
    oclMat rowRange(const Range &r) const;
    //! ... for the specified column span
    oclMat colRange(int startcol, int endcol) const;
    oclMat colRange(const Range &r) const;

    //! returns deep copy of the oclMatrix, i.e. the data is copied
    oclMat clone() const;
    //! copies the oclMatrix content to "m".
    // It calls m.create(this->size(), this->type()).
    // It supports any data type
    void copyTo( oclMat &m ) const;
    //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements.
    //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
    void copyTo( oclMat &m, const oclMat &mask ) const;
    //! converts oclMatrix to another datatype with optional scalng. See cvConvertScale.
    //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
    void convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const;

    void assignTo( oclMat &m, int type = -1 ) const;

    //! sets every oclMatrix element to s
    //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
    oclMat &operator = (const Scalar &s);
    //! sets some of the oclMatrix elements to s, according to the mask
    //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
    oclMat &setTo(const Scalar &s, const oclMat &mask = oclMat());
    //! creates alternative oclMatrix header for the same data, with different
    // number of channels and/or different number of rows. see cvReshape.
    oclMat reshape(int cn, int rows = 0) const;

    //! allocates new oclMatrix data unless the oclMatrix already has specified size and type.
    // previous data is unreferenced if needed.
    void create(int rows, int cols, int type);
    void create(Size size, int type);
    //! decreases reference counter;
    // deallocate the data when reference counter reaches 0.
    void release();

    //! swaps with other smart pointer
    void swap(oclMat &mat);

    //! locates oclMatrix header within a parent oclMatrix. See below
    void locateROI( Size &wholeSize, Point &ofs ) const;
    //! moves/resizes the current oclMatrix ROI inside the parent oclMatrix.
    oclMat &adjustROI( int dtop, int dbottom, int dleft, int dright );
    //! extracts a rectangular sub-oclMatrix
    // (this is a generalized form of row, rowRange etc.)
    oclMat operator()( Range rowRange, Range colRange ) const;
    oclMat operator()( const Rect &roi ) const;

    //! returns true if the oclMatrix data is continuous
    // (i.e. when there are no gaps between successive rows).
    // similar to CV_IS_oclMat_CONT(cvoclMat->type)
    bool isContinuous() const;
    //! returns element size in bytes,
    // similar to CV_ELEM_SIZE(cvMat->type)
    size_t elemSize() const;
    //! returns the size of element channel in bytes.
    size_t elemSize1() const;
    //! returns element type, similar to CV_MAT_TYPE(cvMat->type)
    int type() const;
    //! returns element type, i.e. 8UC3 returns 8UC4 because in ocl
    //! 3 channels element actually use 4 channel space
    int ocltype() const;
    //! returns element type, similar to CV_MAT_DEPTH(cvMat->type)
    int depth() const;
    //! returns element type, similar to CV_MAT_CN(cvMat->type)
    int channels() const;
    //! returns element type, return 4 for 3 channels element,
    //!becuase 3 channels element actually use 4 channel space
    int oclchannels() const;
    //! returns step/elemSize1()
    size_t step1() const;
    //! returns oclMatrix size:
    // width == number of columns, height == number of rows
    Size size() const;
    //! returns true if oclMatrix data is NULL
    bool empty() const;

    //! returns pointer to y-th row
    uchar *ptr(int y = 0);
    const uchar *ptr(int y = 0) const;

    //! template version of the above method
    template<typename _Tp> _Tp *ptr(int y = 0);
    template<typename _Tp> const _Tp *ptr(int y = 0) const;

    //! matrix transposition
    oclMat t() const;

    /*! includes several bit-fields:
      - the magic signature
      - continuity flag
      - depth
      - number of channels
      */
    int flags;
    //! the number of rows and columns
    int rows, cols;
    //! a distance between successive rows in bytes; includes the gap if any
    size_t step;
    //! pointer to the data(OCL memory object)
    uchar *data;

    //! pointer to the reference counter;
    // when oclMatrix points to user-allocated data, the pointer is NULL
    int *refcount;

    //! helper fields used in locateROI and adjustROI
    //datastart and dataend are not used in current version
    uchar *datastart;
    uchar *dataend;

    //! OpenCL context associated with the oclMat object.
    Context *clCxt;
    //add offset for handle ROI, calculated in byte
    int offset;
    //add wholerows and wholecols for the whole matrix, datastart and dataend are no longer used
    int wholerows;
    int wholecols;
};

Basically speaking, the oclMat is the mirror of Mat with the extension of ocl feature, the members have the same meaning and useage of Mat except following:

datastart and dataend are replaced with wholerows and wholecols

add clCxt for oclMat

Only basic flags are supported in oclMat(i.e. depth number of channels)

All the 3-channel matrix(i.e. RGB image) are represented by 4-channel matrix in oclMat. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and oclMat.

For example: If a oclMat has 3 channels, channels() returns 3 and oclchannels() returns 4