Stream Outlets

Text here

Stream Outlet

Doxygen output

class stream_outlet

A stream outlet.

Outlets are used to make streaming data (and the meta-data) available on the lab network.

Push functions

Push a chunk of multiplexed data into the outlet.

Parameters

  • buffer: A buffer of channel values holding the data for zero or more successive samples to send.

  • timestamp: Optionally the capture time of the most recent sample, in agreement with local_clock(); if omitted, the current time is used. The time stamps of other samples are automatically derived according to the sampling rate of the stream.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

Public Functions

stream_outlet(const stream_info &info, int32_t chunk_size = 0, int32_t max_buffered = 360)

Establish a new stream outlet.

This makes the stream discoverable.

Parameters

  • info: The stream information to use for creating this stream. Stays constant over the lifetime of the outlet.

  • chunk_size: Optionally the desired chunk granularity (in samples) for transmission. If unspecified, each push operation yields one chunk. Inlets can override this setting.

  • max_buffered: Optionally the maximum amount of data to buffer (in seconds if there is a nominal sampling rate, otherwise x100 in samples). The default is 6 minutes of data.

template<class T, int32_t N>
void push_sample(const T data[N], double timestamp = 0.0, bool pushthrough = true)

Push a C array of values as a sample into the outlet.

Each entry in the array corresponds to one channel. The function handles type checking & conversion.

Parameters

  • data: An array of values to push (one per channel).

  • timestamp: Optionally the capture time of the sample, in agreement with lsl::local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the sample through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_sample(const std::vector<float> &data, double timestamp = 0.0, bool pushthrough = true)

Push a std vector of values as a sample into the outlet.

Each entry in the vector corresponds to one channel. The function handles type checking & conversion.

Parameters

  • data: A vector of values to push (one for each channel).

  • timestamp: Optionally the capture time of the sample, in agreement with local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the sample through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_sample(const float *data, double timestamp = 0.0, bool pushthrough = true)

Push a pointer to some values as a sample into the outlet.

This is a lower-level function for cases where data is available in some buffer. Handles type checking & conversion.

Parameters

  • data: A pointer to values to push. The number of values pointed to must not be less than the number of channels in the sample.

  • timestamp: Optionally the capture time of the sample, in agreement with local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the sample through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

template<class T>
void push_numeric_struct(const T &sample, double timestamp = 0.0, bool pushthrough = true)

Push a packed C struct (of numeric data) as one sample into the outlet (search for for information on packing structs appropriately).

Overall size checking but no type checking or conversion are done.

Can not be used forvariable-size / string-formatted data.

Parameters

  • sample: The sample struct to push.

  • timestamp: Optionally the capture time of the sample, in agreement with local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the sample through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_numeric_raw(const void *sample, double timestamp = 0.0, bool pushthrough = true)

Push a pointer to raw numeric data as one sample into the outlet.

This is the lowest-level function; performns no checking whatsoever. Can not be used for variable-size / string-formatted channels.

Parameters

  • sample: A pointer to the raw sample data to push.

  • timestamp: Optionally the capture time of the sample, in agreement with local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the sample through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

template<class T>
void push_chunk(const std::vector<T> &samples, double timestamp = 0.0, bool pushthrough = true)

Push a chunk of samples (batched into an STL vector) into the outlet.

Parameters

  • samples: A vector of samples in some supported format (each sample can be a data pointer, data array, or std vector of data).

  • timestamp: Optionally the capture time of the most recent sample, in agreement with local_clock(); if omitted, the current time is used. The time stamps of other samples are automatically derived according to the sampling rate of the stream.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

template<class T>
void push_chunk(const std::vector<T> &samples, const std::vector<double> &timestamps, bool pushthrough = true)

Push a chunk of samples (batched into an STL vector) into the outlet.

Allows to specify a separate time stamp for each sample (for irregular-rate streams).

Parameters

  • samples: A vector of samples in some supported format (each sample can be a data pointer, data array, or std vector of data).

  • timestamps: A vector of capture times for each sample, in agreement with local_clock().

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

template<class T>
void push_chunk_numeric_structs(const std::vector<T> &samples, double timestamp = 0.0, bool pushthrough = true)

Push a chunk of numeric data as C-style structs (batched into an STL vector) into the outlet.

This performs some size checking but no type checking. Can not be used for variable-size / string-formatted data.

Parameters

  • samples: A vector of samples, as C structs.

  • timestamp: Optionally the capture time of the sample, in agreement with local_clock(); if omitted, the current time is used.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

template<class T>
void push_chunk_numeric_structs(const std::vector<T> &samples, const std::vector<double> &timestamps, bool pushthrough = true)

Push a chunk of numeric data from C-style structs (batched into an STL vector), into the outlet.

This performs some size checking but no type checking. Can not be used for variable-size / string-formatted data.

Parameters

  • samples: A vector of samples, as C structs.

  • timestamps: A vector of capture times for each sample, in agreement with local_clock().

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_chunk_multiplexed(const std::vector<float> &buffer, const std::vector<double> &timestamps, bool pushthrough = true)

Push a chunk of multiplexed data into the outlet.

One timestamp per sample is provided. Allows to specify a separate time stamp for each sample (for irregular-rate streams).

Parameters

  • buffer: A buffer of channel values holding the data for zero or more successive samples to send.

  • timestamps: A buffer of timestamp values holding time stamps for each sample in the data buffer.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_chunk_multiplexed(const float *buffer, std::size_t buffer_elements, double timestamp = 0.0, bool pushthrough = true)

Push a chunk of multiplexed samples into the outlet.

Single timestamp provided. IMPORTANT: Note that the provided buffer size is measured in channel values (e.g., floats) rather than in samples.

Parameters

  • buffer: A buffer of channel values holding the data for zero or more successive samples to send.

  • buffer_elements: The number of channel values (of type T) in the buffer. Must be a multiple of the channel count.

  • timestamp: Optionally the capture time of the most recent sample, in agreement with local_clock(); if omitted, the current time is used. The time stamps of other samples are automatically derived based on the sampling rate of the stream.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

void push_chunk_multiplexed(const float *data_buffer, const double *timestamp_buffer, std::size_t data_buffer_elements, bool pushthrough = true)

Push a chunk of multiplexed samples into the outlet.

One timestamp per sample is provided. IMPORTANT: Note that the provided buffer size is measured in channel values (e.g., floats) rather than in samples.

Parameters

  • data_buffer: A buffer of channel values holding the data for zero or more successive samples to send.

  • timestamp_buffer: A buffer of timestamp values holding time stamps for each sample in the data buffer.

  • data_buffer_elements: The number of data values (of type T) in the data buffer. Must be a multiple of the channel count.

  • pushthrough: Whether to push the chunk through to the receivers instead of buffering it with subsequent samples. Note that the chunk_size, if specified at outlet construction, takes precedence over the pushthrough flag.

bool have_consumers()

Check whether consumers are currently registered.

While it does not hurt, there is technically no reason to push samples if there is no consumer.

bool wait_for_consumers(double timeout)

Wait until some consumer shows up (without wasting resources).

Return

True if the wait was successful, false if the timeout expired.

stream_info info() const

Retrieve the stream info provided by this outlet.

This is what was used to create the stream (and also has the Additional Network Information fields assigned).

~stream_outlet()

Destructor.

The stream will no longer be discoverable after destruction and all paired inlets will stop delivering data.