javax.microedition.amms.control.audio3d
Interface CommitControl

All Superinterfaces:

Control

public interface CommitControl
extends 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:

LocationControlDopplerControlOrientationControlDirectivityControlDistanceAttenuationControlMacroscopicControlObstructionControl

(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

Since:

BlackBerry API 5.0.0

Method Summary
void	commit() Transfers all the pending parameters to the audio processing system.
boolean	isDeferred()
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

Since:

BlackBerry API 5.0.0

isDeferred

boolean isDeferred()

Returns:

CommitControl.

true if setting of properties is deferred

Since:

BlackBerry API 5.0.0

commit

void commit()

Transfers all the pending parameters to the audio processing system.

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

Since:

BlackBerry API 5.0.0