Release 5.0 is a result of development effort of nearly two years. This is a major release that introduces significant new features compared to the last 4.x version, for example the Canvas API (2D graphics), OpenSceneGraph-based 3D graphics support, improved logging, a new Qt-based runtime environment that will eventually replace Tkenv, and much more.
We have also taken the opportunity of the major release to improve several corners of the OMNeT++ API, and also to get rid of deprecated functionality. For porting models from OMNeT++ 4.x, see doc/API-changes.txt which lists all changes, with hints on how to update the model code.
In the IDE, breakpoints set during a debugging session may not take effect. The workaround is to restart the debug session after setting the breakpoint. See bug #956.
Changes since the release candidate:
Several organizational and rendering improvements on the API documentation generated using Doxygen.
The User Manual has been renamed to Simulation Manual to reduce the chance of confusing it with the User Guide (which describes the IDE and Tkenv/Qtenv).
Improved the contents and the HTML rendering of the Simulation Manual.
cFigure: skew() methods now take a coefficient instead of an angle.
cOsgCanvas: initialize zNear/zFar to NaN (to indicate they are unset by default), and added the methods setZLimits(), clearZLimits(), hasZLimits(). Missing zNear/zFar will turn on automatic zNear/zFar computation in the viewer.
Removed a Register_Enum()-related workaround introduced around OMNeT++ 5.0b2 so that it could compile INET-3.0.
cFingerprint renamed to cFingerprintCalculator.
cKSplit: method rangeExtension(bool) has been renamed to setRangeExtension().
cModule::size() has been deprecated (use getVectorSize() instead).
Several methods in cComponent, cModule, cSimpleModule, cChannel, cArray, cQueue, cTopology, cStatistic and other classes have been made virtual to allow the user override them.
Fix: simtime_t was not part of the omnetpp namespace.
Fixed #943 which prevented using cDatarateChannel’s forceTransmissionFinishTime() method when the channel’s busy state signal was recorded into an output vector.
Fixed tooltip-related problems: large tooltips could not appear (e.g. the help for log prefix in the Preferences dialog); submodule tooltips were missing from the canvas
Added help to the Log Prefix field in the Preferences dialog and filter fields in the Find Objects dialog
Added tooltips to timeline messages
Fix: on Windows, Earth scenes appeared distorted in the osg-earth and osg-satellites sample simulations
Fix: Earth scenes did not display in the osg-intro sample simulation (blank viewer window)
Additionally, several bug were fixed in the IDE, Tkenv and Qtenv.
This release brings numerous refinements to APIs introduced in previous beta versions, several bug fixes, and relatively few new features. The manual has been improved and brought up to date for the most part, although there are still gaps that will be filled in for the final 5.0 release. The most conspicuous change will be the new simulation time display in Tkenv and Qtenv.
Introduced WITH_TKENV, WITH_QTENV, WITH_OSG and WITH_SYSTEMC in configure.user; these options allow one to disable certain features if they are not needed. In particular, WITH_TKENV=no replaces NO_TCL=1
The logging API was refined. In addition to several renames (e.g. GLOBAL_COMPILETIME_LOGLEVEL was changed to COMPILETIME_LOGLEVEL), the numeric order of log level constants (LOGLEVEL_*) was reversed to make the values consistent with semantics, and LOGLEVEL_OFF was added to allow one completely disable logging. Support for log filtering was added in the form of compile-time and runtime predicates. The default compile-time log levels were also changed (to TRACE in debug builds, and DETAIL in release builds).
In the OpenSceneGraph API, OmnetppObjectNode was renamed to cObjectOsgNode. Static cOsgCanvas methods that existed for creating and manipulating such nodes (createOmnetppObjectNode(), isOmnetppObjectNode(), setOmnetppObject(), getOmnetppObject()) were removed, and one should directly use cObjectOsgNode instead. Also, the osgutil.h header is now part of omnetpp.h, so it doesn’t need to be included separately.
In cOsgCanvas, the redundant setPerspective() method was removed (it was a union of two other setters).
There were several refinements in the cFigure API:
replaced getClassNameForRenderer() with getRendererClassName()
spelling: ArrowHead changed to Arrowhead in method names, enum name, etc.
move() made recursive, nonrecursive version is called moveLocal()
Pixmap: renamed resize() to setSize()
Transform: skew() methods to use coefficient instead of angle
Transform: the matrix was transposed so points can be column vectors instead of row vectors
added NUM_GOOD_DARK_COLORS and NUM_GOOD_LIGHT_COLORS
some cPixmapFigure methods were also renamed
Refined @figure syntax, the way figures can be defined in NED files:
transform= now accepts "( (a b) (c d) (t1 t2) )" and matrix(a,b,c,d,t1,t2) syntaxes as well
in transform=, scale() now accepts center as well
in transform=, skew() now expects coefficient instead of angle
arc, rectangle, image, etc to support bounds=x,t,width,height as an alternative to the pos=,size=,anchor= triplet
Revised the configuration options that control recording of @statistics, individual scalars, and histograms. As a result, the **.statistic-recording and **.bin-recording options were introduced that take over some of the responsibility of the formally overloaded **.scalar-recording option. Rationale and details in src/envir/ChangeLog.
Added cIEventlogManager, a new Envir plugin class that allows one to replace the built-in eventlog manager. Eventlog managers are responsible for recording simulation history into an eventlog file. A new eventlog manager can be activated with the eventlogmanager-class configuration option.
The cFingerprint class was renamed to cFingerprintCalculator, and the fingerprint-class config option to fingerpringcalculator-class.
In cEnvir, renamed getRNGMappingFor(component) to preconfigure(component).
In cSimulation, moved both updating the event number and simulation time into executeEvent(). They were updated inconsistently, plus executeEvent() is a better place for that than getNextEvent(), considering cScheduler’s putBackEvent().
Removed cEnvir::isDisabled() and added cEnvir::isLoggingEnabled(). Renamed cEnvir::disableTracing member variable to cEnvir::loggingEnabled.
cModule: size() deprecated, use getVectorSize() instead
More methods made virtual in cSimpleModule and other classes
Improved the descriptions of several per-object config options.
Added a large simulation time and event number display to the toolbar that display the *current* simulation time (or the time of the last event), as opposed to the time of the next event displayed previously. The status bar below the toolbar displays information about the *next* event, together with the time delta from the current simulation time. Information on the currently set up simulation, along with message statistics, have been moved to the bottom status bar of the main window.
Added a large simulation time and event number display to the toolbar. (This is the same GUI change as in Tkenv, see above.)
Changed the name of the preferences file to .qtenvrc.
Numerous bug fixes and improvements.
Configuration options controlling logging in non-express mode (cmdenv-express-mode=false) have been simplified. The following options have been removed: cmdenv-module-messages, cmdenv-global-log-level, **.cmdenv-ev-output. The equivalent functionality (enabling/disabling logging and setting the log level globally and per-module) is now controlled with **.cmdenv-log-level. Logging can be disabled with **.cmdenv-log-level = OFF. Note that the cmdenv-event-banners and cmdenv-log-prefix options still exist.
The cmdenv-message-trace configuration option has been removed. It had very limited usefulness, and it was somewhat overlapping with eventlog.
Updated visualization in samples to use the new refreshDisplay() callback.
Removed google-earth demo. (We already have a similar demo, osg-earth.)
opp_featuretool revised and improved
The highlights of this release are the experimental version of Qtenv (which is a Qt-based runtime environment that will eventually replace Tkenv), support for 3D graphics using OpenSceneGraph, and the addition of the much-requested opp_featuretool utility. The full list follows:
Use of the omnetpp namespace was made permanent. The recommended way of porting models is to add the "using namespace omnetpp;" like to header files. To compile models without change, add -DAUTOIMPORT_OMNETPP_NAMESPACE to the compiler command line.
Added 3D graphics support via OpenSceneGraph. The 3D scene graph is to be built using the OpenSceneGraph API (e.g. loaded from file via osgDB::readNodeFile()), and then set onto a cOsgCanvas instance. 3D scene(s) can be visualized in the new Qtenv runtime GUI. (There is no 3D support in Tkenv, due to technical limitations.)
Added resolveResourcePath() to cEnvir and cComponent. The method searches a number of folders for a resource given with its file name or relative path, and returns the path for the first match. It can useful for locating various data files for models, OSG model files, and other files.
Visualization: added a method to the base class of modules and channels to serve as a container of visualization-related code. refreshDisplay() is invoked by graphical user interfaces (Qtenv, Tkenv) whenever GUI contents need to be refreshed. Display string updates, canvas figures maintenance, and OSG scene graph updates are probably best done inside refreshDisplay() methods, as it can result in significant performance gain and, in some cases, also in more consistent information being displayed.
An isExpressMode() method has been added to cEnvir to query whether the simulation runs in Express mode under a GUI. This information can be useful additional input for refreshDisplay() code.
The simtime-scale config option has been replaced by simtime-resolution, a more user-friendly incarnation. simtime-resolution accepts time units (s, ms, us, ns, ps, fs, as), power-of-ten multiples of such a unit (e.g. 100ms), and also base-10 scale exponents in the -18..0 range (mostly for backward compatibility with simtime-scale).
RNG-to-module mapping made more flexible: the *.rng-<N> config option now allows expressions, including those containing index, parentIndex, and ancestorIndex(level). This change allows things like assigning a separate RNG to each element of a module vector.
Fingerprint computation has changed. It was also made more flexible, e.g. it is now possible to control which ingredients are added into the fingerprint computation. Define USE_OMNETPP4x_FINGERPRINT at compile-time to get back OMNeT++ 4.x fingerprints.
Signal listener interface change: A cObject *details argument has been added to emit() methods to allow simulation models provide extra information with primitive data types (double, long, etc) they emit, without the need to switch over to emitting cObject altogether. This is a non-backward- compatible change: signal listeners will need to be updated with the extra argument. To facilitate transition, you can compile OMNeT++ and models with WITH_OMNETPP4x_LISTENER_SUPPORT defined; this will set up cIListener to delegate to the old methods, so existing listeners will work.
Result filter/recorder interfaces, being based on signal listeners, have undergone a similar change. Models containing custom result filters or recorders will need to be updated.
SimTime overhaul to increase accuracy (i.e. use integer arithmetic where possible), improve the API, and add missing operations/functions. Details:
Added missing * and / operators for integral types. This causes integer multiplications/divisions to be computed with integer arithmetic instead of floating point, resulting in better accuracy.
Added overflow checking for integer multiplication and negation
Use int64 arithmetic and overflow checking when assigning from integer types
Replaced "int exponent" with "SimTimeUnit unit" in the two-argument constructor (value + unit) and several other methods, with the aim of making the API more user-friendly (and model code easier to read). Models that call affected methods with integers will need to be updated.
Moved math functions like fabs(SimTime) into the omnetpp namespace
Added div(SimTime, SimTime); also refined related fmod()'s documentation
Removed SIMTIME_RAW(), STR_SIMTIME(), and SIMTIME_TTOA(). These macros are no longer needed, as were introduced in OMNeT++ 4.0 to assist porting models from version 3.x where simulation time was stored in double. Also, MAXTIME was renamed to SIMTIME_MAX.
The tkenv-image-path config option has been replaced with image-path.
NOTE: The above descriptions have been edited for brevity. More information is available in the ChangeLog files (e.g. include/omnetpp/ChangeLog and src/sim/ChangeLog), and in doc/API-changes.txt.
Qtenv, the Qt-based runtime environment is currently in preview status, Tkenv is still the default runtime. Qtenv can be activated by adding the '-u Qtenv' switch to simulation command lines. Alternatively, specify 'PREFER_QTENV=yes' in configure.user to make Qtenv the default GUI. Note that 3D visualization is only available in Qtenv.
Updated the bundled SystemC reference implementation to version 2.3.1
Several new examples (osg-intro, osg-earth, osg-indoor, osg-satellites) have been added to the 'samples' folder to demonstrate the new 3D visualization capabilities in Qtenv.
Aloha has been updated to use the new refreshDisplay() method.
Added 'opp_featuretool', which is basically the command-line equivalent of the Project Features dialog in the IDE: it allows one to enable/disable project features defined for an OMNeT++ project, e.g. the INET Framework.
Because of the new Qtenv runtime environment, OMNeT++ now has several additional dependencies: Qt4 is mandatory, while OpenSceneGraph and osgEarth is optional. Qtenv can be fully disabled by commenting out the QT_VERSION= variable in the configure.user file and then re-running ./configure. Building Qtenv without the OpenSceneGraph libraries will disable 3D visualization support in Qtenv.
A separate Mac OS X specific installation bundle was created that contains the binary files for all the external dependencies (Tcl/Tk, Qt, OSG, osgEarth etc.) As a consequence you no longer have to manually install Quartz before installing OMNeT++. We have now separate installation bundles for Linux/Mac/Windows.
The bundled toolchain on Windows has been updated to use MinGW-w64 (32-bit) containing both the 'gcc' and 'clang' compilers. The bundle contains all the dependencies needed to build OMNeT++ (including Tcl/Tk, Qt4, OpenSceneGraph, osgEarth etc.)
Because of the large size of the extra dependencies (Qt, OpenSceneGraph), the tools directory is now distributed as a highly compressed archive file inside the Windows installation bundle. It is extracted to its final location when mingwenv.cmd is first started.
On systems that have both the 'gcc' and 'clang' compilers installed, OMNeT++ will pick 'clang' by default. This behavior can be changed by the PREFER_CLANG variable in the configure.user file.
OMNeT++ classes are now in the "omnetpp" namespace. Models need to be modified to compile, e.g. by adding "using namespace omnetpp" or USING_NAMESPACE lines at appropriate places. (The latter conditionally expands to the former when needed, and to the empty string when not, making your code compatible with OMNeT++ 4.6 too.) If you don’t want to change the model source code, you can define the AUTOIMPORT_NAMESPACE macro on the compiler command line (add -DAUTOIMPORT_NAMESPACE to CFLAGS), which will basically add the using namespace directive at the end of <omnetpp.h>. Turning off the omnetpp namespace (by setting USE_NAMESPACE=no in configure.user) is no longer fully supported, and will be removed in the next beta.
Introduced cRandom, which encapsulates a random number stream into an object. Random numbers can be extracted with the draw() method. Added the following cRandom subclasses: cUniform, cExponential, cNormal, cTruncNormal, cGamma, cBeta, cErlang, cChiSquare, cStudentT, cCauchy, cTriang, cWeibull, cParetoShifted, cIntUniform, cBernoulli, cBinomial, cGeometric, cNegBinomial, cPoisson. They encapsulate the similarly named functions (e.g. exponential()) with their parameters and the random number generator (cRNG). cStatistic also now subclasses from cRandom: it can generate a random variate from the distribution observed in the collected sample.
Random variate generation functions (normal(), etc.) signature change: the trailing "int rng" (RNG index of context module) argument was changed to cRNG*, and moved to the front. Motivation: break the functions' dependence on the context module. However, to lessen the impact of the signature change, random variate generation functions with their original signatures have been added to cComponent as methods. Thus, models that only use those functions from module methods will not notice any change.
The interface of iterators (GateIterator, SubmoduleIterator and ChannelIterator in cModule, cQueue::Iterator, etc.) have been changed to make them more consistent with STL iterators. Therefore, operator() as a means of dereferencing has been deprecated, and operator* and operator-> have been added instead. The increment/decrement operators have also been revised.
FES made replaceable. To this end, an abstract cFutureEventSet base class has been introduced, and cMessageHeap (now renamed cEventHeap) was made to extend cFutureEventSet. An accessor method (cFutureEventSet* getFES()) has been added to cSimulation, and the older members msgQueue and getMessageQueue() have been removed. Simulations now accept a 'futureeventset-class=<classname>' configuration option.
Further refinement of the new canvas API (cCanvas and cFigure + subclasses)
The "simulation" and "ev" macros have been removed, to reduce pollution of the global namespace. You can use the newly introduced getSimulation() and getEnvir() functions instead.
cObject::parsimPack() has become const. You only need to pay attention (and add "const" manually) if you have classes that redefine parsimPack().
cQueue and cMessageHeap had both length()/getLength() and empty()/isEmpty() methods; the former have been removed; use getLength() and isEmpty() instead.
There have been several other, smaller changes and improvements in many classes, e.g. cException, cStatistic, cDensityEstBase, cObjectFactory, etc.
Most methods, typedefs and other items deprecated in previous versions have been removed.
See doc/API-changelog.txt for a complete list of changes.
Allow a "module" to extend a "simple" (motivation: INET 3.x)
The message compiler no longer appends "_var" to the names of data members in generated classes. In cases where this change breaks existing code (classes with @customize(true) or with subclasses), you can emulate the old behavior by adding the following to the message definition: '@fieldNameSuffix("_var");'
In message compiler generated code, doPacking() has been renamed to doParsimPacking(), doUnpacking() to doParsimUnpacking().
Feature: double-clicking a module in the object tree will open it in the main area instead of opening a new inspector window. A new inspector can still be opened from the context menu.
Added the "Hide namespaces" option in the Preferences dialog that turns off the display of the namespace part of C++ class names when they appear in the GUI.
Images under images/old/ are no longer accessible without the "old/" prefix, so if you use such an icon, you must add the "old/" prefix manually for them to continue to work. For example, you have to change "i=cloud" to "i=old/cloud" in display strings. The feature to let old/* images be accessible without the prefix was originally introduced to ease the transition from OMNeT++ 3.x to 4.0.
Several bug fixes
The include/ folder was restructured: only the public header <omnetpp.h> was left in it, all other include files were moved into an omnetpp/ subfolder under include/.
The source tree (src/) has gone through several modernizing and cleanup steps:
Per-folder nested namespaces have been introduced, e.g. Tkenv code is now in the omnetpp::tkenv namespace.
Qualified includes with the folder, i.e. #include "stringutil.h" became #include "common/stringutil.h". This increases readability and reduces the chance of including a wrong header.
Use fully qualified header guards
Modernizing: use the 'nullptr' and 'override' keywords; use C++ names of C headers (e.g. <cstdio> instead of <stdio.h>).
Code style: renamed many identifiers (local variables, arguments, private data members, etc.) to have a consistent, camelcase naming); codebase reformatted to have a consistent indentation style.
Clarifications in the Academic Public License.
Removed JSimpleModule due to lack of users and good use cases
Added the Canvas API, a figure-based 2D drawing API. The Canvas API allows augmenting simulations with graphical elements. Item types include various shapes, text and image, including an SVG-like "path" item (a generalized polygon/polyline, with arcs and Bezier curves). Transformations (scaling, rotation, skewing) are supported, as well as transparency.
New logging API. It features six log levels (FATAL, ERROR, WARN, INFO, DETAIL, DEBUG, TRACE), category support, compile-time and runtime global and per-module log level thresholds. Also, much more information is passed with each log line to the user interface code, allowing one to display a wealth of information in the log prefix (log level, file/line, event number, simulation time, module name and type, object name and type, and so on). Incompatibilities:
lower-case ev<< is no longer legal, use EV<< instead
ev.printf() was removed, use the stream API (EV<<) instead
Introduced cEvent as a base class of cMessage. cEvent allows scheduling of arbitrary code for a simulation time that runs independent of modules. Override the execute() method of cEvent to specify the code. cEvent is not intended for use in simulation models; the primary motivation is to allow implementing simulation time limit with an "end-simulation" event, and to encapsulate foreign events (e.g. SystemC events and crunching) for seamless integration with the simulation event loop.
Added support for simulation lifecycle listeners. Listeners are called back before and after network setup, on network initialization, before and after network finalization, and so on. The motivation was to allow more flexibility when writing initialization and shutdown code for schedulers, result file managers and other extensions.
Channel objects made equal to modules in the sense that now they also have IDs (the getId() method was moved from cModule to cComponent, the common base class of modules and channels), and they are also registered with cSimulation.
added factory methods for links and edges
added methods to manipulate the graph (e.g. build a graph from scratch)
Removed int8..int64 and uint8..uint64. Models should use the standard integer types from <stdint.h> that end in "_t": int8_t, uint8_t, etc.
check_and_cast<> improved; added check_and_cast_nullable<> that accepts NULL pointer as input
New fingerprint computation algorithm. The goal was to make the fingerprint less sensitive to uninteresting changes (e.g. removal of an inactive module), and more sensitive to interesting ones (e.g. change in packet lengths). To get the old fingerprints, define USE_OMNETPP4x_FINGERPRINTS when compiling OMNeT++.
cClassDescriptor interface changes (method renaming and arg list changes)
Code cleanup, including:
removal of 3.x backward compatibility features (WITH_DOUBLE_SIMTIME, WITHOUT_CPACKET)
removal of deprecated classes, functions and macros (cLinkedList, cSimulation::operator, Define_Function(), etc.)
cTopology: internals refactored (use STL instead of arrays, etc.)
error code enum members renamed from eXXX to E_XXX
Log lines can now be prefixed with information such as the module path; simulation time; event’s class and object name; file/line of the log statement; class, name and pointer of the object containing the log statement; etc. The format of this prefix can be changed from ini files.
New inifile config options: cmdenv-log-format, cmdenv-log-level.
The bgs (background scaling) display string tag has been removed. It was originally introduced more or less as a default zoom level, but lost its significance since interactive zoom has been introduced.
Zooming no longer affects icon sizes on the screen (but you still have the Increase/Decrease Icon Size, Ctrl+I/Ctrl+O menu items in Tkenv).
Finished implementation of the Canvas API Tkenv rendering. The implementation is based on figure renderers (see FigureRenderer class) that can be registered for various figure classes. The implementation is based on the Tkpath Tcl/Tk extension, which was significantly enhanced by our team.
Tkpath is now also used internally for drawing submodules, connections and the like. Benefits include:
unlimited zooming of image backgrounds
antialiased drawing (Tk canvas didn’t have antialiasing)
OS X: images are no longer forced into 1-bit transparency
labels are now outlined (have a "halo") to make them readable on noisy backgrounds
range indicator fill is now semi-transparent (because Tkpath supports that)
performance improvements e.g. on OS X, and with image backgrounds
Display log prefix; log prefix format and log level configurable via the Options dialog
Several minor improvements. NED editor support for canvas items is pending.
Added samples/canvas, a demo for the Canvas API
Bugs fixed: see http://dev.omnetpp.org/bugs/changelog_page.php?project_id=1