Rewrite/v2.0 General Discussion Thread

[squarefeet]

Following incredibly valid points from @usnul and @cihadturhan, in order to get this library into the state that it deserves, a rewrite would appear to be necessary. This thread is for anyone to add their 2-cents/pennies/other-currency worth of thoughts on improvements, new features, etc. The more critical, the better (IMHO) - that's one of the major ways to ensure the new version is as easy-to-use and performant as possible.

I do ask that any requests/comments should follow the same format as below: one feature per bullet-point, and grouped into either Required or Nice-to-Have (or both, if you're feeling generous).

Thanks!

---

Required

• Sprite-sheet support for both animated textures and shared texture maps.
• < 1 particle per second.
• A much more intuitive API (at the moment, there are just far too many options. These need to be grouped, or...??)
• Dynamic, and efficient, creation/destruction of emitters.
  • Choice of immediate destruction vs. stopping the emitter and waiting for existing particles to die before being removed.
  • Removal of static emitters.
• Remove the 'Group' constructor, and have only one constructor for the entire library.
  • 'Group' constructor should be replaced by internal logic that groups emitters by texture.
  • A user shouldn't have to create a group manually.
• Runtime adjustment of all parameters.
• Efficient callback/event system that allows users access to individual particle parameters on a per-frame basis.
  • This could (read: probably will) have a negative performance impact, so will have to be thoroughly thought-out.
• "Spiral" emitter type
• An implementation of 'angleAlignVelocity' that actually works when particles are not starting from vec3(0,0,0) position.
• A more intuitive way of setting options. At the moment, it's pretty crappy.
• More efficient JS and GLSL code. It's currently not quite as performant as I'd like, and I know that there are places to squeeze!
• Improved documentation and examples. Maybe a few tutorials.
• It's own website to hold the documentation and examples. I'm not sure that gh-pages is public-facing enough.

Nice-to-haves

• Gravity-well or general "gravity" support.
• Vector-field support.
• Angular velocity and/or acceleration instead of/as well as the current angleStart/Middle/End properties.
• An incredibly difficult one, this: a way to generate fairly realistic smoke. Would require a very high particle count, and either vector-field support, particles interacting with other particles, or a dynamic 'wind' system. Maybe all three and yet more still...

[Usnul]

yup, looks the same. Looks awesome actually :)

[Usnul]

have you seen this? http://david.li/disintegration/ light/shadow related

[squarefeet]

I haven't... super impressive stuff. I came across his Flow stuff before, though. It's interesting how he does an incremental odd-even merge sort for the particles... Must look into that!

[Usnul]

There are also webworkers to assist with sorting, even mobile devices have more than 1 core. Allowing sorting to be incomplete could produce visual artifacts, but with large number of particles this may be an acceptable trade-off, considering you'd only need this when number of particles is large :)

[squarefeet]

Ah-ha, good call... I'll take a look at how best that could be implemented :)

[squarefeet]

Okie dokie, here's a quick update on the (latest) rewrite:

• I currently have 5 shader passes: spawn, velocity, color, position, and draw.
  • This is a slight step backwards from using the BigDaddy shader that does the first four of those passes in one, but for now I believe this is the way to go. It mitigates issues when having large particle counts that create a texture that's larger than gl.MAX_TEXTURE_SIZE.
  • I do have a plan to use the BigDaddy shader when particle counts are < sqrt( gl.MAX_TEXTURE_SIZE ), but this hasn't been written yet. It'll need to dynamically assign shaders and that bit isn't done yet.
  • If, for whatever reason, I find the BigDaddy shader isn't a good solution to the problem of multiple shader passes, I'll still use the same approach to combine, say, the position pass and the velocity pass. This might be dynamically done, but I'm not sure whether to expose this "combining" as an option or not. If I do, it might make things needlessly complicated for the sake of a customisation that doesn't really have much affect in the vast majority of cases.
• I've been experimenting with a few API ideas, and settled on one. The main one I didn't settle on was this:

// Create emitter
var emitter = new Emitter();

// Set acceleration value. Behind the scenes, this sets 
// define values in the shader to 'activate' the acceleration 
// module. 
emitter.acceleration = new THREE.Vector3( 1, 2, 3 );

• The biggest problem with this approach is that since I was using Object.defineProperty and it's get/set functions, it got complicated very quickly when a module (Curl Noise, for example) would require additional define values to be set. TL;DR: Pain to maintain.
• The API that I've settled on is very much like the one from the rewrite before this one:

// Create emitter
var emitter = new Emitter();

// Add a module.
// This style allows for much easier customisation. Custom emitters 
// with custom GLSL calculations are SO easy, now!
emitter.addModule( new AccelerationModule( {
    value: new THREE.Vector3( 1, 2, 3 )
} );

// Repeat adding various modules until emitter is complete.
// Unlike the rewrite before this, no need to call `emitter.prepare();` 
// after all modules have been added.

• This approach allows for hugely customisable shaders. All GLSL uniform strings are automatically created, and wrapped in #ifdef statements to allow modules to be easily turned on and off at will with very minor performance hits.

---

So, I'm pretty sure I've hit a little bit of a jackpot re. combining the best bits from previous rewrites. I've just got to stabilise the emitter code, then tackle a few important internal issues:

• How best to "group" emitters? The more I think about it, the less I'm keen on having grouping happen automatically. If it happened automatically, how would new THREE.PointCloud instances be added to the scene? One could pass in the scene as an argument to an Emitter instance, but that feels clunky and a bit silly... I'm more keen on having grouping happen manually. Much easier control for the end user, that way.
• How best to determine when shader "combining" should happen?
• Should I use a THREE.WebGLRenderTargetCube to render 6 different scene depths in order to do much better collision detection? Failing that, would a camera looking in the opposite direction to the scene's camera and translated on the inverse z-axis (rendering just the 'back' of the scene) be enough?
• Since there are issues using the spawn shader when either spawnRate or maxAge is < 1.0, I'm considering swapping to CPU spawn calculation for this. This swap will be automatic, but will require using attributes to determine whether a particle is alive or not within the other shaders. This will need to be written, but can easily be wrapped in another #ifdef to allow state-swapping to easily occur. Also considering having a user-controllable option to force CPU spawn calculation.

---

Once I've rewritten the remaining modules into the new format, I'll definitely whack this up on Github, I promise! As ever, any questions, comments, or criticisms welcome :)

[Usnul]

@squarefeet

emitter.addModule( new AccelerationModule( {
     value: new THREE.Vector3( 1, 2, 3 )
} );

I like this, "module" feels a bit off though. If you already have the whole shader compiled and only defs are being manipulated, maybe consider using a flag instead:

emitter.accelerationEnabled = false

just a thought though.

How best to "group" emitters? The more I think about it, the less I'm keen on having grouping happen automatically. If it happened automatically, how would new THREE.PointCloud instances be added to the scene? One could pass in the scene as an argument to an Emitter instance, but that feels clunky and a bit silly... I'm more keen on having grouping happen manually. Much easier control for the end user, that way.

• using a group for multiple emitters can allow for fewer draw calls (less instances of geometry), if we know span rate and we know maxAge - it's pretty easy to determine maximum pool size (i.e. how many vertices we need for geometry) Other than using grouping to get better performance for multiple emitters using same particle material - there's a possible place to group various different emitters, like say for fire effect you could have "smoke","flame" and "embers" emitters, being co-located. Just throwing ideas out there.

How best to determine when shader "combining" should happen?

• i'm not sure what this means. Could you elaborate?

Should I use a THREE.WebGLRenderTargetCube to render 6 different scene depths in order to do much better collision detection? Failing that, would a camera looking in the opposite direction to the scene's camera and translated on the inverse z-axis (rendering just the 'back' of the scene) be enough?

• i'd say "no", short of doing world-space simulation, you will have error always, using already existing depth buffer is 0 overhead, and thus a pure win, adding 6 more draws even just for depth is quite considerable. It could be a nice "addon", but you'd be making a very significant performance trade, and sometimes it can be justified.

Since there are issues using the spawn shader when either spawnRate or maxAge is < 1.0, I'm considering swapping to CPU spawn calculation for this. This swap will be automatic, but will require using attributes to determine whether a particle is alive or not within the other shaders. This will need to be written, but can easily be wrapped in another #ifdef to allow state-swapping to easily occur. Also considering having a user-controllable option to force CPU spawn calculation.

• what storage type is used for these? I think it's fair enough, but the problem is probably in floating point rounding error somewhere.

[squarefeet]

I like this, "module" feels a bit off though. If you already have the whole shader compiled and only defs are being manipulated, maybe consider using a flag instead.

I hear that, but with the module style, it will allow for custom modules to be created really easily... Once it's up on Github and you can see the Module code, I daresay you might agree :) I do see the issue about enabling/disabling modules, though: I seem to have added that functionality without properly thinking about how it would be exposed. The flag idea seems to be a fairly good solution. I'll experiment with it and see how it feels.

...say for fire effect you could have "smoke","flame" and "embers" emitters, being co-located. Just throwing ideas out there.

Good shout. I'll think a bit more about grouping, as I daresay it will affect some of the internals quite a lot. Something to do as soon as the Module stuff is fully supported by the Emitter.

How best to determine when shader "combining" should happen? By this, I was thinking aloud re. whether to do, and if so when, the shader 'combining' should happen, i.e. combining the position and velocity shaders, or using the BigDaddy shader. I was just wondering what emitter 'states' should trigger what shaders to be used (i.e. small particle counts: use BigDaddy; larger counts: use combined shaders, huge counts: separate shaders.)

About the spawn rate issue: It'll be a lot easier to explain once the code is publicly accessible. Quite hard to explain otherwise without a huge wall of text. Needless to say, it's not a floating-point precision issue!

[Usnul]

@squarefeet I'be happy to read through ha wall of text, if it helps solve the problem :)

[squarefeet]

@Usnul Ha, braver than I! I'll try and put it up soon for you to peruse.

In the meantime, here's something else that would be good to get your opinion on:

Two constructors, both alike in dignity, in fair JavaScript where we set our scene... One constructor, the ShaderPass creates shader passes (i.e. for velocity, position, etc.), the other a Module that affects the behaviour of a particular ShaderPass (i.e. to add CurlNoise, or acceleration to a velocity pass).

A question about the implementation... which do you think is more logical?

var emitter = new Emitter();

emitter add( new ShaderPass( { 
    name: 'velocity',
    // etc...
} ) );

emitter.add( new Module( {
    name: 'acceleration',
    value: new THREE.Vector3( 1, 2, 3 ),
    affectsShaderPass: 'velocity' // Assign this module to the ShaderPass created above
} ) );

Or:

var emitter = new Emitter(),
    pass = new ShaderPass( { 
        name: 'Velocity', 
        // etc...
    } ),
    module = new Module( {
        name: 'acceleration',
        value: new THREE.Vector3( 1, 2, 3 )
    } );

pass.addModule( module );
emitter.addPass( pass );

EDIT: Quick clarification: As far as the end user goes, most people won't have to create their own ShaderPass instances or Modules. There will be predefined ones in the library (like 'VelocityPass', CurlNoise module, etc.). This is mainly for custom stuff, but these constructors will also be used to create the predefined modules/passes.

[Usnul]

@squarefeet Seems like a "has a" relationship, maybe i'm just not getting something. Module seems to need a pass or many passes, then module should be responsible for a pass, no? And thanks for edit, for common use-cases this does seems like a beast of an API :D

[squarefeet]

Yeah, that's what I was thinking as well - the 2nd option "feels" correct to me. Long story short, it goes like this:

An Emitter needs ShaderPass instances (creates the main shader code, renderTargets, dataTextures, etc.. Also can have a basic calculation string (e.g. value.xyz *= 0.8;) if necessary) in order to actually do something. Some of these ShaderPass instances will be automatically added to an Emitter instance, such as the spawn shader.

A ShaderPass can have custom calculations added to it by adding Module instances to a ShaderPass. Module instances can contain calculations to adjust a ShaderPass's value, such as a CurlNoise module, or a Drag module.

Also, if a ShaderPass or a Module instance needs to read from another ShaderPass's output (for example, a velocity pass might need to read from the position pass), uniforms and texture sampler GLSL code is automatically added.

And yes... it's a dirty ol' beast of an API, but that's the way I like it :D At least it'll make adding new modules/passes nice and easy in the future. Expansions made easy!

[squarefeet]

Just had another thought: using this API, you could theoretically create a ShaderPass that would render a diffuse texture that you could use as the texture for the particles... Oh god. What have I created!? :D