View source for Programming Reference:SignalSharingDemoClient C++ App

==Location==
<tt>src/core/SignalProcessing/SignalSharingDemo</tt>

==Synopsis==
The ''SignalSharingDemo'' client demonstrates how to receive signal data from BCI2000, using shared memory.
SignalSharing allows to tap into BCI2000 processing by receiving any filter output signal through a combination of a TCP connection, and shared memory.

For clarity, this page describes a simplified version of the ''SignalSharingDemo'' client, receiving only signal data, and not using the back channel to send back signal and state data. The full version in SVN shows how to use the full possibilities available to a SignalSharing client.

==Function==
The ''SignalSharing'' component in BCI2000 shares its input signal through a <tt>GenericSignal</tt> object which has been linked to a shared memory block using <tt>GenericSignal::ShareAcrossModules()</tt>. A dedicated thread waits for signal updates, and sends signal data out to a separate application waiting on a TCP/IP connection.

When the client application is running on a separate machine, full signal data are sent over the network. When the client is running on the same machine, only a reference to a shared memory block is sent. On the application side, unserializing the signal will transparently bind it to the shared memory block if available.

The client application visualizes signal data by plotting normalized signals on a circle.

<gallery widths="322px" heights="352px" mode="nolines">
File:SignalSharingDemo1.PNG|Client application waiting for data
File:SignalSharingDemo2.PNG|Client application displaying data
</gallery>

==Client application code==
The client application uses parts of the BCI2000 framework to efficiently receive and decode BCI2000 messages.
To include it into your own project, use
 utils_include(Frameworks/Core)
in your CMake file if it is part of the BCI2000 project.

Otherwise, you might to have to create code for dealing with BCI2000 messages yourself (message format definitions may be found
[[Technical_Reference:BCI2000_Messages#Descriptor_Supplement=3:_Signal_Properties|here]] and
[[Technical_Reference:BCI2000_Messages#Descriptor_Supplement=1:_Signal_Data|here]]).

===Declaration of internal variables===
<syntaxhighlight lang="cpp">
#include "SignalSharingDemoWidget.h"

#include "Sockets.h"
#include "StringUtils.h"
#include "Streambuf.h"
#include "Thread.h"
#include "GenericSignal.h"
#include "ParamList.h"
#include "Synchronized.h"
#include "Runnable.h"

#include <QPaintEvent>
#include <QPainter>

struct SignalSharingDemoWidget::Private
{
  SignalSharingDemoWidget* mpSelf;
  std::vector<QColor> mSignalColors;

  ServerTCPSocket mListeningSocket;
  Synchronized<bool> mConnected;
  SynchronizedObject<GenericSignal> mpSignal;
  SynchronizedObject<ParamList> mpParameters;

  Thread mThread;
  void ThreadFunc();
  MemberCall<void(Private*)> mThreadCall;
  void Invalidate();
  Private();
};
</syntaxhighlight>

===Initialization of internal variables===
<syntaxhighlight lang="cpp">
SignalSharingDemoWidget::Private::Private()
: mThreadCall(&Private::ThreadFunc, this),
  mThread(&mThreadCall, "SignalSharingDemoWidget listening/receiving thread")
{
  mSignalColors.resize(8);
  for(int i = 0; i < mSignalColors.size(); ++i)
    mSignalColors[i].setHsvF(i*1.0/mSignalColors.size(), 1, 0.9);
}
</syntaxhighlight>

===Receiving thread function===
By inheriting from the <tt>MessageChannel</tt> class, the <tt>Private</tt> object will receive dispatched
messages through overridden functions:

<syntaxhighlight lang="cpp">struct SignalSharingDemoWidget::Private : MessageChannel
{
    ...

    // MessageChannel overrides
    bool OnVisSignalProperties(std::istream&) override;
    bool OnVisSignal(std::istream&) override;
    bool OnParam(std::istream&) override;
};

void SignalSharingDemoWidget::Private::ThreadFunc()
{
    while (!mThread.Terminating())
    { // wait for a connection
        while (mListeningSocket.Input().Wait())
        { // accept pending connection
            ClientTCPSocket clientSocket;
            if (mListeningSocket.WaitForAccept(clientSocket, 0))
            {
                mConnected = true;
                Invalidate();
                mBuffer.SetInput(&clientSocket.Input());
                MessageBuffer::ClearIOState();
                while (clientSocket.Input().Wait()) // will be interrupted by Thread::Terminate()
                {
                    MessageChannel::HandleMessage(); // will dispatch to our overridden functions
                                                     // as appropriate
                }
                *mpSignal.Mutable() = GenericSignal();
                mConnected = false;
                Invalidate();
            }
        }
    }
}

bool SignalSharingDemoWidget::Private::OnVisSignalProperties(std::istream& is)
{
    VisSignalProperties properties; // signal properties are wrapped into VisSignalProperties
    properties.Unserialize(is);
    // The only information we need from signal properties is the sampling rate
    // because the signal's dimensions will be transported by signal messages as well.
    double sampleDuration = properties.SignalProperties().ElementUnit().RawToPhysicalValue(1);
    mSamplingRate = 1.0 / sampleDuration;
    return true; // indicate we read our data from the stream
}

bool SignalSharingDemoWidget::Private::OnVisSignal(std::istream& is)
{
    VisSignal visSignal; // signals are wrapped into VisSignal messages
    visSignal.Unserialize(is);
    mpSignal.Mutable()->AssignValues(visSignal.Signal()); // get current signal content
    Invalidate(); // request window update
    return true; // indicate we read our data from the stream
}

bool SignalSharingDemoWidget::Private::OnParam(std::istream& is)
{
    Param param;
    param.Unserialize(is);
    mpParamList.Mutable()->Add(param);
    Invalidate(); // request window update
    return true; // indicate we read our data from the stream
}
</syntaxhighlight>

===The widget's paintEvent()===
<syntaxhighlight lang="cpp">
void
SignalSharingDemoWidget::paintEvent(QPaintEvent* ev)
{
  ev->accept();
  WithLocked(pSignal = p->mpSignal.Const()) // lock the signal while reading from it
  {
    if(pSignal->Empty())
    {
      QPainter painter(this);
      painter.fillRect(ev->rect(), Qt::gray);
      painter.setPen(Qt::white);
      painter.drawText(geometry(), Qt::AlignCenter, 
        p->mConnected ? "Waiting for signal ..." : "Waiting for connection ...");
    }
    else
    {
       // draw some visualization into the widget
       ...
    }
  }
}
</syntaxhighlight>

==Parameters==
===ShareTransmissionFilter===
IP address and port number of the client application. The client's default address is <tt>localhost:1879</tt> but may be changed on the client's command line.

The example uses the ''ShareTransmissionFilter'' parameter but any other filter's ''Share<FilterName>'' parameter under the ''SignalSharing'' tab will work as well to visualize the chosen filter's output signal.

==See also==
[[User Reference:SignalSharing]], [[Programming Reference:GenericSignal Class]],  [[Programming Reference:SignalSharing Python Demo]], [[Programming Reference:SignalSharingClientLibDemo]]


[[Category:Framework API]][[Category:Howto]][[Category:Development]]