Pylon::CGrabResultPtr#

Module: Instant Camera

A smart pointer holding a reference to grab result data. More…

#include <pylon/GrabResultPtr.h>

Public Functions#

Friends#

Detailed Description#

class Pylon::CGrabResultPtr;

A smart pointer holding a reference to grab result data.

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 returned reference to IImage is only valid as long the CGrabResultPtr object it came from is not destroyed.

Thread Safety: Instances of CGrabResultPtr referencing the same grab result can be used from any thread context.

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. 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.

Public Functions Documentation#

function CGrabResultPtr#

CGrabResultPtr()

Creates a smart pointer.

Postcondition: No grab result is referenced.

function CGrabResultPtr#

CGrabResultPtr(
    const CGrabResultPtr & rhs
)

Creates a copy of a smart pointer.

Parameters:

• rhs Another smart pointer, source of the result data to reference.

Postcondition:

• Another reference to the grab result of the source is held if it references a grab result.
• No grab result is referenced if the source does not reference a grab result.

Error Safety:

Still valid after error.

The data itself is not copied.

function operator=#

CGrabResultPtr & operator=(
    const CGrabResultPtr & rhs
)

Assignment of a smart pointer.

Parameters:

• rhs Another smart pointer, source of the result data to reference.

Postcondition:

• The currently referenced data is released.
• Another reference to the grab result of the source is held if it references a grab result.
• No grab result is referenced if the source does not reference a grab result.

Error Safety:

Still valid after error.

The data itself is not copied.

function ~CGrabResultPtr#

~CGrabResultPtr()

Destroys the smart pointer.

Postcondition: The currently referenced data is released.

Error Safety:

Does not throw C++ exceptions.

function operator->#

CGrabResultData * operator->() const

Allows accessing the referenced data.

Return: The pointer to the grab result data.

Precondition: The pointer must reference a grab result. IsValid() or the overloaded bool operator can be used to check whether data is referenced.

Error Safety:

Still valid after error. Throws an exception when no data is referenced.

function IsValid#

bool IsValid() const

Check whether data is referenced.

Return: True if data is referenced.

Error Safety:

Does not throw C++ exceptions.

function operator bool#

operator bool() const

Check whether data is referenced.

Return: IsValid().

Error Safety:

Does not throw C++ exceptions.

The overloaded bool operator can be used to check whether data is referenced. Example:

if ( grabResult)
{
    grabResult->GetStatus();
}

function Release#

void Release()

The currently referenced data is released.

Postcondition: The currently referenced data is released.

Error Safety:

Still valid after error.

function operator IImage &#

operator IImage &() const

Provides an IImage interface to the grab result.

Attention: The returned reference is only valid as long the grab result ptr is not destroyed.

Error Safety:

Still valid after error.

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().

function IsUnique#

bool IsUnique() const

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 Safety:

Does not throw C++ exceptions.

Friends#

friend PylonPrivate::CGrabResultDataConverter#

friend class PylonPrivate::CGrabResultDataConverter;

Internal use only.