|
Impact Acquire SDK C++
|
The following compilers have been tested successfully with the Impact Acquire SDK on Windows:
On Windows for the examples only one set of project files will be part of the installation packages. At the time of writing this was Visual Studio 2013. However as Impact Acquire comes with CMake support files makefiles and project files for a wide variety of other compilers can be generated. Please refer to the Building And Linking Using CMake section for detailed instructions. When generating makefiles or project files for a compiler that is not C++11 or above, be aware that using CMake will automatically result in legacy C++ code being used for the example applications.
Impact Acquire SDK has been compiled successfully with up to gcc 11.3.
Additional information about supported compilers and minimum versions for libstdc++/libgcc can be found here
Traditional makefiles as shipped with Impact Acquire at the time of writing will support a wide variety of target platforms. However since CMake support has been added to the SDK these makefiles will no longer be maintained. The recommended way to build makefiles for compiling the SDK examples these days is by using CMake. This also automatically uses C++11 or above versions of the example code if supported by the target compiler. The ready to use makefiles will only compile C++03 versions of the code. But as Impact Acquire comes with CMake support files, makefiles and project files(e.g. for Eclipse) for a wide variety of other compilers(clang, ...) and platforms can be generated very easily. Please refer to the Building And Linking Using CMake section for detailed instructions.
Impact Acquire SDK has been compiled successfully with with clang 13.0.6, 14.0.0 and 15.0.6.
The recommended way to build makefiles for compiling the SDK examples these days is by using CMake. This also automatically uses C++11 or above versions of the example code. Please refer to the Building And Linking Using CMake section for detailed instructions.
Impact Acquire's internals are built using CMake (https://cmake.org/) and the public interface as well as the example applications are shipped with CMake support as well. Therefore the recommended way of building the example applications or any code based on the Impact Acquire SDK is by using CMake as well.
For those not knowing CMake at all please refer to the CMake website and read about it. In short it is a build system or a tool that can generate Makefiles or e.g. Visual Studio project files. It is a great tool for those who don't want to manually edit makefiles and for those who don't like to maintain makefiles for a wide range of compilers, IDEs and platforms for a single project. At the time of writing Impact Acquire was shipped with Visual Studio 2013 example project files. However by using CMake you can generate Visual Studio or GNU Makefiles matching your compiler version for the example application very easy.
CMake is a build system. It is a set of tools which can be used to generate makefiles or e.g. Visual Studio project files for a wide range of compilers.
To tell CMake what and how to generate makefiles a user needs to write configuration files understood by CMake. A big advantage of CMake is that e.g. a user does no longer need to understand the complicated internals of makefiles, that you no longer need to convert Visual Studio project files from one version to another and that you can build 'out of tree' very easily so you can keep your source tree completely free of build artifacts allowing faster searches etc. within your code. For more information refer to the CMake website: https://cmake.org/
The source code shipped with Impact Acquire comes with CMake support files. When you want to build or modify the example code using a compiler that is not supported by pre-generated makefiles that are shipped with the SDK right now you can simply use CMake to generate the necessary files. If you have never done that before the easiest way to start is probably the cmake-gui tool. Simply download at least version 3.8 of CMake, install it and start the cmake-gui tool.
After starting the tool you will see something like this:
and select the compiler/IDE you want to generate files for (select 'Borland Makefiles' if you want to compile using a Borland compiler (e.g. when using RAD Studio or any Embarcadero C++ compiler package) OR follow the CMake instruction with Ninja support from the Embarcadero website: https://community.idera.com/developer-tools/b/blog/posts/using-cmake-with-the-free-embarcadero-c-compiler, http://docwiki.embarcadero.com/RADStudio/Rio/en/Using_CMake_with_C%2B%2B_Builder)
Afterwards CMake will create the target folder and will perform various checks and basic configuration work:
Once this completed successfully you will notice a lot red properties in the upper half of the tool. These are CMake variables that have either directly or indirectly been created during the last step. Within the CMake GUI everything that is either new or has changed since the last configuration or generation run is displayed in red as there are usually so many parameters in complex projects it would be hard to see the differences otherwise. You can use the tool to modify individual properties once you know what you are doing. So right now there is nothing to worry about. Now click the 'Generate' button.
Everything went alright if no error messages are displayed in the lower output window of the application. The last message you should see there is Generating done. Now you can end the application and open the folder you did previously select for generating the files into. You will find all the project- or makefiles and a solution file (when working with Visual Studio on Windows) here. If you are working on Windows and have generated files for VIsual Studio just open the solution and you can build the examples and tools. On Linux Systems or if you have generated makefiles(e.g. for Borland) you can simply call make all instead.
make successfully (e.g. a RAD Studio command shell)
You might wonder why you cannot switch between 32-bit and 64-bit within that solution. CMake will always create projects for either 32- OR 64-bit. You can create a 2nd target folder and during the configuration process select a different generator/toolset for 64-bit output.
ZERO_CHECK project if you are working with Visual Studio on Windows). Whenever CMake detects a change in it's source files it will automatically recreate the makefiles and apply changes to e.g. a Visual Studio solution. This takes some time to get used to but is much easier than manually adjusting VIsual Studio build dependencies or project properties! Especially as most changes usually apply to Debug AND Release builds etc.. However also keep in mind that this doesn't apply to ALL properties of a project only those which are actually stored in the project file. The debugging properties (startup application, parameters debug connection for example are NOT part of the project thus can be configured as you are used to do it. This also makes perfect sense when thinking about it!
Some of the example applications and tools have certain requirements. If these are not met during the generation process CMake will output some messages why a certain target will not be available. For this target then there will also be no project file. Applications/tools with special requirements are:
The GNU Makefiles CMake generates are quite sophisticated! For example the will allow to build each target individually and when doing that all the dependencies will automatically be resolved. So you can simply call
and myTarget as well as all it's dependencies will be built automatically.
Calling
will output all the linker and compiler parameters for each file in each target.
And of course calling
will result in fast parallel builds on a machine with 8 cores. Always specify a value one higher than the actual number of cores on your build system.
Well if you are already familiar with CMake there is not too much to be said. You can simply integrate Impact Acquire into your build tree then. Impact Acquire comes with a CMake configuration file mvIMPACT_AcquireConfig.cmake located in the top-level folder of the installation. Simply include it into your build tree:
Afterwards you can use Impact Acquire imported targets and include directories. There are just a couple of variables you will need:
mvIMPACT_Acquire_INCLUDE_DIRS for all your target_include_directories statementsmvIMPACT_Acquire_LIBRARIES for all your target_link_libraries statementsmvIMPACT_Acquire::mvDeviceManager and mvIMPACT_Acquire::mvDisplay (Windows only) to your target_link_libraries statements instead if you want more control over the link requirements (e.g. if you do not want to use the mvDisplay library at all you also might not want to ship it thus consequently you will not link it)So a very simple application using Impact Acquire might look like this inside the CMakeLists.txt file:
folder structure:
root | |- myTarget | |- CMakeLists.txt | |- myCode.c | | | etc. |- CMakeLists.txt | etc.
the top-level CMakeLists then might contain something like this:
the CMakeLists.txt in the folder myTarget might contain the following code:
You may wonder why this example does not specify any include directories. Well you can do that if you like:
However this statement actually is redundant as the libraries of mvIMPACT_Acquire_LIBRARIES already add these directories to their public link interface. You can therefore either add it if you like or skip it.
On Windows Impact Acquire uses the auto-link feature if not told otherwise. Please refer to Windows to understand what impact that might have on your application and how to configure it to suit your needs.
For C++ applications not using the GenICam interface only the header mvIMPACT_acquire.h is needed. Applications also using the GenICam interface might need some addition header files:
If you want to use certain helper classes like e.g. mvIMPACT::acquire::helper::RequestProvider you will need to include
as well.
Every header file shall be included like this:
Applications also using the display module used by various example applications another header file will be needed:
Include this file like this:
So always relative to the root directory of the full package. Then and only then
will work properly!
The source code shipped with Impact Acquire comes with CMake support files. When you want to build or modify the example code using a compiler that is not supported by pre-generated makefiles that are shipped with the SDK right now you can simply use CMake to generate the necessary files. You will find the top-level CMakeLists.txt file inside the apps folder of the Impact Acquire installation.
Everything stated in this section is more or less copied from the corresponding Embarcadero documentation (http://docwiki.embarcadero.com/RADStudio/Rio/en/Using_CMake_with_C%2B%2B_Builder) and it is recommended to obtain up to date information from there. This is just meant to list the main steps needed in case the website is not available.
RAD Studio 10.2 Tokyo Release 3 includes support for building CMake projects on the command line using RAD Studio's C++ Compilers. You can compile for Windows or for other platforms from Windows. CMake supports RAD Studio's Clang-enhanced compilers: BCCAARM for Android, BCCIOSARM64 for 64-bit iOS, BCCIOSARM for 32-bit iOS, BCC64 for 64-bit Windows, and BCC32X for 32-bit Windows. RAD Studio 10.2 Tokyo Release 3 also supports using Ninja with CMake. This allows for fast parallel compilation.
Download and install CMake 3.10 or higher. Use the binary installer, since it can optionally add CMake to the system path. Make sure you select that option during the installation.
CMake files are located in C:\Program Files (x86)\Embarcadero\Studio\19.0\cmake (your version might differ from 19.0 of course). However, to prevent errors in the build process, you need to move one file manually. Follow the steps below to do this:
Windows-Embarcadero.cmake file and make a backup.Windows-Embarcadero.cmake from the Studio\19.0\cmake folder and overwrite the version in the CMake folder.Embarcadero claims to have greatly extended the inbuilt CMake support for the Windows compilers and you need to use this file to build successfully.
Download and install Ninja 1.8.2 or above. You'll need to add it to the system path manually.
Start a RAD Studio command prompt from the Start menu, or by opening a command prompt and executing rsvars.bat in the RAD Studio bin folder.
As and example how this could look like in a Windows batch file please refer to the following piece of code:
Then move into one of the generated folders and call ninja to invoke Ninja to do the actual build.
You should see something like this in your output window:
Apart from the Ninja based approach explained above the Borland/Embarcadero/RAD Studio compiler can also be used without modifying CMake as described above. In fact when modifying the CMake Embarcadero support file (Windows-Embarcadero.cmake) the approach explained here does no longer seem to work and building the example applications might fail with an error message
Generating Borland Makefiles is pretty straight forward and either be done using the CMake GUI or via the command line. A possible command line could look like this:
Then start a RAD Studio command prompt from the Start menu, or by opening a command prompt and executing rsvars.bat in the RAD Studio bin folder, move into the generated folder and call make to do the actual build.
You should see something like this in your output window:
If for whatever reason you cannot or don't want to use CMake please think again! It is much easier! If the answer is still no follow the guidelines presented in this section!
Always specify ONE include path only! It should point to the top-level folder of the SDK installation. All include statements inside the SDK headers will assume this and will therefore include additional header files belonging to this SDK relative to this top-level directory. Typically therefore this include path will be "$(MVIMPACT_ACQUIRE_DIR)". Assume your installation looks like this:
Then the one and only include path you should specify would be the path to "<myInstallationPath>". All files belonging to the interface are written in a way that they rely on this path and that no other path is needed.
For example using a Impact Acquire example application like SingleCapture in Microsoft Visual Studio in the standard installation environment, the include path should also be "$(MVIMPACT_ACQUIRE_DIR)" for the reasons mentioned above:
For example the main C++ header file mvIMPACT_acquire.h will include the C headers like this:
When building a plain C application the only header that needs to be included is mvDeviceManager.h. This header must be included in every file that uses functions belonging to the Impact Acquire 'C' interface.
Include the header into your project like this:
This will work when the include path for the project has been set up as described above.
For C++ applications usually the only header needed will be mvIMPACT_acquire.h and it shall be included like this:
This will work when the include path for the project has been set up as described above. The C++ interface is provided completely in source in a single inline wrapper file building a thin layer on top of the C interface. It (for C++ developers) is much easier to use then the conventional C layer.
Apart from that there are some other header files that provide additional features and functions when e.g. using GenICam compliant devices and drivers, functions to display images or features needed for very special applications. A full list of files belonging to this SDK can be found in the files section of this documentation.
When installing the SDK on Windows via one of the MSI packages provided, an environment variable called MVIMPACT_ACQUIRE_DIR will be registered during the installation, on Linux this variable will also be generated during the installation. It points to the route path of the installation as discussed above.
Makefiles or project files then can specify the common include path by referencing the environment variable. When working with Visual Studio on Windows e.g. by opening the settings for the current project, clicking on the "C++" tab and then "additional include directories" and adding "$(MVIMPACT_ACQUIRE_DIR)" to the list of additional directories.
The advantage of this is that this project will compile even if it is copied to a different location.
No matter whether building C or C++ applications there is only one library that needs to be linked with the application: mvDeviceManager. No driver specific library must be linked directly as these will be dynamically loaded by the mvDeviceManager shared library internally.
When working with Microsoft Visual Studio or any other compiler that supports automatic linking, no library must be specified explicitly for linking, as a "#pragma" will perform this work for you.
Direct linking of an export library however sometimes is not desired as this will result in an executable or a library, that can't be started/loaded when the linked library is not present on the target platform. Therefore sometimes dynamic loading is preferable.
To disable automatic linking your project- or makefile must define a macro NO_MV_DEVICE_MANAGER_AUTOLINK. Then however every function exported by the mvDeviceManager library and referenced in the application must be extracted from the library at runtime using the appropriate functions offered by the operating system (e.g. GetProcAddress or dlsym). The macro can either be defined directly in front of the include statement that would include the Impact Acquire API or inside the IDE project. Within Visual Studio this could be achieved like this:
Another interesting approach might be the delay-load feature introduced with Microsoft Visual Studio 2003. Here even if the linked library (mvDeviceManager.dll in this case) is not present on the target platform the application will still be executable even when linked with the import library. However in order not to crash the application once the first function exported by the missing library is called some extra precaution will be necessary. Either you can try if
succeeds before accessing functions and objects belonging to the Impact Acquire interface or you have to handle the exceptions generated by the delay load framework correctly, which is a bit more difficult and doesn't provide additional benefits.
If you want to specify the link path manually, you should refer to folder of the Impact Acquire installation. Using a Impact Acquire example application like SingleCapture, the link path to the libraries will use the environment variable "$(MVIMPACT_ACQUIRE_DIR)". Because of that it doesn't matter where the example project is located. The libraries and header files will be found in any case:
To run an application that has been built using the Impact Acquire framework all user mode libraries belonging to the framework must be located in the library search path of the application using it. The minimal list of libraries that must be present when working with the Impact Acquire frame work consists of
A detailed list of the files and settings needed to deploy an Impact Acquire device driver can be found in the chapter Installation From Private Setup Routines.
When an application that has been developed for 32-bit Windows shall be deployed on a 64-bit version of Windows some extra work might be necessary. On 64-bit Windows there can be both 32- and 64-bit user code but only 64-bit kernel code. To deploy an application on 64-bit Windows there are therefore 2 ways to go:
Even when the latter method is used no extra work is needed when using Impact Acquire as all the packages for 64-bit include the 32-bit user mode code as well.
This section contains information about the wxWidgets based applications making use of the Impact Acquire API. There main purpose is to allow the initial configuration of devices and the SDK itself as well as providing a way to check various product features quickly. The applications can also be used to copy code snippets from or to cross-check certain effects encountered during product development.
The source code of ImpactControlCenter (if installed) can be found under:
The application has been written using wxWidgets. At least version 3.x is required to build it. wxWidgets is a multi platform GUI framework. The source code (needed) can be downloaded from here: http://www.wxwidgets.org/.
After installing wxWidgets the library must be compiled.
The easiest way to build Impact Acquire applications that use wxWidgets is by using CMake as explained in detail in the section: Building The Examples And GUI Tools Using CMake. If for whatever reasons using CMake is not an option for you read on.
ImpactControlCenter is linked against the static versions of the wxWidgets libraries, thus at least these versions (debug and release, 32- and 64-bit) are required.
The Visual Studio project file for ImpactControlCenter uses an environment variable WX_WIDGETS_SOURCE_DIR as well as WX_WIDGETS_BUILD_DIR_X86 and WX_WIDGETS_BUILD_DIR_X64 to reference wxWidgets headers and libraries. The variable must be registered by the user and must point to the top level directory of the wxWidgets installation.
A Visual Studio 2013 solution file, that correctly handles the build dependencies will be installed as part of the source code. On Windows also a link will be created by the installer in the programs menu under Balluff/Impact Acquire/Sample Applications'. The link will always point to the native to version of the application that has been built with the native bit depth of your Windows installation so to the 64-bit on a 64-bit Windows.
You can easily create Makefiles or Visual Studio project files matching your compiler version using CMake. How this is done is explained here: Building And Linking Using CMake
How to build and link ImpactControlCenter on Linux is explained in the chapter "Quickstart" of the respective product manual. The source code of the application will be part of the installation package.
