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... | |
Class for transmitting blocks using the GigE Vision streaming protocol.
Procedure for transmitting blocks (images or raw data) with the eBUS SDK:
The status of a given PvBuffer object can be retrieved by calling PvBuffer::GetOperationResult.
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:
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.
[in] | aTimeout | Represents the maximum number of milliseconds to wait for the current transmit operation before returning PvResult::Code::TIMEOUT. |
[in] | aPartialTransmission | Output, set to true if transmission was stopped in the middle of a block. |
PvResult PvTransmitterGEV::Close | ( | ) |
Stop sending data and close the socket.
Any buffers that are in the middle of being transmitted are aborted.
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.
float PvTransmitterGEV::GetAverageTransmissionRate | ( | ) | const |
Get the average transmission rate (in blocks/second).
Average transmission rate is equivalent to GetBlocksTransmitted() / GetSamplingTime().
uint64_t PvTransmitterGEV::GetBlocksTransmitted | ( | ) | const |
Get the number of blocks transmitted.
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
PvString PvTransmitterGEV::GetDestinationIPAddress | ( | ) |
Returns the IP address to which blocks are transmitted.
uint16_t PvTransmitterGEV::GetDestinationPort | ( | ) |
Returns the port to which blocks are transmitted.
|
virtual |
Get whether extended IDs are used.
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.
float PvTransmitterGEV::GetInstantaneousTransmissionRate | ( | ) | const |
Get the instantaneous transmission rate (in blocks/second).
Instantaneous transmission rate is measured using a short time frame.
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.
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.
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.
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.
uint32_t PvTransmitterGEV::GetQueuedBufferCount | ( | ) |
Returns the number of buffers queued for transmission including the ones that are currently being sent.
uint64_t PvTransmitterGEV::GetSamplingTime | ( | ) | const |
Get the time since last reset.
uint32_t PvTransmitterGEV::GetSentBuffersTimeout | ( | ) | const |
Get the timeout used to keep the buffers in the transmitter after they are sent.
PvString PvTransmitterGEV::GetSourceIPAddress | ( | ) |
Returns the IP address from which blocks are transmitted.
uint16_t PvTransmitterGEV::GetSourcePort | ( | ) |
Returns the port from which blocks are transmitted.
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
|
virtual |
Returns whether a connection is available to begin transmitting blocks.
|
virtual |
Returns whether the transmitter has started transmitting blocks.
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.
[in] | aBuffers | An array of pointers to PvBuffer objects. |
[in] | aBufferCount | The number of buffer pointers provided. |
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.
[in] | aDestinationIp | The address to which the transmitter will send. |
[in] | aDestinationPort | The port to which the transmitter will send. |
[in] | aSourceIp | The 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] | aSourcePort | The 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] | aDontFrag | The value of the Don't Fragment flag in the IP header. |
[in] | aExtendedIDs | Uses 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] | aBuffersCapacity | Maximum number of buffer that can be stored simultaneously in the lower layer of the transmitter. |
[in] | aTimestampWhenSending | Set the timestamp in the buffer header before sending the packets |
[in] | aNumberOfPendingResendRequests | Number of pending resend requests allowed at the same time. All other resend requests will be ignored. |
[in] | aNumberOfBuffersHoldForResends | Number of PvBuffers held in the transmitter to service resend requests after the block is transferred. |
Queue one buffer in to be transmitted when a connection is available.
[in] | aBuffer | The buffer to transmit. |
|
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.
[in] | aBlockID | Block ID of the buffer. |
[in] | aFirstPacketID | First packet ID of the range. |
[in] | aLastPacketID | Last packet ID of the range. |
PvResult PvTransmitterGEV::RetrieveFreeBuffer | ( | PvBuffer ** | aBuffer, |
uint32_t | aTimeout = 0xFFFFFFFF |
||
) |
Retrieve a free buffer from the list of available buffers.
[out] | aBuffer | The buffer that is available to populate and transmit. The pointer is set to NULL if no buffer is available. |
[in] | aTimeout | The maximum number of milliseconds to wait for a free buffer to become available. |
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
[in] | aPriority | See PvPipeline::SetBufferHandlingThreadPriority for description of the supported values |
|
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.
aExtendedID | True to use extended IDs. |
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.
aMaxPayloadThroughput | The maximum throughput in bps. |
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.
[in] | aPacketSize | The maximum packet size (in bytes). |
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.
aTimeout | The timeout value, in milliseconds. |
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
[in] | aPriority | See PvPipeline::SetBufferHandlingThreadPriority for description of the supported values |
Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com