Distorted Android

package org.distorted.library;

import android.graphics.Bitmap;

import android.opengl.GLES20;

import android.opengl.GLUtils;

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * All Objects to which Distorted Graphics effects can be applied need to be extended from here.

 */

public abstract class DistortedObject 

{ 

    static final int TYPE_NUM = 4;

    private static final int TYPE_MASK= (1<<TYPE_NUM)-1;

    private static float[] mViewMatrix = new float[16];

    protected EffectListPreShader  mM;

    protected EffectListFragment   mF;

    protected EffectListVertex     mV;

    protected EffectListPostShader mP;

    protected boolean matrixCloned, vertexCloned, fragmentCloned;

    protected GridObject mGrid = null;

    protected long mID;

    protected int mSizeX, mSizeY, mSizeZ, mSize; // in screen space

    protected Bitmap[] mBmp= null; // 

    int[] mTextureDataH;           // have to be shared among all the cloned Objects

    boolean[] mBitmapSet;          // 

///////////////////////////////////////////////////////////////////////////////////////////////////

    protected abstract DistortedObject deepCopy(int flags);

///////////////////////////////////////////////////////////////////////////////////////////////////

    protected void initializeData(int size)

      {

      mID             = DistortedObjectList.add(this);

      mSize           = size;

      mTextureDataH   = new int[1];

      mTextureDataH[0]= 0;

      mBmp            = new Bitmap[1];

      mBmp[0]         = null;

      mBitmapSet      = new boolean[1];

      mBitmapSet[0]   = false;

      initializeEffectLists(this,0);

      if( Distorted.isInitialized() ) resetTexture();    

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

    protected void initializeEffectLists(DistortedObject d, int flags)

      {

      if( (flags & Distorted.CLONE_PRESHADER) != 0 )

        {

        mM = d.mM;

        matrixCloned = true;

        } 

      else

        {

        mM = new EffectListPreShader(d);

        matrixCloned = false;  

        }

      if( (flags & Distorted.CLONE_VERTEX) != 0 )

        {

        mV = d.mV;

        vertexCloned = true;

        } 

      else

        {

        mV = new EffectListVertex(d);

        vertexCloned = false;  

        }

      if( (flags & Distorted.CLONE_FRAGMENT) != 0 )

        {

        mF = d.mF;

        fragmentCloned = true;

        } 

      else

        {

        mF = new EffectListFragment(d);

        fragmentCloned = false;   

        }

      mP = new EffectListPostShader(d); // PostShader effects are never cloned.

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

// this will be called on startup and every time OpenGL context has been lost

// also call this from the constructor if the OpenGL context has been created already.

    void resetTexture()

      {

      if( mTextureDataH!=null ) 

        {

        if( mTextureDataH[0]==0 ) GLES20.glGenTextures(1, mTextureDataH, 0);

        GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, mTextureDataH[0]);       

        GLES20.glTexParameteri ( GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR );

        GLES20.glTexParameteri ( GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR );

        GLES20.glTexParameteri ( GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE );

        GLES20.glTexParameteri ( GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE );

        if( mBmp!=null && mBmp[0]!=null)

          {

          GLUtils.texImage2D(GLES20.GL_TEXTURE_2D, 0, mBmp[0], 0);

          mBmp[0] = null;

          }

        }

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

    void drawPriv(long currTime, DistortedProjection dp)

      {

      GLES20.glViewport(0, 0, dp.width, dp.height); 

      mM.compute(currTime);

      mM.send(mViewMatrix, dp);

      mV.compute(currTime);

      mV.postprocess();

      mV.send();

      mF.compute(currTime);

      mF.postprocess(mViewMatrix);

      mF.send();

      mGrid.draw();

      mP.send();

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

    void drawNoEffectsPriv(DistortedProjection dp)

      {

      GLES20.glViewport(0, 0, dp.width, dp.height);

      mM.sendNoEffects(dp);

      mV.sendZero();

      mF.sendZero();

      mGrid.draw();

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

    void releasePriv()

      {

      if( matrixCloned  ==false) mM.abortAll();

      if( vertexCloned  ==false) mV.abortAll();

      if( fragmentCloned==false) mF.abortAll();

      mP.abortAll();

      mBmp          = null;

      mGrid         = null;

      mM            = null;

      mV            = null;

      mF            = null;

      mP            = null;

      mTextureDataH = null;

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

    long getBitmapID()

      {

      return mBmp==null ? 0 : mBmp.hashCode();

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

  /**

   * Default empty constructor so that derived classes can call it

   */

    public DistortedObject()

      {

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

  /**

   * Copy constructor used to create a DistortedObject based on various parts of another object.

   * <p>

   * Whatever we do not clone gets created just like in the default constructor.

   *

   * @param dc    Source object to create our object from

   * @param flags A bitmask of values specifying what to copy.

   *              For example, CLONE_BITMAP | CLONE_PRESHADER.

   */

    public DistortedObject(DistortedObject dc, int flags)

      {

      initializeEffectLists(dc,flags);

      mID = DistortedObjectList.add(this);

      mSizeX = dc.mSizeX;

      mSizeY = dc.mSizeY;

      mSizeZ = dc.mSizeZ;

      mSize  = dc.mSize;

      mGrid  = dc.mGrid;

      if( (flags & Distorted.CLONE_BITMAP) != 0 )

        {

        mTextureDataH = dc.mTextureDataH;

        mBmp          = dc.mBmp;

        mBitmapSet    = dc.mBitmapSet;

        }

      else

        {

        mTextureDataH   = new int[1];

        mTextureDataH[0]= 0;

        mBitmapSet      = new boolean[1];

        mBitmapSet[0]   = false;

        mBmp            = new Bitmap[1];

        mBmp[0]         = null;

        if( Distorted.isInitialized() ) resetTexture();

        }

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Draw the DistortedObject to the location specified by current Matrix effects.    

 *     

 * @param currTime current time, in milliseconds, as returned by System.currentTimeMillis().

 *        This gets passed on to Interpolators inside the Effects that are currently applied to the 

 *        Object.

 */

   public void draw(long currTime)

     {

     GLES20.glActiveTexture(GLES20.GL_TEXTURE0);

     GLES20.glBindFramebuffer(GLES20.GL_FRAMEBUFFER, 0);

     GLES20.glUniform1i(Distorted.mTextureUniformH, 0);  

     GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, mTextureDataH[0]); 

     drawPriv(currTime, Distorted.mProjection);

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Releases all resources.

 */

   public synchronized void release()

     {

     releasePriv();  

     DistortedObjectList.remove(this);

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Sets the underlying android.graphics.Bitmap object and uploads it to the GPU. 

 * <p>

 * You can only recycle() the passed Bitmap once the OpenGL context gets created (i.e. after call 

 * to onSurfaceCreated) because only after this point can the Library upload it to the GPU!

 * 

 * @param bmp The android.graphics.Bitmap object to apply effects to and display.

 */

   public void setBitmap(Bitmap bmp)

     {

     mBitmapSet[0] = true; 

     if( Distorted.isInitialized() )

       {

       GLES20.glActiveTexture(GLES20.GL_TEXTURE0);

       GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, mTextureDataH[0]);        

       GLUtils.texImage2D(GLES20.GL_TEXTURE_2D, 0, bmp, 0);

       }

     else

       {

       mBmp[0] = bmp;  

       }

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Adds the calling class to the list of Listeners that get notified each time some event happens 

 * to one of the Effects that are currently applied to the DistortedBitmap.

 * 

 * @param el A class implementing the EffectListener interface that wants to get notifications.

 */

   public void addEventListener(EffectListener el)

     {

     mV.addListener(el);

     mF.addListener(el);

     mM.addListener(el);

     mP.addListener(el);

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Removes the calling class from the list of Listeners.

 * 

 * @param el A class implementing the EffectListener interface that no longer wants to get notifications.

 */

   public void removeEventListener(EffectListener el)

     {

     mV.removeListener(el);

     mF.removeListener(el);

     mM.removeListener(el);

     mP.removeListener(el);

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Returns the height of the DistortedObject.

 *    

 * @return height of the object, in pixels.

 */

   public int getWidth()

     {

     return mSizeX;   

     }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Returns the width of the DistortedObject.

 * 

 * @return width of the Object, in pixels.

 */

    public int getHeight()

      {

      return mSizeY;  

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Returns the depth of the DistortedObject.

 * 

 * @return depth of the Object, in pixels.

 */

    public int getDepth()

      {

      return mSizeZ;  

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Returns unique ID of this instance.

 * 

 * @return ID of the object.

 */

    public long getID()

      {

      return mID;  

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Aborts all Effects. 

 */

    public void abortAllEffects()

      {

      mM.abortAll();

      mV.abortAll();

      mF.abortAll();

      mP.abortAll();

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Aborts a subset of Effects.

 * 

 * @param mask Bitmask of the types of effects we want to abort, e.g. TYPE_PRE | TYPE_VERT | TYPE_FRAG.

 */

    public void abortAllEffects(int mask)

      {

      if( (mask & Distorted.TYPE_PRE ) != 0 ) mM.abortAll();

      if( (mask & Distorted.TYPE_VERT) != 0 ) mV.abortAll();

      if( (mask & Distorted.TYPE_FRAG) != 0 ) mF.abortAll();

      if( (mask & Distorted.TYPE_POST) != 0 ) mP.abortAll();

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Aborts a single Effect.

 * 

 * @param id ID of the Effect we want to abort.

 * @return <code>true</code> if the Effect was found and successfully aborted.

 */

    public boolean abortEffect(long id)

      {

      switch( (int)(id&TYPE_MASK) )

        {

        case Distorted.TYPE_PRE : return mM.removeByID(id>>TYPE_NUM);

        case Distorted.TYPE_VERT: return mV.removeByID(id>>TYPE_NUM);

        case Distorted.TYPE_FRAG: return mF.removeByID(id>>TYPE_NUM);

        case Distorted.TYPE_POST: return mP.removeByID(id>>TYPE_NUM);

        default                 : return false;

        }

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Abort all Effects of a given type, for example all rotations.

 * 

 * @param effectType one of the constants defined in {@link EffectNames}

 * @return <code>true</code> if a single Effect of type effectType has been found and aborted. 

 */

    public boolean abortEffectType(EffectNames effectType)

      {

      switch(effectType.getType())

        {

        case Distorted.TYPE_PRE : return mM.removeByType(effectType);

        case Distorted.TYPE_VERT: return mV.removeByType(effectType);

        case Distorted.TYPE_FRAG: return mF.removeByType(effectType);

        case Distorted.TYPE_POST: return mP.removeByType(effectType);

        default                 : return false;

        }

      }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Print some info about a given Effect to Android's standard out. Used for debugging only.

 * 

 * @param id Effect ID we want to print info about

 * @return <code>true</code> if a single Effect of type effectType has been found.

 */

    public boolean printEffect(long id)

      {

      switch( (int)(id&TYPE_MASK) )

        {

        case Distorted.TYPE_PRE : return mM.printByID(id>>TYPE_NUM);

        case Distorted.TYPE_VERT: return mV.printByID(id>>TYPE_NUM);

        case Distorted.TYPE_FRAG: return mF.printByID(id>>TYPE_NUM);

        case Distorted.TYPE_POST: return mP.printByID(id>>TYPE_NUM);

        default                 : return false;

        }

      }

///////////////////////////////////////////////////////////////////////////////////////////////////   

///////////////////////////////////////////////////////////////////////////////////////////////////

// Individual effect functions.

///////////////////////////////////////////////////////////////////////////////////////////////////

// Matrix-based effects

///////////////////////////////////////////////////////////////////////////////////////////////////

// MOVE

/**

 * Moves the Object by a vector that changes in time as interpolated by the Interpolator.

 * 

 * @param di 3-dimensional Interpolator which at any given time will return a Float3D

 *           representing the current coordinates of the vector we want to move the Object with.

 * @return   ID of the effect added, or -1 if we failed to add one. 

 */

  public long move(Interpolator3D di)

    {   

    return mM.add(EffectNames.MOVE,null,di);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Moves the Bitmap by a vector that smoothly changes from (0,0,0) to (x,y,z).

 *  

 * @param x        The x-coordinate of the vector we want to move the Object with. 

 * @param y        The y-coordinate of the vector we want to move the Object with.

 * @param z        The z-coordinate of the vector we want to move the Object with.

 * @param duration The time, in milliseconds, it takes to complete the movement.

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long move(float x,float y,float z, int duration)

    {   

    Interpolator3D di = new Interpolator3D();  

    di.setCount(0.5f);

    di.setDuration(duration);

    di.add(new Float3D(0.0f,0.0f,0.0f));                             

    di.add(new Float3D(x,y,z));                        

    return mM.add(EffectNames.MOVE,null,di);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Moves the Bitmap by vector (x,y,z) immediately.

 *   

 * @param x The x-coordinate of the vector we want to move the Object with. 

 * @param y The y-coordinate of the vector we want to move the Object with.

 * @param z The z-coordinate of the vector we want to move the Object with.

 * @return  ID of the effect added, or -1 if we failed to add one. 

 */

  public long move(float x,float y,float z)

    {   

    return mM.add(EffectNames.MOVE,0.0f,0.0f,0.0f,x,y,z,0.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

// SCALE

/**

 * Scales the Object by factors that change in time as returned by the Interpolator.

 * 

 * @param di 3-dimensional Interpolator which at any given time returns a Float3D

 *           representing the current x- , y- and z- scale factors.

 * @return   ID of the effect added, or -1 if we failed to add one. 

 */

  public long scale(Interpolator3D di)

    {   

    return mM.add(EffectNames.SCALE,null,di);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Scales the Object by a factor that smoothly changes from (1,1,1) at time 0 to (xscale,yscale,zscale)

 * after 'duration' milliseconds. 

 *    

 * @param xscale   After time 'duration' passes, Bitmap's width will get multiplied by xscale; e.g. if 

 *                 xscale=2, after 'duration' milliseconds the Object will become twice broader.

 * @param yscale   Factor to scale Object's height with.

 * @param zscale   Factor to scale Object's depth with.

 * @param duration Time, in milliseconds, it takes to interpolate to the full (xscale,yscale,zscale) scaling factors.

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long scale(float xscale,float yscale,float zscale, int duration)

    {   

    Interpolator3D di = new Interpolator3D();  

    di.setCount(0.5f);

    di.setDuration(duration);

    di.add(new Float3D(1.0f,1.0f,1.0f));                             

    di.add(new Float3D(xscale,yscale,zscale));                        

    return mM.add(EffectNames.SCALE,null,di);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Immediately scales the Object's width by (xscale,yscale,zscale).   

 *   

 * @param xscale Object's width gets multiplied by this factor; e.g. if 

 *               xscale=2, the Object immediately becomes twice broader.

 * @param yscale factor to scale Object's height with.

 * @param zscale factor to scale Object's depth with. 

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long scale(float xscale,float yscale,float zscale)

    {   

    return mM.add(EffectNames.SCALE,0.0f,0.0f,0.0f,xscale,yscale,zscale,0.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Convenience function - scale the Object by the same factor in all 3 dimensions.   

 *   

 * @param scale all 3 Object's dimensions get multiplied by this factor; e.g. if 

 *              scale=2, the Object immediately becomes twice larger.

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long scale(float scale)

    {   

    return mM.add(EffectNames.SCALE,0.0f,0.0f,0.0f,scale,scale,scale,0.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

// ROTATE

/**

 * Rotates the Object around a (possibly moving) point, with angle and axis that change in time.

 * 

 * @param i 3-dimensional Interpolator which at any given time will return the current center of 

 *          the rotation

 * @param v 4-dimensional Interpolator which at any given time will return a Float4D

 *          representing the current rotation in the (angle,axisX,axisY,axisY) form. 

 * @return  ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Interpolator3D i, Interpolator4D v)

    {   

    return mM.add(EffectNames.ROTATE, i, v);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////  

/**

 * Rotates the Object around a static point, with angle and axis that change in time.

 * 

 * @param point Center of the rotation

 * @param v     4-dimensional Interpolator which at any given time will return a Float4D

 *              representing the current rotation in the (angle,axisX,axisY,axisY) form. 

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Float3D point, Interpolator4D v)

    {   

    return mM.add(EffectNames.ROTATE, point.x, point.y, point.z , v);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////  

/**

 * Rotates the Object around a static point, with angle that changes in time, around axis 

 * (axisX, axisY, axisZ). 

 * 

 * @param point Center of the rotation

 * @param v     1-dimensional Interpolator which at any given time will return the current rotation 

 *              angle.

 * @param axisX Rotation vector: x-coordinate

 * @param axisY Rotation vector: y-coordinate         

 * @param axisZ Rotation vector: z-coordinate         

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Float3D point, Interpolator1D v, float axisX, float axisY, float axisZ)

    {   

    return mM.add(EffectNames.ROTATE, point.x, point.y, point.z , v, axisX, axisY, axisZ);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object around a (possibly moving) point, with angle that changes in time.

 * Axis of rotation is the vector (0,0,1), i.e. a vector normal to the screen surface.

 * 

 * @param i 3-dimensional Interpolator which at any given time will return the current center

 *          of the rotation.

 * @param a 1-dimensional Interpolator which returns the current rotation angle.         

 * @return  ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Interpolator3D i, Interpolator1D a)

    {   

    return mM.add(EffectNames.ROTATE, i, a, 0.0f,0.0f,1.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object around a constant point, with angle that changes in time.  

 * Axis of rotation is the vector (0,0,1), i.e. a vector normal to the screen surface.

 *   

 * @param point    Coordinates of the Point we are rotating around.

 * @param angle    Angle that we want to rotate the Bitmap to. Unit: degrees

 * @param duration Time, in milliseconds, it takes to complete one rotation from 0 to 'angle' degrees.

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Float3D point, int angle, int duration)

    {   

    Interpolator1D di = new Interpolator1D();  

    di.setCount(0.5f);

    di.setDuration(duration);

    di.add(new Float1D(    0));                             

    di.add(new Float1D(angle));                        

    return mM.add(EffectNames.ROTATE,point.x,point.y,point.z, di, 0.0f,0.0f,1.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object immediately by 'angle' degrees around point p.   

 * Axis of rotation is given by the last 3 floats.

 *   

 * @param point Coordinates of the Point we are rotating around.

 * @param angle Angle that we want to rotate the Bitmap to. Unit: degrees

 * @param axisX Axis of rotation: x-coordinate

 * @param axisY Axis of rotation: y-coordinate

 * @param axisZ Axis of rotation: z-coordinate

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Float3D point, float angle, float axisX, float axisY, float axisZ)

    {   

    return mM.add(EffectNames.ROTATE, point.x, point.y, point.z, angle, axisX, axisY, axisZ);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object immediately by 'angle' degrees around point p.   

 *   

 * @param point  Coordinates of the Point we are rotating around.

 * @param angle  The angle that we want to rotate the Bitmap to. Unit: degrees

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long rotate(Float3D point, int angle)

    {   

    return mM.add(EffectNames.ROTATE,point.x,point.y,point.z,angle,0.0f,0.0f,1.0f);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

// QUATERNION

/**

 * Rotates the Object immediately by quaternion (qX,qY,qZ,qW).

 *   

 * @param point Coordinates of the Point we are rotating around.

 * @param qX    Quaternion: x-coordinate

 * @param qY    Quaternion: y-coordinate

 * @param qZ    Quaternion: z-coordinate

 * @param qW    Quaternion: w-coordinate

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long quaternion(Float3D point, float qX, float qY, float qZ, float qW)

    {   

    return mM.add(EffectNames.QUATERNION,point.x,point.y,point.z,qX,qY,qZ,qW);   

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object by a quaternion that's at the moment returned by the InterpolatorQuat.

 *   

 * @param point Coordinates of the Point we are rotating around.

 * @param iq    Interpolator that's going to, at any given moment, return a quaternion.

 * @return      ID of the effect added, or -1 if we failed to add one. 

 */

  public long quaternion(Float3D point, InterpolatorQuat iq)

    {   

    return mM.add(EffectNames.QUATERNION,point.x,point.y,point.z,iq);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Rotates the Object around a moving point by a quaternion that's at the moment returned by the InterpolatorQuat.

 *   

 * @param i  Interpolator that returns the current center of rotation.

 * @param iq Interpolator that's going to, at any given moment, return a quaternion representing the current rotation.

 * @return   ID of the effect added, or -1 if we failed to add one. 

 */

  public long quaternion(Interpolator3D i, InterpolatorQuat iq)

    {   

    return mM.add(EffectNames.QUATERNION,i,iq);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

// SHEAR

/**

 * Shears the Object. If the Interpolator is 1D, it will shear along the X-axis. 2D Interpolator adds

 * shearing along the Y-axis, 3D one along Z axis.

 *

 * @param point  Center of shearing, i.e. the point which stays unmoved. 

 * @param di     1- 2- or 3D Interpolator which, at any given point, returns the ordered 1-, 2- 

 *               or 3-tuple of shear factors.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long shear(Float3D point, Interpolator di)

    {

    return mM.add(EffectNames.SHEAR, point.x, point.y, point.z, di);  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Shears the Object in 3D. Order: first X shearing, then Y, then Z.

 * 

 * @param point  Center of shearing, i.e. the point which stays unmoved. 

 * @param vector ordered 3-tuple (x-degree, y-degree, z-degree) of shearing (tangent of the angle with 

 *               which the X,Y and Z axis get slanted) 

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long shear(Float3D point, Float3D vector)

    {

    Interpolator3D di = new Interpolator3D(); 

    di.setCount(0.5f);

    di.setDuration(0);

    di.add(new Float3D(0.0f,0.0f,0.0f));              

    di.add(vector);                                                

    return mM.add(EffectNames.SHEAR, point.x, point.y, point.z, di );  

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

// Fragment-based effects  

///////////////////////////////////////////////////////////////////////////////////////////////////

// MACROBLOCK

/**

 * Creates macroblocks at and around point defined by the Interpolator2D and the Region. 

 * Size of the macroblocks at any given time is returned by the Interpolator1D.

 * 

 * @param a      1-dimensional Interpolator which, at any given time, returns the size of the macroblocks.

 * @param region Region this Effect is limited to.

 *               Null here means 'apply the effect to the whole Bitmap'.

 * @param i      2-dimensional Interpolator which, at any given time, returns a Float2D representing the

 *               current center of the effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long macroblock(Interpolator1D a, Float4D region, Interpolator2D i)

    {

    return mF.add(EffectNames.MACROBLOCK, a, region, i);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Creates macroblocks at and around point defined by the Point2D and the Region. 

 * Size of the macroblocks at any given time is returned by the Interpolator1D.

 * <p>

 * The difference between this and the previous method is that here the center of the Effect stays constant.

 *    

 * @param a      1-dimensional Interpolator which, at any given time, returns the size of the macroblocks.

 * @param region Region this Effect is limited to. 

 *               Null here means 'apply the effect to the whole Bitmap'.

 * @param point  Center of the Effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long macroblock(Interpolator1D a, Float4D region, Float2D point)

    {

    return mF.add(EffectNames.MACROBLOCK, a, region, point.x, point.y);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Creates macroblocks at and around point defined by the Interpolator2D and the Region. 

 * <p>

 * The macroblocks change in size; at time 0 there are none, and after 'duration/2' milliseconds 

 * they are of (pixels X pixels) size; after 'duration' milliseconds there are again none (i.e. their

 * size is 1X1, i.e. 1 pixel).   

 * 

 * @param pixels   Maximum size, in pixels, of the Macroblocks we want to see.

 * @param region   Region this Effect is limited to. 

 *                 Null here means 'apply the effect to the whole Bitmap'.

 * @param i        2-dimensional Interpolator which, at any given time, returns a Float2D representing the

 *                 current center of the effect.

 * @param duration Time, in milliseconds, it takes to do one full interpolation.

 * @param count    Controls how many interpolations we want to do. See {@link Interpolator#setCount(float)}

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long macroblock(int pixels, Float4D region, Interpolator2D i, int duration, float count)

    {

    Interpolator1D di = new Interpolator1D();

    di.setCount(count);

    di.setDuration(duration);

    di.add(new Float1D(1));                             

    di.add(new Float1D(pixels));                        

    return mF.add(EffectNames.MACROBLOCK, di, region, i);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Creates macroblocks at and around point defined by the Point2D and the Region. 

 * <p>

 * The macroblocks change in size; at time 0 there are none, and after 'duration/2' milliseconds 

 * they are of (pixels X pixels) size; after 'duration' milliseconds there are again none (i.e. their

 * size is 1X1, i.e. 1 pixel).   

 * <p>

 * The difference between this and the previous method is that here the center of the Effect stays constant.

 *    

 * @param pixels   Maximum size, in pixels, of the Macroblocks we want to see.

 * @param region   Region this Effect is limited to. 

 *                 Null here means 'apply the effect to the whole Bitmap'.

 * @param point    Center of the Effect.

 * @param duration Time, in milliseconds, it takes to do one full interpolation.

 * @param count    Controls how many interpolations we want to do. See {@link Interpolator#setCount(float)}

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long macroblock(int pixels, Float4D region, Float2D point, int duration, float count)

    {

    Interpolator1D di = new Interpolator1D();

    di.setCount(count);

    di.setDuration(duration);

    di.add(new Float1D(1));                             

    di.add(new Float1D(pixels));                        

    return mF.add(EffectNames.MACROBLOCK, di, region, point.x, point.y);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Creates macroblocks on the whole Bitmap. 

 * <p>

 * The macroblocks change in size; at time 0 there are none, and after 'duration/2' milliseconds 

 * they are of (pixels X pixels) size; after 'duration' milliseconds there are again none (i.e. their

 * size is 1X1, i.e. 1 pixel).   

 * <p>

 * The difference between this and the previous method is that here there is no masking Region; thus

 * there is also no center of the Effect. 

 *    

 * @param pixels   Maximum size, in pixels, of the Macroblocks we want to see.

 * @param duration Time, in milliseconds, it takes to do one full interpolation.

 * @param count    Controls how many interpolations we want to do. See {@link Interpolator#setCount(float)}

 * @return         ID of the effect added, or -1 if we failed to add one. 

 */

  public long macroblock(int pixels, int duration, float count) 

    {

    Interpolator1D di = new Interpolator1D(); 

    di.setCount(count);

    di.setDuration(duration);

    di.add(new Float1D(1));                            

    di.add(new Float1D(pixels));                        

    return mF.add(EffectNames.MACROBLOCK, di, null, 0.0f, 0.0f);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////////////////////////

// CHROMA

/**

 * Makes a certain sub-region of the Bitmap smoothly change all three of its RGB components.

 *        

 * @param t      1-dimensional Interpolator that returns the level of blend a given pixel will be

 *               mixed with the next parameter 'color': pixel = (1-level)*pixel + level*color

 * @param color  Color to mix.         

 * @param region Region this Effect is limited to. 

 *               Null here means 'apply the Effect to the whole Bitmap'.

 * @param i      2-dimensional Interpolator which, at any given time, returns a Float2D representing 

 *               the current center of the effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long chroma(Interpolator1D t, Float3D color, Float4D region, Interpolator2D i)

    {

    return mF.add(EffectNames.CHROMA, t, color, region, i);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Makes a certain sub-region of the Bitmap smoothly change all three of its RGB components.

 * <p>

 * Here the center of the Effect stays constant.

 *         

 * @param t      1-dimensional Interpolator that returns the level of blend a given pixel will be 

 *               mixed with the next parameter 'color': pixel = (1-level)*pixel + level*color

 * @param color  Color to mix.         

 * @param region Region this Effect is limited to. 

 *               Null here means 'apply the Effect to the whole Bitmap'.

 * @param point  Center of the Effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long chroma(Interpolator1D t, Float3D color, Float4D region, Float2D point)

    {

    return mF.add(EffectNames.CHROMA, t, color, region, point.x, point.y);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////  

/**

 * Makes a certain sub-region of the Bitmap smoothly change all three of its RGB components.

 *        

 * @param t      Level of blend a given pixel will be mixed with the next parameter 'color': 

 *               pixel = (1-t)*pixel + t*color

 * @param color  Color to mix.       

 * @param region Region this Effect is limited to.

 *               Null here means 'apply the Effect to the whole Bitmap'.

 * @param i      2-dimensional Interpolator which, at any given time, returns a Float2D representing the

 *               current center of the effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long chroma(float t, Float3D color, Float4D region, Interpolator2D i)

    {

    return mF.add(EffectNames.CHROMA, t, color, region, i);

    }

///// //////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Makes a certain sub-region of the Bitmap smoothly change all three of its RGB components.

 * <p>

 * Here the center of the Effect stays constant.

 *         

 * @param t      Level of blend a given pixel will be mixed with the next parameter 'color': 

 *               pixel = (1-t)*pixel + t*color

 * @param color  Color to mix.       

 * @param region The Region this Effect is limited to. 

 *               Null here means 'apply the Effect to the whole Bitmap'.

 * @param point  Center of the Effect.

 * @return       ID of the effect added, or -1 if we failed to add one. 

 */

  public long chroma(float t, Float3D color, Float4D region, Float2D point)

    {

    return mF.add(EffectNames.CHROMA, t, color, region, point.x, point.y);

    }

///////////////////////////////////////////////////////////////////////////////////////////////////

/**

 * Makes a certain sub-region of the Bitmap smoothly change all three of its RGB components.

 * <p>

 * Here the Effect applies to the whole bitmap.

 *