@ -710,187 +710,328 @@ train descriptor index, train image index, and distance between descriptors. ::
};
.. _Ptr:
Ptr
---
.. ocv:class :: Ptr
Template class for smart reference-counting pointers ::
Template class for smart pointers with shared ownership. ::
template<typename _Tp> class Ptr
template<typename T>
struct Ptr
{
public:
// default constructor
typedef T element_type;
Ptr();
// constructor that wraps the object pointer
Ptr(_Tp* _obj);
// destructor: calls release()
template<typename Y>
explicit Ptr(Y* p);
template<typename Y, typename D>
Ptr(Y* p, D d);
Ptr(const Ptr& o);
template<typename Y>
Ptr(const Ptr<Y>& o);
template<typename Y>
Ptr(const Ptr<Y>& o, T* p);
~Ptr();
// copy constructor; increments ptr's reference counter
Ptr(const Ptr& ptr);
// assignment operator; decrements own reference counter
// (with release()) and increments ptr's reference counter
Ptr& operator = (const Ptr& ptr);
// increments reference counter
void addref();
// decrements reference counter; when it becomes 0,
// delete_obj() is called
Ptr& operator = (const Ptr& o);
template<typename Y>
Ptr& operator = (const Ptr<Y>& o);
void release();
// user-specified custom object deletion operation.
// by default, "delete obj;" is called
void delete_obj();
// returns true if obj == 0;
template<typename Y>
void reset(Y* p);
template<typename Y, typename D>
void reset(Y* p, D d);
void swap(Ptr& o);
T* get() const;
T& operator * () const;
T* operator -> () const;
operator T* () const;
bool empty() const;
// provide access to the object fields and methods
_Tp* operator -> ();
const _Tp* operator -> () const;
// return the underlying object pointer;
// thanks to the methods, the Ptr<_Tp> can be
// used instead of _Tp*
operator _Tp* ();
operator const _Tp*() const;
protected:
// the encapsulated object pointer
_Tp* obj;
// the associated reference counter
int* refcount;
template<typename Y>
Ptr<Y> staticCast() const;
template<typename Y>
Ptr<Y> constCast() const;
template<typename Y>
Ptr<Y> dynamicCast() const;
};
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.
A `` Ptr<T> `` pretends to be a pointer to an object of type T.
Unlike an ordinary pointer, however, the object will be automatically
cleaned up once all `` Ptr `` instances pointing to it are destroyed.
`` Ptr `` is similar to `` boost::shared_ptr `` that is part of the Boost library
(http://www.boost.org/doc/libs/release/libs/smart_ptr/shared_ptr.htm)
and `` std::shared_ptr `` from the `C++11 <http://en.wikipedia.org/wiki/C++11> `_ standard.
This class provides the following options:
This class provides the following advantage s:
*
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
or 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
However, copy constructors and default constructors can simplify programming a lot. Besides,
they are often required (for example, by STL containers). By using a `` Ptr `` to such an
object instead of the object itself , 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<> `` ,
amount of time if the data structures are large. But if the structures are put into a `` Ptr `` ,
the overhead is small and independent of the data size.
*
Automatic destruction , even for C structures. See the example below with `` FILE* `` .
Automatic and customizable cleanup , 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 loo se 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 an d
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()
{
fclose(obj); // no need to clear the pointer afterwards,
// it is done externally .
}
...
// now use it :
Ptr<FILE> f(fopen("myfile.txt", "r"));
if(f.empty())
throw ...;
of different types in the same container is to store pointers to the base class (`` Base* `` )
instead but then you lose the automatic memory management. Again, by using `` Ptr<Base> ``
instead of raw pointers, you can solve the problem.
A `` Ptr `` is said to *own* a pointer - that is, for each `` Ptr `` there is a pointer that will be delete d
once all `` Ptr `` instances that own it are destroyed. The owned pointer may be null, in which case nothing is deleted.
Each `` Ptr `` also *stores* a pointer. The stored pointer is the pointer the `` Ptr `` pretends to be;
that is, the one you get when you use :ocv:func: `Ptr::get` or the conversion to `` T* `` . It's usually
the same as the owned pointer, but if you use casts or the general shared-ownership constructor, the two may diverge:
the `` Ptr `` will still own the original pointer, but will itself point to something else.
The owned pointer is treated as a black box. The only thing `` Ptr `` needs to know about it is how to
delete it. This knowledge is encapsulated in the *deleter* - an auxiliary object that is associated
with the owned pointer and shared between all `` Ptr `` instances that own it. The default deleter is
an instance of `` DefaultDeleter `` , which uses the standard C++ `` delete `` operator; as such it
will work with any pointer allocated with the standard `` new `` operator .
However, if the pointer must be deleted in a different way, you must specify a custom deleter upon
`` Ptr `` construction. A deleter is simply a callable object that accepts the pointer as its sole argument.
For example, if you want to wrap `` FILE `` , you may do so as follows: :
Ptr<FILE> f(fopen("myfile.txt", "w"), fclose);
if(!f) throw ...;
fprintf(f, ....);
...
// the file will be closed automatically by the Ptr<FILE> destructor.
// the file will be closed automatically by f's destructor.
Alternatively, if you want all pointers of a particular type to be deleted the same way,
you can specialize `` DefaultDeleter<T>::operator() `` for that type, like this::
.. 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.
namespace cv {
template<> void DefaultDeleter<FILE>::operator ()(FILE * obj) const
{
fclose(obj);
}
}
Ptr::Ptr
--------
Various Ptr constructors.
For convenience, the following types from the OpenCV C API already have such a specialization
that calls the appropriate release function:
* `` CvCapture ``
* :ocv:struct: `CvDTreeSplit`
* :ocv:struct: `CvFileStorage`
* `` CvHaarClassifierCascade ``
* :ocv:struct: `CvMat`
* :ocv:struct: `CvMatND`
* :ocv:struct: `CvMemStorage`
* :ocv:struct: `CvSparseMat`
* `` CvVideoWriter ``
* :ocv:struct: `IplImage`
.. note :: The shared ownership mechanism is implemented with reference counting. As such,
cyclic ownership (e.g. when object `` a `` contains a `` Ptr `` to object `` b `` , which
contains a `` Ptr `` to object `` a `` ) will lead to all involved objects never being
cleaned up. Avoid such situations.
.. note :: It is safe to concurrently read (but not write) a `` Ptr `` instance from multiple threads
and therefore it is normally safe to use it in multi-threaded applications.
The same is true for :ocv:class: `Mat` and other C++ OpenCV classes that use internal
reference counts.
Ptr::Ptr (null)
------------------
.. ocv:function :: Ptr::Ptr()
.. ocv:function :: Ptr::Ptr(_Tp* _obj)
.. ocv:function :: Ptr::Ptr(const Ptr& ptr)
:param _obj: Object for copy.
:param ptr: Object for copy.
The default constructor creates a null `` Ptr `` - one that owns and stores a null pointer.
Ptr::Ptr (assuming ownership)
-----------------------------
.. ocv:function :: template<typename Y> Ptr::Ptr(Y* p)
.. ocv:function :: template<typename Y, typename D> Ptr::Ptr(Y* p, D d)
:param d: Deleter to use for the owned pointer.
:param p: Pointer to own.
If `` p `` is null, these are equivalent to the default constructor.
Otherwise, these constructors assume ownership of `` p `` - that is, the created `` Ptr `` owns
and stores `` p `` and assumes it is the sole owner of it. Don't use them if `` p `` is already
owned by another `` Ptr `` , or else `` p `` will get deleted twice.
With the first constructor, `` DefaultDeleter<Y>() `` becomes the associated deleter (so `` p ``
will eventually be deleted with the standard `` delete `` operator). `` Y `` must be a complete
type at the point of invocation.
With the second constructor, `` d `` becomes the associated deleter.
`` Y* `` must be convertible to `` T* `` .
.. note :: It is often easier to use :ocv:func: `makePtr` instead.
Ptr::Ptr (sharing ownership)
----------------------------
.. ocv:function :: Ptr::Ptr(const Ptr& o)
.. ocv:function :: template<typename Y> Ptr::Ptr(const Ptr<Y>& o)
.. ocv:function :: template<typename Y> Ptr::Ptr(const Ptr<Y>& o, T* p)
:param o: ``Ptr`` to share ownership with.
:param p: Pointer to store.
These constructors create a `` Ptr `` that shares ownership with another `` Ptr `` - that is,
own the same pointer as `` o `` .
With the first two, the same pointer is stored, as well; for the second, `` Y* `` must be convertible to `` T* `` .
With the third, `` p `` is stored, and `` Y `` may be any type. This constructor allows to have completely
unrelated owned and stored pointers, and should be used with care to avoid confusion. A relatively
benign use is to create a non-owning `` Ptr `` , like this::
ptr = Ptr<T>(Ptr<T>(), dont_delete_me); // owns nothing; will not delete the pointer.
Ptr::~Ptr
---------
The Ptr destructor.
.. ocv:function :: Ptr::~Ptr()
The destructor is equivalent to calling :ocv:func: `Ptr::release` .
Ptr::operator =
----------------
Assignment operator.
.. ocv:function :: Ptr& Ptr::operator = (const Ptr& ptr)
.. ocv:function :: Ptr& Ptr::operator = (const Ptr& o)
.. ocv:function :: template<typename Y> Ptr& Ptr::operator = (const Ptr<Y>& o)
:param ptr: Object for assignment.
:param o: ``Ptr`` to share ownership with .
Decrements own reference counter (with `` release() `` ) and increments ptr's reference counter.
Ptr::addref
-----------
Increments reference counter.
Assignment replaces the current `` Ptr `` instance with one that owns and stores same
pointers as `` o `` and then destroys the old instance.
.. 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.
If no other `` Ptr `` instance owns the owned pointer, deletes it with the associated deleter.
Then sets both the owned and the stored pointers to `` NULL `` .
Ptr::reset
----------
.. ocv:function :: template<typename Y> void Ptr::reset(Y* p)
.. ocv:function :: template<typename Y, typename D> void Ptr::reset(Y* p, D d)
:param d: Deleter to use for the owned pointer.
:param p: Pointer to own.
`` ptr.reset(...) `` is equivalent to `` ptr = Ptr<T>(...) `` .
Ptr::swap
---------
.. ocv:function :: void Ptr::swap(Ptr& o)
:param o: ``Ptr`` to swap with.
Swaps the owned and stored pointers (and deleters, if any) of this and `` o `` .
Ptr::get
--------
.. ocv:function :: T* Ptr::get() const
.. ocv:function :: void Ptr::delete_obj()
Returns the stored pointer.
Ptr pointer emulation
---------------------
.. ocv:function :: T& Ptr::operator * () const
.. ocv:function :: T* Ptr::operator -> () const
.. ocv:function :: Ptr::operator T* () const
These operators are what allows `` Ptr `` to pretend to be a pointer.
If `` ptr `` is a `` Ptr<T> `` , then `` *ptr `` is equivalent to `` *ptr.get() ``
and `` ptr->foo `` is equivalent to `` ptr.get()->foo `` . In addition, `` ptr ``
is implicitly convertible to `` T* `` , and such conversion is equivalent to
`` ptr.get() `` . As a corollary, `` if (ptr) `` is equivalent to `` if (ptr.get()) `` .
In other words, a `` Ptr `` behaves as if it was its own stored pointer.
Ptr::empty
----------
Returns true if obj == 0;
bool empty() const;
.. ocv:function :: Ptr:: empty() const
Ptr::operator ->
----------------
Provide access to the object fields and methods.
`` ptr.empty() `` is equivalent to `` !ptr.get() `` .
.. ocv:function :: template<typename _Tp> _Tp* Ptr::operator -> ()
.. ocv:function :: template<typename _Tp> const _Tp* Ptr::operator -> () const
Ptr casts
---------
.. ocv:function :: template<typename Y> Ptr<Y> Ptr::staticCast() const
.. ocv:function :: template<typename Y> Ptr<Y> Ptr::constCast() const
.. ocv:function :: template<typename Y> Ptr<Y> Ptr::dynamicCast() const
Ptr::operator _Tp*
------------------
Returns the underlying object pointer. Thanks to the methods, the `` Ptr<_Tp> `` can be used instead
of `` _Tp* `` .
If `` ptr `` is a `` Ptr `` , then `` ptr.fooCast<Y>() `` is equivalent to
`` Ptr<Y>(ptr, foo_cast<Y>(ptr.get())) `` . That is, these functions create
a new `` Ptr `` with the same owned pointer and a cast stored pointer.
Ptr global swap
---------------
.. ocv:function :: template<typename T> void swap(Ptr<T>& ptr1, Ptr<T>& ptr2)
Equivalent to `` ptr1.swap(ptr2) `` . Provided to help write generic algorithms.
Ptr comparisons
---------------
.. ocv:function :: template<typename T> bool operator == (const Ptr<T>& ptr1, const Ptr<T>& ptr2)
.. ocv:function :: template<typename T> bool operator != (const Ptr<T>& ptr1, const Ptr<T>& ptr2)
Return whether `` ptr1.get() `` and `` ptr2.get() `` are equal and not equal, respectively.
makePtr
-------
.. ocv:function :: template<typename T> Ptr<T> makePtr()
.. ocv:function :: template<typename T, typename A1> Ptr<T> makePtr(const A1& a1)
.. ocv:function :: template<typename T, typename A1, typename A2> Ptr<T> makePtr(const A1& a1, const A2& a2)
.. ocv:function :: template<typename T, typename A1, typename A2, typename A3> Ptr<T> makePtr(const A1& a1, const A2& a2, const A3& a3)
(and so on...)
.. ocv:function :: template<typename _Tp> Ptr::operator _Tp* ()
.. ocv:function :: template<typename _Tp> Ptr::operator const _Tp*() const
`` makePtr<T>(...) `` is equivalent to `` Ptr<T>(new T(...)) `` . It is shorter than the latter, and
it's marginally safer than using a constructor or :ocv:func: `Ptr::reset` , since it ensures that
the owned pointer is new and thus not owned by any other `` Ptr `` instance.
Unfortunately, perfect forwarding is impossible to implement in C++03, and so `` makePtr `` is limited
to constructors of `` T `` that have up to 10 arguments, none of which are non-const references.
Mat
---
@ -2967,7 +3108,7 @@ Creates algorithm instance by name
:param name: The algorithm name, one of the names returned by ``Algorithm::getList()``.
This static method creates a new instance of the specified algorithm. If there is no such algorithm, the method will silently return null pointer (that can be checked by `` Ptr::empty() `` method) . Also, you should specify the particular `` Algorithm `` subclass as `` _Tp `` (or simply `` Algorithm `` if you do not know it at that point). ::
This static method creates a new instance of the specified algorithm. If there is no such algorithm, the method will silently return a null pointer. Also, you should specify the particular `` Algorithm `` subclass as `` _Tp `` (or simply `` Algorithm `` if you do not know it at that point). ::
Ptr<BackgroundSubtractor> bgfg = Algorithm::create<BackgroundSubtractor>("BackgroundSubtractor.MOG2");
Roman Donchenko
11 years ago