SDK tutorial
RTMAPS SDK, A SIMPLE TUTORIAL
This document will show you how to write your first RTMaps component in C++ using the RTMaps SDK and its Wizards.
Duration: 5 min.
Download the pdf.
OBJECTIVES
- learn how to use the RTMaps SDK Wizards
- create in less than 30s a new RTMaps package with a new component inside,
- compile it, and run it in the Studio.
INTENDED AUDIENCE
C/C++ developers
OS
Windows
DEVELOPMENT ENVIRONMENT
Visual C++ 2003. The procedure for Visual C++ 2005 is similar.
Note for Visual C++ 6.0 users: The RTMaps wizards used for automatic generation of projects and code skeletons is available as a separate tool (i.e. not included in the Visual Studio environment) but provides the same functionalities.
RTMAPS SDK DESCRIPTION
Double click on the RTMaps SDK VC 2003 icon on the desktop. The RTMaps SDK solution contains 2 pre-existing projects:
- rtmaps_samples and rtmaps_user_modules.
- rtmaps_samples contains a number of RTMaps components source codes that you may browse in order to find out how to write such or such functionalities.
MAKE YOUR OWN PACKAGE OF COMPONENTS
To make your own new package of component, click on "Tools" menu, choose RTMaps, then New Package. Enter the name of your new package in the form that just appeared. Ex: MyPackage.
A new project called "rtmaps_MyPackage" has been created and included in the Visual Studio Solution.
This project contains all the necessary compiler and linker options to make an RTMaps package (which is actually a dll file, renamed with a pck extension). At this point, this package is empty: it contains no source code and thus no component.
CREATE A NEW COMPONENT IN YOUR PACKAGE
Select the project you have just created in the Solution Explorer. Click on "Tools" menu, choose RTMaps, then New Module. Enter the name of your new component in the form that just appeared. Ex: MyComponent.
Two new files have been automatically generated and included in the project: rtmaps_MyComponent.h and rtmaps_MyComponent.cpp. The .h file contains your component class declaration, and the .cpp contains the component implementation.
Edit the ".cpp" file. The first section (made of macros) is aimed at defining the structure of your component: how many inputs, of which type, etc... how many outputs, properties, actions, what is the component name, its version, etc...
then 3 methods have to be implemented:
1) the Birth method, which is called once by the RTMaps engine each time the diagram starts executing,
2) the Core method which is the main function of the component:this method will be called in a loop (like a while(true)) while the diagram is running.
3) the Death method which will be called once by the RTMaps engine when the diagram is shutdown.
After automatic generation, those 3 functions are implemented with simple calls to the ReportInfo function, which displays messages in the Studio console.
Note: the Core method also contains a function Rest(500000), which calls a pause of half a second on the current thread. This is necessary otherwise the component would consume 100% CPU by looping without any pause on the ReportInfo function, thus saturating the console.
COMPILE YOUR PROJECT
(If you are in debug mode, the output directory will be by default .../RTMaps 3.4/rtmaps_sdk/package/debug.)
Open the RTMaps Studio, register the rtmaps_MyPackage.pck file that has just been compiled and place a MyComponent on the diagram, and run the diagram. Messages are displayed in he console.
You can unregister the package by right-clicking on the registered package and selecting "Unregister". You can then modify the source code, recompile the package, then reload it the RTMaps Studio.
