Fix particle indexing edge cases

[player-03]

When a set of dynamic particles are spread across multiple sub-meshes, Away gets their indices wrong. If the sub-meshes are created at different times, Away also generates redundant data for the earlier sub-meshes.

To see this in action, create the "Particles" sample project, and make the following changes to Main:

Changed lines

	public function new()
	{
		super();
		
		stage.scaleMode = StageScaleMode.NO_SCALE;
		stage.align = StageAlign.TOP_LEFT;
		
		_view = new View3D();
		addChild(_view);
		
		_cameraController = new HoverController(_view.camera, null, 45, 20, 1000);
		
		addChild(new AwayStats(_view));
		
		//setup the particle geometry
		var plane:Geometry = new PlaneGeometry(10, 10, 1, 1, false);
		var geometrySet:Vector<Geometry> = new Vector<Geometry>();
-		for (i in 0...20000)
+		for (i in 0...500)
			geometrySet.push(plane);
		
		//setup the particle animation set
		_particleAnimationSet = new ParticleAnimationSet(true, true);
		_particleAnimationSet.addAnimation(new ParticleBillboardNode());
		_particleAnimationSet.addAnimation(new ParticleVelocityNode(ParticlePropertiesMode.LOCAL_STATIC));
		_particleAnimationSet.initParticleFunc = initParticleFunc;
+		var positionNode:ParticlePositionNode = new ParticlePositionNode(ParticlePropertiesMode.LOCAL_DYNAMIC);
+		_particleAnimationSet.addAnimation(positionNode);
		
		//setup the particle material
		var material:TextureMaterial = new TextureMaterial(Cast.bitmapTexture("assets/blue.png"));
		material.blendMode = BlendMode.ADD;
		
		//setup the particle animator and mesh
		_particleAnimator = new ParticleAnimator(_particleAnimationSet);
+		
+		var positionState = positionNode.getAnimationState(_particleAnimator);
+		var positions:Vector<Vector3D> = new Vector<Vector3D>();
+		var position:Vector3D = new Vector3D(-1000);
+		for (_ in 0...500) {
+			positions.push(position);
+		}
+		positionState.setPositions(positions);
+		
		_particleMesh = new Mesh(ParticleGeometryHelper.generateGeometry(geometrySet), material);
		_particleMesh.animator = _particleAnimator;
		_view.scene.addChild(_particleMesh);
		
+		var geometry:ParticleGeometry = cast(_particleMesh.geometry, ParticleGeometry);
+		addEventListener(MouseEvent.DOUBLE_CLICK, function(event:MouseEvent):Void {
+			//Add another 500 particles.
+			var newGeometry:ParticleGeometry = ParticleGeometryHelper.generateGeometry(geometrySet);
+			
+			for (particle in newGeometry.particles) {
+				particle.particleIndex += geometry.numParticles;
+			}
+			geometry.particles = geometry.particles.concat(newGeometry.particles);
+			geometry.numParticles += newGeometry.numParticles;
+			
+			for (newSubGeometry in newGeometry.subGeometries) {
+				geometry.addSubGeometry(newSubGeometry);
+			}
+			
+			/*
+			//Offset each new batch of particles by 100 units. Except without
+			//this pull request, uncommenting the following code causes a null
+			//pointer error.
+			position = new Vector3D(position.x + 100, 0, 0);
+			for (_ in 0...500) {
+				positions.push(position);
+			}
+			*/
+			
+			//Each sub-mesh represents 500 particles, so ideally we should see
+			//nothing but "500" when printing this array. In reality, every time
+			//we add a new batch, it goes through all the old sub-meshes and
+			//generates a redundant copy of their data.
+			haxe.Timer.delay(() -> trace([for(subMesh in _particleMesh.subMeshes)
+				subMesh.animationSubGeometry?.animationParticles.length]), 50);
+		});
+		
		//start the animation
		_particleAnimator.start();
		
		//add listeners
		addEventListener(Event.ENTER_FRAME, onEnterFrame);
		stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
		stage.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);
		stage.addEventListener(Event.RESIZE, onResize);
		onResize();
	}

Entire Main.hx file

/*

Basic GPU-based particle animation example in Away3d

Demonstrates:

How to use the ParticleAnimationSet to define static particle behaviour.
How to create particle geometry using the ParticleGeometryHelper class.
How to apply a particle animation to a particle geometry set using ParticleAnimator.
How to create a random spray of particles eminating from a central point.

Code by Rob Bateman & Liao Cheng
[email protected]
http://www.infiniteturtles.co.uk
[email protected]


This code is distributed under the MIT License

Copyright (c) The Away Foundation http://www.theawayfoundation.org

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

*/

package;

import away3d.animators.*;
import away3d.animators.data.*;
import away3d.animators.nodes.*;
import away3d.containers.*;
import away3d.controllers.*;
import away3d.core.base.*;
import away3d.debug.*;
import away3d.entities.*;
import away3d.materials.*;
import away3d.primitives.*;
import away3d.tools.helpers.*;
import away3d.utils.*;

import openfl.display.*;
import openfl.events.*;
import openfl.geom.*;
import openfl.Vector;

class Main extends Sprite
{		
	//engine variables
	private var _view:View3D;
	private var _cameraController:HoverController;
	
	//particle variables
	private var _particleAnimationSet:ParticleAnimationSet;
	private var _particleMesh:Mesh;
	private var _particleAnimator:ParticleAnimator;
	
	//navigation variables
	private var _move:Bool = false;
	private var _lastPanAngle:Float;
	private var _lastTiltAngle:Float;
	private var _lastMouseX:Float;
	private var _lastMouseY:Float;
	
	/**
	 * Constructor
	 */
	public function new()
	{
		super();
		
		stage.scaleMode = StageScaleMode.NO_SCALE;
		stage.align = StageAlign.TOP_LEFT;
		
		_view = new View3D();
		addChild(_view);
		
		_cameraController = new HoverController(_view.camera, null, 45, 20, 1000);
		
		addChild(new AwayStats(_view));
		
		//setup the particle geometry
		var plane:Geometry = new PlaneGeometry(10, 10, 1, 1, false);
		var geometrySet:Vector<Geometry> = new Vector<Geometry>();
		for (i in 0...500)
			geometrySet.push(plane);
		
		//setup the particle animation set
		_particleAnimationSet = new ParticleAnimationSet(true, true);
		_particleAnimationSet.addAnimation(new ParticleBillboardNode());
		_particleAnimationSet.addAnimation(new ParticleVelocityNode(ParticlePropertiesMode.LOCAL_STATIC));
		_particleAnimationSet.initParticleFunc = initParticleFunc;
		var positionNode:ParticlePositionNode = new ParticlePositionNode(ParticlePropertiesMode.LOCAL_DYNAMIC);
		_particleAnimationSet.addAnimation(positionNode);
		
		//setup the particle material
		var material:TextureMaterial = new TextureMaterial(Cast.bitmapTexture("assets/blue.png"));
		material.blendMode = BlendMode.ADD;
		
		//setup the particle animator and mesh
		_particleAnimator = new ParticleAnimator(_particleAnimationSet);
		
		var positionState = positionNode.getAnimationState(_particleAnimator);
		var positions:Vector<Vector3D> = new Vector<Vector3D>();
		var position:Vector3D = new Vector3D(-1000);
		for (_ in 0...500) {
			positions.push(position);
		}
		positionState.setPositions(positions);
		
		_particleMesh = new Mesh(ParticleGeometryHelper.generateGeometry(geometrySet), material);
		_particleMesh.animator = _particleAnimator;
		_view.scene.addChild(_particleMesh);
		
		var geometry:ParticleGeometry = cast(_particleMesh.geometry, ParticleGeometry);
		addEventListener(MouseEvent.DOUBLE_CLICK, function(event:MouseEvent):Void {
			//Add another 500 particles.
			var newGeometry:ParticleGeometry = ParticleGeometryHelper.generateGeometry(geometrySet);
			
			for (particle in newGeometry.particles) {
				particle.particleIndex += geometry.numParticles;
			}
			geometry.particles = geometry.particles.concat(newGeometry.particles);
			geometry.numParticles += newGeometry.numParticles;
			
			for (newSubGeometry in newGeometry.subGeometries) {
				geometry.addSubGeometry(newSubGeometry);
			}
			
			/*
			//Offset each new batch of particles by 100 units. Except without
			//this pull request, uncommenting the following code causes a null
			//pointer error.
			position = new Vector3D(position.x + 100, 0, 0);
			for (_ in 0...500) {
				positions.push(position);
			}
			*/
			
			//Each sub-mesh represents 500 particles, so ideally we should see
			//nothing but "500" when printing this array. In reality, every time
			//we add a new batch, it goes through all the old sub-meshes and
			//generates a redundant copy of their data.
			haxe.Timer.delay(() -> trace([for(subMesh in _particleMesh.subMeshes)
				subMesh.animationSubGeometry?.animationParticles.length]), 50);
		});
		
		//start the animation
		_particleAnimator.start();
		
		//add listeners
		addEventListener(Event.ENTER_FRAME, onEnterFrame);
		stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
		stage.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);
		stage.addEventListener(Event.RESIZE, onResize);
		onResize();
	}
	
	/**
	 * Initialiser function for particle properties
	 */
	private function initParticleFunc(prop:ParticleProperties):Void
	{
		prop.startTime = Math.random()*5 - 5;
		prop.duration = 5;
		var degree1:Float = Math.random() * Math.PI ;
		var degree2:Float = Math.random() * Math.PI * 2;
		var r:Float = Math.random() * 50 + 400;
		prop.nodes[ParticleVelocityNode.VELOCITY_VECTOR3D] = new Vector3D(r * Math.sin(degree1) * Math.cos(degree2), r * Math.cos(degree1) * Math.cos(degree2), r * Math.sin(degree2));
	}
	
	/**
	 * Navigation and render loop
	 */		
	private function onEnterFrame(event:Event):Void
	{
		if (_move)
		{
			_cameraController.panAngle = 0.3*(stage.mouseX - _lastMouseX) + _lastPanAngle;
			_cameraController.tiltAngle = 0.3*(stage.mouseY - _lastMouseY) + _lastTiltAngle;
		}
		_view.render();
	}
	
	/**
	 * Mouse down listener for navigation
	 */		
	private function onMouseDown(event:MouseEvent):Void
	{
		_lastPanAngle = _cameraController.panAngle;
		_lastTiltAngle = _cameraController.tiltAngle;
		_lastMouseX = stage.mouseX;
		_lastMouseY = stage.mouseY;
		_move = true;
		stage.addEventListener(Event.MOUSE_LEAVE, onStageMouseLeave);
	}
	
	/**
	 * Mouse up listener for navigation
	 */		
	private function onMouseUp(event:MouseEvent):Void
	{
		_move = false;
		stage.removeEventListener(Event.MOUSE_LEAVE, onStageMouseLeave);
	}
	
	/**
	 * Mouse stage leave listener for navigation
	 */
	private function onStageMouseLeave(event:Event):Void
	{
		_move = false;
		stage.removeEventListener(Event.MOUSE_LEAVE, onStageMouseLeave);
	}
	
	/**
	 * stage listener for resize events
	 */
	private function onResize(event:Event = null):Void
	{
		_view.width = stage.stageWidth;
		_view.height = stage.stageHeight;
	}
}

This version starts out with fewer particles, but adds 500 new particles each time you double-click. It then prints out how many animationParticles are allocated per batch (it only needs 500, but ends up creating far more).

Each batch is meant to be offset by 100 units from the last, but since I used dynamic positions, it's impossible to set the position of anything after the first batch, so everything else appears at (0, 0, 0). If you apply this pull request, you can then uncomment the offset code, and it will appear correctly.

---

I'm submitting this as a draft because there's another use case I haven't tested.

Sub-meshes don't have to represent different sets of particles, they can add more geometry to existing particles. And each sub-mesh can have its own material. So for instance, your particles could have a "solid" part stored in sub-mesh 0, with a basic color shader, plus a glowing trail with an alpha texture stored in sub-mesh 1. Then sub-mesh 0 and sub-mesh 1 would both include the same range of particle indices, starting from 0.

Given how everything was implemented, this appears to be the intended use case. However, ParticleGeometryHelper will create sub-meshes that don't start from 0 if there's too much data, and I guess that simply never got tested.