net.sf.jack4j
Class JackTransportClient

java.lang.Object
  net.sf.jack4j.JackClient
      net.sf.jack4j.JackTransportClient

Direct Known Subclasses:

AbstractJackTransportClient

public abstract class JackTransportClient
extends JackClient

JackClient with additional transport-related methods.

Author:

repa

Constructor Summary

JackTransportClient(java.lang.String clientName, boolean useExactName, boolean canStartServer, java.lang.String serverName)

Method Summary

int	getCurrentTransportFrame() Return an estimate of the current transport frame, including any time elapsed since the last transport positional update.
void	locateTransport(int frame) Reposition the transport to a new frame number.
JackTransportState	queryTransport(TransportPosition position) Queries current state and position of Jack transport.
void	releaseTimebase() Releases this client from timebase master responsibility.
void	repositionTransport(TransportPosition position) Request a new transport position.
void	setDefaultSyncCallback() Declares this client as a slow-sync client, using default callback.
boolean	setDefaultTimebaseCallback(boolean conditional) Registers this client as timebase master for the Jack, using default callback.
void	setSyncCallback(long pointer, long arg) Declares this client as a slow-sync client, using default callback.
void	setSyncTimeout(long microseconds) Set the timeout value for slow-sync clients.
boolean	setTimebaseCallback(boolean conditional, long pointer, long arg) Registers this client as timebase master for the Jack.
void	startTransport() Starts the Jack transport.
void	stopTransport() Stops the Jack transport.
abstract boolean	syncCallback(JackTransportState state, TransportPosition position) Synchronization callback for slow-sync clients.
abstract void	timebaseCallback(JackTransportState state, int nframes, TransportPosition pos, boolean newPos) Callback that provides extended position information to Jack transport.
void	unsetSyncCallback() Declares that the client is not slow-sync anymore, and unregisters native sync callback.

Methods inherited from class net.sf.jack4j.JackClient

activate, addAudioPort, addMidiPort, addPort, bufferSizeCallback, clientRegistrationCallback, close, connect, cpuLoad, deactivate, disconnect, finalize, framesSinceCycleStart, framesToTime, frameTime, freewheelCallback, getAllPortConnections, getBufferSize, getCallbackStruct, getClientHandle, getClientName, getClientThread, getPorts, getPorts, getSampleRate, getStatistics, getTotalPortLatency, graphOrderCallback, internalClientByName, isActive, isMine, isOpen, isProcessMethodSynchronized, isRealtime, isShutdown, lastFrameTime, loadInternalClient, localPort, localPortNames, portById, portByName, portConnectCallback, portRegistrationCallback, process, recomputeTotalLatencies, recomputeTotalPortLatency, removePort, requestPortMonitorByName, sampleRateCallback, setAllDefaultCallbacks, setBufferSize, setBufferSizeCallback, setClientRegistrationCallback, setDefaultBufferSizeCallback, setDefaultClientRegistrationCallback, setDefaultFreewheelCallback, setDefaultGraphOrderCallback, setDefaultPortConnectCallback, setDefaultPortRegistrationCallback, setDefaultProcessCallback, setDefaultSampleRateCallback, setDefaultShutdownCallback, setDefaultThreadInitCallback, setDefaultXRunCallback, setFreewheel, setFreewheelCallback, setGraphOrderCallback, setPortConnectCallback, setPortRegistrationCallback, setProcessCallback, setProcessMethodSynchronized, setSampleRateCallback, setShutdownCallback, setThreadInitCallback, setXRunCallback, threadInitCallback, threadWait, time, timeToFrames, xRunCallback

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JackTransportClient

public JackTransportClient(java.lang.String clientName,
                           boolean useExactName,
                           boolean canStartServer,
                           java.lang.String serverName)
                    throws JackException

Throws:

JackException

Method Detail

startTransport

public void startTransport()

Starts the Jack transport.

stopTransport

public void stopTransport()

Stops the Jack transport.

queryTransport

public JackTransportState queryTransport(TransportPosition position)

Queries current state and position of Jack transport.

If the position parameter is not null, the given structure will be updated with the current positional information.

getCurrentTransportFrame

public int getCurrentTransportFrame()

Return an estimate of the current transport frame, including any time elapsed since the last transport positional update.

locateTransport

public void locateTransport(int frame)
                     throws JackException

Reposition the transport to a new frame number.

May be May be called at any time by any client. The new position takes effect in two process cycles. If there are slow-sync clients and the transport is already rolling, it will enter the JackTransportState.STARTING state and begin invoking their synchronization callbacks until ready. This function is realtime-safe.

Throws:

JackException

repositionTransport

public void repositionTransport(TransportPosition position)
                         throws JackException

Request a new transport position.

May be May be called at any time by any client. The new position takes effect in two process cycles. If there are slow-sync clients and the transport is already rolling, it will enter the JackTransportState.STARTING state and begin invoking their synchronization callbacks until ready. This function is realtime-safe.

Throws:

JackException

setSyncTimeout

public void setSyncTimeout(long microseconds)
                    throws JackException

Set the timeout value for slow-sync clients.

Throws:

JackException

setDefaultSyncCallback

public void setDefaultSyncCallback()
                            throws JackException

Declares this client as a slow-sync client, using default callback.

Setting up a sync callback declares this client as a slow-sync client, one that cannot respond immediately to transport position changes.

After the default callback is set, the method syncCallback(JackTransportState, TransportPosition) will be invoked accordingly to Jack synchronization rules (see the description of syncCallback method).

Throws:

JackException

setSyncCallback

public void setSyncCallback(long pointer,
                            long arg)
                     throws JackException

Declares this client as a slow-sync client, using default callback.

Setting up a sync callback declares this client as a slow-sync client, one that cannot respond immediately to transport position changes.

The pointer must be a native JackSyncCallback pointer, represented as long.

Parameters:

pointer - the pointer to native function

arg - the value passed as void* arg parameter to the callback

Throws:

JackException

See Also:

setDefaultSyncCallback()

unsetSyncCallback

public void unsetSyncCallback()
                       throws JackException

Declares that the client is not slow-sync anymore, and unregisters native sync callback.

After this method is called, the syncCallback(JackTransportState, TransportPosition) method won't be called anymore.

Throws:

JackException

setTimebaseCallback

public boolean setTimebaseCallback(boolean conditional,
                                   long pointer,
                                   long arg)
                            throws JackException

Registers this client as timebase master for the Jack.

The timebase master registers a callback that updates extended position information such as beats or timecode whenever necessary. Without this extended information, there is no need for this function.

There is never more than one master at a time. When a new client takes over, the former timebase callback is no longer called. Taking over the timebase may be done conditionally, so it fails if there was a master already.

Parameters:

conditional - if true, the request is made conditionally, ie. if there already is a timebase master, the method does nothing

pointer - the pointer to native function

arg - the value passed as void* arg parameter to the callback

Returns:

true if the call was successful; false if conditional request was made and there's already timebase master.

Throws:

JackException

See Also:

setDefaultTimebaseCallback(boolean)

setDefaultTimebaseCallback

public boolean setDefaultTimebaseCallback(boolean conditional)
                                   throws JackException

Registers this client as timebase master for the Jack, using default callback.

The timebase master registers a callback that updates extended position information such as beats or timecode whenever necessary. Without this extended information, there is no need for this function.

There is never more than one master at a time. When a new client takes over, the former timebase callback is no longer called. Taking over the timebase may be done conditionally, so it fails if there was a master already.

The default timebase callback invokes the method timebaseCallback(JackTransportState, int, TransportPosition, boolean) of this client.

Parameters:

conditional - if true, the request is made conditionally, ie. if there already is a timebase master, the method does nothing

Returns:

true if the call was successful; false if conditional request was made and there's already timebase master.

Throws:

JackException

releaseTimebase

public void releaseTimebase()
                     throws JackException

Releases this client from timebase master responsibility.

After this call, this Jack client is not timebase master anymore. The transport state keeps rolling if it was started, but no extended positional information will be available. The timebaseCallback(JackTransportState, int, TransportPosition, boolean) will not be invoked anymore.

Throws:

JackException

See Also:

setDefaultTimebaseCallback(boolean)

syncCallback

public abstract boolean syncCallback(JackTransportState state,
                                     TransportPosition position)

Synchronization callback for slow-sync clients.

The method is never invoked until the setDefaultSyncCallback() is called.

After the default slow-sync callback is set up, this method will be called during the next process cycle (if the client is active), or after the call to JackClient.activate() (if the client was previously inactive).

Then, the method is called again whenever the transport starts, and whenever some client requests new transport position.

The method must return boolean value that indicates whether the client is ready to roll.

The position structure is only valid during the call. If you need the positional information outside the callback, you can create a clone with TransportPosition.clone().

Parameters:

state - current transport state

position - new transport position

Returns:

true if the client is ready, false otherwise.

timebaseCallback

public abstract void timebaseCallback(JackTransportState state,
                                      int nframes,
                                      TransportPosition pos,
                                      boolean newPos)

Callback that provides extended position information to Jack transport.

This method is never invoked unless the setDefaultTimebaseCallback(boolean) was successfully called.

This method is called immediately after proces callback in the same thread whenever the transport is rolling, or when any client has requested a new position in the previous cycle. The first cycle after the (default) native timebase callback was registered is also treated as a new position, or the first cycle after JackClient.activate() if the client had been inactive.

The method is responsible for setting extended position information into pos structure. The actual transport position can not be set using frame field of that structure; use locateTransport(int) instead. The position structure is only valid during the call. If you need the positional information outside the callback, you can create a clone with TransportPosition.clone().

Parameters:

state - current transport state

nframes - period length

pos - position structure for the next cycle; if newPos is false, the structure already contains extended positional information from current cycle

newPos - if true, new position was requested; in such case, pos structure doesn't contain valid extended information