Scene queries

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

Data Structures
struct	R2QueryFilter
	Scene-query flags, groups, and excluded handles. More...
struct	R2QueryOptions
	Copyable query settings. More...
struct	R2RayHit
	Closest ray intersection, with a world-space normal. More...
struct	R2PointProjection
	Closest projected world-space point and its collider. More...
struct	R2ShapeCastHit
	Shape-cast impact geometry; collider-side data is world-space, moving-shape data is local. More...
struct	R2ShapeCastOptions
	Sweep termination settings. More...
struct	R2RayToi
	Optional ray collider/time result. More...
struct	R2OptionalRayHit
	Optional full ray result. More...
struct	R2VoxelQuery
	Optional voxel lookup result; check found before reading voxel data. More...
struct	R2OptionalShapeCastHit
	Optional shape-cast result. More...
struct	R2OptionalPointProjection
	Optional point projection. More...
struct	R2NonlinearRigidMotion
	Rigid motion with constant linear and angular velocities. More...

Macros
#define	R2_QUERY_EXCLUDE_FIXED   1
	Query filter: exclude fixed.
#define	R2_QUERY_EXCLUDE_KINEMATIC   2
	Query filter: exclude kinematic.
#define	R2_QUERY_EXCLUDE_DYNAMIC   4
	Query filter: exclude dynamic.
#define	R2_QUERY_EXCLUDE_SENSORS   8
	Query filter: exclude sensors.
#define	R2_QUERY_EXCLUDE_SOLIDS   16
	Query filter: exclude solids.
#define	R2_QUERY_ONLY_DYNAMIC   3
	Query filter: only dynamic.
#define	R2_QUERY_ONLY_KINEMATIC   5
	Query filter: only kinematic.
#define	R2_QUERY_ONLY_FIXED   6
	Query filter: only fixed.
#define	R2_SHAPE_CAST_OUT_OF_ITERATIONS   0
	Shape-cast iteration limit reached before convergence.
#define	R2_SHAPE_CAST_CONVERGED   1
	Shape cast converged to the reported impact.
#define	R2_SHAPE_CAST_FAILED   2
	Shape-cast numerical solver failed to converge.
#define	R2_SHAPE_CAST_PENETRATING   3
	Shapes overlap or are within the target distance at the start of the cast.
#define	R2_FEATURE_UNKNOWN   0
	The hit feature is unspecified.
#define	R2_FEATURE_VERTEX   1
	The feature ID denotes a vertex.
#define	R2_FEATURE_EDGE   2
	The feature ID denotes an edge.
#define	R2_FEATURE_FACE   3
	The feature ID denotes a face.

Typedefs
typedef struct R2QueryFilter	R2QueryFilter
	Scene-query flags, groups, and excluded handles.
typedef R2Bool(*)	R2QueryPredicate(void *user_data, const struct R2ReadContext *read, struct R2ColliderHandle handle)
	Called with scoped read access and a collider handle.
typedef struct R2QueryOptions	R2QueryOptions
	Copyable query settings.
typedef struct R2RayHit	R2RayHit
	Closest ray intersection, with a world-space normal.
typedef struct R2PointProjection	R2PointProjection
	Closest projected world-space point and its collider.
typedef struct R2ShapeCastHit	R2ShapeCastHit
	Shape-cast impact geometry; collider-side data is world-space, moving-shape data is local.
typedef struct R2ShapeCastOptions	R2ShapeCastOptions
	Sweep termination settings.
typedef struct R2RayToi	R2RayToi
	Optional ray collider/time result.
typedef struct R2OptionalRayHit	R2OptionalRayHit
	Optional full ray result.
typedef struct R2VoxelQuery	R2VoxelQuery
	Optional voxel lookup result; check found before reading voxel data.
typedef struct R2OptionalShapeCastHit	R2OptionalShapeCastHit
	Optional shape-cast result.
typedef struct R2OptionalPointProjection	R2OptionalPointProjection
	Optional point projection.
typedef struct R2NonlinearRigidMotion	R2NonlinearRigidMotion
	Rigid motion with constant linear and angular velocities.

Functions
struct R2QueryOptions	r2DefaultQueryOptions (void)
	Return native default query options.
struct R2RayHit	r2CastRay (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector origin, struct R2Vector direction, R2Real max_toi, R2Bool solid)
	Return the closest ray hit, or report R2_NOT_FOUND on a miss.
struct R2PointProjection	r2ProjectPoint (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector point, R2Real max_distance, R2Bool solid)
	Return the closest surface projection within max_distance, or report R2_NOT_FOUND.
size_t	r2IntersectPoint (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector point, struct R2ColliderHandle *buffer, size_t capacity)
	Copy handles of colliders containing the world-space point.
size_t	r2IntersectAabbConservative (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Aabb aabb, struct R2ColliderHandle *buffer, size_t capacity)
	Copy broad-phase candidates whose bounding boxes overlap the world-space AABB.
struct R2RayToi	r2CastRayToi (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector origin, struct R2Vector direction, R2Real max_toi, R2Bool solid)
	Return the closest ray collider and time, with found = 0 on a miss (R2_OK).
struct R2OptionalRayHit	r2TryCastRay (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector origin, struct R2Vector direction, R2Real max_toi, R2Bool solid)
	Return the closest ray hit with found = 0 on a miss (R2_OK).
struct R2QueryFilter	r2DefaultQueryFilter (void)
	Return native default query filter.
struct R2ShapeCastOptions	r2DefaultShapeCastOptions (void)
	Return native default shape cast options.
size_t	r2IntersectRay (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector origin, struct R2Vector direction, R2Real max_toi, R2Bool solid, struct R2RayHit *buffer, size_t capacity)
	Copy the hits of every collider intersected by the ray, in no particular order.
struct R2OptionalShapeCastHit	r2TryCastShape (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Pose pose, struct R2Vector velocity, const R2SharedShape *shape, struct R2ShapeCastOptions options)
	Sweep shape from pose along velocity and return the first hit, with found = 0 on a miss (R2_OK).
struct R2OptionalPointProjection	r2TryProjectPoint (const struct R2World *world, const struct R2QueryOptions *query_options, struct R2Vector point, R2Real max_distance, R2Bool solid)
	Return the closest surface projection within max_distance, with found = 0 if there is none (R2_OK).
struct R2Pose	r2NonlinearRigidMotion_PositionAtTime (const struct R2NonlinearRigidMotion *motion, R2Real time)
	Return the world-space pose of the motion at the given time.
struct R2OptionalShapeCastHit	r2TryCastShapeNonlinear (const struct R2World *world, const struct R2QueryOptions *query_options, const struct R2NonlinearRigidMotion *motion, const R2SharedShape *shape, R2Real start_time, R2Real end_time, R2Bool 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 (R2_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

R2_FEATURE_EDGE

#define R2_FEATURE_EDGE   2

The feature ID denotes an edge.

R2_FEATURE_FACE

#define R2_FEATURE_FACE   3

The feature ID denotes a face.

R2_FEATURE_UNKNOWN

#define R2_FEATURE_UNKNOWN   0

The hit feature is unspecified.

R2_FEATURE_VERTEX

#define R2_FEATURE_VERTEX   1

The feature ID denotes a vertex.

R2_QUERY_EXCLUDE_DYNAMIC

#define R2_QUERY_EXCLUDE_DYNAMIC   4

Query filter: exclude dynamic.

R2_QUERY_EXCLUDE_FIXED

#define R2_QUERY_EXCLUDE_FIXED   1

Query filter: exclude fixed.

R2_QUERY_EXCLUDE_KINEMATIC

#define R2_QUERY_EXCLUDE_KINEMATIC   2

Query filter: exclude kinematic.

R2_QUERY_EXCLUDE_SENSORS

#define R2_QUERY_EXCLUDE_SENSORS   8

Query filter: exclude sensors.

R2_QUERY_EXCLUDE_SOLIDS

#define R2_QUERY_EXCLUDE_SOLIDS   16

Query filter: exclude solids.

R2_QUERY_ONLY_DYNAMIC

#define R2_QUERY_ONLY_DYNAMIC   3

Query filter: only dynamic.

R2_QUERY_ONLY_FIXED

#define R2_QUERY_ONLY_FIXED   6

Query filter: only fixed.

R2_QUERY_ONLY_KINEMATIC

#define R2_QUERY_ONLY_KINEMATIC   5

Query filter: only kinematic.

R2_SHAPE_CAST_CONVERGED

#define R2_SHAPE_CAST_CONVERGED   1

Shape cast converged to the reported impact.

R2_SHAPE_CAST_FAILED

#define R2_SHAPE_CAST_FAILED   2

Shape-cast numerical solver failed to converge.

R2_SHAPE_CAST_OUT_OF_ITERATIONS

#define R2_SHAPE_CAST_OUT_OF_ITERATIONS   0

Shape-cast iteration limit reached before convergence.

R2_SHAPE_CAST_PENETRATING

#define R2_SHAPE_CAST_PENETRATING   3

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

Typedef Documentation

R2NonlinearRigidMotion

typedef struct R2NonlinearRigidMotion R2NonlinearRigidMotion

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.

R2OptionalPointProjection

typedef struct R2OptionalPointProjection R2OptionalPointProjection

Optional point projection.

A miss is found = 0 with status OK.

R2OptionalRayHit

typedef struct R2OptionalRayHit R2OptionalRayHit

Optional full ray result.

A miss is found = 0 with status OK.

R2OptionalShapeCastHit

typedef struct R2OptionalShapeCastHit R2OptionalShapeCastHit

Optional shape-cast result.

A miss is found = 0 with status OK.

R2PointProjection

typedef struct R2PointProjection R2PointProjection

Closest projected world-space point and its collider.

R2QueryFilter

typedef struct R2QueryFilter R2QueryFilter

Scene-query flags, groups, and excluded handles.

Initialize with r2DefaultQueryFilter.

R2QueryOptions

typedef struct R2QueryOptions R2QueryOptions

Copyable query settings.

They borrow callback data, never world components.

R2QueryPredicate

typedef R2Bool(*) R2QueryPredicate(void *user_data, const struct R2ReadContext *read, struct R2ColliderHandle 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.

R2RayHit

typedef struct R2RayHit R2RayHit

Closest ray intersection, with a world-space normal.

R2RayToi

typedef struct R2RayToi R2RayToi

Optional ray collider/time result.

A miss is found = 0 with status OK.

R2ShapeCastHit

typedef struct R2ShapeCastHit R2ShapeCastHit

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

R2ShapeCastOptions

typedef struct R2ShapeCastOptions R2ShapeCastOptions

Sweep termination settings.

Initialize with r2DefaultShapeCastOptions.

R2VoxelQuery

typedef struct R2VoxelQuery R2VoxelQuery

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

Function Documentation

r2CastRay()

struct R2RayHit r2CastRay	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	origin,
		struct R2Vector	direction,
		R2Real	max_toi,
		R2Bool	solid )

Return the closest ray hit, or report R2_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.

r2CastRayToi()

struct R2RayToi r2CastRayToi	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	origin,
		struct R2Vector	direction,
		R2Real	max_toi,
		R2Bool	solid )

Return the closest ray collider and time, with found = 0 on a miss (R2_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.

r2DefaultQueryFilter()

struct R2QueryFilter r2DefaultQueryFilter

(

void

)

Return native default query filter.

This POD value owns no resources.

r2DefaultQueryOptions()

struct R2QueryOptions r2DefaultQueryOptions

(

void

)

Return native default query options.

This POD value owns no resources.

r2DefaultShapeCastOptions()

struct R2ShapeCastOptions r2DefaultShapeCastOptions

(

void

)

Return native default shape cast options.

This POD value owns no resources.

r2IntersectAabbConservative()

size_t r2IntersectAabbConservative	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Aabb	aabb,
		struct R2ColliderHandle *	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.

r2IntersectPoint()

size_t r2IntersectPoint	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	point,
		struct R2ColliderHandle *	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.

r2IntersectRay()

size_t r2IntersectRay	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	origin,
		struct R2Vector	direction,
		R2Real	max_toi,
		R2Bool	solid,
		struct R2RayHit *	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.

r2NonlinearRigidMotion_PositionAtTime()

struct R2Pose r2NonlinearRigidMotion_PositionAtTime	(	const struct R2NonlinearRigidMotion *	motion,
		R2Real	time )

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

r2ProjectPoint()

struct R2PointProjection r2ProjectPoint	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	point,
		R2Real	max_distance,
		R2Bool	solid )

Return the closest surface projection within max_distance, or report R2_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.

r2TryCastRay()

struct R2OptionalRayHit r2TryCastRay	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	origin,
		struct R2Vector	direction,
		R2Real	max_toi,
		R2Bool	solid )

Return the closest ray hit with found = 0 on a miss (R2_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.

r2TryCastShape()

struct R2OptionalShapeCastHit r2TryCastShape	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Pose	pose,
		struct R2Vector	velocity,
		const R2SharedShape *	shape,
		struct R2ShapeCastOptions	options )

Sweep shape from pose along velocity and return the first hit, with found = 0 on a miss (R2_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.

r2TryCastShapeNonlinear()

struct R2OptionalShapeCastHit r2TryCastShapeNonlinear	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		const struct R2NonlinearRigidMotion *	motion,
		const R2SharedShape *	shape,
		R2Real	start_time,
		R2Real	end_time,
		R2Bool	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 (R2_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 r2NonlinearRigidMotion_PositionAtTime at the time of impact. NULL query options use the default filter. Query state reflects the latest Step or DetectCollisions call.

r2TryProjectPoint()

struct R2OptionalPointProjection r2TryProjectPoint	(	const struct R2World *	world,
		const struct R2QueryOptions *	query_options,
		struct R2Vector	point,
		R2Real	max_distance,
		R2Bool	solid )

Return the closest surface projection within max_distance, with found = 0 if there is none (R2_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.