Distorted Android

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

// Copyright 2016 Leszek Koltunski                                                               //

//                                                                                               //

// This file is part of Distorted.                                                               //

//                                                                                               //

// Distorted 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 2 of the License, or                             //

// (at your option) any later version.                                                           //

//                                                                                               //

// Distorted 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 Distorted.  If not, see <http://www.gnu.org/licenses/>.                            //

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

package org.distorted.library.main;

import android.opengl.GLES31;

import android.opengl.Matrix;

import org.distorted.library.effect.EffectQuality;

import java.nio.ByteBuffer;

import java.nio.ByteOrder;

import java.nio.IntBuffer;

import java.util.ArrayList;

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

/**

 * This is not really part of the public API.

 *

 * @y.exclude

 */

public abstract class DistortedOutputSurface extends DistortedSurface implements DistortedMaster.Slave

{

//////////// DEBUG FLAGS /////////////////////////////////////////////

/**

 * When rendering a Screen, show FPS in the upper-left corner?

 */

public static final int DEBUG_FPS = 1;

//////////// END DEBUG FLAGS /////////////////////////////////////////

/**

 * Do not create DEPTH or STENCIL attachment

 */

  public static final int NO_DEPTH_NO_STENCIL = 0;

/**

 * Create DEPTH, but not STENCIL

 */

  public static final int DEPTH_NO_STENCIL    = 1;

/**

 * Create both DEPTH and STENCIL

 */

  public static final int BOTH_DEPTH_STENCIL  = 2;

  private static final int ATTACH = 0;

  private static final int DETACH = 1;

  private static final int DETALL = 2;

  private static final int SORT   = 3;

  private ArrayList<DistortedNode> mChildren;

  private int mNumChildren;   // ==mChildren.length(), but we only create mChildren if the first one gets added

  private class Job

    {

    int type;

    DistortedNode node;

    Job(int t, DistortedNode n)

      {

      type = t;

      node = n;

      }

    }

  private ArrayList<Job> mJobs = new ArrayList<>();

  DistortedOutputSurface[] mBuffer;

  private long mTime;

  private float mFOV;

  float mDistance, mNear;

  float[] mProjectionMatrix;

  int mDepthStencilCreated;

  int mDepthStencil;

  int[] mDepthStencilH = new int[1];

  int[] mFBOH          = new int[1];

  private float mClearR, mClearG, mClearB, mClearA;

  private float mClearDepth;

  private int mClearStencil;

  private int mClear;

  float mMipmap;

  private int mDebugLevel;

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

  // section dealing with Shader Storage Buffer Object (for counting transparency)

  private static final int BUFFERING = 3;

  private static int mBufferSize     =10;

  private static DistortedObjectCounter mSurfaceCounter = new DistortedObjectCounter();

  private static int[] mSSBO = new int[1];

  private static IntBuffer mIntBuffer;

  static

    {

    mSSBO[0]= -1;

    }

  private int mSurfaceID;

  private int mLastIndex;

  // end section

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

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

  abstract void prepareDebug(long time);

  abstract void renderDebug(long time);

  abstract void createSurface();

  abstract void deleteSurface();

  abstract void recreateSurface();

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

  DistortedOutputSurface(int width, int height, int createColor, int numcolors, int depthStencil, int fbo, int type)

    {

    super(width,height,createColor,numcolors,type);

    mProjectionMatrix = new float[16];

    mFOV = 60.0f;

    mNear=  0.5f;

    mDepthStencilCreated= (depthStencil== NO_DEPTH_NO_STENCIL ? DONT_CREATE:NOT_CREATED_YET);

    mDepthStencil = depthStencil;

    mFBOH[0]         = fbo;

    mDepthStencilH[0]= 0;

    mTime = 0;

    mDebugLevel = 0;

    mClearR = 0.0f;

    mClearG = 0.0f;

    mClearB = 0.0f;

    mClearA = 0.0f;

    mClearDepth = 1.0f;

    mClearStencil = 0;

    mClear = GLES31.GL_DEPTH_BUFFER_BIT | GLES31.GL_COLOR_BUFFER_BIT;

    mBuffer = new DistortedOutputSurface[1+EffectQuality.LENGTH];

    mMipmap = 1.0f;

    createProjection();

    }

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

// Must be called from a thread holding OpenGL Context

  void create()

    {

    if( mSSBO[0]<0 )

      {

      GLES31.glGenBuffers(1,mSSBO,0);

      // here bind the new SSBO and map it

      GLES31.glBindBuffer(GLES31.GL_SHADER_STORAGE_BUFFER, mSSBO[0]);

      GLES31.glBufferData(GLES31.GL_SHADER_STORAGE_BUFFER, BUFFERING*mBufferSize*4 , null, GLES31.GL_DYNAMIC_READ);

      ByteBuffer buf = (ByteBuffer) GLES31.glMapBufferRange(GLES31.GL_SHADER_STORAGE_BUFFER, 0, BUFFERING*mBufferSize*4, GLES31.GL_MAP_READ_BIT );

      mIntBuffer = buf.order(ByteOrder.nativeOrder()).asIntBuffer();

      GLES31.glBindBufferBase(GLES31.GL_SHADER_STORAGE_BUFFER,0, mSSBO[0]);

      }

    mSurfaceID = mSurfaceCounter.returnNext();

    if( mSurfaceID>=mBufferSize )

      {

      // increase the size of mSSBOBuffer, copy over old values, remap.

      // TODO (don't need this if there are never more than mBufferSize=10 Surfaces)

      }

    createSurface();

    }

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

// Must be called from a thread holding OpenGL Context

  void delete()

    {

    mSurfaceCounter.release(mSurfaceID);

    deleteSurface();

    }

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

  void recreate()

    {

    mSSBO[0] = -1;

    mSurfaceCounter.releaseAll();

    recreateSurface();

    }

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

  int resetNewCounter()

    {

    //mIntBuffer.put(BUFFERING*mSurfaceID+mLastIndex,0);

    return BUFFERING*mSurfaceID + mLastIndex;

    }

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

  int returnOldCounter()

    {

    int ret = mIntBuffer.get(BUFFERING*mSurfaceID+mLastIndex);

    mLastIndex++;

    if( mLastIndex>=BUFFERING ) mLastIndex-=BUFFERING;

    return ret;

    }

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

  int returnCounter()

    {

    return mIntBuffer.get(0);

    }

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

  private void createProjection()

    {

    if( mWidth>0 && mHeight>1 )

      {

      if( mFOV>0.0f )  // perspective projection

        {

        float a = 2.0f*(float)Math.tan(mFOV*Math.PI/360);

        float q = mWidth*mNear;

        float c = mHeight*mNear;

        float left   = -q/2;

        float right  = +q/2;

        float bottom = -c/2;

        float top    = +c/2;

        float near   =  c/a;

        mDistance    = mHeight/a;

        float far    = 2*mDistance-near;

        Matrix.frustumM(mProjectionMatrix, 0, left, right, bottom, top, near, far);

        }

      else             // parallel projection

        {

        float left   = -mWidth/2.0f;

        float right  = +mWidth/2.0f;

        float bottom = -mHeight/2.0f;

        float top    = +mHeight/2.0f;

        float near   = mWidth+mHeight-mHeight*(1.0f-mNear);

        mDistance    = mWidth+mHeight;

        float far    = mWidth+mHeight+mHeight*(1.0f-mNear);

        Matrix.orthoM(mProjectionMatrix, 0, left, right, bottom, top, near, far);

        }

      }

    }

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

  private void createBuffers()

    {

    float mipmap=1.0f;

    for(int j=0; j<EffectQuality.LENGTH; j++)

      {

      mBuffer[j] = new DistortedFramebuffer(2,BOTH_DEPTH_STENCIL,TYPE_SYST, (int)(mWidth*mipmap), (int)(mHeight*mipmap) );

      mBuffer[j].mMipmap = mipmap;

      mBuffer[j].mNear   = mNear;  // copy mNear as well (for blitting- see PostprocessEffect.apply() )

      mBuffer[j].glClearColor(1.0f,1.0f,1.0f,0.0f);

      mipmap *= EffectQuality.MULTIPLIER;

      }

    mBuffer[EffectQuality.LENGTH] = this;

    DistortedObject.toDo(); // create the FBOs immediately. This is safe as we must be holding the OpenGL context now.

    GLES31.glStencilMask(0xff);

    GLES31.glDepthMask(true);

    GLES31.glColorMask(true,true,true,true);

    GLES31.glClearColor(0.0f,0.0f,0.0f,0.0f);

    GLES31.glClearDepthf(1.0f);

    GLES31.glClearStencil(0);

    for(int j=0; j<EffectQuality.LENGTH; j++)

      {

      mBuffer[j].setAsOutput();

      GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, mBuffer[j].mColorH[1], 0);

      GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT|GLES31.GL_DEPTH_BUFFER_BIT|GLES31.GL_STENCIL_BUFFER_BIT);

      GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, mBuffer[j].mColorH[0], 0);

      GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT);

      }

    }

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

  private int blitWithDepth(long currTime, DistortedOutputSurface buffer)

    {

    GLES31.glViewport(0, 0, mWidth, mHeight);

    setAsOutput(currTime);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE0);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, buffer.mColorH[0]);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, buffer.mDepthStencilH[0]);

    GLES31.glDisable(GLES31.GL_STENCIL_TEST);

    GLES31.glStencilMask(0x00);

    DistortedEffects.blitDepthPriv(this);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE0);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, 0);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, 0);

    // clear buffers

    GLES31.glStencilMask(0xff);

    GLES31.glDepthMask(true);

    GLES31.glColorMask(true,true,true,true);

    GLES31.glClearColor(0.0f,0.0f,0.0f,0.0f);

    GLES31.glClearDepthf(1.0f);

    GLES31.glClearStencil(0);

    buffer.setAsOutput();

    GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, buffer.mColorH[1], 0);

    GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT|GLES31.GL_DEPTH_BUFFER_BIT|GLES31.GL_STENCIL_BUFFER_BIT);

    GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, buffer.mColorH[0], 0);

    GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT);

    return 1;

    }

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

// Render all children, one by one. If there are no postprocessing effects, just render to THIS.

// Otherwise, render to a buffer and on each change of Postprocessing Bucket, apply the postprocessing

// to a whole buffer and merge it.

  int renderChildren(long time, int numChildren, ArrayList<DistortedNode> children)

    {

    int quality=0, internalQuality = 0, numRenders = 0, bucketChange = 0;

    DistortedNode child1, child2;

    EffectQueuePostprocess lastQueue=null, currQueue;

    long lastBucket=0, currBucket;

    for(int i=0; i<numChildren; i++)

      {

      child1 = children.get(i);

      currQueue = child1.getPostprocessQueue();

      currBucket= currQueue.getID();

      if( currBucket==0 ) numRenders += child1.draw(time,this);

      else

        {

        if( mBuffer[0]==null ) createBuffers();

        if( lastBucket!=currBucket )

          {

          if( lastBucket!=0 )

            {

            for(int j=bucketChange; j<i; j++)

              {

              child2 = children.get(j);

              numRenders += child2.markStencilAndDepth(time,mBuffer[internalQuality],lastQueue);

              }

            numRenders += lastQueue.postprocess(this);

            numRenders += blitWithDepth(time, mBuffer[quality]);

            }

          internalQuality = currQueue.getInternalQuality();

          quality         = currQueue.getQuality();

          bucketChange    = i;

          }

        child1.draw(time,mBuffer[quality]);

        //numRenders += currQueue.draw(child1,time,mBuffer);

        if( i==numChildren-1 )

          {

          for(int j=bucketChange; j<numChildren; j++)

            {

            child2 = children.get(j);

            numRenders += child2.markStencilAndDepth(time,mBuffer[internalQuality],currQueue);

            }

          numRenders += currQueue.postprocess(this);

          numRenders += blitWithDepth(time, mBuffer[quality]);

          }

        }

      lastQueue = currQueue;

      lastBucket= currBucket;

      }

    return numRenders;

    }

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

  ArrayList<DistortedNode> getChildren()

    {

    return mChildren;

    }

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

// PUBLIC API

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

/**

 * Make the library show various debugging information.

 * <p>

 * Currently only DEBUG_FPS - show FPS in the upper-left corner of every Screen - is defined.

 *

 * @param bitmask 0, or a bitmask of DEBUG_** flags to enable (currently only DEBUG_FPS defined)

 */

  public void setDebug(int bitmask)

    {

    if( this instanceof DistortedScreen )

      mDebugLevel = bitmask;

    }

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

/**

 * Draws all the attached children to this OutputSurface.

 * <p>

 * Must be called from a thread holding OpenGL Context.

 *

 * @param time Current time, in milliseconds. This will be passed to all the Effects stored in the children Nodes.

 * @return Number of objects rendered.

 */

  public int render(long time)

    {

    if( mDebugLevel!=0 ) prepareDebug(time);

    // change tree topology (attach and detach children)

/*

    boolean changed1 =

*/

    DistortedMaster.toDo();

/*

    if( changed1 )

      {

      for(int i=0; i<mNumChildren; i++)

        {

        mChildren.get(i).debug(0);

        }

      DistortedNode.debugMap();

      }

*/

    // create and delete all underlying OpenGL resources

    // Watch out: FIRST change topology, only then deal

    // with OpenGL resources. That's because changing Tree

    // can result in additional Framebuffers that would need

    // to be created immediately, before the calls to drawRecursive()

/*

    boolean changed2 =

*/

    toDo();

/*

    if( changed2 )

      {

      DistortedObject.debugLists();

      }

*/

    // mark OpenGL state as unknown

    DistortedRenderState.reset();

    int numRenders=0;

    for(int i=0; i<mNumChildren; i++)

      {

      numRenders += mChildren.get(i).renderRecursive(time);

      }

    setAsOutput(time);

    numRenders += renderChildren(time,mNumChildren,mChildren);

    if( mDebugLevel != 0 ) renderDebug(time);

    return numRenders;

    }

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

/**

 * Bind this Surface as a Framebuffer we can render to.

 *

 * @param time Present time, in milliseconds. The point: looking at this param the library can figure

 *             out if this is the first time during present frame that this FBO is being set as output.

 *             If so, the library, in addition to binding the Surface for output, also clears the

 *             Surface's color and depth attachments.

 */

  public void setAsOutput(long time)

    {

    GLES31.glBindFramebuffer(GLES31.GL_FRAMEBUFFER, mFBOH[0]);

    if( mTime!=time )

      {

      mTime = time;

      DistortedRenderState.colorDepthStencilOn();

      GLES31.glClearColor(mClearR, mClearG, mClearB, mClearA);

      GLES31.glClearDepthf(mClearDepth);

      GLES31.glClearStencil(mClearStencil);

      GLES31.glClear(mClear);

      DistortedRenderState.colorDepthStencilRestore();

      }

    }

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

/**

 * Bind this Surface as a Framebuffer we can render to.

 * <p>

 * This version does not attempt to clear anything.

 */

  public void setAsOutput()

    {

    GLES31.glBindFramebuffer(GLES31.GL_FRAMEBUFFER, mFBOH[0]);

    }

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

/**

 * Return the Near plane of the Projection included in the Surface.

 *

 * @return the Near plane.

 */

  public float getNear()

    {

    return mNear;

    }

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

/**

 * Set mipmap level.

 * <p>

 * Trick for speeding up your renders - one can create a pyramid of OutputSurface objects, each next

 * one some constant FACTOR smaller than the previous (0.5 is the common value), then set the Mipmap

 * Level of the i-th object to be FACTOR^i (we start counting from 0). When rendering any scene into

 * such prepared OutputSurface, the library will make sure to scale any Effects used so that the end

 * scene will end up looking identical no matter which object we render to. Identical, that is, except

 * for the loss of quality and gain in speed associated with rendering to a smaller Surface.

 * <p>

 * Example: if you create two FBOs, one 1000x1000 and another 500x500 in size, and set the second one

 * mipmap to 0.5 (the first one's is 1.0 by default), define Effects to be a single move by (100,100),

 * and render a skinned Mesh into both FBO, the end result will look proportionally the same, because

 * in the second case the move vector (100,100) will be auto-scaled to (50,50).

 *

 * @param mipmap The mipmap level. Acceptable range: 0<mipmap<infinity, although mipmap>1

 *               does not make any sense (that would result in loss of speed and no gain in quality)

 */

  public void setMipmap(float mipmap)

    {

    mMipmap = mipmap;

    }

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

/**

 * Set the (R,G,B,A) values of GLES31.glClearColor() to set up color with which to clear

 * this Surface at the beginning of each frame.

 *

 * @param r the Red component. Default: 0.0f

 * @param g the Green component. Default: 0.0f

 * @param b the Blue component. Default: 0.0f

 * @param a the Alpha component. Default: 0.0f

 */

  public void glClearColor(float r, float g, float b, float a)

    {

    mClearR = r;

    mClearG = g;

    mClearB = b;

    mClearA = a;

    }

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

/**

 * Uses glClearDepthf() to set up a value with which to clear

 * the Depth buffer of our Surface at the beginning of each frame.

 *

 * @param d the Depth. Default: 1.0f

 */

  public void glClearDepthf(float d)

    {

    mClearDepth = d;

    }

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

/**

 * Uses glClearStencil() to set up a value with which to clear the

 * Stencil buffer of our Surface at the beginning of each frame.

 *

 * @param s the Stencil. Default: 0

 */

  public void glClearStencil(int s)

    {

    mClearStencil = s;

    }

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

/**

 * Which buffers to Clear at the beginning of each frame?

 * <p>

 * Valid values: 0, or bitwise OR of one or more values from the set GL_COLOR_BUFFER_BIT,

 *               GL_DEPTH_BUFFER_BIT, GL_STENCIL_BUFFER_BIT.

 * Default: GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT.

 *

 * @param mask bitwise OR of BUFFER_BITs to clear.

 */

  public void glClear(int mask)

    {

    mClear = mask;

    }

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

/**

 * Create new Projection matrix.

 *

 * @param fov Vertical 'field of view' of the Projection frustrum (in degrees).

 *            Valid values: 0<=fov<180. FOV==0 means 'parallel projection'.

 * @param near Distance between the screen plane and the near plane.

 *             Valid vaules: 0<near<1. When near==0, the Near Plane is exactly at the tip of the

 *             pyramid. When near==1 (illegal!) the near plane is equivalent to the screen plane.

 */

  public void setProjection(float fov, float near)

    {

    if( fov < 180.0f && fov >=0.0f )

      {

      mFOV = fov;

      }

    if( near<   1.0f && near> 0.0f )

      {

      mNear= near;

      }

    else if( near<=0.0f )

      {

      mNear = 0.01f;

      }

    else if( near>=1.0f )

      {

      mNear=0.99f;

      }

    if( mBuffer[0]!=null )

      {

      for(int j=0; j<EffectQuality.LENGTH; j++) mBuffer[j].mNear = mNear;

      }

    createProjection();

    }

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

/**

 * Resize the underlying Framebuffer.

 * <p>

 * This method can be safely called mid-render as it doesn't interfere with rendering.

 *

 * @param width The new width.

 * @param height The new height.

 */

  public void resize(int width, int height)

    {

    if( mWidth!=width || mHeight!=height )

      {

      mWidth = width;

      mHeight= height;

      createProjection();

      if( mColorCreated==CREATED )

        {

        markForCreation();

        recreate();

        }

      }

    }

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

/**

 * Return true if the Surface contains a DEPTH attachment.

 *

 * @return <bold>true</bold> if the Surface contains a DEPTH attachment.

 */

  public boolean hasDepth()

    {

    return mDepthStencilCreated==CREATED;

    }

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

/**

 * Return true if the Surface contains a STENCIL attachment.

 *

 * @return <bold>true</bold> if the Surface contains a STENCIL attachment.

 */

  public boolean hasStencil()

    {

    return (mDepthStencilCreated==CREATED && mDepthStencil==BOTH_DEPTH_STENCIL);

    }

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

/**

 * Adds a new child to the last position in the list of our Surface's children.

 * <p>

 * We cannot do this mid-render - actual attachment will be done just before the next render, by the

 * DistortedMaster (by calling doWork())

 *

 * @param node The new Node to add.

 */

  public void attach(DistortedNode node)

    {

    mJobs.add(new Job(ATTACH,node));

    DistortedMaster.newSlave(this);

    }

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

/**

 * Adds a new child to the last position in the list of our Surface's children.

 * <p>

 * We cannot do this mid-render - actual attachment will be done just before the next render, by the

 * DistortedMaster (by calling doWork())

 *

 * @param surface InputSurface to initialize our child Node with.

 * @param effects DistortedEffects to initialize our child Node with.

 * @param mesh MeshObject to initialize our child Node with.

 * @return the newly constructed child Node, or null if we couldn't allocate resources.

 */

  public DistortedNode attach(DistortedInputSurface surface, DistortedEffects effects, MeshObject mesh)

    {

    DistortedNode node = new DistortedNode(surface,effects,mesh);

    mJobs.add(new Job(ATTACH,node));

    DistortedMaster.newSlave(this);

    return node;

    }

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

/**

 * Removes the first occurrence of a specified child from the list of children of our Surface.

 * <p>

 * A bit questionable method as there can be many different Nodes attached as children, some

 * of them having the same Effects but - for instance - different Mesh. Use with care.

 * <p>

 * We cannot do this mid-render - actual detachment will be done just before the next render, by the

 * DistortedMaster (by calling doWork())

 *

 * @param effects DistortedEffects to remove.

 */

  public void detach(DistortedEffects effects)

    {

    long id = effects.getID();

    DistortedNode node;

    boolean detached = false;

    for(int i=0; i<mNumChildren; i++)

      {

      node = mChildren.get(i);

      if( node.getEffects().getID()==id )

        {

        detached = true;

        mJobs.add(new Job(DETACH,node));

        DistortedMaster.newSlave(this);

        break;

        }

      }

    if( !detached )

      {

      // if we failed to detach any, it still might be the case that

      // there's an ATTACH job that we need to cancel.

      int num = mJobs.size();

      Job job;

      for(int i=0; i<num; i++)

        {

        job = mJobs.get(i);

        if( job.type==ATTACH && job.node.getEffects()==effects )

          {

          mJobs.remove(i);

          break;

          }

        }

      }

    }

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

/**

 * Removes the first occurrence of a specified child from the list of children of our Surface.

 * <p>

 * We cannot do this mid-render - actual attachment will be done just before the next render, by the

 * DistortedMaster (by calling doWork())

 *

 * @param node The Node to remove.

 */

  public void detach(DistortedNode node)

    {

    mJobs.add(new Job(DETACH,node));

    DistortedMaster.newSlave(this);

    }

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

/**

 * Removes all children Nodes.

 * <p>

 * We cannot do this mid-render - actual attachment will be done just before the next render, by the

 * DistortedMaster (by calling doWork())

 */

  public void detachAll()

    {

    mJobs.add(new Job(DETALL,null));

    DistortedMaster.newSlave(this);

    }

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

/**

 * This is not really part of the public API. Has to be public only because it is a part of the

 * DistortedSlave interface, which should really be a class that we extend here instead but

 * Java has no multiple inheritance.

 *

 * @y.exclude

 */

  public void doWork()

    {

    int num = mJobs.size();

    Job job;

    for(int i=0; i<num; i++)

      {

      job = mJobs.remove(0);

      switch(job.type)

        {

        case ATTACH: if( mChildren==null ) mChildren = new ArrayList<>(2);

                     job.node.setSurfaceParent(this);

                     DistortedMaster.addSorted(mChildren,job.node);

                     mNumChildren++;

                     break;

        case DETACH: if( mNumChildren>0 && mChildren.remove(job.node) )

                       {

                       job.node.setSurfaceParent(null);

                       mNumChildren--;

                       }

                     break;

        case DETALL: if( mNumChildren>0 )

                       {

                       DistortedNode tmp;

                       for(int j=mNumChildren-1; j>=0; j--)

                         {

                         tmp = mChildren.remove(j);

                         tmp.setSurfaceParent(null);

                         }

                       mNumChildren = 0;

                       }

                     break;

        case SORT  : mChildren.remove(job.node);

                     DistortedMaster.addSorted(mChildren,job.node);

                     break;

        }

      }

    }

}