Programming Reference:Filter DLLs

Description

When developing a BCI2000 signal processing filter in C++, it may be useful to compile it into a DLL in addition to adding it to a signal processing module, especially if you are going to test it using the BCI2000Analysis tool. This tool has the standard set of filters built-in but new filters may not easily be added: one would need to add the filter's source file to the tool's CMakeLists.txt, and manually add code that instantiates the new filter and adds it to the filter graph as required.

As a solution to this problem, a simple filter DLL interface has been designed that allows to compile filters independently of the BCI2000Analysis tool. As a restriction, it is necessary to build both BCI2000Analysis and filter DLLs with the same compiler, compiler settings, and version. Also, a debug version of BCI2000Analysis may only use filter DLLs that have been compiled in debug mode, and the same applies for release mode builds.

To be able to deal with mismatches in compiler and build settings without crashing, the filter DLL interface contains text-based information functions that allow a host process to obtain the relevant information in a safe manner.

Filter DLL interface

The following functions are exported by a BCI2000 filter DLL. They are declared in src/shared/filters/FilterWrapperLibrary.h.

const char* InterfaceVersion()

Returns the interface version at the time when the DLL was built. In the host process, a string comparison to the value of the FILTER_WRAPPER_INTERFACE_VERSION macro will tell you whether the DLL's interface version matches the one that is expected by the host.

const char* Compiler()

Returns the name of the compiler in a form that can be matched to by the host process.

const char* BuildType()

Returns the build type, which is one of "Debug", "Release", or "RelWithDebInfo".

const char* BuildInfo()

Returns full build configuration info in the form that is visible in GUI applications under Help->About.

const char* FilterName()

Returns the filter's name for display purposes.

void ReleaseString(const char*)

Call this function on the result of any of the above functions once you are done with it.

void SetBcidbg(BCIStream::OutStream*)

Set the respective stream's output to a BCI2000 BCIStream::OutStream object that has been instantiated in the host before. This way, the host may display error and debugging information originating from the filter contained in the DLL.

Specifying nullptr will suppress output from that stream.

void SetVisualizationChannel(bci::MessageChannel*)

Specify a bci::MessageChannel object to receive visualization messages from the filter contained in the DLL. Specifying nullptr will suppress visualization output.

void SetMeasurementUnits(MeasurementUnits*)

Specify a MeasurementUnits object that the filter will use to initialize basic units of measurement, such as the duration of a data block. Calling this function is crucial for proper function of the filter contained in the DLL. Such an object is typically existent in a host that uses BCI2000 filters.

void SetEnvironmentContext(Environment::Context*)

Specify a BCI2000 Environment::Context object through which the filter will receive access to its parameters and states. Such an object is part of the GenericFilter chain the filter will be part of.

GenericFilter* Instantiate(Directory::Node*)

Create an instance of the filter contained in the DLL. The argument is the filter's parent node in the filter graph, and may be obtained through its parent filter chain.

See also

User Reference:BCI2000Analysis