Klang C++ 0.7.15
Language Reference (draft)
Loading...
Searching...
No Matches
klang::Function< Args >

Language Guide / Functions

Function

klang::Function

Wraps a callable as a Klang signal-flow stage.

Use Function<Args...> when a C++ calculation should sit in a signal chain. The template arguments are the callable’s input types, in order. The callable returns a value convertible to float, and the stage exposes its result as a signal. A function pointer can also supply the template arguments by deduction.

Define and route a unary function

This effect constructs a Function<float> from a static C++ function with one input. in >> shape >> out supplies the first argument, evaluates the callable and routes the result. Keep the wrapper as a member and reuse it as samples arrive.

struct Shaper : Effect {
    static float hardclip(float x) {
        return clamp(x, -1.0, 1.0);
    }

    Function<float> shape;

    Shaper() : shape(hardclip) {
    }

    void process() {
        in >> shape >> out;
    }
};

Supply the remaining arguments

For a function such as shape(x, drive), the signal arriving from the left supplies x. Pass drive with shape(drive), or use shape.with(drive) to make the binding explicit. Both forms configure the same stage. Supply one value for each argument after the first.

struct DrivenShape : Effect {
    static float softclip(float x, float drive) {
        return tanh(x * drive);
    }

    Function<float, float> shape;

    DrivenShape() : shape(softclip) {
    }

    void process() {
        in >> shape(4) >> out;
    }
};

Use this expression in process() for the equivalent explicit binding.

in >> shape.with(4) >> out;

To evaluate a mutable wrapper directly, supply all the arguments and call evaluate() to get the result as a signal. A const wrapper can evaluate a full argument list directly and return a float.

const signal sample = shape(0.25, 4).evaluate();

Plot the same calculation

Send a configured wrapper to Graph to see its response. The graph sweeps the first argument across its horizontal axis and uses the arguments supplied through with() for the rest.

Applies a function to a signal (input-output) More...

#include <klang.h>

+ Inheritance diagram for klang::Function< Args >:

Public Member Functions

 Function ()
 
 Function (std::function< float(Args...)> function)
 
 operator signal ()
 
 operator param ()
 
 operator float ()
 
unsigned int args () const
 
std::tuple< Rest... > tail (const std::tuple< First, Rest... > &t) const
 
void input () override
 
virtual const signal & input () const
 
virtual void input (const signal &source)
 
First & first (First &first, Rest...)
 
const First & first (const First &first, Rest...) const
 
Function< signal, Args... > & operator() (const FuncArgs &... args)
 
const float operator() (const FuncArgs &... args) const
 
Modifier< signal > & operator() (params &&... p)
 
Function< signal, Args... > & with (FuncArgs... args)
 
signal evaluate () const
 
virtual void process () override
 
klang::Graph & operator>> (klang::Graph &graph)
 
klang::GraphPtr & operator>> (klang::GraphPtr &graph)
 
TYPE & operator>> (TYPE &destination)
 
 operator const signal & () override
 
 operator const signal & () const override
 
virtual void operator<< (const signal &source)
 
virtual const signal & output () const
 
signal operator+ (TYPE &other)
 
signal operator* (TYPE &other)
 
signal operator- (TYPE &other)
 
signal operator/ (TYPE &other)
 
void reset ()
 

Public Attributes

std::function< float(Args...)> function
 
std::tuple< Args... > inputs
 
signal in
 
signal out
 

Static Public Attributes

static constexpr unsigned int ARGS
 

Detailed Description

template<typename... Args>
struct klang::Function< Args >

Definition at line 3735 of file klang.h.

Constructor & Destructor Documentation

◆ Function() [1/2]

template<typename... Args>
klang::Function< Args >::Function ( )
inline

Definition at line 3741 of file klang.h.

3741: Generic::Function<signal, Args...>(nullptr) {}
Function() -> Function< signal, Args... >
signals< 2 > signal
Stereo audio signal.
Definition klang.h:5840

◆ Function() [2/2]

template<typename... Args>
klang::Function< Args >::Function ( std::function< float(Args...)> function)
inline

Definition at line 3743 of file klang.h.

3743: Generic::Function<signal, Args...>(function) {}
std::function< float(Args...)> function
Definition klang.h:3173

Member Function Documentation

◆ args()

unsigned int klang::Generic::Function< signal, Args >::args ( ) const
inlineinherited

Definition at line 3176 of file klang.h.

3176{ return ARGS; }
static constexpr unsigned int ARGS
Definition klang.h:3175

◆ evaluate()

signal klang::Generic::Function< signal, Args >::evaluate ( ) const
inlineinherited

Definition at line 3289 of file klang.h.

3289 {
3290 if (!function)
3291 return 0.f;
3292 if constexpr (ARGS > 1)
3293 return std::apply(function, inputs);
3294 else
3295 return (signal)function(in);
3296 }

◆ first() [1/2]

const First & klang::Generic::Function< signal, Args >::first ( const First & first,
Rest...  ) const
inlineinherited

Definition at line 3210 of file klang.h.

3210{ return first; }
First & first(First &first, Rest...)
Definition klang.h:3206

◆ first() [2/2]

First & klang::Generic::Function< signal, Args >::first ( First & first,
Rest...  )
inlineinherited

Definition at line 3206 of file klang.h.

3206{ return first; }

◆ input() [1/3]

void klang::Generic::Function< signal, Args >::input ( )
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Input< signal >.

Definition at line 3200 of file klang.h.

3200 {
3201 std::get<0>(inputs) = in.value;
3202 }
float value
Definition klang.h:1124

◆ input() [2/3]

virtual const signal & klang::Generic::Input< signal >::input ( ) const
inlinevirtualinherited

Reimplemented in klang::Generic::Graph< SIZE >::Series.

Definition at line 2947 of file klang.h.

2947{ return in; }

◆ input() [3/3]

virtual void klang::Generic::Input< signal >::input ( const signal & source)
inlinevirtualinherited

Reimplemented in klang::Debug.

Definition at line 2951 of file klang.h.

2951{ in = source; this->input(); }
virtual const signal & input() const
Definition klang.h:2947

◆ operator const signal &() [1/2]

klang::Generic::Modifier< signal >::operator const signal & ( ) const
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3091 of file klang.h.

3091{ return out; } // return last output

◆ operator const signal &() [2/2]

klang::Generic::Modifier< signal >::operator const signal & ( )
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3090 of file klang.h.

3090{ this->process(); return out; } // return processed output
virtual void process() override
Definition klang.h:3094

◆ operator float()

klang::Generic::Function< signal, Args >::operator float ( )
inlineinherited

Definition at line 3142 of file klang.h.

3142 {
3143 if (function)
3144 return out = evaluate();
3145 return out;
3146 }

◆ operator param()

klang::Generic::Function< signal, Args >::operator param ( )
inlineinherited

Definition at line 3137 of file klang.h.

3137 {
3138 if (function)
3139 return out = evaluate();
3140 return out;
3141 }

◆ operator signal()

klang::Generic::Function< signal, Args >::operator signal ( )
inlineinherited

Definition at line 3131 of file klang.h.

3131 {
3132 if (function)
3133 return out = evaluate();
3134 this->process();
3135 return out;
3136 };

◆ operator()() [1/3]

Function< signal, Args... > & klang::Generic::Function< signal, Args >::operator() ( const FuncArgs &... args)
inlineinherited

Definition at line 3214 of file klang.h.

3214 {
3215
3216 //// single argument supplied, more than one expected -> use cached inputs or use as input?
3217 // if constexpr (ARGS > 1 && sizeof...(FuncArgs) == 1){
3218 // //in = first(args...);
3219 // std::get<1>(inputs) = in.value;
3220 // return *this;
3221 // } else
3222
3223 // Calling: full set of arguments supplied (overwrite live input)
3224 if constexpr (ARGS == sizeof...(FuncArgs)) {
3225 in = float(first(args...));
3226 inputs = std::tuple<Args...>(args...);
3227 return *this;
3228
3229 // Streaming: all but first argument supplied (use live input as x)
3230 }
3231 else if constexpr (sizeof...(FuncArgs) == (ARGS - 1)) {
3232 inputs = std::tuple<Args...>(in.value, args...);
3233 return *this;
3234
3235 // Invalid: insufficents arguments
3236 }
3237 else {
3238 static_assert(sizeof...(FuncArgs) < (ARGS - 1), "Insufficient arguments: can only omit first argument");
3239 //in = first(args...);
3240 //std::get<0>(inputs) = in.value;
3241 return *this;
3242 }
3243 }

◆ operator()() [2/3]

const float klang::Generic::Function< signal, Args >::operator() ( const FuncArgs &... args) const
inlineinherited

Definition at line 3247 of file klang.h.

3247 {
3248 signal in = this->in;
3249 std::tuple<Args...> inputs = this->inputs;
3250
3251 // configure inputs
3252 if constexpr (ARGS > 1 && sizeof...(FuncArgs) == 1) {
3253 in = first(args...);
3254 std::get<0>(inputs) = in.value;
3255 }
3256 else if constexpr (ARGS == sizeof...(FuncArgs)) {
3257 in = first(args...);
3258 inputs = std::tuple<Args...>(args...);
3259 }
3260 else if constexpr (sizeof...(FuncArgs) == (ARGS - 1)) {
3261 inputs = std::tuple<Args...>(in.value, args...);
3262 }
3263 else {
3264 in = first(args...);
3265 std::get<0>(inputs) = in.value;
3266 }
3267
3268 // return outputs
3269 if (function) {
3270 if constexpr (ARGS > 1)
3271 return std::apply(function, inputs);
3272 else
3273 return function(in);
3274 }
3275 else {
3276 // NOT YET IMPLEMENTED (needs non-const status)
3277 return out;
3278 }
3279 }

◆ operator()() [3/3]

Modifier< signal > & klang::Generic::Modifier< signal >::operator() ( params &&... p)
inlineinherited

Definition at line 3098 of file klang.h.

3098 {
3099 set(std::forward<params>(p)...); return *this;
3100 }

◆ operator*()

signal klang::Generic::Output< signal >::operator* ( TYPE & other)
inlineinherited

Definition at line 2977 of file klang.h.

2977{ this->process(); return out * SIGNAL(other); }

◆ operator+()

signal klang::Generic::Output< signal >::operator+ ( TYPE & other)
inlineinherited

Definition at line 2976 of file klang.h.

2976{ this->process(); return out + SIGNAL(other); }

◆ operator-()

signal klang::Generic::Output< signal >::operator- ( TYPE & other)
inlineinherited

Definition at line 2978 of file klang.h.

2978{ this->process(); return out - SIGNAL(other); }

◆ operator/()

signal klang::Generic::Output< signal >::operator/ ( TYPE & other)
inlineinherited

Definition at line 2979 of file klang.h.

2979{ this->process(); return out / SIGNAL(other); }

◆ operator<<()

virtual void klang::Generic::Input< signal >::operator<< ( const signal & source)
inlinevirtualinherited

Reimplemented in klang::Debug.

Definition at line 2950 of file klang.h.

2950{ in = source; this->input(); }

◆ operator>>() [1/3]

Graph & klang::Generic::Function< signal, Args >::operator>> ( klang::Graph & graph)
inlineinherited

Definition at line 3302 of file klang.h.

3849 {
3850 graph.plot(*this);
3851 return graph;
3852 }
static THREAD_LOCAL GraphPtr graph
Definition klang.h:3829

◆ operator>>() [2/3]

GraphPtr & klang::Generic::Function< signal, Args >::operator>> ( klang::GraphPtr & graph)
inlineinherited

Definition at line 3303 of file klang.h.

3832 {
3833 graph.plot(*this);
3834 return graph;
3835 }

◆ operator>>() [3/3]

TYPE & klang::Generic::Output< signal >::operator>> ( TYPE & destination)
inlineinherited

Definition at line 2969 of file klang.h.

2969{ this->process(); return destination = out; }

◆ output()

virtual const signal & klang::Generic::Output< signal >::output ( ) const
inlinevirtualinherited

Definition at line 2964 of file klang.h.

2964{ return out; }

◆ process()

virtual void klang::Generic::Function< signal, Args >::process ( )
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Modifier< signal >.

Definition at line 3298 of file klang.h.

3298 {
3299 out = evaluate();
3300 }

◆ reset()

void klang::Generic::Output< signal >::reset ( )
inlineinherited

Definition at line 2981 of file klang.h.

2981{ out = 0; }

◆ tail()

std::tuple< Rest... > klang::Generic::Function< signal, Args >::tail ( const std::tuple< First, Rest... > & t) const
inlineinherited

Definition at line 3182 of file klang.h.

3182 {
3183 return std::apply([](const First&, const Rest&... rest) { return std::make_tuple(rest...); }, t);
3184 }

◆ with()

Function< signal, Args... > & klang::Generic::Function< signal, Args >::with ( FuncArgs... args)
inlineinherited

Definition at line 3282 of file klang.h.

3282 {
3283 static_assert(sizeof...(FuncArgs) == (ARGS - 1), "with() arguments must have all but first argument.");
3284 inputs = std::tuple<Args...>(in.value, args...);
3285
3286 return *this;
3287 }

Member Data Documentation

◆ ARGS

unsigned int klang::Generic::Function< signal, Args >::ARGS
staticconstexprinherited

Definition at line 3175 of file klang.h.

◆ function

std::function<float(Args...)> klang::Generic::Function< signal, Args >::function
inherited

Definition at line 3173 of file klang.h.

◆ in

◆ inputs

std::tuple<Args...> klang::Generic::Function< signal, Args >::inputs
inherited

Definition at line 3178 of file klang.h.

◆ out

Definition at line 2961 of file klang.h.

2961{ 0.f };