Java3D Android support released

Java3D can now be easily used on Android via Android Studio.
The project that supports this is called Java3D-Android and it is an extension to desktop Java3D.

There are just 2 small edits to an Android Studio project to get Java3D-Android integrated into the code.

1.
The file settings.gradle in the root of the project needs the jogamp maven repo added to it:

maven { url "https://jogamp.org/deployment/maven" }
maven { url "https://jogamp.org/deployment/maven-java3d" }

like so:

 
2.
The file gradle.build in the “app” folder needs these dependencies added to it

implementation ('org.jogamp.java3d:java3d-core-and:1.7.2' )
implementation ('org.jogamp.java3d:java3d-utils-and:1.7.2')

Like so:

 

That’s it! You will now be able to call Java3D classes; here is a simple HelloWorld code that will run with those 2 small edits.
HelloUniverseActivity.java



All of the Java3D examples can be seen in the Java3DAndroidExamples project.
Instructions on how to get that code running are at the bottom of this post.
The examples show:
• How to mix normal View elements with Java3D
• How to keep your 3D context alive when the app is paused/resumed
• How to do interface elements that are “on top” of the Java3D window (FPSCounter)

Conversion of an existing project:

To get Java3D to run on Android required 2 major steps and each one has made the code slightly different from the basic Java3D on desktop.

It is worth noting that Java3d-Android can be easily run on desktop (from for example Eclipse), so debugging and project conversion are facilitated. Conversion projects can start by converting to an “android compatible” project that uses the java3d-core-and and java3d-utils-and libraries, then taken to the actual android studio environment. I’ve found this a nice way to separate the issues caused by conversion from the many more numerous issues arising from trying to write code in Android Studio.

No AWT

The Android runtime has no java.awt package. Java3D is built to integrate extremely tightly with the awt windowing system, so to run it on Android there is a “façade” package called javaawt (notice the dot is lost). As it happens java.awt holds the incredibly useful package java.awt.geom, so that sub package had to also be re-created.  This façade system means that that the lifecycle of Canvas3D has changed slightly. It also means that if a BufferedImage needs to be loaded onto the pipeline TextureLoader must be used with a URL and these 2 lines must appear early in the code:
javaawt.image.BufferedImage.installBufferedImageDelegate(VMBufferedImage.class);
javaawt.imageio.ImageIO.installBufferedImageImpl(VMImageIO.class);

OpenGLES2

OpenGLES2 (which is the 3d driver on Android) has no fixed function pipeline, so every 3D object must be rendered via a shader pair. Users of Java3D-Android can basically ignore this issue, as the SimpleShaderAppearance class writes and uses shaders that mimic the fixed Function Pipeline automatically.
By examining the output of that class it’s trivial to extend the shaders for your self and make things look very nice. The Shader Appearance class for Java3D-Android is the same as desktop version.
This line needs to appear early in your code:
SimpleShaderAppearance.setVersionES300();

So ALL instances of Appearance in your code need to be swapped to SImpleShaderAppearance but both have a no arg constructor so this is a find/replace step.
ShaderAppearance instances will need the shader code updated to be compatible with GLSLES3

The GL2ES2Pipeline limitations

These limitations will be written out to standard err if they can be detected by the pipeline. In many cases they cannot and will either be ignored or throw an exception.
These 3 are likely to need attention:
• Coordinates must be defined and of type float, colors must be float type, if defined.
• QuadArray or IndexedQuadArray cannot be supported.
• It is strongly recommended that you use the format GeometryArray.USE_NIO_BUFFER = true.
These others are probably less important depending on what features you have used, and the age of your code.
• Decaling is not supported.
• Model Clip is not supported and must be re-implemented in shaders
• Texture Coordinate generation cannot be supported, examples of it's use can be found in SimpleShaderAppearance in the Java3d-Utils.
• Texture Lod, Filter, Sharpen and Combine cannot be supported
• Texture3D cannot be supported.
• Accum style anti-aliasing cannot be supported.
• RasterOps from RenderingAttributes cannot be used.
• Note LineArray and LineStripArray will not render as nicely as the fixed function pipeline.
• Antialiasing enable/disable GL_MULTI_SAMPLE is gone, but the method glSampleCoverage exists still, so if the caps support it then it must be on GL_SAMPLE_ALPHA_TO_COVERAGE and GL_SAMPLE_COVERAGE can be enabled under ES2
• Display lists are removed, so if you are not using by_ref geometry you are likely to need to add System.setProperty("j3d.displaylist", "false"); somewhere in the first lines of your code.
• Line patterns cannot be supported
• Screen door transparency cannot be supported
• AutoMipMaps are disabled as pure ES2 has a separate system glGenMipMaps but GL2ES2 doesn’t support this
• Image formats without Alpha (like TYPE_INT_BGR) will not have alpha forced to 1, so alpha will be undefined
• Texture boundary colors gone (and therefore CLAMP_TO_BOUNDARY)
• ImageComponentRetained.TYPE_BYTE_ABGR and Texture.INTENSITY andImageComponentRetained.TYPE_INT_BGR cannot be supported

Converting Interface heavy apps:

If you have a deeply complex and rich awt project on desktop it’s not impossible to replicate the entire functionality using some boiler plate code and some adapter classes, as I have done in renovations3D www.renovations3D.com

The source code is not yet nicely published, but it’s open source here:
 https://bitbucket.org/philjord/renovations3d-android/src/master/app/src/main/java/com/mindblowing/swingish/
 

Source code for Java3D-Android:

The code repos for Java3D-Android are here:
https://github.com/philjord/vecmath
https://bitbucket.org/philjord/java3d-core-and
https://bitbucket.org/philjord/java3d-utils-and
https://bitbucket.org/philjord/java3d-examples-and

If you don’t use gradle to get the jars, a support jar is needed to make Java3D-Android run; that can be downloaded from here:
https://jogamp.org/deployment/maven-java3d/org/jogamp/java3d/java3d-jogamp-and/1.7.1/java3d-jogamp-and-1.7.1.jar

Cloning and running the example code

Open Android Studio

If there is no current project the window "Welcome to Android Studio" will pop up. Press "Get from VCS"

or if you have a project open
File->New->Project from Version Control…

Either of the above will open the  "Get from Version Control"
Use Version Control: Git
URL: https://github.com/philjord/Java3DAndroidExamples 
Then press "Clone"

This will download the source…

Once downloaded
Select Build->Make Project

If you get this extremely common android studio config problem:
SDK location not found. Define a valid SDK location with an ANDROID_HOME environment variable or by setting the sdk.dir path in your project's local properties file at 'C:\Users\pjnz\StudioProjects\Java3DAndroidExamples\local.properties'.
Go here and create the file needed with the single line needed:
https://stackoverflow.com/questions/27620262/sdk-location-not-found-define-location-with-sdk-dir-in-the-local-properties-fil/56089502#56089502


You can now run the app, and enjoy…


I'm extremely happy to help anyone who needs it to get a project converted.


I'd like to thank Sven for his amazing work here, Java3D on Android is only possible because it's built on the fantastic Jogl project, which did all the hard work.
I'd also like to thank Julien for mentoring me through all of this.

Excellent job, it's a great step in the good direction for Java3D. Keep up the good work

Hi Phil, looks like lots of work - great to extend Java3D to the Android platform, congrats.

Briefly reading through your description, are you using the Android OpenGL binding?
If so, this would not allow to mix existing JOGL + Java3D.

Since AWT has been excluded for this version as well as fixed function pipeline
due to the ES2+ constraints - how about trying using our JOGL + Java3D on Android?
Would serve the goals .. same API throughout and so forth.
If you like to do that, I maybe able to help a little.

Also, can the Java3D code been consolidated, i.e. one source for both platforms
as we do it with JOGL? AFAIK you can host on on our server here, all permissions should
have been granted.

Now I make your post sticky in the Java3D subforum .. let's see if I figure it out :)

Great stuff .. Java3D keeps kicking .. congrats again!

It seems to use JOGL according to this:
https://bitbucket.org/philjord/java3d-core-and/src/master/src/org/jogamp/java3d/JoglesPipeline.java

+1 for not using Github :)

Sven, thanks for the feedback.

Java3D-Android uses Jogl 2.4.2, the Android binding.
In fact I only attempted this because the ES2 support in Jogl was so great.

It’s almost entirely ordinary Java3D, users should be able to convert form desktop to Android in a couple of hours.

It has  two significant alterations from base Java3D

A new Pipeline class that automatically supports fixed function coding paradigm being pushed out to a programmable world, so it has a bunch of “virtual” attributes and uniforms that magically appear if needed on the shader based on the Java3D Shape3D  attributes. It also has an Appearance class that writes shaders for the user, who can then inspect them and see FFP to programable conversion examples.

It also had to have every class that touches java.awt swapped for a very similar version that uses javaawt package instead. So of the 409 Java3D main classes this project alters only 69 of those, and only about 10 of them significantly.

The biggest differences are that image loading is a bit “at odds with” normal awt, so if you want to show a BufferedImage on a ImageIcon and also in Java3D you have to load it twice, one in java.awt and one in javaawt.
Also the Canvas3D has been royally mashed up.

I had to make a stack of memory optimisations, that should flow back to Java3D core at some point.I made it support compressed Textures as well, because phones are very small platforms.

So once iPhone is running on Jogl I’m very keen to follow up with a Java3D for that platform.

As an interesting note, I had to make some “bug” fixes in a couple of Newt classes to get the Android code to run well, and I had to create a couple of new class in the Newt space. At some point I’ll present these idea to you as a PR.

I also had to package the .so file in a very particular way to get the library loader to find them on Android, I just could not get the gradle system to get them down and in the right place. I’ll discuss with you at some point.

philjord,
this looks awesome, hope i find time soon to try it out.
Thanks for your great work.

Phil, please can you replace "1.7.1" by "1.7.2" in your very first post so that the developers use the latest version?