# ArHitResult

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

## Summary

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult` | typedef `struct ArHitResult_` A single trackable hit ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist` | typedef `struct ArHitResultList_` A list of hit test results ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist **out_hit_result_list)` | `void` Creates a hit result list object. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_destroy(https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist *hit_result_list)` | `void` Releases the memory used by a hit result list object, along with all the trackable references it holds. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_getitem(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist *hit_result_list, int32_t index, https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *out_hit_result)` | `void` Copies an indexed entry in the list. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_getsize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist *hit_result_list, int32_t *out_size)` | `void` Retrieves the number of hit results in this list. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_acquirenewanchor(https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *hit_result, https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor **out_anchor)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Creates a new anchor at the hit location. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_acquiretrackable(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *hit_result, https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable **out_trackable)` | `void` Acquires reference to the hit trackable. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult **out_hit_result)` | `void` Allocates an empty hit result object. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_destroy(https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *hit_result)` | `void` Releases the memory used by a hit result object, along with any trackable reference it holds. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_getdistance(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *hit_result, float *out_distance)` | `void` Returns the distance from the camera to the hit location, in meters. |
| `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_gethitpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult *hit_result, https://developers.google.com/ar/reference/c/group/ar-pose#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](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Create with: `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_create`
- Allocate with: `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_getitem`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_destroy`

<br />

### ArHitResultList

```
struct ArHitResultList_ ArHitResultList
```
A list of hit test results ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Create with: `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_create`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresultlist_destroy`

<br />

## 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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#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,
  https://developers.google.com/ar/reference/c/group/ar-anchor#aranchor **out_anchor
)
```
Creates a new anchor at the hit location.

See `https://developers.google.com/ar/reference/c/group/ar-hit-result#arhitresult_gethitpose` for details. This is equivalent to creating an anchor on the hit trackable at the hit pose.


| Details ||
|---|---|
| **Returns** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_not_tracking` - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_session_paused` - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_resource_exhausted` - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_deadline_exceeded` - hit result must be used before the next call to `https://developers.google.com/ar/reference/c/group/ar-session#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 `https://developers.google.com/ar/reference/c/group/ar-trackable#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.

`https://developers.google.com/ar/reference/c/group/ar-plane#arplane` : X+ is perpendicular to the cast ray and parallel to the plane, Y+ points along the plane normal (up, for `https://developers.google.com/ar/reference/c/group/ar-plane#ar_plane_horizontal_upward_facing` planes), and Z+ is parallel to the plane, pointing roughly toward the ray origin.

`https://developers.google.com/ar/reference/c/group/ar-point#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 `https://developers.google.com/ar/reference/c/group/ar-point#arpoint_getorientationmode` returns `https://developers.google.com/ar/reference/c/group/ar-point#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 `https://developers.google.com/ar/reference/c/group/ar-point#arpoint_getorientationmode` returns `https://developers.google.com/ar/reference/c/group/ar-point#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 `https://developers.google.com/ar/reference/c/group/ar-hit-result#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 `https://developers.google.com/ar/reference/c/group/ar-pose#arpose` object into which the pose will be stored. | |