Shape sampler

Sampling functions

Return type

Description

int3

SamplerName.samplePCoords()
Samples a random location identifier on the shape.
The resulting parametric coordinate then be passed to the other sampling functions.

float3

SamplerName.samplePosition([int3 pCoords]])
Samples a position on the shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample at a random location.

float3

SamplerName.sampleNormal([int3 pCoords]])
Samples a normalon the shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample at a random location.

float4

SamplerName.sampleTangent([int3 pCoords]])
Samples a tangent on the shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample at a random location.
Sampled tangent contains a sign-flip in its 'w' component to take into account tangent-basis mirroring.

float3

SamplerName.sampleVelocity([int3 pCoords]])
Samples the instantaneous surface-velocity of the shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample at a random location.

float2

SamplerName.sampleTexcoord([int3 pCoords]])
Samples a texture-coordinate on the shape sampler shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample a random location.If the mesh has multiple UV streams, functions SamplerName.sampleTexcoord0() to SamplerName.sampleTexcoord9() can be used to sample a specific UV stream, up to 10 UV streams.

float4

SamplerName.sampleColor([int3 pCoords]])
Samples a texture-coordinate on the shape sampler shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample a random location.If the mesh has multiple Color streams, functions SamplerName.sampleColor0() to SamplerName.sampleColor9() can be used to sample a specific Color stream, up to 10 Color streams.

int3

SamplerName.sampleSurfacePCoordsFromUV(float2 uv)
Samples a location identifier on the shape corresponding to the uv coordinates.
The resulting parametric coordinate then be passed to the other sampling functions.

float

SamplerName.sampleDistanceField(float3 location)
Samples the distance-field of the shape at the specified location.

bool

SamplerName.contains(float3 location)
Returns true if the shape contains the specified position, false otherwise.

float4

SamplerName.intersect(float3 rayStart, float3 rayDirection, float rayLength [, bool enabled, bool backfaces])
Raytraces the shape with the specified ray.
Returns the hit normal and intersection distance packed in a float4: normal in result.xyz and distance in result.w.
If the intersection distance is infinite, nothing was hit.
If the optional backfaces argument is true, both frontfaces & backfaces will be intersected[.cf88][v2.23.0]

int4

SamplerName.intersectPCoords(float3 rayStart, float3 rayDirection, float rayLength [, bool enabled, bool backfaces])
Raytraces the shape with the specified ray.
Returns the intersection parametric coordinates in result.xyz, and the intersection distance in asfloat(result.w).
If the intersection distance is infinite, nothing was hit.
If the optional backfaces argument is true, both frontfaces & backfaces will be intersected[.cf88][v2.23.0]

float4

SamplerName.project(float3 position)
Computes the projection of the specified position on the shape.
Returns the vector from position to projected position in result.xyz, and the projection distance in asfloat(result.w).

int3

SamplerName.projectPCoords(float3 position)
Computes the projection of the specified position on the shape.
Returns the parametric coordinate of the projected location.

Properties

Return type

Description

int

shapeType enumeration

shapeType.box: Box shape
shapeType.sphere: Sphere shape
shapeType.complexEllipsoid: Sphere shape with additional parameters such as non-uniform scale & cut-plane
shapeType.cylinder: Cylinder shape
shapeType.capsule: Capsule shape
shapeType.cone: Cone shape
shapeType.mesh: Triangle mesh shape, defined by an external mesh resource
shapeType.collection: Collection of meshes [v2.15.0]

float

SamplerName.surface()
Returns the surface of the shape.

float

SamplerName.volume()
Returns the volume of the shape.

float3

SamplerName.boundsMin() [v2.16.0]
Returns the min corner of the shape’s bounding box.

float3

SamplerName.boundsMax() [v2.16.0]
Returns the max corner of the shape’s bounding box.

float

SamplerName.radius()
Returns the radius of the shape if it’s a sphere, complexEllipsoid, capsule, cone, or cylinder. If not, returns zero.

float

SamplerName.innerRadius()
Returns the innerRadius of the shape if it’s a sphere, complexEllipsoid, capsule, or cylinder. If not, returns zero.

float

SamplerName.height()
Returns the height of the shape if it’s a capsule, cone, or cylinder. If not, returns zero.

int

SamplerName.vertexCount()
Returns the vertex-count of the shape if it’s a mesh. If not, returns zero.

int

SamplerName.triangleCount()
Returns the triangle-count of the shape if it’s a mesh. If not, returns zero.

int

SamplerName.tetraCount()
Returns the tetrahedron-count of the shape if it’s a mesh, and contains tetrahedral information (required for volume sampling). If not, returns zero.

float3

SamplerName.meshScale()
Returns the mesh-scale of the shape if it’s a mesh. If not, returns zero.

float3

SamplerName.boxDim()
Returns the dimensions of the shape if it’s a box. If not, returns zero.

float

SamplerName.type()
Returns the type of the shape. Can be any of the shapeType enumeration values.

Transform accessors

Return type

Description

float3

SamplerName.position()
Returns the position of the shape.

float3

SamplerName.axisSide()
Returns the side axis of the shape.

float3

SamplerName.axisVertical()
Returns the vertical axis of the shape.

float3

SamplerName.axisDepth()
Returns the depth axis of the shape.

float3

SamplerName.axisLeft()
Returns the left axis of the shape.

float3

SamplerName.axisRight()
Returns the right axis of the shape.

float3

SamplerName.axisDown()
Returns the down axis of the shape.

float3

SamplerName.axisUp()
Returns the up axis of the shape.

float3

SamplerName.axisBackward()
Returns the backward axis of the shape.

float3

SamplerName.axisForward()
Returns the forward axis of the shape.

Parametric coordinates helpers

Parametric coordinates are opaque int3 values, where the 96 bits of the int3 holds a bunch of packed information. The way that information is packed depends on the type of shape the parametric coordinate was built for, and is an "implementation detail", meaning it can change without notice from one version of PopcornFX to the next.
The shape namespace contains various helpers to build and disassemble parametric coordinates in a safe and future-proof manner, so you should always use these to fiddle with parametric coordinates, or the "shape.buildParametricCoord" / "shape.disassembleParametricCoord" nodes, which expose more functionality.

Building pCoords

Return type

Description

int3

shape.buildPCoordsMesh(int vertexId)
Builds parametric coordinates for shapes of type mesh, sampled in "vertex" mode.

int3

shape.buildPCoordsMesh(int triangleId, float2 uv)
Builds parametric coordinates for shapes of type mesh, sampled in "surface" mode.
uv are the barycentric coordinates of the sample in the triangle triangleId.

int3

shape.buildPCoordsMesh(int tetraId, float3 uvw)
Builds parametric coordinates for shapes of type mesh, sampled in "volume" mode.
uvw are the barycentric coordinates of the sample in the tetrahedron tetraId.

int3

shape.buildPCoordsBox(int faceId, float2 uv)
Builds parametric coordinates for shapes of type box, sampled in "surface" mode.
uv are the [0,1] coordinates of the sample on the face faceId.

int3

shape.buildPCoordsBox(float3 uvw)
Builds parametric coordinates for shapes of type box, sampled in "surface" mode.
uvw are the [0,1] coordinates of the sample in the normalized box.

int3

shape.buildPCoordsSphere(float2 angles, float radius)
Builds parametric coordinates for shapes of type sphere, sampled in "surface" or "volume" modes.
angles are the theta/phi polar angles of the sample, normalized into the [0, 1] range.
radius is the normalized [0, 1] sample position between the inner and outer radius.

int3

shape.buildPCoordsCapsule(float height, float angle, float radius)
Builds parametric coordinates for shapes of type capsule, sampled in "surface" or "volume" modes.
height is the normalized [0, 1] sample coordinate between the lowest point of the bottom hemisphere, and the highest point of the top hemisphere.
angle is the theta polar angles of the sample, normalized into the [0, 1] range.
radius is the normalized [0, 1] sample coordinate between the inner and outer radius.

int3

shape.buildPCoordsCylinder(float height, float angle, float radius)
Builds parametric coordinates for shapes of type cylinder, sampled in "surface" or "volume" modes.
height is the normalized [0, 1] sample coordinate between the bottom and top cylinder caps.
angle is the theta polar angles of the sample, normalized into the [0, 1] range.
radius is the normalized [0, 1] sample coordinate between the inner and outer radius.

int3

shape.buildPCoordsCone(float height, float angle)
Builds parametric coordinates for shapes of type cone, sampled in "surface" mode.
height is the normalized [0, 1] sample coordinate between the bottom cap and the apex of the cone.
angle is the theta polar angles of the sample, normalized into the [0, 1] range.

int3

shape.buildPCoordsCone(float height, float angle, float radius)
Builds parametric coordinates for shapes of type cone, sampled in "volume" mode.
height is the normalized [0, 1] sample coordinate between the bottom cap and the apex of the cone.
angle is the theta polar angles of the sample, normalized into the [0, 1] range.
radius is the normalized [0, 1] sample coordinate between the center and the edge of the cone.

Building pCoords (coherent samples)

Return type

Description

int3

shape.buildPCoordsBoxRegular(int sampleId, int sampleCount)
Builds parametric coordinates for shapes of type box, sampled in "surface" mode.
The generated PCoords represent points laid out on a pseudo-regular pattern.

int3

shape.buildPCoordsSphereRegular(int sampleId, int sampleCount)
Builds parametric coordinates for shapes of type sphere, sampled in "surface" mode.
The generated PCoords represent points laid out on a pseudo-regular pattern.

int3

shape.buildPCoordsCylinderRegular(int sampleId, int sampleCount)
Builds parametric coordinates for shapes of type cylinder, sampled in "surface" mode.
The generated PCoords represent points laid out on a pseudo-regular pattern.

int3

shape.buildPCoordsConeRegular(int sampleId, int sampleCount)
Builds parametric coordinates for shapes of type cone, sampled in "surface" mode.
The generated PCoords represent points laid out on a pseudo-regular pattern.

Disassembling pCoords

Return type

Description

float3

shape.disassemblePCoordsBoxSurface(int3 pCoords) [v2.7.0]
Disassembles surface parametric coordinates for shapes of type box
UV = out.xy;
FaceID = asint(out.z);

float3

shape.disassemblePCoordsBoxVolume(int3 pCoords) [v2.7.0]
Disassembles volume parametric coordinates for shapes of type box
UVW = out.xyz;

float3

shape.disassemblePCoordsSphere(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type sphere
Angles = out.xy;
Radius = out.z;

float3

shape.disassemblePCoordsCapsule(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type capsule
Height = out.x;
Angle = out.y;
Radius = out.z;

float3

shape.disassemblePCoordsCylinder(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type cylinder
Height = out.x;
Angle = out.y;
Radius = out.z;

float3

shape.disassemblePCoordsCone(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type cone
Height = out.x;
Angle = out.y;
Radius = out.z;

Note: These are describing the reference implementation. When using attribute samplers, the behavior of these functions can vary depending on the implementation in the game-engine where the effect is loaded.