pmlib
Class PMLSequencer

java.lang.Object
  extended by pmlib.PMLSequencer

public class PMLSequencer
extends java.lang.Object

PMLSequencer Class

The PMLSequencer object facilitates the recording and playback of PMLEvent objects. Sequences may be loaded from, or saved to text files and the class includes static sequence load, reverse, offset and combine functions.

This library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.


Constructor Summary
PMLSequencer()
          Create a new object instance
PMLSequencer(java.lang.String t)
          Create a new object instance with the specified tag
 
Method Summary
static boolean combineSequences(java.lang.String s0, java.lang.String s1)
          Combine the specified sequences and store the result in the first
static boolean combineSequences(java.lang.String s0, java.lang.String s1, java.lang.String s2)
          Combine the specified sequences and store the result in the specified output file
 PMLEvent createEvent(PMLFloat f)
          Return a new PMLEvent object for the current frame derived from the specified PMLFloat object
 PMLEvent createEvent(java.lang.String s)
          Return a new PMLEvent object for the current frame with the specified variables
 PMLEvent createEvent(java.lang.String s, float v)
          Return a new PMLEvent object for the current frame with the specified variables
 PMLEvent createEvent(java.lang.String s, float[] v)
          Return a new PMLEvent object for the current frame with the specified variables
 boolean event(PMLEvent e)
          Store a sequencer event if the sequencer is recording
 boolean event(java.lang.String s)
          Store a sequencer event if the sequencer is recording
 boolean event(java.lang.String s, float v)
          Store a sequencer event if the sequencer is recording
 boolean event(java.lang.String s, float[] v)
          Store a sequencer event if the sequencer is recording
 PMLEvent[] frame()
          Iterate the sequencer by one frame
 PMLEvent[] frame(int f)
          Iterate the sequencer by the specified number of frames
 int getCurrentFrame()
          Return the current sequencer frame
 float[] getEventRange(java.lang.String s, int v)
          Return the event range for the specified event and variable index
 int getEventVars(java.lang.String s)
          Return the amount of variables attached to the first instance of the specified event.
 int getSequenceLength()
          Return the length in frames of the most recently played sequence
 boolean hasEvent(java.lang.String s)
          Return true if the loaded sequence contains the specified event
 boolean isActive()
          Return true if the sequencer is active
 boolean isPlaying()
          Return true if the sequencer is playing
 boolean isRecording()
          Return true if the sequencer is recording
static boolean offsetSequence(java.lang.String s, int v)
          Offset each event frame in the specified sequence by the denoted amount
static boolean offsetSequence(java.lang.String s0, java.lang.String s1, int v)
          Offset each event frame in the specified sequence by the denoted amount and store the result in the chosen output file
 void play()
          Toggle sequencer playback
static boolean randomOffsetSequence(java.lang.String s, int r)
          Apply a random frame offset to each event within the specified sequence
static boolean randomOffsetSequence(java.lang.String s0, java.lang.String s1, int r)
          Apply a random frame offset to each event within the specified input sequence and store the result to the specified output
 boolean read(java.io.File f)
          Load a sequence from the file specified
 boolean read(java.lang.String f)
          Load a sequence from the file specified
 boolean readBuffer()
          Load the contents of the record buffer into the playback buffer
static PMLEvent[] readSequence(java.io.File f)
          Load the specified sequence and return an array of PMLEvent objects
static PMLEvent[] readSequence(java.lang.String f)
          Load the specified sequence and return an array of PMLEvent objects
 void record()
          Toggle sequencer recording
static boolean reverseSequence(java.lang.String s)
          Reverse the specified sequence
static boolean reverseSequence(java.lang.String s0, java.lang.String s1)
          Reverse the specified sequence and store the result in the chosen file
 boolean sequenceLoaded()
          Return true if a sequence has been loaded
static boolean sequenceToHtml(java.lang.String s, java.lang.String f)
          Read the specified sequence and store the data in an HTML table
 void setEventHandler(PMLEventHandler h)
          Set the sequencer event handler
 void setInputMatrix(PMLMatrix m)
          Set the input matrix
 void setMatrixInterval(int i)
          Set the matrix sampling interval
 void setOutputMatrix(PMLMatrix m)
          Set the output matrix
 void setVerbose(boolean b)
          Set whether this sequencer is verbose
 void stop()
          Stop sequencer recording/playback
 PMLEvent[] toArray()
          Return the loaded sequence as an array of PMLEvent objects
 PMLEvent[] toArray(java.lang.String t)
          Returns all instances of the specified event tag as an array of PMLEvent objects
 boolean write(java.io.File f)
          Write the recorded sequence to the specified file
 boolean write(java.lang.String f)
          Write the recorded sequence to the specified file
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PMLSequencer

public PMLSequencer()
Create a new object instance


PMLSequencer

public PMLSequencer(java.lang.String t)
Create a new object instance with the specified tag

Method Detail

frame

public PMLEvent[] frame()
Iterate the sequencer by one frame

If the sequencer is in playback, frame events will be parsed and output to the output matrix if applicable. If the sequencer is recording and a matrix is assigned, the input matrix will be sampled.

Returns:
all parsed events as an array of PMLEvent objects

frame

public PMLEvent[] frame(int f)
Iterate the sequencer by the specified number of frames

If the sequencer is in playback, frame events will be parsed and output to the output matrix and event handler if applicable. If the sequencer is recording and a matrix is assigned, the input matrix will be sampled.

Parameters:
f - frames
Returns:
all parsed events as an array of PMLEvent objects

getCurrentFrame

public int getCurrentFrame()
Return the current sequencer frame

Returns:
the current sequencer frame;

getSequenceLength

public int getSequenceLength()
Return the length in frames of the most recently played sequence

Returns:
the length in frames of the most recently played sequence

hasEvent

public boolean hasEvent(java.lang.String s)
Return true if the loaded sequence contains the specified event

Parameters:
s - event string
Returns:
true if the loaded sequence contains the specified event

getEventVars

public int getEventVars(java.lang.String s)
Return the amount of variables attached to the first instance of the specified event.

If the sequence is empty or the specified event cannot be found, -1 will be returned.

Parameters:
s - event string
Returns:
the amount of variables attached to the specified event

getEventRange

public float[] getEventRange(java.lang.String s,
                             int v)
Return the event range for the specified event and variable index

The variable index specifies the event variable from which to derive the event range, with a value of 0 specifying the first variable and so on.

The return float array takes the format: { minimum, maximum, mean }

Parameters:
s - event string
v - variable index
Returns:
the event range for the specified event and variable index

createEvent

public PMLEvent createEvent(PMLFloat f)
Return a new PMLEvent object for the current frame derived from the specified PMLFloat object

Parameters:
f - PMLFloat object
Returns:
a new PMLEvent object for the current frame

createEvent

public PMLEvent createEvent(java.lang.String s)
Return a new PMLEvent object for the current frame with the specified variables

Parameters:
s - event tag
Returns:
a new PMLEvent object for the current frame

createEvent

public PMLEvent createEvent(java.lang.String s,
                            float v)
Return a new PMLEvent object for the current frame with the specified variables

Parameters:
s - event tag
v - variable
Returns:
a new PMLEvent object for the current frame

createEvent

public PMLEvent createEvent(java.lang.String s,
                            float[] v)
Return a new PMLEvent object for the current frame with the specified variables

Parameters:
s - event tag
v - variables
Returns:
a new PMLEvent object for the current frame

event

public boolean event(PMLEvent e)
Store a sequencer event if the sequencer is recording

Parameters:
e - sequencer event
Returns:
true if the event was stored

event

public boolean event(java.lang.String s)
Store a sequencer event if the sequencer is recording

Parameters:
s - event string
Returns:
true if the event was stored

event

public boolean event(java.lang.String s,
                     float v)
Store a sequencer event if the sequencer is recording

Parameters:
s - event string
v - variable
Returns:
true if the event was stored

event

public boolean event(java.lang.String s,
                     float[] v)
Store a sequencer event if the sequencer is recording

Parameters:
s - event string
v - variable array
Returns:
true if the event was stored

readBuffer

public boolean readBuffer()
Load the contents of the record buffer into the playback buffer

Returns:
false if the record buffer is empty

read

public boolean read(java.lang.String f)
Load a sequence from the file specified

Parameters:
f - sequence file
Returns:
true if the sequence was successfully loaded

read

public boolean read(java.io.File f)
Load a sequence from the file specified

Parameters:
f - sequence file
Returns:
true if the sequence was successfully loaded

sequenceLoaded

public boolean sequenceLoaded()
Return true if a sequence has been loaded

Returns:
true if a sequence has been loaded

play

public void play()
Toggle sequencer playback


record

public void record()
Toggle sequencer recording


stop

public void stop()
Stop sequencer recording/playback


isActive

public boolean isActive()
Return true if the sequencer is active

Returns:
true if the sequencer is active;

isPlaying

public boolean isPlaying()
Return true if the sequencer is playing

Returns:
true if the sequencer is playing

isRecording

public boolean isRecording()
Return true if the sequencer is recording

Returns:
true if the sequencer is recording

write

public boolean write(java.lang.String f)
Write the recorded sequence to the specified file

Parameters:
f - file
Returns:
true if the file was successfully written

write

public boolean write(java.io.File f)
Write the recorded sequence to the specified file

Parameters:
f - file
Returns:
true if the file was successfully written

setInputMatrix

public void setInputMatrix(PMLMatrix m)
Set the input matrix

If the sequencer is recording and the matrix is not null then it will be sampled on calling frame(). If output values within the matrix have changed then they will be stored in the current sequence.

If ramping is enabled then the ramped value will be stored, resulting in more constant value changes. As such, it is advisable to disable matrix value ramping within this context.

Parameters:
m - matrix

setMatrixInterval

public void setMatrixInterval(int i)
Set the matrix sampling interval

The matrix sampling interval specifies how regularly the input matrix should be sampled. A value of 1 would result in sampling every frame, whilst a value of 10 would result in sampling every 10 frames.

Default: 1

Parameters:
i - interval

setOutputMatrix

public void setOutputMatrix(PMLMatrix m)
Set the output matrix

If the sequencer is playing and the matrix is not null, then sequencer events will be routed to the appropriate matrix input upon calling frame().

Parameters:
m - matrix

setEventHandler

public void setEventHandler(PMLEventHandler h)
Set the sequencer event handler

If the sequencer is playing and the event handler is not null, then sequencer events will be routed to the object methods specified within the event handler upon calling frame().

Parameters:
h - event handler

setVerbose

public void setVerbose(boolean b)
Set whether this sequencer is verbose

Default: false

Parameters:
b - boolean

toArray

public PMLEvent[] toArray()
Return the loaded sequence as an array of PMLEvent objects

If there is no loaded sequence an empty array will be returned

Returns:
PMLEvent array

toArray

public PMLEvent[] toArray(java.lang.String t)
Returns all instances of the specified event tag as an array of PMLEvent objects

If there is no loaded sequence or there are no instances of the specified tag an empty array will be returned

Parameters:
t - tag
Returns:
PMLEvent array

readSequence

public static PMLEvent[] readSequence(java.lang.String f)
Load the specified sequence and return an array of PMLEvent objects

Sequence entries that cannot be parsed will be ignored and the returned array will be sorted

Parameters:
f - sequence file
Returns:
an array of PMLEvent objects

readSequence

public static PMLEvent[] readSequence(java.io.File f)
Load the specified sequence and return an array of PMLEvent objects

Sequence entries that cannot be parsed will be ignored and the returned array will be sorted. If the specified file cannot be read or is empty a null value will be returned.

Parameters:
f - sequence file
Returns:
an array of PMLEvent objects

reverseSequence

public static boolean reverseSequence(java.lang.String s)
Reverse the specified sequence

Parameters:
s - input sequence
Returns:
true if the sequence was successfully modified

reverseSequence

public static boolean reverseSequence(java.lang.String s0,
                                      java.lang.String s1)
Reverse the specified sequence and store the result in the chosen file

Parameters:
s0 - input sequence
s1 - output sequence
Returns:
true if the sequence was successfully written

offsetSequence

public static boolean offsetSequence(java.lang.String s,
                                     int v)
Offset each event frame in the specified sequence by the denoted amount

Parameters:
s - input sequence
v - frame offset
Returns:
true if the sequence was successfully modified

offsetSequence

public static boolean offsetSequence(java.lang.String s0,
                                     java.lang.String s1,
                                     int v)
Offset each event frame in the specified sequence by the denoted amount and store the result in the chosen output file

Parameters:
s0 - input sequence
s1 - output sequence
v - frame offset
Returns:
true if the sequence was successfully written

randomOffsetSequence

public static boolean randomOffsetSequence(java.lang.String s,
                                           int r)
Apply a random frame offset to each event within the specified sequence

The offset value will be within the range specified by +/- r.

Parameters:
s - input sequence
r - offset range
Returns:
true if the sequence was successfully modified

randomOffsetSequence

public static boolean randomOffsetSequence(java.lang.String s0,
                                           java.lang.String s1,
                                           int r)
Apply a random frame offset to each event within the specified input sequence and store the result to the specified output

The offset value will be within the range specified by +/- r.

Parameters:
s0 - input sequence
s1 - output sequence
r - offset range
Returns:
true if the sequence was successfully written

combineSequences

public static boolean combineSequences(java.lang.String s0,
                                       java.lang.String s1)
Combine the specified sequences and store the result in the first

Parameters:
s0 - input sequence 1
s1 - input sequence 2
Returns:
true if the sequence was successfully modified

combineSequences

public static boolean combineSequences(java.lang.String s0,
                                       java.lang.String s1,
                                       java.lang.String s2)
Combine the specified sequences and store the result in the specified output file

Parameters:
s0 - input sequence 1
s1 - input sequence 2
s2 - output sequence
Returns:
true if the sequence was successfully written

sequenceToHtml

public static boolean sequenceToHtml(java.lang.String s,
                                     java.lang.String f)
Read the specified sequence and store the data in an HTML table

Parameters:
s - sequence
f - HTML file
Returns:
true if the file was successfully written