Class PvBuffer

Represents a block of GigE Vision or USB3 Vision data in memory

Inheritance

object

IPvChunkData

PvBuffer

Implements

IDisposable

Inherited Members

IPvChunkData.swigCMemOwn

IPvChunkData.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: eBUSDotNet

Assembly: eBUSDotNet.dll

Syntax

public class PvBuffer : IPvChunkData, IDisposable

Remarks

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

Creating and configuring buffers:

• Create several buffers using the default constructor.
• Set the size of the buffer. The method you use depends on whether you want to use an internally or externally controlled block of memory:
  • To use memory that the PvBuffer object allocates and owns, use Alloc(uint).
  • To use memory that you control (external to the PvBuffer object), use Attach(byte[], uint).

Accessing payload type specific data:

• Retrieve the PayloadType using the PayloadType property.
• If PayloadType is PvPayloadTypeImage, retrieve PvImage pointer from your PvBuffer using GetImage().
• Access image specific data through the PvImage pointer, like Width, Height, etc.
• There is no need to release or delete the PvImage pointer. It is valid as long as the PvBuffer exists.

Processing images:

• Retrieve a PvImage interface to the buffer using GetImage().
• Test the success of the image acquisition using the OperationResult property.
• Process the image using your own code. You may process the image in place, if you wish.

Constructors

PvBuffer()

Constructor.

Declaration

public PvBuffer()

PvBuffer(PvPayloadType)

Constructor.

Declaration

public PvBuffer(PvPayloadType aPayloadType)

Parameters

Type	Name	Description
PvPayloadType	aPayloadType	The block type (default PvPayloadTypeImage).

Properties

AcquiredSize

Gets the size, in bytes of the payload received by the data receiver.

Declaration

public uint AcquiredSize { get; }

Property Value

Type	Description
uint

Remarks

This property is not necessarily equal to (Width * Height * BitsPerPixel) / 8 + (PaddingX * Height + PaddingY) for an image.

BlockID

Gets or sets the block ID.

Declaration

public ulong BlockID { get; set; }

Property Value

Type	Description
ulong

Remarks

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

ChunkCount

ChunkCount property of PvBuffer.

Declaration

public override uint ChunkCount { get; }

Property Value

Type	Description
uint

Overrides

IPvChunkData.ChunkCount

ChunkDataCapacity

ChunkDataCapacity property of PvBuffer.

Declaration

public override uint ChunkDataCapacity { get; }

Property Value

Type	Description
uint

Overrides

IPvChunkData.ChunkDataCapacity

ChunkDataSize

ChunkDataSize property of PvBuffer.

Declaration

public override uint ChunkDataSize { get; }

Property Value

Type	Description
uint

Overrides

IPvChunkData.ChunkDataSize

ChunkLayoutID

ChunkLayoutID property of PvBuffer.

Declaration

public override uint ChunkLayoutID { get; set; }

Property Value

Type	Description
uint

Overrides

IPvChunkData.ChunkLayoutID

ID

ID of PvBuffer.

Declaration

public ulong ID { get; set; }

Property Value

Type	Description
ulong

IgnoredPacketCount

Ignored packet count of PvBuffer.

Declaration

public uint IgnoredPacketCount { get; }

Property Value

Type	Description
uint

LostPacketCount

Lost packet count of PvBuffer.

Declaration

public uint LostPacketCount { get; }

Property Value

Type	Description
uint

OperationResult

Gets the value of the operation result when this buffer was last received through a PvStream.

Declaration

public PvResult OperationResult { get; }

Property Value

Type	Description
PvResult

Remarks

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.

PacketOutOfOrderCount

Packet out of order count of PvBuffer.

Declaration

public uint PacketOutOfOrderCount { get; }

Property Value

Type	Description
uint

PacketsRecoveredCount

The number of lost packets successfully recovered by packet resend requests.

Declaration

public uint PacketsRecoveredCount { get; }

Property Value

Type	Description
uint

Remarks

Duplicate received packets are not counted.

PacketsRecoveredSingleResendCount

Packets recovered single resend count of PvBuffer.

Declaration

public uint PacketsRecoveredSingleResendCount { get; }

Property Value

Type	Description
uint

PayloadSize

Payload size of PvBuffer.

Declaration

public uint PayloadSize { get; }

Property Value

Type	Description
uint

PayloadType

Payload type of PvBuffer.

Declaration

public PvPayloadType PayloadType { get; }

Property Value

Type	Description
PvPayloadType

PvDuration

Duration of PvBuffer.

Declaration

public ulong PvDuration { get; set; }

Property Value

Type	Description
ulong

PvSize

Size of PvBuffer.

Declaration

public uint PvSize { get; }

Property Value

Type	Description
uint

ReceptionTime

Reception time of PvBuffer.

Declaration

public ulong ReceptionTime { get; set; }

Property Value

Type	Description
ulong

RedundantPacketCount

Redundant packet count of PvBuffer.

Declaration

public uint RedundantPacketCount { get; }

Property Value

Type	Description
uint

RequiredSize

Required size of PvBuffer.

Declaration

public uint RequiredSize { get; }

Property Value

Type	Description
uint

ResendGroupRequestedCount

Resend group requested count of PvBuffer.

Declaration

public uint ResendGroupRequestedCount { get; }

Property Value

Type	Description
uint

ResendPacketRequestedCount

Resend packet requested count of PvBuffer.

Declaration

public uint ResendPacketRequestedCount { get; }

Property Value

Type	Description
uint

Timestamp

Gets or sets the buffer's timestamp.

Declaration

public ulong Timestamp { get; set; }

Property Value

Type	Description
ulong

Remarks

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

Use the PvStream GenApi interface to configure whether hardware or software time stamps are used.

Methods

AddChunk(uint, byte[], uint)

Add chunk data to the buffer.

Declaration

public override PvResult AddChunk(uint aID, byte[] aData, uint aLength)

Parameters

Type	Name	Description
uint	aID	Chunk data ID for aIndex.
byte[]	aData	Payload data of the chunk data.
uint	aLength	Length of the payload data of the chunk, in bytes. Must be a multiple of 4 bytes.

Returns

Type	Description
PvResult	A PvResult is used to capture the success or failure of the operation: #PvResult::Code::OK #PvResult::Code::BUFFER_TOO_SMALL There is not enough space in the buffer to add the chunk data. #PvResult::Code::INVALID_PARAMETER One of the input arguments is invalid.

Overrides

IPvChunkData.AddChunk(uint, byte[], uint)

Alloc(uint)

Allocates memory for this #PvBuffer.

Declaration

public PvResult Alloc(uint aSize)

Parameters

Type	Name	Description
uint	aSize	The size of the buffer, in bytes.

Returns

Type	Description
PvResult	Includes: #PvResult::Code::OK #PvResult::Code::NOT_ENOUGH_MEMORY

AllocChunk(uint)

Alloc a separate space for chunk data in this #PvBuffer.

Declaration

public PvResult AllocChunk(uint aSize)

Parameters

Type	Name	Description
uint	aSize	The size, in bytes, required for the buffer.

Returns

Type	Description
PvResult	Includes: #PvResult::Code::OK #PvResult::Code::INVALID_PARAMETER

See Also

FreeChunk()

Attach(byte[], uint)

Attach this #PvBuffer to an external memory buffer.

Declaration

public PvResult Attach(byte[] aBuffer, uint aSize)

Parameters

Type	Name	Description
byte[]	aBuffer	A pointer to the buffer.
uint	aSize	The size, in bytes, of the buffer.

Returns

Type	Description
PvResult	Includes: #PvResult::Code::OK #PvResult::Code::INVALID_PARAMETER

Remarks

To use an internal memory buffer, use Alloc(uint).

See Also

Detach()

AttachGenDCManager(IPvGenDCManager)

Attaches the GenDC Manager to a PvBuffer.

Declaration

public PvResult AttachGenDCManager(IPvGenDCManager aManager)

Parameters

Type	Name	Description
IPvGenDCManager	aManager	The GenDC Manager to attach to the buffer.

Returns

Type	Description
PvResult	#PvResult::Code::OK or #PvResult::Code::INVALID_PARAMETER if the buffer is not of GenDC type

Detach()

Releases an attached memory buffer.

Declaration

public byte* Detach()

Returns

Type	Description
byte*	The buffer's location in memory.

See Also

Attach(byte[], uint)

Dispose(bool)

Dispose

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing

Overrides

IPvChunkData.Dispose(bool)

FindTrackedBuffer(PvBuffer)

Finds a tracked buffer by its native pointer.

Declaration

public static PvBuffer FindTrackedBuffer(PvBuffer genericWrapper)

Parameters

Type	Name	Description
PvBuffer	genericWrapper	A wrapper containing the native pointer to look up.

Returns

Type	Description
PvBuffer	The tracked buffer if found and still alive, otherwise null.

Free()

Frees (de-allocates) the buffer's internal memory.

Declaration

public void Free()

See Also

Alloc(uint)

FreeChunk()

Frees (de-allocates) an attached memory buffer of chunk data.

Declaration

public void FreeChunk()

See Also

AllocChunk(uint)

GetChunkData()

Returns the #PvChunkData interface to the buffer.

Declaration

public PvChunkData GetChunkData()

Returns

Type	Description
PvChunkData	Pointer to #PvChunkData interface or NULL, depending on payload type.

GetChunkIDByIndex(uint, out uint)

Returns the ID of a chunk based on its index.

Declaration

public override PvResult GetChunkIDByIndex(uint aIndex, out uint aID)

Parameters

Type	Name	Description
uint	aIndex	Data chunk index.
uint	aID	Data chunk ID for aIndex.

Returns

Type	Description
PvResult	A PvResult is used to captured the success or failure of the operation as 0 can be a valid chunk ID: - #PvResult::Code::OK - #PvResult::Code::NOT_FOUND if the index is out of range or the buffer does not have any chunks

Overrides

IPvChunkData.GetChunkIDByIndex(uint, out uint)

GetChunkRawDataByID(uint)

Returns a const pointer to the data chunk with its ID matching aID.

Declaration

public override byte* GetChunkRawDataByID(uint aID)

Parameters

Type	Name	Description
uint	aID	Data chunk ID.

Returns

Type	Description
byte*	Point to chunk data. NULL if the chunk ID is not found.

Overrides

IPvChunkData.GetChunkRawDataByID(uint)

GetChunkRawDataByIndex(uint)

Returns a const pointer to the data chunk at zero-based aIndex.

Declaration

public override byte* GetChunkRawDataByIndex(uint aIndex)

Parameters

Type	Name	Description
uint	aIndex	Data chunk index.

Returns

Type	Description
byte*	Point to chunk data. NULL if the index is out of range.

Overrides

IPvChunkData.GetChunkRawDataByIndex(uint)

GetChunkSizeByID(uint)

Returns the size in bytes of the data chunk identified by aID.

Declaration

public override uint GetChunkSizeByID(uint aID)

Parameters

Type	Name	Description
uint	aID	Data chunk ID.

Returns

Type	Description
uint	Data chunk size. 0 if the chunk ID is not found.

Overrides

IPvChunkData.GetChunkSizeByID(uint)

GetChunkSizeByIndex(uint)

Returns the size in bytes of the data chunk at zero-based aIndex.

Declaration

public override uint GetChunkSizeByIndex(uint aIndex)

Parameters

Type	Name	Description
uint	aIndex	Data chunk index.

Returns

Type	Description
uint	Data chunk size. 0 if the index is out of range.

Overrides

IPvChunkData.GetChunkSizeByIndex(uint)

GetDataPointer()

Get the buffer's data pointer.

Declaration

public byte* GetDataPointer()

Returns

Type	Description
byte*	A pointer to the memory pointer.

GetGenDC()

Returns the #IPvGenericDataContainer interface to the buffer.

Declaration

public IPvGenericDataContainer GetGenDC()

Returns

Type	Description
IPvGenericDataContainer	Pointer to #IPvGenericDataContainer interface or NULL, depending on payload type.

GetH264AccessUnit()

Returns the #IPvH264AccessUnit interface to the buffer.

Declaration

public IPvH264AccessUnit GetH264AccessUnit()

Returns

Type	Description
IPvH264AccessUnit	Pointer to #IPvH264AccessUnit interface or NULL, depending on payload type.

GetImage()

Returns the #PvImage interface to the buffer.

Declaration

public PvImage GetImage()

Returns

Type	Description
PvImage	Pointer to #PvImage interface or NULL, depending on payload type.

Remarks

If the payload type of the PvBuffer is PvPayloadTypeImage, a pointer to the PvImage interface of the buffer is returned.

If the payload type is NOT PvPayloadTypeImage, NULL is returned.

This pointer is owned by the PvBuffer and does not need to be released after use. It is valid as long as the PvBuffer exists.

GetMissingPacketIds(uint, out uint, out uint)

Get a missing packet group that represents an unpopulated area of memory in this buffer

Declaration

public PvResult GetMissingPacketIds(uint aIndex, out uint aPacketIdLow, out uint aPacketIdHigh)

Parameters

Type	Name	Description
uint	aIndex	The index of the missing packet group being retrieved.
uint	aPacketIdLow	The first packet of a range of missing packets.
uint	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.

Returns

Type	Description
PvResult	#PvResult::Code::OK or #PvResult::Code::NOT_IMPLEMENTED.

GetMissingPacketIdsCount(out uint)

Get the number of missing packet groups that represent unpopulated areas of memory in this buffer

Declaration

public PvResult GetMissingPacketIdsCount(out uint aCount)

Parameters

Type	Name	Description
uint	aCount	The number of missing packet groups that represent unpopulated areas of memory in this buffer

Returns

Type	Description
PvResult	#PvResult::Code::OK or #PvResult::Code::NOT_IMPLEMENTED.

GetMultiPartContainer()

Returns the #IPvMultiPartContainer interface to the buffer.

Declaration

public IPvMultiPartContainer GetMultiPartContainer()

Returns

Type	Description
IPvMultiPartContainer	Pointer to #IPvMultiPartContainer interface or NULL, depending on payload type.

GetPleoraCompressed()

Returns the #PvPleoraCompressed interface to the buffer.

Declaration

public PvPleoraCompressed GetPleoraCompressed()

Returns

Type	Description
PvPleoraCompressed	Pointer to #PvPleoraCompressed interface or NULL, depending on payload type.

GetRawData()

Returns the #PvRawData interface to the buffer.

Declaration

public PvRawData GetRawData()

Returns

Type	Description
PvRawData	Pointer to #PvRawData interface or NULL, depending on payload type.

HasChunks()

Returns true if the buffer has data chunks.

Declaration

public override bool HasChunks()

Returns

Type	Description
bool	True if the buffer holds data chunks, false if not.

Overrides

IPvChunkData.HasChunks()

IsAllocated()

Returns true if the buffer has been attached (instead of attached)

Declaration

public bool IsAllocated()

Returns

Type	Description
bool	True if allocated.

IsAttached()

Returns true if the buffer has been attached (instead of allocated)

Declaration

public bool IsAttached()

Returns

Type	Description
bool	True if attached.

IsExtendedID()

Check if the buffer is currently in extended ID mode.

Declaration

public bool IsExtendedID()

Returns

Type	Description
bool	true if the extended if mode is in usage:

Remarks

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 the PvStream. When a PvBuffer is sent, the extended ID mode will be initialized by the PvTransmitterGEV according to its configuration.

IsHeaderValid()

Returns whether this buffer has valid header (GVSP) information.

Declaration

public bool IsHeaderValid()

Returns

Type	Description
bool	True if the GVSP header is valid.

IsLargeLeaderTrailerEnabled()

Returns whether this buffer has large data leader and data trailer enabled.

Declaration

public bool IsLargeLeaderTrailerEnabled()

Returns

Type	Description
bool	True if the Large Data Leader and Trailer is enabled on the buffer which contains Multi-part.

IsTrailerValid()

Returns whether this buffer has valid trailer (GVSP) information.

Declaration

public bool IsTrailerValid()

Returns

Type	Description
bool	True if the GVSP header is valid.

Reset()

Reconstruct the object with a new payload type.

Declaration

public PvResult Reset()

Returns

Type	Description
PvResult	#PvResult::Code::OK if successful.

Remarks

This method resets the buffer to a different payload type, releasing any previously allocated resources and preparing it for a new type of data.

Reset(PvPayloadType)

Reconstruct the object with a new payload type.

Declaration

public PvResult Reset(PvPayloadType aPayloadType)

Parameters

Type	Name	Description
PvPayloadType	aPayloadType	The payload type to reset the buffer to.

Returns

Type	Description
PvResult	#PvResult::Code::OK if successful.

Remarks

This method resets the buffer to a different payload type, releasing any previously allocated resources and preparing it for a new type of data.

ResetChunks()

Resets the internal chunk state.

Declaration

public override void ResetChunks()

Overrides

IPvChunkData.ResetChunks()

TrackBuffer(PvBuffer)

Tracks a buffer by storing a weak reference to prevent premature garbage collection.

Declaration

public static void TrackBuffer(PvBuffer buffer)

Parameters

Type	Name	Description
PvBuffer	buffer	The buffer to track.

Implements

IDisposable