class cv::cuda::GpuMat

Overview

Base storage class for GPU memory with reference counting. More…

#include <cuda.hpp>

class GpuMat
{
public:
    // classes

    class Allocator;

    // fields

    Allocator* allocator;
    int cols;
    uchar* data;
    const uchar* dataend;
    uchar* datastart;
    int flags;
    int* refcount;
    int rows;
    size_t step;

    // construction

    GpuMat(Allocator* allocator = defaultAllocator());

    GpuMat(
        int rows,
        int cols,
        int type,
        Allocator* allocator = defaultAllocator()
        );

    GpuMat(
        Size size,
        int type,
        Allocator* allocator = defaultAllocator()
        );

    GpuMat(
        int rows,
        int cols,
        int type,
        Scalar s,
        Allocator* allocator = defaultAllocator()
        );

    GpuMat(
        Size size,
        int type,
        Scalar s,
        Allocator* allocator = defaultAllocator()
        );

    GpuMat(const GpuMat& m);

    GpuMat(
        int rows,
        int cols,
        int type,
        void* data,
        size_t step = Mat::AUTO_STEP
        );

    GpuMat(
        Size size,
        int type,
        void* data,
        size_t step = Mat::AUTO_STEP
        );

    GpuMat(
        const GpuMat& m,
        Range rowRange,
        Range colRange
        );

    GpuMat(
        const GpuMat& m,
        Rect roi
        );

    GpuMat(
        InputArray arr,
        Allocator* allocator = defaultAllocator()
        );

    // methods

    static
    Allocator*
    defaultAllocator();

    static
    void
    setDefaultAllocator(Allocator* allocator);

    GpuMat&
    adjustROI(
        int dtop,
        int dbottom,
        int dleft,
        int dright
        );

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

    int
    channels() const;

    GpuMat
    clone() const;

    GpuMat
    col(int x) const;

    GpuMat
    colRange(
        int startcol,
        int endcol
        ) const;

    GpuMat
    colRange(Range r) const;

    void
    convertTo(
        OutputArray dst,
        int rtype
        ) const;

    void
    convertTo(
        OutputArray dst,
        int rtype,
        Stream& stream
        ) const;

    void
    convertTo(
        OutputArray dst,
        int rtype,
        double alpha,
        double beta = 0.0
        ) const;

    void
    convertTo(
        OutputArray dst,
        int rtype,
        double alpha,
        Stream& stream
        ) const;

    void
    convertTo(
        OutputArray dst,
        int rtype,
        double alpha,
        double beta,
        Stream& stream
        ) const;

    void
    copyTo(OutputArray dst) const;

    void
    copyTo(
        OutputArray dst,
        Stream& stream
        ) const;

    void
    copyTo(
        OutputArray dst,
        InputArray mask
        ) const;

    void
    copyTo(
        OutputArray dst,
        InputArray mask,
        Stream& stream
        ) const;

    void
    create(
        int rows,
        int cols,
        int type
        );

    void
    create(
        Size size,
        int type
        );

    int
    depth() const;

    void
    download(OutputArray dst) const;

    void
    download(
        OutputArray dst,
        Stream& stream
        ) const;

    size_t
    elemSize() const;

    size_t
    elemSize1() const;

    bool
    empty() const;

    bool
    isContinuous() const;

    void
    locateROI(
        Size& wholeSize,
        Point& ofs
        ) const;

    template <typename _Tp>
    operator PtrStep< _Tp >() const;

    template <typename _Tp>
    operator PtrStepSz< _Tp >() const;

    GpuMat
    operator()(
        Range rowRange,
        Range colRange
        ) const;

    GpuMat
    operator()(Rect roi) const;

    GpuMat&
    operator=(const GpuMat& m);

    uchar*
    ptr(int y = 0);

    const uchar*
    ptr(int y = 0) const;

    template <typename _Tp>
    _Tp*
    ptr(int y = 0);

    template <typename _Tp>
    const _Tp*
    ptr(int y = 0) const;

    void
    release();

    GpuMat
    reshape(
        int cn,
        int rows = 0
        ) const;

    GpuMat
    row(int y) const;

    GpuMat
    rowRange(
        int startrow,
        int endrow
        ) const;

    GpuMat
    rowRange(Range r) const;

    GpuMat&
    setTo(Scalar s);

    GpuMat&
    setTo(
        Scalar s,
        Stream& stream
        );

    GpuMat&
    setTo(
        Scalar s,
        InputArray mask
        );

    GpuMat&
    setTo(
        Scalar s,
        InputArray mask,
        Stream& stream
        );

    Size
    size() const;

    size_t
    step1() const;

    void
    swap(GpuMat& mat);

    int
    type() const;

    void
    upload(InputArray arr);

    void
    upload(
        InputArray arr,
        Stream& stream
        );
};

// direct descendants

template <typename T>
class GpuMat_;

Detailed Documentation

Base storage class for GPU memory with reference counting.

Its interface matches the Mat interface with the following limitations:

• no arbitrary dimensions support (only 2D)
• no functions that return references to their data (because references on GPU are not valid for CPU)
• no expression templates technique support

Beware that the latter limitation may lead to overloaded matrix operators that cause memory allocations. The GpuMat class is convertible to cuda::PtrStepSz and cuda::PtrStep so it can be passed directly to the kernel.

In contrast with Mat, in most cases GpuMat::isContinuous() == false . This means that rows are aligned to a size depending on the hardware. Single-row GpuMat is always a continuous matrix.

You are not recommended to leave static or global GpuMat variables allocated, that is, to rely on its destructor. The destruction order of such variables and CUDA context is undefined. GPU memory release function returns error if the CUDA context has been destroyed before.

See also:

Mat

Fields

Allocator* allocator

allocator

uchar* data

pointer to the data

uchar* datastart

helper fields used in locateROI and adjustROI

int flags

includes several bit-fields:

• the magic signature
• continuity flag
• depth
• number of channels

int* refcount

pointer to the reference counter; when GpuMat points to user-allocated data, the pointer is NULL

int rows

the number of rows and columns

size_t step

a distance between successive rows in bytes; includes the gap if any

Construction

GpuMat(Allocator* allocator = defaultAllocator())

default constructor

GpuMat(
    int rows,
    int cols,
    int type,
    Allocator* allocator = defaultAllocator()
    )

constructs GpuMat of the specified size and type

GpuMat(
    int rows,
    int cols,
    int type,
    Scalar s,
    Allocator* allocator = defaultAllocator()
    )

constucts GpuMat and fills it with the specified value _s

GpuMat(const GpuMat& m)

copy constructor

GpuMat(
    int rows,
    int cols,
    int type,
    void* data,
    size_t step = Mat::AUTO_STEP
    )

constructor for GpuMat headers pointing to user-allocated data

GpuMat(
    const GpuMat& m,
    Range rowRange,
    Range colRange
    )

creates a GpuMat header for a part of the bigger matrix

GpuMat(
    InputArray arr,
    Allocator* allocator = defaultAllocator()
    )

builds GpuMat from host memory (Blocking call)

Methods

static
Allocator*
defaultAllocator()

default allocator

GpuMat&
adjustROI(
    int dtop,
    int dbottom,
    int dleft,
    int dright
    )

moves/resizes the current GpuMat ROI inside the parent GpuMat

int
channels() const

returns number of channels

GpuMat
clone() const

returns deep copy of the GpuMat, i.e. the data is copied

GpuMat
col(int x) const

returns a new GpuMat header for the specified column

GpuMat
colRange(
    int startcol,
    int endcol
    ) const

… for the specified column span

void
convertTo(
    OutputArray dst,
    int rtype
    ) const

converts GpuMat to another datatype (Blocking call)

void
convertTo(
    OutputArray dst,
    int rtype,
    Stream& stream
    ) const

converts GpuMat to another datatype (Non-Blocking call)

void
convertTo(
    OutputArray dst,
    int rtype,
    double alpha,
    double beta = 0.0
    ) const

converts GpuMat to another datatype with scaling (Blocking call)

void
convertTo(
    OutputArray dst,
    int rtype,
    double alpha,
    Stream& stream
    ) const

converts GpuMat to another datatype with scaling (Non-Blocking call)

void
convertTo(
    OutputArray dst,
    int rtype,
    double alpha,
    double beta,
    Stream& stream
    ) const

converts GpuMat to another datatype with scaling (Non-Blocking call)

void
copyTo(OutputArray dst) const

copies the GpuMat content to device memory (Blocking call)

void
copyTo(
    OutputArray dst,
    Stream& stream
    ) const

copies the GpuMat content to device memory (Non-Blocking call)

void
copyTo(
    OutputArray dst,
    InputArray mask
    ) const

copies those GpuMat elements to “m” that are marked with non-zero mask elements (Blocking call)

void
copyTo(
    OutputArray dst,
    InputArray mask,
    Stream& stream
    ) const

copies those GpuMat elements to “m” that are marked with non-zero mask elements (Non-Blocking call)

void
create(
    int rows,
    int cols,
    int type
    )

allocates new GpuMat data unless the GpuMat already has specified size and type

int
depth() const

returns element type

void
download(OutputArray dst) const

pefroms download data from device to host memory (Blocking call)

void
download(
    OutputArray dst,
    Stream& stream
    ) const

pefroms download data from device to host memory (Non-Blocking call)

size_t
elemSize() const

returns element size in bytes

size_t
elemSize1() const

returns the size of element channel in bytes

bool
empty() const

returns true if GpuMat data is NULL

bool
isContinuous() const

returns true iff the GpuMat data is continuous (i.e. when there are no gaps between successive rows)

void
locateROI(
    Size& wholeSize,
    Point& ofs
    ) const

locates GpuMat header within a parent GpuMat

GpuMat
operator()(
    Range rowRange,
    Range colRange
    ) const

extracts a rectangular sub-GpuMat (this is a generalized form of row, rowRange etc.)

GpuMat&
operator=(const GpuMat& m)

assignment operators

uchar*
ptr(int y = 0)

returns pointer to y-th row

template <typename _Tp>
_Tp*
ptr(int y = 0)

template version of the above method

void
release()

decreases reference counter, deallocate the data when reference counter reaches 0

GpuMat
reshape(
    int cn,
    int rows = 0
    ) const

creates alternative GpuMat header for the same data, with different number of channels and/or different number of rows

GpuMat
row(int y) const

returns a new GpuMat header for the specified row

GpuMat
rowRange(
    int startrow,
    int endrow
    ) const

… for the specified row span

GpuMat&
setTo(Scalar s)

sets some of the GpuMat elements to s (Blocking call)

GpuMat&
setTo(
    Scalar s,
    Stream& stream
    )

sets some of the GpuMat elements to s (Non-Blocking call)

GpuMat&
setTo(
    Scalar s,
    InputArray mask
    )

sets some of the GpuMat elements to s, according to the mask (Blocking call)

GpuMat&
setTo(
    Scalar s,
    InputArray mask,
    Stream& stream
    )

sets some of the GpuMat elements to s, according to the mask (Non-Blocking call)

Size
size() const

returns GpuMat size : width == number of columns, height == number of rows

size_t
step1() const

returns step/elemSize1()

void
swap(GpuMat& mat)

swaps with other smart pointer

int
type() const

returns element type

void
upload(InputArray arr)

pefroms upload data to GpuMat (Blocking call)

void
upload(
    InputArray arr,
    Stream& stream
    )

pefroms upload data to GpuMat (Non-Blocking call)