TimeSliceField

This field unit stores a series of values collected over time, which can then be sampled spatially like an array across the normalized range [0, 1]. It is useful for plotting time-varying signals, such as mapping audio or sensor input onto an LED strip or a motor array.

The unit gathers samples over a defined time period, storing them in its internal memory. When it is ready to be read, it fires an updated event which can be used to update outputs only when necessary.

The size SIZE of the internal memory (ie., the number of values that are stored internally) and the overall time period (in seconds) over which the field applies is specified at creation time:

TimeSliceField<SIZE> field(period);
The unit supports two modes:

  1. In the block mode (default) the buffer fills up and fires the updated event when it is full; then it is emptied and starts filling up again.

  2. In the rolling mode the buffer fills up, then…

  • … when it is full it fires updated;

  • … when enough time has passed that a new value needs to be replaced, the older value is removed and the buffer is shifted by one value and it fires updated to signal a change.

Example

Here is a simple example that uses a TimeSliceField to collect data from a sine wave and render it to an LED strip.

#include <Plaquette.h>

// The number of LEDs.
const int N_LEDS = 8;

// An array of LEDs.
DigitalOut leds[] = { 2, 3, 4, 5, 6, 7, 8, 9 }; // shorthand for DigitalOut leds[] = { DigitalOut(2), DigitalOut(3), DigitalOut(4), ... };

// The sine wave with a period of one second.
Wave wave(SINE, 1.0f);

// The time slice field (over 2 seconds period).
TimeSliceField<N_LEDS> timeSlice(2.0f);

void begin() {
  // Set field to rolling mode.
  timeSlice.rolling();
}

void step() {
  // Update the field.
  wave >> timeSlice;

  // Update the LEDs.
  if (timeSlice.updated()) {
    for (int i=0; i<N_LEDS; i++) {
      float proportion = mapTo01(i, 0, N_LEDS-1); // maps i to [0, 1]
      timeSlice.at(proportion) >> leds[i]; // send to LED
    }
  }
}

Reference

template<size_t COUNT>
class TimeSliceField : public AbstractField

TimeSliceField generic class.

Template Parameters

COUNT – the size of the buffer

Public Functions

inline TimeSliceField(float period)

Constructor.

Parameters

period – the period in seconds

inline virtual ~TimeSliceField()
inline virtual float at(float proportion) override

Returns value at given proportion in [0, 1].

Parameters

proportion – the proportion of the field to read

Returns

the value

inline virtual float get() override

Returns value.

inline virtual float put(float value) override

Pushes value into the unit.

Parameters

value – the value sent to the unit

Returns

the new value of the unit

inline void period(float period)

Sets period over which the time slice occurs.

Parameters

period – the new period (in seconds)

inline float period() const

Returns period.

inline float atIndex(size_t index)

Returns value at given index.

inline size_t count() const

Returns count.

inline bool updated()

Returns true if the field has been updated and is ready to be used.

inline bool isFull()

Returns true if the field is full.

inline void reset()

Resets the field.

inline void setRolling(bool rolling)

Sets rolling mode.

Parameters

rolling – the rolling mode

inline void rolling()

Activates rolling mode.

inline void noRolling()

Deactivates rolling mode.

inline bool isRolling() const

Returns true if rolling mode is active.

inline virtual void onUpdate(EventCallback callback)

Registers event callback on update event.

template<typename T>
inline void populate(T *array, size_t size, bool wrap = false)

Fills an array with values from this field.

Parameters

  • array – the array to read into

  • size – the size of the array

  • wrap – if true, the array is considered to be a circular buffer that wraps around

virtual void clearEvents()
inline float seconds() const

Returns engine time in seconds.

inline uint32_t milliSeconds() const

Returns engine time in milliseconds.

inline uint64_t microSeconds() const

Returns engine time in microseconds.

inline unsigned long nSteps() const

Returns number of engine steps.

inline float sampleRate() const

Returns engine sample rate.

inline float samplePeriod() const

Returns enginesample period.

inline operator float()

Object can be used directly to access its value.

inline virtual float mapTo(float toLow, float toHigh)

Maps value to new range.

This function guarantees that the value is within [toLow, toHigh]. If the unit’s values are unbounded, returns get() constrained to [toLow, toHigh].

inline explicit operator bool()

Operator that allows usage in conditional expressions.

Public Static Functions

static inline bool analogToDigital(float f)

Converts analog (float) value to digital (bool) value.

static inline float digitalToAnalog(bool b)

Converts digital (bool) value to analog (float) value.

See Also