javax.microedition.amms.control.audio3d
Interface CommitControl

All Superinterfaces:

javax.microedition.media.Control

public interface CommitControl
extends javax.microedition.media.Control

CommitControl provides a mechanism to enable many audio parameters to be updated simultaneously. In many ways, it can be considered to be the analog of a 'Draw' or 'Flush' method of a graphics system. The commit control, if it is supported, can only be obtained from the GlobalManager.

The commit control has two operating modes: immediate mode (the default) and deferred mode:

• In the immediate mode, the CommitControl is effectively disabled, so all audio parameters are passed directly to the audio processing system as soon as they are set.
• In the deferred mode, the CommitControl buffers all the audio parameters until the commit method is called.

Why do we need commit?

Audio processing occurs autonomously in the background under hardware control, so the application is not aware that it is happening. Therefore the application is not synchronized to the audio processing frame rate, which means the application has no control over when these frames occur. The commit control overcomes the classic inter-thread communication problem by ensuring that all the parameters for a given state of the application are valid.

The secondary reason for using a commit control is to improve the performance. If a game with 6 audio sources and one listener is being updated at 20 frames per second, and at each frame the 6 sources and the listener are all moving and changing their orientation and velocity, we require:

    (6 + 1) * 3 * 20 = 420

API calls each second. In the immediate mode, each of these API calls will require a parameter block to be transmitted to the audio processing unit (which is often a separate CPU or DSP). Each of these transactions takes a small (but not insignificant) amount of time.

When the CommitControl is used in the deferred mode, the Java methods buffer the parameters (which is simple and fast) until the application calls commit. Now all the pending parameters are transmitted in one larger block to the audio processing system. This gives the opportunity for a significant improvement in performance.

Details

The commit control affects the audio parameters for the following controls:

• LocationControl
• DopplerControl
• OrientationControl
• DirectivityControl
• DistanceAttenuationControl
• MacroscopicControl
• ObstructionControl

(The first three controls are the ones that are most likely to be updated rapidly, once per frame of an interactive application or game.)

The CommitControl affects the parameters for these controls on the Spectator and all the SoundSource3D objects.

Example

This example illustrates the Java methods involved in using the CommitControl. (In reality, a typical game would obviously cache the controls for efficiency.)

In the example, we assume that an array of a fictitious class GameObject, namely gameObjects[], contains locations and velocities of some objects in the game and that there exists a method updateGame to move all these GameObjects. In the example, we also assume for instance, that the Players that are connected to SoundSource3Ds have been started and that the DopplerControls have been enabled.

     // Get the CommitControl
     CommitControl commitC = (CommitControl)GlobalManager.getControl("javax.microedition.amms.control.audio3d.CommitControl");

     // Set the 3d audio system to deferred mode
     commitC.setDeferred(true);

     // Get the Spectator and its Controls:
     Spectator spectator = GlobalManager.getSpectator();
     LocationControl locSpec =
         (LocationControl)spectator.getControl("javax.microedition.amms.control.audio3d.LocationControl");
     OrientationControl oriSpec =
         (OrientationControl)spectator.getControl("javax.microedition.amms.control.audio3d.OrientationControl");
     DopplerControl dopSpec =
         (DopplerControl)spectator.getControl("javax.microedition.amms.control.audio3d.DopplerControl");

     // The main game loop
     while(true) {

         // Update positions of game objects
         updateGame();

         // Update the 3d audio system
         for (i = 0; i < gameObjects.length; i++) {

             // Get the ith game object and its SoundSource3D
             GameObject obj = gameObjects[i];
             SoundSource3D ss3d = obj.getSoundSource3D();
             LocationControl lc = (LocationControl)ss3d.getControl("javax.microedition.amms.control.audio3d.LocationControl");
             DopplerControl dc = (DopplerControl)ss3d.getControl("javax.microedition.amms.control.audio3d.DopplerControl");

             // Set the position of the sound source
             lc.setCartesian(obj.x, obj.y, obj.z);

             // Set the velocity of the sound source
             dc.setVelocityCartesian(obj.vx, obj.vy, obj.vz);
         }

         // Set the location, orientation and velocity of the spectator
         locSpec.setCartesian(user.x, user.y, user.z);
         oriSpec.setOrientation(user.heading, user.pitch, user.roll);
         dopSpec.setVelocityCartesian(user.vx, user.vy, user.vz);


         // Commit the changes to the 3d audio system
         commitC.commit();

         // Render graphics
         // .....
     }

See Also:

LocationControl, DopplerControl, OrientationControl

Method Summary

void	commit() Transfers all the pending parameters to the audio processing system.
boolean	isDeferred() Returns the mode of the CommitControl.
void	setDeferred(boolean deferred) Sets the mode of the CommitControl.

Method Detail

setDeferred

void setDeferred(boolean deferred)

Sets the mode of the CommitControl.

When switching back from the deferred mode to the immediate mode (setDeferred(false)) all the pending parameters from the buffer are transmitted to the audio processing system automatically.

Parameters:

deferred - a boolean indicating if the property setting should be deferred

isDeferred

boolean isDeferred()

Returns the mode of the CommitControl.

Returns:

true if setting of properties is deferred

commit

void commit()

Transfers all the pending parameters to the audio processing system.

In the immediate mode, a call to this method is ignored.