217 lines
6.0 KiB
C++
217 lines
6.0 KiB
C++
//-----------------------------------------------------------------------------
|
|
// Basler pylon SDK
|
|
// Copyright (c) 2010-2023 Basler AG
|
|
// http://www.baslerweb.com
|
|
// Author: Andreas Gau
|
|
//-----------------------------------------------------------------------------
|
|
/*!
|
|
\file
|
|
\brief Contains a smart pointer that holds a reference to grab result data.
|
|
*/
|
|
|
|
#ifndef INCLUDED_GRABRESULTPTR_H_4356898
|
|
#define INCLUDED_GRABRESULTPTR_H_4356898
|
|
|
|
#include <pylon/Platform.h>
|
|
|
|
#ifdef _MSC_VER
|
|
# pragma pack(push, PYLON_PACKING)
|
|
#endif /* _MSC_VER */
|
|
|
|
#include <pylon/PylonBase.h>
|
|
#include <pylon/GrabResultData.h>
|
|
#include <pylon/Image.h>
|
|
|
|
namespace Pylon
|
|
{
|
|
namespace PylonPrivate
|
|
{
|
|
class CGrabResultDataConverter;
|
|
}
|
|
|
|
/** \addtogroup Pylon_InstantCameraApiGeneric
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
\class CGrabResultPtr
|
|
\brief A smart pointer holding a reference to grab result data.
|
|
|
|
This class is used for distributing the grab result data of a camera. It controls
|
|
the reuse and lifetime of the referenced buffer. When all smart pointers referencing
|
|
a buffer go out of scope the referenced buffer is reused or destroyed.
|
|
The data and the held buffer are still valid after the camera object it originated from
|
|
has been destroyed.
|
|
\attention The grabbing will stop with an input queue underrun, when the grab results are
|
|
never released, e.g. when put into a container.
|
|
|
|
The CGrabResultPtr class provides a cast operator that allows passing the grab result directly to functions or methods
|
|
that take an const IImage& as parameter, e.g. image saving functions or image format converter methods.
|
|
|
|
\attention The returned reference to IImage is only valid as long the CGrabResultPtr object it came from is not destroyed.
|
|
|
|
\threading Instances of CGrabResultPtr referencing the same grab result can be used from any thread context.
|
|
*/
|
|
class PYLONBASE_API CGrabResultPtr
|
|
{
|
|
public:
|
|
/*!
|
|
\brief Creates a smart pointer.
|
|
\post No grab result is referenced.
|
|
*/
|
|
CGrabResultPtr();
|
|
|
|
|
|
/*!
|
|
\brief Creates a copy of a smart pointer.
|
|
|
|
\param[in] rhs Another smart pointer, source of the result data to reference.
|
|
|
|
The data itself is not copied.
|
|
|
|
\post
|
|
<ul>
|
|
<li>Another reference to the grab result of the source is held if it references a grab result.
|
|
<li>No grab result is referenced if the source does not reference a grab result.
|
|
</ul>
|
|
|
|
\error
|
|
Still valid after error.
|
|
*/
|
|
CGrabResultPtr( const CGrabResultPtr& rhs );
|
|
|
|
|
|
/*!
|
|
\brief Assignment of a smart pointer.
|
|
|
|
\param[in] rhs Another smart pointer, source of the result data to reference.
|
|
|
|
The data itself is not copied.
|
|
|
|
\post
|
|
<ul>
|
|
<li>The currently referenced data is released.
|
|
<li>Another reference to the grab result of the source is held if it references a grab result.
|
|
<li>No grab result is referenced if the source does not reference a grab result.
|
|
</ul>
|
|
|
|
\error
|
|
Still valid after error.
|
|
*/
|
|
CGrabResultPtr& operator = ( const CGrabResultPtr& rhs );
|
|
|
|
|
|
/*!
|
|
\brief Destroys the smart pointer.
|
|
|
|
\post The currently referenced data is released.
|
|
|
|
\error
|
|
Does not throw C++ exceptions.
|
|
*/
|
|
~CGrabResultPtr();
|
|
|
|
|
|
/*!
|
|
\brief Allows accessing the referenced data.
|
|
|
|
\return The pointer to the grab result data.
|
|
|
|
\pre The pointer must reference a grab result.
|
|
IsValid() or the overloaded bool operator can be used to check whether data is referenced.
|
|
|
|
\error
|
|
Still valid after error. Throws an exception when no data is referenced.
|
|
*/
|
|
CGrabResultData* operator->() const;
|
|
|
|
|
|
/*!
|
|
\brief Check whether data is referenced.
|
|
|
|
\return True if data is referenced.
|
|
|
|
\error
|
|
Does not throw C++ exceptions.
|
|
*/
|
|
bool IsValid() const;
|
|
|
|
|
|
/*!
|
|
\brief Check whether data is referenced.
|
|
|
|
\return IsValid().
|
|
|
|
The overloaded bool operator can be used to check whether data is referenced.
|
|
Example:
|
|
\code
|
|
if ( grabResult)
|
|
{
|
|
grabResult->GetStatus();
|
|
}
|
|
\endcode
|
|
|
|
\error
|
|
Does not throw C++ exceptions.
|
|
*/
|
|
operator bool() const;
|
|
|
|
|
|
/*!
|
|
\brief The currently referenced data is released.
|
|
|
|
\post The currently referenced data is released.
|
|
|
|
\error
|
|
Still valid after error.
|
|
*/
|
|
void Release();
|
|
|
|
|
|
/*!
|
|
\brief Provides an IImage interface to the grab result.
|
|
|
|
This cast operator allows passing the grab result to saving functions or image format converter.
|
|
The returned image is invalid if the grab was not successful, see CGrabResultData::GrabSucceeded().
|
|
|
|
\attention The returned reference is only valid as long the grab result ptr is not destroyed.
|
|
|
|
\error
|
|
Still valid after error.
|
|
*/
|
|
operator IImage& () const;
|
|
|
|
|
|
/*!
|
|
\brief Indicates that the held grab result data and buffer is only referenced by this grab result.
|
|
|
|
\return Returns true if the held grab result data and buffer is only referenced by this grab result. Returns false if the grab result is invalid.
|
|
|
|
\error
|
|
Does not throw C++ exceptions.
|
|
*/
|
|
bool IsUnique() const;
|
|
|
|
|
|
/// Internal use only.
|
|
class CGrabResultPtrImpl;
|
|
CGrabResultPtr& operator = ( const CGrabResultPtrImpl& rhs );
|
|
private:
|
|
/// Internal use only.
|
|
friend class PylonPrivate::CGrabResultDataConverter;
|
|
CGrabResultData* GetPtr() const;
|
|
mutable CGrabResultPtrImpl* m_pImpl;
|
|
CGrabResultData* m_pGrabResultData;
|
|
};
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
}
|
|
|
|
#ifdef _MSC_VER
|
|
# pragma pack(pop)
|
|
#endif /* _MSC_VER */
|
|
|
|
#endif /* INCLUDED_GRABRESULTPTR_H_4356898 */
|