Spatial

"Spatial Layers" are a special datastructure that allow chosen particles to store data, and other particles to query that data efficiently.

This allows inter-particle communication and interactions.

This concept might be complex for beginners, we provided effects that are showing basic usage of "Spatial Layers" in our Tutorials Pack (Effects 140, 141 & 145), available on the PopcornFX Marketplace.

SpatialInsert

Node SpatialInsertion

This node inserts the input payload into the input spatial layer, at the input "location".
The "location" is used later for querying the payload at nearby locations.
Currently, the "location" is a float3 and queries are made in a 3D-space world.

Input pins

Layer

spatialLayer

Spatial Layer object that will receive data

Payload

spatialPayload

Spatial Payload that will send data into the Spatial Layer

Location

float3

Location where the spatial payload will be inserted.

+ all common properties

SpatialLayer

Node SpatialLayer

This node declares a spatial layer object.

Like attributes, spatial layer objects are shared between the different layers of the effect.
If another particle layer declares a spatial layer with the same SelfName and CellSize property, both particle layers will access the same spatial layer, allowing them to share data and communicate.
When the spatial layer is declared as global, it is visible from other effects, and the same storage is used while the SelfName and CellSize properties match.

Property

Type

Description

Self Name

LocalizedString

Name of the Layer

Global

bool

Make the Spatial Layer visible from other effects

Cell Size

float

Each cell will have its own data and communication radius.

Storage

float-float4
int-int4

Output pins

Value

spatialLayer

Input Value

+ all common properties except ExecStage and ExecFrequency

SpatialPayloadAppend

Node SpatialPayloadAppend

Much like event payloads, there are spatial payloads. But unlike events, a spatial payload doesn’t need a spatial layer link to append data.

We use spatial payload append nodes to construct the payload we want to insert.

Property

Type

Description

Payload Name

LocalizedString

Name of your payload

Payload Type

float-float4
int-int4

Type of values you will insert

Force Override

bool

Force Type Override

bool

Input pins

Payload

spatialPayload

(If there’s a previous payload to send)

Value

float-float4
int-int4
bool-bool4

Input Value

Output pins

Payload

spatialPayload

Payload to insert in the Spatial Layer

+ all common properties

SpatialQuery

Node SpatialQuery

Spatial queries are special spatial operations that gives you different results depending on the operation you will make.

It needs a spatial layer, and it will only read data from it.

Property

Type

Description

Query Type

enum

Spatial Operation to make.

  • NeighborCount: Returns the number of data elements contained in the query sphere.

  • NeighborCount2: Returns the number of data elements contained in the query sphere with an inner radius.

  • CountInCell: Returns the number of data elements contained in the specified hash-grid cell. Low-level direct access, low-overhead.

  • Closest: Returns the value of the element closest from the query center. If no elements are in the radius, returns +infinity.

  • Closest2: Returns the value of the element closest from the query center. If no elements are in the radius, returns +infinity. (This option has an inner radius)

  • GetFromCell: Direct access to a data element inside the specified hash-grid cell. Low-level direct access, low overhead.

  • Sum: Fetch all data present in the spatial structure that are contained in the query sphere, and:

    • Weight each value with a filtering kernel (1D curve), sampled with the normalized distance of the data to the center of the query sphere.

    • Sum all the results together

  • Average:

  • Min:

  • Max:

  • SumDirectionnal:

Input pins

Layer

spatialLayer

Spatial Layer to read data from

Location

float3

Location in the Spatial Layer where it will read data

InnerRadius

float

(Only for some Query Types) Query Inner Radius

Radius

float

(Only for some Query Types) Query Radius

Kernel

dataCurve

(Only for some Query Types) Weight applied to the data, with cursor = distance / radius

Neighbor Index

int

(Only for some Query Types) Neighbor index (starts at zero).

Output pins

Payload

spatialPayload

Not-used

Value

float-float4
int-int4
bool-bool4

Output Value

HasData

bool

(Only for some Query Types) Value if Spatial Query receive data

+ all common properties