CParticleSamplerAnimTrack

From PopcornFX
Jump to: navigation, search

Particle sampler anim track - Main page : Particle samplers Particle samplers


The Animtrack sampler allows you to sample multiple animation paths exported from your usual 3D authoring package (3DsMax, Maya, etc..)
Please see the Quick-tips : importing animations page for more details on importing.


Animtrack


Particle sampler curve Node properties

Field name Default value Description
Particle sampler curve General
SamplerName Empty, or editor-generated Name of the sampler. (Used to sample from inside the scripts)
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.
AnimResource Empty Path to the exported animation resource
AnimTrackIndex 0 Optional, tells which sub-track should be sampled when invoking the sampler without specifying a track.
Particle sampler curve Import track transformations
TransformTranslate true If checked, will take into account the animation's translations when sampling the track.
TransformRotate true If checked, will take into account the animation's rotations when sampling the track.
TransformScale true If checked, will take into account the animation's scaling factors when sampling the track.
Particle sampler curve Localization
Position 0; 0; 0 Track position offset, in X;Y;Z world units.
EulerOrientation 0; 0; 0 Track orientation offset, rotation angles in degrees along the X;Y;Z axes.
Scale 1; 1; 1 Track non-uniform scaling factors, along the X;Y;Z axes.
Particle sampler curve properties


Additional properties

In the particle treeview, you can also specify a shape to sweep along the path:

Tips ImportAnim 14.png


This way, when sampling the path, it will actually sample the shape swept across the path.


Particle sampler curve Script bindings

The animtrack sampler publishes four main combinations of sampling functions to the scripts:

  • sample with animation cursor only, in the [0,1] range, 0 meaning the beginning of the path, 1 meaning the end of the path.
  • sample with animation cursor and parametric coordinates (when sampling a swept-shape)
  • sample with track index and animation cursor
  • sample with track index, animation cursor, and parametric coordinates


The base sampling function is 'samplePosition', but depending on the swept shape, you can also use all its own sampling functions, such as 'sampleNormal' or 'sampleTangent'.

The base prototypes are:

Function Prototypes Notes
samplePosition
float3    samplePosition(float cursor);
float3    samplePosition(float cursor, int3 pCoords);
float3    samplePosition(int trackIndex, float cursor);
float3    samplePosition(int trackIndex, float cursor, int3 pCoords);
Fully transformed by the path transforms
sampleNormal
float3    sampleNormal(float cursor);
float3    sampleNormal(float cursor, int3 pCoords);
float3    sampleNormal(int trackIndex, float cursor);
float3    sampleNormal(int trackIndex, float cursor, int3 pCoords);
Fully rotated & scaled by the path transforms
sampleTangent
float4    sampleTangent(float cursor);
float4    sampleTangent(float cursor, int3 pCoords);
float4    sampleTangent(int trackIndex, float cursor);
float4    sampleTangent(int trackIndex, float cursor, int3 pCoords);
Fully rotated & scaled by the path transforms. 'w' contains tangent-space flip sign.
sampleTexcoord
float2    sampleTexcoord(float cursor);
float2    sampleTexcoord(float cursor, int3 pCoords);
float2    sampleTexcoord(int trackIndex, float cursor);
float2    sampleTexcoord(int trackIndex, float cursor, int3 pCoords);
Not affected by the path. directly routed to the swept shape's 'sampleTexcoord' function.
sampleColor
float4    sampleColor(float cursor);
float4    sampleColor(float cursor, int3 pCoords);
float4    sampleColor(int trackIndex, float cursor);
float4    sampleColor(int trackIndex, float cursor, int3 pCoords);
Not affected by the path. directly routed to the swept shape's 'sampleColor' function.
sampleParametricCoords
int3    sampleParametricCoords();
Routes to the swept shape 'sampleParametricCoords()' function
Additional functions
sampleDistanceField
float    sampleDistanceField(float3 position, float cursor);
Returns the distance from 'location' to the shape's surface swept across the path at 'cursor'
contains
int    contains(float3 position, float cursor);
Returns -1 if 'location' is inside the shape swept across the path at 'cursor', 0 if it is outside.
transform
float3    transform(float cursor, float3 position);
Applies the track's full-transforms at 'cursor' to the input 'position'
translate
float3    translate(float cursor, float3 position);
Applies the track's translations at 'cursor' to the input 'position'
rotate
float3    rotate(float cursor, float3 position);
Applies the track's rotations at 'cursor' to the input 'position'
scale
float3    scale(float cursor, float3 position);
Applies the track's scales at 'cursor' to the input 'position'


Parameter ranges are:

Parameter Range
trackIndex

From 0 to the number of tracks minus one. For example, if there are 15 tracks in the animation resource, the valid range is [0,14]. If the track index is outside that range, the sampler will clamp it to the correct range.

cursor

in the [0,1] range. The sampler will clamp it to that range if the input value goes beyond the limits.

pCoords

depends on the swept shape. see the Particle sampler shape shape sampler documentation for more details on parametric coordinates.


The 'cursor' parameter should be in the [0,1] curve, and will map the horizontal axis of the curve.
the function will return the value of each component of the curve at that coordinate.


Particle sampler curve Node viewer panel

When this node is selected, it will display the Spline editor inside the Node viewer panel. The curves displayed will change depending on the current TransformMode in the realtime viewport.

Transform mode Realtime viewport shortcut Curve displayed Curve editor
None 'Q' No curve displayed Animtrack curve view (TransformMode = None)
Translate 'W' Path translations Animtrack curve view (TransformMode = Translate)
Rotate 'E' Path rotations Animtrack curve view (TransformMode = Rotate)
Scale 'R' Path scale factors Animtrack curve view (TransformMode = Scale)


Visualizing the swept shape

When the animtrack sampler is selected in the treeview, it will display the Spline editor inside the Node viewer panel.
The curves displayed will change depending on the current TransformMode in the realtime viewport.


When moving the mouse-pointer in the spline editor, the current transformed swept shape will be displayed at that time along the path:


CParticleSamplerAnimTrack Viewport 02b.jpg NodeEd CParticleSamplerAnimTrack 05.jpg

CParticleSamplerAnimTrack Viewport 05.jpg NodeEd CParticleSamplerAnimTrack 06.jpg

CParticleSamplerAnimTrack Viewport 06.jpg NodeEd CParticleSamplerAnimTrack 07.jpg

Note: the displayed spline editor are read-only, therefore you will not be able to modify the animation curves directly from there.
Modifying or creating from scratch animation paths in the viewport is planned for a future version of the editor.