yase::Container Class Reference

#include <container.hh>

Inheritance diagram for yase::Container:

Collaboration diagram for yase::Container:

Detailed Description

A module and event manager that can contain other modules.

It can be used as a top level module for constructing an entire synthesizer, or as a way to group together a few modules into a commonly used function, as with, for example a phasor which would contain a delay and a sum. A good example of a container is the Echo Module, which contains a Delay, a a Gain and a Sum. Additionally, most examples use a main container to add sub-modules to. For example, the following code sets up a Container called synth, adds a few modules to it.

// 
// YASE Example
// 
// Copyright (C) 2022 Eric Klavins
// This file is part of YASE
// 
// YASE is free software: you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the Free Software
// Foundation, either version 3 of the License, or (at your option) any later
// version.
//
// YASE is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
// details.
// 
// You should have received a copy of the GNU General Public License along
// with YASE. If not, see <https://www.gnu.org/licenses/>.
// 
 
#include "yase.hh"
 
using namespace yase;
 
int main(int argc, char * argv[]) {
 
    Sine sine1, sine2;
    Audio audio;
    Container synth;
    
    sine1.set_input("frequency", 440);
    sine2.set_input("frequency", 441);
 
    synth.connect(sine1,"signal",audio,"left")
         .connect(sine2,"signal",audio,"right");
 
    synth.run(UNTIL_INTERRUPTED);
 
    return 0; 
 
}

Public Member Functions
void	init ()
void	update ()
Container &	add (Module &module)
Container &	add_if_new (Module &module)
Container &	propagate_to (EventManager &em)
void	run (int num_steps)
void	run_again (int num_steps)
void	stop ()
Container &	connect (Module &source, string output, Module &dest, string input)
Container &	connect (Module &source, string output, Module &dest, int input)
Container &	connect (AutoLoad &loader, string category, Module &module)
Container &	connect (Module &source, Module &dest)
Container &	path (Module &a, Module &b, Module &c)
Container &	path (Module &a, Module &b, Module &c, Module &d)
Container &	path (Module &a, Module &b, Module &c, Module &d, Module &e)
Container &	disconnect (Module &source, string output, Module &dest, string input)
bool	connected (Module *module, string input_name)
Container &	equate_input (string input, Module &sub_module, string sub_input)
Container &	attach_inputs (std::vector< std::tuple< string, Module &, string > > attachments)
Container &	equate_output (string output, Module &sub_module, string sub_output)
Container &	attach_outputs (std::vector< std::tuple< string, Module &, string > > attachments)
Container &	set_thread_number (int n)
	EXPERIMENTAL.
Container &	add (Module &module, int n)
	EXPERIMENTAL.
void	run_threaded (int num_steps)
	EXPERIMENTAL.
void	update_threaded ()
	EXPERIMENTAL.
void	thread_loop (int i)
	EXPERIMENTAL.
Public Member Functions inherited from yase::Module
virtual void	init ()=0
virtual void	update ()=0
int	add_input (string name)
int	add_output (string name)
int	get_input_index (string name) const
string	get_input_name (int index) const
string	get_output_name (int index) const
int	get_output_index (string name) const
void	set_input (string name, double value)
void	set_input (int index, double value)
double	get_input (int index) const
double	get_input (string name) const
double	get_output (string name) const
double	get_output (int index) const
void	set_output (int index, double value)
void	copy_inputs (const Module &source)
void	copy_outputs (Module &destination) const
void	configure (std::vector< std::tuple< string, double > > assignments)
int	num_inputs () const
int	num_outputs () const
void	emit (Event e)
void	set_ts (double s)
double	get_ts ()
Public Member Functions inherited from yase::EventManager
	EventManager ()
	Make a new event manager.
void	process_events (vector< Module * > &modules)
void	respond_to (const Event &event)
EventManager &	listen (int event_type, function< void(const Event &)> handler)
EventManager &	listen (int event_type, int port, function< void(const Event &)> handler)

Member Function Documentation

add()

Container & yase::Container::add

(

Module &

module

)

Adds a module to the container. When the container is run, the module will be updated on each iteration. Note that if you use Module::connect to connect two modules, those modules will be automatically added so you don't need to add them with this method.

Parameters

module

The module to be added

Returns

A reference to the container for method chaining

add_if_new()

Container & yase::Container::add_if_new

(

Module &

module

)

Add if the module is not already added

Parameters

module

The module to be added

Returns

A reference to the container for method chaining

attach_inputs()

Container & yase::Container::attach_inputs

(

std::vector< std::tuple< string, Module &, string > >

attachments

)

Attach the inputs this module to the inputs of sub-modules. Calls add_input and equate_input on each tuple

Parameters

attachements

A vector of tuples of the form {{string,Module&,string}, ...}

attach_outputs()

Container & yase::Container::attach_outputs

(

std::vector< std::tuple< string, Module &, string > >

attachments

)

Attach outputs of this module to the outputs of sub-modules. Calls add_input and equate_input on each tuple

Parameters

attachements

A vector of tuples of the form {{string,Module&,string}, ...}

connect() [1/4]

Container & yase::Container::connect	(	AutoLoad &	loader,
		string	category,
		Module &	module
	)

Connect a parameter autoloader to the inputs of the given module. The autoloader should be used with a *.json file that has an object called "category" in it that in turn has keys with the same names as module. The values associated with the keys the keys should be numbers and will be connected to the modules inputs. Once configured, the user can edit the *.json file, save the changes, and the inputs to the module will be changed.

Parameters

loader	an AutoLoad object
string	the name of the category in the *.json file to use
module	The module to connect

connect() [2/4]

Container & yase::Container::connect	(	Module &	source,
		Module &	dest
	)

Connect the two modules, assuming the output and input are called "signal" NOTE: This method has the side effect that it adds both source and dest to the container, if they are not alreaddy added

Parameters

source	The source module
dest	The desintation module

Returns

A reference to the container for method chaining

connect() [3/4]

Container & yase::Container::connect	(	Module &	source,
		string	output,
		Module &	dest,
		int	input
	)

Connect the source output to the destination input with a virtual wire. Upon each update, the container will first copy the output of source to the input of destination, and then it will update the modules. NOTE: This method has the side effect that it adds both source and dest to the container, if they are not alreaddy added

Parameters

source	The source module
output	The name of the output of the source module
dest	The desintation module
input	The index of the input of the desintation module

Returns

A reference to the container for method chaining

connect() [4/4]

Container & yase::Container::connect	(	Module &	source,
		string	output,
		Module &	dest,
		string	input
	)

Connect the source output to the destination input with a virtual wire. Upon each update, the container will first copy the output of source to the input of destination, and then it will update the modules. NOTE: This method has the side effect that it adds both source and dest to the container, if they are not alreaddy added

Parameters

source	The source module
output	The name of the output of the source module
dest	The desintation module
input	The name of the input of the desintation module

Returns

A reference to the container for method chaining

connected()

bool yase::Container::connected	(	Module *	module,
		string	input_name
	)

Test whether the in put to module is connected to another module

Parameters

source	The module
output	The name of the input to the module

disconnect()

Container & yase::Container::disconnect	(	Module &	source,
		string	output,
		Module &	dest,
		string	input
	)

Remove a connection

Parameters

source	The source module
output	The name of the output of the source module
dest	The desintation module
input	The name of the input of the desintation module

equate_input()

Container & yase::Container::equate_input	(	string	input,
		Module &	sub_module,
		string	sub_input
	)

Equate the main input of this module to the sub-input of the sub-module. Whenever the main module's input is updated, the sub-modules input will also be updated.

Parameters

input	A string identifying the main input
sub_module	A reference to the sub-module
sub_input	A string identifying the sub-module input

equate_output()

Container & yase::Container::equate_output	(	string	output,
		Module &	sub_module,
		string	sub_output
	)

Equate the main output of this module to the sub-output of the sub-module. After the sub-module has been updated, it's output will by copied to the main module output.

Parameters

output	A string identifying the main output
sub_module	A reference to the sub-module
sub_output	A string identifying the sub-module output

init()

void yase::Container::init ( )

virtual

This method should be overridden by derived classes. It will usually be called once, after all modules and connections objects have been added to a synthesizer, but before the synthesizer starts running.

Implements yase::Module.

Reimplemented in yase::Controls, yase::Echo, yase::FadableDelay, yase::MidiToAnalog, and yase::Mix.

path() [1/3]

Container & yase::Container::path	(	Module &	a,
		Module &	b,
		Module &	c
	)

Connect the three modules into a path, assuming the outputs and inputs are called "signal" NOTE: This method has the side effect that it adds all modules container, if they are not alreaddy added

Parameters

a	The first module
b	The second module
c	The third module

Returns

A reference to the container for method chaining

path() [2/3]

Container & yase::Container::path	(	Module &	a,
		Module &	b,
		Module &	c,
		Module &	d
	)

Connect the four modules into a path, assuming the outputs and inputs are called "signal" NOTE: This method has the side effect that it adds all modules container, if they are not alreaddy added

Parameters

a	The first module
b	The second module
c	The third module
d	The fourth module

Returns

A reference to the container for method chaining

path() [3/3]

Container & yase::Container::path	(	Module &	a,
		Module &	b,
		Module &	c,
		Module &	d,
		Module &	e
	)

Connect the four modules into a path, assuming the outputs and inputs are called "signal" NOTE: This method has the side effect that it adds all modules container, if they are not alreaddy added

Parameters

a	The first module
b	The second module
c	The third module
d	The fourth module
e	The fifth module

Returns

A reference to the container for method chaining

propagate_to()

Container & yase::Container::propagate_to

(

EventManager &

em

)

Tell the container to propagate all events to another event manager. Thus, if some module contained within the container emits an event, the event manager em will hear the event too. Usually used in conjunction with add().

Parameters

em	The event manager (another module) that should receive events

Returns

A reference to the container for method chaining

In the following example, a Controls object is constructed, added, and propagated to. When MidiEvents are received by the container, they are sent to the control, which responds to them by adjusting the associated input.

// 
// YASE Example
// 
// Copyright (C) 2022 Eric Klavins
// This file is part of YASE
// 
// YASE is free software: you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the Free Software
// Foundation, either version 3 of the License, or (at your option) any later
// version.
//
// YASE is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
// details.
// 
// You should have received a copy of the GNU General Public License along
// with YASE. If not, see <https://www.gnu.org/licenses/>.
// 
 
#include <iostream>
#include "yase.hh"
 
using namespace yase;
 
int main(int argc, char * argv[]) {
 
    Saw osc1;
    Saw osc2;
    Controls controls;
    Audio audio;
    MidiInput midi("Arturia MiniLab mkII");
    Container synth;
 
    osc1.set_input("frequency", 55);
    osc2.set_input("frequency", 55);
 
    synth.add(midi)
         .add(controls) 
         .propagate_to(controls);
 
    synth.connect(osc1,"signal",audio,"left")
         .connect(osc2,"signal",audio,"right");
 
    controls.map(osc1, "frequency", 55, 110, 74)
            .map(osc2, "frequency", 55, 110, 71);
 
    synth.run(UNTIL_INTERRUPTED);
 
    return 0;
 
}

run()

void yase::Container::run

(

int

num_steps

)

Run the container for the indicated number of steps. Use -1 or UNTIL_INTERRUPTED for the number of steps to run until interupted by Ctrl-C.

Parameters

The	number of steps argument to run the container.

run_again()

void yase::Container::run_again

(

int

num_steps

)

Continue running assuming the container has already been run for some amount of time. Contained Module init() methods will not be called again. Will run for the indicated number of steps. Use -1 or UNTIL_INTERRUPTED for the number of steps arrgument to run until interupted by Ctrl-C.

Parameters

The	number of steps to run the container.

update()

void yase::Container::update ( )

virtual

This method should be overridden by derived classes. It will be called repeatedly by a synthesizer at a frequency determined by SAMPLE_RATE.

Implements yase::Module.

Reimplemented in yase::Controls, yase::Echo, yase::FadableDelay, yase::MidiToAnalog, and yase::Mix.

---

The documentation for this class was generated from the following files:

• include/container.hh
• src/container.cc