CParticleSamplerSpectrum

From PopcornFX
Jump to: navigation, search

Particle sampler spectrum - Main page : Particle samplers Particle samplers


The spectrum sampler allows you to sample a realtime audio frequency spectrum. You can specify which audio channel group you wish to sample. It is useful to make the particles react to audio, and supports easy-to-use convolution to sample the spectrum a different levels-of-detail.


Particles sampling an audio spectrum and moving with the beat


Particle sampler spectrum Node properties

Field name Default value Description
Particle sampler spectrum General
SamplerName Auto-generated name Name of the sampler, published to the rest of the effect
SamplerDescription Empty Sampler Description (optional)
UserData Empty Use this if you need to pass custom data to your game engine's integration (custom PopcornFX SDK). If you're Using UE4 or Unity, you can ignore this.
ChannelGroup "Master" Name of the channel group the spectrum analyzer should listen to. By default, set to the master channel (global). See the list of available ChannelGroup names below.
Mode Spectrum Tells the sampler what to sample
  • Spectrum : will sample the frequency spectrum of the audio channel
  • Waveform : will sample the raw audio waveform
Filter Point
  • Point
  • Linear
  • Cubic
Convolution Point
  • Point
  • Linear
  • Cubic
DefaultConvolutionLevel 0.0f default convolution level when calling the sampling functions with no convolution level specified. must be in the [0,1] range.
Spectrum sampler properties


Particle sampler spectrum Channel Groups

Inside the PopcornFX-Editor, you can use the following ChannelGroup names:

  • Master
    • Music
    • UI
    • World_Master
      • World_Ambient
      • World_Collision
    • FX_Master
      • FX_Effect
      • FX_Collision
  • Speaker

Each sound that plays inside a specific ChannelGroup can be sampled by specifying it or one of its parent channels (ie. FX_Master will allow you to sample all audio data playing inside the FX_Effect and FX_Collision channel groups). However, this is PopcornFX-Editor specific, so you need to refer to your target engine's implementation documentation.

Particle sampler spectrum Script bindings

for each sampler, the following functions are published to scripts:

float	sample(float cursor, int sampleFilter);
float	sample(float cursor, float convolution, int sampleFilter, int convolutionFilter);

'cursor' is expected to be provided in the [0,1] range. If it overflows that range, the sampler will clamp the input cursors between 0.0 and 1.0


The second overload of the 'sample' function allows you to specify for each sample a convolution level.
the 'convolution' argument will be clamped to the [0,1] range.

  • a value of 0.0 means the fully-detailed spectrum will be sampled.
  • a value of 1.0 means the convolution filter has the width of the whole spectrum. that is, regardless of the given cursor, you will always get a single value, that will be equal to the average of all spectrum values.
  • values in-between sample downscaled versions of the full-scale spectrum, and, depending on the value of the 'Convolution' attribute, additional filtering will be performed. Pretty much like what does the graphics card when sampling a texture between mipmap levels when trilinear texture filtering is activated.


The 'sampleFilter' and 'convolutionFilter' parameters are optional. If not explicitely given to the sample functions, their default values is equal to the 'Filter' and 'Convolution' attributes set in the spectrum sampler node.

Their values can be any of the following:

spectrumFilter.Point
spectrumFilter.Linear
spectrumFilter.Cubic


Particle sampler spectrum Examples

// will sample the spectrum named 'MySpectrum' with the default filtering mode, using the particle's LifeRatio as a sampling cursor
float	value = MySpectrum.sample(LifeRatio);

// will sample the spectrum named 'MySpectrum' with the default filtering mode, at convolution level 0.5
float	value = MySpectrum.sample(LifeRatio, 0.5f);

// will sample the spectrum named 'MySpectrum' with cubic filtering, and no convolution
float	value = MySpectrum.sample(LifeRatio, spectrumFilter.Cubic);

// will sample the spectrum named 'MySpectrum' with cubic filtering mode, at convolution level 0.5
float	value = MySpectrum.sample(LifeRatio, 0.5f, spectrumFilter.Cubic);


Filter: Point

Point sampling. direct sample fetch.

Spectrum sample filter mode : Point
Filter: Linear

Linear interpolation.

Spectrum sample filter mode : Linear
Filter: Cubic

Cubic bezier interpolation.

Spectrum sample filter mode : Cubic


Here is an example of what happens when changing the convolution level:


Convolution level = 0.0










Changing spectrum convolution level

Convolution level = 0.35











Convolution level = 0.68











Convolution level = 0.94