view src/uk/ac/qmul/eecs/depic/daw/Selection.java @ 1:629262395647

Added some dosumentation
added .hginfo

/*  
 Cross-Modal DAW Prototype - Prototype of a simple Cross-Modal Digital Audio Workstation.

 Copyright (C) 2015  Queen Mary University of London (http://depic.eecs.qmul.ac.uk/)
	
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 This program 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 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
package uk.ac.qmul.eecs.depic.daw;

import uk.ac.qmul.eecs.depic.patterns.Range;

/**
 * 	
 * A selection on integer values
 *
 */
public final class Selection extends Range<Integer>{
	public static Selection ZERO_SELECTION = new Selection(0,1);
	private int scaleFactor; 
	private boolean open;
	
	/**
	 * Constructs a new instance of {@code LoopPoints} from the bound values passed as argument. 
	 *
	 * The lower value is assigned to the start of the loop, whereas the higher value is assigned to the end of the loop.
	 * If the two values are equals the loop is assumed to have no end but only a starting point.  
	 *
	 * @param start the start of the range, it must be greater or equal than 0 
	 * @param end the end of the range, it must be either greater or equal than 0 or equal to {@code NO_POSITION}
	 * @param scaleFactor 
	 * 
	 * @throws IndexOutOfBoundsException whether {@code start} is a negative
	 *         value or {@code end} is a negative value different from {@code NO_POSITION}
	 * @throws IllegalArgumentException if {@code end} is greater than {@code start}
	 */
	public Selection(int start, int end, int scaleFactor) {	
		super(start,end);
		if(start < 0 && !equals(ZERO_SELECTION)){
			throw new IndexOutOfBoundsException("bounds value must be a positive integer . start:"+start);
		}
		if(end < 0){
			throw new IndexOutOfBoundsException("bounds value must be a positive integer end:"+end);
		}
		if(start > end ){
			throw new IllegalArgumentException("start cannot be greater than end. start:"+start+" end:"+end);
		}
		
		open = false;
		this.scaleFactor = scaleFactor; // FIXME controls on scaleFactor 
	}
	
	public Selection(int start, int scaleFactor){
		super(start,start);   
		if(start < 0){
			throw new IndexOutOfBoundsException("bounds value must be a positive integer . start:"+start);
		}
		
		this.scaleFactor = scaleFactor;
		open = true;
	}
	
	/**
	 * Returns the end value of the loop
	 * 
	 * @return the end point or -1 if the loop has only the start and no end to indicate the final frame. 
	 * This value is consistent with the {@code Clip interface} 
	 * 
	 *  @see javax.sound.sampled.Clip#setLoopPoints(int, int)
	 */
	@Override
	public final Integer getEnd(){
		if(open)
			return -1;
		else
			return super.getEnd();
	}

	/**
	 * Returns the scale factor of this selection 
	 * 
	 * @return the scale factor of this selection
	 */
	public int getScaleFactor(){
		return scaleFactor;
	}
	
	/**
	 * Checks whether the selection defines an open or closed interval.  
	 * 
	 * The selection is open is the end is equal to {@code NO_POSITION}.
	 * 
	 * @return {@code true} is the selection is open, {@code false} otherwise
	 */
	public boolean isOpen(){
		return open;
	}
	
	
	
	/**
	 * Returns {@code true} if {@code p} is contained in the selection ( p is greater than {@code getStart()}
	 * and smaller than {@code getEnd()} ).
	 * 
	 *  If the selection is open, {@code false} is returned.
	 * 
	 * @param p the integer vale to check for
	 * 
	 * @return @return {@code true} if {@code p} is contained in the selection, {@code false} otherwise
	 */
	public boolean contains(int p){
		if(isOpen()){
			return false;
		}else{
			return ((p>=getStart()) && (p<=getEnd()));			
		}
		
	}
	
	@Override
	public String toString(){
		if(open)
			return getClass().getSimpleName()+" ["+getStart()+",inf), scale factor:"+scaleFactor;
		else
			return getClass().getSimpleName()+" ["+getStart()+","+getEnd()+"], scale factor:"+scaleFactor;
	}
	
	/**
	 * Convert a selection to another selection with a new scale factor.
	 * 
	 * The {@code start} and {@code end} of the selection are changed accordingly. 
	 * 
	 * @param s the selection to convert 
	 * @param newFactor the factor of the converted selection  
	 * @return {@code s} if {@code newFactor} is already the scale factor of {@code s}, a new selection 
	 *    
	 */
	public static Selection convertFactor(Selection s, int newFactor){
		if(s.getScaleFactor() == newFactor)
			return s;
		int newStart = (int)(s.getStart() * Math.pow(2,s.getScaleFactor()-newFactor));
		if(!s.isOpen()){
			int newEnd = (int)(s.getEnd() * Math.pow(2,s.getScaleFactor()-newFactor));
			return new Selection(newStart,newEnd,newFactor);
		}else{
			return new Selection(newStart,newFactor);			
		}
	}
	
	public static int convertFactor(int position, int fromFactor, int toFactor){
		if(fromFactor == toFactor){
			return position;
		}
			
		return (int)(position * Math.pow(2,fromFactor-toFactor));
	}
	
}