Represents a block of GigE Vision or USB3 Vision data in memory. More...
Public Member Functions | |
PvBuffer (PvPayloadType aPayloadType=PvPayloadTypeImage) | |
Constructor. More... | |
virtual | ~PvBuffer () |
Destructor. | |
PvPayloadType | GetPayloadType () const |
Returns the payload type currently used by the buffer. More... | |
PvImage * | GetImage () |
Returns the PvImage interface to the buffer. More... | |
const PvImage * | GetImage () const |
Returns the PvImage interface to the buffer. More... | |
PvRawData * | GetRawData () |
Returns the PvRawData interface to the buffer. More... | |
const PvRawData * | GetRawData () const |
Returns the PvRawData interface to the buffer. More... | |
PvChunkData * | GetChunkData () |
Returns the PvChunkData interface to the buffer. More... | |
const PvChunkData * | GetChunkData () const |
Returns the PvChunkData interface to the buffer. More... | |
IPvMultiPartContainer * | GetMultiPartContainer () |
Returns the PvChunkData interface to the buffer. More... | |
const IPvMultiPartContainer * | GetMultiPartContainer () const |
Returns the PvChunkData interface to the buffer. More... | |
IPvH264AccessUnit * | GetH264AccessUnit () |
Returns the IPvH264AccessUnit interface to the buffer. More... | |
const IPvH264AccessUnit * | GetH264AccessUnit () const |
Returns the IPvH264AccessUnit interface to the buffer. More... | |
const uint8_t * | GetDataPointer () const |
Get the buffer's data pointer. More... | |
uint8_t * | GetDataPointer () |
Get the buffer's data pointer. More... | |
uint64_t | GetID () const |
Get the buffer's ID. More... | |
void | SetID (uint64_t aValue) |
Set the buffer's ID. More... | |
bool | IsExtendedID () const |
Check if the buffer is currently in extended ID mode. More... | |
bool | IsAttached () const |
Returns true if the buffer has been attached (instead of allocated) More... | |
bool | IsAllocated () const |
Returns true if the buffer has been attached (instead of attached) More... | |
uint32_t | GetAcquiredSize () const |
Gets the size in bytes of the block received by the data receiver including, if present, additional chunk data and headers, optional padding. More... | |
uint32_t | GetRequiredSize () const |
Gets the size of buffer required to hold the acquired block including, if present, additional chunk data and headers, padding. More... | |
uint32_t | GetSize () const |
Get the buffer's allocated or attached size (total capacity) in bytes. More... | |
PvResult | Reset (PvPayloadType aPayloadType=PvPayloadTypeImage) |
Reconstruct the object with a new payload type. More... | |
PvResult | Alloc (uint32_t aSize) |
Allocates memory for this PvBuffer. More... | |
PvResult | AllocChunk (uint32_t aSize) |
Alloc a separate space for chunk data in this PvBuffer. More... | |
void | Free () |
Frees (de-allocates) the buffer's internal memory. More... | |
void | FreeChunk () |
Frees (de-allocates) an attached memory buffer of chunk data. More... | |
PvResult | Attach (void *aBuffer, uint32_t aSize) |
Attach this PvBuffer to an external memory buffer. More... | |
uint8_t * | Detach () |
Releases an attached memory buffer. More... | |
uint64_t | GetBlockID () const |
Return the block ID. More... | |
PvResult | GetOperationResult () const |
Returns the value of aOperationResult when this buffer was last received through a PvStream. More... | |
uint64_t | GetTimestamp () const |
Get the buffer's timestamp. More... | |
uint64_t | GetReceptionTime () const |
Get the buffer's reception timestamp. More... | |
uint64_t | GetDuration () const |
Get the buffer's duration. More... | |
PvResult | SetTimestamp (uint64_t aTimestamp) |
Set the timestamp to place in the block leader. More... | |
PvResult | SetDuration (uint64_t aDuration) |
Set the duration of the buffer in the context of a stream. More... | |
PvResult | SetBlockID (uint64_t aBlockID) |
Sets the block ID of a buffer. More... | |
PvResult | SetReceptionTime (uint64_t aReceptionTime) |
Sets the reception time of a buffer. More... | |
uint32_t | GetPacketsRecoveredCount () const |
The number of lost packets successfully recovered by packet resend requests. Duplicate received packets are not counted. More... | |
uint32_t | GetPacketsRecoveredSingleResendCount () const |
The number of lost packets successfully recovered by packet resend requests without any resend request retries. More... | |
uint32_t | GetResendGroupRequestedCount () const |
The number of resend requests issued by the data receiver. More... | |
uint32_t | GetResendPacketRequestedCount () const |
The number of packets the data receiver requests with ResendGroupRequested. More... | |
uint32_t | GetLostPacketCount () const |
Packets that were not successfully delivered when this PvBuffer was filled by the data receiver. More... | |
uint32_t | GetIgnoredPacketCount () const |
Packets received that were ignored when this buffer was filled by the data receiver. More... | |
uint32_t | GetRedundantPacketCount () const |
Number of packets received more than once. More... | |
uint32_t | GetPacketOutOfOrderCount () const |
Number of packets received out of order. More... | |
PvResult | GetMissingPacketIdsCount (uint32_t &aCount) |
Get the number of missing packet groups that represent unpopulated areas of memory in this buffer. More... | |
PvResult | GetMissingPacketIds (uint32_t aIndex, uint32_t &aPacketIdLow, uint32_t &aPacketIdHigh) |
Get a missing packet group that represents an unpopulated area of memory in this buffer. More... | |
void | ResetChunks () |
Resets the internal chunk state. More... | |
PvResult | AddChunk (uint32_t aID, const uint8_t *aData, uint32_t aLength) |
Add chunk data to the buffer. More... | |
void | SetChunkLayoutID (uint32_t aChunkLayoutID) |
Set the chunk data layout ID. More... | |
bool | HasChunks () const |
Returns true if the buffer has data chunks. More... | |
uint32_t | GetChunkCount () |
Returns the number of data chunks in the PvBuffer. More... | |
PvResult | GetChunkIDByIndex (uint32_t aIndex, uint32_t &aID) |
Returns the ID of a chunk based on its index. More... | |
uint32_t | GetChunkSizeByIndex (uint32_t aIndex) |
Returns the size in bytes of the data chunk at zero-based aIndex. More... | |
uint32_t | GetChunkSizeByID (uint32_t aID) |
Returns the size in bytes of the data chunk identified by aID. More... | |
const uint8_t * | GetChunkRawDataByIndex (uint32_t aIndex) |
Returns a const pointer to the data chunk at zero-based aIndex. More... | |
const uint8_t * | GetChunkRawDataByID (uint32_t aID) |
Returns a const pointer to the data chunk with its ID matching aID. More... | |
uint32_t | GetPayloadSize () const |
Returns payload size in bytes, excluding any extra padding. More... | |
uint32_t | GetChunkLayoutID () |
Get the chunk data layout ID. More... | |
uint32_t | GetChunkDataSize () const |
Returns the current chunk data size. More... | |
uint32_t | GetChunkDataCapacity () const |
Returns the current chunk data capacity. More... | |
bool | IsHeaderValid () const |
Returns whether this buffer has valid header (GVSP) information. More... | |
bool | IsTrailerValid () const |
Returns whether this buffer has valid trailer (GVSP) information. More... | |
Friends | |
class | PvPipeline |
class | PvStream |
class | PvBufferConverter |
class | PvBufferConverterRGBFilter |
class | PvDeInterlacer |
class | PvTransmitterGEV |
Represents a block of GigE Vision or USB3 Vision data in memory.
A PvBuffer object is typically used to receive data from a GigE Vision or USB3 Vision transmitter or to transmit data to a GigE Vision receiver. To learn about receiving data from a GigE Vision or USB3 Vision transmitter, see PvStream. To learn about transmitting GigE Vision data to a GigE Vision receiver, see PvTransmitterGEV.
A block of GigE Vision or USB3 Vision data has an associated payload which can be an image, raw data, file, chunk data, extended chunk data or device specific.
In order to access the payload specific data, use methods like PvBuffer::GetImage in order to get a pointer to an interface giving you access to payload specific methods and properties.
The current payload type of a PvBuffer can be determined by using the PvBuffer::GetPayloadType method.
In this section:
To create and configure buffers:
To determine the payload type and access payload type specific data:
To process an image:
PvBuffer::PvBuffer | ( | PvPayloadType | aPayloadType = PvPayloadTypeImage | ) |
Constructor.
[in] | aPayloadType | The block type (default PvPayloadTypeImage). |
|
virtual |
Add chunk data to the buffer.
Add chunk data to the buffer payload section by specifying the ID of the chunk data.
See ResetChunks for more information.
[in] | aID | Chunk data ID for aIndex. |
[in] | aData | Payload data of the chunk data. |
[in] | aLength | Length of the payload data of the chunk, in bytes. Must be a multiple of 4 bytes. |
Implements IPvChunkData.
PvResult PvBuffer::Alloc | ( | uint32_t | aSize | ) |
Allocates memory for this PvBuffer.
[in] | aSize | The size of the buffer, in bytes. |
PvResult PvBuffer::AllocChunk | ( | uint32_t | aSize | ) |
PvResult PvBuffer::Attach | ( | void * | aBuffer, |
uint32_t | aSize | ||
) |
uint8_t * PvBuffer::Detach | ( | ) |
Releases an attached memory buffer.
Does nothing other then resetting the memory buffer pointer to NULL.
void PvBuffer::Free | ( | ) |
Frees (de-allocates) the buffer's internal memory.
void PvBuffer::FreeChunk | ( | ) |
Frees (de-allocates) an attached memory buffer of chunk data.
uint32_t PvBuffer::GetAcquiredSize | ( | ) | const |
Gets the size in bytes of the block received by the data receiver including, if present, additional chunk data and headers, optional padding.
uint64_t PvBuffer::GetBlockID | ( | ) | const |
Return the block ID.
This method returns the block ID. The GigE Vision or USB3 Vision transmitter typically increments the value by 1 for each new image. You can use this value to ensure the blocks are in order and that none are missing. The value is unsigned and wraps around to 1 (skipping 0) when it reaches 65536 (for legacy 16bit Block ID mode) or 2^64 (for 64 bit Extended Block ID mode).
|
virtual |
Returns the number of data chunks in the PvBuffer.
If no data chunks are available, 0 is returned.
Counting chunks requires the chunks to be parsed and resolved which has a performance hit.
If you need to access chunks directly, you need to use this method to enumerate the chunks. If you access the chunks through GenICam, just use HasChunks to see if you need to attach the buffer the GenICam parameter array of the device.
Implements IPvChunkData.
PvChunkData * PvBuffer::GetChunkData | ( | ) |
Returns the PvChunkData interface to the buffer.
If the payload type of the PvBuffer is PvPayloadTypeChunkData, a pointer to the PvChunkData interface of the buffer is returned.
If the payload type of the PvBuffer is NOT PvPayloadTypeChunkData, a NULL pointer is returned.
This PvChunkData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.
const PvChunkData * PvBuffer::GetChunkData | ( | ) | const |
Returns the PvChunkData interface to the buffer.
Const version.
|
virtual |
Returns the current chunk data capacity.
In a transmission context where you create the buffer, memory is allocated for chunks. This method returns how many bytes can still be added as chunk data.
One chunk is always made of 8-bytes of headers plus the chunk data length. You also need to reserve another 8-bytes for the main chunk (typically the image) unless you buffer only contains chunk data.
This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.
Implements IPvChunkData.
|
virtual |
Returns the current chunk data size.
In a transmission context this method returns how many bytes are used for extra chunk data. It includes the chunk headers for all chunk data and if applicable the chunk header for the main chunk (typically the image).
This method has no use in a reception context where the data receiver delivers the buffer. Use either the direct chunk access methods or the GenApi interface of the device to access chunk data.
Implements IPvChunkData.
|
virtual |
Returns the ID of a chunk based on its index.
If the index is out of range or the PvBuffer does not have any data chunk 0 is returned in aID.
[in] | aIndex | Data chunk index. |
[out] | aID | Data chunk ID for aIndex. |
Implements IPvChunkData.
|
virtual |
|
virtual |
Returns a const pointer to the data chunk with its ID matching aID.
If the aID chunk is not found or the PvBuffer does not have any chunks NULL is returned.
[in] | aID | Data chunk ID. |
Implements IPvChunkData.
|
virtual |
Returns a const pointer to the data chunk at zero-based aIndex.
Chunks are enumerated from the end of the payload data to its beginning. If the index is out of range or the PvBuffer does not have any data chunk NULL is returned.
[in] | aIndex | Data chunk index. |
Implements IPvChunkData.
|
virtual |
Returns the size in bytes of the data chunk identified by aID.
If the aID chunk is not found or the PvBuffer does not have any chunks 0 is returned.
[in] | aID | Data chunk ID. |
Implements IPvChunkData.
|
virtual |
Returns the size in bytes of the data chunk at zero-based aIndex.
Chunks are enumerated from the end of the payload data to its beginning. If the index is out of range or the PvBuffer does not have any data chunk 0 is returned.
[in] | aIndex | Data chunk index. |
Implements IPvChunkData.
const uint8_t * PvBuffer::GetDataPointer | ( | ) | const |
Get the buffer's data pointer.
The GetDataPointer method returns a pointer to the buffer. To set the memory location, use Alloc or Attach.
uint8_t * PvBuffer::GetDataPointer | ( | ) |
Get the buffer's data pointer.
uint64_t PvBuffer::GetDuration | ( | ) | const |
Get the buffer's duration.
Buffer duration when applicable. Typically used by stream decoders to control frame rate of a sequence of frames.
IPvH264AccessUnit * PvBuffer::GetH264AccessUnit | ( | ) |
Returns the IPvH264AccessUnit interface to the buffer.
If the payload type of the PvBuffer is PvPayloadTypeH264, a pointer to the IPvH264AccessUnit interface of the buffer is returned.
If the payload type of the PvBuffer is NOT IPvH264AccessUnit, a NULL pointer is returned.
This IPvH264AccessUnit pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.
const IPvH264AccessUnit * PvBuffer::GetH264AccessUnit | ( | ) | const |
Returns the IPvH264AccessUnit interface to the buffer.
Const version.
uint64_t PvBuffer::GetID | ( | ) | const |
uint32_t PvBuffer::GetIgnoredPacketCount | ( | ) | const |
Packets received that were ignored when this buffer was filled by the data receiver.
PvImage * PvBuffer::GetImage | ( | ) |
Returns the PvImage interface to the buffer.
If the payload type of the PvBuffer is PvPayloadTypeImage, a pointer to the PvImage interface of the buffer is returned.
If the payload type of the PvBuffer is NOT PvPayloadTypeImage, a NULL pointer is returned.
This PvImage pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.
const PvImage * PvBuffer::GetImage | ( | ) | const |
uint32_t PvBuffer::GetLostPacketCount | ( | ) | const |
Packets that were not successfully delivered when this PvBuffer was filled by the data receiver.
PvResult PvBuffer::GetMissingPacketIds | ( | uint32_t | aIndex, |
uint32_t & | aPacketIdLow, | ||
uint32_t & | aPacketIdHigh | ||
) |
Get a missing packet group that represents an unpopulated area of memory in this buffer.
aIndex | The index of the missing packet group being retrieved. |
aPacketIdLow | The first packet of a range of missing packets. |
aPacketIdHigh | The last packet of a range of missing packets. A value of 0xFFFFFF ( or 0xFFFFFFFF for ExtendedID ) indicates that the last packet of the block went missing and therefore the actual size of the block is unknown. |
PvResult PvBuffer::GetMissingPacketIdsCount | ( | uint32_t & | aCount | ) |
Get the number of missing packet groups that represent unpopulated areas of memory in this buffer.
When receiving data from a GigE Vision transmitter, network conditions may prevent the successful delivery of all the data for a given block. Although the eBUS data receiver provides a mechanism for requesting lost packets, there are cases when it is desirable to ignore missing packets and make use of a buffer that contains missing information. In some cases, there are portions of a block that are less important and can thus be disregarded. GetMissingPacketIdsCount and GetMissingPacketIds can provide information about which packets were lost. To use this feature take note of the following procedure:
aCount | The number of missing packet groups that represent unpopulated areas of memory in this buffer |
IPvMultiPartContainer * PvBuffer::GetMultiPartContainer | ( | ) |
Returns the PvChunkData interface to the buffer.
If the payload type of the PvBuffer is PvPayloadTypeCunkData, a pointer to the PvChunkData interface of the buffer is returned.
If the payload type of the PvBuffer is NOT PvPayloadTypeChunkData, a NULL pointer is returned.
This PvChunkData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.
const IPvMultiPartContainer * PvBuffer::GetMultiPartContainer | ( | ) | const |
Returns the PvChunkData interface to the buffer.
Const version.
PvResult PvBuffer::GetOperationResult | ( | ) | const |
Returns the value of aOperationResult when this buffer was last received through a PvStream.
Buffers with BUFFER_TOO_SMALL, ABORTED, NOT_CONNECTED and NO_MORE_ITEM operation results are never returned to the user with PvPipeline. PvPipeline handles these operation results internally without returning the buffers. Buffers with these operation results can only reach the user when using PvStream directly.
uint32_t PvBuffer::GetPacketOutOfOrderCount | ( | ) | const |
Number of packets received out of order.
uint32_t PvBuffer::GetPacketsRecoveredCount | ( | ) | const |
The number of lost packets successfully recovered by packet resend requests. Duplicate received packets are not counted.
uint32_t PvBuffer::GetPacketsRecoveredSingleResendCount | ( | ) | const |
The number of lost packets successfully recovered by packet resend requests without any resend request retries.
uint32_t PvBuffer::GetPayloadSize | ( | ) | const |
Returns payload size in bytes, excluding any extra padding.
Gets the size in bytes of the block received by the data receiver including, if present, additional chunk data and headers.
Different than GetAcquiredSize as it does not include optional additional padding when data chunks are present.
If data chunks are not present, this method returns the same value as GetAcquiredSize as extra padding is only an issue when data chunks are present.
This method is required in order to parse the chunk data using GenICam.
PvPayloadType PvBuffer::GetPayloadType | ( | ) | const |
Returns the payload type currently used by the buffer.
If data chunks are available, the buffer payload type is the same as if no data chunks were available. Use GetChunkCount to determine if chunks are available.
PvRawData * PvBuffer::GetRawData | ( | ) |
Returns the PvRawData interface to the buffer.
If the payload type of the PvBuffer is PvPayloadTypeRawData, a pointer to the PvRawData interface of the buffer is returned.
If the payload type of the PvBuffer is NOT PvPayloadTypeRawData, a NULL pointer is returned.
This PvRawData pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.
const PvRawData * PvBuffer::GetRawData | ( | ) | const |
uint64_t PvBuffer::GetReceptionTime | ( | ) | const |
Get the buffer's reception timestamp.
uint32_t PvBuffer::GetRedundantPacketCount | ( | ) | const |
Number of packets received more than once.
uint32_t PvBuffer::GetRequiredSize | ( | ) | const |
Gets the size of buffer required to hold the acquired block including, if present, additional chunk data and headers, padding.
uint32_t PvBuffer::GetResendGroupRequestedCount | ( | ) | const |
The number of resend requests issued by the data receiver.
uint32_t PvBuffer::GetResendPacketRequestedCount | ( | ) | const |
The number of packets the data receiver requests with ResendGroupRequested.
uint32_t PvBuffer::GetSize | ( | ) | const |
Get the buffer's allocated or attached size (total capacity) in bytes.
uint64_t PvBuffer::GetTimestamp | ( | ) | const |
Get the buffer's timestamp.
With hardware timestamps and GigE Vision devices, the device defines the timestamp tick frequency. The effective value can be retrieved from the GenApi interface of the device.
With hardware timestamps and USB3 Vision devices, timestamps are always defined in nanoseconds.
With software timestamps the timestamps are in micro seconds.
Use the PvStream GenApi interface to configure whether hardware or software time stamps are used.
|
virtual |
Returns true if the buffer has data chunks.
Unlike GetChunkCount, chunks do not need to be parsed or resolved with this method.
Implements IPvChunkData.
bool PvBuffer::IsAllocated | ( | ) | const |
Returns true if the buffer has been attached (instead of attached)
bool PvBuffer::IsAttached | ( | ) | const |
Returns true if the buffer has been attached (instead of allocated)
bool PvBuffer::IsExtendedID | ( | ) | const |
Check if the buffer is currently in extended ID mode.
When the extended ID mode is not enabled, the maximum block ID is 0xFFFFFF and the maximum packet ID is 0xFFFFFF as per the GEV 1.X specification. When the extended ID mode is enabled, the maximum block ID is 0xFFFFFFFFFFFFFFFF and the maximum packet ID is 0xFFFFFFFF as per the GEV 2.X specification.
When a PvBuffer is received, the extended ID mode is initialized based on the information received by PvStream. When a PvBuffer is sent, the extended ID mode will be initialized by the PvTransmitterGEV::PvTransmitterGEV according to its configuration.
bool PvBuffer::IsHeaderValid | ( | ) | const |
Returns whether this buffer has valid header (GVSP) information.
If the buffer header is not valid (missing) the buffer has to be manipulated with extreme caution. To start with, it is impossible to confirm the payload type. The timestamp and other shared header information is not valid. Finally, information specific to some payload types (like with, height, pixel format, etc. for the image payload type) is not available or valid this buffer.
When a buffer is attached or allocated for use other than receiving GVSP data, this attribute evaluates to true in order to appear as valid.
bool PvBuffer::IsTrailerValid | ( | ) | const |
Returns whether this buffer has valid trailer (GVSP) information.
If the buffer trailer is not valid (missing) some information about the buffer could be missing. As an example, the image payload type confirms the number of lines received in the trailer.
When a buffer is attached or allocated for use other than receiving GVSP data, this attribute evaluates to true in order to appear as valid.
PvResult PvBuffer::Reset | ( | PvPayloadType | aPayloadType = PvPayloadTypeImage | ) |
Reconstruct the object with a new payload type.
[in] | aPayloadType | The payload type to reset the buffer to. |
|
virtual |
Resets the internal chunk state.
Used when creating PvBuffer with chunks for transmission. This method should always be called before adding the first chunk block to a buffer. It removes chunk data from the previous sequence of AddChunkData.
If you are adding more than one chunk block to a buffer, you would normally perform this sequence for every buffer setup for transmission:
Implements IPvChunkData.
PvResult PvBuffer::SetBlockID | ( | uint64_t | aBlockID | ) |
Sets the block ID of a buffer.
Should only be used for creating synthetic test PvBuffers or copies of a PvBuffer which caries some information over from the original.
aBlockID | Block ID to assign to the buffer. |
|
virtual |
Set the chunk data layout ID.
[in] | aChunkLayoutID | Chunk data layout ID. |
Implements IPvChunkData.
PvResult PvBuffer::SetDuration | ( | uint64_t | aDuration | ) |
Set the duration of the buffer in the context of a stream.
[in] | aDuration | Duration of the buffer. |
void PvBuffer::SetID | ( | uint64_t | aID | ) |
Set the buffer's ID.
The SetID method lets you assign an arbitrary number to a buffer. When you retrieve the buffer later, you can also recover the number you assigned.
The ID is completely arbitrary and solely available for your own use. It can be useful to keep track of buffers in an application.
[in] | aID | The buffer's ID. |
PvResult PvBuffer::SetReceptionTime | ( | uint64_t | aReceptionTime | ) |
Sets the reception time of a buffer.
Should only be used for creating synthetic test PvBuffers or copies of a PvBuffer which caries some information over from the original.
aReceptionTime | Reception tiome to assign to the buffer. |
PvResult PvBuffer::SetTimestamp | ( | uint64_t | aTimestamp | ) |
Set the timestamp to place in the block leader.
When transmitting blocks to a GigE Vision receiver, by default, the timestamp on outgoing blocks is zero. However, the calling application may set a timestamp on the outgoing blocks if desired by calling SetTimestamp.
aTimestamp | The timestamp to set in the block leader |
Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com