/*
 *  Software License Agreement
 *
 * Copyright (C) Cross The Road Electronics.  All rights
 * reserved.
 * 
 * Cross The Road Electronics (CTRE) licenses to you the right to 
 * use, publish, and distribute copies of CRF (Cross The Road) firmware files (*.crf) and Software
 * API Libraries ONLY when in use with Cross The Road Electronics hardware products.
 * 
 * THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT
 * WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT
 * LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL
 * CROSS THE ROAD ELECTRONICS BE LIABLE FOR ANY INCIDENTAL, SPECIAL, 
 * INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF
 * PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS
 * BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE
 * THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER
 * SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT
 * (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE
 */
package com.ctre.phoenix.music;

import com.ctre.phoenix.ErrorCode;
import com.ctre.phoenix.motorcontrol.can.TalonFX;
import java.util.Collection;

/**
 * An Orchestra is used to play music through Talon FX motor controllers.
 * It uses a "Chirp" (.chrp) music file that can be generated using Phoenix Tuner.
 * 
 * Chirp files are generated from standard MIDI files.
 * Each Talon FX can only play a single track within the music file.
 * For multi-track files, multiple Talon FXs are needed.
 *  ie, The first track will be played through the first Talon FX added,
 *  the second track will be played through the second Talon FX added, etc.
 * 
 * Any Chirp file located in the src/main/deploy directory of your FRC project 
 *  will automatically be copied to the roboRIO on code deploy.
 * 
 * To use the Orchestra:
 *  - Add the Talon FXs to be used as instruments
 *  - Load the Chirp file to be played using the loadMusic routine.
 * Both of these can also be done in the Orchestra constructor.
 * 
 * Once ready, the Orchestra can be controlled using standard
 * play/pause/stop routines.
 * 
 * New music files can be loaded at any time.
 * 
 * The robot must be enabled to play music.
 * 
 * Calling set on any of the TalonFX instruments while the orchestra is
 * playing will pause the orchestra.
 */
public class Orchestra {
    private long m_handle;

    /**
     * Constructor for an Orchestra Object.
     * Call AddInstrument after this to add the instruments.
     */
    public Orchestra() {
        m_handle = OrchestraJNI.JNI_new_Orchestra();
    }
    /**
     * Constructor for an Orchestra Object.
     * @param instruments
     *          A collection of TalonFX's that will be used as instruments
     *          inside the orchestra.
     */
    public Orchestra(Collection<TalonFX> instruments) {
        this();

        for(TalonFX instrument : instruments) {
            addInstrument(instrument);
        }
    }
    /**
     * Constructor for an Orchestra Object
     * @param instruments
     *          A collection of TalonFX's that will be used as instruments
     *          inside the orchestra.
     * @param filePath
     *          The path to the music file to immediately load into
     *          the orchestra.
     */
    public Orchestra(Collection<TalonFX> instruments, String filePath) {
        this(instruments);

        loadMusic(filePath);
    }

    /**
     * Loads a Chirp file at the specified file path.
     * 
     * If the Chirp file is inside your "src/main/deploy" directory
     * this file will be automatically deployed to a default directory in
     * the RoboRIO when you deploy code. For these files, the name and file 
     * extension is sufficient.
     * 
     * Use Tuner to create a Chirp file.
     * @param filePath
     *              The path to the Chirp File.
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode loadMusic(String filePath) {
        int retval = OrchestraJNI.JNI_LoadMusic(m_handle, filePath);
        return ErrorCode.valueOf(retval);
    }

    /**
     * Plays the music file that's loaded. 
     * If the player is paused, this will resume.
     * This will also resume a song if the orchestra was interrupted.
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode play() {
        int retval = OrchestraJNI.JNI_Play(m_handle);
        return ErrorCode.valueOf(retval);
    }

    /**
     * Stops the music file that's loaded. 
     * This resets the current position in the track to the start.
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode stop() {
        int retval = OrchestraJNI.JNI_Stop(m_handle);
        return ErrorCode.valueOf(retval);
    }

    /**
     * Pauses the music file that's loaded. 
     * This saves the current position in the track, so it can be resumed later.
     * Pausing while stopped is an invalid request.
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode pause() {
        int retval = OrchestraJNI.JNI_Pause(m_handle);
        return ErrorCode.valueOf(retval);
    }

    /**
     * Returns whether the current track is actively playing or not
     * @return True if playing, false otherwise 
     */
    public boolean isPlaying() {
        return OrchestraJNI.JNI_IsPlaying(m_handle);
    }
    
    /**
     * @return The current timestamp of the music file (playing or paused) in milliseconds.
     * The timestamp will reset to zero whenever loadMusic() or stop() is called.
     * If isPlaying() returns false, this routine can be used to determine if music is stopped or paused.
     */
    public int getCurrentTime() {
        return OrchestraJNI.JNI_GetCurrentTime(m_handle);
    }

    /**
     * Clears all instruments in the orchestra.
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode clearInstruments() {
        int retval = OrchestraJNI.JNI_ClearInstruments(m_handle);
        return ErrorCode.valueOf(retval);
    }

    /**
     * Adds another instrument to the orchestra.
     * @param instrument
     *              TalonFX to add to orchestra
     * @return Error Code generated by function. 0 indicates no error. 
     */
    public ErrorCode addInstrument(TalonFX instrument) {
        int retval = OrchestraJNI.JNI_AddInstrument(m_handle, instrument.getHandle());
        return ErrorCode.valueOf(retval);
    }
}