IDriverContext Class Referenceabstract

Base class for kernel functioanlities access from the driver classes. More...

Inherited by CDriverContext.

Public Member Functions

virtual ~IDriverContext (void)
 Destructor.
 
virtual OpenViBE::Kernel::ILogManager & getLogManager (void) const =0
 Gets the kernel Log Manager. More...
 
virtual OpenViBE::Kernel::IConfigurationManager & getConfigurationManager (void) const =0
 Gets the kernel Configuration Manager. More...
 
virtual OpenViBE::boolean isConnected (void) const =0
 Gets connection status. More...
 
virtual OpenViBE::boolean isStarted (void) const =0
 Gets acquisition status. More...
 
virtual OpenViBE::boolean isImpedanceCheckRequested (void) const =0
 Checks if impedance check is required (when available) More...
 
virtual OpenViBE::int64 getDriftSampleCount (void) const =0
 Gets drift sample count. More...
 
virtual OpenViBE::int64 getDriftToleranceSampleCount (void) const =0
 Gets the drift sample count tolerance. More...
 
virtual OpenViBE::int64 getSuggestedDriftCorrectionSampleCount (void) const =0
 Gets the suggested drift correction sample count. More...
 
virtual OpenViBE::boolean correctDriftSampleCount (OpenViBE::int64 i64SampleCount)=0
 Corrects a drifting device. More...
 
virtual OpenViBE::boolean setInnerLatencySampleCount (OpenViBE::int64 i64SampleCount)=0
 Sets a fixed latency due to the driver implementation and / or hardware. More...
 
virtual OpenViBE::int64 getInnerLatencySampleCount (void) const =0
 Gets the fixed latency due to the driver implementation and / or hardware. More...
 
virtual OpenViBE::boolean updateImpedance (const OpenViBE::uint32 ui32ChannelIndex, const OpenViBE::float64 f64Impedance)=0
 Updates impedance for a specific channel. More...
 

Detailed Description

Base class for kernel functioanlities access from the driver classes.

Author
Yann Renard (INRIA/IRISA)
Date
2009-10-12
See also
IDriver

Member Function Documentation

virtual OpenViBE::Kernel::ILogManager& getLogManager ( void  ) const
pure virtual

Gets the kernel Log Manager.

Returns
the kernel Log Manager
See also
OpenViBE::Kernel::ILogManager

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::Kernel::IConfigurationManager& getConfigurationManager ( void  ) const
pure virtual

Gets the kernel Configuration Manager.

Returns
the kernel Configuration Manager
See also
OpenViBE::Kernel::IConfigurationManager

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean isConnected ( void  ) const
pure virtual

Gets connection status.

Returns
true if the driver is connected
false if the driver is not connected
See also
isStarted

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean isStarted ( void  ) const
pure virtual

Gets acquisition status.

Returns
true if acquisition is started
false if acquisition is stoped
See also
isConnected

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean isImpedanceCheckRequested ( void  ) const
pure virtual

Checks if impedance check is required (when available)

Returns
true if impedance check is required
false if impedance check is not required

It is up to the driver to check whether impedance check is required by the acquisition server or not. If this test is required, then the driver should perform impedance measures while initialized but not yet started.

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::int64 getDriftSampleCount ( void  ) const
pure virtual

Gets drift sample count.

Returns
the drift sample count
See also
correctDriftSampleCount

This function returns the difference between the theorical number of samples this driver should have sent so far and the number of samples it actually sent. This drift sample count is computed by the acquisition server and can be used to correct a drifting device behavior.

Note
If this number is less than 0 then samples are missing
If this number if more than 0 then there are too much samples
If this number is exactly 0 then the driver sent the exact number of samples it had to send

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::int64 getDriftToleranceSampleCount ( void  ) const
pure virtual

Gets the drift sample count tolerance.

Returns
the drift sample count tolerance

Gets the tolerance configured for the acquisition server. This tolerance is present to avoid numerous corrections on a drift value that would oscillate in a small range around 0. In such case, a correction in a way would probably turn in a correction in the opposite way a few seconds later, resulting in crap measurements because of irregular but valid source.

If the actual drift is in the [-tolerance +tolerance] range, better don't correct it.

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::int64 getSuggestedDriftCorrectionSampleCount ( void  ) const
pure virtual

Gets the suggested drift correction sample count.

Returns
the suggested drift correction sample count

In case you don't want to manage how much samples should be used to correct the drift, you could simply use this function. The algorithm used to compute the returned value should be considered as undefined. This computation could change over time and versions of OpenViBE. That means the driver should not make any assumption on the way of computing the actual value returned by this function.

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean correctDriftSampleCount ( OpenViBE::int64  i64SampleCount)
pure virtual

Corrects a drifting device.

Returns
true in case of success
false in case of error
See also
getDriftSampleCount
setInnerLatencySampleCount

Some devices don't sent the number of samples they promised to while requesting sampling rate. This can be for multiple reasons but the most probable one is that the device does not have its internal clock synchronized with the internal computer clock. OpenViBE data being dated with a start / end time, it is important for synchronisation purpose that all the theorical number of samples per second is preserved.

In case the difference between the theorical number of samples this driver should have sent so far and the number of samples it actually sent becomes too big, this function helps to correct the drifting, removing or adding dummy samples. In a strict signal processing point of view those samples can't be considered as valid. However, this is the only way to guarantee that the timings are preserved.

Note
Passing a negative value removes samples
Passing a positive value adds samples
Passing 0 does nothing
This function can be called several times if needed but does not change what getDriftSampleCount returns until the next IDriver::loop execution
Warning
Please be careful when calling this function. Consider the fact that there could be some drifting in the device and ths OS-level driver itself, or even in the communication pipeline to the prorprietary acquisition software. As an OpenViBE driver developer, you should allow an arbitrary small drifting (which range depends of the actual driver you are creating).

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean setInnerLatencySampleCount ( OpenViBE::int64  i64SampleCount)
pure virtual

Sets a fixed latency due to the driver implementation and / or hardware.

Parameters
i64SampleCount[in] : the number of samples for the inner latency
Returns
true in case of success
false in case of error

Some drivers / hardware devices implement processes that delay the overall acquisition stream. Such processes include for instance sample buffering or temporal filtering. The delay induced by these processes can not be known by the acquisition server in a generic way and are usually not provided by the device manufacturer. An intelligent setup based on hardware tagging could however induce a fair estimate of this latency so that it can be injected in the drift correction process. Driver developers will generally not have to care about this feature. However, if it is important to have neurophysiologically relevant measures (more particularly on ERPs) and it is know that the driver and / or hardware has a latency, this latency compensation can be injected in the drift correction process using the aforementionned function.

Note
Passing a positive value supposes the driver / hardware induce a delay which shall be corrected
Passing a negative value supposes the driver / hardware is able to predict and send future measures before they actually get measured (probably not recommended)
Passing 0 supposes both the driver and hardware are ideals and send samples immediately to the acquisition server as they happen on the scalp
Default configuration supposes both the driver and hardware are ideal, thus sets the inner latency to 0
See also
getInnerLatencySampleCount

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::int64 getInnerLatencySampleCount ( void  ) const
pure virtual

Gets the fixed latency due to the driver implementation and / or hardware.

Returns
The inner latency of the driver in sample count
See also
setInnerLatencySampleCount

Referenced by IDriverContext::~IDriverContext().

virtual OpenViBE::boolean updateImpedance ( const OpenViBE::uint32  ui32ChannelIndex,
const OpenViBE::float64  f64Impedance 
)
pure virtual

Updates impedance for a specific channel.

Parameters
ui32ChannelIndex[in] : the index of the channel should be updated
f64Impedance[in] : the impedance of the specified channel (in ohm)
Returns
true in case of success.
false in case of error.

This can be used during initialization phase to check if impedances are correct. This function should be connected while the driver is initialized and not started.

If f64Impedance is -1, then the impedance is considered as "unknown / measuring" If f64Impedance is -2, then the impedance is considered as "unknown / not available" If f64Impedance is any other negative value, then the impedance is considered as "unknown"

Referenced by IDriverContext::~IDriverContext().