Interface that is used by PvSoftDeviceGEV to query and report information from a streaming source implemented by your application. More...
Public Member Functions | |
virtual | ~IPvStreamingChannelSource () |
Virtual destructor. | |
virtual uint32_t | GetWidth () const =0 |
Returns the current image width. More... | |
virtual uint32_t | GetHeight () const =0 |
Returns the current image height. More... | |
virtual uint32_t | GetOffsetX () const =0 |
Returns the current image offset X. More... | |
virtual uint32_t | GetOffsetY () const =0 |
Returns the current image offset Y. More... | |
virtual PvPixelType | GetPixelType () const =0 |
Returns the current pixel type. More... | |
virtual void | GetWidthInfo (uint32_t &aMin, uint32_t &aMax, uint32_t &aInc) const =0 |
Returns the stream channel width attributes. More... | |
virtual void | GetHeightInfo (uint32_t &aMin, uint32_t &aMax, uint32_t &aInc) const =0 |
Returns the stream channel height attributes. More... | |
virtual uint32_t | GetChunksSize () const =0 |
Gets the stream channel chunk size attributes. More... | |
virtual uint32_t | GetPayloadSize () const =0 |
Stream channel payload size in bytes. Return zero to have it inferred from width, height and pixel format. More... | |
virtual PvScanType | GetScanType () const =0 |
Returns the scan type that is used by the streaming source. More... | |
virtual bool | GetChunkModeActive () const =0 |
Indicates whether the current master chunk mode is active. More... | |
virtual bool | GetChunkEnable (uint32_t aChunkID) const =0 |
Returns the current chunk enabled state. More... | |
virtual PvResult | GetSupportedPixelType (int aIndex, PvPixelType &aPixelType) const =0 |
Obtains an index of supported pixel types. Used at PvSoftDeviceGEV::Start time to create the GenICam XML of the device. More... | |
virtual PvResult | GetSupportedChunk (int aIndex, uint32_t &aID, PvString &aName) const =0 |
Returns the indexed supported chunk type. Used at PvSoftDeviceGEV::Start time to create the GenICam XML of the device. More... | |
virtual PvResult | SetWidth (uint32_t aWidth)=0 |
Request from the PvSoftDeviceGEV to change the image width. More... | |
virtual PvResult | SetHeight (uint32_t aHeight)=0 |
Request from the PvSoftDeviceGEV to change the image height. More... | |
virtual PvResult | SetOffsetX (uint32_t aOffsetX)=0 |
Request from the PvSoftDeviceGEV to change the image offset X. More... | |
virtual PvResult | SetOffsetY (uint32_t aOffsetY)=0 |
Request from the PvSoftDeviceGEV to change the image offset Y. More... | |
virtual PvResult | SetPixelType (PvPixelType aPixelType)=0 |
Request from the PvSoftDeviceGEV to change the image pixel type. More... | |
virtual PvResult | SetChunkModeActive (bool aEnabled)=0 |
Set the master chunk mode active state. More... | |
virtual PvResult | SetChunkEnable (uint32_t aChunkID, bool aEnabled)=0 |
Sets the chunk enabled state for a specific chunk type. More... | |
virtual void | OnOpen (const PvString &aDestIP, uint16_t aDestPort)=0 |
Notification from the PvSoftDeviceGEV that this streaming channel has been opened. More... | |
virtual void | OnClose ()=0 |
Notification from the PvSoftDeviceGEV that this streaming channel has been closed. | |
virtual void | OnStreamingStart ()=0 |
Notification that the GigE Vision controller has requested that the device start streaming on this channel. | |
virtual void | OnStreamingStop ()=0 |
Notification that the GigE Vision controller has requested that the device stop streaming on this channel. | |
virtual PvBuffer * | AllocBuffer ()=0 |
Request by the PvSoftDeviceGEV to allocate a PvBuffer. More... | |
virtual void | FreeBuffer (PvBuffer *aBuffer)=0 |
Request by the PvSoftDeviceGEV to free or release a buffer allocated with AllocBuffer. More... | |
virtual PvResult | QueueBuffer (PvBuffer *aBuffer)=0 |
Request by the PvSoftDeviceGEV to queue a buffer for acquisition. More... | |
virtual PvResult | RetrieveBuffer (PvBuffer **aBuffer)=0 |
Request by the PvSoftDeviceGEV to retrieve a buffer from the streaming source. More... | |
virtual void | AbortQueuedBuffers ()=0 |
Request by the PvSoftDeviceGEV to abort all buffers queued for acquisition. More... | |
virtual void | CreateRegisters (IPvRegisterMap *aRegisterMap, IPvRegisterFactory *aFactory) |
When called, the streaming channel source should create its custom registers if they are needed. More... | |
virtual void | CreateGenApiFeatures (IPvRegisterMap *aRegisterMap, IPvGenApiFactory *aFactory) |
When called, the streaming channel source should create its custom GenApi parameters if they are needed. More... | |
virtual bool | IsPayloadTypeSupported (PvPayloadType aPayloadType) |
When called, the streaming source has to return whether the specificed payload type is supported or not. More... | |
virtual void | SetMultiPartAllowed (bool aAllowed) |
Sets whether the streaming source is allowed or not, but not forced, to transmit multi-part data. More... | |
virtual PvResult | SetTestPayloadFormatMode (PvPayloadType aPayloadType) |
When called, the streaming source has to ensure it can stream buffers of the specified payload type. More... | |
Interface that is used by PvSoftDeviceGEV to query and report information from a streaming source implemented by your application.
For the application to provide a streaming source to your software-based GigE Vision Device, inherit one of your classes from IPvStreamingChannelSource, implement all of the methods, instantiate an object from your class, and pass a pointer to your class to PvSoftDeviceGEV::AddStream.
The GigE Vision Device will use this interface to query the application about stream capabilities and to report streaming events, such as acquisition start and stop. The GigE Vision Device also uses this interface to manage streaming data.
To properly report the PayloadSize GenApi parameter, your application must provide the GigE Vision Device with the width, height, pixel format, and data chunk size values using the GetWidth, GetHeight, GetPixelFormat, and GetChunksSize methods.
You can hardcode the supported chunk size by returning the required chunk size using GetChunksSize. You could also provide more information about the supported chunk types using GetSupportedChunk. Doing so will allow the GigE Vision Device to properly populate the ChunkSelector of its GenApi interface to let the user decide which chunks it should support. The streaming source should decide whether or not to append a specific chunk type by looking at whether the master chunk active mode is enabled AND that the specific chunk type is enabled.
It is possible to create streaming channel source custom registers and GenApi parameters. See IPvStreamingChannelSource::CreateGenApiFeatures and IPvStreamingChannelSource::CreateRegisters for more information. You should create streaming channel source GenApi feature and registers for source-specific features like deinterlacing, gain, exposure time. Look at IPvSoftDeviceGEVEventSink::OnCreateCustomRegisters and IPvSoftDeviceGEVEventSink::OnCreateCustomGenApiFeatures to create device-scope features. Note that chunks and messaging channel GenApi parameters should always be created from IPvSoftDeviceGEVEventSink and be at the device-scope.
Here is what a typical streaming session would look like when it comes to buffer management:
|
pure virtual |
Request by the PvSoftDeviceGEV to abort all buffers queued for acquisition.
This method should block until acquisition has been aborted or canceled for all buffers provided by QueueBuffer that have not yet been retrieved with RetrievedBuffer.
When this method returns, it should be possible to call RetrieveBuffer for all aborted buffers.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request by the PvSoftDeviceGEV to allocate a PvBuffer.
On initialization, the PvSoftDeviceGEV will call this method, asking the application to allocate buffers that will be used for image acquisition and transmission. The application should return buffers until it has reached the desired number of buffers it wants to use for streaming and then return NULL.
The more buffers you use, the more buffers you can have queued in the application for image acquisition and the more buffers you can leave in the transmission output queue for packet resend. The downside of using more buffers is increased memory usage.
Buffers returned on AllocBuffer calls should be unique: you should not return the same buffer more than once.
A maximum of 64 buffers can be used by one streaming channel of the PvSoftDeviceGEV. If your application does not return NULL on the 64th buffer, AllocBuffer will not be called a 64th time.
Implemented in PvStreamingChannelSourceDefault.
|
inlinevirtual |
When called, the streaming channel source should create its custom GenApi parameters if they are needed.
Create GenApi features from this callback if the feature is associated with a streaming channel source. For global-device, non streaming channel source features use IPvSoftDeviceGEVEventSink::OnCreateCustomGenApiFeatures instead.
In a multi-source application, GenApi features created by a streaming channel source will only be available when the SourceSelector is set to the streaming channel source that created the feature.
If FeatureXYX is created by Source0 and Source1 but not by Source2, the feature will only be available in the GenApi interface when SourceSelector is set to Source0 or Source1.
If integers with the same name are created for more than one source but with source-specific minimum, maximum and increment attributes, these attributes will be handled by GenICam SwissKnife operators in the GenICam XML so they are dynamically adjusted based on the value of SourceSelector. The same applies to float maximum and minimum.
If enumerations with the same name are created for more than one source but with different enum entries, they will be added to the GenICam XML file of the device in way that the correct enum entries should be available for the enum features based on the current SourceSelector value:
Creating features of the same name but different types is not supported. Attempting to do so should have the PvSoftDeviceGEV::Start call failing with an appropriate error description.
GenApi features created for a streaming channel source should use registers unique to this streaming channel source. If you have a source class MySource that creates registers and features, it should still create unique register having their own unique addresses. They should however use the same parameter name. The GenApi parameters created by MySource should use the right register for the source instance. The complexity of overlapping per-source feature name is handled by PvSoftDeviceGEV when creating the GenICam XML file from PvSoftDeviceGEV::Start.
The exception to this rule is selectors: if selectors are created at the streaming source level they must all use the same register, sharing the same register address.
Custom source-specific GenApi features creation occurs AFTER custom source-specific registers creation, inside the PvSoftDeviceGEV::Start call.
[in] | aRegisterMap | The register map of the device. |
[in] | aFactory | GenApi factory used to create the new GenApi features. |
Reimplemented in PvStreamingChannelSourceDefault.
|
inlinevirtual |
When called, the streaming channel source should create its custom registers if they are needed.
To create source-specific custom registers in your application, implement the CreateRegisters method of the IPvStreamingChannelSource interface.
Custom source-specific register creation occurs BEFORE custom source-specific GenApi features creation, inside the PvSoftDeviceGEV::Start call.
If more than one streaming channel source is created from the same class, you must make sure its registers are still unique: RegisterXYZ in Source0 and Source1 should not have the same address. It is also recommended to assign them unique names like RegisterXYZ0 and RegisterXYZ1.
[in] | aRegisterMap | The register map of the device. |
[in] | aFactory | Register factory used to create the new registers. |
Reimplemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request by the PvSoftDeviceGEV to free or release a buffer allocated with AllocBuffer.
You should not delete or free any PvBuffer provided by the AllocBuffer method. FreeBuffer will be called for each buffer created with AllocBuffer when PvSoftDeviceGEV::Stop is called.
[in] | aBuffer | Buffer to free. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current chunk enabled state.
The application must implement this method and return the current chunk enabled state for the specified chunk ID. The streaming source should maintain an enabled/disabled state for each chunk type that it supports.
The application should append the chunk represented by the specified chunk ID if it is enabled and if the master chunk mode (see GetChunkModeActive) is true.
[in] | aChunkID | Chunk ID. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Indicates whether the current master chunk mode is active.
The application must implement this method and return the current master chunk mode state. Return false as a hardcoded value if chunks are not supported by the streaming source.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Gets the stream channel chunk size attributes.
When using data chunks, it is important to report the chunk data size when queried through this method.
The chunk data size needs to be taken into account when reporting the PayloadSize GenICam parameter to the GigE Vision controller, so it can properly allocate its buffer for streaming without forced buffer re-allocation.
The size reported must for each chunk adds 4 bytes for the chunk ID and another 4 bytes for the chunk length fields. If you have a chunk that is 64 bytes long and it is your only data chunk, you need to report 64 + 4 + 4 (72 bytes) when GetChunksSize is called.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current image height.
Your application must implement this method and return the current image height when invoked.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the stream channel height attributes.
When using the GigE Vision Device as a transmitter, the Height parameter is automatically added to the device's GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Height parameter.
[out] | aMin | Height minimum. |
[out] | aMax | Height maximum. |
[out] | aInc | Height increment. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current image offset X.
Your application must implement this method and return the current image offset X when invoked.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current image offset Y.
Your application must implement this method and return the current image offset Y when invoked.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Stream channel payload size in bytes. Return zero to have it inferred from width, height and pixel format.
If not using image streams (raw data, multi-part, etc.) use implement the GetPayloadSize method and return the payload size for the current streaming channel source configuration. If GetPayloadSize returns 0 the payload size will be inferred from the width, height, pixel format and data chunk size.
When using multi-part, return the sum of the maximum size of all parts plus data chunk.
When payload size is not zero, the payload size value is simply used as provided. Nothing is added to it, not even data chunk size.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current pixel type.
Your application must implement this method and return the current image pixel type when invoked.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the scan type that is used by the streaming source.
Return PvScanTypeArea if your image source is areascan or PvScanTypeLine if your image source is linescan.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the indexed supported chunk type. Used at PvSoftDeviceGEV::Start time to create the GenICam XML of the device.
This method is used by the PvSoftDeviceGEV to query the application about the supported chunk types for this streaming channel.
The PvSoftDeviceGEV will query the application through this stream interface for all supported chunk types. It will start at index 0 and then increase until something other than PvResult::Code::OK is returned.
The information retrieved through this method is used to populate the chunk selector, allowing the GigE Vision controller to enable or disable each chunk type individually.
If the application supports ChunkSample (ID 0x4001) and ChunkHistogram (ID 0x4002) it needs to handle request to GetSupportedChunk as follows:
[in] | aIndex | Index of the chunk type to return. |
[out] | aID | ID of the chunk type requested by aIndex. |
[out] | aName | Name of the chunk type requested by aIndex. Should always use the "Chunk" prefix for GenICam SFNC compliance. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Obtains an index of supported pixel types. Used at PvSoftDeviceGEV::Start time to create the GenICam XML of the device.
This method is used by the PvSoftDeviceGEV to query the application about the supported pixel types for the streaming channel.
The PvSoftDeviceGEV will query the application using this stream interface for all supported pixel types. It will start at index 0 and then increase until something other than PvResult::Code::OK is returned.
If the application supports Mono8, BayerRG8, and RGBa8 it needs to handle the request to GetSupportedPixelType, as follows:
[in] | aIndex | Index of the pixel type to return. |
[out] | aPixelType | PvPixelType requested by aIndex. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the current image width.
Your application must implement this method and return the current image width when invoked.
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Returns the stream channel width attributes.
When using the GigE Vision Device as a transmitter, the Width parameter is automatically added to the device's GenICam XML file. This method is used to query the minimum, maximum, and increment attributes for the Width parameter.
[out] | aMin | Width minimum. |
[out] | aMax | Width maximum. |
[out] | aInc | Width increment. |
Implemented in PvStreamingChannelSourceDefault.
|
inlinevirtual |
When called, the streaming source has to return whether the specificed payload type is supported or not.
Return true if the streaming source exlusively or non-exclusively can stream buffers of the specified payload type. A default implementation is provided for this method which returns false.
This method must be implemented and returning true for aPayloadType being equal to PvPayloadTypeMultiPart when multi-part is supported by the streaming source.
See SetTestPayloadFormatMode and SetMultiPartAllowed for more information on propertly supporting the multi-part payload type.
aPayloadType | [in] The payload type for which support is queried. |
Reimplemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Notification from the PvSoftDeviceGEV that this streaming channel has been opened.
[in] | aDestIP | IP address of the stream destination as a string in the "192.168.138.115" format (SCDA). |
[in] | aDestPort | UDP port of the stream destination (SCP). |
Implemented in PvStreamingChannelSourceDefault.
Request by the PvSoftDeviceGEV to queue a buffer for acquisition.
If the application can accept the buffer and queue it for image acquisition, it returns success. If the acquisition queue or pipeline is full, return a PvResult error code.
[in] | aBuffer | Buffer to queue for image acquisition. |
Request by the PvSoftDeviceGEV to retrieve a buffer from the streaming source.
During acquisition, buffers retrieved with this method will contain valid image data and are going to be transmitted using the GVSP protocol. This method is also used to retrieve queued buffers after calling AbortQueuedBuffers.
If no image is immediately available, we recommend that you wait until an image is available in this method to allow the acquisition thread to wait efficiently for a new image. If getting a new image can take a long time, your application should wait small chunks of time (10, 20, or 50 ms) to prevent deadlocking the acquisition thread and to allow the PvSoftDeviceGEV to stop streaming gracefully.
[in] | aBuffer | A pointer to a pointer to a buffer: set to a pointer to the PvBuffer being retrieved. |
|
pure virtual |
Sets the chunk enabled state for a specific chunk type.
The streaming source should append a specific chunk type to its streaming data when both the GetChunkModeActive (master chunk mode) and GetChunkEnable for this specific chunk type are true.
[in] | aChunkID | Chunk ID of the chunk type to enable or disable. |
[in] | aEnabled | True to enable the chunk type, false to disable it. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Set the master chunk mode active state.
The streaming source should append a specific chunk type to its streaming data when both the GetChunkModeActive (master chunk mode) and GetChunkEnable for this specific chunk type are true.
[in] | aEnabled | True to enable chunk mode for this streaming channel, false to disable it. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request from the PvSoftDeviceGEV to change the image height.
The PvSoftDeviceGEV will call SetHeight when the Height GenApi parameter or the underlying register is changed by the GigE Vision controller.
To accept the new height, return PvResult::Code::OK and update your streaming code to use the new height.
[in] | aHeight | New image height. |
Implemented in PvStreamingChannelSourceDefault.
|
inlinevirtual |
Sets whether the streaming source is allowed or not, but not forced, to transmit multi-part data.
Streaming sources supporting multi-part data transmission must support non-multi-part streaming by default. All devices starting in a mode where multi-part is not allowed. The GigE Vision controller must unlock the multi-part capability of a GVSP streaming channel using either the SCCx and SCCFGx bootstrap registers or the GevSCCFGMultiPartEnabled GenApi parameter.
The GevSCCFGMultiPartEnabled GenApi parameter is automatically added to the GenICam XML file of a PvSoftDeviceGEV device when IsPayloadTypeSupported returns true when prompted with PvPayloadTypeMultiPart.
See IsPayloadTypeSupported and SetTestPayloadFormatMode for more information on propertly supporting the multi-part payload type.
aAllowed | [in] True if multi-part is allowed. |
Reimplemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request from the PvSoftDeviceGEV to change the image offset X.
To accept the new offset X, return PvResult::Code::OK and update your streaming code to use the new value.
[in] | aOffsetX | New image offset X. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request from the PvSoftDeviceGEV to change the image offset Y.
To accept the new offset Y, return PvResult::Code::OK and update your streaming code to use the new value.
[in] | aOffsetY | New image offset Y. |
Implemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request from the PvSoftDeviceGEV to change the image pixel type.
The PvSoftDeviceGEV will call SetPixelType when the PixelType GenApi parameter or the underlying register is changed by the GigE Vision controller.
To accept the new pixel type, return PvResult::Code::OK and update your streaming code to use the new pixel type.
[in] | aPixelType | New image pixel type. |
Implemented in PvStreamingChannelSourceDefault.
|
inlinevirtual |
When called, the streaming source has to ensure it can stream buffers of the specified payload type.
The GigE Vision Validation Framework has to be able to set the device in a functional streaming mode for some payload types (currently only multi-part with more to come) in order to properly validate the device.
This method must be implemented and for aPayloadType being PvPayloadTypeMultiPart when multi-part is supported by the streaming source. The streaming source must be able to configure itself in a mode where it will be able to stream data for certification with the GigE Vision Validation Framework.
Of course, this method will only be called on a streaming source for payload type that have been reported as supported with IsPayloadTypeSupported.
How to prepare your multi-source device source for GigE Vision Validation Framework validation:
See the SoftDeviceGEVMultiPart C++ sample for an example of how to implement this method, SetMultiPartAllowed, and IsPayloadTypeSupported.
[in] | aPayloadType | Payload type to prepare test for. PvPayloadTypeNone sets the device back in normal operation mode. |
Reimplemented in PvStreamingChannelSourceDefault.
|
pure virtual |
Request from the PvSoftDeviceGEV to change the image width.
The PvSoftDeviceGEV will call SetWidth when the Width GenApi parameter or the underlying register is changed by the GigE Vision controller.
To accept the new width, return PvResult::Code::OK and update your streaming code to use the new width.
[in] | aWidth | New image width. |
Implemented in PvStreamingChannelSourceDefault.
Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com