Scene queries

Queries read the broad phase from the latest Step or DetectCollisions. More...

Data Structures
struct	R3QueryFilter
	Scene-query flags, groups, and excluded handles. More...
struct	R3QueryOptions
	Copyable query settings. More...
struct	R3RayHit
	Closest ray intersection, with a world-space normal. More...
struct	R3PointProjection
	Closest projected world-space point and its collider. More...
struct	R3ShapeCastHit
	Shape-cast impact geometry; collider-side data is world-space, moving-shape data is local. More...
struct	R3ShapeCastOptions
	Sweep termination settings. More...
struct	R3RayToi
	Optional ray collider/time result. More...
struct	R3OptionalRayHit
	Optional full ray result. More...
struct	R3VoxelQuery
	Optional voxel lookup result; check found before reading voxel data. More...
struct	R3OptionalShapeCastHit
	Optional shape-cast result. More...
struct	R3OptionalPointProjection
	Optional point projection. More...
struct	R3NonlinearRigidMotion
	Rigid motion with constant linear and angular velocities. More...

Macros
#define	R3_QUERY_EXCLUDE_FIXED   1
	Query filter: exclude fixed.
#define	R3_QUERY_EXCLUDE_KINEMATIC   2
	Query filter: exclude kinematic.
#define	R3_QUERY_EXCLUDE_DYNAMIC   4
	Query filter: exclude dynamic.
#define	R3_QUERY_EXCLUDE_SENSORS   8
	Query filter: exclude sensors.
#define	R3_QUERY_EXCLUDE_SOLIDS   16
	Query filter: exclude solids.
#define	R3_QUERY_ONLY_DYNAMIC   3
	Query filter: only dynamic.
#define	R3_QUERY_ONLY_KINEMATIC   5
	Query filter: only kinematic.
#define	R3_QUERY_ONLY_FIXED   6
	Query filter: only fixed.
#define	R3_SHAPE_CAST_OUT_OF_ITERATIONS   0
	Shape-cast iteration limit reached before convergence.
#define	R3_SHAPE_CAST_CONVERGED   1
	Shape cast converged to the reported impact.
#define	R3_SHAPE_CAST_FAILED   2
	Shape-cast numerical solver failed to converge.
#define	R3_SHAPE_CAST_PENETRATING   3
	Shapes overlap or are within the target distance at the start of the cast.
#define	R3_FEATURE_UNKNOWN   0
	The hit feature is unspecified.
#define	R3_FEATURE_VERTEX   1
	The feature ID denotes a vertex.
#define	R3_FEATURE_EDGE   2
	The feature ID denotes an edge.
#define	R3_FEATURE_FACE   3
	The feature ID denotes a face.

Typedefs
typedef struct R3QueryFilter	R3QueryFilter
	Scene-query flags, groups, and excluded handles.
typedef R3Bool(*)	R3QueryPredicate(void *user_data, const struct R3ReadContext *read, struct R3ColliderHandle handle)
	Called with scoped read access and a collider handle.
typedef struct R3QueryOptions	R3QueryOptions
	Copyable query settings.
typedef struct R3RayHit	R3RayHit
	Closest ray intersection, with a world-space normal.
typedef struct R3PointProjection	R3PointProjection
	Closest projected world-space point and its collider.
typedef struct R3ShapeCastHit	R3ShapeCastHit
	Shape-cast impact geometry; collider-side data is world-space, moving-shape data is local.
typedef struct R3ShapeCastOptions	R3ShapeCastOptions
	Sweep termination settings.
typedef struct R3RayToi	R3RayToi
	Optional ray collider/time result.
typedef struct R3OptionalRayHit	R3OptionalRayHit
	Optional full ray result.
typedef struct R3VoxelQuery	R3VoxelQuery
	Optional voxel lookup result; check found before reading voxel data.
typedef struct R3OptionalShapeCastHit	R3OptionalShapeCastHit
	Optional shape-cast result.
typedef struct R3OptionalPointProjection	R3OptionalPointProjection
	Optional point projection.
typedef struct R3NonlinearRigidMotion	R3NonlinearRigidMotion
	Rigid motion with constant linear and angular velocities.

Functions
struct R3QueryOptions	r3DefaultQueryOptions (void)
	Return native default query options.
struct R3RayHit	r3CastRay (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector origin, struct R3Vector direction, R3Real max_toi, R3Bool solid)
	Return the closest ray hit, or report R3_NOT_FOUND on a miss.
struct R3PointProjection	r3ProjectPoint (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector point, R3Real max_distance, R3Bool solid)
	Return the closest surface projection within max_distance, or report R3_NOT_FOUND.
size_t	r3IntersectPoint (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector point, struct R3ColliderHandle *buffer, size_t capacity)
	Copy handles of colliders containing the world-space point.
size_t	r3IntersectAabbConservative (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Aabb aabb, struct R3ColliderHandle *buffer, size_t capacity)
	Copy broad-phase candidates whose bounding boxes overlap the world-space AABB.
struct R3RayToi	r3CastRayToi (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector origin, struct R3Vector direction, R3Real max_toi, R3Bool solid)
	Return the closest ray collider and time, with found = 0 on a miss (R3_OK).
struct R3OptionalRayHit	r3TryCastRay (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector origin, struct R3Vector direction, R3Real max_toi, R3Bool solid)
	Return the closest ray hit with found = 0 on a miss (R3_OK).
struct R3QueryFilter	r3DefaultQueryFilter (void)
	Return native default query filter.
struct R3ShapeCastOptions	r3DefaultShapeCastOptions (void)
	Return native default shape cast options.
size_t	r3IntersectRay (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector origin, struct R3Vector direction, R3Real max_toi, R3Bool solid, struct R3RayHit *buffer, size_t capacity)
	Copy the hits of every collider intersected by the ray, in no particular order.
struct R3OptionalShapeCastHit	r3TryCastShape (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Pose pose, struct R3Vector velocity, const R3SharedShape *shape, struct R3ShapeCastOptions options)
	Sweep shape from pose along velocity and return the first hit, with found = 0 on a miss (R3_OK).
struct R3OptionalPointProjection	r3TryProjectPoint (const struct R3World *world, const struct R3QueryOptions *query_options, struct R3Vector point, R3Real max_distance, R3Bool solid)
	Return the closest surface projection within max_distance, with found = 0 if there is none (R3_OK).
struct R3Pose	r3NonlinearRigidMotion_PositionAtTime (const struct R3NonlinearRigidMotion *motion, R3Real time)
	Return the world-space pose of the motion at the given time.
struct R3OptionalShapeCastHit	r3TryCastShapeNonlinear (const struct R3World *world, const struct R3QueryOptions *query_options, const struct R3NonlinearRigidMotion *motion, const R3SharedShape *shape, R3Real start_time, R3Real end_time, R3Bool stop_at_penetration)
	Sweep shape along a rotating motion and return the first hit between start_time and end_time, with found = 0 on a miss (R3_OK).

Detailed Description

Queries read the broad phase from the latest Step or DetectCollisions.

After insertion or manual pose changes, update collision detection before querying. NULL QueryOptions uses native defaults. Predicates borrow their ReadContext.

Macro Definition Documentation

R3_FEATURE_EDGE

#define R3_FEATURE_EDGE   2

The feature ID denotes an edge.

R3_FEATURE_FACE

#define R3_FEATURE_FACE   3

The feature ID denotes a face.

R3_FEATURE_UNKNOWN

#define R3_FEATURE_UNKNOWN   0

The hit feature is unspecified.

R3_FEATURE_VERTEX

#define R3_FEATURE_VERTEX   1

The feature ID denotes a vertex.

R3_QUERY_EXCLUDE_DYNAMIC

#define R3_QUERY_EXCLUDE_DYNAMIC   4

Query filter: exclude dynamic.

R3_QUERY_EXCLUDE_FIXED

#define R3_QUERY_EXCLUDE_FIXED   1

Query filter: exclude fixed.

R3_QUERY_EXCLUDE_KINEMATIC

#define R3_QUERY_EXCLUDE_KINEMATIC   2

Query filter: exclude kinematic.

R3_QUERY_EXCLUDE_SENSORS

#define R3_QUERY_EXCLUDE_SENSORS   8

Query filter: exclude sensors.

R3_QUERY_EXCLUDE_SOLIDS

#define R3_QUERY_EXCLUDE_SOLIDS   16

Query filter: exclude solids.

R3_QUERY_ONLY_DYNAMIC

#define R3_QUERY_ONLY_DYNAMIC   3

Query filter: only dynamic.

R3_QUERY_ONLY_FIXED

#define R3_QUERY_ONLY_FIXED   6

Query filter: only fixed.

R3_QUERY_ONLY_KINEMATIC

#define R3_QUERY_ONLY_KINEMATIC   5

Query filter: only kinematic.

R3_SHAPE_CAST_CONVERGED

#define R3_SHAPE_CAST_CONVERGED   1

Shape cast converged to the reported impact.

R3_SHAPE_CAST_FAILED

#define R3_SHAPE_CAST_FAILED   2

Shape-cast numerical solver failed to converge.

R3_SHAPE_CAST_OUT_OF_ITERATIONS

#define R3_SHAPE_CAST_OUT_OF_ITERATIONS   0

Shape-cast iteration limit reached before convergence.

R3_SHAPE_CAST_PENETRATING

#define R3_SHAPE_CAST_PENETRATING   3

Shapes overlap or are within the target distance at the start of the cast.

Typedef Documentation

R3NonlinearRigidMotion

typedef struct R3NonlinearRigidMotion R3NonlinearRigidMotion

Rigid motion with constant linear and angular velocities.

At time t, the shape at start is rotated by angvel * t around its local_center point, then translated by linvel * t.

R3OptionalPointProjection

typedef struct R3OptionalPointProjection R3OptionalPointProjection

Optional point projection.

A miss is found = 0 with status OK.

R3OptionalRayHit

typedef struct R3OptionalRayHit R3OptionalRayHit

Optional full ray result.

A miss is found = 0 with status OK.

R3OptionalShapeCastHit

typedef struct R3OptionalShapeCastHit R3OptionalShapeCastHit

Optional shape-cast result.

A miss is found = 0 with status OK.

R3PointProjection

typedef struct R3PointProjection R3PointProjection

Closest projected world-space point and its collider.

R3QueryFilter

typedef struct R3QueryFilter R3QueryFilter

Scene-query flags, groups, and excluded handles.

Initialize with r3DefaultQueryFilter.

R3QueryOptions

typedef struct R3QueryOptions R3QueryOptions

Copyable query settings.

They borrow callback data, never world components.

R3QueryPredicate

typedef R3Bool(*) R3QueryPredicate(void *user_data, const struct R3ReadContext *read, struct R3ColliderHandle handle)

Called with scoped read access and a collider handle.

Shared queries may nest; world mutations are rejected until the outer query returns. Never retain the context.

R3RayHit

typedef struct R3RayHit R3RayHit

Closest ray intersection, with a world-space normal.

R3RayToi

typedef struct R3RayToi R3RayToi

Optional ray collider/time result.

A miss is found = 0 with status OK.

R3ShapeCastHit

typedef struct R3ShapeCastHit R3ShapeCastHit

Shape-cast impact geometry; collider-side data is world-space, moving-shape data is local.

R3ShapeCastOptions

typedef struct R3ShapeCastOptions R3ShapeCastOptions

Sweep termination settings.

Initialize with r3DefaultShapeCastOptions.

R3VoxelQuery

typedef struct R3VoxelQuery R3VoxelQuery

Optional voxel lookup result; check found before reading voxel data.

Function Documentation

r3CastRay()

struct R3RayHit r3CastRay	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	origin,
		struct R3Vector	direction,
		R3Real	max_toi,
		R3Bool	solid )

Return the closest ray hit, or report R3_NOT_FOUND on a miss.

The ray is origin + direction * t for 0 <= t <= max_toi; direction need not be normalized. solid treats an interior origin as a hit at t = 0. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3CastRayToi()

struct R3RayToi r3CastRayToi	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	origin,
		struct R3Vector	direction,
		R3Real	max_toi,
		R3Bool	solid )

Return the closest ray collider and time, with found = 0 on a miss (R3_OK).

The ray is origin + direction * t; max_toi bounds t. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3DefaultQueryFilter()

struct R3QueryFilter r3DefaultQueryFilter

(

void

)

Return native default query filter.

This POD value owns no resources.

r3DefaultQueryOptions()

struct R3QueryOptions r3DefaultQueryOptions

(

void

)

Return native default query options.

This POD value owns no resources.

r3DefaultShapeCastOptions()

struct R3ShapeCastOptions r3DefaultShapeCastOptions

(

void

)

Return native default shape cast options.

This POD value owns no resources.

r3IntersectAabbConservative()

size_t r3IntersectAabbConservative	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Aabb	aabb,
		struct R3ColliderHandle *	buffer,
		size_t	capacity )

Copy broad-phase candidates whose bounding boxes overlap the world-space AABB.

Results may include false positives.

See also

Arrays and output buffers NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3IntersectPoint()

size_t r3IntersectPoint	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	point,
		struct R3ColliderHandle *	buffer,
		size_t	capacity )

Copy handles of colliders containing the world-space point.

See also

Arrays and output buffers NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3IntersectRay()

size_t r3IntersectRay	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	origin,
		struct R3Vector	direction,
		R3Real	max_toi,
		R3Bool	solid,
		struct R3RayHit *	buffer,
		size_t	capacity )

Copy the hits of every collider intersected by the ray, in no particular order.

The ray is origin + direction * t for 0 <= t <= max_toi; direction need not be normalized. solid treats an interior origin as a hit at t = 0.

See also

Arrays and output buffers NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3NonlinearRigidMotion_PositionAtTime()

struct R3Pose r3NonlinearRigidMotion_PositionAtTime	(	const struct R3NonlinearRigidMotion *	motion,
		R3Real	time )

Return the world-space pose of the motion at the given time.

r3ProjectPoint()

struct R3PointProjection r3ProjectPoint	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	point,
		R3Real	max_distance,
		R3Bool	solid )

Return the closest surface projection within max_distance, or report R3_NOT_FOUND.

With solid = 1, an interior point projects to itself. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3TryCastRay()

struct R3OptionalRayHit r3TryCastRay	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	origin,
		struct R3Vector	direction,
		R3Real	max_toi,
		R3Bool	solid )

Return the closest ray hit with found = 0 on a miss (R3_OK).

The ray is origin + direction * t; solid treats an interior origin as a hit at t = 0. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3TryCastShape()

struct R3OptionalShapeCastHit r3TryCastShape	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Pose	pose,
		struct R3Vector	velocity,
		const R3SharedShape *	shape,
		struct R3ShapeCastOptions	options )

Sweep shape from pose along velocity and return the first hit, with found = 0 on a miss (R3_OK).

Time is bounded by options.max_time_of_impact. The shape is borrowed for this call. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3TryCastShapeNonlinear()

struct R3OptionalShapeCastHit r3TryCastShapeNonlinear	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		const struct R3NonlinearRigidMotion *	motion,
		const R3SharedShape *	shape,
		R3Real	start_time,
		R3Real	end_time,
		R3Bool	stop_at_penetration )

Sweep shape along a rotating motion and return the first hit between start_time and end_time, with found = 0 on a miss (R3_OK).

With stop_at_penetration = 1, a shape already intersecting a collider at start_time hits it at start_time; with 0, that penetration is ignored while the motion separates the shapes. witness1/normal1 are world-space; witness2/normal2 are local to the shape, posed by r3NonlinearRigidMotion_PositionAtTime at the time of impact. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r3TryProjectPoint()

struct R3OptionalPointProjection r3TryProjectPoint	(	const struct R3World *	world,
		const struct R3QueryOptions *	query_options,
		struct R3Vector	point,
		R3Real	max_distance,
		R3Bool	solid )

Return the closest surface projection within max_distance, with found = 0 if there is none (R3_OK).

With solid = 1, an interior point projects to itself. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.