Skip to content

usine event class

Jump to bottom
senso edited this page Jun 22, 2026 · 2 revisions

UsineEventClass Reference

#sdk #reference #class #events #audio #midi #data #color

UsineEventClass is the main data container class in the Usine SDK. It wraps a UsineEventPtr and provides methods for manipulating audio, data, MIDI, color, and text values.

Defined in: sdk/UsineEventClass.h

Overview

Events are the universal data type in Usine. Every parameter is backed by an event, and all data flows through events. An event is essentially a dynamically-sized array of float (TPrecision) values with specialized accessors for different data interpretations.

Construction & Lifecycle

UsineEventClass();                          // Default constructor (null event)
explicit UsineEventClass(UsineEventPtr e);  // Wrap existing event pointer

Note: UsineEventClass is non-copyable (copy assignment is deleted). Events are typically bound to parameters via TParamInfo::setEventClass() and managed by Usine.

Manual Event Management

void createEvent(int size);   // Allocate a new event with given size
void destroyEvent();          // Destroy the event and set to nullptr

Use createEvent/destroyEvent for temporary events (e.g., intermediate buffers in audio processing). Events bound to parameters are managed automatically.

Core Access

UsineEventPtr& event();             // Get raw event pointer
operator UsineEventPtr();           // Implicit cast to UsineEventPtr
explicit operator UsineEventPtr*(); // Explicit cast to pointer-to-pointer

Size Management

void setSize(int size);    // Set number of elements
int  getSize();            // Get number of elements
void setMaxSize(int size); // Set maximum capacity (pre-allocate)

Data Access — Single Values

void       setData(TPrecision value);   // Set the first element
TPrecision getData();                    // Get the first element

void         setColor(TUsineColor color); // Set as color value
TUsineColor  getColor();                   // Get as color value

void setPChar(AnsiCharPtr s);  // Set text value
AnsiCharPtr getPChar();        // Get text value

Data Access — Arrays

void       setArrayData(int index, TPrecision value);  // Set element at index
TPrecision getArrayData(int index);                     // Get element at index

void pushArrayData(TPrecision value);  // Append value (auto-resizes by PUSH_GRANULARITY=128)

void        setArrayColor(int index, TUsineColor color);  // Set color at index
TUsineColor getArrayColor(int index);                       // Get color at index

void           setArrayMidi(int index, TUsineMidiCode midi);  // Set MIDI code at index
TUsineMidiCode getArrayMidi(int index);                        // Get MIDI code at index

T3DPointF get3DPoint(int pointIndex);  // Get 3D point (event size must be multiple of 3)

TPrecision* getDataAddr();  // Get raw pointer to first element

Pointer Data

For ptPointer type parameters:

void* getPointerData();                // Get raw pointer data
int   getPointerDataSize();            // Get pointer data size in bytes
void  setPointerDataSize(int size);    // Set pointer data size in bytes
int   getPointerDataType();            // Get pointer data type
void  setPointerDataChanged();         // Notify Usine that pointer data changed

Event Operations

Copy & Compare

LongBool compare(UsineEventClass& e);   // Compare two events for equality
void     copyfrom(UsineEventClass& src); // Copy data from source
void     copyto(UsineEventClass& dest);  // Copy data to destination
void     concat(UsineEventClass& e);     // Append another event's data
void     shift(int n);                   // Shift values right (n>0) or left (n<0)

Arithmetic

void add(UsineEventClass& e);          // Element-wise addition
void sub(UsineEventClass& e);          // Element-wise subtraction
void mult(TPrecision factor);          // Multiply all elements by scalar
void mult(UsineEventClass& e);         // Element-wise multiplication
void div(UsineEventClass& e);          // Element-wise division
void mod(UsineEventClass& e);          // Element-wise modulo
void power(UsineEventClass& e);        // Element-wise power

Math Functions

void exp();           // Exponential of all elements (in-place)
void sqrt();          // Square root of all elements (in-place)
TPrecision max();     // Get maximum value
TPrecision min();     // Get minimum value
void tresh(TPrecision min, TPrecision max);  // Clamp values to range

Audio-Specific

void multAudio(UsineEventClass& e);   // Multiply audio events (optimized)
void fadeIn();                         // Apply fade-in envelope
void fadeOut();                        // Apply fade-out envelope
void clearAudio();                     // Zero audio with denormalization
void denormalizeAudio();               // Add tiny value to prevent denormals

MIDI

void mixMidi(UsineEventClass& e);  // Mix MIDI events together

Smoothing

void smooth(TPrecision& oldValue, TPrecision factor);
// Smooth a single value: oldValue += (getData() - oldValue) * factor

void smooth(TPrecision& oldValue, TPrecision target, TPrecision factor);
// Smooth towards target: oldValue += (target - oldValue) * factor

Smoothing Factor Constants

Constant Value Description
SMOOTH_VERY_VERY_SLOW 0.00001f Extremely slow smoothing
SMOOTH_VERY_SLOW 0.0001f Very slow smoothing
SMOOTH_SLOW 0.001f Slow smoothing
SMOOTH_NORMAL 0.005f Normal smoothing
SMOOTH_FAST 0.01f Fast smoothing
SMOOTH_VERY_FAST 0.05f Very fast smoothing
SMOOTH_VERY_VERY_FAST 0.1f Extremely fast smoothing
SMOOTH_NO_SMOOTH 1.0f No smoothing (instant)

Usage Examples

Basic Data Processing

See DataMultiply for a complete example.

UsineEventClass input, output;

// In onProcess:
float value = input.getData();
output.setData(value * 2.0f);

Audio Processing

See AudioVolume for a complete example.

UsineEventClass audioIn, audioOut, gain;

// In onProcess:
audioOut.copyfrom(audioIn);
audioOut.multAudio(gain);

Array Manipulation

UsineEventClass arrayEvt;

arrayEvt.createEvent(10);
for (int i = 0; i < 10; i++)
    arrayEvt.setArrayData(i, (float)i);

float val = arrayEvt.getArrayData(5);  // 5.0
arrayEvt.pushArrayData(99.0f);         // appends, now size=11

MIDI Processing

See MidiTranspose for a complete example.

UsineEventClass midiIn, midiOut;

// In onProcess:
int size = midiIn.getSize();
midiOut.copyfrom(midiIn);
for (int i = 0; i < size; i++)
{
    TUsineMidiCode code = midiOut.getArrayMidi(i);
    if (code.Msg == MIDI_NOTEON)
        code.Data1 += 12;  // transpose up one octave
    midiOut.setArrayMidi(i, code);
}

Related Pages

Clone this wiki locally