Represents a GenTL buffer module. More...

#include <peak/buffer/peak_buffer.hpp>

Inheritance diagram for peak::core::Buffer:

Public Member Functions
	Buffer ()=delete
	~Buffer () override=default
	Buffer (const Buffer &other)=delete
Buffer &	operator= (const Buffer &other)=delete
	Buffer (Buffer &&other)=delete
Buffer &	operator= (Buffer &&other)=delete
PEAK_COMMON_NO_DISCARD ImageView	ToImageView ()
	Create an ImageView from this buffer.
PEAK_COMMON_NO_DISCARD ImageView	ToImageView (MetadataExtractionMode mode)
	Create an ImageView from this buffer with a specific metadata extraction mode.
PEAK_COMMON_NO_DISCARD std::vector< std::shared_ptr< BufferChunk > >	Chunks ()
	Returns the buffer's chunks if it contains chunks.
PEAK_COMMON_NO_DISCARD std::vector< std::shared_ptr< BufferPart > >	Parts ()
	Returns all buffer parts for multipart buffers.
PEAK_COMMON_NO_DISCARD std::shared_ptr< DataStream >	ParentDataStream () const
	Returns the parent data stream.
Info Commands
Information based on GenTL BUFFER_INFO_CMD.
PEAK_COMMON_NO_DISCARD RawInformation	Info (int32_t infoCommand) const
	Delivers information based on the given GenTL info command.
PEAK_COMMON_NO_DISCARD std::string	TLType () const
	Returns the TL (transport layer) type.
PEAK_COMMON_NO_DISCARD void *	BasePtr () const
	Returns the base pointer.
PEAK_COMMON_NO_DISCARD size_t	Size () const
	Returns the size of the buffer in bytes.
PEAK_COMMON_NO_DISCARD void *	UserPtr () const
	Returns the pointer to custom user data attached to the buffer.
PEAK_COMMON_NO_DISCARD BufferPayloadType	PayloadType () const
	Returns the payload type.
PEAK_COMMON_NO_DISCARD uint64_t	PixelFormat () const
	Returns the pixel format of the data.
PEAK_COMMON_NO_DISCARD peak::common::PixelFormatInfo	PixelFormatInfo () const
	Returns the pixel format info of the data.
PEAK_COMMON_NO_DISCARD peak::core::PixelFormatNamespace	PixelFormatNamespace () const
	Returns the pixel format namespace, to allow interpretation of the PixelFormat().
PEAK_COMMON_NO_DISCARD Endianness	PixelEndianness () const
	Returns the pixel endianness.
PEAK_COMMON_NO_DISCARD size_t	ExpectedDataSize () const
	Returns the expected data size.
PEAK_COMMON_NO_DISCARD size_t	DeliveredDataSize () const
	Returns the delivered data size.
PEAK_COMMON_NO_DISCARD uint64_t	FrameID () const
	Returns the identifier of the current frame.
PEAK_COMMON_NO_DISCARD size_t	ImageOffset () const
	Returns the offset of the image data from the beginning of the delivered buffer in bytes.
PEAK_COMMON_NO_DISCARD size_t	DeliveredImageHeight () const
	Returns the delivered image height.
PEAK_COMMON_NO_DISCARD size_t	DeliveredChunkPayloadSize () const
	Returns the delivered chunk payload size.
PEAK_COMMON_NO_DISCARD uint64_t	ChunkLayoutID () const
	Returns the chunk layout ID.
PEAK_COMMON_NO_DISCARD std::string	FileName () const
	Retrieves the file name.
PEAK_COMMON_NO_DISCARD size_t	Width () const
	Returns the width.
PEAK_COMMON_NO_DISCARD size_t	Height () const
	Returns the height.
PEAK_COMMON_NO_DISCARD peak::common::Size	ImageSize () const
	Returns the size of the image.
PEAK_COMMON_NO_DISCARD size_t	XOffset () const
	Returns the x offset of the data in the buffer in number of pixels from the image origin to handle areas of interest.
PEAK_COMMON_NO_DISCARD size_t	YOffset () const
	Returns the y offset of the data in the buffer in number of lines from the image origin to handle areas of interest.
PEAK_COMMON_NO_DISCARD size_t	XPadding () const
	Returns the x padding of the data in the buffer in number of bytes.
PEAK_COMMON_NO_DISCARD size_t	YPadding () const
	Returns the y padding of the data in the buffer in number of bytes.
PEAK_COMMON_NO_DISCARD uint64_t	Timestamp_ticks () const
	Returns the timestamp.
PEAK_COMMON_NO_DISCARD uint64_t	Timestamp_ns () const
	Returns the timestamp associated with when the image was recorded.
PEAK_COMMON_NO_DISCARD bool	IsQueued () const
	Checks whether the buffer is queued or not.
PEAK_COMMON_NO_DISCARD bool	IsAcquiring () const
	Checks whether the buffer is currently being filled.
PEAK_COMMON_NO_DISCARD bool	IsIncomplete () const
	Checks whether the buffer is incomplete or not.
PEAK_COMMON_NO_DISCARD bool	HasNewData () const
	Checks whether the buffer has new data since the last delivery.
PEAK_COMMON_NO_DISCARD bool	HasImage () const
	Checks whether the buffer contains image data.
PEAK_COMMON_NO_DISCARD bool	HasChunks () const
	Checks whether the buffer contains chunks.
PEAK_COMMON_NO_DISCARD bool	HasParts () const
	Checks whether the buffer contains parts.
PEAK_COMMON_NO_DISCARD uint64_t	SystemTimestamp_ns () const
	Returns the system timestamp corresponding to this buffer.
Public Member Functions inherited from peak::core::EventSupportingModule
	EventSupportingModule ()=default
	~EventSupportingModule () override=default
	EventSupportingModule (const EventSupportingModule &other)=delete
EventSupportingModule &	operator= (const EventSupportingModule &other)=delete
	EventSupportingModule (EventSupportingModule &&other)=delete
EventSupportingModule &	operator= (EventSupportingModule &&other)=delete
PEAK_COMMON_NO_DISCARD std::unique_ptr< EventController >	EnableEvents (EventType type)
	Enables events of the given event type.
Public Member Functions inherited from peak::core::Module
	Module ()=default
virtual	~Module ()=default
	Module (const Module &other)=delete
Module &	operator= (const Module &other)=delete
	Module (Module &&other)=delete
Module &	operator= (Module &&other)=delete
PEAK_COMMON_NO_DISCARD std::vector< std::shared_ptr< NodeMap > >	NodeMaps () const
	Returns the module's node maps.
PEAK_COMMON_NO_DISCARD std::shared_ptr< class Port >	Port () const
	Returns the module's port.

Friends
class	DataStream

Detailed Description

Represents a GenTL buffer module.

This class allows to query information about a GenTL buffer module and to enumerate its chunks or parts.

Constructor & Destructor Documentation

◆ Buffer() [1/3]

peak::core::Buffer::Buffer ( )

delete

◆ ~Buffer()

peak::core::Buffer::~Buffer ( )

overridedefault

◆ Buffer() [2/3]

peak::core::Buffer::Buffer ( const Buffer & other )

delete

◆ Buffer() [3/3]

peak::core::Buffer::Buffer ( Buffer && other )

delete

Member Function Documentation

◆ BasePtr()

void * peak::core::Buffer::BasePtr ( ) const

inline

Returns the base pointer.

Returns: Base pointer

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ChunkLayoutID()

uint64_t peak::core::Buffer::ChunkLayoutID ( ) const

inline

Returns the chunk layout ID.

Returns: Chunk layout ID

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Chunks()

std::vector< std::shared_ptr< BufferChunk > > peak::core::Buffer::Chunks ( )

inline

Returns the buffer's chunks if it contains chunks.

Check if the buffer has chunks with HasChunks().

Returns: Buffer chunks

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ DeliveredChunkPayloadSize()

size_t peak::core::Buffer::DeliveredChunkPayloadSize ( ) const

inline

Returns the delivered chunk payload size.

Returns: Delivered chunk payload size

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ DeliveredDataSize()

size_t peak::core::Buffer::DeliveredDataSize ( ) const

inline

Returns the delivered data size.

Returns: Delivered data size

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ DeliveredImageHeight()

size_t peak::core::Buffer::DeliveredImageHeight ( ) const

inline

Returns the delivered image height.

Returns: Delivered image height

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ExpectedDataSize()

size_t peak::core::Buffer::ExpectedDataSize ( ) const

inline

Returns the expected data size.

Returns: Expected data size

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ FileName()

std::string peak::core::Buffer::FileName ( ) const

inline

Retrieves the file name.

Returns the file name if the payload contains a file. For example, in GigE Vision, this corresponds to information provided in the image stream data leader. Implementations for other technologies should provide similar functionality as appropriate.

As this is based on GigE Vision, the file name is UTF-8 encoded, consistent with the GigE Vision specification.

Returns: A UTF-8 encoded file name as a string.

Since: 1.0

Exceptions

InternalErrorException If an internal error occurs.

◆ FrameID()

uint64_t peak::core::Buffer::FrameID ( ) const

inline

Returns the identifier of the current frame.

The frame ID is a sequentially incremented value that increases by one from one frame to the next. It serves as a means to detect missing or out-of-order frames in a stream. Once the maximum value supported by the device and transport layer is reached, the frame ID wraps back to zero. The exact wrap-around point is not fixed and depends on both the device and the transport layer in use.

Returns: A 64-bit unsigned integer representing the frame ID.

Since: 1.0

Exceptions

InternalErrorException If an internal error occurs.

◆ HasChunks()

bool peak::core::Buffer::HasChunks ( ) const

inline

Checks whether the buffer contains chunks.

If HasChunks() is true, check the BufferChunks using Chunks().

Returns: True, if the buffer has chunks.; False otherwise.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ HasImage()

bool peak::core::Buffer::HasImage ( ) const

inline

Checks whether the buffer contains image data.

Returns: True, if the buffer contains an image.; False otherwise.

See GenTL BUFFER_INFO_IMAGEPRESENT.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ HasNewData()

bool peak::core::Buffer::HasNewData ( ) const

inline

Checks whether the buffer has new data since the last delivery.

Returns: True when the buffer has new data since the last delivery.; False otherwise.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ HasParts()

bool peak::core::Buffer::HasParts ( ) const

inline

Checks whether the buffer contains parts.

If HasParts() is true, check the BufferParts using Parts().

Returns: True, if the buffer has parts.; False otherwise.

Since: 1.8

Exceptions

InternalErrorException An internal error has occurred.

◆ Height()

size_t peak::core::Buffer::Height ( ) const

inline

Returns the height.

Returns: Height

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ImageOffset()

size_t peak::core::Buffer::ImageOffset ( ) const

inline

Returns the offset of the image data from the beginning of the delivered buffer in bytes.

Returns: Image offset in bytes

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ImageSize()

peak::common::Size peak::core::Buffer::ImageSize ( ) const

inline

Returns the size of the image.

Returns: peak::common::Size

Since: 1.17

Exceptions

InternalErrorException An internal error has occurred.

◆ Info()

RawInformation peak::core::Buffer::Info ( int32_t infoCommand ) const

inline

Delivers information based on the given GenTL info command.

Parameters

[in] infoCommand The GenTL info command.

This function can be used to query information going beyond the predefined info functions, based on the GenTL info commands of the corresponding module.

Example (error handling is omitted):

#include <peak/thirdparty/GenTL.h>
auto info = object->Info(GenTL::XX_INFO_XX);
 
// Cast depending on the delivered data type
if (info.dataType == GenTL::INFO_DATATYPE_UINT64)
{
    uint64_t uint64Var = *reinterpret_cast<const uint64_t*>(info.data.data());
    // Do something with the information
}
else if (infoDataTypeVar == GenTL::INFO_DATATYPE_INT64)
{
    ...
}
...

Returns: Raw information according to the passed info command

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ IsAcquiring()

bool peak::core::Buffer::IsAcquiring ( ) const

inline

Checks whether the buffer is currently being filled.

Returns: True, while the buffer is being filled.; False otherwise.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ IsIncomplete()

bool peak::core::Buffer::IsIncomplete ( ) const

inline

Checks whether the buffer is incomplete or not.

Incomplete buffers can happen when an error occurred while the buffer was being filled.

Returns: True if the buffer couldn't be filled completely.; False if the buffer is complete.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ IsQueued()

bool peak::core::Buffer::IsQueued ( ) const

inline

Checks whether the buffer is queued or not.

Returns: True, while the buffer is in the input pool, is currently being filled or is in the output buffer queue.; False otherwise.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ operator=() [1/2]

Buffer & peak::core::Buffer::operator= ( Buffer && other )

delete

◆ operator=() [2/2]

Buffer & peak::core::Buffer::operator= ( const Buffer & other )

delete

◆ ParentDataStream()

std::shared_ptr< DataStream > peak::core::Buffer::ParentDataStream ( ) const

inline

Returns the parent data stream.

Returns: Parent data stream

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Parts()

std::vector< std::shared_ptr< BufferPart > > peak::core::Buffer::Parts ( )

inline

Returns all buffer parts for multipart buffers.

Returns: Buffer parts

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ PayloadType()

BufferPayloadType peak::core::Buffer::PayloadType ( ) const

inline

Returns the payload type.

Returns: Payload type

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ PixelEndianness()

Endianness peak::core::Buffer::PixelEndianness ( ) const

inline

Returns the pixel endianness.

Returns: Pixel endianness

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ PixelFormat()

uint64_t peak::core::Buffer::PixelFormat ( ) const

inline

Returns the pixel format of the data.

The interpretation of the pixel format depends on the namespace the pixel format belongs to. This can be inquired using PixelFormatNamespace().

Returns: Pixel format

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ PixelFormatInfo()

peak::common::PixelFormatInfo peak::core::Buffer::PixelFormatInfo ( ) const

inline

Returns the pixel format info of the data.

The interpretation of the pixel format depends on the namespace the pixel format belongs to. This can be inquired using PixelFormatNamespace().

Returns: Pixel format info

Since: 1.17

Exceptions

InternalErrorException An internal error has occurred.

◆ PixelFormatNamespace()

peak::core::PixelFormatNamespace peak::core::Buffer::PixelFormatNamespace ( ) const

inline

Returns the pixel format namespace, to allow interpretation of the PixelFormat().

Returns: Pixel format namespace

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Size()

size_t peak::core::Buffer::Size ( ) const

inline

Returns the size of the buffer in bytes.

Returns: Buffer size in bytes

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ SystemTimestamp_ns()

uint64_t peak::core::Buffer::SystemTimestamp_ns ( ) const

inline

Returns the system timestamp corresponding to this buffer.

Provides the system timestamp, expressed as nanoseconds since the Unix epoch (00:00:00 UTC on January 1, 1970), corresponding to the device timestamp of this buffer. This allows buffers to be associated with a system time, for example for logging or correlation with other system events.

The effective accuracy of the system timestamp is subject to various platform- and environment-specific influences, such as system and device clock resolution, operating system scheduling behavior, system load, and network characteristics (e.g. size and traffic load). As such, a deterministic timestamp precision cannot be specified.

Internal measurements under representative conditions indicate that the timestamp deviation is most commonly on the order of 1–2 ms and typically remains below 10 ms, even under high network load.

Note: For high-precision or time-synchronization use cases, it is recommended to use the device timestamp instead of the system timestamp. In particular, devices supporting IEEE 1588 Precision Time Protocol (PTP) can provide significantly higher timestamp accuracy and synchronization across multiple systems.; Support for this function may depend on the transport layer. If unavailable, an exception may be thrown.

Returns: System timestamp in nanoseconds since the Unix epoch.

Since: 1.15

Exceptions

InternalErrorException if an internal error occurs.

◆ Timestamp_ns()

uint64_t peak::core::Buffer::Timestamp_ns ( ) const

inline

Returns the timestamp associated with when the image was recorded.

The timestamp is expressed in nanoseconds and is relative to a reference point (t = 0) defined by the transport layer and the device. This reference point is not known to the caller. The timestamp does not represent an absolute wall-clock time, but instead the elapsed time since that reference. The difference between timestamps of consecutive images indicates the time interval between their recordings.

Depending on the transport layer, timestamp information might not be provided.

Returns: Timestamp in nanoseconds, relative to an unknown reference point.

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Timestamp_ticks()

uint64_t peak::core::Buffer::Timestamp_ticks ( ) const

inline

Returns the timestamp.

Returns: Timestamp in ticks

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ TLType()

std::string peak::core::Buffer::TLType ( ) const

inline

Returns the TL (transport layer) type.

Returns: TL type

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ ToImageView() [1/2]

ImageView peak::core::Buffer::ToImageView ( )

inline

Create an ImageView from this buffer.

Uses the default metadata extraction mode MetadataExtractionMode::Minimal.

Returns: ImageView implementing peak::common::IImageView.

Note: The Buffer must remain valid and must not be queued for the lifetime of the ImageView.

Since: 1.12

◆ ToImageView() [2/2]

ImageView peak::core::Buffer::ToImageView ( MetadataExtractionMode mode )

inline

Create an ImageView from this buffer with a specific metadata extraction mode.

Parameters

mode	Metadata extraction mode (see MetadataExtractionMode).

Returns: ImageView implementing peak::common::IImageView.

Note: The Buffer must remain valid and must not be queued for the lifetime of the ImageView.

Since: 1.15

◆ UserPtr()

void * peak::core::Buffer::UserPtr ( ) const

inline

Returns the pointer to custom user data attached to the buffer.

Pointer to user data provided at buffer announcement using DataStream::AnnounceBuffer() / DataStream::AllocAndAnnounceBuffer(). This pointer can be used to identify or to attach custom user data to the buffer.

Returns: User pointer

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ Width()

size_t peak::core::Buffer::Width ( ) const

inline

Returns the width.

Returns: Width

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ XOffset()

size_t peak::core::Buffer::XOffset ( ) const

inline

Returns the x offset of the data in the buffer in number of pixels from the image origin to handle areas of interest.

Returns: X offset in number of pixels

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ XPadding()

size_t peak::core::Buffer::XPadding ( ) const

inline

Returns the x padding of the data in the buffer in number of bytes.

Returns: X padding in bytes

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ YOffset()

size_t peak::core::Buffer::YOffset ( ) const

inline

Returns the y offset of the data in the buffer in number of lines from the image origin to handle areas of interest.

Returns: Y offset in number of lines

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ YPadding()

size_t peak::core::Buffer::YPadding ( ) const

inline

Returns the y padding of the data in the buffer in number of bytes.

Returns: Y padding in bytes

Since: 1.0

Exceptions

InternalErrorException An internal error has occurred.

◆ DataStream

friend class DataStream

friend

The documentation for this class was generated from the following file:

peak/buffer/peak_buffer.hpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Buffer() [1/3]

◆ ~Buffer()

◆ Buffer() [2/3]

◆ Buffer() [3/3]

Member Function Documentation

◆ BasePtr()

◆ ChunkLayoutID()

◆ Chunks()

◆ DeliveredChunkPayloadSize()

◆ DeliveredDataSize()

◆ DeliveredImageHeight()

◆ ExpectedDataSize()

◆ FileName()

◆ FrameID()

◆ HasChunks()

◆ HasImage()

◆ HasNewData()

◆ HasParts()

◆ Height()

◆ ImageOffset()

◆ ImageSize()

◆ Info()

◆ IsAcquiring()

◆ IsIncomplete()

◆ IsQueued()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ParentDataStream()

◆ Parts()

◆ PayloadType()

◆ PixelEndianness()

◆ PixelFormat()

◆ PixelFormatInfo()

◆ PixelFormatNamespace()

◆ Size()

◆ SystemTimestamp_ns()

◆ Timestamp_ns()

◆ Timestamp_ticks()

◆ TLType()

◆ ToImageView() [1/2]

◆ ToImageView() [2/2]

◆ UserPtr()

◆ Width()

◆ XOffset()

◆ XPadding()

◆ YOffset()

◆ YPadding()

Friends And Related Symbol Documentation

◆ DataStream