ArHitResult

Defines an intersection between a ray and estimated real-world geometry.

Summary

Typedefs
ArHitResult	typedef struct ArHitResult_ A single trackable hit (value type).
ArHitResultList	typedef struct ArHitResultList_ A list of hit test results (value type).

Functions
ArHitResultList_create(const ArSession *session, ArHitResultList **out_hit_result_list)	void Creates a hit result list object.
ArHitResultList_destroy(ArHitResultList *hit_result_list)	void Releases the memory used by a hit result list object, along with all the trackable references it holds.
ArHitResultList_getItem(const ArSession *session, const ArHitResultList *hit_result_list, int32_t index, ArHitResult *out_hit_result)	void Copies an indexed entry in the list.
ArHitResultList_getSize(const ArSession *session, const ArHitResultList *hit_result_list, int32_t *out_size)	void Retrieves the number of hit results in this list.
ArHitResult_acquireNewAnchor(ArSession *session, ArHitResult *hit_result, ArAnchor **out_anchor)	ArStatus Creates a new anchor at the hit location.
ArHitResult_acquireTrackable(const ArSession *session, const ArHitResult *hit_result, ArTrackable **out_trackable)	void Acquires reference to the hit trackable.
ArHitResult_create(const ArSession *session, ArHitResult **out_hit_result)	void Allocates an empty hit result object.
ArHitResult_destroy(ArHitResult *hit_result)	void Releases the memory used by a hit result object, along with any trackable reference it holds.
ArHitResult_getDistance(const ArSession *session, const ArHitResult *hit_result, float *out_distance)	void Returns the distance from the camera to the hit location, in meters.
ArHitResult_getHitPose(const ArSession *session, const ArHitResult *hit_result, ArPose *out_pose)	void Returns the pose of the intersection between a ray and detected real-world geometry.

Typedefs

ArHitResult

struct ArHitResult_ ArHitResult

A single trackable hit (value type).

• Create with: ArHitResult_create
• Allocate with: ArHitResultList_getItem
• Release with: ArHitResult_destroy

ArHitResultList

struct ArHitResultList_ ArHitResultList

A list of hit test results (value type).

• Create with: ArHitResultList_create
• Release with: ArHitResultList_destroy

Functions

ArHitResultList_create

void ArHitResultList_create(
  const ArSession *session,
  ArHitResultList **out_hit_result_list
)

Creates a hit result list object.

ArHitResultList_destroy

void ArHitResultList_destroy(
  ArHitResultList *hit_result_list
)

Releases the memory used by a hit result list object, along with all the trackable references it holds.

ArHitResultList_getItem

void ArHitResultList_getItem(
  const ArSession *session,
  const ArHitResultList *hit_result_list,
  int32_t index,
  ArHitResult *out_hit_result
)

Copies an indexed entry in the list.

This acquires a reference to any trackable referenced by the item, and releases any reference currently held by the provided result object.

Details
Parameters	session The ARCore session. hit_result_list The list from which to copy an item. index Index of the entry to copy. out_hit_result An already-allocated ArHitResult object into which the result will be copied.

ArHitResultList_getSize

void ArHitResultList_getSize(
  const ArSession *session,
  const ArHitResultList *hit_result_list,
  int32_t *out_size
)

Retrieves the number of hit results in this list.

ArHitResult_acquireNewAnchor

ArStatus ArHitResult_acquireNewAnchor(
  ArSession *session,
  ArHitResult *hit_result,
  ArAnchor **out_anchor
)

Creates a new anchor at the hit location.

See ArHitResult_getHitPose for details. This is equivalent to creating an anchor on the hit trackable at the hit pose.

Details
Returns	AR_SUCCESS or any of: AR_ERROR_NOT_TRACKING AR_ERROR_SESSION_PAUSED AR_ERROR_RESOURCE_EXHAUSTED AR_ERROR_DEADLINE_EXCEEDED - hit result must be used before the next call to ArSession_update.

ArHitResult_acquireTrackable

void ArHitResult_acquireTrackable(
  const ArSession *session,
  const ArHitResult *hit_result,
  ArTrackable **out_trackable
)

Acquires reference to the hit trackable.

This call must be paired with a call to ArTrackable_release.

ArHitResult_create

void ArHitResult_create(
  const ArSession *session,
  ArHitResult **out_hit_result
)

Allocates an empty hit result object.

ArHitResult_destroy

void ArHitResult_destroy(
  ArHitResult *hit_result
)

Releases the memory used by a hit result object, along with any trackable reference it holds.

ArHitResult_getDistance

void ArHitResult_getDistance(
  const ArSession *session,
  const ArHitResult *hit_result,
  float *out_distance
)

Returns the distance from the camera to the hit location, in meters.

ArHitResult_getHitPose

void ArHitResult_getHitPose(
  const ArSession *session,
  const ArHitResult *hit_result,
  ArPose *out_pose
)

Returns the pose of the intersection between a ray and detected real-world geometry.

The position is the location in space where the ray intersected the geometry. The orientation is a best effort to face the ray origin, and its exact definition differs depending on the Trackable that was hit.

ArPlane : X+ is perpendicular to the cast ray and parallel to the plane, Y+ points along the plane normal (up, for AR_PLANE_HORIZONTAL_UPWARD_FACING planes), and Z+ is parallel to the plane, pointing roughly toward the ray origin.

ArPoint : Attempt to estimate the normal of the surface centered around the hit test. Surface normal estimation is most likely to succeed on textured surfaces and with camera motion. If ArPoint_getOrientationMode returns AR_POINT_ORIENTATION_ESTIMATED_SURFACE_NORMAL, then X+ is perpendicular to the cast ray and parallel to the physical surface centered around the hit test, Y+ points along the estimated surface normal, and Z+ points roughly toward the ray origin. If ArPoint_getOrientationMode returns AR_POINT_ORIENTATION_INITIALIZED_TO_IDENTITY, then X+ is perpendicular to the cast ray and points right from the perspective of the ray origin, Y+ points up, and Z+ points roughly toward the ray origin.

If you wish to retain the location of this pose beyond the duration of a single frame, create an anchor using ArHitResult_acquireNewAnchor to save the pose in a physically consistent way.

Details
Parameters	session The ARCore session. hit_result The hit result to retrieve the pose of. out_pose An already-allocated ArPose object into which the pose will be stored.