potok/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2026-07-31 08:13:04 +04:00
Code Packages Releases Wiki Activity

corrected grammar (done by Elena)

Browse Source
This commit is contained in:
Vadim Pisarevsky
2011-03-28 23:16:20 +00:00
parent fafc2f372c
commit 5291b9dfe5
4 changed files with 443 additions and 511 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/gpu/doc/data_structures.rst
+147 -148
View File
@@ -1,17 +1,14 @@
Data Structures
===============
.. highlight:: cpp
.. index:: gpu::DevMem2D\_
.. index:: gpu::DevMem2D_
gpu::DevMem2D\_
gpu::DevMem2D\_
---------------
.. cpp:class:: gpu::DevMem2D_
.. cpp:class:: gpu::DevMem2D\_
This is a simple lightweight class that encapsulate pitched memory on GPU. It is intended to pass to nvcc-compiled code, i.e. CUDA kernels. So it is used internally by OpenCV and by users writes own device code. Its members can be called both from host and from device code. ::
This lightweight class encapsulates pitched memory on a GPU and is passed to nvcc-compiled code (CUDA kernels). Typically, it is used internally by OpenCV and by users who write device code. You can call its members from both host and device code.
::
template <typename T> struct DevMem2D_
{
@@ -31,7 +28,7 @@ This is a simple lightweight class that encapsulate pitched memory on GPU. It is
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
/* returns pointer to the beggining of given image row */
/* returns pointer to the beggining of the given image row */
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
@@ -41,29 +38,30 @@ This is a simple lightweight class that encapsulate pitched memory on GPU. It is
typedef DevMem2D_<int> DevMem2Di;
.. index:: gpu::PtrStep_
.. index:: gpu::PtrStep\_
gpu::PtrStep\_
--------------
.. cpp:class:: gpu::PtrStep_
.. cpp:class:: gpu::PtrStep\_
This is structure is similar to :cpp:class:`gpu::DevMem2D_` but contains only pointer and row step. Width and height fields are excluded due to performance reasons. The structure is for internal use or for users who write own device code. ::
This structure is similar to
:cpp:class:`DevMem2D_` but contains only a pointer and row step. Width and height fields are excluded due to performance reasons. The structure is intended for internal use or for users who write device code.
::
template<typename T> struct PtrStep_
{
T* data;
size_t step;
T* data;
size_t step;
PtrStep_();
PtrStep_(const DevMem2D_<T>& mem);
PtrStep_();
PtrStep_(const DevMem2D_<T>& mem);
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
typedef PtrStep_<unsigned char> PtrStep;
@@ -71,27 +69,23 @@ This is structure is similar to :cpp:class:`gpu::DevMem2D_` but contains only po
typedef PtrStep_<int> PtrStepi;
.. index:: gpu::PtrElemStrp\_
.. index:: gpu::PtrElemStep_
gpu::PtrElemStep\_
gpu::PtrElemStrp\_
------------------
.. cpp:class:: gpu::PtrElemStep_
.. cpp:class:: gpu::PtrElemStrp\_
This is structure is similar to :cpp:class:`gpu::DevMem2D_` but contains only pointer and row step in elements. Width and height fields are excluded due to performance reasons. This class is can only be constructed if ``sizeof(T)`` is a multiple of 256. The structure is for internal use or for users who write own device code. ::
This structure is similar to
:cpp:class:`DevMem2D_` but contains only pointer and row step in elements. Width and height fields are excluded due to performance reasons. This class can only be constructed if ``sizeof(T)`` is a multiple of 256. The structure is intended for internal use or for users who write device code.
::
template<typename T> struct PtrElemStep_ : public PtrStep_<T>
{
PtrElemStep_(const DevMem2D_<T>& mem);
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
PtrElemStep_(const DevMem2D_<T>& mem);
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
typedef PtrElemStep_<unsigned char> PtrElemStep;
typedef PtrElemStep_<float> PtrElemStepf;
typedef PtrElemStep_<int> PtrElemStepi;
.. index:: gpu::GpuMat
@@ -99,47 +93,58 @@ gpu::GpuMat
-----------
.. cpp:class:: gpu::GpuMat
The base storage class for GPU memory with reference counting. Its interface is almost :c:type:`Mat` interface with some limitations, so using it won't be a problem. The limitations are no arbitrary dimensions support (only 2D), no functions that returns references to its data (because references on GPU are not valid for CPU), no expression templates technique support. Because of last limitation please take care with overloaded matrix operators - they cause memory allocations. The ``GpuMat`` class is convertible to :cpp:class:`gpu::DevMem2D_` and :cpp:class:`gpu::PtrStep_` so it can be passed to directly to kernel.
This is a base storage class for GPU memory with reference counting. Its interface matches the
:c:type:`Mat` interface with the following limitations:
**Please note:** In contrast with :c:type:`Mat`, in most cases ``GpuMat::isContinuous() == false`` , i.e. rows are aligned to size depending on hardware. Also single row ``GpuMat`` is always a continuous matrix. ::
*
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 :cpp:class:`gpu::DevMem2D_` and :cpp:class:`gpu::PtrStep_` so it can be passed to directly to kernel.
class GpuMat
**Note:**
In contrast with :c:type:`Mat`, in most cases ``GpuMat::isContinuous() == false`` . This means that rows are aligned to size depending on the hardware. Single-row ``GpuMat`` is always a continuous matrix. ::
class CV_EXPORTS GpuMat
{
public:
//! default constructor
GpuMat();
//! default constructor
GpuMat();
GpuMat(int rows, int cols, int type);
GpuMat(Size size, int type);
GpuMat(int rows, int cols, int type);
GpuMat(Size size, int type);
.....
.....
//! builds GpuMat from Mat. Perfom blocking upload to device.
explicit GpuMat (const Mat& m);
//! builds GpuMat from Mat. Blocks uploading to device.
explicit GpuMat (const Mat& m);
//! returns lightweight DevMem2D_ structure for passing
//to nvcc-compiled code. Contains size, data ptr and step.
template <class T> operator DevMem2D_<T>() const;
template <class T> operator PtrStep_<T>() const;
//! returns lightweight DevMem2D_ structure for passing
//to nvcc-compiled code. Contains size, data ptr and step.
template <class T> operator DevMem2D_<T>() const;
template <class T> operator PtrStep_<T>() const;
//! pefroms blocking upload data to GpuMat.
void upload(const cv::Mat& m);
void upload(const CudaMem& m, Stream& stream);
//! blocks uploading data to GpuMat.
void upload(const cv::Mat& m);
void upload(const CudaMem& m, Stream& stream);
//! downloads data from device to host memory. Blocking calls.
operator Mat() const;
void download(cv::Mat& m) const;
//! downloads data from device to host memory. Blocking calls.
operator Mat() const;
void download(cv::Mat& m) const;
//! download async
void download(CudaMem& m, Stream& stream) const;
//! download async
void download(CudaMem& m, Stream& stream) const;
};
**Please note:** Is it a bad practice to leave static or global ``GpuMat`` variables allocated, i.e. to rely on its destructor. That is because destruction order of such variables and CUDA context is undefined and GPU memory release function returns error if CUDA context has been destroyed before.
See also: :c:type:`Mat`.
**Note:**
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:
:func:`Mat`
.. index:: gpu::CudaMem
@@ -147,47 +152,50 @@ gpu::CudaMem
------------
.. cpp:class:: gpu::CudaMem
This is a class with reference counting that wraps special memory type allocation functions from CUDA. Its interface is also :c:type:`Mat`-like but with additional memory type parameter:
This class with reference counting wraps special memory type allocation functions from CUDA. Its interface is also
:func:`Mat`-like but with additional memory type parameters.
*
``ALLOC_PAGE_LOCKED``: Sets a page locked memory type, used commonly for fast and asynchronous upload/download data from/to GPU.
*
``ALLOC_ZEROCOPY``: Specifies a zero copy memory allocation that enables mapping the host memory to GPU address space, if supported.
*
``ALLOC_WRITE_COMBINED``: Sets the write combined buffer that is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is a better CPU cache utilization.
* ``ALLOC_PAGE_LOCKED`` Set page locked memory type, used commonly for fast and asynchronous upload/download data from/to GPU.
**Note:**
Allocation size of such memory types is usually limited. For more details please see "CUDA 2.2 Pinned Memory APIs" document or "CUDA_C Programming Guide".
::
* ``ALLOC_ZEROCOPY`` Specifies zero copy memory allocation, i.e. with possibility to map host memory to GPU address space if supported.
* ``ALLOC_WRITE_COMBINED`` Sets write combined buffer which is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is better CPU cache utilization.
**Please note:** Allocation size of such memory types is usually limited. For more details please see "CUDA 2.2 Pinned Memory APIs" document or "CUDA_C Programming Guide". ::
class CudaMem
class CV_EXPORTS CudaMem
{
public:
enum { ALLOC_PAGE_LOCKED = 1, ALLOC_ZEROCOPY = 2,
ALLOC_WRITE_COMBINED = 4 };
enum { ALLOC_PAGE_LOCKED = 1, ALLOC_ZEROCOPY = 2,
ALLOC_WRITE_COMBINED = 4 };
CudaMem(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
CudaMem(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
//! creates from cv::Mat with coping data
explicit CudaMem(const Mat& m, int alloc_type = ALLOC_PAGE_LOCKED);
//! creates from cv::Mat with coping data
explicit CudaMem(const Mat& m, int alloc_type = ALLOC_PAGE_LOCKED);
......
......
void create(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
void create(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
//! returns matrix header with disabled ref. counting for CudaMem data.
Mat createMatHeader() const;
operator Mat() const;
//! returns matrix header with disabled ref. counting for CudaMem data.
Mat createMatHeader() const;
operator Mat() const;
//! maps host memory into device address space
GpuMat createGpuMatHeader() const;
operator GpuMat() const;
//! maps host memory into device address space
GpuMat createGpuMatHeader() const;
operator GpuMat() const;
//if host memory can be mapperd to gpu address space;
static bool canMapHostMemory();
//if host memory can be mapped to gpu address space;
static bool canMapHostMemory();
int alloc_type;
int alloc_type;
};
.. index:: gpu::CudaMem::createMatHeader
gpu::CudaMem::createMatHeader
@@ -195,11 +203,7 @@ gpu::CudaMem::createMatHeader
.. cpp:function:: Mat gpu::CudaMem::createMatHeader() const
.. cpp:function:: gpu::CudaMem::operator Mat() const
Creates header without reference counting to :cpp:class:`gpu::CudaMem` data.
Creates a header without reference counting to :cpp:class:`gpu::CudaMem` data.
.. index:: gpu::CudaMem::createGpuMatHeader
@@ -208,11 +212,7 @@ gpu::CudaMem::createGpuMatHeader
.. cpp:function:: GpuMat gpu::CudaMem::createGpuMatHeader() const
.. cpp:function:: gpu::CudaMem::operator GpuMat() const
Maps CPU memory to GPU address space and creates :cpp:class:`gpu::GpuMat` header without reference counting for it. This can be done only if memory was allocated with ``ALLOC_ZEROCOPY`` flag and if it is supported by hardware (laptops often share video and CPU memory, so address spaces can be mapped, and that eliminates extra copy).
Maps CPU memory to GPU address space and creates :cpp:class:`gpu::GpuMat` header without reference counting for it. This can be done only if memory was allocated with ``ALLOC_ZEROCOPY`` flag and if it is supported by the hardware (laptops often share video and CPU memory, so address spaces can be mapped, and that eliminates an extra copy).
.. index:: gpu::CudaMem::canMapHostMemory
@@ -222,54 +222,53 @@ gpu::CudaMem::canMapHostMemory
Returns true if the current hardware supports address space mapping and ``ALLOC_ZEROCOPY`` memory allocation.
.. index:: gpu::Stream
gpu::Stream
-----------
.. cpp:class:: gpu::Stream
This class encapsulated queue of the asynchronous calls. Some functions have overloads with additional ``gpu::Stream`` parameter. The overloads do initialization work (allocate output buffers, upload constants, etc.), start GPU kernel and return before results are ready. A check if all operation are complete can be performed via :cpp:func:`gpu::Stream::queryIfComplete`. Asynchronous upload/download have to be performed from/to page-locked buffers, i.e. using :cpp:class:`gpu::CudaMem` or :c:type:`Mat` header that points to a region of :cpp:class:`gpu::CudaMem`.
This class encapsulated a queue of asynchronous calls. Some functions have overloads with the additional ``gpu::Stream`` parameter. The overloads do initialization work (allocate output buffers, upload constants, and so on), start the GPU kernel, and return before results are ready. You can check whether all operation are complete via :cpp:func:`gpu::Stream::queryIfComplete`. You can asynchronously upload/download data from/to page-locked buffers, using :cpp:class:`gpu::CudaMem` or :c:type:`Mat` header that points to a region of :cpp:class:`gpu::CudaMem`.
**Please note the limitation**: currently it is not guaranteed that all will work properly if one operation will be enqueued twice with different data. Some functions use constant GPU memory and next call may update the memory before previous has been finished. But calling asynchronously different operations is safe because each operation has own constant buffer. Memory copy/upload/download/set operations to buffers hold by user are also safe. ::
**Note:**
Currently, you may face problems if an operation is enqueued twice with different data. Some functions use the constant GPU memory, and next call may update the memory before the previous one has been finished. But calling different operations asynchronously is safe because each operation has its own constant buffer. Memory copy/upload/download/set operations to the buffers you hold are also safe.
::
class Stream
class CV_EXPORTS Stream
{
public:
Stream();
~Stream();
Stream();
~Stream();
Stream(const Stream&);
Stream& operator=(const Stream&);
Stream(const Stream&);
Stream& operator=(const Stream&);
bool queryIfComplete();
void waitForCompletion();
bool queryIfComplete();
void waitForCompletion();
//! downloads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its subMat)
void enqueueDownload(const GpuMat& src, CudaMem& dst);
void enqueueDownload(const GpuMat& src, Mat& dst);
//! downloads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its subMat)
void enqueueDownload(const GpuMat& src, CudaMem& dst);
void enqueueDownload(const GpuMat& src, Mat& dst);
//! uploads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its ROI)
void enqueueUpload(const CudaMem& src, GpuMat& dst);
void enqueueUpload(const Mat& src, GpuMat& dst);
//! uploads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its ROI)
void enqueueUpload(const CudaMem& src, GpuMat& dst);
void enqueueUpload(const Mat& src, GpuMat& dst);
void enqueueCopy(const GpuMat& src, GpuMat& dst);
void enqueueCopy(const GpuMat& src, GpuMat& dst);
void enqueueMemSet(const GpuMat& src, Scalar val);
void enqueueMemSet(const GpuMat& src, Scalar val, const GpuMat& mask);
void enqueueMemSet(const GpuMat& src, Scalar val);
void enqueueMemSet(const GpuMat& src, Scalar val, const GpuMat& mask);
// converts matrix type, ex from float to uchar depending on type
void enqueueConvert(const GpuMat& src, GpuMat& dst, int type,
double a = 1, double b = 0);
// converts matrix type, ex from float to uchar depending on type
void enqueueConvert(const GpuMat& src, GpuMat& dst, int type,
double a = 1, double b = 0);
};
.. index:: gpu::Stream::queryIfComplete
gpu::Stream::queryIfComplete
@@ -278,8 +277,6 @@ gpu::Stream::queryIfComplete
Returns true if the current stream queue is finished, otherwise false.
.. index:: gpu::Stream::waitForCompletion
gpu::Stream::waitForCompletion
@@ -288,30 +285,28 @@ gpu::Stream::waitForCompletion
Blocks until all operations in the stream are complete.
.. index:: gpu::StreamAccessor
gpu::StreamAccessor
-------------------
.. cpp:class:: gpu::StreamAccessor
This class provides possibility to get ``cudaStream_t`` from :cpp:class:`gpu::Stream`. This class is declared in ``stream_accessor.hpp`` because that is only public header that depend on Cuda Runtime API. Including it will bring the dependency to your code. ::
This class enables getting ``cudaStream_t`` from :cpp:class:`gpu::Stream` and is declared in ``stream_accessor.hpp`` because it is the only public header that depends on the CUDA Runtime API. Including it brings a dependency to your code.
::
struct StreamAccessor
{
static cudaStream_t getStream(const Stream& stream);
CV_EXPORTS static cudaStream_t getStream(const Stream& stream);
};
.. index:: gpu::createContinuous
gpu::createContinuous
-------------------------
.. cpp:function:: void gpu::createContinuous(int rows, int cols, int type, GpuMat& m)
Creates continuous matrix in GPU memory.
Creates a continuous matrix in the GPU memory.
:param rows: Row count.
@@ -319,19 +314,18 @@ gpu::createContinuous
:param type: Type of the matrix.
:param m: Destination matrix. Will be only reshaped if it has proper type and area (``rows`` :math:`\times` ``cols``).
Also the following wrappers are available:
.. cpp:function:: GpuMat gpu::createContinuous(int rows, int cols, int type)
.. cpp:function:: void gpu::createContinuous(Size size, int type, GpuMat& m)
.. cpp:function:: GpuMat gpu::createContinuous(Size size, int type)
Matrix is called continuous if its elements are stored continuously, i.e. wuthout gaps in the end of each row.
:param m: Destination matrix. This parameter changes only if it has a proper type and area (``rows x cols``).
The following wrappers are also available:
*
.. cpp:function:: GpuMat gpu::createContinuous(int rows, int cols, int type)
*
.. cpp:function:: void gpu::createContinuous(Size size, int type, GpuMat& m)
*
.. cpp:function:: GpuMat gpu::createContinuous(Size size, int type)
Matrix is called continuous if its elements are stored continuously, that is wuthout gaps in the end of each row.
.. index:: gpu::ensureSizeIsEnough
@@ -339,16 +333,21 @@ gpu::ensureSizeIsEnough
---------------------------
.. cpp:function:: void gpu::ensureSizeIsEnough(int rows, int cols, int type, GpuMat& m)
Ensures that size of matrix is big enough and matrix has proper type. The function doesn't reallocate memory if the matrix has proper attributes already.
.. cpp:function:: void gpu::ensureSizeIsEnough(Size size, int type, GpuMat& m)
Ensures that the size of a matrix is big enough and the matrix has a proper type. The function does not reallocate memory if the matrix has proper attributes already.
:param rows: Minimum desired number of rows.
:param cols: Minimum desired number of cols.
:param cols: Minimum desired number of columns.
:param size: rows and cols passed as a structure
:param type: Desired matrix type.
:param m: Destination matrix.
Also the following wrapper is available:
The following wrapper is also available:
.. cpp:function:: void gpu::ensureSizeIsEnough(Size size, int type, GpuMat& m)