view src/uk/ac/qmul/eecs/depic/daw/haptics/HapticViewPort.java @ 2:c0412c81d274

Added documentation

package uk.ac.qmul.eecs.depic.daw.haptics;

/**
 * The haptic viewport is the specific portion of a track that is visible in the haptic view 
 * in every moment. 
 * 
 * It uses the same concept of a scrollable window: if the content is to big to be represented 
 * in a single window, then you only represent a portion of it and allow the user to scroll 
 * up and down. Likewise the haptic view port only represent one portion of audio track at 
 * the time and when the haptic proxy gets to the left or right ends of the view port, then 
 * the viewport is shifted of a certain amount of pixels.
 * 
 *
 */
public class HapticViewPort {
	public static final int DEFAULT_WIDTH = 2320; // 2 secs at scale factor =1 
												  //with 8000 Hz frame rate. x = 4000/frameRate * minChunksize => 2 = 4000/8000 * 4 
	public final static float STEP_SIZE = 5.0f;// in milliseconds 
	private static final double LOG_2 = Math.log(2);
	
	/* the width of the viewport */
	private int width;
	private float offset;
	private int trackSize;
	private int scaleFactor;
	
	public HapticViewPort(int scaleFactor){
		offset = 0.0f;
		width = DEFAULT_WIDTH;
		this.scaleFactor = scaleFactor;
		trackSize = 0;
	}
	

	/**
	 * 
	 * @param amount the amount of shift in pixels (or chunks)
	 */
	public void shift(float amount){
		if(width > trackSize) // shifts only if viewport is smaller than the whole track
			return;

		offset += amount;
		if(offset < 0) // cannot shift more left than 0 
			offset = 0;
		else if(offset > (trackSize - width)) // cannot more right than the track size-VIEWPORT_SIZE 
			offset = (trackSize - width);     // (as the offset counts for the viewport start)
	}
	
	/**
	 * Returns the position in the haptic view port that is mapped to {@code ratio}. 
	 * {@code ratio} is a normalized value ranging from 0 to 1. 
	 * 
	 * 
	 * @param ratio the position on the haptic view port as a ratio of the haptic view port width  
	 * @return the the position on the haptic view port as chunk/pixel position  
	 */
	public int getPosition(float ratio){
		return (int)(offset+(width*ratio));
	}
	
	public void setTrackSize(int trackSize){
		this.trackSize = trackSize;
	}
	
	public int getScaleFactor() {
		return scaleFactor;
	}
	
	public int getWidth(){
		return width;
	}

	public void setScaleFactor(int scaleFactor) {
		if(scaleFactor <= 0)
			throw new IllegalArgumentException("scaleFactor must be greater than 0");
		this.scaleFactor = scaleFactor;
		
		/* this formula makes the viewport size grow linearly-ish * 
		 * It grows as a function of scaleFactor : (2 * (2^(scaleFactor - 1)) / scaleFactor) + 2*log_2(scaleFactor)) */
		double w = (DEFAULT_WIDTH / scaleFactor ) + (log2(scaleFactor) * DEFAULT_WIDTH/Math.pow(2, scaleFactor-1)) ;
		width = (int)w;
	}

	public static double log2(double x) {
		return Math.log(x)/LOG_2;
	}
}