COM interface to the eBUS SDK DirectShow Source filter, PvDSSource. More...
Public Member Functions | |
HRESULT | get_Role (int *role) |
Filter role read method. More... | |
HRESULT | put_Role (int role) |
Filter role write method. More... | |
HRESULT | get_UnicastPort (int *port) |
Filter unicast port read method. More... | |
HRESULT | put_UnicastPort (int port) |
Filter unicast port write method. More... | |
HRESULT | get_MulticastIP (BSTR *ip) |
Filter multicast group IP address read method. More... | |
HRESULT | put_MulticastIP (BSTR ip) |
Filter multicast group IP address write method. More... | |
HRESULT | get_MulticastPort (int *port) |
Filter multicast group port read method. More... | |
HRESULT | put_MulticastPort (int port) |
Multicast group port to join where the streaming data from the GigE Vision device is received with the multicast role. More... | |
HRESULT | get_DiagnosticEnabled (BOOL *enabled) |
Filter diagnostic enabled read method. More... | |
HRESULT | put_DiagnosticEnabled (BOOL enabled) |
Filter diagnostic enabled write method. More... | |
HRESULT | get_DeviceID (BSTR *deviceid) |
Filter device ID read method. More... | |
HRESULT | put_DeviceID (BSTR deviceid) |
Device ID write method. More... | |
HRESULT | DisconnectDevice () |
Disconnects the filter from the device. More... | |
HRESULT | ConnectIfNeeded () |
Connects the filter to the device. More... | |
HRESULT | get_SourceCount (int *sourcecount) |
How many sources are available on the device currently controlled. More... | |
HRESULT | get_SourceName (int aIndex, BSTR *sourcename) |
Name of one of the sources of the device currently controlled. More... | |
HRESULT | get_Source (BSTR *source) |
Name of the source currently selected on the device read method. More... | |
HRESULT | put_Source (BSTR source) |
Name of the source currently selected on the device write method. More... | |
HRESULT | get_Channel (int *channel) |
Streaming channel read method. More... | |
HRESULT | put_Channel (int channel) |
Streaming channel write method. More... | |
HRESULT | get_BufferCount (int *count) |
Buffer count read method. More... | |
HRESULT | put_BufferCount (int count) |
Buffer count write method. More... | |
HRESULT | get_DefaultBufferSize (int *size) |
Default buffer size read method. More... | |
HRESULT | put_DefaultBufferSize (int size) |
Default buffer size write method. More... | |
HRESULT | get_DropThreshold (int *threshold) |
Drop threshold read method. More... | |
HRESULT | put_DropThreshold (int threshold) |
Drop threshold write method. More... | |
HRESULT | get_Width (int *width) |
Filter image format width read method. More... | |
HRESULT | put_Width (int width) |
Filter image format width write method. More... | |
HRESULT | get_Height (int *height) |
Filter image format height read method. More... | |
HRESULT | put_Height (int height) |
Filter image format height write method. More... | |
HRESULT | get_ParametersSelector (int *selector) |
Currently active GenICam interface read method. More... | |
HRESULT | put_ParametersSelector (int selector) |
Currently active GenICam interface write method. More... | |
HRESULT | get_ParametersAvailable (BOOL *available) |
Currently active GenICam interface availability method. More... | |
HRESULT | get_ParameterCount (int *count) |
Currently active GenICam interface parameter count method. More... | |
HRESULT | get_ParameterName (int index, BSTR *name) |
Name of the parameter at a specific index in the currently selected GenICam interface. More... | |
HRESULT | get_ParameterCategory (BSTR name, BSTR *category) |
Category of a parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterValue (BSTR name, BSTR *value) |
Method used to read the value of a specific parameter as a string for the currently selected GenICam interface. More... | |
HRESULT | put_ParameterValue (BSTR name, BSTR value, BSTR *message) |
Method used to write the value of a specific parameter as a string for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterType (BSTR name, BSTR *type) |
Type of a parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterAccess (THIS_ BSTR name, BOOL *available, BOOL *readable, BOOL *writable) |
Current access mode for a parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | ParameterExecute (BSTR name, BSTR *message) |
Executes a command parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterPossibleValueCount (BSTR name, int *count) |
Count of possible values for an enum or Boolean parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterPossibleValue (BSTR name, int index, BSTR *value) |
One of the possible values for an enum or Boolean parameter identified by its name for the currently selected GenICam interface. More... | |
HRESULT | get_ParameterVisibility (BSTR name, int *visibility) |
Visibility of a parameter identified by its name for the currently selected GenICam interface. More... | |
COM interface to the eBUS SDK DirectShow Source filter, PvDSSource.
When you have instantiated a PvDSSource DirectShow filter, you can retrieve the IPvDSSource configuration interface by using QueryInterface on any interface of the object. Remember to always release interfaces when finished with them to avoid resource leaks.
The documentation of this interface assumes good knowledge of DirectShow by the reader.
To configure (and use) your PvDSSource filter, typically:
From prototyping, you can interact with the filter using GraphEdit:
It is important to connect the PvDSSource filter to the device BEFORE connecting it to other DirectShow filters. Doing so will adjust the filter width, height and other key parameters that are expected to stay fixed by filters you connect to your PvDSSource filter.
The PvDSSource filter supports pins reconfiguration when its configuration changes. However we found through our experiments that not all filters like having their configuration changed on the fly. It is recommend to design for changing width and height of the source when not connected to an other filter.
If you are using the unicast or multicast mode (GigE Vision only) you should manually (or programmatically) set the width and the height of the PvDSSource filter before connecting it to other filters.
The GUID of the filter is defined as IID_IPvDSSource {7D692BC5-05D4-4032-A581-B7FA1C202825}. You can include it in your own project through PvDSSourceUIDs.h or redefine it from this GUID.
You can look at the eBUS SDK DirectShowDisplay (available for C++ and C#) samples for examples of how to use the PvDSSource filter to link GigE Vision or USB3 Vision image streams to a DirectShow display.
The filter can be used in three different modes, or roles.
The filter takes control of the device and receives images from the same device. This mode can be used with GigE Vision devices and USB3 Vision devices. To configure the filter for this mode, just assign the device ID. With this mode, the filter is responsible of controlling when the device starts and stops streaming.
The filter is just a data receiver that receives images from a GigE Vision device. The device is typically controlled by a PvDeviceGEV which can exist in the same process, a different process or even a different computer. Some devices in autonomous streaming modes could also be used. To configure the filter for this mode, assign the device ID and and unicast port. Make sure your device is configured to stream to your local interface on this port. With this mode, you are responsible of making sure the' device starts and stops streaming. The filter is just a passive receiver.
Just like unicast mode but instead of the data being sent to a unique IP/port address, the data is being multicast to a group joined by the filter. With this mode, more than one DirectShow filter or GigE Vision receiver can listen in on transmitted images. To use this mode, assign the device ID, multicast group address and port. Make sure your device is configured to stream to this multicast group. Just like the unicast mode, the filter is just a passive receiver: you are responsible of making sure it starts and stops streaming.
The PvDSSource filter implements the IPersistStream COM interface. This enables saving the filter configuration to a DirectShow graph persistence file. When the file is read back the filter is automatically configured and connected to the device it was using when its state was persisted. All filter configuration parameter are persisted. GenICam interfaces (communication, control and stream) are also persisted if applicable.
This enables the user from saving a graph state from GraphEdit. This capability can also be used programmatically using the DirectShow graph COM interface.
The filter exposes the GenICam interfaces of some internal components: the controller communication parameters (control mode), the device parameters (control mode) and the stream parameters (all modes).
The API for these GenICam interfaces has been simplified. It should be enough for basic control and statistics monitoring.
The parameter selector property is used to select which GenICam interface is being interacted with. With one GenICam interface selected it is possible to enumerate all parameters, retrieve some properties and get/set the parameter values using simple strings - as would be expected from the PvGenParameter or GenApi "to string" and "from string" capabilities where the value of various parameter types is abstracted to simple strings.
As an example of what can be achieved using the GenICam interface of IPvDSSource, the simplified GenICam browser of the PvDSSource filter is using that API and nothing else.
HRESULT IPvDSSource::ConnectIfNeeded | ( | ) |
Connects the filter to the device.
Calling this method connects the filter to the device if connected device or the way it is connected to does not match the current filter configuration. If the device needs to be connected in a different way the device is first disconnected and then connection is re-established.
The device that is connected is defined using put_DeviceID. How the device is connected is defined by put_Role and role related parameters, the streaming channel and/or the selected source.
Whenever the filter configuration changes in a way that can affect which device or how the device is connected you should call this method to make sure the changes are applied. put_DeviceID, put_Source, put_Channel, put_Role, put_UnicastPort, put_MulticastIP, put_MulticastPort can affect connectivity.
HRESULT IPvDSSource::DisconnectDevice | ( | ) |
Disconnects the filter from the device.
HRESULT IPvDSSource::get_BufferCount | ( | int * | count | ) |
Buffer count read method.
See put_BufferCount.
[out] | count | Buffer count. |
HRESULT IPvDSSource::get_Channel | ( | int * | channel | ) |
Streaming channel read method.
See put_Channel.
[out] | channel | Streaming channel. |
HRESULT IPvDSSource::get_DefaultBufferSize | ( | int * | size | ) |
Default buffer size read method.
[out] | size | Default buffer size. |
HRESULT IPvDSSource::get_DeviceID | ( | BSTR * | deviceid | ) |
Filter device ID read method.
[out] | deviceid | Filter device ID. |
HRESULT IPvDSSource::get_DiagnosticEnabled | ( | BOOL * | enabled | ) |
Filter diagnostic enabled read method.
[out] | enabled | Filter diagnostic enabled state. |
HRESULT IPvDSSource::get_DropThreshold | ( | int * | threshold | ) |
Drop threshold read method.
See put_DropThreshold.
[out] | threshold | Drop threshold. |
HRESULT IPvDSSource::get_Height | ( | int * | height | ) |
HRESULT IPvDSSource::get_MulticastIP | ( | BSTR * | ip | ) |
Filter multicast group IP address read method.
See put_MulticastIP.
[out] | ip | Filter multicast IP address. |
HRESULT IPvDSSource::get_MulticastPort | ( | int * | port | ) |
Filter multicast group port read method.
See put_MulticastPort.
[out] | port | Filter multicast port. |
HRESULT IPvDSSource::get_ParameterAccess | ( | THIS_ BSTR | name, |
BOOL * | available, | ||
BOOL * | readable, | ||
BOOL * | writable | ||
) |
Current access mode for a parameter identified by its name for the currently selected GenICam interface.
[in] | name | Name of the parameter. |
[out] | available | True if the parameter is currently available. |
[out] | readable | True if the parameter is currently readable. |
[out] | writable | True if the parameter is currently writable. |
HRESULT IPvDSSource::get_ParameterCategory | ( | BSTR | name, |
BSTR * | category | ||
) |
Category of a parameter identified by its name for the currently selected GenICam interface.
See PvGenParameterArray::GetCategory for more information.
[in] | name | Name of the parameter. |
[out] | category | Category of the parameter. |
HRESULT IPvDSSource::get_ParameterCount | ( | int * | count | ) |
Currently active GenICam interface parameter count method.
Use this method to obtain how much parameters are available in the currently selected GenICam interface of the filter. This method can be used to iterate through all GenICam parameters using get_ParameterName.
[out] | count | Parameter count of the currently selected GenICam interface. |
HRESULT IPvDSSource::get_ParameterName | ( | int | index, |
BSTR * | name | ||
) |
Name of the parameter at a specific index in the currently selected GenICam interface.
[out] | index | Index of the parameter |
[out] | name | Name of the parameter. |
HRESULT IPvDSSource::get_ParameterPossibleValue | ( | BSTR | name, |
int | index, | ||
BSTR * | value | ||
) |
One of the possible values for an enum or Boolean parameter identified by its name for the currently selected GenICam interface.
See get_ParameterPossibleValueCount.
[in] | name | Name of the parameter. |
[in] | index | Index of the possible value. |
[out] | value | Requested possible value. |
HRESULT IPvDSSource::get_ParameterPossibleValueCount | ( | BSTR | name, |
int * | count | ||
) |
Count of possible values for an enum or Boolean parameter identified by its name for the currently selected GenICam interface.
This method only applies to enum and Boolean parameters. It is typically used with get_ParameterPossibleValue in order to populate a combobox with all possible values the parameter can take.
[in] | name | Name of the parameter. |
[out] | count | Possible value count. |
HRESULT IPvDSSource::get_ParametersAvailable | ( | BOOL * | available | ) |
Currently active GenICam interface availability method.
If the active/selected GenICam interface is:
[out] | available | True if the currently selected GenICam interface is active. |
HRESULT IPvDSSource::get_ParametersSelector | ( | int * | selector | ) |
Currently active GenICam interface read method.
[out] | selector | Currently active GenICam interface. |
HRESULT IPvDSSource::get_ParameterType | ( | BSTR | name, |
BSTR * | type | ||
) |
Type of a parameter identified by its name for the currently selected GenICam interface.
Possible values:
[in] | name | Name of the parameter. |
[out] | type | String representing the parameter type. |
HRESULT IPvDSSource::get_ParameterValue | ( | BSTR | name, |
BSTR * | value | ||
) |
Method used to read the value of a specific parameter as a string for the currently selected GenICam interface.
See PvGenParameterArray::FromString for more information.
[in] | name | Name of the parameter. |
[out] | value | Value of the parameter. |
HRESULT IPvDSSource::get_ParameterVisibility | ( | BSTR | name, |
int * | visibility | ||
) |
Visibility of a parameter identified by its name for the currently selected GenICam interface.
The visibility of the parameter is expressed as an integer:
See get_ParameterPossibleValueCount.
[in] | name | Name of the parameter. |
[out] | visibility | Visibility of the parameter. |
HRESULT IPvDSSource::get_Role | ( | int * | role | ) |
HRESULT IPvDSSource::get_Source | ( | BSTR * | source | ) |
Name of the source currently selected on the device read method.
See put_Source.
[out] | source | Name of the active source. |
HRESULT IPvDSSource::get_SourceCount | ( | int * | sourcecount | ) |
How many sources are available on the device currently controlled.
This parameter and get_SourceName can be used to retrieve all available sources and present the user with a list or combo box where the active source can be selected.
See put_Source.
[out] | sourcecount | How many sources the currently controlled device has. |
HRESULT IPvDSSource::get_SourceName | ( | int | aIndex, |
BSTR * | sourcename | ||
) |
Name of one of the sources of the device currently controlled.
See put_Source.
[in] | aIndex | Zero-based index of the source. |
[out] | sourcename | Name of the source. |
HRESULT IPvDSSource::get_UnicastPort | ( | int * | port | ) |
Filter unicast port read method.
See put_UnicastPort.
[out] | port | Filter unicast port. |
HRESULT IPvDSSource::get_Width | ( | int * | width | ) |
Filter image format width read method.
The user can set the image format width using put_Width but this value can automatically be adjusted when the controlled device is connected or when the width is being changed on the controlled device.
See put_Width.
[out] | width | Filter image format width. |
HRESULT IPvDSSource::ParameterExecute | ( | BSTR | name, |
BSTR * | message | ||
) |
Executes a command parameter identified by its name for the currently selected GenICam interface.
[in] | name | Name of the parameter. |
[out] | message | On failure, contains the GenICam/GenApi error message. |
HRESULT IPvDSSource::put_BufferCount | ( | int | count | ) |
Buffer count write method.
This parameter controls how many image buffers are used internally by the eBUS SDK PvDSSource filter when receiving data.
Setting the buffer count does immediately changes the effective buffer count. ConnectIfNeeded must be called in order to apply the change.
[in] | count | buffer count. |
HRESULT IPvDSSource::put_Channel | ( | int | channel | ) |
Streaming channel write method.
This parameter controls which streaming channel is used when receiving data with the unicast or multicast roles. It is not applicable with the controller and data-receiver role when it is automatically configured.
It is highly recommended to set this parameter when using unicast or multicast roles. Streaming will still work if not defined but resend packets may not work as expected if the channel is different than 0.
Setting the channel does immediately make the new channel active. ConnectIfNeeded must be called in order to apply the change.
[in] | channel | Streaming channel. |
HRESULT IPvDSSource::put_DefaultBufferSize | ( | int | size | ) |
Default buffer size write method.
This parameter defines the default buffer size used to allocate the internal image buffers when the filter cannot read the effective payload size on the device. This can happen if the device does not properly implement the GigE Vision specific (unexpected) or if the role is set to unicast or multicast and the device is not being controlled by the filter.
This parameter is used if the effective payload size cannot be obtained, every time the DirectShow filter graph is started.
If the buffers cannot be properly allocated and the default buffer size is not large enough to accommodate incoming images the filter will automatically resize its internal buffers accordingly. However, some BUFFER_TOO_SMALL errors will be recorded and the first few images coming from the device will never be delivered.
[in] | size | Default buffer size. |
HRESULT IPvDSSource::put_DeviceID | ( | BSTR | deviceid | ) |
Device ID write method.
The device ID is used to connect the device. For a GigE Vision device, provide the MAC or IP address of the device. For a USB3 Vision device, provide the GUID of the device. You can also use the PvDeviceInfo::GetConnectionID method if you are using PvSystem or PvDeviceFinderWnd to detect and select the device of interest.
The device is connected when the ConnectIfNeeded method is called. Changing the device ID does not connect the filter to a device, it is just stored for the next ConnectIfNeeded operation.
[in] | deviceid | Filter device ID. |
HRESULT IPvDSSource::put_DiagnosticEnabled | ( | BOOL | enabled | ) |
Filter diagnostic enabled write method.
When the diagnostic mode is enabled, statistics and other information about the state of the filter are drawn over the images output by the filter. It can be useful to diagnose why you are not getting images or why the images are not formatted as expected.
[in] | enabled | Filter diagnostic enabled state. |
HRESULT IPvDSSource::put_DropThreshold | ( | int | threshold | ) |
Drop threshold write method.
Threshold used by the filter to internally drop incoming images. The upstream filter(s) are asking the source filter to deliver data at their own pace. If buffers keep arriving from the device to the PvDSSource filter, they accumulate without being delivered to the connected filters.
This parameter defines the threshold of ready images above which the filter will drop images until delivering an image when asked for one by the downstream filter.
Example: if set at 4 and the downstream filter (display, compressor, etc.) asks for an image and 7 images are available the filter will drop the 3 oldest images before delivering.
No one wants to drop images but in DirectShow as a source filter we do not control the rate at which the downstream filter asks for images. This parameter can be used to minimize latency.
Setting this parameter to 0 disables image dropping at the filter level.
If the filter runs out of available image buffer images may be dropped internally at the acquisition pipeline level. It is also possible that if the device is not able to transmit images quickly enough that images maybe be dropped at the device/grabber level as well. Counters on these three "drop" gates are available in the filter diagnostics.
[in] | threshold | Drop threshold. |
HRESULT IPvDSSource::put_Height | ( | int | height | ) |
HRESULT IPvDSSource::put_MulticastIP | ( | BSTR | ip | ) |
Filter multicast group IP address write method.
Multicast group IP address to join where the streaming data from the GigE Vision device is received with the multicast role.
The user has to make sure the GigE Vision device is configured to send data to that multicast group. This is typically performed using the eBUS Player multicast mode (setup dialog) or the PvDeviceGEV::SetStreamDestination method.
The filter multicast group IP address is only considered when connecting the device with the role defined as multicast receiver for GigE Vision devices. The device is connected when the ConnectIfNeeded method is called.
This parameter is usually set in pair with put_MulticastPort.
[in] | ip | Filter multicast IP address. |
HRESULT IPvDSSource::put_MulticastPort | ( | int | port | ) |
Multicast group port to join where the streaming data from the GigE Vision device is received with the multicast role.
The user has to make sure the GigE Vision device is configured to send data to that multicast group. This is typically performed using the eBUS Player multicast mode (setup dialog) or the PvDeviceGEV::SetStreamDestination method.
The filter multicast group port is only considered when connecting the device with the role defined as multicast receiver for GigE Vision devices. The device is connected when the ConnectIfNeeded method is called.
This parameter is usually set in pair with put_MulticastIP.
[in] | port | Filter unicast port. |
HRESULT IPvDSSource::put_ParametersSelector | ( | int | selector | ) |
Currently active GenICam interface write method.
This method selects the active GenICam interface for the internal filter objects:
All the GenICam parameter operations are performed on the currently active/selected GenICam interface. The active GenICam interface is selecting using this method.
[in] | selector | Currently active GenICam interface. |
HRESULT IPvDSSource::put_ParameterValue | ( | BSTR | name, |
BSTR | value, | ||
BSTR * | message | ||
) |
Method used to write the value of a specific parameter as a string for the currently selected GenICam interface.
See PvGenParameterArray::ToString for more information.
[in] | name | Name of the parameter. |
[in] | value | New value of the parameter. |
[out] | message | On failure, contains the GenICam/GenApi error message. |
HRESULT IPvDSSource::put_Role | ( | int | role | ) |
Filter role write method.
The role of the filter can be:
The filter role is only considered when connecting the device. The device is connected when the ConnectIfNeeded method is called.
[in] | role | Filter role. |
HRESULT IPvDSSource::put_Source | ( | BSTR | source | ) |
Name of the source currently selected on the device write method.
This parameter only applies to multi-sources devices. It should simply be left blank on devices having a single source.
Setting the source does immediately make the source active. ConnectIfNeeded must be called in order to apply the change.
[in] | source | Name of the active source. |
HRESULT IPvDSSource::put_UnicastPort | ( | int | port | ) |
Filter unicast port write method.
Unicast port where the streaming data from the GigE Vision device is received with the unicast role. A socket bound to the network interface that can reach the device is configured to listen for incoming images on that port.
The user has to make sure the GigE Vision device is configured to send data to the IP address of that local interface and at that unicast port. This is typically performed using the eBUS Player unicast mode (setup dialog) or the PvDeviceGEV::SetStreamDestination method.
The filter unicast port is only considered when connecting the device with the role defined as unicast receiver for GigE Vision devices. The device is connected when the ConnectIfNeeded method is called.
[in] | port | Filter unicast port. |
HRESULT IPvDSSource::put_Width | ( | int | width | ) |
Filter image format width write method.
The width and height is usually automatically managed by the filter when connecting to a device which is being controlled - when the role is set to controller and data receiver.
If the filter is being used in a data receiver role (unicast or multicast) the width and height must be set by the user before using the filter. It is highly recommended to set the width and height before connecting the PvDSSource filter to other filters.
Width/height mismatched can be debugged using the filter diagnostics. Typically if the configured image size is larger than what is received the image data will be provided to the downstream filter in the upper-left corner with black bands on the right and bottom. If the configured image size is too small black images are output by the filter.
[in] | width | Filter image format width. |
Copyright (c) 2002-2018 Pleora Technologies Inc.
www.pleora.com