Connect, configure and control a GigE Vision or USB3 Vision device. More...
Public Member Functions | |
virtual | ~PvDevice () |
Destructor. | |
PvDeviceType | GetType () const |
Returns the type of the instantiated device. More... | |
virtual PvResult | Connect (const PvDeviceInfo *aDeviceInfo) |
Connect to a GigE Vision or USB3 Vision device. More... | |
virtual PvResult | Connect (const PvString &aInfo) |
Connect to a GigE Vision or USB3 Vision device. More... | |
PvResult | Disconnect () |
Disconnect the PvDevice object from the GigE Vision or USB3 Vision device to which it is currently connected. More... | |
PvResult | StreamEnable (uint32_t aChannel=0) |
Enables streaming on the device. More... | |
PvResult | StreamDisable (uint32_t aChannel=0) |
Disables streaming on the device. More... | |
bool | IsConnected () const |
Test if this PvDevice is currently connected to a GigE Vision or USB3 Vision device. More... | |
bool | IsPleoraPowered () const |
Test if this PvDevice is currently connected to a Pleora powered GigE Vision or USB3 Vision device. More... | |
PvResult | DumpGenICamXML (const PvString &aFilename) |
Save the GigE Vision or USB3 Visio device's GenICam XML file to disk. More... | |
PvResult | GetDefaultGenICamXMLFilename (PvString &aFilename) |
Returns a good default filename to use with DumpGenICamXML. More... | |
PvGenParameterArray * | GetParameters () |
Get the parameters used to control the GigE Vision or USB3 Vision device to which you are connected. More... | |
PvGenParameterArray * | GetCommunicationParameters () |
Get the parameters used to define how PvDevice connects to and communicates with the device. More... | |
PvResult | ReadMemory (int64_t aAddress, unsigned char *aDestination, int64_t aByteCount) |
Reads bytes starting at a specific register address on the GigE Vision or USB3 Vision device. More... | |
PvResult | WriteMemory (int64_t aAddress, const unsigned char *aSource, int64_t aByteCount) |
Writes bytes starting at a specific register address on the GigE Vision or USB3 Vision device. More... | |
PvResult | WaitForMessagingChannelIdle (uint32_t aTimeout) |
Waits for the messaging channel to become idle. More... | |
PvResult | RegisterEventSink (PvDeviceEventSink *aEventSink) |
Register an event sink used for callbacks. More... | |
PvResult | UnregisterEventSink (PvDeviceEventSink *aEventSink) |
Unregister an event sink. More... | |
uint32_t | GetHeartbeatThreadPriority () const |
Get the priority of the heartbeat thread. More... | |
PvResult | SetHeartbeatThreadPriority (uint32_t aPriority) |
Set the priority of the heartbeat thread. More... | |
uint32_t | GetInterruptLinkThreadPriority () const |
Get the priority of the interrupt link thread. More... | |
PvResult | SetInterruptLinkThreadPriority (uint32_t aPriority) |
Set the priority of the interrupt link thread. More... | |
uint32_t | GetInterruptQueueThreadPriority () const |
Get the priority of the interrupt queue thread. More... | |
PvResult | SetInterruptQueueThreadPriority (uint32_t aPriority) |
Set the priority of the interrupt queue thread. More... | |
uint32_t | GetPayloadSize () |
Returns the payload size the device is currently configured to stream with. More... | |
PvResult | GetUniqueID (PvString &aID) |
Returns a unique string identifier for the device. More... | |
Static Public Member Functions | |
static PvDevice * | CreateAndConnect (const PvDeviceInfo *aDeviceInfo, PvResult *aResult) |
Dynamically allocates a PvDevice of the right type. More... | |
static PvDevice * | CreateAndConnect (const PvString &aInfo, PvResult *aResult) |
Dynamically allocates a PvDevice of the right type. More... | |
static void | Free (PvDevice *aDevice) |
Frees an object allocated with CreateAndConnect. More... | |
Protected Member Functions | |
PvDevice () | |
Constructor. | |
Connect, configure and control a GigE Vision or USB3 Vision device.
It is not possible to instantiate a generic PvDevice. PvDeviceGEV and PvDeviceU3V can be instantiated directly.
If order to write hybrid code one could use the static CreateAndConnect methods. These methods dynamically allocated a PvDevice of the right type to connect to the requested device. Just remember to free the dynamically allocated device object using the static Free method.
|
virtual |
Connect to a GigE Vision or USB3 Vision device.
The Connect method connects to a GigE Vision device found using a PvSystem or device finder dialog object. Only one device can be connected to at a time.
[in] | aDeviceInfo | The GigE Vision device's network connectivity information; a PvDeviceInfo object. |
Reimplemented in PvDeviceU3V, and PvDeviceGEV.
Connect to a GigE Vision or USB3 Vision device.
If you know the GigE Vision device's IP address, MAC address or DeviceUserID, you can use this method to connect to it.
If you know the USB3 Vision device's GUID or DeviceUserID, you can use this method to connect it.
[in] | aInfo | Information that uniquely identifies the device. You may use one of the following:
|
Reimplemented in PvDeviceGEV, and PvDeviceU3V.
|
static |
Dynamically allocates a PvDevice of the right type.
This static method takes a generic PvDeviceInfo, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.
Objects allocated with CreateAndConnect should be freed with PvDevice::Free.
[in] | aDeviceInfo | Pointer to the device information used to connect the device. |
[out] | aResult | Outcome of the operation:
|
Dynamically allocates a PvDevice of the right type.
This static method takes a string identifying a device, creates the right type of PvDevice (PvDeviceGEV or PvDeviceU3V) and connects it.
Objects allocated with CreateAndConnect should be freed with PvDevice::Free.
[in] | aInfo | String identifying the device. See PvDevice::Connect for more information. |
[out] | aResult | Outcome of the operation.
|
PvResult PvDevice::Disconnect | ( | ) |
Save the GigE Vision or USB3 Visio device's GenICam XML file to disk.
If the XML is stored in a zip file on the device, the zip file containing the XML is saved on the disk.
aFilename | The file's name. |
|
static |
Frees an object allocated with CreateAndConnect.
Even though calling delete on a PvDevice created with CreateAndConnect 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 PvDevice allocated with CreateAndConnect.
[in] | aDevice | Pointer to the device object to delete. |
PvGenParameterArray * PvDevice::GetCommunicationParameters | ( | ) |
Get the parameters used to define how PvDevice connects to and communicates with the device.
For a listing of all the available parameters, refer to GEV Device Communication Parameters or U3V Device Communication Parameters
Returns a good default filename to use with DumpGenICamXML.
The filename is built from the URL that was used in order to locate the GenICam XML file of the device.
aFilename | A default filename built from the device XML location URL. |
uint32_t PvDevice::GetHeartbeatThreadPriority | ( | ) | const |
Get the priority of the heartbeat thread.
See SetHeartbeatThreadPriority for details about the meaning of the values returned
uint32_t PvDevice::GetInterruptLinkThreadPriority | ( | ) | const |
Get the priority of the interrupt link thread.
See SetInterruptLinkThreadPriority for details about the meaning of the values returned
uint32_t PvDevice::GetInterruptQueueThreadPriority | ( | ) | const |
Get the priority of the interrupt queue thread.
See SetInterruptQueueThreadPriority for details about the meaning of the values returned
PvGenParameterArray * PvDevice::GetParameters | ( | ) |
Get the parameters used to control the GigE Vision or USB3 Vision device to which you are connected.
Each device provides its own GenICam XML file with parameters describing its behaviour referred to as features. The PvGenParameterArray object returned by this method provides an interface to these features.
uint32_t PvDevice::GetPayloadSize | ( | ) |
Returns the payload size the device is currently configured to stream with.
This method attempts to read the GenICam PayloadSize parameter of the device. If the operation fails the payload size is computed from width, height and pixel format as a fall back. If even this fails, a value that is still valid to allocate buffers is finally returned.
PvDeviceType PvDevice::GetType | ( | ) | const |
Returns the type of the instantiated device.
Returns a unique string identifier for the device.
[out] | aID | Unique string identifier for the device. |
bool PvDevice::IsConnected | ( | ) | const |
bool PvDevice::IsPleoraPowered | ( | ) | const |
PvResult PvDevice::ReadMemory | ( | int64_t | aAddress, |
unsigned char * | aDestination, | ||
int64_t | aByteCount | ||
) |
Reads bytes starting at a specific register address on the GigE Vision or USB3 Vision device.
See warnings about accessing the register map directly in WriteMemory.
[in] | aAddress | Start address of the read memory operation (mod 4). |
[out] | aDestination | Buffer where to write data read from the device. |
[in] | aByteCount | Bytes to read from the device (mod 4, non 0) |
PvResult PvDevice::RegisterEventSink | ( | PvDeviceEventSink * | aEventSink | ) |
Register an event sink used for callbacks.
[in] | aEventSink | A pointer to the event sink. |
PvResult PvDevice::SetHeartbeatThreadPriority | ( | uint32_t | aPriority | ) |
Set the priority of the heartbeat thread.
The heartbeat thread priority is critical to most applications. This thread must never starve against any other system thread to the risk of losing the device connection.
This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.
See GetHeartbeatThreadPriority
[in] | aPriority | See PvPipeline::SetBufferHandlingThreadPriority for description of the supported values |
PvResult PvDevice::SetInterruptLinkThreadPriority | ( | uint32_t | aPriority | ) |
Set the priority of the interrupt link thread.
Interrupt link thread receives messaging channel packets from the device, sends acknowledge back and queues the message in the interrupt queue. Process and callbacks are not done from this thread.
This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.
See GetInterruptLinkThreadPriority
[in] | aPriority | See PvPipeline::SetBufferHandlingThreadPriority for description of the supported values |
PvResult PvDevice::SetInterruptQueueThreadPriority | ( | uint32_t | aPriority | ) |
Set the priority of the interrupt queue thread.
This thread is simply used to fire/invoke the OnLinkDisconnected and OnLinkReconnected PvDeviceEventSink events.
This thread takes all messages queued for deferred processing by the interrupt link thread and fires all GenApi and PvDeviceEventSink callback. All callbacks are fired/run in the context of this thread.
See GetInterruptQueueThreadPriority
[in] | aPriority | See PvPipeline::SetBufferHandlingThreadPriority for description of the supported values |
PvResult PvDevice::StreamDisable | ( | uint32_t | aChannel = 0 | ) |
Disables streaming on the device.
For GigE Vision devices, this takes care of resetting the TLParamsLocked so that changes to streaming related parameters are possible again.
For USB3 Vision devices, this takes care of the TLParamsLocked and sets the streaming enable bit on the device.
StreamDisable should be called after the AcquisitionStop GenICam command has been executed and all images have been received.
[in] | aChannel | The channel on which to enable streaming. |
PvResult PvDevice::StreamEnable | ( | uint32_t | aChannel = 0 | ) |
Enables streaming on the device.
For GigE Vision devices, this takes care of setting the TLParamsLocked so that changes to streaming related parameters are prevent in the GenICam interface of the device.
For USB3 Vision devices, this takes care of the TLParamsLocked, configures the driver for streaming and sets the streaming enable bit on the device.
After calling StreamEnable, the user must still execute the AcquisitionStart GenICam command of the device to instruct the device to begin acquisition.
[in] | aChannel | The channel on which to enable streaming. |
PvResult PvDevice::UnregisterEventSink | ( | PvDeviceEventSink * | aEventSink | ) |
Unregister an event sink.
[in] | aEventSink | A pointer to the event sink. |
PvResult PvDevice::WaitForMessagingChannelIdle | ( | uint32_t | aTimeout | ) |
Waits for the messaging channel to become idle.
This method returns once the host-side messaging channel in-queue is empty or aTimeout (ms) has elapsed.
[in] | aTimeout | Maximum time to wait, in ms. |
PvResult PvDevice::WriteMemory | ( | int64_t | aAddress, |
const unsigned char * | aSource, | ||
int64_t | aByteCount | ||
) |
Writes bytes starting at a specific register address on the GigE Vision or USB3 Vision device.
This is an advanced method and is rarely needed. In general, most users should instead use the device's GenICam interface which can be obtained through GetParameters.
This method let advanced users control third-party GigE Vision devices with poor or incomplete GenICam XML files. The methods presume detailed working knowledge of the GigE Vision device's register map. Since the WriteMemory method bypasses the GenICam interface and the SDK's cache of values, incorrect use may cause indeterminate results.
Not all GigE Vision devices are supporting the write memory operation. When using this method on a Gig Vision device not supporting write memory operations, the write is broken down in as many write register commands as required.
[in] | aAddress | Start address of the write memory operation (mod 4). |
[out] | aSource | Buffer holding the data to write to the device. |
[in] | aByteCount | Bytes to write to the device (mod 4, non 0) |
Copyright (c) 2002-2021 Pleora Technologies Inc.
www.pleora.com