path: root/src/javax/media/j3d/PhysicalEnvironment.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.util.ArrayList;
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Vector;

/**
 * This object contains a specification of the physical environment in
 * which the view will be generated.  It is used to set up input
 * devices (sensors) for head-tracking and other uses, and the audio
 * output device.  Sensors are indexed starting at zero.
 *
 * @see View
 */

public class PhysicalEnvironment extends Object {
    /**
     * The Sensor Index associated with the Head
     */
    int HeadIndex = 0;

    // The Sensor index associated with the Right Hand
    int RightHandIndex = 1;

    // The Sensor index associated with the Left Hand
    int LeftHandIndex = 2;

    // The current Dominant Hand Sensor Index
    int DominantHandIndex = 1;

    // The current Non Dominant Hand Sensor Index
    int NonDominantHandIndex = 2;

    //
    // Coexistence coordinate system to tracker-base coordinate
    // system transform.  If head tracking is enabled, this transform
    // is a calibration constant.  If head tracking is not enabled,
    // this transform is not used.
    // This is used in both SCREEN_VIEW and HMD_VIEW modes.
    //
    Transform3D coexistenceToTrackerBase = new Transform3D();

    //
    // Indicates whether the underlying hardware implementation
    // supports tracking.
    //
    boolean trackingAvailable = false;

    // The view associated with this physical environment
    //    View view;

    //
    // This variable specifies the policy Java 3D will use in placing
    // the user's eye position relative to the user's head position
    // (NOMINAL_SCREEN, NOMINAL_HEAD, or NOMINAL_FEET).
    // It is used in the calibration process.
    //
    // TODO: this needs better explanation in the spec
    int coexistenceCenterInPworldPolicy = View.NOMINAL_SCREEN;

    // Mask that indicates this PhysicalEnv's view dependence info. has changed,
    // and CanvasViewCache may need to recompute the final view matries.
    int peDirtyMask = (View.PE_COE_TO_TRACKER_BASE_DIRTY
		       | View.PE_TRACKING_AVAILABLE_DIRTY
		       | View.PE_COE_CENTER_IN_PWORLD_POLICY_DIRTY);


////    /**
////     * The offset in the user's dominant-hand-tracker coordinates
////     * to that hand's hot spot. This value is a calibration constant.
////     */
////    Vector3d dominantHandTrackerHotspotOffset;
////
////    /**
////     * The offset in the user's non-dominant-hand-tracker coordinates
////     * to that hand's hot spot. This value is a calibration constant.
////     */
////    Vector3d nondominantHandTrackerHotspotOffset;

    //
    // The number of sensor stored within the PhysicalEnvironment
    //
    int sensorCount;

    //
    // Array of sensors
    //
    Sensor[] sensors;

    // Audio device associated with this PhysicalEnvironment
    AudioDevice audioDevice = null;

    boolean sensorListChanged = false;

    Sensor[] sensorList = null;

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

    // Scheduler for input devices
    InputDeviceScheduler inputsched;

// store all inputDevices
Vector<InputDevice> devices = new Vector<InputDevice>(1);

    // Number of active view users
    int activeViewRef = 0;

// Hashtable that maps a PhysicalEnvironment to its InputDeviceScheduler
static final Hashtable<PhysicalEnvironment, InputDeviceScheduler> physicalEnvMap;

static {
	physicalEnvMap = new Hashtable<PhysicalEnvironment, InputDeviceScheduler>();
}
    /**
     * Constructs a PhysicalEnvironment object with default parameters.
     * The default values are as follows:
     * <ul>
     * sensor count : 3<br>
     * sensors : null (for all array elements)<br>
     * head index : 0<br>
     * right hand index : 1<br>
     * left hand index : 2<br>
     * dominant hand index : 1<br>
     * nondominant hand index : 2<br>
     * tracking available : false<br>
     * audio device : null<br>
     * input device list : empty<br>
     * coexistence to tracker base transform : identity<br>
     * coexistence center in pworld policy : View.NOMINAL_SCREEN<br>
     * </ul>
     */
    public PhysicalEnvironment() {
	this(3);
    }

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

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

// Add a user to the list of users
synchronized void notifyUsers() {
	for (int i = users.size() - 1; i >= 0; i--) {
		users.get(i).repaint();
	}
}

    /**
     * Constructs and initializes a PhysicalEnvironment object with
     * the specified number of sensors.
     * @param sensorCount the number of sensors to create.
     */
    public PhysicalEnvironment(int sensorCount) {
	this.sensorCount = sensorCount;
	sensors = new Sensor[sensorCount];
	for(int i=sensorCount-1; i>=0; i--) {
	    sensors[i] = null;
	}
    }



    /**
     * Returns copy of Sensor references.  Returns null for zero
     * sensors, so user of method must check for null.  Also, any of
     * these sensors could be null.
     */
    Sensor[] getSensorList() {
        synchronized(sensors) {
           if(sensorListChanged) {  // note: this is a rare case
               sensorList = new Sensor[sensors.length];
               for(int i=0 ; i<sensors.length ; i++) {
                    sensorList[i] = sensors[i];
               }
               sensorListChanged = false;

           }
           return sensorList;
        }
    }


    /**
     * Sets the specified AudioDevice object as the device through
     * which audio rendering for this PhysicalEnvironment will be
     * performed.
     * @param device audio device object to be associated with this
     * PhysicalEnvironment
     */
    public void setAudioDevice(AudioDevice device) {
        audioDevice = device;
    }

    /**
     * Gets the audioDevice for this PhysicalEnvironment.
     * @return audio device object associated with this PhysicalEnvironment
     */
    public AudioDevice getAudioDevice(){
        return audioDevice;
    }

/**
 * Create an enumerator that produces all input devices.
 * @return an enumerator of all available devices
 */
public Enumeration<InputDevice> getAllInputDevices() {
	return devices.elements();
}

/**
 * Add an input device to the list of input devices.  User is
 * responsible for initializing the device and setting the
 * processing mode (streaming or polling).
 * @param device  the device to be added to the list of input devices
 * @exception IllegalArgumentException if InputDevice.getProcessingMode()
 * does not return one of BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN.
 */
public void addInputDevice(InputDevice device) {

	int driver_type = device.getProcessingMode();

	if ((driver_type == InputDevice.BLOCKING) ||
	    (driver_type == InputDevice.NON_BLOCKING) ||
	    (driver_type == InputDevice.DEMAND_DRIVEN)) {
		synchronized (devices) {
			devices.add(device);
			if (inputsched != null) {
				inputsched.addInputDevice(device);
			}
		}
	} else {
		throw new IllegalArgumentException(J3dI18N.getString("PhysicalEnvironment0"));
	}
}

/**
 * Remove an input device from the list of input devices.
 * User is responsible for closing out the device and releasing
 * the device resources.
 * @param device  the device to be removed
 */
public void removeInputDevice(InputDevice device) {
	synchronized (devices) {
		devices.remove(device);
		if (inputsched != null) {
			inputsched.removeInputDevice(device);
		}
	}
}

    /**
     * Sets the index of the head to the specified sensor index.
     * @param index the new sensor index of the head
     */
    public void setHeadIndex(int index) {
	HeadIndex = index;
	synchronized(this) {
	    computeTrackingAvailable();
	    peDirtyMask |= View.PE_TRACKING_AVAILABLE_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Gets the sensor index of the head.
     * @return the sensor index of the head
     */
    public int getHeadIndex() {
	return HeadIndex;
    }

    /**
     * Sets the index of the right hand to the specified sensor index.
     * @param index the new sensor index of the right hand
     */
    public void setRightHandIndex(int index) {
	RightHandIndex = index;
	notifyUsers();
    }

    /**
     * Gets the sensor index of the right hand.
     * @return the sensor index of the right hand
     */
    public int getRightHandIndex() {
	return RightHandIndex;
    }

    /**
     * Sets the index of the left hand to the specified sensor index.
     * @param index the new sensor index of the left hand
     */
    public void setLeftHandIndex(int index) {
	LeftHandIndex = index;
	notifyUsers();
    }

    /**
     * Gets the sensor index of the left hand.
     * @return the sensor index of the left hand
     */
    public int getLeftHandIndex() {
	return LeftHandIndex;
    }

    /**
     * Sets the index of the dominant hand to the specified sensor index.
     * @param index the new sensor index of the dominant hand
     */
    public void setDominantHandIndex(int index) {
	DominantHandIndex = index;
	notifyUsers();
    }

    /**
     * Gets the sensor index of the dominant hand.
     * @return the sensor index of the dominant hand
     */
    public int getDominantHandIndex() {
	return DominantHandIndex;
    }

    /**
     * Sets the index of the non-dominant hand to the specified sensor index.
     * @param index the new sensor index of the non dominant hand
     */
    public void setNonDominantHandIndex(int index) {
	NonDominantHandIndex = index;
	notifyUsers();
    }

    /**
     * Gets the sensor index of the non-dominant hand.
     * @return the sensor index of the non dominant hand
     */
    public int getNonDominantHandIndex() {
	return NonDominantHandIndex;
    }

    /**
     * Set the sensor specified by the index to sensor provided; sensors are
     * indexed starting at 0.  All sensors must be registered via this
     * method.
     * @param index the sensor's index
     * @param sensor the new sensor
     */
    public void setSensor(int index, Sensor sensor) {
        synchronized(sensors) {
	  sensors[index] = sensor;
          sensorListChanged = true;
        }
	synchronized(this) {
	    computeTrackingAvailable();
	    peDirtyMask |= View.PE_TRACKING_AVAILABLE_DIRTY;
	}

	notifyUsers();
    }

    /**
     * Gets the sensor specified by the index; sensors are indexed starting
     * at 0.
     * @param index the sensor's index
     */
    public Sensor getSensor(int index){
           // not synchronized, since the only way to write to sensors is
           // via a public API call, and user shouldn't call Sensor with
           // two threads
	   return sensors[index];
    }

    /**
     * Sets the coexistence coordinate system to tracker-base coordinate
     * system transform.  If head tracking is enabled, this transform
     * is a calibration constant.  If head tracking is not enabled,
     * this transform is not used.
     * This is used in both SCREEN_VIEW and HMD_VIEW modes.
     * @param t the new transform
     * @exception BadTransformException if the transform is not rigid
     */
    public void setCoexistenceToTrackerBase(Transform3D t) {
	if (!t.isRigid()) {
	    throw new BadTransformException(J3dI18N.getString("PhysicalEnvironment1"));
	}
	synchronized(this) {
	    coexistenceToTrackerBase.setWithLock(t);
	    peDirtyMask |= View.PE_COE_TO_TRACKER_BASE_DIRTY;
	}

	notifyUsers();
    }

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

    /**
     * Returns a status flag indicating whether or not tracking
     * is available.
     * @return a flag telling whether tracking is available
     */
    public boolean getTrackingAvailable() {
      return this.trackingAvailable;
    }

    /**
     * Sets the coexistence center in physical world policy.
     * This setting determines how Java 3D places the
     * user's eye point as a function of head position during the
     * calibration process, one of View.NOMINAL_SCREEN,
     * View.NOMINAL_HEAD, or View.NOMINAL_FEET.
     * The default policy is View.NOMINAL_SCREEN.
     * @param policy the new policy
     */
    public void setCoexistenceCenterInPworldPolicy(int policy) {
	switch (policy) {
	case View.NOMINAL_SCREEN:
	case View.NOMINAL_HEAD:
	case View.NOMINAL_FEET:
	    break;

	default:
	    throw new IllegalArgumentException(J3dI18N.getString("PhysicalEnvironment2"));
	}

	synchronized(this) {
	    this.coexistenceCenterInPworldPolicy = policy;
	    peDirtyMask |= View.PE_COE_CENTER_IN_PWORLD_POLICY_DIRTY;
	}
	notifyUsers();
    }

    /**
     * Returns the current coexistence center in physical world policy.
     * @return one of: View.NOMINAL_SCREEN, View.NOMINAL_HEAD, or
     * View.NOMINAL_FEET
     */
    public int getCoexistenceCenterInPworldPolicy() {
	return this.coexistenceCenterInPworldPolicy;
    }

    /**
     * Get the current sensor count.
     * @return the number of sensor objects per PhysicalEnvironment object
     */
    public int getSensorCount() {
	return sensorCount;
    }

    /**
     * Set the number of sensor objects per PhysicalEnvironmnet. This is a
     * calibration parameter that should be set before setting any sensors
     * in the PhysicalEnvironment object.  This call associates 'count'
     * Sensors with this object, and they are indexed from 0 to count-1.
     * @param count the new sensor  count
     */
    public void setSensorCount(int count) {

        Sensor[] tmp = new Sensor[count];
        int i=0;

        synchronized(sensors) {
	    int min =  Math.min(count, sensorCount);
            while(i < min) {
                tmp[i] = sensors[i++];
            }
            while(i < count) {
                tmp[i++] = null;
            }
            sensorCount = count;
            sensorListChanged = true;
            sensors = tmp;
        }
	notifyUsers();
    }

    // (re-)compute the tracking available flag
    private void computeTrackingAvailable() {
        synchronized(sensors) {
	   trackingAvailable = ((HeadIndex < sensors.length) &&
			     (sensors[HeadIndex] != null));
        }
    }

}