1. Home
  2. My First Filter

My First Filter

This guide teaches you how to wire up your own Filter by following three simple steps. If you are looking for a more comprehensive explanation of what Filters are follow this link.

Create the CMakeLists.txt

To create a CMake based project all you have to do is provide a CMakeLists.txt file inside the folder where your source files live. Setting up a valid CMakeLists.txt file includes the following steps:

For further information regarding relation of adtfplugin, plugindescription and CMake please have a look at Generate Plugin Description. 

          
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
project (HelloWorld)

set (HELLO_WORLD_FILTER hello_world_filter)

if(NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/hello_world_filter.h)
  file(WRITE hello_world_filter.h)
endif()
if(NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/hello_world_filter.cpp)
  file(WRITE hello_world_filter.cpp)
endif()

find_package(ADTF COMPONENTS filtersdk)

# Adds the hello_world_filter project to the Visual Studio solution, which when build
# creates a shared object called hello_world_filter.adtfplugin
adtf_add_filter(${HELLO_WORLD_FILTER} hello_world_filter.h hello_world_filter.cpp)

# Adds the INSTALL project to the Visual Studio solution, which when build
# copies our Filter to the subdirectory given as the second argument into ${CMAKE_INSTALL_PREFIX}
adtf_install_filter(${HELLO_WORLD_FILTER} src/examples/bin)

# Generate a plugindescription for our Filter
adtf_create_plugindescription(
    TARGET ${HELLO_WORLD_FILTER}
    PLUGIN_SUBDIR "src/examples/bin"
    VERSION "0.8.15"
    LICENSE "ADTF"
    SUPPORT_MAIL "support@mycompany.org"
    HOMEPAGE_URL "www.mycompany.org"
)

# Generate a documentation for our Filter
adtf_convert_plugindescription_to_dox(
    TARGET ${HELLO_WORLD_FILTER}
    DIRECTORY ${CMAKE_BINARY_DIR}/src/doxygen/generated
)


Use the CMake-GUI to configure relevant properties

Switch to the CMake-GUI and follow these steps:


Implement the Filter inside Visual Studio

Open the hello_world_filter project in the solution explorer which should look like this:

Visual Studio solution explorer

Open the hello_world_filter.h file and add this minimal Filter declaration: 

            
#pragma once

// Include all necessary headers from the ADTF SDK
#include <adtffiltersdk/adtf_filtersdk.h>

// For simplicity use the necessary namespaces
using namespace adtf::util;
using namespace adtf::ucom;
using namespace adtf::base;
using namespace adtf::streaming;
using namespace adtf::filter;

// To implement a Filter we subclass adtf::filter::cFilter
class cHelloWorldFilter: public cFilter
{
public:
    // This macros provides some meta information about our Filter Implementation
    // This will be exposed by the plugin class factory.
    ADTF_CLASS_ID_NAME(cHelloWorldFilter,
                       "hello_world_printer.filter.adtf_guides.cid",
                       "Hello World Printer");

public:
    // In the constructor, we setup all aspects of our Filter.
    cHelloWorldFilter();

    // This method gets called when our Runner is triggered.
    tResult Process(tNanoSeconds tmTimeOfTrigger,
                    IRunner* pRunner) override;
};


Open the hello_world_filter.cpp file and add this minimal Filter definition: 

          
#include "hello_world_filter.h"

// The code behind the macro creates a plugin and the main entries to the plugin DLL or shared object.
// The cHelloWorldFilter will be available through the plugins class factory.
ADTF_PLUGIN("Hello World Plugin",
            cHelloWorldFilter);

cHelloWorldFilter::cHelloWorldFilter()
{
    // Create our Runner and give the ADTF Configuration Editor a hint on which
    // Active Runner to connect to it. In this case a Timer Runner.
    CreateRunner("data_generator_function",
                 cTimerTriggerHint(std::chrono::seconds(1)));
    SetDescription("data_generator_function", "Runner to periodically trigger the function which prints the happy text");

    // set basic information about the component itself and purpose
    SetDescription("This filter shows how to trigger a cyclic log message.");
}

// Executes each time the data generation function Runner is stimulated (e.g. through a Timer Runner).
// This is where your logic has to be implemented.
tResult cHelloWorldFilter::Process(tNanoSeconds /* tmTimeOfTrigger */,
                                   IRunner* /* pRunner */)
{
    LOG_INFO("I am so happy :)");

    RETURN_NOERROR;
}


Build the "Hello World" solution with Visual Studio to get the shared object *.adtfplugin

Build the solution


Build the "INSTALL" project with Visual Studio (this step deploys the created *.plugindescription files)

Build the INSTALL project



Now you have a brand new hello world Filter which logs "I am so happy :)" to the console when activated. You can find the generated hello_world_filter.adtfplugin and hello_world_filter.plugindescription in the src\examples\bin\debug directory of your ADTF directory.

Generated files

Build an ADTF Session for our new Filter

Fire up the Configuration Editor

  1. Create a new project
  2. Drag and drop the Hello World Filter from the Components tab into the Filter Graph
  3. Drag and drop a Timer Runnerinto the Filter Graph
  4. Connect the Timer Runner with the Hello World Filter
  5. Save the project ctrl + s
  6. Switch to the Sessions tab
  7. Right click on the default ADTF Session and choose Launch with ADTF Control
  8. In the command line of the ADTF Control type rl running
    Filter output

Congratulations! Now you know the steps to construct an ADTF Filter from scratch.

Where to go next?

Have a look at Streaming Sources to learn where the data comes from that flows through the ADTF System.