VCV Rack API v2
rack::engine::Module Struct Reference

DSP processor instance for your module. More...

#include <Module.hpp>

Collaboration diagram for rack::engine::Module:
[legend]

Classes

struct  AddEvent
 
struct  BypassEvent
 
struct  BypassRoute
 
struct  Expander
 Represents a message-passing channel for an adjacent module. More...
 
struct  ExpanderChangeEvent
 
struct  PortChangeEvent
 
struct  ProcessArgs
 
struct  RandomizeEvent
 
struct  RemoveEvent
 
struct  ResetEvent
 
struct  SampleRateChangeEvent
 
struct  SaveEvent
 
struct  SetMasterEvent
 
struct  UnBypassEvent
 
struct  UnsetMasterEvent
 

Public Member Functions

 Module ()
 Constructs a Module with no params, inputs, outputs, and lights. More...
 
DEPRECATED Module (int numParams, int numInputs, int numOutputs, int numLights=0)
 Use config() instead. More...
 
virtual ~Module ()
 
void config (int numParams, int numInputs, int numOutputs, int numLights=0)
 Configures the number of Params, Outputs, Inputs, and Lights. More...
 
template<class TParamQuantity = ParamQuantity>
TParamQuantity * configParam (int paramId, float minValue, float maxValue, float defaultValue, std::string name="", std::string unit="", float displayBase=0.f, float displayMultiplier=1.f, float displayOffset=0.f)
 Helper for creating a ParamQuantity and setting its properties. More...
 
template<class TSwitchQuantity = SwitchQuantity>
TSwitchQuantity * configSwitch (int paramId, float minValue, float maxValue, float defaultValue, std::string name="", std::vector< std::string > labels={})
 Helper for creating a SwitchQuantity and setting its label strings. More...
 
template<class TSwitchQuantity = SwitchQuantity>
TSwitchQuantity * configButton (int paramId, std::string name="")
 Helper for creating a SwitchQuantity with no label. More...
 
template<class TPortInfo = PortInfo>
TPortInfo * configInput (int portId, std::string name="")
 Helper for creating a PortInfo for an input port and setting its properties. More...
 
template<class TPortInfo = PortInfo>
TPortInfo * configOutput (int portId, std::string name="")
 Helper for creating a PortInfo for an output port and setting its properties. More...
 
template<class TLightInfo = LightInfo>
TLightInfo * configLight (int lightId, std::string name="")
 Helper for creating a LightInfo and setting its properties. More...
 
void configBypass (int inputId, int outputId)
 Adds a direct route from an input to an output when the module is bypassed. More...
 
std::string createPatchStorageDirectory ()
 Creates and returns the module's patch storage directory path. More...
 
std::string getPatchStorageDirectory ()
 
plugin::ModelgetModel ()
 Getters for members. More...
 
int64_t getId ()
 
int getNumParams ()
 
ParamgetParam (int index)
 
int getNumInputs ()
 
InputgetInput (int index)
 
int getNumOutputs ()
 
OutputgetOutput (int index)
 
int getNumLights ()
 
LightgetLight (int index)
 
ParamQuantitygetParamQuantity (int index)
 
PortInfogetInputInfo (int index)
 
PortInfogetOutputInfo (int index)
 
LightInfogetLightInfo (int index)
 
ExpandergetLeftExpander ()
 
ExpandergetRightExpander ()
 
ExpandergetExpander (bool side)
 Returns the left Expander if side is false, and the right Expander if side is true. More...
 
virtual void process (const ProcessArgs &args)
 Advances the module by one audio sample. More...
 
virtual void step ()
 DEPRECATED. More...
 
virtual void processBypass (const ProcessArgs &args)
 Called instead of process() when Module is bypassed. More...
 
virtual json_t * toJson ()
 Usually you should override dataToJson() instead. More...
 
virtual void fromJson (json_t *rootJ)
 This is virtual only for the purpose of unserializing legacy data when you could set properties of the .modules[] object itself. More...
 
virtual json_t * paramsToJson ()
 Serializes the "params" object. More...
 
virtual void paramsFromJson (json_t *rootJ)
 
virtual json_t * dataToJson ()
 Override to store extra internal data in the "data" property of the module's JSON object. More...
 
virtual void dataFromJson (json_t *rootJ)
 Override to load internal data from the "data" property of the module's JSON object. More...
 
virtual void onAdd (const AddEvent &e)
 Called after adding the module to the Engine. More...
 
virtual void onRemove (const RemoveEvent &e)
 Called before removing the module from the Engine. More...
 
virtual void onBypass (const BypassEvent &e)
 Called after bypassing the module. More...
 
virtual void onUnBypass (const UnBypassEvent &e)
 Called after enabling the module. More...
 
virtual void onPortChange (const PortChangeEvent &e)
 Called after a cable connects to or disconnects from a port. More...
 
virtual void onSampleRateChange (const SampleRateChangeEvent &e)
 Called when the Engine sample rate changes, and when the Module is added to the Engine. More...
 
virtual void onExpanderChange (const ExpanderChangeEvent &e)
 Called after an expander is added, removed, or changed on either the left or right side of the Module. More...
 
virtual void onReset (const ResetEvent &e)
 Called when the user resets (initializes) the module. More...
 
virtual void onRandomize (const RandomizeEvent &e)
 Called when the user randomizes the module. More...
 
virtual void onSave (const SaveEvent &e)
 Called when the user saves the patch to a file. More...
 
virtual void onSetMaster (const SetMasterEvent &e)
 
virtual void onUnsetMaster (const UnsetMasterEvent &e)
 
virtual void onAdd ()
 DEPRECATED. More...
 
virtual void onRemove ()
 DEPRECATED. More...
 
virtual void onReset ()
 DEPRECATED. More...
 
virtual void onRandomize ()
 DEPRECATED. More...
 
virtual void onSampleRateChange ()
 DEPRECATED. More...
 
bool isBypassed ()
 
PRIVATE void setBypassed (bool bypassed)
 
PRIVATE const float * meterBuffer ()
 
PRIVATE int meterLength ()
 
PRIVATE int meterIndex ()
 
PRIVATE void doProcess (const ProcessArgs &args)
 

Static Public Member Functions

static PRIVATE void jsonStripIds (json_t *rootJ)
 

Public Attributes

Internal * internal
 
plugin::Modelmodel = NULL
 
int64_t id = -1
 Unique ID for referring to the module in the engine. More...
 
std::vector< Paramparams
 Arrays of components. More...
 
std::vector< Inputinputs
 
std::vector< Outputoutputs
 
std::vector< Lightlights
 
std::vector< ParamQuantity * > paramQuantities
 Arrays of component metadata. More...
 
std::vector< PortInfo * > inputInfos
 
std::vector< PortInfo * > outputInfos
 
std::vector< LightInfo * > lightInfos
 
Expander leftExpander
 
Expander rightExpander
 
std::vector< BypassRoutebypassRoutes
 

Detailed Description

DSP processor instance for your module.

Constructor & Destructor Documentation

◆ Module() [1/2]

rack::engine::Module::Module ( )

Constructs a Module with no params, inputs, outputs, and lights.

◆ Module() [2/2]

DEPRECATED rack::engine::Module::Module ( int  numParams,
int  numInputs,
int  numOutputs,
int  numLights = 0 
)
inline

Use config() instead.

◆ ~Module()

virtual rack::engine::Module::~Module ( )
virtual

Member Function Documentation

◆ config()

void rack::engine::Module::config ( int  numParams,
int  numInputs,
int  numOutputs,
int  numLights = 0 
)

Configures the number of Params, Outputs, Inputs, and Lights.

Should only be called from a Module subclass's constructor.

◆ configParam()

template<class TParamQuantity = ParamQuantity>
TParamQuantity * rack::engine::Module::configParam ( int  paramId,
float  minValue,
float  maxValue,
float  defaultValue,
std::string  name = "",
std::string  unit = "",
float  displayBase = 0.f,
float  displayMultiplier = 1.f,
float  displayOffset = 0.f 
)
inline

Helper for creating a ParamQuantity and setting its properties.

See ParamQuantity for documentation of arguments. Should only be called from a Module subclass's constructor.

◆ configSwitch()

template<class TSwitchQuantity = SwitchQuantity>
TSwitchQuantity * rack::engine::Module::configSwitch ( int  paramId,
float  minValue,
float  maxValue,
float  defaultValue,
std::string  name = "",
std::vector< std::string >  labels = {} 
)
inline

Helper for creating a SwitchQuantity and setting its label strings.

See ParamQuantity and SwitchQuantity for documentation of arguments. Should only be called from a Module subclass's constructor.

◆ configButton()

template<class TSwitchQuantity = SwitchQuantity>
TSwitchQuantity * rack::engine::Module::configButton ( int  paramId,
std::string  name = "" 
)
inline

Helper for creating a SwitchQuantity with no label.

Should only be called from a Module subclass's constructor.

◆ configInput()

template<class TPortInfo = PortInfo>
TPortInfo * rack::engine::Module::configInput ( int  portId,
std::string  name = "" 
)
inline

Helper for creating a PortInfo for an input port and setting its properties.

See PortInfo for documentation of arguments. Should only be called from a Module subclass's constructor.

◆ configOutput()

template<class TPortInfo = PortInfo>
TPortInfo * rack::engine::Module::configOutput ( int  portId,
std::string  name = "" 
)
inline

Helper for creating a PortInfo for an output port and setting its properties.

See PortInfo for documentation of arguments. Should only be called from a Module subclass's constructor.

◆ configLight()

template<class TLightInfo = LightInfo>
TLightInfo * rack::engine::Module::configLight ( int  lightId,
std::string  name = "" 
)
inline

Helper for creating a LightInfo and setting its properties.

For multi-colored lights, use the first lightId. See LightInfo for documentation of arguments. Should only be called from a Module subclass's constructor.

◆ configBypass()

void rack::engine::Module::configBypass ( int  inputId,
int  outputId 
)
inline

Adds a direct route from an input to an output when the module is bypassed.

Should only be called from a Module subclass's constructor.

◆ createPatchStorageDirectory()

std::string rack::engine::Module::createPatchStorageDirectory ( )

Creates and returns the module's patch storage directory path.

Do not call this method in process() since filesystem operations block the audio thread.

Throws an Exception if Module is not yet added to the Engine. Therefore, you may not call these methods in your Module constructor. Instead, load patch storage files in onAdd() and save them in onSave().

Patch storage files of deleted modules are garbage collected when user saves the patch. To allow the Undo feature to restore patch storage if the module is accidentally deleted, it is recommended to not delete patch storage in onRemove().

◆ getPatchStorageDirectory()

std::string rack::engine::Module::getPatchStorageDirectory ( )

◆ getModel()

plugin::Model * rack::engine::Module::getModel ( )
inline

Getters for members.

◆ getId()

int64_t rack::engine::Module::getId ( )
inline

◆ getNumParams()

int rack::engine::Module::getNumParams ( )
inline

◆ getParam()

Param & rack::engine::Module::getParam ( int  index)
inline

◆ getNumInputs()

int rack::engine::Module::getNumInputs ( )
inline

◆ getInput()

Input & rack::engine::Module::getInput ( int  index)
inline

◆ getNumOutputs()

int rack::engine::Module::getNumOutputs ( )
inline

◆ getOutput()

Output & rack::engine::Module::getOutput ( int  index)
inline

◆ getNumLights()

int rack::engine::Module::getNumLights ( )
inline

◆ getLight()

Light & rack::engine::Module::getLight ( int  index)
inline

◆ getParamQuantity()

ParamQuantity * rack::engine::Module::getParamQuantity ( int  index)
inline

◆ getInputInfo()

PortInfo * rack::engine::Module::getInputInfo ( int  index)
inline

◆ getOutputInfo()

PortInfo * rack::engine::Module::getOutputInfo ( int  index)
inline

◆ getLightInfo()

LightInfo * rack::engine::Module::getLightInfo ( int  index)
inline

◆ getLeftExpander()

Expander & rack::engine::Module::getLeftExpander ( )
inline

◆ getRightExpander()

Expander & rack::engine::Module::getRightExpander ( )
inline

◆ getExpander()

Expander & rack::engine::Module::getExpander ( bool  side)
inline

Returns the left Expander if side is false, and the right Expander if side is true.

◆ process()

virtual void rack::engine::Module::process ( const ProcessArgs args)
inlinevirtual

Advances the module by one audio sample.

Override this method to read Inputs and Params and to write Outputs and Lights.

◆ step()

virtual void rack::engine::Module::step ( )
inlinevirtual

DEPRECATED.

Override process(const ProcessArgs& args) instead.

◆ processBypass()

virtual void rack::engine::Module::processBypass ( const ProcessArgs args)
virtual

Called instead of process() when Module is bypassed.

Typically you do not need to override this. Use configBypass() instead. If you do override it, avoid reading param values, since the state of the module should have no effect on routing.

◆ toJson()

virtual json_t * rack::engine::Module::toJson ( )
virtual

Usually you should override dataToJson() instead.

There are very few reasons you should override this (perhaps to lock a mutex while serialization is occurring).

◆ fromJson()

virtual void rack::engine::Module::fromJson ( json_t *  rootJ)
virtual

This is virtual only for the purpose of unserializing legacy data when you could set properties of the .modules[] object itself.

Normally you should override dataFromJson(). Remember to call Module::fromJson(rootJ) within your overridden method.

◆ paramsToJson()

virtual json_t * rack::engine::Module::paramsToJson ( )
virtual

Serializes the "params" object.

◆ paramsFromJson()

virtual void rack::engine::Module::paramsFromJson ( json_t *  rootJ)
virtual

◆ dataToJson()

virtual json_t * rack::engine::Module::dataToJson ( )
inlinevirtual

Override to store extra internal data in the "data" property of the module's JSON object.

◆ dataFromJson()

virtual void rack::engine::Module::dataFromJson ( json_t *  rootJ)
inlinevirtual

Override to load internal data from the "data" property of the module's JSON object.

Not called if "data" property is not present.

◆ onAdd() [1/2]

virtual void rack::engine::Module::onAdd ( const AddEvent e)
inlinevirtual

Called after adding the module to the Engine.

◆ onRemove() [1/2]

virtual void rack::engine::Module::onRemove ( const RemoveEvent e)
inlinevirtual

Called before removing the module from the Engine.

◆ onBypass()

virtual void rack::engine::Module::onBypass ( const BypassEvent e)
inlinevirtual

Called after bypassing the module.

◆ onUnBypass()

virtual void rack::engine::Module::onUnBypass ( const UnBypassEvent e)
inlinevirtual

Called after enabling the module.

◆ onPortChange()

virtual void rack::engine::Module::onPortChange ( const PortChangeEvent e)
inlinevirtual

Called after a cable connects to or disconnects from a port.

This event is not called for output ports if a stackable cable was added/removed and did not change the port's connected state.

◆ onSampleRateChange() [1/2]

virtual void rack::engine::Module::onSampleRateChange ( const SampleRateChangeEvent e)
inlinevirtual

Called when the Engine sample rate changes, and when the Module is added to the Engine.

◆ onExpanderChange()

virtual void rack::engine::Module::onExpanderChange ( const ExpanderChangeEvent e)
inlinevirtual

Called after an expander is added, removed, or changed on either the left or right side of the Module.

◆ onReset() [1/2]

virtual void rack::engine::Module::onReset ( const ResetEvent e)
virtual

Called when the user resets (initializes) the module.

The default implementation resets all parameters to their default value, so you must call Module::onReset(e) in your overridden method if you want to keep this behavior.

◆ onRandomize() [1/2]

virtual void rack::engine::Module::onRandomize ( const RandomizeEvent e)
virtual

Called when the user randomizes the module.

The default implementation randomizes all parameters by default, so you must call Module::onRandomize(e) in your overridden method if you want to keep this behavior.

◆ onSave()

virtual void rack::engine::Module::onSave ( const SaveEvent e)
inlinevirtual

Called when the user saves the patch to a file.

If your module uses patch asset storage, make sure all files are saved in this event.

◆ onSetMaster()

virtual void rack::engine::Module::onSetMaster ( const SetMasterEvent e)
inlinevirtual

◆ onUnsetMaster()

virtual void rack::engine::Module::onUnsetMaster ( const UnsetMasterEvent e)
inlinevirtual

◆ onAdd() [2/2]

virtual void rack::engine::Module::onAdd ( )
inlinevirtual

DEPRECATED.

Override onAdd(e) instead.

◆ onRemove() [2/2]

virtual void rack::engine::Module::onRemove ( )
inlinevirtual

DEPRECATED.

Override onRemove(e) instead.

◆ onReset() [2/2]

virtual void rack::engine::Module::onReset ( )
inlinevirtual

DEPRECATED.

Override onReset(e) instead.

◆ onRandomize() [2/2]

virtual void rack::engine::Module::onRandomize ( )
inlinevirtual

DEPRECATED.

Override onRandomize(e) instead.

◆ onSampleRateChange() [2/2]

virtual void rack::engine::Module::onSampleRateChange ( )
inlinevirtual

DEPRECATED.

Override onSampleRateChange(e) instead.

◆ isBypassed()

bool rack::engine::Module::isBypassed ( )

◆ setBypassed()

PRIVATE void rack::engine::Module::setBypassed ( bool  bypassed)

◆ meterBuffer()

PRIVATE const float * rack::engine::Module::meterBuffer ( )

◆ meterLength()

PRIVATE int rack::engine::Module::meterLength ( )

◆ meterIndex()

PRIVATE int rack::engine::Module::meterIndex ( )

◆ doProcess()

PRIVATE void rack::engine::Module::doProcess ( const ProcessArgs args)

◆ jsonStripIds()

static PRIVATE void rack::engine::Module::jsonStripIds ( json_t *  rootJ)
static

Member Data Documentation

◆ internal

Internal* rack::engine::Module::internal

◆ model

plugin::Model* rack::engine::Module::model = NULL

◆ id

int64_t rack::engine::Module::id = -1

Unique ID for referring to the module in the engine.

Between 0 and 2^53 since this is serialized with JSON. Assigned when added to the engine.

◆ params

std::vector<Param> rack::engine::Module::params

Arrays of components.

Initialized with config().

◆ inputs

std::vector<Input> rack::engine::Module::inputs

◆ outputs

std::vector<Output> rack::engine::Module::outputs

◆ lights

std::vector<Light> rack::engine::Module::lights

◆ paramQuantities

std::vector<ParamQuantity*> rack::engine::Module::paramQuantities

Arrays of component metadata.

Initialized with configParam(), configInput(), configOutput(), and configLight(). LightInfos are initialized to null unless configLight() is called.

◆ inputInfos

std::vector<PortInfo*> rack::engine::Module::inputInfos

◆ outputInfos

std::vector<PortInfo*> rack::engine::Module::outputInfos

◆ lightInfos

std::vector<LightInfo*> rack::engine::Module::lightInfos

◆ leftExpander

Expander rack::engine::Module::leftExpander

◆ rightExpander

Expander rack::engine::Module::rightExpander

◆ bypassRoutes

std::vector<BypassRoute> rack::engine::Module::bypassRoutes

The documentation for this struct was generated from the following file: