class cv::ogl::Buffer

Overview

Smart pointer for OpenGL buffer object with reference counting. More…

#include <opengl.hpp>

class Buffer
{
public:
    // enums

    enum Access;
    enum Target;

    // construction

    Buffer();

    Buffer(
        int arows,
        int acols,
        int atype,
        unsigned int abufId,
        bool autoRelease = false
        );

    Buffer(
        Size asize,
        int atype,
        unsigned int abufId,
        bool autoRelease = false
        );

    Buffer(
        int arows,
        int acols,
        int atype,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    Buffer(
        Size asize,
        int atype,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    Buffer(
        InputArray arr,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    // methods

    void
    bind(Target target) const;

    unsigned int
    bufId() const;

    int
    channels() const;

    Buffer
    clone(
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        ) const;

    int
    cols() const;

    void
    copyFrom(
        InputArray arr,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    void
    copyFrom(
        InputArray arr,
        cuda::Stream& stream,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    void
    copyTo(OutputArray arr) const;

    void
    copyTo(
        OutputArray arr,
        cuda::Stream& stream
        ) const;

    void
    create(
        int arows,
        int acols,
        int atype,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    void
    create(
        Size asize,
        int atype,
        Target target = ARRAY_BUFFER,
        bool autoRelease = false
        );

    int
    depth() const;

    int
    elemSize() const;

    int
    elemSize1() const;

    bool
    empty() const;

    cuda::GpuMat
    mapDevice();

    cuda::GpuMat
    mapDevice(cuda::Stream& stream);

    Mat
    mapHost(Access access);

    void
    release();

    int
    rows() const;

    void
    setAutoRelease(bool flag);

    Size
    size() const;

    int
    type() const;

    void
    unmapDevice();

    void
    unmapDevice(cuda::Stream& stream);

    void
    unmapHost();

    static
    void
    unbind(Target target);
};

Detailed Documentation

Smart pointer for OpenGL buffer object with reference counting.

Buffer Objects are OpenGL objects that store an array of unformatted memory allocated by the OpenGL context. These can be used to store vertex data, pixel data retrieved from images or the framebuffer, and a variety of other things.

ogl::Buffer has interface similar with Mat interface and represents 2D array memory.

ogl::Buffer supports memory transfers between host and device and also can be mapped to CUDA memory.

Construction

Buffer()

The constructors.

Creates empty ogl::Buffer object, creates ogl::Buffer object from existed buffer ( abufId parameter), allocates memory for ogl::Buffer object or copies from host/device memory.

Buffer(
    int arows,
    int acols,
    int atype,
    unsigned int abufId,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

arows Number of rows in a 2D array.
acols Number of columns in a 2D array.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
abufId Buffer object name.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
Buffer(
    Size asize,
    int atype,
    unsigned int abufId,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

asize 2D array size.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
abufId Buffer object name.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
Buffer(
    int arows,
    int acols,
    int atype,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

arows Number of rows in a 2D array.
acols Number of columns in a 2D array.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
Buffer(
    Size asize,
    int atype,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

asize 2D array size.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
Buffer(
    InputArray arr,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

arr Input array (host or device memory, it can be Mat, cuda::GpuMat or std::vector ).
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor).

Methods

void
bind(Target target) const

Binds OpenGL buffer to the specified buffer binding point.

Parameters:

target Binding point. See cv::ogl::Buffer::Target. 
unsigned int
bufId() const

get OpenGL opject id

Buffer
clone(
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    ) const

Creates a full copy of the buffer object and the underlying data.

Parameters:

target Buffer usage for destination buffer.
autoRelease Auto release mode for destination buffer. 
void
copyFrom(
    InputArray arr,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

Copies from host/device memory to OpenGL buffer.

Parameters:

arr Input array (host or device memory, it can be Mat, cuda::GpuMat or std::vector ).
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
void
copyFrom(
    InputArray arr,
    cuda::Stream& stream,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
copyTo(OutputArray arr) const

Copies from OpenGL buffer to host/device memory or another OpenGL buffer object.

Parameters:

arr Destination array (host or device memory, can be Mat, cuda::GpuMat, std::vector or ogl::Buffer). 
void
copyTo(
    OutputArray arr,
    cuda::Stream& stream
    ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
create(
    int arows,
    int acols,
    int atype,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

Allocates memory for ogl::Buffer object.

Parameters:

arows Number of rows in a 2D array.
acols Number of columns in a 2D array.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
void
create(
    Size asize,
    int atype,
    Target target = ARRAY_BUFFER,
    bool autoRelease = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

asize 2D array size.
atype Array type ( CV_8UC1, …, CV_64FC4 ). See Mat for details.
target Buffer usage. See cv::ogl::Buffer::Target.
autoRelease Auto release mode (if true, release will be called in object’s destructor). 
cuda::GpuMat
mapDevice()

map to device memory (blocking)

cuda::GpuMat
mapDevice(cuda::Stream& stream)

Maps OpenGL buffer to CUDA device memory.

This operatation doesn’t copy data. Several buffer objects can be mapped to CUDA memory at a time.

A mapped data store must be unmapped with ogl::Buffer::unmapDevice before its buffer object is used.

Mat
mapHost(Access access)

Maps OpenGL buffer to host memory.

mapHost maps to the client’s address space the entire data store of the buffer object. The data can then be directly read and/or written relative to the returned pointer, depending on the specified access policy.

A mapped data store must be unmapped with ogl::Buffer::unmapHost before its buffer object is used.

This operation can lead to memory transfers between host and device.

Only one buffer object can be mapped at a time.

Parameters:

access Access policy, indicating whether it will be possible to read from, write to, or both read from and write to the buffer object’s mapped data store. The symbolic constant must be ogl::Buffer::READ_ONLY, ogl::Buffer::WRITE_ONLY or ogl::Buffer::READ_WRITE. 
void
release()

Decrements the reference counter and destroys the buffer object if needed.

The function will call setAutoRelease(true) .

void
setAutoRelease(bool flag)

Sets auto release mode.

The lifetime of the OpenGL object is tied to the lifetime of the context. If OpenGL context was bound to a window it could be released at any time (user can close a window). If object’s destructor is called after destruction of the context it will cause an error. Thus ogl::Buffer doesn’t destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context). This function can force ogl::Buffer destructor to destroy OpenGL object.

Parameters:

flag Auto release mode (if true, release will be called in object’s destructor). 
void
unmapDevice(cuda::Stream& stream)

Unmaps OpenGL buffer.

void
unmapHost()

Unmaps OpenGL buffer.

static
void
unbind(Target target)

Unbind any buffers from the specified binding point.

Parameters:

target Binding point. See cv::ogl::Buffer::Target.