generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

cv::Ptr description extended.

Browse Source
This commit is contained in:
Alexander 2013-02-17 18:18:12 +04:00 committed by Alexander Smorkalov
parent 39baa2237e
commit 4091eab45e
1 changed files with 110 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
modules/core/doc/basic_structures.rst
View File

@ -418,27 +418,47 @@ Template class for smart reference-counting pointers ::
};
The ``Ptr<_Tp>`` class is a template class that wraps pointers of the corresponding type. It is similar to ``shared_ptr`` that is part of the Boost library (
http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm
) and also part of the `C++0x <http://en.wikipedia.org/wiki/C++0x>`_
standard.
The ``Ptr<_Tp>`` class is a template class that wraps pointers of the corresponding type. It is
similar to ``shared_ptr`` that is part of the Boost library
(http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm) and also part of the
`C++0x <http://en.wikipedia.org/wiki/C++0x>`_ standard.
This class provides the following options:
*
Default constructor, copy constructor, and assignment operator for an arbitrary C++ class or a C structure. For some objects, like files, windows, mutexes, sockets, and others, a copy constructor or an assignment operator are difficult to define. For some other objects, like complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally, some of complex OpenCV and your own data structures may be written in C. However, copy constructors and default constructors can simplify programming a lot. Besides, they are often required (for example, by STL containers). By wrapping a pointer to such a complex object ``TObj`` to ``Ptr<TObj>`` , you automatically get all of the necessary constructors and the assignment operator.
Default constructor, copy constructor, and assignment operator for an arbitrary C++ class
or a C structure. For some objects, like files, windows, mutexes, sockets, and others, a copy
constructor or an assignment operator are difficult to define. For some other objects, like
complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally,
some of complex OpenCV and your own data structures may be written in C.
However, copy constructors and default constructors can simplify programming a lot.Besides,
they are often required (for example, by STL containers). By wrapping a pointer to such a
complex object ``TObj`` to ``Ptr<TObj>``, you automatically get all of the necessary
constructors and the assignment operator.
*
*O(1)* complexity of the above-mentioned operations. While some structures, like ``std::vector``, provide a copy constructor and an assignment operator, the operations may take a considerable amount of time if the data structures are large. But if the structures are put into ``Ptr<>`` , the overhead is small and independent of the data size.
*O(1)* complexity of the above-mentioned operations. While some structures, like ``std::vector``,
provide a copy constructor and an assignment operator, the operations may take a considerable
amount of time if the data structures are large. But if the structures are put into ``Ptr<>``,
the overhead is small and independent of the data size.
*
Automatic destruction, even for C structures. See the example below with ``FILE*`` .
Automatic destruction, even for C structures. See the example below with ``FILE*``.
*
Heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers can store only objects of the same type and the same size. The classical solution to store objects of different types in the same container is to store pointers to the base class ``base_class_t*`` instead but then you loose the automatic memory management. Again, by using ``Ptr<base_class_t>()`` instead of the raw pointers, you can solve the problem.
Heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers
can store only objects of the same type and the same size. The classical solution to store objects
of different types in the same container is to store pointers to the base class ``base_class_t*``
instead but then you loose the automatic memory management. Again, by using ``Ptr<base_class_t>()``
instead of the raw pointers, you can solve the problem.
The ``Ptr`` class treats the wrapped object as a black box. The reference counter is allocated and managed separately. The only thing the pointer class needs to know about the object is how to deallocate it. This knowledge is encapsulated in the ``Ptr::delete_obj()`` method that is called when the reference counter becomes 0. If the object is a C++ class instance, no additional coding is needed, because the default implementation of this method calls ``delete obj;`` .
However, if the object is deallocated in a different way, the specialized method should be created. For example, if you want to wrap ``FILE`` , the ``delete_obj`` may be implemented as follows: ::
The ``Ptr`` class treats the wrapped object as a black box. The reference counter is allocated and
managed separately. The only thing the pointer class needs to know about the object is how to
deallocate it. This knowledge is encapsulated in the ``Ptr::delete_obj()`` method that is called when
the reference counter becomes 0. If the object is a C++ class instance, no additional coding is
needed, because the default implementation of this method calls ``delete obj;``. However, if the
object is deallocated in a different way, the specialized method should be created. For example,
if you want to wrap ``FILE``, the ``delete_obj`` may be implemented as follows: ::
template<> inline void Ptr<FILE>::delete_obj()
{
@ -456,7 +476,73 @@ However, if the object is deallocated in a different way, the specialized method
// the file will be closed automatically by the Ptr<FILE> destructor.
.. note:: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for :ocv:class:`Mat` and other C++ OpenCV classes that operate on the reference counters.
.. note:: The reference increment/decrement operations are implemented as atomic operations,
and therefore it is normally safe to use the classes in multi-threaded applications.
The same is true for :ocv:class:`Mat` and other C++ OpenCV classes that operate on
the reference counters.
Ptr::Ptr
--------
Various Ptr constructors.
.. ocv:function:: Ptr::Ptr()
.. ocv:function:: Ptr::Ptr(_Tp* _obj)
.. ocv:function:: Ptr::Ptr(const Ptr& ptr)
Ptr::~Ptr
---------
The Ptr destructor.
.. ocv:function:: Ptr::~Ptr()
Ptr::operator =
----------------
Assignment operator.
.. ocv:function:: Ptr& Ptr::operator = (const Ptr& ptr)
Decrements own reference counter (with ``release()``) and increments ptr's reference counter.
Ptr::addref
-----------
Increments reference counter.
.. ocv:function:: void Ptr::addref()
Ptr::release
------------
Decrements reference counter; when it becomes 0, ``delete_obj()`` is called.
.. ocv:function:: void Ptr::release()
Ptr::delete_obj
---------------
User-specified custom object deletion operation. By default, ``delete obj;`` is called.
.. ocv:function:: void Ptr::delete_obj()
Ptr::empty
----------
Returns true if obj == 0;
bool empty() const;
Ptr::operator ->
----------------
Provide access to the object fields and methods.
.. ocv:function:: template<typename _Tp> _Tp* Ptr::operator -> ()
.. ocv:function:: template<typename _Tp> const _Tp* Ptr::operator -> () const
Ptr::operator _Tp*
------------------
Returns the underlying object pointer. Thanks to the methods, the ``Ptr<_Tp>`` can be used instead
of ``_Tp*``.
.. ocv:function:: template<typename _Tp> Ptr::operator _Tp* ()
.. ocv:function:: template<typename _Tp> Ptr::operator const _Tp*() const
Mat
---
@ -494,9 +580,9 @@ OpenCV C++ n-dimensional dense array class ::
The class ``Mat`` represents an n-dimensional dense numerical single-channel or multi-channel array. It can be used to store real or complex-valued vectors and matrices, grayscale or color images, voxel volumes, vector fields, point clouds, tensors, histograms (though, very high-dimensional histograms may be better stored in a ``SparseMat`` ). The data layout of the array
:math:`M` is defined by the array ``M.step[]`` , so that the address of element
:math:`(i_0,...,i_{M.dims-1})` , where
:math:`0\leq i_k<M.size[k]` , is computed as:
:math:`M` is defined by the array ``M.step[]``, so that the address of element
:math:`(i_0,...,i_{M.dims-1})`, where
:math:`0\leq i_k<M.size[k]`, is computed as:
.. math::
@ -905,7 +991,7 @@ Provides matrix assignment operators.
:param m: Assigned, right-hand-side matrix. Matrix assignment is an O(1) operation. This means that no data is copied but the data is shared and the reference counter, if any, is incremented. Before assigning new data, the old data is de-referenced via :ocv:func:`Mat::release` .
:param expr: Assigned matrix expression object. As opposite to the first form of the assignment operation, the second form can reuse already allocated matrix if it has the right size and type to fit the matrix expression result. It is automatically handled by the real function that the matrix expressions is expanded to. For example, ``C=A+B`` is expanded to ``add(A, B, C)`` , and :func:`add` takes care of automatic ``C`` reallocation.
:param expr: Assigned matrix expression object. As opposite to the first form of the assignment operation, the second form can reuse already allocated matrix if it has the right size and type to fit the matrix expression result. It is automatically handled by the real function that the matrix expressions is expanded to. For example, ``C=A+B`` is expanded to ``add(A, B, C)``, and :func:`add` takes care of automatic ``C`` reallocation.
:param s: Scalar assigned to each matrix element. The matrix size or type is not changed.
@ -1983,7 +2069,7 @@ The class ``SparseMat`` represents multi-dimensional sparse numerical arrays. Su
:ocv:class:`Mat` can store. *Sparse* means that only non-zero elements are stored (though, as a result of operations on a sparse matrix, some of its stored elements can actually become 0. It is up to you to detect such elements and delete them using ``SparseMat::erase`` ). The non-zero elements are stored in a hash table that grows when it is filled so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:
*
Query operations ( ``SparseMat::ptr`` and the higher-level ``SparseMat::ref``, ``SparseMat::value`` and ``SparseMat::find`` ), for example:
Query operations (``SparseMat::ptr`` and the higher-level ``SparseMat::ref``, ``SparseMat::value`` and ``SparseMat::find``), for example:
::