How to put sprite on top in AndEngine

Intruduction

    There are no easy ways to put sprite on top of the others in AndEngine. You ether have to manipulate z index or detach/attach sprites to scene to gain what you need. Both methods are performance expensive and ugly.

Solution

    We need a method in Entity which will look something like:

  

public void setOnTop(boolean pOnTop);

The method input is boolean which controls if our sprite is on top.

First of all we need to add the code below to IEntity.java(yes, we shall modify some part of the engine):

public boolean isOnTop();
public void setOnTop(final boolean pOnTop);

Then add implementation of these methods to BaseMenuDecorator.java

@Override
public boolean isOnTop() {
    return false;
}

@Override
public void setOnTop(boolean pOnTop) {

}

Nothing interesting is in here, just a stub.

Next let's come to main part in Entity.java. Override methods you've just created in IEntity.java with something like this:

    @Override
    public boolean isOnTop() {
        return mIsOnTop;
    }

    @Override
    public void setOnTop(boolean pOnTop) {
        mIsOnTop = pOnTop;
    }

mIsOnTop is a variable that holds if an Entity is on top.
Next go to method

void onManagedDraw(final GLState pGLState, final Camera pCamera);

This method is called every time IEntity is being drawn to, well, draw it:). We should check if entityes in draw loops are on top and if so draw them last. That's it. I'm putting here the whole modifyed method so you can compare it with original:

 protected void onManagedDraw(final GLState pGLState, final Camera pCamera) {
  pGLState.pushModelViewGLMatrix();
  {
   this.onApplyTransformations(pGLState);

   final SmartList<IEntity> children = this.mChildren;
   if ((children == null) || !this.mChildrenVisible) {
    /* Draw only self. */
    this.preDraw(pGLState, pCamera);
    this.draw(pGLState, pCamera);
    this.postDraw(pGLState, pCamera);
   } else {
    if (this.mChildrenSortPending) {
     ZIndexSorter.getInstance().sort(this.mChildren);
     this.mChildrenSortPending = false;
    }

    final int childCount = children.size();
    int i = 0;

                List<IEntity> topList = new LinkedList<>();
    { /* Draw children behind this Entity. */
     for (; i < childCount; i++) {
      final IEntity child = children.get(i);
      if (child.getZIndex() < 0) {
                            if (!child.isOnTop()) {
                                child.onDraw(pGLState, pCamera);
                            } else {
                                topList.add(child);
                            }
      } else {
       break;
      }
     }
    }

    /* Draw self. */
    this.preDraw(pGLState, pCamera);
    this.draw(pGLState, pCamera);
    this.postDraw(pGLState, pCamera);

    { /* Draw children in front of this Entity. */
     for (; i < childCount; i++) {
                        final IEntity child = children.get(i);
                        if (!child.isOnTop()) {
                            children.get(i).onDraw(pGLState, pCamera);
                        } else {
                            topList.add(child);
                        }
     }
    }

                { /* Draw top Entityes */
                    for (IEntity child : topList) {
                        child.onDraw(pGLState, pCamera);
                    }
                }
   }
  }
  pGLState.popModelViewGLMatrix();
 }

Nothing special as you can see. Now if you want sprite to became on top just call setOnTop(true).
Thanks for reading and have a good day.

You can find edited files here.

Using shaders in AndEngine

Introduction

    I'd spent quite a lot time trying to  figure out how to use custom shaders in AndEngine. There are a couple of tutorials on the Internet but all of them are incomplete or have some strange solutions like engine onDraw overloading or something like this, so i decided to write this tutorial to collect useful info in one place.

First steps

Luckily  AndEngine has logical and straight architecture and we don't need to walk through the forest of code. It already has ShaderProgram class that can be used as a basis for our shader. In this example i will show how to write simple blink shader using which you can mark sprites in your game for example. So let me show you the whole BlinkShader class and then explain how it works:

package com.syouth.heli.main.shaders;

import android.opengl.GLES20;

import org.andengine.opengl.shader.ShaderProgram;
import org.andengine.opengl.shader.constants.ShaderProgramConstants;
import org.andengine.opengl.shader.exception.ShaderProgramException;
import org.andengine.opengl.shader.exception.ShaderProgramLinkException;
import org.andengine.opengl.util.GLState;
import org.andengine.opengl.vbo.attribute.VertexBufferObjectAttributes;

/**
 * Created by syouth on 25.03.15.
 */
public class BlinkShader extends ShaderProgram {
    public static final String UNIFORM_INTENCITY = "intencity";
    public static final double START_ANGLE = 60.0;

    private static BlinkShader INSTANCE = null;
    private static final float BLINKING_SPEED = 0.09f;
    private static final float MAX_ANGLE = 90;
    private static final float MIN_ANGLE = 0;
    private static final float MIN_INTENCITY = 0.5f;
    private static final float MAX_INTENCITY = 1.5f;
    private static final float mDiv = (float) ((MAX_INTENCITY - MIN_INTENCITY) /
            (Math.cos(Math.toRadians(MIN_ANGLE)) - Math.cos(Math.toRadians(MAX_ANGLE))));
    private static int mModelViewProjectionMatrixLocation = ShaderProgramConstants.LOCATION_INVALID;
    private static int mTexture0Location = ShaderProgramConstants.LOCATION_INVALID;
    private static int mIntencityLocation = ShaderProgramConstants.LOCATION_INVALID;

    private static boolean mBlink = false;
    private static double mCurAngle = 0.0f;
    private static long mPrevTime = 0;
    private static boolean mGrow = true;

    private static final String VERTEXT_SHADER =
            "uniform mat4 " + ShaderProgramConstants.UNIFORM_MODELVIEWPROJECTIONMATRIX + ";\n" +
                    "attribute vec4 " + ShaderProgramConstants.ATTRIBUTE_POSITION + ";\n" +
                    "attribute vec2 " + ShaderProgramConstants.ATTRIBUTE_TEXTURECOORDINATES + ";\n" +
                    "attribute vec4 " + ShaderProgramConstants.ATTRIBUTE_COLOR + ";\n" +
                    "varying vec2 " + ShaderProgramConstants.VARYING_TEXTURECOORDINATES + ";\n" +
                    "varying vec4 " + ShaderProgramConstants.VARYING_COLOR + ";\n" +
                    "void main() {\n" +
                    "   " + ShaderProgramConstants.VARYING_COLOR +
                    " = " + ShaderProgramConstants.ATTRIBUTE_COLOR + ";\n" +
                    "   " + ShaderProgramConstants.VARYING_TEXTURECOORDINATES + " = " +
                    ShaderProgramConstants.ATTRIBUTE_TEXTURECOORDINATES + ";\n" +
                    "   gl_Position = " + ShaderProgramConstants.UNIFORM_MODELVIEWPROJECTIONMATRIX +
                    "*" + ShaderProgramConstants.ATTRIBUTE_POSITION + ";\n" +
                    "}";

    private static final String FRAGMENT_SHADER =
            "precision lowp float;\n" +
                    "uniform float " + UNIFORM_INTENCITY + ";\n" +
                    "uniform sampler2D " + ShaderProgramConstants.UNIFORM_TEXTURE_0 + ";\n" +
                    "varying mediump vec2 " + ShaderProgramConstants.VARYING_TEXTURECOORDINATES + ";\n" +
                    "varying lowp vec4 " + ShaderProgramConstants.VARYING_COLOR + ";\n" +
                    "void main() {\n" +
                    "   vec4 inten = vec4(" + UNIFORM_INTENCITY + ", " +
                    UNIFORM_INTENCITY + ", " +
                    UNIFORM_INTENCITY + ", 1.0);\n" +
                    "   gl_FragColor = inten * " + ShaderProgramConstants.VARYING_COLOR + " * " +
                    "texture2D(" + ShaderProgramConstants.UNIFORM_TEXTURE_0 + ", " + ShaderProgramConstants.VARYING_TEXTURECOORDINATES + ");\n" +
                    "}";
    private BlinkShader() {
        super(VERTEXT_SHADER, FRAGMENT_SHADER);
    }

    public static BlinkShader getInstance() {
        if (INSTANCE == null) {
            INSTANCE = new BlinkShader();
        }

        return INSTANCE;
    }

    @Override
    protected void link(GLState pGLState) throws ShaderProgramLinkException {
        GLES20.glBindAttribLocation(mProgramID,
                ShaderProgramConstants.ATTRIBUTE_POSITION_LOCATION,
                ShaderProgramConstants.ATTRIBUTE_POSITION);
        GLES20.glBindAttribLocation(mProgramID,
                ShaderProgramConstants.ATTRIBUTE_TEXTURECOORDINATES_LOCATION,
                ShaderProgramConstants.ATTRIBUTE_TEXTURECOORDINATES);
        GLES20.glBindAttribLocation(mProgramID,
                ShaderProgramConstants.ATTRIBUTE_COLOR_LOCATION,
                ShaderProgramConstants.ATTRIBUTE_COLOR);
        super.link(pGLState);
        mModelViewProjectionMatrixLocation =
                getUniformLocation(ShaderProgramConstants.UNIFORM_MODELVIEWPROJECTIONMATRIX);
        mTexture0Location =
                getUniformLocation(ShaderProgramConstants.UNIFORM_TEXTURE_0);
        mIntencityLocation =
                getUniformLocation(UNIFORM_INTENCITY);
    }

    @Override
    public void bind(GLState pGLState, VertexBufferObjectAttributes pVertexBufferObjectAttributes) throws ShaderProgramException {
        super.bind(pGLState, pVertexBufferObjectAttributes);
        GLES20.glUniformMatrix4fv(
                mModelViewProjectionMatrixLocation,
                1,
                false,
                pGLState.getModelViewProjectionGLMatrix(),
                0
        );
        GLES20.glUniform1i(mTexture0Location, 0);
        if (mBlink) {
            long curTime = System.currentTimeMillis();
            long timeDelta = curTime - mPrevTime;
            mPrevTime = curTime;
            float angleDelta = timeDelta * BLINKING_SPEED;
            if (mGrow) {
                mCurAngle += angleDelta;
            } else {
                mCurAngle -= angleDelta;
            }
            if (mCurAngle > MAX_ANGLE) {
                mCurAngle -= 2 * angleDelta;
                mGrow = false;
            } else if (mCurAngle < 0) {
                mCurAngle += 2 * angleDelta;
                mGrow = true;
            }
        }
        GLES20.glUniform1f(mIntencityLocation, map(mCurAngle));
    }

    private static float map(double angle) {
        return (float) (MIN_INTENCITY + mDiv * Math.cos(Math.toRadians(angle)));
    }

    public static void setmBlink(boolean mBlink) {
        mPrevTime = System.currentTimeMillis();
        mGrow = false;
        mCurAngle = START_ANGLE;
        BlinkShader.mBlink = mBlink;
    }
}

It's a bit messy so sorry for this.
The shader itself is very easy. It just changes an intensity of the sprite according to passed variable.

ShaderProgramConstants.ATTRIBUTE_POSITION, ATTRIBUTE_TEXTURECOORDINATES, ATTRIBUTE_COLOR

are used for simplicity. They represent position, texture coordinates and color for triangle respectively. The main parts are link and bind methonds.
Link is called before the shader is linked and you have to bind your attributes here before the shader is linked.

GLES20.glBindAttribLocation()

is used for this.

ShaderProgramConstants.ATTRIBUTE_POSITION_LOCATION

is a constant that represents the location AndEngine uses for position and so on. After the linkage is completed in super.link we should get location of our unifor variables.

getUniformLocation()

is used for this. The nex inportant method is

public void bind(GLState pGLState, VertexBufferObjectAttributes pVertexBufferObjectAttributes) throws ShaderProgramExceptionpublic

It's called every time sprite is being drawn, so here we pass variables to shader.

GLES20.glUniform1i(mTexture0Location, 0)

This line means that 0's texture unit will be used for sampler.

How to attach shader to sprite

Attaching shader to sprite is really simple. You just have to write 

o.setShaderProgram(BlinkShader.getInstance());
BlinkShader.getInstance().setmBlink(true);

This will attach shader to sprite and start blinking. Also you have to add your shader to shader manager to correctly manage onResume and onPause events

mActivity.getShaderProgramManager().loadShaderProgram(BlinkShader.getInstance());

The end

Thats it. As you can see its very easy to use shaders in AndEngine if you know how to do this. Later i will show how to use multitexturing and maybe so other methods.

Settings up AndEngine in Android studio

When i decided to use AndEngine in my project I discovered that it doesn't support Android studio and there is not any passable tutorial about how to make it work. So I spent some time and set it up by myself.

Let's assume that you already have created a project and it has default structure. First create folder named third_party in the root directory of the project. Then in third_party directory create subdirectories called andengine and andenginebox2d. I assume that you already downloaded or cloned AndEngine and Box2d extension for it. Put AndEngine and AndEngineBox2d in andengine and andenginebox2d directories respectively. Create file named build.gradle in andengine directory and andenginebox2d directory. Build.gradle files is a file that tells gradle how to build your project.
Next you have to put content in your build.gradle files. In file located in andengine folder put:

apply plugin: 'android-library'

android {
    compileSdkVersion 17
    buildToolsVersion "19.0.3"

    defaultConfig {
        minSdkVersion 14
        targetSdkVersion 19
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }

    buildTypes {
        release {
            runProguard false
            proguardFiles getDefaultProguardFile('proguard-project.txt')
        }
    }

    sourceSets {
        main {
            manifest.srcFile 'AndroidManifest.xml'
            java.srcDirs = ['src']
            resources.srcDirs = ['src']
            res.srcDirs = ['res']
            assets.srcDirs = ['assets']
        }

        instrumentTest.setRoot('tests')
    }
}

By doing so you are telling gradle that minSdkVersion is 14 and targetSdk is 19. Above all I'm using Java 7 in my project so there is

compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }

block.

In file located in andenginebox2d folder put such content:

apply plugin: 'android-library'

android {
    compileSdkVersion 17
    buildToolsVersion "19.0.3"

    defaultConfig {
        minSdkVersion 14
        targetSdkVersion 19
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }

    buildTypes {
        release {
            runProguard false
            proguardFiles getDefaultProguardFile('proguard-project.txt')
        }
    }

    sourceSets {
        main {
            manifest.srcFile 'AndroidManifest.xml'
            java.srcDirs = ['src']
            resources.srcDirs = ['src']
            res.srcDirs = ['res']
            assets.srcDirs = ['assets']
        }

        instrumentTest.setRoot('tests')
    }
}

dependencies {
    compile project(':third_party:andengine')
}

As you can see it is almost identical to previous except dependencies block. That block tells gradle that andenginebox2d depends on andengine and gradle should include it as a library project.

We are almost done. Next step is to tell gradle that you want it to compile AndEngine with your project.
Open settings.gradle that is located in your project's root directory and add two lines to it:

include ':third_party:andengine'
include ':third_party:andenginebox2d'

Next open build.gradle which locates in app directory and add

    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile project(':third_party:andenginebox2d')
    compile project(':third_party:andengine')

to dependencies block. You already know that it means that your application is dependent of andengine project.

The final step is to open AndroidManifest.xml in andegine and andenginebox2d directories and make them look like this:

<application /> block is needed because of bug in manifest merging tool.
That's it! Now clean your project and press run. Everything should work just fine.