VISR API

Architecture

API reference

Class Component

class visr::Component

Base class for processing components. Components may contain ports to exchange data (either audio signal or parameter) with other components or with the exterior. A component may have a parent, that is, a composite component it is contained in. If the parent is null it is a top-level component. Components also have a name, which must be unique within a containing composite component.

Public Functions

Component(SignalFlowContext const &context, char const *componentName, CompositeComponent *parent)

Constructor, constructs a component.

Parameters
  • context -

    Configuration object containing basic execution parameters (such as sampling frequency and period (block length))

  • componentName -

    The name of the component. If this component is contained in a higher-level parent component, the name must be unique within that parent component

  • parent -

    Pointer to the containing composite component, if there is one. Otherwise, that is, if the present component is at the top level, pass nullptr.

Component(SignalFlowContext const &context, std::string const &componentName, CompositeComponent *parent)

Constructor. Convenvience function, accepts a standard string instead of a C chararacter pointer.

Parameters
  • context -

    Configuration object containing basic execution parameters (such as sampling frequency and period (block length))

  • componentName -

    The name of the component. If this component is contained in a higher-level parent component, the name must be unique within that parent component.

  • parent -

    Pointer to the containing composite component, if there is one. Otherwise, that is, if the present component is at the top level, pass nullptr.

Component(Component const&)

Deleted copy constructor to avoid copy construction of this and derived classes.

Component(Component&&)

Deleted move constructor to avoid moving of this and derived classes.

Component &operator=(Component const&)

Deleted assignment operator to prohibit (copy) assignment of this and derived classes.

Component &operator=(Component&&)

Deleted assignment operator to prohibit move assignment of this and derived classes.

virtual ~Component()

Destructor (virtual)

std::string const &name() const

Return the ‘local’, non-hierarchical name.

std::string fullName() const

Return the full, hierarchical name of the component.

void status(StatusMessage::Kind status, char const *message)

Signal informational messages or the error conditions. Depending on the value of the status parameter, this might result in a message conveyed to the user or abortion of the audio processing.

Parameters
  • status -

    The class of the status message

  • message -

    An informational message string.

template <typename... MessageArgs>
void status(StatusMessage::Kind status, MessageArgs... args)

Signal informational messages or the error conditions where the message string is constructed from an arbitrary sequence of arguments. Depending on the value of the status parameter, this might result in a message conveyed to the user or abortion of the audio processing.

Template Parameters
  • MessageArgs -

    List of argument types to be printed. Normally they are automatically determined by the compiler, so there is no need to specify them.

Parameters
  • status -

    The class of the status message

  • args -

    Comma-seprated list of parameters with unspecified types. The main requirement is that all types support an “<<” operator.

bool isComposite() const

Query whether this component is atomic (i.e., a piece of code implementing a rendering functionality) or a composite consisting of an interconnection of atomic (or further composite) components.

AudioPortBase &audioPort(char const *portName)
AudioPortBase const &audioPort(char const *portName) const
AudioPortBase &audioPort(std::string const &portName)
AudioPortBase const &audioPort(std::string const &portName) const
ParameterPortBase &parameterPort(char const *portName)
ParameterPortBase const &parameterPort(char const *portName) const
ParameterPortBase &parameterPort(std::string const &portName)
ParameterPortBase const &parameterPort(std::string const &portName) const
SamplingFrequencyType samplingFrequency() const

Return the sampling frequency of the containing signal flow.

std::size_t period() const

Return the period of the containing signal processing graph, i.e., the number of samples processed in each invocation of the process function of the derived audio components. This methods can be called at any point of the lifetime of the derived component, i.e., for instance in the constructor.

bool isTopLevel() const

Query whether the component is at the top level of a signal flow.

Note
Not needed for user API

impl::ComponentImplementation &implementation()

Provide a pointer to an external implementation object. The type of this implementation object is opaque, i.e., not visible from the public VISR API.

Note
This method is not supposed to be called in user code. It is public because it is is used by the VISR runtime system.

impl::ComponentImplementation const &implementation() const

Provide a pointer to an external implementation object, constant version. The type of this implementation object is opaque, i.e., not visible from the public VISR API.

Note
This method is not supposed to be called in user code. It is public because it is is used by the VISR runtime system.

Public Static Functions

std::string const &nameSeparator()

Separator used to form hierarchical names.

Protected Functions

Component(impl::ComponentImplementation *impl)

Constructor that receives the internal implementation object. This overload has to be called by the other constructors (including those of subclasses) to make sure that the implementation object is instantiated. The motivation for this constructor is to provide different implementation objects for different subclasses.

Class AtomicComponent

class visr::AtomicComponent

Base class for atomic components. These components are at the lowest level in the hierarchy and implement runtime functionality as C++ code. Abstract base class, derived classes must override the virtual method process().

Public Functions

AtomicComponent(SignalFlowContext const &context, char const *name, CompositeComponent *parent)

Constructor.

Parameters
  • context -

    a signal flow context structure containing general parameters, e.g., sampling rate and block size of computation.

  • name -

    Null-terminated character string containing the name. Name must be unique within the containing composite component (if there is one).

  • parent -

    A composite component to contain this atom, If it is a null pointer (the default), then this component is at the top level.

AtomicComponent(AtomicComponent const&)

Deleted copy constructor to avoid copying.

AtomicComponent(AtomicComponent&&)

Deleted move constructor to avoid move construction.

virtual ~AtomicComponent()

Destructor (virtual). Atomic components are destined to be instantiated and managed polymorphically, thus requiring virtual destructors.

virtual void process() = 0

Pure virtual process() function. The overriding methods of base classes are called in regular intervals, each processing a fixed number (context.period()) number of samples.

Class CompositeComponent

class visr::CompositeComponent

Base class for processing components that are composed of other components (atomic and composite). In this way, processing components can be structured hierarchically. Composite components store the contained sub-components, external audio and parameter ports, and conenctions between the ports.

Unnamed Group

typedef using visr::CompositeComponent::ChannelRange = visr::ChannelRange

Making the types for defining audio connections known inside CompositeConponent and derived classes These are convenience aliases to make the syntax in derived signal flows more concise.

Note
: This also means that we include the ChannelList/ChannelRange definition in this header, as these classes become part the CompositeComponent interface.

typedef using visr::CompositeComponent::ChannelList = visr::ChannelList

Public Functions

CompositeComponent(SignalFlowContext const &context, char const *name, CompositeComponent *parent)

Constructor.

Parameters
  • context -

    Reference to a signal flow context object providing basic runtime parameters as period length or sampling frequency.

  • name -

    “the name of the component. Used to address the component inside other components and for status reporting.

  • parent -

    Reference (pointer) to a parent component if the present object is part of a containing signal flow. If nullptr is passed, this component is the top level.

~CompositeComponent()

Destructor.

std::size_t numberOfComponents() const

The number of contained components (not including the composite itself). This method considers only atomic and composite components at the next level, i.e., not recursively.

impl::CompositeComponentImplementation &implementation()

Return a reference to the internal data structures holding ports and contained components. From the user point of view, these data structure is opaque and unknown.

impl::CompositeComponentImplementation const &implementation() const

Return a reference to the internal data structures holding ports and contained components, const version. From the user point of view, these data structure is opaque and unknown.

void parameterConnection(char const *sendComponent, char const *sendPort, char const *receiveComponent, char const *receivePort)

Register a connection between parameter ports (both real ports of contained components or external placeholder ports).

Parameters
  • sendComponent -

    The name of the component holding the send port (local name, not the fully qualified name). When specifiying an external port of a composite component, use an empty string or "this".

  • sendPort -

    The local (not fully qualified) name of the send port.

  • receiveComponent -

    The name of the component holding the receive port (local name, not the fully qualified name). When specifiying an external port of a composite component, use an empty string or "this".

  • receivePort -

    The local (not fully qualified) name of the receive port.

Exceptions
  • std::invalid_argument -

    if a specified component or port does not exist.

void parameterConnection(ParameterPortBase &sender, ParameterPortBase &receiver)

Register a connection between parameter ports (both real ports of contained components or external placeholder ports).

Parameters

void audioConnection(char const *sendComponent, char const *sendPort, ChannelList const &sendIndices, char const *receiveComponent, char const *receivePort, ChannelList const &receiveIndices)

Register an audio connection between a sending and a receiving audio port. This overload uses C strings to denote both the names of the components holding the ports and the output ports itself. Lists of channel indices are to be specified for the sending and the receiving port. The sizes of these lists must be identical, and the contained indices must not exceed the width of the send and receive port, respectively. Empty lists for both the send and receive indices are permitted and result in no connection.

See
ChannelList for the syntax to specify the channel index lists.
Parameters
  • sendComponent -

    Name of the component holding the sending audio port. If the send port is an external input of this component, use “” or “this”

  • sendPort -

    The name of the sending port.

  • sendIndices -

    A list of channel indices denoting the send channels of the sending side.

  • receiveComponent -

    Name of the component holding the receiving audio port. If the receive port is an external output of the present component, use “” or “this”

  • receivePort -

    The name of the receiving port.

  • receiveIndices -

    A list of channel indices denoting the receive channels within the receiver port.

Exceptions
  • std::invalid_argument -

    if a specified component or port does not exist.

void audioConnection(AudioPortBase &sendPort, ChannelList const &sendIndices, AudioPortBase &receivePort, ChannelList const &receiveIndices)

Register an audio connection between a sending and a receiving audio port. This overload uses audio ports (either directly referencing external in- and output of this components or retrieving ports of contained components using the Component::audioPort() method). Lists of channel indices are to be specified for the sending and the receiving port. The sizes of these lists must be identical, and the contained indices must not exceed the width of the send and receive port, respectively. Empty lists for both the send and receive indices are permitted and result in no connection.

See
ChannelList for the syntax to specify the channel index lists.
Parameters
  • sendPort -

    The send port object.

  • sendIndices -

    A list of channel indices denoting the send channels of the sending side.

  • receivePort -

    The receive port object.

  • receiveIndices -

    A list of channel indices denoting the receive channels within the receiver port.

void audioConnection(AudioPortBase &sendPort, AudioPortBase &receivePort)

Register an audio connection between all channels of a sending and a receiving audio port. This overload uses audio ports (either directly referencing external in- and output of this components or retrieving ports of contained components using the Component::audioPort() method). It establishes one-to-one connections between the channels of the sender and the receiver.

Parameters
  • sendPort -

    The send port object.

  • receivePort -

    The receive port object.

Exceptions
  • std::invalid_argument -

    if the port widths do not match.

Class AudioPortBase

class visr::AudioPortBase

Base class for audio ports. Audio ports can form part of the external interface of components and denote start and end points od audio signal connections. An audio port is characterised by a sample type (fundamental integral and floating-point data type as well as complex floating-point types), the width, that is, the number of elementary audio signals represented by this port.

Protected Functions

void *basePointer()

Return the data pointer to fir first (technically zeroth) channel. The type of this pointer is char and needs to be casted in derived, typed port classes.

void const *basePointer() const

Return the data pointer to fir first (technically zeroth) channel, costant versiob The type of this pointer is char and needs to be casted in derived, typed port classes.

Private Members

impl::AudioPortBaseImplementation *mImpl

Pointer to the private, opaque implementation object.

Class AudioInputBase

class visr::AudioInputBase

Base class for audio input ports. This base class is not intended to be used by API users. This class itself cannot be instantiated, because it is not associated with a specific sample type. Only derived classes may actually be instantiated.

Template class AudioInputT

template <typename DataType>
class visr::AudioInputT

Class template for concrete audio inputs holding samples of a specific type.

Template Parameters
  • DataType -

    The sample type used by this audio port type.

Alias class AudioInput

Non-template of the visr::AudioInputT port template specialised for the default sample type.

typedef using visr::AudioInput = typedef AudioInputT<SampleType>

Alias for audio input ports using the default datatype (typically float)