package com.brackeen.javagamebook.sound;

/**
    Klasa abstrakcyjna zaprojektowana do filtrowania próbek dźwiękowych.
    Ponieważ obiekty SoundFilter mogą korzystać z wewnętrznego buforowania
    próbek, dla każdego odtwarzanego dźwięku należy tworzyć osobny obiekt
    SoundFilter. Po zakończeniu odtwarzania dźwięku, obiekty
    SoundFilters mogą być ponownie wykorzystane po wywołaniu metody reset().
    <p>Zakładamy, że próbki są w formacie 16-bitowym, ze znakiem, z rosnącym
    porządkiem bitów.
    @see FilteredSoundStream
*/
public abstract class SoundFilter{

    /**
        Resetuje bieżący SoundFilter. Domyślnie nic nie robi.
    */
    public void reset() {
        // nic nie rób
    }

    /**
        Zwraca ilość dodatkowych danych (w bajtach), które filtr odtwarza po
        zakończeniu oryginalnego dźwięku. Przykładem może być echo, które
        trwa dużej niż oryginalny dźwięk.
        Domyślnie metoda zwraca 0.
    */
    public int getRemainingSize() {
        return 0;
    }

    /**
        Filtruje tablicę próbek. Próbki powinny być w formacie 16-bitowym, 
        ze znakiem i rosnącym porządkiem bitów.
    */
    public void filter(byte[] samples) {
        filter(samples, 0, samples.length);
    }

    /**
        Filtruje tablicę próbek. Próbki powinny być w formacie 16-bitowym, 
        ze znakiem i rosnącym porządkiem bitów. Metoda ta powinna
        być zaimplementowana w klasach pochodnych.
    */
    public abstract void filter(
        byte[] samples, int offset, int length);


    /**
        Wygodna metoda do pobierania 16-bitowych próbek z tablicy bajtów.
        Próbki powinny być w formacie 16-bitowym, ze znakiem
        i rosnącym porządkiem bitów.
    */
    public static short getSample(byte[] buffer, int position) {
        return (short)(
            ((buffer[position+1] & 0xff) << 8) |
            (buffer[position] & 0xff));
    }


    /**
        Wygodna metoda do ustawiania 16-bitowych próbek w tablicy bajtów.
        Próbki powinny być w formacie 16-bitowym, ze znakiem 
        i rosnącym porządkiem bitów.
    */
    public static void setSample(byte[] buffer, int position,
        short sample)
    {
        buffer[position] = (byte)(sample & 0xff);
        buffer[position+1] = (byte)((sample >> 8) & 0xff);
    }

}
