Acquisition


Functions

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_callback (TECELLA_HNDL h, TECELLA_ACQUIRE_CB f, unsigned int period=1024)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_enable_channel (TECELLA_HNDL h, int channel, bool enable)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_enable_auto_zero (TECELLA_HNDL h, int channel, bool enable, int window_size)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_buffer_size (TECELLA_HNDL h, unsigned int samples_per_chan)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_trigger_in_mode (TECELLA_HNDL h, bool active_high, double debounce_delay)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start (TECELLA_HNDL h, int sample_period_multiplier, bool continuous=false, bool start_stimuli=true, bool continuous_stimuli=false, bool start_on_trigger=false)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start_stimulus (TECELLA_HNDL h, int stimulus_index, bool start=true, bool continuous=false, int sample_period_multiplier=1)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start_stimuli (TECELLA_HNDL h, int *stimulus_indexes, int stimulus_count, bool start=true, bool continuous=false, int sample_period_multiplier=1)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_stop_stimulus (TECELLA_HNDL h, int stimulus_index, bool continuous=false)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_stop (TECELLA_HNDL h)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_samples_available (TECELLA_HNDL h, int chan, unsigned int *samples_available)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_d (TECELLA_HNDL h, int chan, int requested_samples, double *data, unsigned int *actual_samples, unsigned long long *first_sample_timestamp, bool *last_sample_flag)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_f (TECELLA_HNDL h, int chan, int requested_samples, float *data, unsigned int *actual_samples, unsigned long long *first_sample_timestamp, bool *last_sample_flag)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_i (TECELLA_HNDL h, int chan, int requested_samples, short *data, unsigned int *actual_samples, unsigned long long *first_sample_timestamp, bool *last_sample_flag)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_clip_detect (TECELLA_HNDL h, int chan, bool *clipping_detected)
DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_i2d_scale (TECELLA_HNDL h, int chan, double *scale)

Detailed Description

Acquisition can be started or stopped simply by calling tecella_acquire_start() and tecella_acquire_stop().

The samples can be read in many different formats including raw, unscaled 16-bit integers (tecella_acquire_read_i()), 32-bit floats (tecella_acquire_read_f()), and 64-bit doubles (tecella_acquire_read_d()). If reading the samples as 16-bit integers, you can scale to the proper units by using the scale returned by tecella_acquire_i2d_scale().

If you do not need asynchronous control of multiple stimuli, you do not need to worry about the tecella_acquire_start_stimulus() and tecella_acquire_stop_stimulus() functions.

Note: TecellaAmp allows you to use callbacks to get notifications of when samples are available, but it is more straightforward to call tecella_acquire_read() in a blocking fashion if possible.

Note: If you are receiving any software buffer overflow errors, you may want to increase the software buffer sizes via tecella_acquire_set_buffer_size().


Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_enable_auto_zero ( TECELLA_HNDL  h,
int  channel,
bool  enable,
int  window_size 
)

Enables or disables auto-zero for a channel. A window of initial samples is averaged to offset the entire acquisition, such that the window of samples average out to zero.

Parameters:
h A handle to an initialized device.
channel The channel to enable or disable.
enable If true, enable auto zero.
window_size The number of initial samples to average for the new zero level.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_enable_channel ( TECELLA_HNDL  h,
int  channel,
bool  enable 
)

Enables or disables acquisition for a channel. All channels are enabled by default.

Parameters:
h A handle to an initialized device.
channel The channel to enable or disable.
enable If true, capture. If false, don't.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_i2d_scale ( TECELLA_HNDL  h,
int  chan,
double *  scale 
)

Gets the current multiplier used to convert a 16 bit short sample to Amps.

Parameters:
h A handle to an initialized device.
chan The specified channel. TECELLA_ALLCHAN cannot be used with this function.
scale The return argument for the Amp multiplier.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_clip_detect ( TECELLA_HNDL  h,
int  chan,
bool *  clipping_detected 
)

Determines if clipping has been detected since the last time this function was called for a given channel. If this function returns clipping_detected as true, subsequent calls to this function will return clipping_detected as false unless clipping has been detected again.

Parameters:
h A handle to an initialized device.
chan The specified channel. TECELLA_ALLCHAN cannot be used with this function.
clipping_detected Returns true if clipping has been detected since the last time this function was called.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_d ( TECELLA_HNDL  h,
int  chan,
int  requested_samples,
double *  data,
unsigned int *  actual_samples,
unsigned long long *  first_sample_timestamp,
bool *  last_sample_flag 
)

Reads samples from the queue as double-precision floats whose units are in Amps. Once the requested data has been returned, it no longer resides in the queue and cannot be retrieved again. All samples returned by a single call are continuous. A call to this function will block until the number of requested_samples are available or until acqusition is complete. To ensure this function is a non-blocking request use the number of samples returned by tecella_acquire_samples_available(). To recover from any acquisition error, call tecella_acquire_stop() and tecella_acquire_start() again. It is not necessary to re-initialize the entire hardware.

Parameters:
h A handle to an initialized device.
chan The specified channel. TECELLA_ALLCHAN cannot be used with this function.
requested_samples The number of samples the user would like to have copied to data.
data A pointer to an array of doubles, at least of size requested_samples.
actual_samples Used to return how many samples were actually acquired, in the case acquisition is complete.
first_sample_timestamp Timestamp of the first sample. The timestamp increments by 1 for each sample period after the last call to tecella_acquire_start(). (To be implemented.)
last_sample_flag Indicates breaks in acquisition (samples after the last sample returned will not be captured). To be implemented.
Returns:
TECELLA_ERR_OK If the read completed successfully.

TECELLA_ERR_SW_BUFFER_OVERFLOW If the software buffers have been filled.

TECELLA_ERR_HW_BUFFER_OVERFLOW If the hardware buffers have overflowed.

TECELLA_ERR_ACQ_CRC_FAILED If the data stream was corrupted. (Not implemented yet)

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_f ( TECELLA_HNDL  h,
int  chan,
int  requested_samples,
float *  data,
unsigned int *  actual_samples,
unsigned long long *  first_sample_timestamp,
bool *  last_sample_flag 
)

Reads samples from the queue as single-precision floats whose units are in Amps. Same as tecella_acquire_read_d, but for single-precision floats.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_read_i ( TECELLA_HNDL  h,
int  chan,
int  requested_samples,
short *  data,
unsigned int *  actual_samples,
unsigned long long *  first_sample_timestamp,
bool *  last_sample_flag 
)

Reads samples from the queue as 16 bit integers whose units can be retrieved using tecella_acquire_i2d_scale(). Once the requested data has been returned, it no longer resides in the queue and cannot be retrieved again. A call to this function will block until the number of requested_samples are available or until acqusition is complete. To ensure this function is a non-blocking request use the number of samples returned by tecella_acquire_samples_available(). To recover from any acquisition error, call tecella_acquire_stop() and tecella_acquire_start() again. It is not necessary to re-initialize the entire hardware.

Parameters:
h A handle to an initialized device.
chan The specified channel. TECELLA_ALLCHAN cannot be used with this function.
requested_samples The number of samples the user would like to have copied to data.
data A pointer to an array of shorts, at least of size requested_samples.
actual_samples Used to return how many samples were actually acquired, in the case acquisition is complete.
first_sample_timestamp Timestamp of the first sample. The timestamp increments by 1 for each sample period after the last call to tecella_acquire_start(). (To be implemented.)
last_sample_flag Indicates breaks in acquisition (samples after the last sample returned will not be captured). To be implemented.
Returns:
TECELLA_ERR_OK If the read completed successfully.

TECELLA_ERR_SW_BUFFER_OVERFLOW If the software buffers have been filled.

TECELLA_ERR_HW_BUFFER_OVERFLOW If the hardware buffers have overflowed.

TECELLA_ERR_ACQ_CRC_FAILED If the data stream was corrupted. (Not implemented yet)

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_samples_available ( TECELLA_HNDL  h,
int  chan,
unsigned int *  samples_available 
)

Gets the current number of samples in the queue for the given channel.

Parameters:
h A handle to an initialized device.
chan The specified channel. If TECELLA_ALLCHAN is specified, this function returns the minimum samples available across all channels.
samples_available The number of samples available are returned in this variable.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_buffer_size ( TECELLA_HNDL  h,
unsigned int  samples_per_chan 
)

Pre-allocates an internal per-channel software queue for acquisition.

Parameters:
h A handle to an initialized device.
samples_per_chan Maximum number of samples per channel to allow in the queue.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_callback ( TECELLA_HNDL  h,
TECELLA_ACQUIRE_CB  f,
unsigned int  period = 1024 
)

Sets a callback function to be called whenever there is new data for any channel.

Parameters:
h A handle to an initialized device.
f The acquire callback function.
period The number of samples received in a channel before a notification is sent. The number of samples notified may be less if any stimulus starts before the period has been reached or if acquisition has stopped for a particular channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_set_trigger_in_mode ( TECELLA_HNDL  h,
bool  active_high,
double  debounce_delay 
)

Sets the trigger in mode.

Parameters:
h A handle to an initialized device.
active_high If true, trigger in occurs when going from low to high. If false, trigger in occurs when going from high to low.
debounce_delay The trigger in must be high for at least this long before it is concidered true. Units are in seconds.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start ( TECELLA_HNDL  h,
int  sample_period_multiplier,
bool  continuous = false,
bool  start_stimuli = true,
bool  continuous_stimuli = false,
bool  start_on_trigger = false 
)

Sets up an acquisition and returns once the acquisition has begun. When the function returns, an internal thread runs asynchronously that constantly pulls data from the device and pushes it into the internal queue.

Parameters:
h A handle to an initialized device.
sample_period_multiplier The actual sample period used will be sample_period_min times sample_peiriod_multiplier.
continuous If true, acquisition continues until tecella_acquire_stop() is called. If false, acquisition continues for as long as the longest programmed stimulus or until tecella_acquire_stop() is called.
start_stimuli If true, all stimuli start playing at the start of acquisition and also capture continuously if continuous_stimuli is ture. To use different options for different stimuli set both continuous_stimuli and start_stimuli to false and call tecella_acquire_start_stimulus() for each stimulus before calling tecella_acquire_start().
continuous_stimuli Valid only if continuous is true. If true, all stimuli will capture continuously and also start playing if start_stimuli is true. To use different options for different stimuli set both continuous_stimuli and start_stimuli to false and call tecella_acquire_start_stimulus() for each stimulus before calling tecella_acquire_start().
start_on_trigger If true, acquisition will not start until an external hardware trigger is detected.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start_stimuli ( TECELLA_HNDL  h,
int *  stimulus_indexes,
int  stimulus_count,
bool  start = true,
bool  continuous = false,
int  sample_period_multiplier = 1 
)

Starts one or more stimuli and starts acquiring data for the associated channels that are also enabled. tecella_acquire_start() must be called first, with continuous=true. There are three modes available when calling tecella_acquire_start_stimuli(): Mode0) If start=false and continuous=false, tecella_acquire_start_stimuli does nothing. Mode1) If start=false and continuous=true, you can acquire data continuously without starting the stimulus. Mode2) If start=true and continuous=false, only the samples that are part of the stimulus will be acquired. Mode3) If start=true and continuous=true, acquisition will start when the stimulus starts but then continue acquiring after the stimulus has ended, until tecella_acquire_stop_stimulus() is called.

Parameters:
h A handle to an initialized device.
stimulus_indexes A pointer to an array of stimulus indexes to start acquiring for.
stimulus_count The size of the array pointed to by stimulus_indexes.
start If true, the vcmd plays at the start of acquisition.
continuous If true, acquisition starts and continues until tecella_acquire_stop_stimulus() is called. If false, acquisition only occurs while the stimlus is playing or until tecella_acquire_stop() is called.
sample_period_multiplier Multiplies the base sample period (specified in tecella_acquire_start()) by this number.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_start_stimulus ( TECELLA_HNDL  h,
int  stimulus_index,
bool  start = true,
bool  continuous = false,
int  sample_period_multiplier = 1 
)

Starts a stimulus and starts acquiring data for the associated channels that are also enabled. tecella_acquire_start() must be called first, with continuous=true. There are three modes available when calling tecella_acquire_start_stimulus(): Mode0) If start=false and continuous=false, tecella_acquire_start_stimulus does nothing. Mode1) If start=false and continuous=true, you can acquire data continuously without starting the stimulus. Mode2) If start=true and continuous=false, only the samples that are part of the stimulus will be acquired. Mode3) If start=true and continuous=true, acquisition will start when the stimulus starts but then continue acquiring after the stimulus has ended, until tecella_acquire_stop_stimulus() is called.

Parameters:
h A handle to an initialized device.
stimulus_index The stimulus to start acquiring for.
start If true, the vcmd plays at the start of acquisition.
continuous If true, acquisition starts and continues until tecella_acquire_stop_stimulus() is called. If false, acquisition only occurs while the stimlus is playing or until tecella_acquire_stop() is called.
sample_period_multiplier Multiplies the base sample period (specified in tecella_acquire_start()) by this number.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_stop ( TECELLA_HNDL  h  ) 

Stops the current acquistion and all stimuli. Sends a message to the acquisition thread to stop and returns immediately.

Parameters:
h A handle to an initialized device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_acquire_stop_stimulus ( TECELLA_HNDL  h,
int  stimulus_index,
bool  continuous = false 
)

Stops a stimulus and stops acquiring data for the associated channels that are also enabled. Valid only in asynchronous stimulus mode.

Parameters:
h A handle to an initialized device.
stimulus_index The stimulus to stop.
continuous If true, associated channels will continue acquiring even after stimulus has stopped.


Generated on Sat Mar 11 11:22:08 2017 for Tecella Amp by  doxygen 1.5.8