# Stimulus

## Functions
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_set_hold (TECELLA_HNDL h, double value, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_set (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT *segments, int segment_count, int delta_count=1, int repeat_count=1, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_set_ex (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT_EX *segments, int segment_count, int delta_count=1, int repeat_count=1, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_get (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT *segments, int segments_max, int *segments_in_stimulus, int *delta_count, int *repeat_count, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_get_ex (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT_EX *segments, int segments_max, int *segments_in_stimulus, int *delta_count, int *repeat_count, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_set_slew (TECELLA_HNDL h, int choice, int index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_set_callback (TECELLA_HNDL h, TECELLA_STIMULUS_CB f)
DLLEXPORT unsigned long long CALL | tecella_stimulus_index_sample_count (TECELLA_HNDL h, int index, double sample_period)
DLLEXPORT unsigned long long CALL | tecella_stimulus_sample_count (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT *segments, int segment_count, int delta_count, int repeat_count, double sample_period)
DLLEXPORT unsigned long long CALL | tecella_stimulus_sample_count_ex (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT_EX *segments, int segment_count, int delta_count, int repeat_count, double sample_period)
DLLEXPORT unsigned int CALL | tecella_stimulus_sample_count_partial (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT *segments, int segment_count, int delta_iteration, double sample_period)
DLLEXPORT unsigned int CALL | tecella_stimulus_sample_count_partial_ex (TECELLA_HNDL h, TECELLA_STIMULUS_SEGMENT_EX *segments, int segment_count, int delta_iteration, double sample_period)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_zap (TECELLA_HNDL h, double duration, double amplitude, int *channels=0, int channel_count=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_stimulus_steer (TECELLA_HNDL h, int stimulus_index, int destination_index, bool enable)

## Detailed Description

These functions allow you to control the holding level of the stimulus and the sequence of stimulus segments to play during acquisition. Helper functions to get the expected number of samples associated with a stimulus are available.

Additionally, ZAP functionality is accessed via tecella_stimulus_zap().

## Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_get | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT * | segments,
|  | int | segments_max,
|  | int * | segments_in_stimulus,
|  | int * | delta_count,
|  | int * | repeat_count,
|  | int | index = `0` |
| ) |  |  |

Retreives the currently programed stimulus. Note: due to precision constraints of the hardware, the stimulus returned by tecella_stimulus_get() may not exactly match the stimulus passed into tecella_stimulus_set().

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of pre-allocated segments.
  | segments_max | The maximum size of the array pointed to by segments, so the API does not write into unallocated memory.
  | segments_in_stimulus | The actual number of segments in the stimulus.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | index | Specifies which stimulus to program if multiple stimuli are supported on the device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_get_ex | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT_EX * | segments,
|  | int | segments_max,
|  | int * | segments_in_stimulus,
|  | int * | delta_count,
|  | int * | repeat_count,
|  | int | index = `0` |
| ) |  |  |

Retreives the currently programed stimulus. Note: This function has more functionality than the "non ex" version, but is more subject to change in future versions of the API. Note: due to precision constraints of the hardware, the stimulus returned by tecella_stimulus_get() may not exactly match the stimulus passed into tecella_stimulus_set().

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of pre-allocated segments.
  | segments_max | The maximum size of the array pointed to by segments, so the API does not write into unallocated memory.
  | segments_in_stimulus | The actual number of segments in the stimulus.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | index | Specifies which stimulus to program if multiple stimuli are supported on the device.

DLLEXPORT unsigned long long CALL tecella_stimulus_index_sample_count | ( | TECELLA_HNDL | h,
|  | int | index,
|  | double | sample_period |
| ) |  |  |

Returns the number of samples to expect for a given stimulus, including all delta iterations and repeat iterations.

Parameters:

  | h | A handle to an initialized device.
  | index | A stimulus index.
  | sample_period | The sample period in seconds.

Returns:
  The number of samples in the stimulus, including all repeat counts and delta counts.

DLLEXPORT unsigned long long CALL tecella_stimulus_sample_count | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT * | segments,
|  | int | segment_count,
|  | int | delta_count,
|  | int | repeat_count,
|  | double | sample_period |
| ) |  |  |

Returns the number of samples to expect for a given stimulus, including all delta iterations and repeat iterations.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | sample_period | The sample period in seconds used when acquiring. Be sure to manually include any

DLLEXPORT unsigned long long CALL tecella_stimulus_sample_count_ex | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT_EX * | segments,
|  | int | segment_count,
|  | int | delta_count,
|  | int | repeat_count,
|  | double | sample_period |
| ) |  |  |

Returns the number of samples to expect for a given stimulus, including all delta iterations and repeat iterations. Note: This function has more functionality than the "non ex" version, but is more subject to change in future versions of the API.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | sample_period | The sample period in seconds used when acquiring. Be sure to manually include any

DLLEXPORT unsigned int CALL tecella_stimulus_sample_count_partial | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT * | segments,
|  | int | segment_count,
|  | int | delta_iteration,
|  | double | sample_period |
| ) |  |  |

Returns the number of samples to expect for a given stimulus, for only a single delta iteration.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points.
  | delta_iteration | The step iteration of the stimulus used to calculate the sample count.
  | sample_period | The sample period in seconds used when acquiring.

DLLEXPORT unsigned int CALL tecella_stimulus_sample_count_partial_ex | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT_EX * | segments,
|  | int | segment_count,
|  | int | delta_iteration,
|  | double | sample_period |
| ) |  |  |

Returns the number of samples to expect for a given stimulus, for only a single delta iteration. Note: This function has more functionality than the "non ex" version, but is more subject to change in future versions of the API.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points.
  | delta_iteration | The step iteration of the stimulus used to calculate the sample count.
  | sample_period | The sample period in seconds used when acquiring.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_set | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT * | segments,
|  | int | segment_count,
|  | int | delta_count = `1`,
|  | int | repeat_count = `1`,
|  | int | index = `0` |
| ) |  |  |

Programs a stimulus into the hardware. When the stimulus is played it will iterate through all its segments. Once it finishes or is stopped, the output will go back to the holding voltage as defined by tecella_stimulus_set_hold(). Note: Currently, a stimulus must have 3 or more segments.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points. A stimulus must have 3 or more segments.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | index | Specifies which stimulus to program if multiple stimuli are supported on the device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_set_callback | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_CB | f |
| ) |  |  |

Sets the stimulus callback. The stimulus callback will be called whenever a stimulus has started during acquisition. The stimulus callback is called in the same thread as the acquire callback. Notification of stimulus start is guaranteed to occur before notification of any associated samples.

Parameters:

  | h | A handle to an initialized device.
  | f | The stimulus callback function.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_set_ex | ( | TECELLA_HNDL | h,
|  | TECELLA_STIMULUS_SEGMENT_EX * | segments,
|  | int | segment_count,
|  | int | delta_count = `1`,
|  | int | repeat_count = `1`,
|  | int | index = `0` |
| ) |  |  |

Programs a stimulus into the hardware. This function has more functionality than the "non ex" version, but is more subject to change in future versions of the API. When the stimulus is played it will iterate through all its segments. Once it finishes or is stopped, the output will go back to the holding voltage as defined by tecella_stimulus_set_hold(). Note: Currently, a stimulus must have 3 or more segments.

Parameters:

  | h | A handle to an initialized device.
  | segments | A pointer to an array of segments that define the stimulus.
  | segment_count | The number of segments to which segments points. A stimulus must have 3 or more segments.
  | delta_count | The number of times to increment a segment by the step value. After delta_count repeats, the segment goes back to it's initial value. Must be >=1.
  | repeat_count | The number of times the entire stimulus will repeat. Must be >=1.
  | index | Specifies which stimulus to program if multiple stimuli are supported on the device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_set_hold | ( | TECELLA_HNDL | h,
|  | double | value,
|  | int | index = `0` |
| ) |  |  |

Programs a simple holding voltage into the hardware. The holding voltage is defined as the voltage that is output whenever the stimulus is not playing.

Parameters:

  | h | A handle to an initialized device.
  | value | The requested holding voltage/current in Volts/Amps. Must be within the valid range for a stimulus segment.
  | index | The index of the stimulus to set the value of.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_set_slew | ( | TECELLA_HNDL | h,
|  | int | choice,
|  | int | index = `0` |
| ) |  |  |

DEPCRICATED This function is no longer supported and will be removed in the next majof version of the API. Use ex versions of the stimulus functions instead. Sets the slew rate of the stimulus / how fast the edges rise and fall.

Parameters:

  | h | A handle to an initialized device.
  | choice | 0 is the fastest, then it gets slower as the choice increases. The max value for this parameter depends on the connected hardware. Each increment may also not be linear.
  | index | The stimulus index to change the slew rate of.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_steer | ( | TECELLA_HNDL | h,
|  | int | stimulus_index,
|  | int | destination_index,
|  | bool | enable |
| ) |  |  |

Steers the stimulus to the specified distination. In most cases, the destination is a single channel. Note that this is not supported by most hardware. (As of 4/14, only Amadeus based amplifiers support this.) Check the field supports_stimulus_steering in the hwprops to see if it is supported by your device.

Parameters:

  | h | A handle to an initialized device.
  | stimulus_index | The stimulus to steer.
  | destination_index | In most cases, this is the channel to which we want to steer the stimulus.
  | enable | If false, steers the stimulus to nothing.

DLLEXPORT TECELLA_ERRNUM CALL tecella_stimulus_zap | ( | TECELLA_HNDL | h,
|  | double | duration,
|  | double | amplitude,
|  | int * | channels = `0`,
|  | int | channel_count = `0` |
| ) |  |  |

Applies a voltage pulse of a specified duration.

Parameters:

  | h | A handle to an initialized device.
  | duration | The duration of the zap in seconds. If duration is 0, zap will be held at the specified amplitude until the next call to this function.
  | amplitude | The amplitude of the zap in Volts.
  | channels | An array of channels to zap.
  | channel_count | The number of channels in channel_array.