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 org.distorted.library.effectqueue.EffectQueuePostprocess;

import org.distorted.library.mesh.MeshBase;

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

/**

 * This is not really part of the public API.

 *

 * @y.exclude

 */

public abstract class InternalOutputSurface extends InternalSurface implements InternalChildrenList.Parent

{

  public static final int NO_DEPTH_NO_STENCIL = 0;

  public static final int DEPTH_NO_STENCIL    = 1;

  public static final int BOTH_DEPTH_STENCIL  = 2;

  float mFOV, mDistance, mNear, mMipmap;

  float[] mProjectionMatrix;

  int mDepthStencilCreated, mDepthStencil;

  int[] mDepthStencilH, mFBOH;

  int mRealWidth;   // the Surface can be backed up by a texture larger than the viewport we have to it.

  int mRealHeight;  // mWidth,mHeight are the sizes of the Viewport, those - sizes of the backing up texture.

  int mCurrFBO;     // internal current FBO (see DistortedLibrary.FBO_QUEUE_SIZE)

  int mWidth, mHeight;

  private static DistortedFramebuffer[] mBuffer=null; // Global buffers used for postprocessing.

  private long[] mTime;

  private float mClearR, mClearG, mClearB, mClearA, mClearDepth;

  private int mClear, mClearStencil;

  private boolean mRenderWayOIT;

  private InternalChildrenList mChildren;

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

  InternalOutputSurface(int width, int height, int createColor, int numfbos, int numcolors, int depthStencil, int fbo, int type)

    {

    super(createColor,numfbos,numcolors,type);

    mRenderWayOIT = false;

    mCurrFBO      = 0;

    mDepthStencilH = new int[numfbos];

    mFBOH          = new int[numfbos];

    mTime = new long[numfbos];

    for(int i=0; i<mNumFBOs;i++) mTime[i]=0;

    mRealWidth = mWidth = width;

    mRealHeight= mHeight= height;

    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;

    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;

    mMipmap = 1.0f;

    mChildren = new InternalChildrenList(this);

    createProjection();

    }

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

  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 static void createPostprocessingBuffers(int width, int height, float near)

    {

    final float CLEAR_R = 1.0f;

    final float CLEAR_G = 1.0f;

    final float CLEAR_B = 1.0f;

    final float CLEAR_A = 0.0f;

    final float CLEAR_D = 1.0f;

    final int   CLEAR_S = 0;

    mBuffer = new DistortedFramebuffer[EffectQuality.LENGTH];

    float mipmap=1.0f;

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

      {

      mBuffer[j] = new DistortedFramebuffer(DistortedLibrary.FBO_QUEUE_SIZE,2,BOTH_DEPTH_STENCIL,TYPE_SYST, (int)(width*mipmap), (int)(height*mipmap) );

      mBuffer[j].mMipmap = mipmap;

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

      mBuffer[j].glClearColor(CLEAR_R, CLEAR_G, CLEAR_B, CLEAR_A);

      mipmap *= EffectQuality.MULTIPLIER;

      }

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

    InternalRenderState.colorDepthStencilOn();

    GLES31.glClearColor(CLEAR_R, CLEAR_G, CLEAR_B, CLEAR_A);

    GLES31.glClearDepthf(CLEAR_D);

    GLES31.glClearStencil(CLEAR_S);

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

      {

      for(int k = 0; k< DistortedLibrary.FBO_QUEUE_SIZE; k++)

        {

        GLES31.glBindFramebuffer(GLES31.GL_FRAMEBUFFER, mBuffer[j].mFBOH[k]);

        GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, mBuffer[j].mColorH[2*k+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[2*k  ], 0);

        GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT);

        }

      }

    InternalRenderState.colorDepthStencilRestore();

    GLES31.glBindFramebuffer(GLES31.GL_FRAMEBUFFER, 0);

    }

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

  static synchronized void onDestroy()

    {

    if( mBuffer!=null )

      {

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

        {

        mBuffer[j] = null;

        }

      mBuffer = null;

      }

    }

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

// The postprocessing buffers mBuffer[] are generally speaking too large (there's just one static

// set of them) so before we use them for output, we need to adjust the Viewport as if they were

// smaller. That takes care of outputting pixels to them. When we use them as input, we have to

// adjust the texture coords - see the get{Width|Height}Correction functions.

//

// Also, adjust the Buffers so their Projection is the same like the surface we are supposed to be

// rendering to.

  private static void clonePostprocessingViewportAndProjection(InternalOutputSurface from)

    {

    if( mBuffer[0].mWidth != from.mWidth || mBuffer[0].mHeight != from.mHeight ||

        mBuffer[0].mFOV   != from.mFOV   || mBuffer[0].mNear   != from.mNear    )

      {

      InternalOutputSurface surface;

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

        {

        surface = mBuffer[i];

        surface.mWidth  = (int)(from.mWidth *surface.mMipmap);

        surface.mHeight = (int)(from.mHeight*surface.mMipmap);

        surface.mFOV    = from.mFOV;

        surface.mNear   = from.mNear;  // Near plane is independent of the mipmap level

        surface.createProjection();

        int maxw = surface.mWidth  > surface.mRealWidth  ? surface.mWidth  : surface.mRealWidth;

        int maxh = surface.mHeight > surface.mRealHeight ? surface.mHeight : surface.mRealHeight;

        if (maxw > surface.mRealWidth || maxh > surface.mRealHeight)

          {

          surface.mRealWidth = maxw;

          surface.mRealHeight = maxh;

          surface.recreate();

          surface.create();

          }

        }

      }

    }

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

  private int blitWithDepth(long currTime, InternalOutputSurface buffer, int fbo)

    {

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

    setAsOutput(currTime);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE0);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, buffer.mColorH[2*fbo]);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

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

    GLES31.glDisable(GLES31.GL_STENCIL_TEST);

    GLES31.glStencilMask(0x00);

    DistortedLibrary.blitDepthPriv(this, buffer.getWidthCorrection(), buffer.getHeightCorrection() );

    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(buffer.mClearR,buffer.mClearG,buffer.mClearB,buffer.mClearA);

    GLES31.glClearDepthf(buffer.mClearDepth);

    GLES31.glClearStencil(buffer.mClearStencil);

    buffer.setAsOutput();

    GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, buffer.mColorH[2*fbo+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[2*fbo  ], 0);

    GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT);

    return 1;

    }

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

  private static void oitClear(InternalOutputSurface buffer)

    {

    int counter = DistortedLibrary.zeroOutAtomic();

    DistortedLibrary.oitClear(buffer,counter);

    GLES31.glMemoryBarrier(GLES31.GL_SHADER_STORAGE_BARRIER_BIT|GLES31.GL_ATOMIC_COUNTER_BARRIER_BIT);

    }

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

  private int oitBuild(long time, InternalOutputSurface buffer, int fbo)

    {

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

    setAsOutput(time);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE0);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, buffer.mColorH[2*fbo]);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

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

    InternalRenderState.colorDepthStencilOn();

    InternalRenderState.enableDepthTest();

    DistortedLibrary.oitBuild(this, buffer.getWidthCorrection(), buffer.getHeightCorrection() );

    GLES31.glActiveTexture(GLES31.GL_TEXTURE0);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, 0);

    GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

    GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, 0);

    InternalRenderState.colorDepthStencilRestore();

    InternalRenderState.restoreDepthTest();

    return 1;

    }

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

// two phases: 1. collapse the SSBO 2. blend the ssbo's color

  private int oitRender(long currTime, int fbo)

    {

    float corrW = getWidthCorrection();

    float corrH = getHeightCorrection();

    // Do the Collapse Pass only if we do have a Depth attachment.

    // Otherwise there's no point (in fact we then would create a feedback loop!)

    if( mDepthStencilH[fbo] != 0 )

      {

      GLES31.glBindFramebuffer(GLES31.GL_FRAMEBUFFER, 0);

      GLES31.glActiveTexture(GLES31.GL_TEXTURE1);

      GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, mDepthStencilH[fbo]);

      InternalRenderState.switchOffColorDepthStencil();

      DistortedLibrary.oitCollapse(this, corrW, corrH);

      GLES31.glBindTexture(GLES31.GL_TEXTURE_2D, 0);

      }

    setAsOutput(currTime);

    InternalRenderState.switchColorDepthOnStencilOff();

    DistortedLibrary.oitRender(this, corrW, corrH);

    InternalRenderState.restoreColorDepthStencil();

    return 1;

    }

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

  private void clear()

    {

    InternalRenderState.colorDepthStencilOn();

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

    GLES31.glClearDepthf(mClearDepth);

    GLES31.glClearStencil(mClearStencil);

    GLES31.glClear(mClear);

    InternalRenderState.colorDepthStencilRestore();

    }

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

  void setCurrFBO(int fbo)

    {

    mCurrFBO = fbo;

    }

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

// 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 (lastQueue.postprocess) and merge it (this.oitBuild or blitWithDepth - depending

// on the type of rendering)

  int renderChildren(long time, int numChildren, InternalChildrenList children, int fbo, boolean oit)

    {

    int numRenders=0, bucketChange=0;

    DistortedNode child;

    DistortedFramebuffer buffer=null;

    EffectQueuePostprocess lastQueue=null, currQueue;

    long lastBucket=0, currBucket;

    boolean renderDirectly=false;

    setCurrFBO(fbo);

    if( mBuffer!=null )

      {

      for (int i=0; i<EffectQuality.LENGTH; i++) mBuffer[i].setCurrFBO(fbo);

      }

    if( oit && numChildren>0 )

      {

      oitClear(this);

      }

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

      {

      child = children.getChild(i);

      currQueue = (EffectQueuePostprocess)child.getEffects().getQueues()[3];

      currBucket= currQueue.getID();

      if( currBucket==0 )

        {

        setAsOutput(time);

        if( oit )

          {

          numRenders += child.drawOIT(time, this);

          GLES31.glMemoryBarrier(GLES31.GL_SHADER_STORAGE_BARRIER_BIT | GLES31.GL_ATOMIC_COUNTER_BARRIER_BIT);

          }

        else

          {

          numRenders += child.draw(time, this);

          }

        }

      else

        {

        if( mBuffer==null )

          {

          createPostprocessingBuffers(mWidth,mHeight,mNear);

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

          }

        if( lastBucket!=currBucket )

          {

          if( lastBucket==0 )

            {

            clonePostprocessingViewportAndProjection(this);

            }

          else

            {

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

              {

              DistortedNode node = children.getChild(j);

              if( node.getSurface().setAsInput() )

                {

                buffer.setAsOutput();

                numRenders += lastQueue.preprocess( buffer, node, buffer.mDistance, buffer.mMipmap, buffer.mProjectionMatrix );

                }

              }

            numRenders += lastQueue.postprocess(buffer);

            if( oit )

              {

              numRenders += oitBuild(time, buffer, fbo);

              GLES31.glMemoryBarrier(GLES31.GL_SHADER_STORAGE_BARRIER_BIT | GLES31.GL_ATOMIC_COUNTER_BARRIER_BIT);

              }

            else

              {

              numRenders += blitWithDepth(time, buffer, fbo);

              }

            buffer.clearBuffer(fbo);

            }

          buffer= mBuffer[currQueue.getQuality()];

          bucketChange= i;

          renderDirectly = currQueue.getRender();

          }

        if( renderDirectly )

          {

          setAsOutput(time);

          if( oit )

            {

            numRenders += child.drawOIT(time, this);

            GLES31.glMemoryBarrier(GLES31.GL_SHADER_STORAGE_BARRIER_BIT | GLES31.GL_ATOMIC_COUNTER_BARRIER_BIT);

            }

          else

            {

            numRenders += child.draw(time, this);

            }

          }

        else

          {

          buffer.setAsOutput(time);

          child.drawNoBlend(time, buffer);

          }

        if( i==numChildren-1 )

          {

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

            {

            DistortedNode node = children.getChild(j);

            if( node.getSurface().setAsInput() )

              {

              buffer.setAsOutput();

              numRenders += currQueue.preprocess( buffer, node, buffer.mDistance, buffer.mMipmap, buffer.mProjectionMatrix );

              }

            }

          numRenders += currQueue.postprocess(buffer);

          if( oit )

            {

            numRenders += oitBuild(time, buffer, fbo);

            GLES31.glMemoryBarrier(GLES31.GL_SHADER_STORAGE_BARRIER_BIT | GLES31.GL_ATOMIC_COUNTER_BARRIER_BIT);

            buffer.clearBuffer(fbo);

            }

          else

            {

            numRenders += blitWithDepth(time, buffer,fbo);

            }

          }

        } // end else (postprocessed child)

      lastQueue = currQueue;

      lastBucket= currBucket;

      } // end main for loop

    if( oit && numChildren>0 )

      {

      numRenders += oitRender(time, fbo);  // merge the OIT linked list

      }

    return numRenders;

    }

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

/**

 * Not part of the public API.

 *

 * @y.exclude

 */

  public void adjustIsomorphism() { }

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

/**

 * Not part of the Public API.

 *

 * @y.exclude

 */

  public float getWidthCorrection()

    {

    return (float)mWidth/mRealWidth;

    }

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

/**

 * Not part of the Public API.

 *

 * @y.exclude

 */

  public float getHeightCorrection()

    {

    return (float)mHeight/mRealHeight;

    }

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

  void clearBuffer(int fbo)

    {

    InternalRenderState.colorDepthStencilOn();

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

    GLES31.glClearDepthf(mClearDepth);

    GLES31.glClearStencil(mClearStencil);

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

    GLES31.glFramebufferTexture2D(GLES31.GL_FRAMEBUFFER, GLES31.GL_COLOR_ATTACHMENT0, GLES31.GL_TEXTURE_2D, mColorH[2*fbo+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, mColorH[2*fbo  ], 0);

    GLES31.glClear(GLES31.GL_COLOR_BUFFER_BIT);

    InternalRenderState.colorDepthStencilRestore();

    }

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

  void setAsOutput(long time)

    {

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

    if( mTime[mCurrFBO]!=time )

      {

      mTime[mCurrFBO] = time;

      clear();

      }

    }

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

// PUBLIC API

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

/**

 * Draws all the attached children to this OutputSurface's 0th FBO.

 * <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)

    {

    return render(time,0);

    }

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

/**

 * 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.

 * @param fbo The surface can have many FBOs backing it up - render this to FBO number 'fbo'.

 * @return Number of objects rendered.

 */

  public int render(long time, int fbo)

    {

    InternalMaster.toDo();

    toDo();

    InternalRenderState.reset();

    int numRenders=0, numChildren = mChildren.getNumChildren();

    DistortedNode node;

    long oldBucket=0, newBucket;

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

      {

      node = mChildren.getChild(i);

      newBucket = node.getBucket();

      numRenders += node.renderRecursive(time);

      if( newBucket<oldBucket ) mChildren.rearrangeByBuckets(i,newBucket);

      else oldBucket=newBucket;

      }

    numRenders += renderChildren(time,numChildren,mChildren,fbo, mRenderWayOIT);

    return numRenders;

    }

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

/**

 * 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[mCurrFBO]);

    }

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

/**

 * 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 (illegal!), 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!=null )

      {

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

      }

    createProjection();

    }

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

/**

 * Return the vertical field of view angle.

 *

 * @return Vertival Field of View Angle, in degrees.

 */

  public float getFOV()

    {

    return mFOV;

    }

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

/**

 * 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 = mRealWidth = width;

      mHeight= mRealHeight= 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);

    }

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

/**

 * When rendering this Node, should we use the Order Independent Transparency render mode?

 * <p>

 * There are two modes of rendering: the fast 'normal' way, which however renders transparent

 * fragments in different ways depending on which fragments get rendered first, or the slower

 * 'oit' way, which renders transparent fragments correctly regardless of their order.

 *

 * @param oit True if we want to render more slowly, but in a way which accounts for transparency.

 */

  public void setOrderIndependentTransparency(boolean oit)

    {

    mRenderWayOIT = oit;

    }

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

/**

 * When rendering this Node, should we use the Order Independent Transparency render mode?

 * <p>

 * There are two modes of rendering: the fast 'normal' way, which however renders transparent

 * fragments in different ways depending on which fragments get rendered first, or the slower

 * 'oit' way, which renders transparent fragments correctly regardless of their order.

 *

 * @param oit True if we want to render more slowly, but in a way which accounts for transparency.

 * @param initialSize Initial number of transparent fragments we expect, in screenfuls.

 *                    I.e '1.0' means 'the scene we are going to render contains dialog_about 1 screen

 *                    worth of transparent fragments'. Valid values: 0.0 < initialSize < 10.0

 *                    Even if you get this wrong, the library will detect that there are more

 *                    transparent fragments than it has space for and readjust its internal buffers,

 *                    but only after a few frames during which one will probably see missing objects.

 */

public void setOrderIndependentTransparency(boolean oit, float initialSize)

  {

  mRenderWayOIT = oit;

  if( initialSize>0.0f && initialSize<10.0f )

    DistortedLibrary.setSSBOSize(initialSize);

  }

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

/**

 * 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

 * InternalMaster (by calling doWork())

 *

 * @param node The new Node to add.

 */

  public void attach(DistortedNode node)

    {

    mChildren.attach(node);

    }

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

/**

 * 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

 * InternalMaster (by calling doWork())

 *

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

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

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

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

 */

  public DistortedNode attach(InternalSurface surface, DistortedEffects effects, MeshBase mesh)

    {

    return mChildren.attach(surface,effects,mesh);

    }

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

/**

 * 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

 * InternalMaster (by calling doWork())