audioengine3d.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: AudioEngine3D.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistribution of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 *
 * Neither the name of Sun Microsystems, Inc. or the names of
 * contributors may be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * You acknowledge that this software is not designed, licensed or
 * intended for use in the design, construction, operation or
 * maintenance of any nuclear facility.
 *
 * $Revision: 1.5 $
 * $Date: 2007/02/09 17:20:02 $
 * $State: Exp $
 */

package com.sun.j3d.audioengines;

import javax.media.j3d.*;
import javax.vecmath.*;
import java.util.ArrayList;


/**
 * The AudioEngine3D Class defines an audio output device that generates
 * sound 'image' from high-level sound parameters passed to it during 
 * scene graph.
 *
 * <P>
 * The methods in this class are meant to be optionally overridden by an 
 * extended class.  This extended class would provice device specific code.
 *
 * <P>
 * Error checking on all parameters passed to these methods is already
 * explicitly being done by the Java 3D core code that calls these methods.
 *
 * <p>
 * NOTE: AudioEngine developers should not subclass this class directly.
 * Subclass AudioEngine3DL2 instead.
 */

public abstract class AudioEngine3D extends AudioEngine implements AudioDevice3D
{
    /*
     *  Identifiers of sample associated with sound source
     *  This array grows as the AudioDevice3D implementation requires it larger.
     */  
    protected ArrayList samples = new ArrayList(64);

    /**
     *  Current View sound is being rendered
     */  
    protected View  currentView = (View)null;

    /*
     * current Aural attribute Parameters
     */
    protected AuralParameters attribs = new AuralParameters();

    /**
     * Construct a new AudioEngine with the specified PhysicalEnvironment.
     * @param physicalEnvironment the physical environment object where we
     * want access to this device.
     */  
    public AudioEngine3D(PhysicalEnvironment physicalEnvironment ) {
        super(physicalEnvironment);
    }

    /*
     *
     * Methods that affect AudioEngine3D fields that are NOT associated 
     * with a specific sound sample
     *
     */

    /**
     * Save a reference to the current View object.
     * @param reference to current view object
     */
    public void  setView(View reference) {
        currentView = reference;
        return;
    }
    /**
     * Get reference to the current View object.
     * @return reference to current view object
     */
    public View getView() {
        return (currentView);
    }

    /*
     *
     *  Methods explicitly affect sound rendering and that require
     *  audio device specific methods that override this class.
     *
     */

    /**
     * Prepare Sound in device.
     * Makes sound assessible to device - in this case attempts to load sound
     * Stores sound type and data.
     * @param soundType denotes type of sound: Background, Point or Cone
     * @param soundData descrition of sound source data
     * @return index into sample vector of Sample object for sound
     */  
    public int   prepareSound(int soundType, MediaContainer soundData) {
        // This method must be overridden by device specific implementation
        return Sample.NULL_SAMPLE;
    }

    /**
     * Clear Sound.
     * Removes/clears associated sound data with this sound source node
     * @param index device specific reference number to device driver sample
     */  
    public abstract void clearSound(int index);

    /**
     * Set the transform for local to virtual world coordinate space
     * @param index device specific reference number to device driver sample
     * @param trans is a reference to virtual world composite transform
     */
    public void  setVworldXfrm(int index, Transform3D trans) {
         Sample sample = (Sample)getSample(index);
         if (sample != null)
             sample.vworldXfrm.set(trans);
         return;
    }
    /**
     * Start sample playing on audio device
     * @param index device specific reference number to device driver sample
     * @return status: < 0 denotes an error
     */
    public abstract int startSample(int index);

    /**
     * Stop sample playing on audio device
     * @param index device specific reference number to device driver sample
     * @return status: < 0 denotes an error
     */
    public abstract int stopSample(int index);

    /**
     * Update sample. 
     * Implies that some parameters affecting rendering have been modified.
     * @param index device specific reference number to device driver sample
     */
    // TODO: The update method exists on a TEMPORARY basis.
    public abstract void updateSample(int index);

    /**
     * Mute sample. 
     * @param index device specific reference number to device driver sample
     */
    public abstract void muteSample(int index);

    /**
     * Unmute sample. 
     * @param index device specific reference number to device driver sample
     */
    public abstract void unmuteSample(int index);

    /**
     * Pause sample. 
     * @param index device specific reference number to device driver sample
     */
    public abstract void pauseSample(int index);

    /**
     * Unpause sample. 
     * @param index device specific reference number to device driver sample
     */
    public abstract void unpauseSample(int index);
    
    /*
     *
     *  Methods that affect fields associated with the sound sample
     *  and that may cause implicit rendering.
     *
     */
    /**
     * Set gain scale factor applied to sample. 
     * @param index device specific reference number to device driver sample
     * @param scaleFactor floating point multiplier applied to sample amplitude
     */
    public void  setSampleGain(int index, float scaleFactor) {
        Sample sample = (Sample)getSample(index);
        if (sample != null) 
            sample.setGain(scaleFactor);
        return;
    }

    /** 
     * Set number of times sample is looped.
     * @param index device specific reference number to device driver sample
     * @param count number of times sample is repeated
     */
    public void   setLoop(int index, int count) {
        Sample sample = (Sample)getSample(index);
        if (sample != null) 
            sample.setLoopCount(count);
        return;
    }

    /**
     * Set location of sample.
     * @param index device specific reference number to device driver sample
     * @param position point location in virtual world coordinate of sample