Pleora Technologies Inc. eBUS SDK v6.2.8.5877 API



PvPipeline Class Reference

Helper class for receiving data from a GigE Vision or USB3 Vision transmitter. More...

Public Member Functions

 PvPipeline (PvStream *aStream)
 Constructor. More...
 
virtual ~PvPipeline ()
 Virtual destructor.
 
uint32_t GetBufferSize () const
 Get the size for all managed buffers in bytes. More...
 
uint32_t GetBufferCount () const
 Get number of buffers owned and used by the pipeline. More...
 
uint32_t GetOutputQueueSize () const
 Returns the number of PvBuffer objects currently available in the output queue. More...
 
bool GetHandleBufferTooSmall () const
 Returns if the pipeline is configured to handle BUFFER_TOO_SMALL operation results automatically. More...
 
bool IsStarted ()
 Test if the pipeline has started. More...
 
void SetBufferSize (uint32_t aSize)
 Set the optimal size of buffers being queued into the data receiver. More...
 
PvResult SetBufferCount (uint32_t aBufferCount)
 Set the number of buffers owned and used by the PvPipeline. More...
 
void SetHandleBufferTooSmall (bool aValue)
 Configures whether the pipeline handles BUFFER_TOO_SMALL operation result or not. More...
 
PvResult RetrieveNextBuffer (PvBuffer **aBuffer, uint32_t aTimeout=0xFFFFFFFF, PvResult *aOperationResult=NULL)
 Retrieve the next acquired block. More...
 
PvResult ReleaseBuffer (PvBuffer *aBuffer)
 Return a buffer to the pipeline. More...
 
PvResult Start ()
 Starts the PvPipeline. More...
 
PvResult Stop ()
 Stops the PvPipeline. More...
 
PvResult Reset ()
 Resets the pipeline. More...
 
PvResult RegisterEventSink (PvPipelineEventSink *aEventSink)
 Register an event sink used for callbacks. More...
 
PvResult UnregisterEventSink (PvPipelineEventSink *aEventSink)
 Unregister an event sink. More...
 
uint32_t GetBufferHandlingThreadPriority () const
 Get the priority of the pipeline thread. More...
 
PvResult SetBufferHandlingThreadPriority (uint32_t aPriority)
 Set the priority of the pipeline thread. More...
 

Detailed Description

Helper class for receiving data from a GigE Vision or USB3 Vision transmitter.

The process of receiving data from a GigE Vision or USB3 Vision transmitter involves queuing buffers into the data receiver ensuring that there are always buffers available for the incoming data. PvPipeline partners with a PvStream object to allocate and push buffers into the data receiver as needed.

For further information on how PvPipeline fits in with the process of receiving data from a GigE Vision transmitter, refer to the receiving data from a transmitter page.

Constructor & Destructor Documentation

PvPipeline::PvPipeline ( PvStream aStream)

Constructor.

The PvPipeline is just a helper of a PvStream class. Your code is still the owner of the PvStream class.

Parameters
[in]aStreamThe object responsible for receiving data from a GEV transmitter; a PvStream object.

Member Function Documentation

uint32_t PvPipeline::GetBufferCount ( ) const

Get number of buffers owned and used by the pipeline.

Returns
The number of buffers.
uint32_t PvPipeline::GetBufferHandlingThreadPriority ( ) const

Get the priority of the pipeline thread.

See SetBufferHandlingThreadPriority for details about the meaning of the values returned

Returns
The priority of the thread
uint32_t PvPipeline::GetBufferSize ( ) const

Get the size for all managed buffers in bytes.

Returns
The size of managed buffers, in bytes.
bool PvPipeline::GetHandleBufferTooSmall ( ) const

Returns if the pipeline is configured to handle BUFFER_TOO_SMALL operation results automatically.

Returns
True if the pipeline handles BUFFER_TOO_SMALL operation results automatically.
See also
PvPipeline::SetHandleBufferTooSmall
uint32_t PvPipeline::GetOutputQueueSize ( ) const

Returns the number of PvBuffer objects currently available in the output queue.

PvBuffer objects are pushed into the output queue as soon as they have been populated with incoming data. PvBuffer objects are pulled out of the output queue by calling RetrieveNextBuffer. The number of buffers available in the pool managed by PvPipeline is limited to GetBufferCount. If the calling application cannot retrieve buffers at the rate that data is arriving, buffers are silently dropped. To obtain a count of dropped buffers, refer to the PipelineImagesDropped property of the PvStream parameters.

Returns
The number of PvBuffer currently available in the output queue.
bool PvPipeline::IsStarted ( )

Test if the pipeline has started.

Returns
True if the pipeline has been started (using Start); otherwise, false.
PvResult PvPipeline::RegisterEventSink ( PvPipelineEventSink aEventSink)

Register an event sink used for callbacks.

Parameters
[in]aEventSinkA pointer to the event sink.
Returns
Includes:
PvResult PvPipeline::ReleaseBuffer ( PvBuffer aBuffer)

Return a buffer to the pipeline.

IMPORTANT: all buffers retrieved through RetrieveNextBuffer must be released back to the PvPipeline. A minimum of 4 buffers must be available to the PvPipeline at all times.

Parameters
[in]aBufferA pointer to the buffer to return to the queue.
Returns
Includes:
  • PvResult::Code:OK
  • PvResult::Code:NOT_ENOUGH_MEMORY (May occur if the buffer size needs to be increased but not enough memory is available.)
PvResult PvPipeline::Reset ( )

Resets the pipeline.

Synchronously aborts the stream, waits for all buffers to be removed from the stream and queues in a fresh set of buffers. Call ONLY when it is running, otherwise it returns error

Returns
Includes:
PvResult PvPipeline::RetrieveNextBuffer ( PvBuffer **  aBuffer,
uint32_t  aTimeout = 0xFFFFFFFF,
PvResult aOperationResult = NULL 
)

Retrieve the next acquired block.

Parameters
[out]aBufferA pointer to the pointer to the buffer.
[in]aTimeoutThe maximum time, in ms, to wait for a buffer to be received. The default value is 0xFFFFFFFF milliseconds
[out]aOperationResultA pointer to the result of the acquisition operation on aBuffer, see PvBuffer::GetOperationResult.
Returns
Includes:
PvResult PvPipeline::SetBufferCount ( uint32_t  aBufferCount)

Set the number of buffers owned and used by the PvPipeline.

Buffers are added or removed as necessary until the actual buffer count matches the desired buffer count being set. During this time, the pipeline is paused temporarily.

Parameters
[in]aBufferCountThe total number of buffers.
Returns
Includes:
PvResult PvPipeline::SetBufferHandlingThreadPriority ( uint32_t  aPriority)

Set the priority of the pipeline thread.

This thread is pretty much the pipeline itself: it queues buffers in PvStream and retrieves them when they are ready, making them available in an output queue.

In Linux, the priorities supported are between 0 and 99, 99 been the highest priority as per the SCHED_FIFO scheduler specifications. If the process is not running with root priviledge, all the threads are run into the SCHED_OTHER ( scheduler 01 ) and have the same priority at 0.

In Windows, the priorities supported are between 0 and 6. The value will be translated into one of the following scheduler defines: 0 - THREAD_PRIORITY_IDLE 1 - THREAD_PRIORITY_LOWEST 2 - THREAD_PRIORITY_BELOW_NORMAL 3 - THREAD_PRIORITY_NORMAL 4 - THREAD_PRIORITY_ABOVE_NORMAL 5 - THREAD_PRIORITY_HIGHEST 6 - THREAD_PRIORITY_TIME_CRITICAL

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 GetBufferHandlingThreadPriority

Parameters
[in]aPriorityPriority to be set to the conversion threads.
Returns
Includes:
void PvPipeline::SetBufferSize ( uint32_t  aSize)

Set the optimal size of buffers being queued into the data receiver.

Each time a buffer is queued into the data receiver, it is re-allocated as necessary according to the following behavior:

  • If the buffer size is less than the require buffer size (BUFFER_TOO_SMALL) it is re-allocated.
  • If the buffer size is more than four times the required buffer size, it is re-allocated in order to save memory.

Originally the buffer size can be specified using SetBufferSize. The pipeline automatically adjusts the buffer size based on incoming buffers. As buffers are returned to the pipeline and being queued by the data receiver they may be re-allocated as described above.

Parameters
[in]aSizeThe size of the buffer, in bytes.
See also
PvBuffer::Alloc
void PvPipeline::SetHandleBufferTooSmall ( bool  aValue)

Configures whether the pipeline handles BUFFER_TOO_SMALL operation result or not.

If the pipeline is configured to handle BUFFER_TOO_SMALL operation results the buffers are automatically re-allocated and re-queued for acquisition when this condition occurs.

If the pipeline is not configured to handled BUFFER_TOO_SMALL operation results the buffers are queued in the pipeline output queue just as any other buffer and what to do with the buffer is deferred to the application using PvPipeline.

If the pipeline handles BUFFER_TOO_SMALL operation results, the PvPipelineEventSink::OnBufferTooSmall callback is invoked in order to order to query how to handle the condition. If not implemented the default behaviour is applied. See PvPipelineEventSink::OnBufferTooSmall for more information.

PvPipelineEventSink::OnBufferTooSmall is not invoked when the pipeline is not configured to handle BUFFER_TOO_SMALL operation results.

Parameters
[in]aValueIf true, the pipeline handles BUFFER_TOO_SMALL operation results automatically. If false the pipeline queues these buffers in the output queue and defers handling of these buffers to the application.
PvResult PvPipeline::Start ( )

Starts the PvPipeline.

In order to retrieve images from the stream and make them available to RetrieveNextBuffer, the pipeline must be running. This starts a thread that continually ensures that buffers are allocated and ready in the PvStream so that incoming data is captured.

Returns
Includes:
PvResult PvPipeline::Stop ( )

Stops the PvPipeline.

Returns
Includes:
PvResult PvPipeline::UnregisterEventSink ( PvPipelineEventSink aEventSink)

Unregister an event sink.

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

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

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