[Update] ParallaxLayer

[jaym]

Click here for parallaxLayer allowing Y parallax: http://www.andengine.org/forums/features/parallaxlayer-t5390-20.html#p31586


NEW PARALLAX LAYER (Previously ScrollableParallaxBackground)

Due to my current project needing more variance in terms of parallaxing items in the game, I decided to create the parallax layer class. It is a modified class based off Andengine's original parallax background class. This class requires GLES20.

Selling points of this class:
- Non-Background: ParallaxLayer is not a background, it is an entity which is attached to the scene like a sprite or shape. The purpose for this is to allow zooming to affect perspective of the parallax entities and if for some instance you need to apply parallax images to the hud or anywhere else, you can do that simply by attachChild(parallaxLayer).

- Multiple Uses: ParallaxLayer allows for more readily available use of both camera scrolling parallax entities as well as auto scrolling parallax entities. You can easily attach clouds to the parallax layer which will move across the screen continuously and on the same parallax layer, you can attach hills in the background which will only move when the camera moves. My favourite part of this is the simplicity. You can achieve a situation like this with only 4 lines of code with this class.

- Customizable Frequencies: You may notice when creating parallax entities, the original auto parallax background strings the images together end to end, which might not be such a good idea for things like clouds. In order to have 1 cloud scroll the screen at a time, this would require you to have a cloud .png (or whatever file type you're using) the entire width of your camera size (width). With this class you can lower the frequency of the images that are scrolling. This will allow you to reduce the image sizes of things like clouds, and simply reduce the frequency of the parallax entity containing the cloud sprite so that it is not strung end to end. Best of all, this also helps to improve framerate considerably, depending on the size of your parallaxing sprites.

- Customizable Ranges: Since Andengine's parallax background is based off, well... a background, the parallax entities have a range of camera min x to camera max x. This causes parallax entities to revert back to the "starting point" when it exits camera view. Parallax Layer allows you to set the range of the parallax entities (how far they will travel before being reverted back to the other side of the layer). You may be thinking that this is not so important, but here's an example situation.. Half of your level is a happy place, with clouds and blue sky, the other half things start to turn dark and gloomy. You can have the parallax entities from the "happy" place stop at a specific range and allow more gloomy (maybe somebats or dead leaves) sprites to take over when you get to the second, darker half of the level.

- Best of all? No more Issue where a tiny space appears in between parallax entities when moving the camera (or otherwise) . I've tested multiple times and have not yet seen any problems with this anymore. Let me know if there's any trouble with this.

That's it for now, let me know if you find any problems so I can fix them.

Class:

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. public class ParallaxLayer extends Entity {
2.         // ===========================================================
3.         // Constants
4.         // ===========================================================
5.  
6.         // ===========================================================
7.         // Fields
8.         // ===========================================================
9.  
10.         private final ArrayList<ParallaxEntity> mParallaxEntities = new ArrayList<ParallaxEntity>();
11.         private int mParallaxEntityCount;
12.  
13.         protected float mParallaxValue;
14.         protected float mParallaxScrollValue;
15.        
16.         protected float mParallaxChangePerSecond;
17.        
18.         protected float mParallaxScrollFactor = 0.2f;
19.        
20.         private Camera mCamera;
21.        
22.         private float mCameraPreviousX;
23.         private float mCameraOffsetX;
24.        
25.         private float   mLevelWidth = 0;
26.        
27.         private boolean mIsScrollable = false;
28.  
29.        
30.         // ===========================================================
31.         // Constructors
32.         // ===========================================================
33.         public ParallaxLayer() {
34.         }
35.  
36.         public ParallaxLayer(final Camera camera, final boolean mIsScrollable){
37.                 this.mCamera = camera;
38.                 this.mIsScrollable = mIsScrollable;
39.                
40.                 mCameraPreviousX = camera.getCenterX();
41.         }
42.        
43.         public ParallaxLayer(final Camera camera, final boolean mIsScrollable, final int mLevelWidth){
44.                 this.mCamera = camera;
45.                 this.mIsScrollable = mIsScrollable;
46.                 this.mLevelWidth = mLevelWidth;
47.                
48.                 mCameraPreviousX = camera.getCenterX();
49.         }
50.        
51.         // ===========================================================
52.         // Getter & Setter
53.         // ===========================================================
54.  
55.         public void setParallaxValue(final float pParallaxValue) {
56.                 this.mParallaxValue = pParallaxValue;
57.         }
58.        
59.         public void setParallaxChangePerSecond(final float pParallaxChangePerSecond) {
60.                 this.mParallaxChangePerSecond = pParallaxChangePerSecond;
61.         }
62.  
63.         public void setParallaxScrollFactor(final float pParallaxScrollFactor){
64.                 this.mParallaxScrollFactor = pParallaxScrollFactor;
65.         }
66.        
67.         // ===========================================================
68.         // Methods for/from SuperClass/Interfaces
69.         // ===========================================================
70.         @Override
71.         public void onManagedDraw(GLState pGLState, Camera pCamera) {
72.                 super.preDraw(pGLState, pCamera);
73.  
74.                
75.                 final float parallaxValue = this.mParallaxValue;
76.                 final float parallaxScrollValue = this.mParallaxScrollValue;
77.                 final ArrayList<ParallaxEntity> parallaxEntities = this.mParallaxEntities;
78.  
79.                 for(int i = 0; i < this.mParallaxEntityCount; i++) {
80.                         if(parallaxEntities.get(i).mIsScrollable){
81.                                 parallaxEntities.get(i).onDraw(pGLState, pCamera, parallaxScrollValue, mLevelWidth);
82.                         } else {
83.                                 parallaxEntities.get(i).onDraw(pGLState, pCamera, parallaxValue, mLevelWidth);
84.                         }
85.  
86.                 }
87.         }
88.        
89.         @Override
90.         protected void onManagedUpdate(float pSecondsElapsed) {
91.                
92.                 if(mIsScrollable && mCameraPreviousX != this.mCamera.getCenterX()){
93.                                 mCameraOffsetX = mCameraPreviousX - this.mCamera.getCenterX();
94.                                 mCameraPreviousX = this.mCamera.getCenterX();
95.                                
96.                                 this.mParallaxScrollValue += mCameraOffsetX * this.mParallaxScrollFactor;
97.                                 mCameraOffsetX = 0;
98.                 }
99.                
100.                 this.mParallaxValue += this.mParallaxChangePerSecond * pSecondsElapsed;
101.                 super.onManagedUpdate(pSecondsElapsed);
102.         }
103.  
104.         // ===========================================================
105.         // Methods
106.         // ===========================================================
107.  
108.         public void attachParallaxEntity(final ParallaxEntity parallaxEntity) {
109.                 this.mParallaxEntities.add(parallaxEntity);
110.                 this.mParallaxEntityCount++;
111.         }
112.  
113.         public boolean detachParallaxEntity(final ParallaxEntity pParallaxEntity) {
114.                 this.mParallaxEntityCount--;
115.                 final boolean success = this.mParallaxEntities.remove(pParallaxEntity);
116.                 if(!success) {
117.                         this.mParallaxEntityCount++;
118.                 }
119.                 return success;
120.         }
121.        
122.         // ===========================================================
123.         // Inner and Anonymous Classes
124.         // ===========================================================
125.  
126.         public static class ParallaxEntity {
127.                 // ===========================================================
128.                 // Constants
129.                 // ===========================================================
130.  
131.                 // ===========================================================
132.                 // Fields
133.                 // ===========================================================
134.  
135.                 final float mParallaxFactor;
136.                 final IAreaShape mAreaShape;
137.                 final boolean mIsScrollable;
138.  
139.                 final float shapeWidthScaled;
140.  
141.                 // ===========================================================
142.                 // Constructors
143.                 // ===========================================================
144.  
145.                 public ParallaxEntity(final float pParallaxFactor, final IAreaShape pAreaShape) {
146.                         this.mParallaxFactor = pParallaxFactor;
147.                         this.mAreaShape = pAreaShape;
148.                         this.mIsScrollable = false;
149.                         shapeWidthScaled = this.mAreaShape.getWidthScaled();
150.                 }
151.                
152.                 public ParallaxEntity(final float pParallaxFactor, final IAreaShape pAreaShape, final boolean mIsScrollable) {
153.                         this.mParallaxFactor = pParallaxFactor;
154.                         this.mAreaShape = pAreaShape;
155.                         this.mIsScrollable = mIsScrollable;
156.                         shapeWidthScaled = this.mAreaShape.getWidthScaled();
157.                 }
158.                
159.                 public ParallaxEntity(final float pParallaxFactor, final IAreaShape pAreaShape, final boolean mIsScrollable, final int mReduceFrequency) {
160.                         this.mParallaxFactor = pParallaxFactor;
161.                         this.mAreaShape = pAreaShape;
162.                         this.mIsScrollable = mIsScrollable;
163.                         shapeWidthScaled = this.mAreaShape.getWidthScaled() * mReduceFrequency;
164.                 }
165.  
166.                 // ===========================================================
167.                 // Getter & Setter
168.                 // ===========================================================
169.  
170.                 // ===========================================================
171.                 // Methods for/from SuperClass/Interfaces
172.                 // ===========================================================
173.  
174.                 // ===========================================================
175.                 // Methods
176.                 // ===========================================================
177.  
178.                 public void onDraw(final GLState pGLState, final Camera pCamera, final float pParallaxValue, final float mLevelWidth) {
179.                         pGLState.pushModelViewGLMatrix();
180.                         {
181.                                 float widthRange;
182.                                
183.                                 if(mLevelWidth != 0){
184.                                         widthRange = mLevelWidth;
185.                                 } else {
186.                                         widthRange = pCamera.getWidth();
187.                                 }
188.  
189.                                 float baseOffset = (pParallaxValue * this.mParallaxFactor) % shapeWidthScaled;
190.  
191.                                 while(baseOffset > 0) {
192.                                         baseOffset -= shapeWidthScaled;
193.                                 }
194.                                 pGLState.translateModelViewGLMatrixf(baseOffset, 0, 0);
195.  
196.                                 float currentMaxX = baseOffset;
197.                                
198.                                 do {
199.                                         this.mAreaShape.onDraw(pGLState, pCamera);
200.                                         pGLState.translateModelViewGLMatrixf(shapeWidthScaled - 1, 0, 0);
201.                                         currentMaxX += shapeWidthScaled;
202.                                 } while(currentMaxX < widthRange);
203.                         }
204.                         pGLState.popModelViewGLMatrix();
205.                 }
206.  
207.                 // ===========================================================
208.                 // Inner and Anonymous Classes
209.                 // ===========================================================
210.         }
211.  
212.  
213. }

Parsed in 0.054 seconds, using GeSHi 1.0.8.4

and implementation:

1. Create your ParallaxLayer object:

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. ParallaxLayer parallaxLayer = new ParallaxLayer(camera, true, 4000);

Parsed in 0.030 seconds, using GeSHi 1.0.8.4

Parameter 1: Camera, needed for Scrolling entities such as hills.
Parameter 2: allow scrolling? this should be enabled if you plan to use parallax entities which move depending on camera movement.
Parameter 3: this is the range in which parallax layer will allow scrolling. Do not include this parameter if you would simply like the parallax layer to use default camera width. The "4000" here means that the parallax entity would scroll for approximately 4000 pixels before it is reverted back to the "starting" point.

These two methods will adjust the speed in which parallax entities travel. Top for auto parallax entities, bottom for camera based parallax entities.

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. backgroundParallax.setParallaxChangePerSecond(8);
2. backgroundParallax.setParallaxScrollFactor(1);

Parsed in 0.033 seconds, using GeSHi 1.0.8.4

Adding ParallaxEntities:

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. // Create your sprites as you normally would
2. Sprite mountainsSprite = new Sprite(0, 0, WIDTH, HEIGHT, mountainsTextureRegion, mEngine.getVertexBufferObjectManager());
3. Sprite starsSprite = new Sprite(0, 0, WIDTH, HEIGHT, starsTextureRegion, mEngine.getVertexBufferObjectManager());
4.  
5. backgroundParallax.attachParallaxEntity(new ParallaxEntity(15, starsSprite, false, 1));
6. backgroundParallax.attachParallaxEntity(new ParallaxEntity(10, mountainsSprite, true));

Parsed in 0.036 seconds, using GeSHi 1.0.8.4

Parameters 1&2: Nothing new, you've used these before with default ParallaxBackground.
Parameter 3: true for camera parallax, false for continuous(auto) parallax.
Parameter 4: Reduce frequency of the parallax image by a number given. For example, with the first parallaxEntity (starsSprite), the frequency is reduced by 1. This means that for every starsSprite on the parallaxLayer, there will be a space the size of starsSprite.getWidth() between each parallax image shown. This is good for improving framerate and obviously not having to create parallax images with unnecessary transparent pixels.

And of course, a quick video which is very simple. You can see how it works at a very basic level though.

[Mathew]

Looks really good, thanks for share!

[Bluepanda]

Yeah jaym your code is no where near complete. Right now none of it works, please put all of the needed code up, not just parts of it.

[jaym]

Yeah jaym your code is no where near complete. Right now none of it works, please put all of the needed code up, not just parts of it.

As requested, here is all of the code. The only thing you'll have to do now is find images to replace the current sky, mountain, land and stars .png's I'm using. I hope too many people didn't have problems figuring this out do to missing the full code example.

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. package com.test;
2.  
3. import org.anddev.andengine.engine.Engine;
4. import org.anddev.andengine.engine.camera.Camera;
5. import org.anddev.andengine.engine.options.EngineOptions;
6. import org.anddev.andengine.engine.options.EngineOptions.ScreenOrientation;
7. import org.anddev.andengine.engine.options.resolutionpolicy.RatioResolutionPolicy;
8. import org.anddev.andengine.entity.scene.Scene;
9. import org.anddev.andengine.entity.scene.Scene.IOnSceneTouchListener;
10. import org.anddev.andengine.entity.scene.background.ParallaxBackground.ParallaxEntity;
11. import org.anddev.andengine.entity.sprite.Sprite;
12. import org.anddev.andengine.input.touch.TouchEvent;
13. import org.anddev.andengine.opengl.texture.atlas.bitmap.BitmapTextureAtlasTextureRegionFactory;
14. import org.anddev.andengine.opengl.texture.atlas.bitmap.BuildableBitmapTextureAtlas;
15. import org.anddev.andengine.opengl.texture.atlas.buildable.builder.BlackPawnTextureBuilder;
16. import org.anddev.andengine.opengl.texture.atlas.buildable.builder.ITextureBuilder.TextureAtlasSourcePackingException;
17. import org.anddev.andengine.opengl.texture.region.TextureRegion;
18. import org.anddev.andengine.ui.activity.BaseGameActivity;
19.  
20. import android.util.Log;
21. import android.view.MotionEvent;
22. import android.view.WindowManager;
23.  
24. public class ScrollableExample extends BaseGameActivity implements
25.                 IOnSceneTouchListener {
26.  
27.         private static int WIDTH;
28.         private static int HEIGHT;
29.  
30.         private Camera camera;
31.  
32.         private TextureRegion skyTextureRegion;
33.         private TextureRegion starsTextureRegion;
34.         private TextureRegion mountainsTextureRegion;
35.         private TextureRegion landTextureRegion;
36.  
37.         private ScrollableParallaxBackground backgroundParallax;
38.  
39.         public Engine onLoadEngine() {
40.                 WindowManager windowManager = (WindowManager) getSystemService(WINDOW_SERVICE);
41.                 WIDTH = windowManager.getDefaultDisplay().getWidth();
42.                 HEIGHT = windowManager.getDefaultDisplay().getHeight();
43.  
44.                 camera = new Camera(0, 0, WIDTH, HEIGHT);
45.  
46.                 EngineOptions engineOptions = new EngineOptions(true,
47.                                 ScreenOrientation.LANDSCAPE, new RatioResolutionPolicy(WIDTH,
48.                                                 HEIGHT), camera);
49.  
50.                 return new Engine(engineOptions);
51.         }
52.  
53.         @Override
54.         public void onLoadResources() {
55.                 BuildableBitmapTextureAtlas texture = new BuildableBitmapTextureAtlas(
56.                                 1024, 1024);
57.  
58.                 skyTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(texture,
59.                                 this, "gfx/sky.png");
60.  
61.                 mountainsTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(
62.                                 texture, this, "gfx/mountains.png");
63.  
64.                 landTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(texture,
65.                                 this, "gfx/land.png");
66.  
67.                 starsTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(texture,
68.                                 this, "gfx/stars.png");
69.  
70.                 try {
71.                         texture.build(new BlackPawnTextureBuilder(0));
72.                 } catch (TextureAtlasSourcePackingException e) {
73.                         // TODO Auto-generated catch block
74.                         e.printStackTrace();
75.                 }
76.  
77.                 mEngine.getTextureManager().loadTexture(texture);
78.         }
79.  
80.         float touchX;
81.  
82.         @Override
83.         public Scene onLoadScene() {
84.                 final Scene scene = new Scene();
85.  
86.                 Sprite skySprite = new Sprite(0, 0, WIDTH, HEIGHT, skyTextureRegion);
87.                 Sprite landSprite = new Sprite(0, 0, WIDTH, HEIGHT, landTextureRegion);
88.                 Sprite mountainsSprite = new Sprite(0, 0, WIDTH, HEIGHT, mountainsTextureRegion);
89.                 Sprite starsSprite = new Sprite(0, 0, WIDTH, HEIGHT, starsTextureRegion);
90.  
91.                 backgroundParallax = new ScrollableParallaxBackground(0, 0, 0, camera);
92.  
93.                 backgroundParallax.attachParallaxEntity(new ParallaxEntity(0, skySprite));
94.                 backgroundParallax.attachParallaxEntity(new ParallaxEntity(-5, starsSprite));
95.                 backgroundParallax
96.                                 .attachParallaxEntity(new ParallaxEntity(-10, mountainsSprite));
97.                 backgroundParallax.attachParallaxEntity(new ParallaxEntity(-15, landSprite));
98.  
99.                 scene.setBackground(backgroundParallax);
100.  
101.                 scene.setOnSceneTouchListener(this);
102.  
103.                 return scene;
104.         }
105.  
106.         @Override
107.         public void onLoadComplete() {
108.  
109.         }
110.  
111.         // Scrolling
112.         private float mTouchX = 0, mTouchOffsetX = 0;
113.  
114.         @Override
115.         public boolean onSceneTouchEvent(Scene pScene, TouchEvent pTouchEvent) {
116.  
117.                 if (pTouchEvent.getAction() == MotionEvent.ACTION_DOWN) {
118.                         mTouchX = pTouchEvent.getMotionEvent().getX();
119.                 } else if (pTouchEvent.getAction() == MotionEvent.ACTION_MOVE) {
120.                         float newX = pTouchEvent.getMotionEvent().getX();
121.  
122.                         mTouchOffsetX = (newX - mTouchX);
123.  
124.                         backgroundParallax.updateScrollEvents();
125.  
126.                         float newScrollX = this.camera.getCenterX() - mTouchOffsetX;
127.  
128.                         this.camera.setCenter(newScrollX, camera.getCenterY());
129.                         mTouchX = newX;
130.                 }
131.                 return true;
132.         }
133. }
134.  

Parsed in 0.052 seconds, using GeSHi 1.0.8.4

[nivangerow]

Why cant this be directly implemented into AndEngine? Someone should tell Nicolas Gramlich!

[Mathew]

Its pointless to implement every modification, because and engine, would be big mess, thats why only basic, and most important/most valuable things are included (its my opinion, I may be wrong of course) Its really easy to extend engine or add some modifications, so there is rather no need to include many modifications by default.

[virtual]

Thank you, jaym, for that useful class and example.

But i have some litle (but unpleasant) problem. Parallax background in intersecting with self gives artifact, black flickering line.

Also this artifact is present in AndEngine example "Autoparallax background"

There screenshot from emulator with this line


also with screenshot from AndEngine Examples



How to fix it?

PS: AndEngine is great.

[Mathew]

There is thread about such issue, one member, posted really good solution, cleaning texture before importing your images, unfortunately, I couldn't find it, search in GLES1 section, as far as I remember, it was there (thread name was connected to black lines around sprites, or similar)

[virtual]

Hi, Mathew. I think, i found thead:
http://www.andengine.org/forums/gles1/black-lines-around-sprites-t5255.html

I trying to use next tip by whalabi:

Basically, when you make a new BitmapTextureAtlas or whatever, draw a completely blank (that's transparent, not black) png onto it, so that it covers the atlas completely.
E.g.:
atlas = new BitmapTextureAtlas(1024, 1024, BitmapTextureFormat.RGBA_8888, textureOptions);
BitmapTextureAtlasTextureRegionFactory.createFromAsset(atlas, context, "blank1024.png", 0, 0);
Then, add the rest of your textures over it, pretending the blank one isn't there.

But i still have black flickering line.

Note: i have not constant RGBA_8888, i use BILINEAR_PREMULTIPLYALPHA

There is my code:

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using java Syntax Highlighting

1. BitmapTextureAtlas texture = new BitmapTextureAtlas(1024, 1024,
2.                                 TextureOptions.BILINEAR_PREMULTIPLYALPHA);
3.  
4.                 BitmapTextureAtlasTextureRegionFactory.createFromAsset(texture, this,
5.                                 "blank1024.png", 0, 0);
6.  
7.                 final int pad = 5;
8.  
9.                 skyTextureRegion = BitmapTextureAtlasTextureRegionFactory
10.                                 .createFromAsset(texture, this, "sky.png", 0 + pad, 0 + pad);
11.  
12.                 sky2TextureRegion = BitmapTextureAtlasTextureRegionFactory
13.                                 .createFromAsset(texture, this, "sky2.png", 0 + pad, 481 + pad);
14.  
15.                 mEngine.getTextureManager().loadTexture(texture);

Parsed in 0.037 seconds, using GeSHi 1.0.8.4

Note: i try several variants of filling blank1024.png. Filling it by RED color gives red lines! Filling with transparent color gives black lines.

[virtual]

Also I tried to use TransparentBitmapTextureAtlasSource hack by ill2005, but did not help.

There is simple example of that bug in attach.
Short description:
1. AutoParallaxBackgroundBugActivity.java - minimal activity source, that used my AutoParallaxBackground
2. ScrollableParallaxBackground.java - slightly modified class, i change extends from ParallaxBackground to AutoParallaxBackground, and (SIC! ) add new method addSprite, that simplifies using of parallax. Look on addSprite, there I use TransparentBitmapTextureAtlasSource
3. TransparentBitmapTextureAtlasSource.java just TransparentBitmapTextureAtlasSource.