Class lsl::stream_inlet

ClassList > lsl > stream_inlet

#include <lsl_cpp.h>

Public Functions

Type	Name
void	close_stream ()
uint32_t	flush () noexcept Drop all queued not-yet pulled samples, return the nr of dropped samples.
int	get_channel_count () const
std::shared_ptr< lsl_inlet_struct_ >	handle ()
stream_info	info (double timeout=FOREVER)
void	open_stream (double timeout=FOREVER)
stream_inlet &	operator= (stream_inlet && rhs) noexcept
bool	pull_chunk (std::vector< std::vector< T > > & chunk, std::vector< double > & timestamps)
double	pull_chunk (std::vector< std::vector< T > > & chunk)
std::vector< std::vector< T > >	pull_chunk ()
std::size_t	pull_chunk_multiplexed (float * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (double * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (int64_t * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (int32_t * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (int16_t * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (char * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
std::size_t	pull_chunk_multiplexed (std::string * data_buffer, double * timestamp_buffer, std::size_t data_buffer_elements, std::size_t timestamp_buffer_elements, double timeout=0.0)
bool	pull_chunk_multiplexed (std::vector< T > & chunk, std::vector< double > * timestamps=nullptr, double timeout=0.0, bool append=false)
bool	pull_chunk_numeric_structs (std::vector< T > & chunk, std::vector< double > & timestamps)
double	pull_chunk_numeric_structs (std::vector< T > & chunk)
std::vector< T >	pull_chunk_numeric_structs ()
double	pull_numeric_raw (void * sample, int32_t buffer_bytes, double timeout=FOREVER)
double	pull_numeric_struct (T & sample, double timeout=FOREVER)
double	pull_sample (T sample, double timeout=FOREVER)
double	pull_sample (std::vector< float > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< double > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< int64_t > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< int32_t > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< int16_t > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< char > & sample, double timeout=FOREVER)
double	pull_sample (std::vector< std::string > & sample, double timeout=FOREVER)
double	pull_sample (float * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (double * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (int64_t * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (int32_t * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (int16_t * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (char * buffer, int32_t buffer_elements, double timeout=FOREVER)
double	pull_sample (std::string * buffer, int32_t buffer_elements, double timeout=FOREVER)
std::size_t	samples_available ()
void	set_postprocessing (uint32_t flags=post_ALL)
void	smoothing_halftime (float value)
	stream_inlet (const stream_info & info, int32_t max_buflen=360, int32_t max_chunklen=0, bool recover=true, lsl_transport_options_t flags=transp_default)
	stream_inlet (stream_inlet && rhs) noexcept Move constructor for stream_inlet .
double	time_correction (double timeout=FOREVER)
double	time_correction (double * remote_time, double * uncertainty, double timeout=FOREVER)
bool	was_clock_reset ()

Detailed Description

A stream inlet. Inlets are used to receive streaming data (and meta-data) from the lab network.

Public Functions Documentation

function close_stream

inline void lsl::stream_inlet::close_stream ()

Drop the current data stream.

All samples that are still buffered or in flight will be dropped and transmission and buffering of data for this inlet will be stopped. If an application stops being interested in data from a source (temporarily or not) but keeps the outlet alive, it should call close_stream() to not waste unnecessary system and network resources.

function flush

Drop all queued not-yet pulled samples, return the nr of dropped samples.

inline uint32_t lsl::stream_inlet::flush () noexcept

function get_channel_count

inline int lsl::stream_inlet::get_channel_count () const

function handle

inline std::shared_ptr< lsl_inlet_struct_ > lsl::stream_inlet::handle ()

Return a shared pointer to pass to C-API functions that aren't wrapped yet

Example:

lsl_pull_sample_buf(inlet.handle().get(), buf, …);

function info

inline stream_info lsl::stream_inlet::info (
    double timeout=FOREVER
)

Retrieve the complete information of the given stream, including the extended description. Can be invoked at any time of the stream's lifetime.

Parameters:

timeout Timeout of the operation (default: no timeout).

Exception:

timeout_error (if the timeout expires), or lost_error (if the stream source has been lost).

function open_stream

inline void lsl::stream_inlet::open_stream (
    double timeout=FOREVER
)

Subscribe to the data stream. All samples pushed in at the other end from this moment onwards will be queued and eventually be delivered in response to pull_sample() or pull_chunk() calls. Pulling a sample without some preceding open_stream() is permitted (the stream will then be opened implicitly).

Parameters:

timeout Optional timeout of the operation (default: no timeout).

Exception:

timeout_error (if the timeout expires), or lost_error (if the stream source has been lost).

function operator=

stream_inlet & lsl::stream_inlet::operator= (
    stream_inlet && rhs
) noexcept

function pull_chunk [1/3]

template<class T>
inline bool lsl::stream_inlet::pull_chunk (
    std::vector< std::vector< T > > & chunk,
    std::vector< double > & timestamps
)

Pull a chunk of samples from the inlet.

This is the most complete version, returning both the data and a timestamp for each sample.

Parameters:

chunk A vector of vectors to hold the samples.
timestamps A vector to hold the time stamps.

Returns:

True if some data was obtained.

Exception:

lost_error (if the stream source has been lost).

function pull_chunk [2/3]

template<class T>
inline double lsl::stream_inlet::pull_chunk (
    std::vector< std::vector< T > > & chunk
)

Pull a chunk of samples from the inlet.

This version returns only the most recent sample's time stamp.

Parameters:

chunk A vector of vectors to hold the samples.

Returns:

The time when the most recent sample was captured on the remote machine, or 0.0 if no new sample was available.

Exception:

lost_error (if the stream source has been lost)

function pull_chunk [3/3]

template<class T>
inline std::vector< std::vector< T > > lsl::stream_inlet::pull_chunk ()

Pull a chunk of samples from the inlet.

This function does not return time stamps for the samples. Invoked as: mychunk = pull_chunk<float>();

Returns:

A vector of vectors containing the obtained samples; may be empty.

Exception:

lost_error (if the stream source has been lost)

function pull_chunk_multiplexed [1/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    float * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

Pull a chunk of data from the inlet into a pre-allocated buffer.

This is a high-performance function that performs no memory allocations (useful for very high data rates or on low-powered devices).

Warning:

The provided buffer size is measured in channel values (e.g., floats), not samples.

Parameters:

data_buffer A pointer to a buffer of data values where the results shall be stored.
timestamp_buffer A pointer to a buffer of timestamp values where time stamps shall be stored. If this is NULL, no time stamps will be returned.
data_buffer_elements The size of the data buffer, in channel data elements (of type T). Must be a multiple of the stream's channel count.
timestamp_buffer_elements The size of the timestamp buffer. If a timestamp buffer is provided then this must correspond to the same number of samples as data_buffer_elements.
timeout The timeout for this operation, if any. When the timeout expires, the function may return before the entire buffer is filled. The default value of 0.0 will retrieve only data available for immediate pickup.

Returns:

data_elements_written Number of channel data elements written to the data buffer.

Exception:

lost_error (if the stream source has been lost).

function pull_chunk_multiplexed [2/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    double * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [3/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    int64_t * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [4/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    int32_t * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [5/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    int16_t * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [6/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    char * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [7/8]

inline std::size_t lsl::stream_inlet::pull_chunk_multiplexed (
    std::string * data_buffer,
    double * timestamp_buffer,
    std::size_t data_buffer_elements,
    std::size_t timestamp_buffer_elements,
    double timeout=0.0
)

function pull_chunk_multiplexed [8/8]

template<typename T>
inline bool lsl::stream_inlet::pull_chunk_multiplexed (
    std::vector< T > & chunk,
    std::vector< double > * timestamps=nullptr,
    double timeout=0.0,
    bool append=false
)

Pull a multiplexed chunk of samples and optionally the sample timestamps from the inlet.

Parameters:

chunk A vector to hold the multiplexed (Sample 1 Channel 1, S1C2, S2C1, S2C2, S3C1, S3C2, ...) samples
timestamps A vector to hold the timestamps or nullptr
timeout Time to wait for the first sample. The default value of 0.0 will not wait for data to arrive, pulling only samples already received.
append (True:) Append data or (false:) clear them first

Returns:

True if some data was obtained.

Exception:

lost_error (if the stream source has been lost).

function pull_chunk_numeric_structs [1/3]

template<class T>
inline bool lsl::stream_inlet::pull_chunk_numeric_structs (
    std::vector< T > & chunk,
    std::vector< double > & timestamps
)

Pull a chunk of samples from the inlet.

This is the most complete version, returning both the data and a timestamp for each sample.

Parameters:

chunk A vector of C-style structs to hold the samples.
timestamps A vector to hold the time stamps.

Returns:

True if some data was obtained.

Exception:

lost_error (if the stream source has been lost)

function pull_chunk_numeric_structs [2/3]

template<class T>
inline double lsl::stream_inlet::pull_chunk_numeric_structs (
    std::vector< T > & chunk
)

Pull a chunk of samples from the inlet.

This version returns only the most recent sample's time stamp.

Parameters:

chunk A vector of C-style structs to hold the samples.

Returns:

The time when the most recent sample was captured on the remote machine, or 0.0 if no new sample was available.

Exception:

lost_error (if the stream source has been lost)

function pull_chunk_numeric_structs [3/3]

template<class T>
inline std::vector< T > lsl::stream_inlet::pull_chunk_numeric_structs ()

Pull a chunk of samples from the inlet.

This function does not return time stamps. Invoked as: mychunk = pull_chunk<mystruct>();

Returns:

A vector of C-style structs containing the obtained samples; may be empty.

Exception:

lost_error (if the stream source has been lost)

function pull_numeric_raw

inline double lsl::stream_inlet::pull_numeric_raw (
    void * sample,
    int32_t buffer_bytes,
    double timeout=FOREVER
)

Pull a sample from the inlet and read it into a pointer to raw data.

No type checking or conversions are done (not recommended!). Do not use for variable-size/string-formatted streams.

Parameters:

sample A pointer to hold the resulting raw sample data.
buffer_bytes The number of bytes allocated in the buffer. Note: it is the responsibility of the user to allocate enough memory.
timeout The timeout for this operation, if any. Use 0.0 to make the function non-blocking.

Returns:

The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by .time_correction() to it.

Exception:

lost_error (if the stream source has been lost).

function pull_numeric_struct

template<class T>
inline double lsl::stream_inlet::pull_numeric_struct (
    T & sample,
    double timeout=FOREVER
)

Pull a sample from the inlet and read it into a custom C-style struct.

Overall size checking but no type checking or conversion are done. Do not use for variable-size/string-formatted streams.

Parameters:

sample The raw sample object to hold the data (packed C-style struct). Search for #``pragma pack for information on how to pack structs correctly.
timeout The timeout for this operation, if any. Use 0.0 to make the function non-blocking.

Returns:

The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by .time_correction() to it.

Exception:

lost_error (if the stream source has been lost).

function pull_sample [1/15]

template<class T, int N>
inline double lsl::stream_inlet::pull_sample (
    T sample,
    double timeout=FOREVER
)

Pull a sample from the inlet and read it into an array of values. Handles type checking & conversion.

Parameters:

sample An array to hold the resulting values.
timeout The timeout for this operation, if any. Use 0.0 to make the function non-blocking.

Returns:

The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by .time_correction() to it.

Exception:

lost_error (if the stream source has been lost).

function pull_sample [2/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< float > & sample,
    double timeout=FOREVER
)

Pull a sample from the inlet and read it into a std vector of values. Handles type checking & conversion and allocates the necessary memory in the vector if necessary.

Parameters:

sample An STL vector to hold the resulting values.
timeout The timeout for this operation, if any. Use 0.0 to make the function non-blocking.

Returns:

The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by .time_correction() to it.

Exception:

lost_error (if the stream source has been lost).

function pull_sample [3/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< double > & sample,
    double timeout=FOREVER
)

function pull_sample [4/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< int64_t > & sample,
    double timeout=FOREVER
)

function pull_sample [5/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< int32_t > & sample,
    double timeout=FOREVER
)

function pull_sample [6/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< int16_t > & sample,
    double timeout=FOREVER
)

function pull_sample [7/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< char > & sample,
    double timeout=FOREVER
)

function pull_sample [8/15]

inline double lsl::stream_inlet::pull_sample (
    std::vector< std::string > & sample,
    double timeout=FOREVER
)

function pull_sample [9/15]

inline double lsl::stream_inlet::pull_sample (
    float * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

Pull a sample from the inlet and read it into a pointer to values. Handles type checking & conversion.

Parameters:

buffer A pointer to hold the resulting values.
buffer_elements The number of samples allocated in the buffer. Note: it is the responsibility of the user to allocate enough memory.
timeout The timeout for this operation, if any. Use 0.0 to make the function non-blocking.

Returns:

The capture time of the sample on the remote machine, or 0.0 if no new sample was available. To remap this time stamp to the local clock, add the value returned by .time_correction() to it.

Exception:

lost_error (if the stream source has been lost).

function pull_sample [10/15]

inline double lsl::stream_inlet::pull_sample (
    double * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function pull_sample [11/15]

inline double lsl::stream_inlet::pull_sample (
    int64_t * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function pull_sample [12/15]

inline double lsl::stream_inlet::pull_sample (
    int32_t * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function pull_sample [13/15]

inline double lsl::stream_inlet::pull_sample (
    int16_t * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function pull_sample [14/15]

inline double lsl::stream_inlet::pull_sample (
    char * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function pull_sample [15/15]

inline double lsl::stream_inlet::pull_sample (
    std::string * buffer,
    int32_t buffer_elements,
    double timeout=FOREVER
)

function samples_available

inline std::size_t lsl::stream_inlet::samples_available ()

Query whether samples are currently available for immediate pickup.

Note that it is not a good idea to use samples_available() to determine whether a pull_*() call would block: to be sure, set the pull timeout to 0.0 or an acceptably low value. If the underlying implementation supports it, the value will be the number of samples available (otherwise it will be 1 or 0).

function set_postprocessing

inline void lsl::stream_inlet::set_postprocessing (
    uint32_t flags=post_ALL
)

Set post-processing flags to use.

By default, the inlet performs NO post-processing and returns the ground-truth time stamps, which can then be manually synchronized using .time_correction(), and then smoothed/dejittered if desired. This function allows automating these two and possibly more operations.

Warning:

When you enable this, you will no longer receive or be able to recover the original time stamps.

Parameters:

flags An integer that is the result of bitwise OR'ing one or more options from processing_options_t together (e.g., post_clocksync|post_dejitter); the default is to enable all options.

function smoothing_halftime

inline void lsl::stream_inlet::smoothing_halftime (
    float value
)

Override the half-time (forget factor) of the time-stamp smoothing.

The default is 90 seconds unless a different value is set in the config file. Using a longer window will yield lower jitter in the time stamps, but longer windows will have trouble tracking changes in the clock rate (usually due to temperature changes); the default is able to track changes up to 10 degrees C per minute sufficiently well.

function stream_inlet [1/3]

inline lsl::stream_inlet::stream_inlet (
    const stream_info & info,
    int32_t max_buflen=360,
    int32_t max_chunklen=0,
    bool recover=true,
    lsl_transport_options_t flags=transp_default
)

Construct a new stream inlet from a resolved stream info.

Parameters:

info A resolved stream info object (as coming from one of the resolver functions). Note: The stream_inlet may also be constructed with a fully-specified stream_info, if the desired channel format and count is already known up-front, but this is strongly discouraged and should only ever be done if there is no time to resolve the stream up-front (e.g., due to limitations in the client program).
max_buflen Optionally the maximum amount of data to buffer (in seconds if there is a nominal sampling rate, otherwise x100 in samples). Recording applications want to use a fairly large buffer size here, while real-time applications would only buffer as much as they need to perform their next calculation.
max_chunklen Optionally the maximum size, in samples, at which chunks are transmitted (the default corresponds to the chunk sizes used by the sender). Recording applications can use a generous size here (leaving it to the network how to pack things), while real-time applications may want a finer (perhaps 1-sample) granularity. If left unspecified (=0), the sender determines the chunk granularity.
recover Try to silently recover lost streams that are recoverable (=those that that have a source_id set). In all other cases (recover is false or the stream is not recoverable) functions may throw a lsl::lost_error if the stream's source is lost (e.g., due to an app or computer crash).

function stream_inlet [2/3]

Move constructor for stream_inlet .

lsl::stream_inlet::stream_inlet (
    stream_inlet && rhs
) noexcept

function time_correction [1/2]

inline double lsl::stream_inlet::time_correction (
    double timeout=FOREVER
)

Retrieve an estimated time correction offset for the given stream.

The first call to this function takes several milliseconds until a reliable first estimate is obtained. Subsequent calls are instantaneous (and rely on periodic background updates). On a well-behaved network, the precision of these estimates should be below 1 ms (empirically it is within +/-0.2 ms).

To get a measure of whether the network is well-behaved, use the extended version time_correction(double*,double*,double) and check uncertainty (i.e. the round-trip-time).

0.2 ms is typical of wired networks. 2 ms is typical of wireless networks. The number can be much higher on poor networks.

Parameters:

timeout Timeout to acquire the first time-correction estimate (default: no timeout).

Returns:

The time correction estimate. This is the number that needs to be added to a time stamp that was remotely generated via lsl_local_clock() to map it into the local clock domain of this machine.

Exception:

lsl::timeout_error (if the timeout expires), or lsl::lost_error (if the stream source has been lost).

function time_correction [2/2]

inline double lsl::stream_inlet::time_correction (
    double * remote_time,
    double * uncertainty,
    double timeout=FOREVER
)

Retrieve an estimated time correction offset for the given stream.

The first call to this function takes several milliseconds until a reliable first estimate is obtained. Subsequent calls are instantaneous (and rely on periodic background updates). On a well-behaved network, the precision of these estimates should be below 1 ms (empirically it is within +/-0.2 ms).

To get a measure of whether the network is well-behaved, use the extended version time_correction(double*,double*,double) and check uncertainty (i.e. the round-trip-time).

0.2 ms is typical of wired networks. 2 ms is typical of wireless networks. The number can be much higher on poor networks.

Parameters:

timeout Timeout to acquire the first time-correction estimate (default: no timeout).

Returns:

The time correction estimate. This is the number that needs to be added to a time stamp that was remotely generated via lsl_local_clock() to map it into the local clock domain of this machine.

Exception:

lsl::timeout_error (if the timeout expires), or lsl::lost_error (if the stream source has been lost).

Parameters:

remote_time The current time of the remote computer that was used to generate this time_correction. If desired, the client can fit time_correction vs remote_time to improve the real-time time_correction further.
uncertainty The maximum uncertainty of the given time correction.

function was_clock_reset

inline bool lsl::stream_inlet::was_clock_reset ()

Query whether the clock was potentially reset since the last call to was_clock_reset().

This is a rarely-used function that is only useful to applications that combine multiple time_correction values to estimate precise clock drift; it allows to tolerate cases where the source machine was hot-swapped or restarted in between two measurements.

The documentation for this class was generated from the following file liblsl/include/lsl_cpp.h