GeometryInstancesSpatialQueries (object)

The GeometryInstancesSpatialQueries object enables to issue spatial queries (raycast, getClosest) to a group of many geometry instances (Geometry - transform pairs) while ensuring scalability.

Adding a new geometry instance is done in two steps. First, the GeometryInstancesSpatialQueries.createInstance function will return a new key associated to the geometry instance to be added. Then, that key needs to be passed back to the GeometryInstancesSpatialQueries.updateInstance function when updating geometry instance’s information. Changes will be detected and an incremental update will be performed when calling GeometryInstancesSpatialQueries.prepareForSpatialQueries.

The geometry instance key is used to identify a geometry instance for all the methods, like knowing which one was hit by a raycast.

GeometryInstancesSpatialQueries GeometryInstancesSpatialQueries GeometryInstancesSpatialQueries StatisticSourceWithAutoRegisterMember StatisticSourceWithAutoRegisterMember GeometryInstancesSpatialQueries->StatisticSourceWithAutoRegisterMember

Members

_GeometryInstanceSpatialQueriesData[] data  
IndexPool dataPoolIndices  
_GeometrySpatialQueryData[Geometry] geometryData  
SpatialAccelerationChooser acceleration  
Boolean dirtyAcceleration  
FewObjectsRecyclingAllocator queryAllocator  
StatisticsAutoRegisterMember autoStats   
/*
** Example: GeometryInstancesSpatialQueries
*/

require Geometry;
  
operator entry() {

  //Add a 10X10 point grid (XZ), centered at origin
  Points points = Points();
  points.addPlane( Xfo(), 10, 10, 11, 11 );//10X10 points grid
  points.defaultPointSize = 0.5;
  Xfo pointsXfo;
  
  //Add a 10X10 lines grid (XZ), centered at X=20
  Lines lines = Lines();
  lines.addGrid( Xfo(), 10, 1, 10, 9, 1, 9 );//10X10 lines grid
  lines.raycastThickness = 0.5;
  Xfo linesXfo;
  linesXfo.tr = Vec3(20, 0, 0);
  
  //Add a 10X10 mesh plane (XZ), centered at X=40
  PolygonMesh mesh = PolygonMesh();
  mesh.addPlane( Xfo(), 10, 10, 9, 9);//10X10 polygon plane
  Xfo meshXfo;
  meshXfo.tr = Vec3(40, 0, 0);
  
  //Create instances and set their initial values
  GeometryInstancesSpatialQueries instances();
  
  Size meshKey = instances.createInstance();
  Size linesKey = instances.createInstance();
  Size pointsKey = instances.createInstance();
  
  instances.updateInstance( meshKey, mesh, meshXfo );
  instances.updateInstance( pointsKey, points, pointsXfo );
  instances.updateInstance( linesKey, lines, linesXfo );
  
  //Prepare for issuing one query at each 4 units along the X axis
  instances.prepareForSpatialQueries( 20, true, null );
  
  for( Size i = 0; i < 20; ++i ) {
    GeometryLocation location;
    Size geometryKey;
    instances.raycast( Ray( Vec3(i*4.0f, 5, 0), Vec3(0.0, -1.0, 0.0) ), true, 0, SCALAR_INFINITE, geometryKey, location );
  
    if( location.isValid() ) {
      Vec3 worldPosition = instances.getWorldPositionAtLocation(geometryKey, location);
  
      if( geometryKey == meshKey )
        report( "Mesh hit at " + worldPosition);
      else if( geometryKey == linesKey )
        report( "Lines hit at " + worldPosition );
      else if( geometryKey == pointsKey )
        report( "Points hit at " + worldPosition);
    }
  }
  
}

/*
** Output:

Points hit at {x:+0.0,y:+0.25,z:+0.0}
Points hit at {x:+4.0,y:+0.25,z:+0.0}
Lines hit at {x:+16.0,y:+0.0,z:+0.0}
Lines hit at {x:+20.0,y:+0.0,z:+0.0}
Lines hit at {x:+24.0,y:+0.0,z:+0.0}
Mesh hit at {x:+36.0,y:+0.0,z:+0.0}
Mesh hit at {x:+40.0,y:+0.0,z:-1.013278e-7}
Mesh hit at {x:+44.0,y:+0.0,z:-2.980232e-8}

*/

Methods

  GeometryInstancesSpatialQueries ( in GeometryInstancesSpatialQueries other )
  GeometryInstancesSpatialQueries ()
Ref<GeometryInstancesSpatialQuery> beginSpatialQuery ? ()
GeometryInstancesSpatialQueries clone ? ()
Size createInstance ! ()
  endSpatialQuery ? ( in Ref<GeometryInstancesSpatialQuery> query )
  getClosest ? ( in Vec3 position, in Scalar maxUnscaledDistance, io Size geometryKey, io GeometryLocation location )
Ref<Geometry> getInstanceGeometry ? ( in Size geometryKey )
Mat44 getInstanceTransform ? ( in Size geometryKey )
Vec3 getWorldPositionAtLocation ? ( in Size geometryKey, in GeometryLocation location )
  prepareForSpatialQueries ? ( in Size approximateNumberOfQueries, in Boolean prepareIndividualGeometries, in GenericValueContainer options )
  raycast ? ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance, io Size geometryKey, io GeometryLocation location )
  removeInstance ! ( in Size geometryKey )
  updateInstance ! ( in Size geometryKey, in Ref<Geometry> geometry, in Mat44 transform )
  updateInstance ! ( in Size geometryKey, in Ref<Geometry> geometry, in Xfo transform )

Methods in detail

GeometryInstancesSpatialQueries ( in GeometryInstancesSpatialQueries other )

copy constructor

GeometryInstancesSpatialQueries ()

Ref<GeometryInstancesSpatialQuery> GeometryInstancesSpatialQueries.beginSpatialQuery? ()

See SpatialQueryable.beginSpatialQuery.

GeometryInstancesSpatialQueries GeometryInstancesSpatialQueries.clone? ()

clone method

Size GeometryInstancesSpatialQueries.createInstance! ()

Returns a geometryKey to be used for a new Geometry instance. This geometryKey needs to be passed to various functions such as GeometryInstancesSpatialQueries.updateInstance or GeometryInstancesSpatialQueries.removeInstance in order to identify the Geometry instance. Functions such as GeometryInstancesSpatialQueries.raycast and GeometryInstancesSpatialQueries.getClosest will return the geometryKey as a reference.

GeometryInstancesSpatialQueries.endSpatialQuery? ( in Ref<GeometryInstancesSpatialQuery> query )

See SpatialQueryable.endSpatialQuery.

GeometryInstancesSpatialQueries.getClosest? ( in Vec3 position, in Scalar maxUnscaledDistance, io Size geometryKey, io GeometryLocation location )

Like SpatialQueryable.getClosest, but returns a geometryKey identifying the instance that was hit (if any). If none was hit, the returned GeometryLocation will be invalid, and geometryKey will be InvalidIndex.

Ref<Geometry> GeometryInstancesSpatialQueries.getInstanceGeometry? ( in Size geometryKey )

Returns the Geometry associated with the key (as last submitted through GeometryInstancesSpatialQueries.updateInstance)

Mat44 GeometryInstancesSpatialQueries.getInstanceTransform? ( in Size geometryKey )

Returns the ‘transform’ associated with the key (as last submitted through GeometryInstancesSpatialQueries.updateInstance)

Vec3 GeometryInstancesSpatialQueries.getWorldPositionAtLocation? ( in Size geometryKey, in GeometryLocation location )

Returns geometry instance’s position, in world space, associated to a GeometryLocation (must be valid and related to that geometry). In particular, the geometryKey and location might have been returned by a call to GeometryInstancesSpatialQueries.raycast or GeometryInstancesSpatialQueries.getClosest.

GeometryInstancesSpatialQueries.prepareForSpatialQueries? ( in Size approximateNumberOfQueries, in Boolean prepareIndividualGeometries, in GenericValueContainer options )

Similar to SpatialQueryable.prepareForSpatialQueries method. This function must be call after all instances have been updated with GeometryInstancesSpatialQueries.updateInstance. This function is not thread-safe.

prepareIndividualGeometries If true, the preparation step will be relayed to individual geometries (and multithreaded among these).
approximateNumberOfQueries Should contain an approximation of the total number of queries to be issued (such as raycast or getClosest).
options See SpatialQueryable.prepareForSpatialQueries for a description of this parameter. Options are applied to all octrees (including instances’ octrees).

GeometryInstancesSpatialQueries.raycast? ( in Ray ray, in Boolean doubleSided, in Scalar coneThreshold, in Scalar maxDistance, io Size geometryKey, io GeometryLocation location )

Like SpatialQueryable.raycast, but returns a geometryKey identifying the instance that was hit (if any). If none was hit, the returned GeometryLocation will be invalid, and geometryKey will be InvalidIndex.

GeometryInstancesSpatialQueries.removeInstance! ( in Size geometryKey )

Removes an instance from the geometry instances group. The same geometryKey might be reassigned to future GeometryInstancesSpatialQueries.createInstance calls.

GeometryInstancesSpatialQueries.updateInstance! ( in Size geometryKey, in Ref<Geometry> geometry, in Mat44 transform )

Updates information for a given geometry instance. It is safe to change the ‘geometry’ value. This function is not thread-safe.

GeometryInstancesSpatialQueries.updateInstance! ( in Size geometryKey, in Ref<Geometry> geometry, in Xfo transform )

Updates information for a given geometry instance. It is safe to change the geometry value. This function is not thread-safe.