Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvTransmitterGEV Class Reference

Class for transmitting blocks using the GigE Vision streaming protocol. More...

Public Member Functions

 PvTransmitterGEV ()
 Constructor.
 
virtual ~PvTransmitterGEV ()
 Destructor.
 
PvResult Open (PvString aDestinationIPAddress, uint16_t aDestinationPort, PvString aSourceIPAddress="", uint16_t aSourcePort=0, bool aDontFrag=true, bool aExtendedIDs=false, uint32_t aBuffersCapacity=64, bool aTimestampWhenSending=false, uint32_t aNumberOfPendingResendRequests=32, uint32_t aNumberOfBuffersHoldForResends=0)
 Initialize a socket to begin transmitting data. More...
 
PvResult Close ()
 Stop sending data and close the socket. More...
 
PvResult LoadBufferPool (PvBuffer **aBuffers, uint32_t aBufferCount)
 Load a set of free buffers into the pool. More...
 
PvResult QueueBuffer (PvBuffer *aBuffer)
 Queue one buffer in to be transmitted when a connection is available. More...
 
PvResult RetrieveFreeBuffer (PvBuffer **aBuffer, uint32_t aTimeout=0xFFFFFFFF)
 Retrieve a free buffer from the list of available buffers. More...
 
PvResult AbortQueuedBuffers (uint32_t aTimeout=0xFFFFFFFF, bool *aPartialTransmission=NULL)
 Frees all pending transmission requests. More...
 
uint32_t GetQueuedBufferCount ()
 Returns the number of buffers queued for transmission including the ones that are currently being sent. More...
 
uint32_t GetPacketSize ()
 Returns the maximum packet size of GVSP payload packets. More...
 
PvResult SetPacketSize (uint32_t aPacketSize)
 Set the maximum packet size of GVSP payload packets. More...
 
float GetMaxPayloadThroughput ()
 Returns the maximum effective throughput in bps. More...
 
PvResult SetMaxPayloadThroughput (float aMaxPayloadThroughput)
 Sets the desired effective throughput in bps. More...
 
uint16_t GetSourcePort ()
 Returns the port from which blocks are transmitted. More...
 
uint16_t GetDestinationPort ()
 Returns the port to which blocks are transmitted. More...
 
PvString GetDestinationIPAddress ()
 Returns the IP address to which blocks are transmitted. More...
 
PvString GetSourceIPAddress ()
 Returns the IP address from which blocks are transmitted. More...
 
void ResetStats ()
 Zero all running counters.
 
uint64_t GetBlocksTransmitted () const
 Get the number of blocks transmitted. More...
 
uint64_t GetSamplingTime () const
 Get the time since last reset. More...
 
uint64_t GetPayloadBytesTransmitted () const
 Get the number of payload bytes transmitted. More...
 
float GetInstantaneousPayloadThroughput () const
 Get an instantaneous calculation of the payload throughput (in bps). More...
 
float GetAveragePayloadThroughput () const
 Get the average payload throughput (in bps). More...
 
float GetInstantaneousTransmissionRate () const
 Get the instantaneous transmission rate (in blocks/second). More...
 
float GetAverageTransmissionRate () const
 Get the average transmission rate (in blocks/second). More...
 
uint64_t GetNumberOfResendRequests () const
 Get the number of resend requests. More...
 
PvResult SetSentBuffersTimeout (uint32_t aTimeout)
 Set how long the transmitter keeps a buffer available for resend requests. More...
 
uint32_t GetSentBuffersTimeout () const
 Get the timeout used to keep the buffers in the transmitter after they are sent. More...
 
virtual bool IsOpen () const
 Returns whether a connection is available to begin transmitting blocks. More...
 
virtual bool IsTransmitting () const
 Returns whether the transmitter has started transmitting blocks. More...
 
virtual bool GetExtendedIDs () const
 Get whether extended IDs are used. More...
 
virtual PvResult SetExtendedIDs (bool aExtendedID)
 Configures the transmitter to use extended (64-bit) block IDs, as specified in GigE Vision 2.0. For receivers that are compliant with earlier versions of GigE Vision, set this to false to use standard (32-bit) block IDs. This parameter should only be used with GigE Vision 2.0 compliant receivers. More...
 
virtual void QueuePacketResend (uint64_t aBlockID, uint32_t aFirstPacketID, uint32_t aLastPacketID)
 This command is for internal eBUS SDK use. It allows a virtual GigE Vision device to execute resend requests. Your application should not call this function. More...
 
uint32_t GetUserModeTransmitterThreadPriority () const
 Get the priority of the thread in charge of sending the packets on the network. More...
 
PvResult SetUserModeTransmitterThreadPriority (uint32_t aPriority)
 Set the priority of the thread in charge of sending the packets on the network. More...
 
uint32_t GetBufferPoolThreadPriority () const
 Get the priority of the thread used to manage the buffer of the buffer pool. More...
 
PvResult SetBufferPoolThreadPriority (uint32_t aPriority)
 Set the priority of the thread used to manage the buffer of the buffer pool. More...
 

Detailed Description

Class for transmitting blocks using the GigE Vision streaming protocol.

Procedure for transmitting blocks (images or raw data) with the eBUS SDK:

  • Ensure that the transmitter knows where to send blocks by calling Open.
  • Initialize the transmitter with a set of free buffers (PvBuffer objects) by calling LoadBufferPool.
  • Retrieve a free buffer to populate by calling RetrieveFreeBuffer.
  • Queue a buffer for transmission by calling QueueBuffer.
  • Once a buffer has been transmitted, it can be retrieved again by calling RetrieveFreeBuffer.

The status of a given PvBuffer object can be retrieved by calling PvBuffer::GetOperationResult.

Note
PvTransmitterGEV is only responsible for transmitting blocks. It does not implement a control channel like a complete GigE Vision device. To receive transmitted blocks with a PvStream application (such as eBUS Player), the transmitting application must be set up to respond to device discovery requests. Use PvVirtualDeviceGEV to respond to device discovery requests. If using eBUS Player to receive data being transmitted with this class, ensure that the application is set up as Data Receiver Only.

For an illustration of how this API is used in practice, refer to the following source code samples in the samples directory where the eBUS SDK resides:

  • TransmitTestPattern - Transmits a test pattern to a given destination. This is the easiest starting point for learning to use PvTransmitterGEV.
  • TransmitProcessImage - Receives video from a GigE Vision device using PvStream and PvPipeline, re-samples it and print text on it using OpenCV and finally transmits it using PvTransmitterGEV.
  • TransmitTiledImagesSample - An MFC GUI application that receives video from multiple GEV transmitters, tiles into one video feed and transmits to a given destination.

Member Function Documentation

◆ AbortQueuedBuffers()

PvResult PvTransmitterGEV::AbortQueuedBuffers ( uint32_t  aTimeout = 0xFFFFFFFF,
bool *  aPartialTransmission = NULL 
)

Frees all pending transmission requests.

Buffers that were aborted will have an operation result set at PvResult::Code::ABORTED.

Parameters
[in]aTimeoutRepresents the maximum number of milliseconds to wait for the current transmit operation before returning PvResult::Code::TIMEOUT.
[in]aPartialTransmissionOutput, set to true if transmission was stopped in the middle of a block.
Returns
PvResult::Code::OK if successful

◆ Close()

PvResult PvTransmitterGEV::Close ( )

Stop sending data and close the socket.

Any buffers that are in the middle of being transmitted are aborted.

Returns
PvResult::Code::OK if successful

◆ GetAveragePayloadThroughput()

float PvTransmitterGEV::GetAveragePayloadThroughput ( ) const

Get the average payload throughput (in bps).

Average payload transmission rate is equivalent to GetPayloadBytesTransmitted() * 8 / GetSamplingTime(). Note that this calculation only includes the number of useful data bytes and does not include GVSP, IP and UDP header overhead.

Returns
The average network throughput (in bps)

◆ GetAverageTransmissionRate()

float PvTransmitterGEV::GetAverageTransmissionRate ( ) const

Get the average transmission rate (in blocks/second).

Average transmission rate is equivalent to GetBlocksTransmitted() / GetSamplingTime().

Returns
The average transmission rate (in blocks/second)

◆ GetBlocksTransmitted()

uint64_t PvTransmitterGEV::GetBlocksTransmitted ( ) const

Get the number of blocks transmitted.

Returns
The number of blocks this object has transmitted.

◆ GetBufferPoolThreadPriority()

uint32_t PvTransmitterGEV::GetBufferPoolThreadPriority ( ) const

Get the priority of the thread used to manage the buffer of the buffer pool.

See SetBufferPoolThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread

◆ GetDestinationIPAddress()

PvString PvTransmitterGEV::GetDestinationIPAddress ( )

Returns the IP address to which blocks are transmitted.

Returns
The ip address to which blocks are transmitted. Returns an empty string when a connection has not yet been opened.

◆ GetDestinationPort()

uint16_t PvTransmitterGEV::GetDestinationPort ( )

Returns the port to which blocks are transmitted.

Returns
The port number to which blocks are transmitted. Returns 0 when a connection has not yet been opened.

◆ GetExtendedIDs()

bool PvTransmitterGEV::GetExtendedIDs ( ) const
virtual

Get whether extended IDs are used.

Returns
See SetExtendedIDs for information about the return values.

◆ GetInstantaneousPayloadThroughput()

float PvTransmitterGEV::GetInstantaneousPayloadThroughput ( ) const

Get an instantaneous calculation of the payload throughput (in bps).

Instantaneous payload transmission rate is measured using a short time frame. Note that this calculation only includes the number of useful data bytes and does not include GVSP, IP and UDP header overhead.

Returns
The payload transmission rate (in bps)

◆ GetInstantaneousTransmissionRate()

float PvTransmitterGEV::GetInstantaneousTransmissionRate ( ) const

Get the instantaneous transmission rate (in blocks/second).

Instantaneous transmission rate is measured using a short time frame.

Returns
The instantaneous transmission rate (in blocks/second)

◆ GetMaxPayloadThroughput()

float PvTransmitterGEV::GetMaxPayloadThroughput ( )

Returns the maximum effective throughput in bps.

An occasional delay is placed between the packets being transmitted to attempt to throttle the effective throughput. This helps to spread out network traffic to optimize bandwidth availability for other applications. A value of 0 (default) indicates that there should be no throttling based on throughput.

Returns
the desired throughput in bps.

◆ GetNumberOfResendRequests()

uint64_t PvTransmitterGEV::GetNumberOfResendRequests ( ) const

Get the number of resend requests.

This is the number of times the GVSP transmitter has serviced a resend request.

Returns
The number of resend requests.

◆ GetPacketSize()

uint32_t PvTransmitterGEV::GetPacketSize ( )

Returns the maximum packet size of GVSP payload packets.

When a block is packetized and transmitted, the payload is broken down into packets of a given size. The default value for the maximum packet size is 1440 because that is the size that should work in theory for all network adapters.

For best results, enable jumbo packets in your network adapter properties and increase the maximum packet size to match When sending very small blocks at high frame rates it may sometimes be desirable to set the maximum packet size to a lower number.

Returns
The maximum packet size (in bytes).

◆ GetPayloadBytesTransmitted()

uint64_t PvTransmitterGEV::GetPayloadBytesTransmitted ( ) const

Get the number of payload bytes transmitted.

Note that this value only includes the number of useful data bytes and does not include GVSP, IP and UDP header overhead.

Returns
The number of payload bytes transmitted.

◆ GetQueuedBufferCount()

uint32_t PvTransmitterGEV::GetQueuedBufferCount ( )

Returns the number of buffers queued for transmission including the ones that are currently being sent.

Returns
The number of buffers queued for transmission including the ones that are currently being sent.

◆ GetSamplingTime()

uint64_t PvTransmitterGEV::GetSamplingTime ( ) const

Get the time since last reset.

Returns
The time, in ms, since the counters were zeroed; the time since the object was created, the transmitter was opened (using Open), or ResetStats was called.

◆ GetSentBuffersTimeout()

uint32_t PvTransmitterGEV::GetSentBuffersTimeout ( ) const

Get the timeout used to keep the buffers in the transmitter after they are sent.

Returns
See SetSentBuffersTimeout for details about the meaning of the values returned

◆ GetSourceIPAddress()

PvString PvTransmitterGEV::GetSourceIPAddress ( )

Returns the IP address from which blocks are transmitted.

Returns
The IP address from which blocks are transmitted. Returns an empty string when a connection has not yet been opened.

◆ GetSourcePort()

uint16_t PvTransmitterGEV::GetSourcePort ( )

Returns the port from which blocks are transmitted.

Returns
The port number from which blocks are transmitted. Returns 0 when a connection has not yet been opened.

◆ GetUserModeTransmitterThreadPriority()

uint32_t PvTransmitterGEV::GetUserModeTransmitterThreadPriority ( ) const

Get the priority of the thread in charge of sending the packets on the network.

See SetUserModeTransmitterThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread

◆ IsOpen()

bool PvTransmitterGEV::IsOpen ( ) const
virtual

Returns whether a connection is available to begin transmitting blocks.

Returns
True if a connection is available. False if no connection is available.

◆ IsTransmitting()

bool PvTransmitterGEV::IsTransmitting ( ) const
virtual

Returns whether the transmitter has started transmitting blocks.

Returns
True if transmitting has started.

◆ LoadBufferPool()

PvResult PvTransmitterGEV::LoadBufferPool ( PvBuffer **  aBuffers,
uint32_t  aBufferCount 
)

Load a set of free buffers into the pool.

This method provides the transmitter with a set of free buffers that can be retrieved immediately by calling RetrieveFreeBuffer.

Parameters
[in]aBuffersAn array of pointers to PvBuffer objects.
[in]aBufferCountThe number of buffer pointers provided.
Returns
PvResult::Code::OK if successful

◆ Open()

PvResult PvTransmitterGEV::Open ( PvString  aDestinationIp,
uint16_t  aDestinationPort,
PvString  aSourceIp = "",
uint16_t  aSourcePort = 0,
bool  aDontFrag = true,
bool  aExtendedIDs = false,
uint32_t  aBuffersCapacity = 64,
bool  aTimestampWhenSending = false,
uint32_t  aNumberOfPendingResendRequests = 32,
uint32_t  aNumberOfBuffersHoldForResends = 0 
)

Initialize a socket to begin transmitting data.

Once this call is completed successfully, the transmitter will begin sending blocks as soon as the first buffer is queued in by calling QueueBuffer.

Parameters
[in]aDestinationIpThe address to which the transmitter will send.
[in]aDestinationPortThe port to which the transmitter will send.
[in]aSourceIpThe address from which the transmitter will send. If the parameter is an empty string (default), the socket will not be bound to a specific local IP address.
[in]aSourcePortThe port from which the transmitter will send. If the parameter is 0 (default), the source port will be dynamically assigned by the operating system.
[in]aDontFragThe value of the Don't Fragment flag in the IP header.
[in]aExtendedIDsUses the extended ID for blocks and packets when set to true. This parameter should only be used with GigE Vision 2.0 compliant receivers.
[in]aBuffersCapacityMaximum number of buffer that can be stored simultaneously in the lower layer of the transmitter.
[in]aTimestampWhenSendingSet the timestamp in the buffer header before sending the packets
[in]aNumberOfPendingResendRequestsNumber of pending resend requests allowed at the same time. All other resend requests will be ignored.
[in]aNumberOfBuffersHoldForResendsNumber of PvBuffers held in the transmitter to service resend requests after the block is transferred.
Returns
PvResult::Code::OK if successful PvResult::Code::NETWORK_ERROR if the socket could not be created

◆ QueueBuffer()

PvResult PvTransmitterGEV::QueueBuffer ( PvBuffer aBuffer)

Queue one buffer in to be transmitted when a connection is available.

Parameters
[in]aBufferThe buffer to transmit.
Returns
PvResult::Code::OK if successful. PvResult::Code::BUFFER_TOO_SMALL if the buffer is empty.

◆ QueuePacketResend()

void PvTransmitterGEV::QueuePacketResend ( uint64_t  aBlockID,
uint32_t  aFirstPacketID,
uint32_t  aLastPacketID 
)
virtual

This command is for internal eBUS SDK use. It allows a virtual GigE Vision device to execute resend requests. Your application should not call this function.

Parameters
[in]aBlockIDBlock ID of the buffer.
[in]aFirstPacketIDFirst packet ID of the range.
[in]aLastPacketIDLast packet ID of the range.

◆ RetrieveFreeBuffer()

PvResult PvTransmitterGEV::RetrieveFreeBuffer ( PvBuffer **  aBuffer,
uint32_t  aTimeout = 0xFFFFFFFF 
)

Retrieve a free buffer from the list of available buffers.

Parameters
[out]aBufferThe buffer that is available to populate and transmit. The pointer is set to NULL if no buffer is available.
[in]aTimeoutThe maximum number of milliseconds to wait for a free buffer to become available.
Returns
PvResult::Code::OK if successful.or PvResult::Code::TIMEOUT if the aTimeout parameter was exceeded while waiting for a buffer to become available.

◆ SetBufferPoolThreadPriority()

PvResult PvTransmitterGEV::SetBufferPoolThreadPriority ( uint32_t  aPriority)

Set the priority of the thread used to manage the buffer of the buffer pool.

Only applicable if using a buffer pool ( See LoadBufferPool ). The thread will manage the buffer exchange with the transmitter.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See GetBufferPoolThreadPriority

Parameters
[in]aPrioritySee PvPipeline::SetBufferHandlingThreadPriority for description of the supported values
Returns
Includes:

◆ SetExtendedIDs()

PvResult PvTransmitterGEV::SetExtendedIDs ( bool  aExtendedID)
virtual

Configures the transmitter to use extended (64-bit) block IDs, as specified in GigE Vision 2.0. For receivers that are compliant with earlier versions of GigE Vision, set this to false to use standard (32-bit) block IDs. This parameter should only be used with GigE Vision 2.0 compliant receivers.

Note
Can only be changed before the first buffer is queued in the transmitter.
Parameters
aExtendedIDTrue to use extended IDs.
Returns
PvResult::Code::OK if successful. PvResult::Code::BUSY buffer(s) were already queued.

◆ SetMaxPayloadThroughput()

PvResult PvTransmitterGEV::SetMaxPayloadThroughput ( float  aMaxPayloadThroughput)

Sets the desired effective throughput in bps.

An occasional delay is placed between the packets being transmitted to attempt to throttle the effective throughput. This helps to spread out network traffic to optimize bandwidth availability for other applications. A value of 0 (default) indicates that there should be no throttling based on throughput.

The throughput is measured in effective throughput on the content of the transmitted PvBuffer objects. It does not take into account the GigE Vision, UDP, IP and Ethernet protocol overhead of the packetized data.

Parameters
aMaxPayloadThroughputThe maximum throughput in bps.
Returns
PvResult::Code::OK if successful.

◆ SetPacketSize()

PvResult PvTransmitterGEV::SetPacketSize ( uint32_t  aPacketSize)

Set the maximum packet size of GVSP payload packets.

When a block is packetized and transmitted, the payload is broken down into packets of a given size. The default value for the maximum packet size is 1440 because that is the size that should work in theory for all network adapters.

For best results, enable jumbo packets in your network adapter properties and increase the maximum packet size to match When sending very small blocks at high frame rates it may sometimes be desirable to set the maximum packet size to a lower number.

Parameters
[in]aPacketSizeThe maximum packet size (in bytes).
Returns
PvResult::Code::OK if successful, PvResult::Code::INVALID_PARAMETER if aPacketSize is less than or equal to 36

◆ SetSentBuffersTimeout()

PvResult PvTransmitterGEV::SetSentBuffersTimeout ( uint32_t  aTimeout)

Set how long the transmitter keeps a buffer available for resend requests.

This timeout allows the system to hold the buffer to service the resend requests. The timeout is only checked when each image (PvBuffer) is sent, so the accuracy is not exact.

Parameters
aTimeoutThe timeout value, in milliseconds.
Returns
PvResult::Code::OK if successful.

◆ SetUserModeTransmitterThreadPriority()

PvResult PvTransmitterGEV::SetUserModeTransmitterThreadPriority ( uint32_t  aPriority)

Set the priority of the thread in charge of sending the packets on the network.

Only applicable if using a user-mode transmitter. The thread priority of a driver-based transmitter cannot be controlled. Thread that is responsible for breaking buffers in packets and transmitting them.

If you change the thread priorities, it may alterate the stability of the system. For this reason, if you report a bug to Pleora, ensure to clearly mention that you change threads priorities.

See GetUserModeTransmitterThreadPriority

Parameters
[in]aPrioritySee PvPipeline::SetBufferHandlingThreadPriority for description of the supported values
Returns
Includes:

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

Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com