javax.media.j3d.InputDevice Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of java3d-core Show documentation
Java3D Core And Java3D Util Libraries
The newest version!
/*
 * 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;



/**
 * InputDevice is the interface through which Java 3D and Java 3D
 * application programs communicate with a device driver.  All input
 * devices that Java 3D uses must implement the InputDevice interface and
 * be registered with Java 3D via a call to
 * PhysicalEnvironment.addInputDevice(InputDevice).  An input device
 * transfers information to the Java 3D implementation and Java 3D
 * applications by writing transform information to sensors that the
 * device driver has created and manages.  The driver can update its
 * sensor information each time the pollAndProcessInput method is
 * called.
 */

public interface InputDevice {

    /**
     * Signifies that the driver for a device is a blocking driver and that
     * it should be scheduled for regular reads by Java 3D.  A blocking driver
     * is defined as a driver that can cause the thread accessing the driver
     * (the Java 3D implementation thread calling the pollAndProcessInput
     * method) to block while the data is being accessed from the driver.
     */
    public static final int BLOCKING = 3;


   /**
    * Signifies that the driver for a device is a non-blocking driver and
    * that it should be scheduled for regular reads by Java 3D.  A
    * non-blocking driver is defined as a driver that does not cause the
    * calling thread to block while data is being retrieved from the
    * driver.  If no data is available from the device, pollAndProcessInput
    * should return without updating the sensor read value.
    */
    public static final int NON_BLOCKING = 4;

   /**
    * Signifies that the Java 3D implementation should not schedule
    * regular reads on the sensors of this device; the Java 3D
    * implementation will only call pollAndProcessInput when one of the
    * device's sensors' getRead methods is called.  A DEMAND_DRIVEN driver
    * must always provide the current value of the sensor on demand whenever
    * pollAndProcessInput is called.  This means that DEMAND_DRIVEN drivers
    * are non-blocking by definition.
    */
    public static final int DEMAND_DRIVEN = 5;


    /**
     * This method initializes the device.  A device should be initialized
     * before it is registered with Java 3D via the
     * PhysicalEnvironment.addInputDevice(InputDevice) method call.
     * @return return true for succesful initialization, false for failure
     */
    public abstract boolean initialize();

    /**
     * This method sets the device's current position and orientation as the
     * devices nominal position and orientation (establish its reference
     * frame relative to the "Tracker base" reference frame).
     */
    public abstract void setNominalPositionAndOrientation();


    /**
     * This method causes the device's sensor readings to be updated by the
     * device driver.  For BLOCKING and NON_BLOCKING drivers, this method is
     * called regularly and the Java 3D implementation can cache the sensor
     * values.  For DEMAND_DRIVEN drivers this method is called each time one
     * of the Sensor.getRead methods is called, and is not otherwise called.
     */
    public abstract void pollAndProcessInput();

    /**
     * This method will not be called by the Java 3D implementation and
     * should be implemented as an empty method.
     */
    public abstract void processStreamInput();

    /**
     * Code to process the clean up of the device and relinquish associated
     * resources.  This method should be called after the device has been
     * unregistered from Java 3D via the
     * PhysicalEnvironment.removeInputDevice(InputDevice) method call.
     */
    public abstract void close();

    /**
     * This method retrieves the device's processing mode: one of BLOCKING,
     * NON_BLOCKING, or DEMAND_DRIVEN.  The Java 3D implementation calls
     * this method when PhysicalEnvironment.addInputDevice(InputDevice) is
     * called to register the device with Java 3D.  If this method returns
     * any value other than BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN,
     * addInputDevice will throw an IllegalArgumentException.
     * @return Returns the devices processing mode, one of BLOCKING,
     * NON_BLOCKING, or DEMAND_DRIVEN
     */
    public abstract int getProcessingMode();


    /**
     * This method sets the device's processing mode to one of: BLOCKING,
     * NON_BLOCKING, or DEMAND_DRIVEN.  Many drivers will be written to run
     * in only one mode.  Applications using such drivers should not attempt
     * to set the processing mode.  This method should throw an
     * IllegalArgumentException if there is an attempt to set the processing
     * mode to anything other than the aforementioned three values.
     *
     * 
     * NOTE: this method should not be called after the input
     * device has been added to a PhysicalEnvironment.  The
     * processingMode must remain constant while a device is attached
     * to a PhysicalEnvironment.
     *
     * @param mode One of BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN
     */
    public abstract void setProcessingMode(int mode);


    /**
     * This method gets the number of sensors associated with the device.
     * @return the device's sensor count.
     */
    public int getSensorCount();

    /**
     * Gets the specified Sensor associated with the device.  Each InputDevice
     * implementation is responsible for creating and managing its own set of
     * sensors.  The sensor indices begin at zero and end at number of
     * sensors minus one.  Each sensor should have had
     * Sensor.setDevice(InputDevice) set properly before addInputDevice
     * is called.
     * @param sensorIndex the sensor to retrieve
     * @return Returns the specified sensor.
     */
    public Sensor getSensor(int sensorIndex);

}