1. Home
  2. Docs
  3. PopcornFX v2.7
  4. Scripting reference
  5. Samplers
  6. Shape sampler

Shape sampler

Shape sampler

Sampling functions

Return typeDescription
int3SamplerName.samplePCoords()
Samples a random location identifier on the shape.
The resulting parametric coordinate then be passed to the other sampling functions.
float3SamplerName.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.
float3SamplerName.sampleNormal([int3 pCoords]])
Samples a normalon the shape. Accepts an optional parametric coordinate.
If no pCoord is provided, will sample at a random location.
float4SamplerName.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.
float3SamplerName.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.
float2SamplerName.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.
float4SamplerName.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.
int3SamplerName.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.
floatSamplerName.sampleDistanceField(float3 location)
Samples the distance-field of the shape at the specified location.
boolSamplerName.contains(float3 location)
Returns true if the shape contains the specified position, false otherwise.
float4SamplerName.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.
int4SamplerName.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.
float4SamplerName.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).
int3SamplerName.projectPCoords(float3 position)
Computes the projection of the specified position on the shape.
Returns the parametric coordinate of the projected location.

 

Properties

Return typeDescription
intshapeType enumeration

  1. shapeType.box: Box shape
  2. shapeType.sphere: Sphere shape
  3. shapeType.complexEllipsoid: Sphere shape with additional parameters such as non-uniform scale & cut-plane
  4. shapeType.cylinder: Cylinder shape
  5. shapeType.capsule: Capsule shape
  6. shapeType.cone: Cone shape
  7. shapeType.mesh: Triangle mesh shape, defined by an external mesh resource
floatSamplerName.surface()
Returns the surface of the shape.
floatSamplerName.volume()
Returns the volume of the shape.
floatSamplerName.radius()
Returns the radius of the shape if it’s a sphere, complexEllipsoid, capsule, cone, or cylinder. If not, returns zero.
floatSamplerName.innerRadius()
Returns the innerRadius of the shape if it’s a sphere, complexEllipsoid, capsule, or cylinder. If not, returns zero.
floatSamplerName.height()
Returns the height of the shape if it’s a capsule, cone, or cylinder. If not, returns zero.
intSamplerName.vertexCount()
Returns the vertex-count of the shape if it’s a mesh. If not, returns zero.
intSamplerName.triangleCount()
Returns the triangle-count of the shape if it’s a mesh. If not, returns zero.
intSamplerName.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.
float3SamplerName.meshScale()
Returns the mesh-scale of the shape if it’s a mesh. If not, returns zero.
float3SamplerName.boxDim()
Returns the dimensions of the shape if it’s a box. If not, returns zero.
floatSamplerName.type()
Returns the type of the shape. Can be any of the shapeType enumeration values.

 

Transform accessors

Return typeDescription
float3SamplerName.position()
Returns the position of the shape.
float3SamplerName.axisSide()
Returns the side axis of the shape.
float3SamplerName.axisVertical()
Returns the vertical axis of the shape.
float3SamplerName.axisDepth()
Returns the depth axis of the shape.
float3SamplerName.axisLeft()
Returns the left axis of the shape.
float3SamplerName.axisRight()
Returns the right axis of the shape.
float3SamplerName.axisDown()
Returns the down axis of the shape.
float3SamplerName.axisUp()
Returns the up axis of the shape.
float3SamplerName.axisBackward()
Returns the backward axis of the shape.
float3SamplerName.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 typeDescription
int3shape.buildPCoordsMesh(int vertexId)
Builds parametric coordinates for shapes of type mesh, sampled in “vertex” mode.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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 typeDescription
int3shape.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.
int3shape.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.
int3shape.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.
int3shape.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 typeDescription
float3shape.disassemblePCoordsBoxSurface(int3 pCoords) [v2.7.0]
Disassembles surface parametric coordinates for shapes of type box
UV = out.xy;
FaceID = asint(out.z);
float3shape.disassemblePCoordsBoxVolume(int3 pCoords) [v2.7.0]
Disassembles volume parametric coordinates for shapes of type box
UVW = out.xyz;
float3shape.disassemblePCoordsSphere(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type sphere
Angles = out.xy;
Radius = out.z;
float3shape.disassemblePCoordsCapsule(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type capsule
Height = out.x;
Angle = out.y;
Radius = out.z;
float3shape.disassemblePCoordsCylinder(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type cylinder
Height = out.x;
Angle = out.y;
Radius = out.z;
float3shape.disassemblePCoordsCone(int3 pCoords) [v2.7.0]
Disassembles parametric coordinates for shapes of type cone
Height = out.x;
Angle = out.y;
Radius = out.z;
Was this article helpful to you? Yes No

How can we help?