The DLL component – Getting started, Part 1: Setting up a Netbeans Project

The DLL component – Getting started, Part 1: Setting up a Netbeans Project

No Comments

The DLL (Dynamic Link Library) component is arguably the most powerful component in Flowstone, it allows us to extend Flowstones functionally (albeit in a limited way) in ways previously not possible. It also enables us to do processing that would be just too slow in Ruby or Green.

You may be thinking because it is named “DLL component” that this means we can load any DLL, this is not the case. Flowstone is expecting a very specific type of function with specific parameters, which any old DLL  will not have, hence they cannot be used directly. You are going to have to get your hands dirty writing your own DLL, which means writing C++ and using an IDE and compiler. This I think is why the DLL component doesn’t get much love over on the Flowstone forums. Most of us are using Flowstone to avoid having to write or learn C++! But if you want to really push the boundaries of what is possible in Flowstone then learning C++ and the DLL component is a must.

In this article I will give instruction on how to set up a Flowstone DLL project in the Netbeans IDE.

Netbeans IDE

Firstly, why Netbeans? Well this is just my personal preference because I use it for Java projects and it also supports C++. It helps that it is also a really great IDE and free :) .

There is a bit of work involved in getting Netbeans set up but hopefully this won’t be too much hassle for you.

Firstly you need to download the Netbeans IDE .  Choose either the “C/C++” version or “All” ,  “All” includes many things that may not be of interest to you, if so just select the “C/C++” version. Also it is important to note that the IDE needs Java installed to work.

Getting Netbeans Ready for C++

We have a bit more work to do to set the IDE up to work with C++. The Netbeans IDE doesn’t come with a C++ compiler so this has to be installed separately.

The compiler I use is MinGW – (Minimalist GNU for Windows) download it and follow these steps (some of this is copy pasted from the Netbeans site).

1. Run the installer.

2. Accept the default install location C:\MinGW , don’t change it.

3. In the MinGW installer select the following components to install:

  • mingw-developer-toolkit
  • mingw32-base
  • msys-base
  • mingw32-gcc-g++

4. Select Installation > Apply Changes from the main menu.  Click Apply to confirm the installation and wait while the installer downloads the components.

5. Click Close when the packages installation is completed.

Now you must add the paths to the the binaries for MinGW and MSYS tools to your PATH. If you installed to the default location the paths are C:\MinGW\bin and C:\MinGW\MSYS\1.0\bin.

To edit your PATH environment variable in Windows:
  1. Open the Environment Variables window:
    • On Windows XP and Windows 2000: Right-click My Computer > Properties > Advanced tab > Environment Variables button.
    • On Windows Vista and Windows 7: Right-click My Computer > Properties > Advanced System Settings link > Environment Variables button.
    • On Windows 8: Right-Click My-PC > Properties> Advanced System Settings > Environment Variables button.
  2. In the Environment Variables window, select the Path variable in the Systems Variable section and click Edit.
  3. At the end of the path, insert a semi-colon and add the paths to the executables for MinGW and MSYS. Use semi-colons between the paths and do not use any spaces. Be careful not to remove anything already on your PATH or your computer might not work correctly.
    When you are finished, your path should look similar to the following:

    %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;
    %SYSTEMROOT%\System32\WindowsPowerShell\v1.0;C:\MinGW\bin;C:\MinGW\MSYS\1.0\bin
  4. Click OK in the Environment Variables window.
Setting up the Flowstone DLL project

So now if you followed the previous steps correctly  Netbeans should be set up to work with C++ projects.

Now open Netbeans (if it fails to open you may not have Java installed)  and follow these steps.

1. Click File > New Project.

2. In the Categories you should see “C/C++” click that category.

3. In projects select “C/C++ Dynamic Library” and click Next.

4. Enter a project name and then click Finish.

Now in the left corner you should see your project with folders such as Header Files, Resource Files ect.

Netbeans Project

 

Now right click the “Source Files” folder select New > C++ Source File. Give the file the name “function” and click Finish.

The new file should automatically open, now just copy and paste in this bit of code…

//////////////////////////////////////////////////////////////////////////////////
// Helper Macros - use as you please
#define GETFLOAT(p) *((float*)&p)
#define GETBOOL(p) *((bool*)&p)
#define GETINT(p) p
#define GETSTRING(p) *((char**)&p)
#define GETFLOATARRAY(p) p ? ((float*)p+1) : 0
#define GETINTARRAY(p) p ? ((int*)p+1) : 0
#define GETSTRINGARRAY(p) p ? ((char**)p+1) : 0
#define GETARRAYSIZE(p) p ? *((int*)p) : 0
#define GETFRAME(p) p ? ((float*)p+1) : 0
#define GETFRAMESIZE(p) p ? *((int*)p) : 0
#define GETBITMAPWIDTH(p) p ? *((int*)p) : 0
#define GETBITMAPHEIGHT(p) p ? *((int*)p+1) : 0
#define GETBITMAPCHANNELS(p) p ? *((int*)p+2) : 0
#define GETBITMAPDATA(p) p ? ((BYTE*)p+12) : 0
#define GETBITMAPBYTES(p) p ? *((int*)p) * *((int*)p+1) * *((int*)p+2) : 0
#define NEWINTARRAY(p,n) if(n>0) { *((int**)&p)=new int[n+1]; ((int*)p)[0]=n; }
#define NEWFLOATARRAY(p,n) if(n>0) { *((float**)&p)=new float[n+1]; ((int*)p)[0]=n; }
#define NEWSTRINGARRAY(p,n) if(n>0) { *((char***)&p)=new char*[n+1]; ((int*)p)[0]=n; }
#define DELETESTRING(p) if(p) { delete *((char**)&p); p=0; }
#define DELETEINTARRAY(p) if(p) { delete *((int**)&p); p=0; }
#define DELETEFLOATARRAY(p) if(p) { delete *((float**)&p); p=0; }
#define DELETESTRINGARRAY(p) if(p) { for( int j=0; j<*((int*)p); j++ ) { if( ((char**)p+1)[j] ) delete ((char**)p+1)[j]; } delete *((char***)&p); p=0; }

//////////////////////////////////////////////////////////////////////////////////

extern "C" __declspec(dllexport) void myFunction( int nParams, int* pIn, int* pOut )
{
}

Now select File > Save all to save your project.

All the defines are just handy methods for casting to certain types and creating/deleting Arrays. Trust me you will need these! Some of those methods are pretty ugly and confusing. The reason why they are needed is because “pIn” and “pOut” are int arrays so only int’s can be passed to the function (although we can actually pass many types) these int’s are the memory addresses of each type with the exception of int which is just passed “as is”. I will explain all this in more detail in the next article.

Dependencies

To avoid dependencies in your resulting DLL we can set a couple of linker options, this will ensure your DLL works on other PCs that could be missing some libraries.  Follow these steps…

1. Right click your project name , select properties > Linker.

2. Click the box with the three dots next to libraries then click the Add option button.

3. Click OK to select “Static bindings”

4. Click Add option button again and select “Other option”

5. Add “-static-libgcc” (without quotes) press OK. Click OK again then Click Apply.

Now you need to do the same again for the release build ( A Pain I know)

1. Click “Configuration” and select Release.

2. Follow the previous 5 steps again.

All setup

Phew! that is it now I promise. Now you can get on with some coding!

In the next article on the DLL component I will introduce some basic C++ code in a few functions which will highlight everything you need to know when creating a Flowstone DLL.

0 0 0 0 0
Exo

About the author:

I am the founder of Flowstone Guru. I have been using Flowstone since the early days when it was Synthmaker, talking 7-8 years now! I have created lots of things in Flowstone and have a wealth of experience with the software, some of my work you will find on this site in the Downloads section. I'm passionate about programming (Flowstone, Java ,C++,Ruby) there is nothing I like to do more. I just love a challenge and enjoy pushing myself and the tools I use to there limits!

Tags:
Add Comment Register



Leave a comment

You must be logged in to post a comment.

Back to Top