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])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. |
int4 | SamplerName.intersectPCoords(float3 rayStart, float3 rayDirection, float rayLength [, bool enabled])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. |
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
|
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 boxUV = out.xy;FaceID = asint(out.z); |
float3 | shape.disassemblePCoordsBoxVolume(int3 pCoords) [v2.7.0]Disassembles volume parametric coordinates for shapes of type boxUVW = out.xyz; |
float3 | shape.disassemblePCoordsSphere(int3 pCoords) [v2.7.0]Disassembles parametric coordinates for shapes of type sphereAngles = out.xy;Radius = out.z; |
float3 | shape.disassemblePCoordsCapsule(int3 pCoords) [v2.7.0]Disassembles parametric coordinates for shapes of type capsuleHeight = out.x;Angle = out.y;Radius = out.z; |
float3 | shape.disassemblePCoordsCylinder(int3 pCoords) [v2.7.0]Disassembles parametric coordinates for shapes of type cylinderHeight = out.x;Angle = out.y;Radius = out.z; |
float3 | shape.disassemblePCoordsCone(int3 pCoords) [v2.7.0]Disassembles parametric coordinates for shapes of type coneHeight = 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.
