Stream Outlets¶
Text here
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_tN
>
voidpush_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
>
voidpush_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
>
voidpush_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
>
voidpush_chunk
(const std::vector<T> &samples, const std::vector<double> ×tamps, 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
>
voidpush_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
>
voidpush_chunk_numeric_structs
(const std::vector<T> &samples, const std::vector<double> ×tamps, 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> ×tamps, 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.