Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvStream Class Referenceabstract

Receive data from a GigE Vision or USB3 Vision transmitter. More...

Public Member Functions

virtual ~PvStream ()
 Destructor.
 
uint32_t GetQueuedBufferCount () const
 Get the number of buffers (PvBuffer objects) waiting to be filled with images by the data receiver. More...
 
uint32_t GetQueuedBufferMaximum () const
 Get the maximum number of buffers (PvBuffer objects) that can be queued at a time. More...
 
PvResult Close ()
 Close the stream channel receiver. More...
 
virtual PvStreamType GetType () const
 Returns whether the object is a GigE Vision or USB3 Vision stream receiver. More...
 
PvResult AbortQueuedBuffers ()
 Abort all pending block requests. More...
 
PvResult QueueBuffer (PvBuffer *aBuffer)
 Queue a buffer to receive a block. More...
 
PvResult RetrieveBuffer (PvBuffer **aBuffer, PvResult *aOperationResult, uint32_t aTimeout=0xFFFFFFFF)
 Attempt to retrieve a queued buffer. More...
 
uint16_t GetChannel ()
 Get the stream's Channel property. More...
 
bool IsOpen () const
 Test if the stream is open. More...
 
PvResult RegisterEventSink (PvStreamEventSink *aEventSink)
 Register an event sink used for callbacks. More...
 
PvResult UnregisterEventSink (PvStreamEventSink *aEventSink)
 Unregister an event sink. More...
 
PvGenParameterArrayGetParameters ()
 Get the parameters defining how data is received from a GigE Vision transmitter. More...
 

Static Public Member Functions

static PvStreamCreateAndOpen (const PvDeviceInfo *aDeviceInfo, PvResult *aResult)
 Dynamically allocates a PvStream of the right type. More...
 
static PvStreamCreateAndOpen (const PvString &aInfo, PvResult *aResult)
 Dynamically allocates a PvStream of the right type. More...
 
static void Free (PvStream *aStream)
 Frees an object allocated with CreateAndOpen. More...
 

Protected Member Functions

 PvStream ()
 Constructor.
 

Friends

class PvPipeline
 

Detailed Description

Receive data from a GigE Vision or USB3 Vision transmitter.

This provides a means of opening a connection to the data receiver and obtaining data from it.

Member Function Documentation

◆ AbortQueuedBuffers()

PvResult PvStream::AbortQueuedBuffers ( )

Abort all pending block requests.

Once you've aborted pending block requests, they still need to be de-queued. Use RetrieveBuffer.

Returns
Includes:

◆ Close()

PvResult PvStream::Close ( )

Close the stream channel receiver.

Returns
Includes:
See also
Open

◆ CreateAndOpen() [1/2]

PvStream * PvStream::CreateAndOpen ( const PvDeviceInfo aDeviceInfo,
PvResult aResult 
)
static

Dynamically allocates a PvStream of the right type.

This static method takes a generic PvDeviceInfo, creates the right type of PvStream (PvStreamGEV or PvStreamU3V) and opens it.

Objects allocated with CreateAndOpen should be freed with PvStream::Free.

Parameters
[in]aDeviceInfoPointer to the device information used to open the stream.
[out]aResultOutcome of the operation. Includes:
Returns
A pointer to the new object on success, NULL on failure. See aResult for more information on the failure.

◆ CreateAndOpen() [2/2]

PvStream * PvStream::CreateAndOpen ( const PvString aInfo,
PvResult aResult 
)
static

Dynamically allocates a PvStream of the right type.

This static method takes a string and creates the right type of PvStream (PvStreamGEV or PvStreamU3V) and connects it.

Objects allocated with CreateAndOpen should be freed with PvStream::Free.

Parameters
[in]aInfoInformation that uniquely identifies the device. You may use one of the following:
  • GigE Vision device's IP Address. Use the form 192.168.1.114.
  • USB3 Vision GUID.
[out]aResultOutcome of the operation. Includes:
Returns
A pointer to the new object on success, NULL on failure. See aResult for more information on the failure (unless failure was aResult being NULL)

◆ Free()

void PvStream::Free ( PvStream aStream)
static

Frees an object allocated with CreateAndOpen.

Even though calling delete on a PvStream created with CreateAndOpen should work in most cases, sometime it is necessary to call "delete" in the same context where "new" was called to avoid false positives on memory leaks.

It is a good practice to use this method to free a PvStream allocated with CreateAndOpen.

Parameters
[in]aStreamPointer to the device object to delete.

◆ GetChannel()

uint16_t PvStream::GetChannel ( )

Get the stream's Channel property.

Returns
The stream's Channel property.

◆ GetParameters()

PvGenParameterArray * PvStream::GetParameters ( )

Get the parameters defining how data is received from a GigE Vision transmitter.

Returns
The parameters defining how data is received from a GigE Vision transmitter

◆ GetQueuedBufferCount()

uint32_t PvStream::GetQueuedBufferCount ( ) const

Get the number of buffers (PvBuffer objects) waiting to be filled with images by the data receiver.

Every call to QueueBuffer increases the count by one; every call to RetrieveBuffer reduces the count by one.

Returns
The number of buffers (PvBuffer objects).

◆ GetQueuedBufferMaximum()

uint32_t PvStream::GetQueuedBufferMaximum ( ) const

Get the maximum number of buffers (PvBuffer objects) that can be queued at a time.

Returns
Maximum number of buffers (PvBuffer objects).

◆ GetType()

PvStreamType PvStream::GetType ( ) const
virtual

Returns whether the object is a GigE Vision or USB3 Vision stream receiver.

Returns
Specific object type.

Reimplemented in PvStreamGEV, PvStreamRTP, and PvStreamU3V.

◆ IsOpen()

bool PvStream::IsOpen ( ) const

Test if the stream is open.

Returns
True if the stream is opened; otherwise, false.

◆ QueueBuffer()

PvResult PvStream::QueueBuffer ( PvBuffer aBuffer)

Queue a buffer to receive a block.

The QueueBuffer method queues in a buffer (PvBuffer object) to a stream (PvStream object) so it can be filled by the data receiver.

For each buffer you remove (using RetrieveBuffer), you should queue another (using QueueBuffer). The maximum number of buffers that can be queued at a given time can be obtained by calling GetQueuedBufferMaximum. To reduce the risk of missing incoming data, it is recommended that several blocks remain queued and ready to go at any given time. Generally it is recommended that a larger number of buffers remain queued for higher frame rates. Larger block sizes with blocks being streamed at a lower frame rate can afford to allocate fewer buffers to optimize memory usage and reduce potential latency.

Once the stream fills the buffer with a block, retrieve the buffer by calling RetrieveBuffer.

Parameters
[in]aBufferA pointer to the buffer to be filled.
Returns
Includes:

◆ RegisterEventSink()

PvResult PvStream::RegisterEventSink ( PvStreamEventSink aEventSink)

Register an event sink used for callbacks.

Parameters
[in]aEventSinkA pointer to the event sink.
Returns
Includes:

◆ RetrieveBuffer()

PvResult PvStream::RetrieveBuffer ( PvBuffer **  aBuffer,
PvResult aOperationResult,
uint32_t  aTimeout = 0xFFFFFFFF 
)

Attempt to retrieve a queued buffer.

To use this method, see also QueueBuffer.

The RetrieveBuffer method blocks until one of the following occurs:

  • The buffer is filled with a block (image or raw data).
  • The retrieve buffer operation times out: it exceeds aTimeout.
  • The acquisition fails (by being aborted, data receiver timeout as defined by ImageTimeout property, etc.)

Once the method returns, you can determine the ultimate success of the image acquisition by testing the aOperationResult parameter. For example, RetrieveBuffer may return PvResult::Code::OK, even if the operation was aborted (by a call to AbortQueuedBuffers or Close). In this case, aOperationResult would be PvResult::Code::ABORTED.

The return value contains the RetrieveBuffer operation results and aOperationResult contains the actual result (or failure) of the data receiver on this buffer. This method can succeed in providing you the oldest buffer but the result of the operation may still be a failure - if acquisition was aborted, incomplete, etc.

Parameters
[out]aBufferThe buffer that holds the image.
[out]aOperationResultA pointer to the result of the acquisition operation on aBuffer, see PvBuffer::GetOperationResult.
[in]aTimeoutThe maximum time, in ms, to wait for a buffer to be returned by the data receiver.
Returns
Includes:

◆ UnregisterEventSink()

PvResult PvStream::UnregisterEventSink ( PvStreamEventSink aEventSink)

Unregister an event sink.

Parameters
[in]aEventSinkA pointer to the event sink.
Returns
Includes:
See also
RegisterEventSink

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

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