
Simple3D – a simple way to play with Java 3D
http://fivedots.coe.psu.ac.th/~ad/Simple3D/

Andrew Davison, Nov. 2021
ad@fivedots.coe.psu.ac.th
Last Updated: Dec 17, 2021


What's here:

Four folders:
  images/        // textures and other pics go here
  lib/           // the JAR files for Simple3D, Java 3D, and JOGL are here
  models/        // OBJ models
  shaders/       // various vertex and fragment shaders

6 example programs for Part 2:
  Earth.java
  ViewEarthSG.java
  ShowText3D.java
  SunEarth.java
  LoadModel.java
  TeapotDimples.java

6 example programs for Part 3:
  StartShapes.java
  RGraph.java
  RTrans.java
  Rocket.java
  JointedArm.java and UseArm.java

6 example programs for Part 4:
  Dice.java
  UseTetra.java
  Platonics.java
  LoadModel.java
  PosHome.java
  SaveEarth.java

8 example programs for Part 5:
  PenguinWalks.java
  ChangeVisibility.java
  MovingModels.java
  MovingModels2.java
  GasGiant.java
  MorphCube.java         <<========== 3 WARNINGS issued at compile time; IGNORE
  PulseCube.java and GeometryUpdaterBeh.java

7 example programs for Part 7:
  PickCubes.java
  PickActs.java
  PickMoveCubes.java and PickMoverListener.java
  PickMoverBeh.java  
  HitSpheres.java and CollisionBeh.java


Two batch files for compiling/executing 
the programs on MS Windows:
  compile.bat
  run.bat

Two Bash shell scripts for compiling/executing 
the programs on Ubuntu:
  compile.sh
  run.sh
These will need to be made executable:
> chmod u+x compile.sh
> chmod u+x run.sh

For listing built-in color names:
  colors.bat

---------------------------
The lib/ Folder

Simple3D.jar
------------
It contains the source and compiled code for:
  Simple3D.java
and
  ColorFactory.java
  FireAlpha.java
  KeysBehavior.java
  MyMouseRotate.java
  MyMouseTranslate.java
  MyOrbitBehavior.java
  OBJWriter.java
  PickBehavior.java
  PickUpdater.java
  RotPosPath.java
  TGViewer.java
  TimeBehavior.java
  TimeUpdater.java

JARs for Java 3D:
  j3dcore.jar
  j3dtree.jar
  j3dutils.jar
  vecmath.jar

JOGL:
  jogamp-fat.jar

---------------------------
Compilation and Execution Examples


On MS Windows:
> compile *.java
or
> compile Earth.java
> run Earth

On Ubuntu:
> ./compile.sh Earth.java
> ./run.sh Earth


> compile ShowText3D.java
> run ShowText3D <a text string>
e.g.
> run ShowText3D "Hello World!"


> compile LoadModel.java
> run LoadModel <the relative path to an OBJ model>
e.g.
> run LoadModel models/house/home.obj


------------------------------
Using Simple3D

All Simple3D examples understand a wide range of mouse-based
and key-based navigation commands. They are summarized in a pop-down
image accessible via the Simple3D "Show Help" item on the
"Camera" menu. That picture is also included here, as navHelp.png
in the images/ folder.

Programming with Simple3D is introduced in Part 2 of 
"Simple3D – a simple way to play with Java 3D" at 
http://fivedots.coe.psu.ac.th/~ad/Simple3D/


BTW, the Simple3D.jar file in the libs/ folder contains both compiled code and 
Java source files, so you can look at how things are implemented if 
you're so inclined.

-----------------
Ubuntu

Some of my test machines are running Ubuntu 20.04 (Focal) with 
OpenJDK 11 installed as the Java compiler and run-time.
Mainly for that reason I use Java's "--release" option to 
produce class files for Java 11. This seems like a reasonable
compromise, but platforms using older OpenJDKs will have to be 
updated. For example:

sudo apt install openjdk-14-jdk

You can use:
> java -version
and
> javac -version

to check the installed version. It needs to be v11 or later.

----------------
Ubuntu X11Util.Display Warning

When Simple3D terminates on Ubuntu, a X11Util.Display message is printed:

X11Util.Display: Shutdown (JVM shutdown: true, open (no close attempt): 1/1, 
reusable (open, marked uncloseable): 2, pending (open in creation order): 3)
X11Util: Open X11 Display Connections: 1
X11Util: Open[0]: NamedX11Display[localhost:10.0, 0x7f4210004f00, 
refCount 1, unCloseable true]

I've tried various hacks to remove it, but to no avail. It doesn't 
affect the execution otherwise, so can be ignored.
It seems related to JOGAMP bug 705: 
https://jogamp.org/bugzilla/show_bug.cgi?id=705


-----------------------
Ubuntu and Windows 10's WSL

I'm using the X11 server that's part of MobaXterm 
(https://mobaxterm.mobatek.net/) to run Simple3D
in Ubuntu on MS Windows 10 WSL 2. 

I've encountered occassional non-fatal errors related to Shader linking. 
The problem comes and goes, and can occur even when the program 
isn't calling Java 3D's shader API. 

MobaXterm should be configured to use hardware OpenGL acceleration, 
and the user's ./bashrc must include the line:

export DISPLAY=:0.0


