path: root/src/javax/media/j3d/Screen3D.java

/*
 * Copyright 1997-2008 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 *
 */

package javax.media.j3d;

import java.awt.Dimension;
import java.awt.GraphicsConfiguration;
import java.awt.GraphicsDevice;
import java.awt.Rectangle;
import java.util.ArrayList;
import java.util.Hashtable;

/**
 * The Screen3D Object contains all information about a particular screen.
 * All Canvas3D objects on the same physical screen (display device)
 * refer to the same Screen3D object.  Note that Screen3D has no public
 * constructors--it is obtained from the Canvas3D via the getScreen3D
 * method.
 * <p>
 * Default values for Screen3D parameters are as follows:
 * <ul>
 * physical screen width : 0.0254/90.0 * screen width (in pixels)<br>
 * physical screen height : 0.0254/90.0 * screen height (in pixels)<br>
 * tracker base to image plate transform : identity<br>
 * head tracker to left image plate transform : identity<br>
 * head tracker to right image plate transform : identity<br>
 * off-screen size : (0,0)<br>
 * </ul>
 * <P>
 * <b>Offscreen Rendering</b><P>
 * New for Java 3D 1.2, an off-screen rendering mode allows rendering
 * to a memory image, which is possibly larger than the screen. The
 * setSize and getSize methods are defined specifically for this
 * mode. Note that the off-screen size, physical width, and physical height
 * must be set prior to rendering
 * to the associated off-screen canvas. Failure to do so will result
 * in an exception.<P>
 * <b>Calibration Parameters</b><P>
 * The Screen3D object must be calibrated with the coexistence volume.
 * The Screen3D class provides several methods for defining the
 * calibration parameters.<P>
 * <UL>Measured Parameters<P>
 * The screen's (image plate's) physical width and height (in meters)
 * is set once, typically by a browser, calibration program, system
 * administrator, or system calibrator, not by an applet. These values
 * must be determined by measuring the display's active image width
 * and height. In the case of a head-mounted display, this should be
 * the display's apparent width and height at the focal plane. These
 * values are defined by the setPhysicalScreenWidth and
 * setPhysicalScreenHeight methods.<P>
 *
 * Head-tracker Coordinate System<P>
 * If head tracking is enabled, one of two parameters need to be specified:<P>
 * <UL><LI>If the view policy is SCREEN_VIEW, the tracker-base-to-image-plate
 * coordinate system must be specified (setTrackerBaseToImagePlate method).
 * This coordinate system must be recalibrated whenever the image
 * plate moves relative to the tracker.</LI><P>
 *
 * <LI>If the view policy is HMD_VIEW, the head-tracker-to-left-image-plate
 * and head-tracker-to-right-image-plate coordinate systems must be
 * specified (setHeadTrackerToLeftImagePlate and
 * setHeadTrackerToRightImagePlate methods).</LI><P></UL>
 * </UL><P>
 *
 * <p>
 * <b>Additional Information</b>
 * <p>
 * For more information, see the
 * <a href="doc-files/intro.html">Introduction to the Java 3D API</a> and
 * <a href="doc-files/ViewModel.html">View Model</a>
 * documents.
 *
 * @see Canvas3D
 * @see Canvas3D#getScreen3D
 */

public class Screen3D extends Object {
    private static final boolean debug = false;

    // Assume a default of 90 DPI: 90 pix/inch = 1/90 inch/pix =
    // 0.0254/90 meter/pix
    private static final double METERS_PER_PIXEL = 0.0254/90.0;

    // GraphicsDevice associated with this Screen3D object.  Note that
    // all on-screen Canvas3D objects that are created on the same
    // GraphicsDevice will share the same Screen3D.
    GraphicsDevice graphicsDevice;

    // Flag indicating whether this Screen3D is associated with
    // an off-screen Canvas3D or with one or more on-screen Canvas3Ds
    boolean offScreen;

    // Screen number
    int screen;

    // The width and height of the screen in meters.
    double physicalScreenWidth;
    double physicalScreenHeight;

    // Screen size in pixels
    Dimension screenSize = new Dimension(0, 0);

    //
    // Tracker-base coordinate system to image-plate coordinate
    // system transform.  This transform
    // is typically a calibration constant.
    // This is used only in SCREEN_VIEW mode.
    //
    Transform3D trackerBaseToImagePlate = new Transform3D();

    //
    // Head-tracker coordinate system to left and right image-plate
    // coordinate system transforms.  These transforms are typically
    // calibration constants.  These are used only in HMD_VIEW mode.
    //
    Transform3D headTrackerToLeftImagePlate = new Transform3D();
    Transform3D headTrackerToRightImagePlate = new Transform3D();


    //  Physical screen size related field has changed.
    static final int PHYSICAL_SCREEN_SIZE_DIRTY          = 0x01;
    // Screen size field has changed.
    static final int SCREEN_SIZE_DIRTY_DIRTY             = 0x02;
    // Tracker base to image plate field has changed.
    static final int TRACKER_BASE_TO_IMAGE_PLATE_DIRTY   = 0x04;
    // Head tracker to  image plate field has changed.
    static final int HEAD_TRACKER_TO_IMAGE_PLATE_DIRTY   = 0x08;

    // Mask that indicates this Screen3D view dependence info. has changed,
    // and CanvasViewCache may need to recompute the final view matries.
    int scrDirtyMask = (PHYSICAL_SCREEN_SIZE_DIRTY | SCREEN_SIZE_DIRTY_DIRTY
			| TRACKER_BASE_TO_IMAGE_PLATE_DIRTY
			| HEAD_TRACKER_TO_IMAGE_PLATE_DIRTY);

    //
    // View cache for this screen
    //
    ScreenViewCache screenViewCache = null;

    // The renderer for this screen
    Renderer renderer = null;

// Hashtable that maps a GraphicsDevice to its associated renderer
static Hashtable<GraphicsDevice, Renderer> deviceRendererMap = new Hashtable<GraphicsDevice, Renderer>();

    // A count of the number of canvases associated with this screen
    int canvasCount = 0;

	// A list of Canvas3D Objects that refer to this
	private final ArrayList<Canvas3D> users = new ArrayList<Canvas3D>();

// Add a user to the list of users
synchronized void removeUser(Canvas3D c) {
	users.remove(c);
}

// Add a user to the list of users
synchronized void addUser(Canvas3D c) {
	if (!users.contains(c))
		users.add(c);
}

// Add a user to the list of users
synchronized void notifyUsers() {
	for (int i = 0; i < users.size(); i++) {
		users.get(i).redraw();
	}
}

    /**
     * Retrieves the width and height (in pixels) of this Screen3D.
     *
     * @return a new Dimension object containing the width and height
     * of this Screen3D.
     */
    public Dimension getSize() {
	return new Dimension(screenSize);
    }

    /**
     * Retrieves the width and height (in pixels) of this Screen3D
     * and copies it into the specified Dimension object.
     *
     * @param rv Dimension object into which the size of
     * this Screen3D is copied.
     * If <code>rv</code> is null, a new Dimension object is allocated.
     *
     * @return <code>rv</code>
     *
     * @since Java 3D 1.2
     */
    public Dimension getSize(Dimension rv) {
	if (rv == null) {
	    return new Dimension(screenSize);
	}
	else {
	    rv.setSize(screenSize);
	    return rv;
	}
    }

    /**
     * Sets the width and height (in pixels) of this off-screen Screen3D.
     * The default size for off-screen Screen3D objects is (0,0).
     * <br>
     * NOTE: the size must be
     * set prior to rendering to the associated off-screen canvas.
     * Failure to do so will result in an exception.
     *
     * @param width the new width of this Screen3D object
     * @param height the new height of this Screen3D object
     *
     * @exception IllegalStateException if this Screen3D is not in
     * off-screen mode.
     *
     * @since Java 3D 1.2
     */
    public void setSize(int width, int height) {

	if (!offScreen)
            throw new IllegalStateException(J3dI18N.getString("Screen3D1"));

	synchronized(this) {
	    screenSize.width = width;
	    screenSize.height = height;
	    scrDirtyMask |= SCREEN_SIZE_DIRTY_DIRTY;
	}
    }

    /**
     * Sets the width and height (in pixels) of this off-screen Screen3D.
     * The default size for off-screen Screen3D objects is (0,0).
     * <br>
     * NOTE: the size must be
     * set prior to rendering to the associated off-screen canvas.
     * Failure to do so will result in an exception.
     *
     * @param d the new dimension of this Screen3D object
     *
     * @exception IllegalStateException if this Screen3D is not in
     * off-screen mode.
     *
     * @since Java 3D 1.2
     */
    public void setSize(Dimension d) {
	if (!offScreen)
            throw new IllegalStateException(J3dI18N.getString("Screen3D1"));

	synchronized(this) {
	    screenSize.width = d.width;
	    screenSize.height = d.height;
	    scrDirtyMask |= SCREEN_SIZE_DIRTY_DIRTY;
	}
    }

    /**
     * Sets the screen physical width in meters.  In the case of a
     * head-mounted display, this should be the apparent width
     * at the focal plane.
     * @param width the screen's physical width in meters
     */
    public void setPhysicalScreenWidth(double width) {
	synchronized(this) {
	    physicalScreenWidth = width;
	    scrDirtyMask |= PHYSICAL_SCREEN_SIZE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Retrieves the screen's physical width in meters.
     * @return the screen's physical width in meters
     */
    public double getPhysicalScreenWidth() {
	return physicalScreenWidth;
    }

    /**
     * Sets the screen physical height in meters.  In the case of a
     * head-mounted display, this should be the apparent height
     * at the focal plane.
     * @param height the screen's physical height in meters
     */
    public void setPhysicalScreenHeight(double height) {
	synchronized(this) {
	    physicalScreenHeight = height;
	    scrDirtyMask |= PHYSICAL_SCREEN_SIZE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Retrieves the the screen's physical height in meters.
     * @return the screen's physical height in meters
     */
    public double getPhysicalScreenHeight() {
	return physicalScreenHeight;
    }

    @Override
    public String toString() {
	return "Screen3D: size = " +
	    "(" + getSize().width + " x " + getSize().height + ")" +
	    ", physical size = " +
	    "(" + getPhysicalScreenWidth() + "m x " +
	    getPhysicalScreenHeight() + "m)";
    }

    // Static initializer for Screen3D class
    static {
 	VirtualUniverse.loadLibraries();
    }

    /**
     * Construct a new Screen3D object with the specified size in pixels.
     * Note that currently, there is no AWT equivalent of screen so Java 3D
     * users need to get this through the Canvas3D object (via getScreen()) if
     * they need it.
     * @param graphicsConfiguration the AWT graphics configuration associated
     * with this Screen3D
     * @param offScreen a flag that indicates whether this Screen3D is
     * associated with an off-screen Canvas3D
     */
    Screen3D(GraphicsConfiguration graphicsConfiguration, boolean offScreen) {
	this.offScreen = offScreen;
	this.graphicsDevice = graphicsConfiguration.getDevice();

	screenViewCache = new ScreenViewCache(this);

	// Get the display handle and the screen number from the Pipeline
	screen = Pipeline.getPipeline().getScreen(graphicsDevice);

	if (debug)
	    System.err.println("Screen3D: screen " + screen + " hashcode " +
			       this.hashCode());

	if (!offScreen) {
	    // Store the information in this screen object
	    Rectangle bounds = graphicsConfiguration.getBounds();
	    screenSize.width = bounds.width;
	    screenSize.height = bounds.height;
	}

	// Set the default physical size based on size in pixels
	physicalScreenWidth = screenSize.width * METERS_PER_PIXEL;
	physicalScreenHeight = screenSize.height * METERS_PER_PIXEL;
    }


    /**
     * Sets the tracker-base coordinate system to image-plate coordinate
     * system transform.  This transform
     * is typically a calibration constant.
     * This is used only in SCREEN_VIEW mode.
     * @param t the new transform
     * @exception BadTransformException if the transform is not rigid
     */
    public void setTrackerBaseToImagePlate(Transform3D t) {
	synchronized(this) {
	    if (!t.isRigid()) {
		throw new BadTransformException(J3dI18N.getString("Screen3D0"));
	    }
	    trackerBaseToImagePlate.setWithLock(t);
	    scrDirtyMask |= Screen3D.TRACKER_BASE_TO_IMAGE_PLATE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Retrieves the tracker-base coordinate system to image-plate
     * coordinate system transform and copies it into the specified
     * Transform3D object.
     * @param t the object that will receive the transform
     */
    public void getTrackerBaseToImagePlate(Transform3D t) {
	t.set(trackerBaseToImagePlate);
    }

    /**
     * Sets the head-tracker coordinate system to left image-plate coordinate
     * system transform.  This transform
     * is typically a calibration constant.
     * This is used only in HMD_VIEW mode.
     * @param t the new transform
     * @exception BadTransformException if the transform is not rigid
     */
    public void setHeadTrackerToLeftImagePlate(Transform3D t) {
	synchronized(this) {
	    if (!t.isRigid()) {
		throw new BadTransformException(J3dI18N.getString("Screen3D0"));
	    }
	    headTrackerToLeftImagePlate.setWithLock(t);
	    scrDirtyMask |= Screen3D.HEAD_TRACKER_TO_IMAGE_PLATE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Retrieves the head-tracker coordinate system to left image-plate
     * coordinate system transform and copies it into the specified
     * Transform3D object.
     * @param t the object that will receive the transform
     */
    public void getHeadTrackerToLeftImagePlate(Transform3D t) {
	t.set(headTrackerToLeftImagePlate);
    }

    /**
     * Sets the head-tracker coordinate system to right image-plate coordinate
     * system transform.  This transform
     * is typically a calibration constant.
     * This is used only in HMD_VIEW mode.
     * @param t the new transform
     * @exception BadTransformException if the transform is not rigid
     */
    public void setHeadTrackerToRightImagePlate(Transform3D t) {
	synchronized(this) {
	    if (!t.isRigid()) {
		throw new BadTransformException(J3dI18N.getString("Screen3D0"));
	    }
	    headTrackerToRightImagePlate.setWithLock(t);
	    scrDirtyMask |= Screen3D.HEAD_TRACKER_TO_IMAGE_PLATE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Retrieves the head-tracker coordinate system to right image-plate
     * coordinate system transform and copies it into the specified
     * Transform3D object.
     * @param t the object that will receive the transform
     */
    public void getHeadTrackerToRightImagePlate(Transform3D t) {
	t.set(headTrackerToRightImagePlate);
    }

    /**
     * Update the view cache associated with this screen.
     */
    void updateViewCache() {
	synchronized(this) {
	    screenViewCache.snapshot();
	}
    }
}