org.hd.d.pg2k.webSvr.threeD
Class ThreeDMain

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Window
              java.awt.Frame
                  javax.swing.JFrame
                      org.hd.d.pg2k.webSvr.threeD.ThreeDMain

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants

public final class ThreeDMain
extends javax.swing.JFrame

Main (UI) class of JWS-based 3D walkthrough. Runs as a Swing App.

This class/file contains as little non-UI code as is reasonably practical, so that if we change the UI details then other classes should be unaffected.

We don't really want/need this class to be Serializable, but this class inherits Serializable from JFrame.

See Also:

Serialized Form

logger

private final SimpleLoggerIF logger

Central logger instance for uploader; never null. This instance may log to the status bar and elsewhere.

logic

private final ThreeDLogic logic

Our companion "business-logic" class; never null.

status

private final javax.swing.JLabel status

Status bar; never null.

sisListener

private final ThreeDMain.SISListener sisListener

Single listener instance.

APPLICATION_WINDOW_TITLE

private static final java.lang.String APPLICATION_WINDOW_TITLE

Title shown for application.

See Also:

Constant Field Values

simpleUniverse

private volatile com.sun.j3d.utils.universe.SimpleUniverse simpleUniverse

Our simple universe; only null if Java3D not available or set-up not yet complete. Marked volatile for thread-safe lock-free access.

canvas3D

private final javax.media.j3d.Canvas3D canvas3D

3D canvas for Java3D to draw on; only null if Java3D not available.

exhibitsBranchGroup

private final javax.media.j3d.BranchGroup exhibitsBranchGroup

BranchGroup used to hold the exhibits; never null. This is set up to be writable/extendable at runtime so that we can update the exhibits scene as needed.

sliderX

private final javax.swing.JSlider sliderX

X-axis slider; never null.

sliderY

private final javax.swing.JSlider sliderY

Y-axis slider; never null.

sliderZ

private final javax.swing.JSlider sliderZ

Z-axis slider; never null.

CANVAS3D_WIDTH

private static final int CANVAS3D_WIDTH

Canvas width in pixels.

See Also:

Constant Field Values

CANVAS3D_HEIGHT

private static final int CANVAS3D_HEIGHT

Canvas height in pixels.

See Also:

Constant Field Values

ANIMATE_BANNER

private static final boolean ANIMATE_BANNER

If true, animate the name banner (at the cost of CPU time, etc).

See Also:

Constant Field Values

MAX_EXHIBIT_DIM_M

public static final float MAX_EXHIBIT_DIM_M

Maximum exhibit dimension (eg height or width) in metres; strictly positive. A value of around 1.0m, eg less than the viewer's nominal height, may be good.

See Also:

Constant Field Values

EXHIBIT_CSPACING_M

public static final float EXHIBIT_CSPACING_M

Exhibit (centres) spacing in metres; strictly positive and no smaller than MAX_EXHIBIT_DIM_M. A value of around twice MAX_EXHIBIT_DIM_M, may be good.

See Also:

Constant Field Values

EXHIBIT_VISIBLE_M

public static final float EXHIBIT_VISIBLE_M

Exhibit visibility spacing in metres; strictly positive and no smaller than MAX_EXHIBIT_DIM_M. When out of this radius we can save CPU and memory by reverting to a fall-back view.

We ensure that the nearest exhibit to the user is visible in their initial view.

FOG_START

private static final float FOG_START

Distance at which fog starts to have an effect, in open range ]0, EXHIBIT_VISIBLE_M[.

TEXT_COLOUR

private static final javax.vecmath.Color3f TEXT_COLOUR

Colour of text for captions, etc, logically immutable; never null.

TEXT_ALT_COLOUR

private static final javax.vecmath.Color3f TEXT_ALT_COLOUR

Alternate/highlight/not-good colour of text/othe3r for captions, etc, logically immutable; never null.

TEXT_ALT2_COLOUR

private static final javax.vecmath.Color3f TEXT_ALT2_COLOUR

Alternate/highlight/not-good colour of text/othe3r for captions, etc, logically immutable; never null.

TEXT_ALT3_COLOUR

private static final javax.vecmath.Color3f TEXT_ALT3_COLOUR

Alternate/highlight/not-good colour of text/othe3r for captions, etc, logically immutable; never null.

TEXT_OK_COLOUR

private static final javax.vecmath.Color3f TEXT_OK_COLOUR

Alternate/highlight/OK colour of text/other for captions, etc, logically immutable; never null.

TEXT_APPEARANCE

private static final javax.media.j3d.Appearance TEXT_APPEARANCE

Standard text colour/appearance, logically immutable; never null.

MIN_CAPTION_CHARS

private static final int MIN_CAPTION_CHARS

Minimum number of characters that we will show in a caption for comprehensibility; non-negative.

See Also:

Constant Field Values

maxCaptionCharsSoFar

private static final java.util.concurrent.atomic.AtomicInteger maxCaptionCharsSoFar

Maximum number of chars (excluding any trailer) so far found to fit in a caption; no less than MIN_CAPTION_CHARS. Suitable for thread-safe lockless access.

TRIMMED_CAPTION_SUFFIX

private static final java.lang.String TRIMMED_CAPTION_SUFFIX

Suffix to add to any trimmed caption.

See Also:

Constant Field Values

_makeIndexLetter_geomCache

private static final javax.media.j3d.Text3D[] _makeIndexLetter_geomCache

Private geometry cache for _makeIndexLetter; never null. Big enough to hold geometry for all ASCII chars up to 'z' by index.

Accessed under a lock on this array for thread-safety.

_createTexGen_cache

private static final javax.media.j3d.TexCoordGeneration[] _createTexGen_cache

Cache for _createTexGen; never null. Caches values for up to the standard thumbnail dimensions, created on first use.

This is likely to remain largely empty since we are only likely to use the slots corresponding to textures that are powers of two.

USE_2D_LAYOUT

private static final boolean USE_2D_LAYOUT

If true then lay out exhibits in 2D grid, else use 3D layout.

See Also:

Constant Field Values

MAX_VPC_X

private static final float MAX_VPC_X

Maximum (most positive) permitted view-platform-centre X value to avoid losing sight of exhibits.

See Also:

Constant Field Values

MAX_VPC_Y

private static final float MAX_VPC_Y

Maximum (most positive) permitted view-platform-centre Y value to avoid losing sight of exhibits.

See Also:

Constant Field Values

MAX_VPC_Z

private static final float MAX_VPC_Z

Maximum (most positive) permitted view-platform-centre Z value to avoid losing sight of exhibits.

currentSet

private volatile LightweightMetaDataFetchInterface.GalleryBasicMetaData currentSet

What exhibit set are we currently displaying; never null. When this changes we reconstruct our scene graph.

Marked volatile for thread-safe lock-free access.

Initially an empty set of exhibits.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

ThreeDMain

private ThreeDMain()

Create an instance of the Uploader app main window. Designed to be called by main().

shutdown

private void shutdown()
               throws java.lang.UnsupportedOperationException

Perform any activity required to shut down cleanly, eg save state, then exit. This should try to avoid taking a long time.

This may throw an UnsupportedOperationException to try to veto an exit that the user changes their mind about, eg because we have work in progress!

Throws:

java.lang.UnsupportedOperationException - if the user vetoes the shut-down

create3DPane

private javax.swing.JPanel create3DPane()

Create the (main) 3D component, called during construction; never null.

createMainBannerSceneGraph

private static javax.media.j3d.BranchGroup createMainBannerSceneGraph(javax.vecmath.Point3f bottomRight)

Creates the PG2K banner branch graph; never null. This sits just above (0,0,0), is 3D text, is about human height, and may have some animation effects...

Derived from the "HelloUniverse" example!

We add some other misc bits of the scene here, such as fog.

makeExhibitSpace

private javax.media.j3d.Node makeExhibitSpace(javax.vecmath.Point3f centre,
                                              int index)

Create one exhibit's "space" and "sphere of influence"; never null. This centres the exhibit on the point given, and surrounds it with concentric bounds:

1. An inner bound at which the exhibit can be seen/heard/etc in hi-fi.
2. A bound at which the exhibit can be seen, maybe at lo-fi, and may have the hi-fi version (pre-)fetched as needed.
3. An outer bound at which the exhibit is pre-fetched at lo-fi and possibly seen.

When outside the lo-red bounds the exhibit may be invisible and indeed only the scheduling bounds may exist to conserve memory.

Parameters:

centre - the centre of the exhibit and exhibit's space; never null

index - the index in the server's ordered list of exhibits; non-negative

_makeCaptionTexture

private static com.sun.j3d.utils.geometry.Text2D _makeCaptionTexture(java.lang.String captionFullText)

Makes the caption for an exhibit as a texture; never null. Tries to reuse textures, etc, to save time and space.

Parameters:

captionFullText - printable-ASCII string; never null

_makeRawCaptionText2D

private static com.sun.j3d.utils.geometry.Text2D _makeRawCaptionText2D(java.lang.String sb)

Make raw caption Text2D from the given text; never null.

_makeIndexLetter

private static javax.media.j3d.Shape3D _makeIndexLetter(char indexLetter)

Makes an index letter bottom-right aligned to (0,0,0); never null. We try to cache the geometry of the text to save time and memory.

Parameters:

indexLetter - printable ASCII character (up to 'z')

computeViewPlatformVWorldXYZ

private static javax.vecmath.Vector3d computeViewPlatformVWorldXYZ(com.sun.j3d.utils.universe.SimpleUniverse su)

Compute the view-platform location (x,y,z) in virtual-world coordinates; never null.

_createTexGen

private static javax.media.j3d.TexCoordGeneration _createTexGen(int textureWidth)

Build a tex-gen that maps a texture of the given width across our exhibit box front face; never null. This assumes that the caller will never modify the result, and thus instances can be safely cached and reused.

Parameters:

textureWidth - positive power of two

computeGridXYDim

private static int computeGridXYDim(int exhibitCount)

Compute width/height (X/Y dimension) of exhibit grid given exhibit count.

computeGridZDim

private static int computeGridZDim(int exhibitCount)

Compute depth (Z dimension) of exhibit grid given exhibit count.

computeMinVPCX

private float computeMinVPCX()

Compute minimum (most negative) permitted view-platform-centre X value to avoid losing sight of exhibits.

computeMinVPCY

private float computeMinVPCY()

Compute minimum (most negative) permitted view-platform-centre Y value to avoid losing sight of exhibits.

computeMinVPCZ

private float computeMinVPCZ()

Compute minimum (most negative) permitted view-platform-centre Z value to avoid losing sight of exhibits.

makeExhibitsScene

private javax.media.j3d.BranchGroup makeExhibitsScene(LightweightMetaDataFetchInterface.GalleryBasicMetaData galleryBasicMetaData,
                                                      javax.vecmath.Point3f topRightFront)

Make the BranchGroup containing the current set of exhibits; never null. This should replace any previous exhibit BranchGroup.

Parameters:

galleryBasicMetaData - new exhibit set meta-data

topRightFront - origin/offset of this exhibit set; never null

Returns:

non-null compiled BranchGroup containing the exhibits, with BranchGroup.ALLOW_DETACH capability set

initUserControls

private void initUserControls(com.sun.j3d.utils.universe.SimpleUniverse u,
                              javax.media.j3d.BranchGroup exhibitsBranchGroup)

Initialise user's location, etc.

createStatusBar

private static javax.swing.JLabel createStatusBar()

Creates and initialises a status bar.

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent evt)

This method acts as the Action handler delegate for all the actions.

pollUI

private void pollUI()

Poll UI (in AWT/Swing thread, ie Swing-safe). This routine notices when the exhibit set changes and rebuilds the exhibit part of the scene graph to suit.

main

public static void main(java.lang.String[] args)

Main method invoked from JWS.