How to Start ?

If you have sucessfully installed MT4j, the best thing to do when starting to develop your own applications is to take a look at the examples included in MT4j first and play around with them a little, to get an idea how everything works in MT4j. There are examples ranging from a simple "Hello World" program to more complex applications.

Furthermore you can take a look at the tutorial section to learn more about special topics.
You can also ask for help at the IRC channel #mt4j on Freenode. You can connect via Web IRC
For tips and tricks and to avoid common problems or mistakes browse through this FAQ section.
MT4j and common problems are also discussed on the NUIGroup forums.

How to get Support?

Chat - You can talk to the developers and ask questions directly in the MT4j IRC channel #mt4j on Freenode. You can also connect via Web IRC
Forum - MT4j topics are also discussed in this forum NUIGroup forums.

How do I run my application fullscreen ?

This, like many other settings, can be changed by setting the appropriate value in the file "Settings.txt", located in the MT4j root folder. In this case, the entry "Fullscreen=false" has to be changed to "Fullscreen=true". Fullscreen exlusive mode will (in most cases) prevent other windows or popups overlapping the mt4j window. It is also possible to use a different fullscreen resolution than the desktop screen resolution in fullscreen exclusive mode. The performance might also be better.

Im having problems with fullscreen mode - what can I do ?

If the fullscreen exclusive mode has problems and doesent work correctly try setting the switch "FullscreenExclusive" to "false" in the Settings.txt file. MT4j will then create a window without borders and with the dimensions of the screen. If you want to get fullscreen exclusive mode running under Windows, you should add the command line switch "-Dsun.java2d.noddraw=true" when running your applications. Under Windows Vista/7 it might also help to disable Aero.

What version of Java is required by MT4j?

MT4j applications can be run using Java 1.5+. For developing and compiling MT4j, Java version 1.6 is required since MT4j uses classes introduced by Java 1.6.

How can I use multiple mice for input ?

First, connect the mice you want to use to your system. (A laptop with a trackpad in combination with an external mouse can also be used for two separate inputs) Then change the setting "MultiMiceEnabled" to "true" in the file "Settings.txt" before starting your MT4j application. This feature is currently only supported on Windows™ and Linux platforms.
Tip: Sometimes you have to press a mouse button first before the cursors appear in MT4j.

Does MT4j run on 64-Bit operating systems?

64-Bit systems support is limited and can cause some problems. However, you can get it running by replacing the native java OpenGL libraries in the MT4j root folder with the 64-bit versions which are found in the ./mt4jLibs/jogl/ directory. For windows systems, the needed files are located in the jogl-natives-windows-amd64.jar and gluegen-rt-natives-windows-amd64.jar, for linux, in the jogl-natives-linux-amd64.jar and gluegen-rt-natives-linux-amd64.jar. These jar files can be opened by most archive programs like 7-Zip for example. If problems still exist, try changing the installed java runtime environment to a 32-Bit version.

Does MT4j support the Windows 7 (Multi-)Touch API ?

Yes, from Version 0.9 on, MT4j does support the Windows 7 Touch API. In version 0.9 it is supported when using a 32-Bit Java Virtual Machine. The latest version also works on 64 bit JVM's. If all fails, it is possible to use a workaround by using an external program that converts the native messages into the supported TUIO protocol. This 'WM_TOUCH to TUIO converter' is discussed and available for download in this thread on the NUI Group forums. The converter's transparent window has to be placed on top of the MT4j window for it to work.

How to avoid threading problems ?

In OpenGL, it is impossible to access certain functionality during drawing. Normally, this is not a problem but it can become a problem when you are using Threads in your MT4j application which interact with UI components. When accessing UI components from Threads while OpenGL is drawing (this will hapen sooner or later) results in unpredictable behavior of your application. The mechanism in MT4j to prevent this is called PreDrawAction. Code to be processed within a Thread can be placed in a class which implements the IPreDrawAcrion interface and can be added to a Scene using the registerPreDrawAction(IPreDrawAcrion action) method. Your PreDrawAction then will be performed exactly before the next time, the scene is drawn. Another way, not tied to a scene is to use the invokeLater(Runnable runnable) method of the MTApplication class. The runnable will then be exectuted when entering the next rendering frame.

I'm getting an "out of memory" error running a MT4j application - what can I do?

Using a lot of components, fonts, images or detailed geometry can use a lot of memory. By default, the java runtime allows you to use up to 64MB of RAM. If this limit is exceeded, the out of memory error is thrown. This can be solved by granting the application the right to use more memory. The java command line switch "-Xmx" allows to do this. Adding the switch "-Xmx256m" to the java command line will allow the application to use up to 256MB of RAM for example.
If you are using the Eclipse IDE this switch can be set like this:
Go to menu "Run" -> "Run configurations/Open Run Dialog.." -> select your application on the left -> "Arguments" tab -> "VMArguments" -> write "-Xmx256m" into the VMArguments text area -> "Apply"

How to avoid memory leaks ?

Unlike most 'plain' Java™ applications, MT4j is mainly based on OpenGL regarding rendering of graphics which means that Java™ garbage collection does not remove everything from memory automatically and some elements (based on native OpenGL elements) have to free their resources and memory manually. E.g. textures have a big memory footprint (even bigger with OpenGL mip mapping enabled). Manually removing components and freeing their no longer used resources can be done by calling the destroy() method of the obsolete MT4j component. If you create your own mt4j-components and create OpenGL textures, displaylists, etc you should override the destroyComponent() method (which is called by the destroy() method) and manually free all the resources that the component used there. If destroy() is invoked on any component, all of its children will be destroyed automatically, too.

Is the order in which I draw my components important?

Yes. The best practice would be the following: - Create a group (MTComponent) for each of the "layers" you need for your application. Create different groups for 2D-Components (e.g. windows, images etc - components that lie on the same plane) and 3D-Components (e.g. 3D meshes etc). This will make it a lot easier to organize your scene and the order in which components are drawn.
The order in which to add the groups would be:
1. add the 2D component groups
2. add the 3D component groups
(3. add a head up display group (ie. GUI) to be drawn in front of everything in the scene - optional)

A special case exists for (semi-)transparent components. In order for them to render correctly, they have to be drawn after the components that are supposed to be seen through the transparent parts. So these components have to be added after these components. If we have transparent components positioned somewhere in a 3D-scene, we have to render them in back-to-front order which can be achieved by sorting the transparent components by their distance from the camera (sometimes this has to be done each frame). For more informations see OpenGL transparency FAQ

How to achieve the best performance ?

Graphics performance:

• Use OpenGL as your renderer
• Running in fullscreen mode is faster on some systems (See the Settings.txt file)
• Use displaylists for drawing shapes that are immutable (usage: myShape.generateAndUseDisplayLists()) or Vertex Buffer Objects (VBO) for shapes that are changed rarely (usage: myShape.setUseVBOs(true)).
  Note: All this applies only if using the OpenGL renderer and for shapes that have more than just a few vertices.
• Enable frustum culling on your canvas (canvas.setFrustumCulling(true))

Selection/Picking performance:

• If we know that certain shapes are only 2D and lying on the z=0 plane, we can use 2D boundingshapes (ie. the BoundsZPlaneRectangle class) to accelerate picking.
• We can set the picking behaviour of the shape to the value "BOUNDS_ONLY_CHECK" so that only the bounding shape is checked for a hit and not the real shape which is advisable for complex shapes. (usage: myShape.setBoundsPickingBehaviour(AbstractShape.BOUNDS_ONLY_CHECK)")

Can I develop MT4j applications with the Processing IDE?

At the moment you can't use MT4j as a processing library. The architecture of MT4j differs too much from a usual Processing sketch. To develop MT4j applications it is recommended to use a java IDE like Eclipse or Netbeans.

I'm getting several errors about missing and unresolved classes (i.e "ArrayDeque") - whats the problem?

Youre probably referencing a Java version older than version 1.6. You have to switch to java version 1.6+ to resolve these problems. If you dont have Java version 1.6 installed, download and install it first. Using the Eclipse IDE, you can then switch to the new Java Runtime Environment (JRE) at "Window"->"Preferences"->"Java"->"Installed JREs"->"Add..."

How to contribute ?

Contributions to the mt4j project are always welcome. If you create MT4j scenes or components you need for your projects, please consider sharing them with the community. Further information about how to contribute to MT4j, you can find here.

Page as PDF

My MacBook has a multi-touch trackpad - how can I use it for input?

Since Version 0.95 MT4j has an Input Source for muli-touch mac trackpads. It is disabled by default. To enable it put the following code into your application's startUp() method:

getInputManager().registerInputSource(new MacTrackpadSource(this));