Welcome to the MindCode !

Here we will talk about your brain, and what it can do. Things that may sounds like science fiction.
It’s called Brain Computer Interface, and it’s a hot research topic around the world, with many challenges and expectations.

We will talk about OpenViBE, the open-source software to design, test and use BCI.
I will try to give you tips, tutorials and presentations on the things not covered by the official support.

NOTA:  This blog is now unmaintained, but will remain online for the record. 

Link with a delayload library with VS2010 & CMake

This article is related to the latest patch I made for the Emotiv EPOC driver for the OpenViBE Acquisition Server.

The main motivation for that patch is the time we consume on support for the Emotiv EPOC users, that needed to compile manually the software to have the driver.
As this headset is quiet cheap, aiming mass market, many people using it were not particularly comfortable with SVN, C++ compilation, scripts and technical computer stuff.

The manufacturer, namely Emotiv, agreed to let us redistribute a binary version of the driver, without providing its proprietary DLL.
Doing so, the binary version of OpenViBE will work with the Emotiv EPOC headset once users provide a valid DLL they purchased from Emotiv (Emotiv SDK Research Edition or above).

Solution : load the DLL only at runtime, with a clean error handling if the DLL is not present.

When developing this patch, I was totally newbie to DLL delayed loading, and I faced one big problem : the lack of documentation and example, even on the official MSDN website.
The purpose of that article is to give feedback and sample code in one place, for those who may need it in the future. It’s not clearly OpenViBE related as you may notice🙂

The environment

Here is the specifications of the setup I used:

  • OS : Windows 7 64bits
  • Visual Studio 2010 Ultimate
  • CMake 2.8.3
  • OpenViBE svn 3065 (18 Aug 2011)
  • Standard cup of coffee

Delay load library

In Visual Studio

To load a dll at runtime in an application compiled by Visual Studio, you must tell the linker to do so. Specify the delay loaded libraries in the project properties (linker > entries > delay load library).
The resulting command line option is :

/linker /DELAYLOAD:MyDLL.dll

To do the job, Visual studio relies on the library Delayimp.lib that you must link against at compilation time.
You can add it in the project properties (linker > entries > additional library)

Build your project.

When running your application, the DLL will be loaded only at the first call to a function within the DLL.
If you remove the DLL and run the application again, it should fail at the same moment,  with an unhandled exception “MODULE NOT FOUND”.
It should definitely not fail at startup with “missing MyDLL.dll.

With CMake

The OpenViBE software platform uses CMake for compilation over several operating system.

We add the following linker option into the cmake command line:

-DCMAKE_EXE_LINKER_FLAGS=" /DELAYLOAD:MyDLL.dll"

We also need to link the project with Delayimp.lib.
This is done in the CMake script that initializes cmake properly to compile the Acquisition Server, thanks to the command :

TARGET_LINK_LIBRARIES(${PROJECT_NAME}-dynamic Delayimp.lib

Exception handling

My program now works fine if I have the DLL on board, and fails when not present with an unhandled exception.
To perform a clean exception handling, one solution is to safely guard the first call to our DLL using Structured Exception Handling (__try/__except) clauses.
Please not that this require your code to #include <windows.h>.

 __try
 {    
   int result = functionInMyDLL();
 }
 __except(EXCEPTION_EXECUTE_HANDLER)
 {
    //fail nicely   
 }

In my case, I guard the first call to the Emotiv DLL in the driver initialization. If the exception rises, I print an error and return false, stopping the execution of the driver.
I am sure that not a single call to any of the DLL functions can be performed if this one fails.

Error C2712

As all developers know, when it comes to programming, nothing goes as expected.

Everything was fine until I tried to improve the driver. The following code resulted in a compilation error C2712 (yeah that famous one. or not.)

...
CObject l_oObject();
l_oObject.doStuff();
...
__try
 {    
   int result = functionInMyDLL();
 }
 __except(EXCEPTION_EXECUTE_HANDLER)
 {
    //fail nicely   
 }
...

The error C2712 means : “cannot use __try in functions that require object unwinding”
In other words, you cannot use objects with destructors in a function that uses __try/__except.

My CObject class has a destructor, I cannot instantiate it in my function.

Solution selected : refactor my code to be able to do:

...
this->doStuffOnObject();
...
__try
 {    
   int result = functionInMyDLL();
 }
 __except(EXCEPTION_EXECUTE_HANDLER)
 {
    //fail nicely   
 }
...

This error happened because our project is compiled with the Error Handling Model /EHs:

s    The exception-handling model that catches C++ exceptions only and tells the compiler to assume that extern C functions do throw an exception.

Conclusion

This article may not be very complete, as I didn’t want to just copy paste pieces of code too much specialized  to openvibe.
My goal is just to keep record of my experience with delayload library on windows, for anyone who may need it (including myself😉 )

Cheers.

Sources:

MSDN official documentation : <http://msdn.microsoft.com/en-us/library/151kt790.aspx>

“Delay Load Dlls Error Recovery” by Tomer Margolin: <http://www.codemaestro.com/articles/6>

Error C2712: <http://msdn.microsoft.com/en-us/library/xwtb73ad%28v=vs.80%29.aspx>

What’s the next step ?

Hi there !

I’ve been quiet busy these weeks and didn’t manage to take some times for my blog…

However I recently started to think about the openvibe project and the fact that the community is growing nicely, and we may have to change the way we manage everything so far.
And I really wanted to share my reflexions with whoever reads me😉

Here is a quick – unordered – snapshot of the project today :
– We keep a strong release policy, 1 every 3 months or so, since the very beginning. If everything goes as expected, July will see openvibe 0.11.0.
– More than 100 peoples are registered and posted on the forum (spambots not included ofc).
– 23+ EEG devices are officially compatible with openvibe
– We are regularly integrating community contributions, e.g. CSP filtering, Brainamp EEG  driver, Statistical computations.
– The platform includes full BCI pipelines for Motor-Imagery, P300 and SSVEP paradigms
– Presentation and demonstration during many many events in the past 2 years (tutorial at BCI meeting 2010, stall at IIT Bombay Techfest 2011, PRIT 2011, tv & press covers, …)
– …

In my opinion this is quiet positive… I’m still very excited by this project, and even more when I see what people do with OpenViBE; academic , industrial or independent researchers.

But as the possible contributions are showing up, this brings several questions…
How can we help people contribute easily ? Can we integrate everything ? and how ? Is it relevant for everyone ?
And… who will do the job ?

We already developed a new set of tools for the plugin developers : Skeleton Generator, Codec toolkit, tutorials…
But helping the sole implementation is not enough, we need a community ecosystem. A place where every developer would be free to post their contributions and where every user could search for new plugins.

So… what is the next step ?

New position at INRIA

Some fresh news !

Our dear colleague Yann Renard has left INRIA a week ago now, and of course we are wishing him the best for the future !
Yann is starting his own business activity, based on his wide expertise in the field of BCI in general and OpenViBE in particular.
Don’t hesitate to follow him on twitter (@stickyvibe) or on his blog.

Yann has been the Lead Software Engineer of the OpenViBE project since the very beginning, and as the most experienced developer (sigh!) I am taking this position from now on.
I’m very excited by this opportunity, and I will do my very best to lead this project as successfully as Yann did in the past 5 years!

Laurent

Using the OpenViBE build scripts in Visual Studio

Hello  !

This article present a new tip for those who are using Visual Studio as their primary development tool for OpenViBE.
If you try to install OpenViBE from the source code on the SVN repository, then you have to use the provided scripts for nearly everything… And Visual Studio will only be a C++ code editor. No “build project” command, no debug/release configurations, etc. I felt this frustrating as I had always used VS in the past as my “all-in-one” developer tool.

A previous article on this blog described how to use the Visual Studio debugger when developing a new plugin or driver.
This time I will focus on using the scripts provided with OpenViBE right inside Visual Studio.

This article is based on Jay Smith blog post here.

What we need:

Let’s list what we may want to integrate in the IDE. First, the build scripts:

  1. win32-build.cmd: builds every project of the software platform (applications, plugins, etc.)
  2. win32-clean.cmd: cleanup the CMake cache directory, thus when building again everything will be compiled and installed from scratch.

Then some launchers for the main applications:

  1. ov-designer.cmd
  2. ov-acquisition-server.cmd
  3. ov-skeleton-generator.cmd

Add new menu contents :

Open Visual Studio and your openvibe solution, then go in Tools > External Tools. You should have something like this :

Let’s add the win32-build.cmd script. Add a new content and fill it with the following information:

Title:                   Build OpenViBE
Command:                 C:\[path-to-repository]\scripts\win32-build.cmd
Arguments:               [NO ARGUMENT]
Initial directory:       C:\[path-to-repository]\scripts\
Use Output Window:       YES
Prompt for arguments:    NO
Treat output as Unicode: NO

With Use Output Window checked, the build log will be directly printed in the “output” console of Visual Studio. I didn’t find how to redirect the output with the color information, so the log is just printed black on white in Visual Studio. Uncheck this option if you still want the CMD terminal popping up when building the software.

You can do exactly the same for win32-clean.cmd if you’d like to.

For the application launchers, add new content with the following information:

Title:                   ov-designer
Command:                 C:\[path-to-repository]\dist\test-designer.cmd
Arguments:               [NO ARGUMENT]
Initial directory:       C:\[path-to-repository]\dist\
Use Output Window:       NO
Prompt for arguments:    NO
Treat output as Unicode: NO

This time I don’t want to print the output console in Visual Studio.

You can do the same for the acquisition-server and/or the skeleton-generator for example.

Now that you defined all your personal the menu contents, note their indexes in the list of External Tools, starting at 1.
Why that ?! because Visual Studio doesn’t seem to be capable of referencing these new menu contents by their names… instead you will have something like “External Command 4“, “External Command 5“, etc.
Nevermind… :s

Access the new commands:

Now that we defined some new commands, let’s use them. In my case, I want to be able to run the build process in the context menu of the editor (right click in the main edition panel) or with a dedicated button in the toolbar.
Right click somewhere in the toolbar and select Customize. You have 2 panels, one for the toolbars and one for the commands that appears in the toolbars and menus.

In Toolbars you can add a new group named “OpenViBE”. We will add new buttons in it for our new commands.
Go in the Commands tab.

In the Toolbar selection box, search for “OpenViBE”. You should see in the Controls panel… nothing at all. Click on the Add Command… button.
You will find your new menu content in the category Tool, under the name “External Command #”. I hope your remember the indexes🙂
Add the external commands corresponding to the build script and the launchers, you should see them in the Visual studio toolbar.

In the Context menus selection box, search for Project and Solution Context Menus |Item. This correspond to the context menu that pops up when right-clicking somewhere in the editor main panel.
As I want to be able to launch the build from there, I also add the corresponding external command.

Want more ?

As we already discussed in a previous article how to customize the build process, it is possible to have more than one build script. For example I personaly have 3 of them:

  • One in Release, that builds every project.
  • 2 others in Debug and Release, that rely on a specific win32-init_env_command script that only select for build the project I’m currently working on (e.g. work-in-progress branches)

Thus I added 3 commands in Visual Studio: “OpenViBE build (wip/release)”, “OpenViBE build (wip/debug)”,“OpenViBE build (all/release)”.

I hope this article will give you some new ideas to improve your development environment, not only for OpenViBE of course🙂

Cheers !

Debugging in OpenViBE with Visual Studio

Hello openvibe developers !

For those who develop new plugins for openvibe on windows, this article will describe a simple procedure in order to be able to debug inside openvibe using the Visual Studio C++ editor.
This works exactly the same on Visual 2008 and 2010.

Compiling OpenViBE in Debug

Take a look at the build script win32-build.cmd.

Basically, the script loops on every projects (every applications and plugins) and build each one with this nice (who said ugly ?) CMake commandon line 48 :

cmake -DCMAKE_INSTALL_PREFIX="%%s" -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=" /DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR /wd4355" -Wno-dev -DCMAKE_MODULE_PATH="%saved_directory:\=/%/../cmake-modules;${CMAKE_MODULE_PATH}" !OpenViBE_project_name_full! -G"NMake Makefiles"

Look at this flag :

... -DCMAKE_BUILD_TYPE=Release ...

If you want to compile some part of the software in debug, just replace Release by Debug.
The projects written in the build-order file generated by win32-init_env_command.cmd will be compiled in Debug.
To select only the projects you need, customize your win32-init_env script, as described in this previous article.

It is highly advised to first compile the whole software in Release, then the specific plugins in Debug. With a debug-kernel and/or debug-Designer, it will be insanely (and logically) slow.

Attaching the Visual Studio debugger

First case :
The application crashes. Windows wisely ask you if you want to debug the program. This time (finally…) it will be useful ! Select your opened project and you’re good.
You should have in the call stack the mean to access the failing piece of code.

Second case :
The application runs fine, but you know it will crash at will (e.g. when playing a scenario).
Execute the application, then go back in Visual Studio. You should have in the menu Tools the possibility to attach a process (Ctrl + Alt + P).
In the process list, look for your application (e.g. OpenViBE-Designer-dynamic.exe), and attach it.

Now you can add breakpoints and debug as you usually do when using Visual Studio.

Hope this helps 🙂

Speed up the OpenViBE build on windows

Hello everyone !

This new tips session is focused on helping the openvibe developers to speed up the build process when working on Windows.
When I started extending the platform by developing new plugins, I was always a bit irritated when running the win32-build.cmd script : it took a century even when I modified just one file !
In fact, I felt very  frustrated as the same process usually take less than 30 seconds on Linux (not enough to make me move to Linux though. Sorry🙂 ).

Let’s take a look at that build scripts…

Win32-build.cmd, a day at the batch

If you have never written any Batch scripts in your life, once you open it you realize it is far from simple.

Hmm… tricky…

The first 20 lines are just a trick, in order to recall win32-build.cmd with some cmd options (/e /v /c ).

if "%1" == "" goto recall_me
goto base

:recall_me

cmd /e /v /c %0 dummy
goto terminate

:base
... build process ...

If no argument is provided, the script recall itself with the options and a dummy argument.
This is not a major point for this article, so I let you check these cmd options in the MS documentation🙂

Update 12/05/2011 : I recently spent some time investigating batch scripting, and I found a proper way to do that. I replaced this ugly and tricky stuff with the SetLocal command:

SetLocal EnableDelayedExpansion
SetLocal EnableExtensions

Initialize the environment

This is a crucial point !

if not exist "win32-init_env_command.cmd" (
    echo You have to configure your `win32-init_env_command` file.
    echo `win32-init_env_command.cmd-skeleton` is a good file to start with... (I'll copy this file for you^)
    copy "win32-init_env_command.cmd-skeleton" "win32-init_env_command.cmd"
)

call "win32-init_env_command.cmd"

One way or the other, we call the script win32-init_env_command.cmd, in order to prepare the environment to the build process:

  • Set the SVN branches that may be used used instead of trunks
  • Creates the corresponding path variables
  • Calls win32-dependencies.cmd, the files that lists all the dependencies and their locations.
  • Finds the compiler (VS2008 or VS 2010, priority to the latest one)
  • Completes the PATH variable with the libs & binaries location for the dependencies
  • Constructs the build order, i.e. the list of projects scheduled for build

We will detail this file later on, because obviously that’s where many things can be done !

Build baby !  build !

The build itself relies on CMake. We loop on the build-order, and build each project one by one by calling cmake.

cmake -DCMAKE_INSTALL_PREFIX="%%s" -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=" /DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR /wd4355" -Wno-dev -DCMAKE_MODULE_PATH="%saved_directory:\=/%/../cmake-modules;${CMAKE_MODULE_PATH}" !OpenViBE_project_name_full! -G"NMake Makefiles"

As you can see, the flag DCMAKE_BUILD_TYPE is by default set to Release. You can change it to Debug if you want to generated debugging information with the software.

Then win32-build generates all the scripts that are used to launch the applications, for example:

echo @echo off                                               >  %target_dist%\ov-designer.cmd
echo pushd ..\scripts                                        >> %target_dist%\ov-designer.cmd
echo call win32-init_env_command.cmd                         >> %target_dist%\ov-designer.cmd
echo popd                                                    >> %target_dist%\ov-designer.cmd
echo cd bin                                                  >> %target_dist%\ov-designer.cmd
echo OpenViBE-designer-dynamic.exe %%1 %%2 %%3 %%4 %%5 %%6   >> %target_dist%\ov-designer.cmd
echo pause                                                   >> %target_dist%\ov-designer.cmd

Produces the following script ov-designer.cmd:

@echo off                                               
pushd ..\scripts                                        
call win32-init_env_command.cmd                         
popd                                                    
cd bin                                                  
OpenViBE-designer-dynamic.exe %1 %2 %3 %4 %5 %6   
pause

That prepares the execution environment before calling the executable (giving it the possible arguments %1 to %6).

Finally the generated files are installed in the dist folder.

Customizing the Build process

Now that you saw the build steps, we move on to the interesting part : how we can customize the build and speed it up.
We will focus on the environment initialization, namely the win32-init_env_command.cmd file.

First…

You should always build the whole software once without tweaking anything in the scripts.
Following this advice you should start with a fresh, up-to-date and working openvibe.

Building a SVN branch

This may be useful for those who want to test a work-in-progress functionality before its possible integration in the trunk.

For example : a new driver is being developed for your EEG device, and you want to contribute by giving feedback and bug reports during the development.
The driver is in a branch, let’s say in openvibe-applications\acquisition-server\branches\wip-my-little-eeg.

We will prepare the build environment to choose the branch instead of the trunc.

win32-init_env_command.cmd : line 38

SET OpenViBE_application_acquisition_server_branch=

Will become :

SET OpenViBE_application_acquisition_server_branch=branches\wip-my-little-eeg

And that’s all. CMake will look in the branch instead of the trunk when building the acquisition-server project.

Selecting the projects to be built

When developing new plugins, you need to build it repeatedly. The problem is the time spent by the script… CMake checks every projects for modification, one by one, and on Windows it’s quiet long. I won’t explain why here but the file system on Linux is much faster in that case.

Anyway, you can do something to speed the build up !

At the end of win32-init_env_command.cmd, you will find the construction of the build order, i.e. the ordinated list of all the projects composing the software. The order itself is based on the dependency links between projects. As you can see, every project is present, but you can easily select only the one you need.

There is several ways to customize that part of the script, one is to comment (using REM) all the lines related to the projects you don’t need.
For example, I want to compile only the box I’m working on. Say the box is located in openvibe-plugins\signal-processing.
I comment all the lines except the “signal-processing” one:

del %OpenViBE_build_order% > NULL 2<&1
REM echo %OpenViBE% >> %OpenViBE_build_order%
REM echo %OpenViBE_application_id_generator% >> %OpenViBE_build_order%
REM echo %OpenViBE_module_ebml% >> %OpenViBE_build_order%
...
REM echo %OpenViBE_plugin_samples% >> %OpenViBE_build_order%
echo %OpenViBE_plugin_signal_processing% >> %OpenViBE_build_order%
REM echo %OpenViBE_plugin_signal_processing_gpl% >> %OpenViBE_build_order%
...
REM echo %OpenViBE_documentation% >> %OpenViBE_build_order%
REM echo %OpenViBE_scenarios% >> %OpenViBE_build_order%

When I will run the build, it will only check for modification in the signal-processing project, recompiling it if needed.

Forcing a project to be re-compiled

If you want to force CMake to compile from scratch the whole software, you can use the script win32-clean.cmd.
This script is simple : it destroys every CMake local directories, thus when executing win32-build.cmd, you will build everything again.

If you want to force the recompilation of only one particular project, just erase the corresponding cmake folder, located in local-tmp (e.g. local-tmp\openvibe-plugins\signal-processing)

This may be useful when changing some dependencies of a project (e.g. you want to test an up-to-date or unstable version of an openvibe  dependency). In that case CMake won’t find any change in the source code of the openvibe plugin itself, thus won’t trigger the build. However you do want the build to occur as you need to compile the plugin against your new dependency.

Closing words

When you know where to look, the build scripts for windows can be tweaked without changing much of it.

I hope this article will help the Windows users in the community !

Cheers-

Using Gtk themes on Windows

For those who are not familiar with Gtk, the themes change the whole layout of your Gtk interfaces.

On Linux it’s really easy, as Gtk is widely used and integrated with the various distributions (e.g. Gnome and Xfce are base on Gtk).
You will find Gtk options in some OS “Appearance” menu…

On windows, switching from one theme to another has to be done manually.

When installing OpenViBE dependencies, you can choose to add new Gtk themes directly in openvibe.
Please note that this option is enabled only when building from sources.

Anyway, you can find all the themes you want on the official website (here).
Warning: on windows, you may encounter significant slowdown at runtime white some themes.

The basic theme on windows is a little bit depressive in my opinion. Too much grey…

It somehow reminds me the old Windows application.

I prefer using the Clearlooks Theme. Nice without too much shiny effects.

Now… How to change the Gtk theme used by OpenViBE ?

When building from sources

  1. Be sure to check “Gtk Themes” when installing the dependencies.
  2. Go into dependencies/gtk.
  3. in share/themes you will find many (many !) themes. Each one is in fact described in a file named gtkrc.
  4. Copy the gtkrc file you want into etc/gtk-2.0.
  5. Run the Designer.

When installing from binaries

You don’t have the Gtk themes installed when using the windows installer.

  1. Download themes you find on the Internet
  2. Go into dependencies/gtk.
  3. Copy the theme files (there should at least a gtkrc) into etc/gtk-2.0.
  4. Run the Designer.

Cheers !

Laurent-