# 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.