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... | |
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.
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.
[in] | aStream | The object responsible for receiving data from a GEV transmitter; a PvStream object. |
uint32_t PvPipeline::GetBufferCount | ( | ) | const |
Get number of buffers owned and used by the pipeline.
uint32_t PvPipeline::GetBufferHandlingThreadPriority | ( | ) | const |
Get the priority of the pipeline thread.
See SetBufferHandlingThreadPriority for details about the meaning of the values returned
uint32_t PvPipeline::GetBufferSize | ( | ) | const |
Get the size for all managed buffers in bytes.
bool PvPipeline::GetHandleBufferTooSmall | ( | ) | const |
Returns if the pipeline is configured to handle BUFFER_TOO_SMALL operation results automatically.
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.
bool PvPipeline::IsStarted | ( | ) |
Test if the pipeline has started.
PvResult PvPipeline::RegisterEventSink | ( | PvPipelineEventSink * | aEventSink | ) |
Register an event sink used for callbacks.
[in] | aEventSink | A pointer to the event sink. |
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.
[in] | aBuffer | A pointer to the buffer to return to the queue. |
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
PvResult PvPipeline::RetrieveNextBuffer | ( | PvBuffer ** | aBuffer, |
uint32_t | aTimeout = 0xFFFFFFFF , |
||
PvResult * | aOperationResult = NULL |
||
) |
Retrieve the next acquired block.
[out] | aBuffer | A pointer to the pointer to the buffer. |
[in] | aTimeout | The maximum time, in ms, to wait for a buffer to be received. The default value is 0xFFFFFFFF milliseconds |
[out] | aOperationResult | A pointer to the result of the acquisition operation on aBuffer, see PvBuffer::GetOperationResult. |
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.
[in] | aBufferCount | The total number of buffers. |
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
[in] | aPriority | Priority to be set to the conversion threads. |
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:
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.
[in] | aSize | The size of the buffer, in bytes. |
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.
[in] | aValue | If 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.
PvResult PvPipeline::Stop | ( | ) |
Stops the PvPipeline.
PvResult PvPipeline::UnregisterEventSink | ( | PvPipelineEventSink * | aEventSink | ) |
Unregister an event sink.
[in] | aEventSink | A pointer to the event sink. |
Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com