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)
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).

ArHitResultList

struct ArHitResultList_ ArHitResultList

A list of hit test results (value type).

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

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.