com.softsynth.jsyn
Class SynthContext

java.lang.Object
  extended by com.softsynth.jsyn.SynthContext

public class SynthContext
extends java.lang.Object

This class provides a context for the synthesis to occur. By using separate contexts, multiple JSyn programs can run at different sample rates, including non-real-time. This is particularly important when writing Applets for a browser because their execution may overlap.

The methods are similar to the Synth class methods. But the Synth class creates a shared SynthContext for compatability with older apps. You should delete the contextID when you are through using it to recover the allocated memory.

Version:
JSyn Version 142
Author:
(C) 1997,2001 Phil Burk, SoftSynth.com, All Rights Reserved
See Also:
Synth, SynthObject

Constructor Summary
SynthContext()
           
 
Method Summary
 void checkEngineErrors()
          Used by sleep routines to keep FIFOs clear.
 int debug()
           
 int debug(int command, int data)
           
 void delete()
           
 void deleteAll()
          Delete all tracked units, SynthSamples, SynthEnvelopes and other Synth objects created since initialize() was called.
 void enableDeletionByGarbageCollector(boolean ifEnabled)
          Enable deletion of the native portion of SynthObjects (eg.
 void enableTracking(boolean ifTrack)
          Request that all SynthObjects created by the currently executing thread be automatically tracked when created, or not.
 int getFrameCount()
          Returns index of last calculated frame.
 double getFrameRate()
          Rate that frames are generated, typically 44100.0.
 int getFramesPerTick()
           
 double getInputLatency()
           
 int getObjectCount()
           
 double getOutputLatency()
           
 SharedSleeper getSleeper()
          Return SharedSleeper that is used to coordinate non-real-time synthesis.
 int getTickCount()
          Get current time in ticks.
 double getTickRate()
           
 int getTrace()
           
 double getUsage()
          Returns the fraction of critical resources used by synthesis context.
 void initialize()
          Initialize Library.
static boolean isApplet()
           
 boolean isTrackingEnabled()
           
 int setSuggestedInputLatency(double latency)
           
 int setSuggestedOutputLatency(double latency)
           
 void setTrace(int mask)
          Set trace flags for debugging.
 void sleepForTicks(int ticks)
          Sleep for the specified number of ticks.
 void sleepUntilTick(int wakeUpTick)
          Sleep until the specified tick is reached.
 void start(int flags)
           
 void start(int flags, double frameRate)
          Start the synthesis context.
 void start(int flags, double frameRate, int inputDeviceID, int numInputChannels, int outputDeviceID, int numOutputChannels)
          Starts execution of process that performs synthesis.
 void startEngine(int flags)
          Starts execution of process using default frameRate.
 void startEngine(int flags, double frameRate)
          Calls initialize() and start( flags, frameRate ).
 void stop()
          Stops execution of process that performs synthesis.
 void stopEngine()
          Stops execution of process that performs synthesis.
 void terminate()
          Terminate library.
 void track(SynthObject sob)
          Keep a reference to this object in a vector in the SynthObject class.
 void unTrack(SynthObject sob)
          Remove from tracking vector if tracked.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SynthContext

public SynthContext()
Method Detail

delete

public void delete()

debug

public int debug()

debug

public int debug(int command,
                 int data)

getUsage

public double getUsage()
Returns the fraction of critical resources used by synthesis context. A value of 0.5 would be 50%.

Returns:
fraction of resources used.

getObjectCount

public int getObjectCount()
Returns:
Number of units, samples, tables and other objects allocated.

getFrameCount

public int getFrameCount()
Returns index of last calculated frame. The frame index will tend to jump upwards because frames are calculated in large blocks by a high priority process.

Returns:
Index of last calculated frame.

getTickCount

public int getTickCount()
Get current time in ticks. This is the basic clock use for scheduling in JSyn.

Returns:
Count of synthesis ticks.

getFramesPerTick

public int getFramesPerTick()
Returns:
Number of audio frames per clock tick.

getFrameRate

public double getFrameRate()
Rate that frames are generated, typically 44100.0.

Returns:
Number of audio frames per second.

getTickRate

public double getTickRate()
Returns:
Number of clock ticks per second.

sleepUntilTick

public void sleepUntilTick(int wakeUpTick)
                    throws SynthException
Sleep until the specified tick is reached.

Throws:
SynthException - If timer not running.

checkEngineErrors

public void checkEngineErrors()
                       throws SynthException
Used by sleep routines to keep FIFOs clear.

Throws:
SynthException

sleepForTicks

public void sleepForTicks(int ticks)
                   throws SynthException
Sleep for the specified number of ticks.

Throws:
SynthException - If timer not running.

startEngine

public void startEngine(int flags,
                        double frameRate)
                 throws SynthException
Calls initialize() and start( flags, frameRate ).

Parameters:
frameRate - Calculation rate in Hertz, typically 44100.0.
Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

start

public void start(int flags,
                  double frameRate,
                  int inputDeviceID,
                  int numInputChannels,
                  int outputDeviceID,
                  int numOutputChannels)
           throws SynthException
Starts execution of process that performs synthesis. This must be called before performing any synthesis. Because the device IDs are passed explicitly, the flags Synth.FLAG_ENABLE_INPUT and Synth.FLAG_DISABLE_OUTPUT are ignored.

Parameters:
flags - used to select options. Legal flags are Synth.FLAG_NON_REAL_TIME, Synth.FLAG_ENABLE_INPUT, Synth.FLAG_DISABLE_OUTPUT.
frameRate - Calculation rate in Hertz, typically 44100.0.
inputDeviceID - PortAudio hardware audio device ID for input, Synth.NO_DEVICE for no input.
numInputChannels - Number of input channels to use. Typically 0 or 2.
outputDeviceID - PortAudio hardware audio device ID for output, Synth.NO_DEVICE for no output.
numOutputChannels - Number of output channels to use. Typically 0 or 2.
Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

start

public void start(int flags,
                  double frameRate)
           throws SynthException
Start the synthesis context. If the flag Synth.FLAG_ENABLE_INPUT is set then Synth.getDefaultInputDeviceID() will be used. If the flag Synth.FLAG_DISABLE_OUTPUT is clear then Synth.getDefaultOutputDeviceID() will be used.

Throws:
SynthException

start

public void start(int flags)
           throws SynthException
Throws:
SynthException

getSleeper

public SharedSleeper getSleeper()
Return SharedSleeper that is used to coordinate non-real-time synthesis.


initialize

public void initialize()
                throws SynthException
Initialize Library. This must be called before any other synthesis functions. Resets AudioInputPermission.

Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

startEngine

public void startEngine(int flags)
                 throws SynthException
Starts execution of process using default frameRate.

Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

stopEngine

public void stopEngine()
                throws SynthException
Stops execution of process that performs synthesis. Calls stop() and terminate().

Throws:
SynthException - If engine cannot be stopped.

stop

public void stop()
          throws SynthException
Stops execution of process that performs synthesis.

Throws:
SynthException - If engine cannot be stopped.

terminate

public void terminate()
               throws SynthException
Terminate library.

Throws:
SynthException - If engine cannot be stopped.

isTrackingEnabled

public boolean isTrackingEnabled()

enableTracking

public void enableTracking(boolean ifTrack)
Request that all SynthObjects created by the currently executing thread be automatically tracked when created, or not. Calls can be nested.

See Also:
track

track

public void track(SynthObject sob)
Keep a reference to this object in a vector in the SynthObject class. This will prevent the garbage collector from accidentally deleting a JSyn object that is active but not referenced by any other Java objects. It also allows the object to be deleted automatically by stopEngine() or by calling deleteAll().


unTrack

public void unTrack(SynthObject sob)
Remove from tracking vector if tracked.


deleteAll

public void deleteAll()
               throws SynthException
Delete all tracked units, SynthSamples, SynthEnvelopes and other Synth objects created since initialize() was called. This will be called automatically by terminate().

Throws:
SynthException

enableDeletionByGarbageCollector

public void enableDeletionByGarbageCollector(boolean ifEnabled)
Enable deletion of the native portion of SynthObjects (eg. units and samples) when the Java portion is deleted by the Garbage Collector.
Warning: enabling this can cause unexpected removal of objects that may be making sound but are no longer referenced by Java. The sudden silence can be embarassing.
Warning: disabling this can cause native resources to accumulate unless you explicitly delete them using their delete() method. This can consume memory and cause memory allocation to fail.
The safest thing to do is to disable this and delete() your own objects when you are through using them.

Parameters:
ifEnabled - set true to enable deletion, false to disable, default is true
See Also:
getObjectCount

setTrace

public void setTrace(int mask)
Set trace flags for debugging.


getTrace

public int getTrace()

isApplet

public static boolean isApplet()

setSuggestedInputLatency

public int setSuggestedInputLatency(double latency)

setSuggestedOutputLatency

public int setSuggestedOutputLatency(double latency)

getOutputLatency

public double getOutputLatency()

getInputLatency

public double getInputLatency()