# Lens Distortion

# Lens Distortion

This module calculates the projection and eyes distortion matrices, based on the device (Cardboard viewer) and screen parameters.

## Summary

It also includes functions to calculate the distortion for a single point.

| ### Functions ||
|---|---|
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1gab66881b2cd4ca37ce93a9300c6113388(const uint8_t *encoded_device_params, int size, int display_width, int display_height)` | `https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *` Creates a new lens distortion object and initializes it with the values from `encoded_device_params`. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga8ebdc9237fd82635e19e2dd6b65743d3(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion)` | `void` Destroys and releases memory used by the provided lens distortion object. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga8da17e644a4735bbbf5d1e8dfdce8241(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, const https://developers.google.com/cardboard/reference/c/struct/cardboard-uv#struct_cardboard_uv *undistorted_uv, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye)` | `https://developers.google.com/cardboard/reference/c/struct/cardboard-uv#struct_cardboard_uv` Applies lens distortion function to a point normalized \[0,1\] in the screen post-distortion space. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga3d4fa00d8c0dabb90fc1bbd5f0864d4f(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye, https://developers.google.com/cardboard/reference/c/struct/cardboard-mesh#struct_cardboard_mesh *mesh)` | `void` Gets the distortion mesh for a particular eye. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga5d5aff22647ed29dcbe926878ff9da5f(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye, float *eye_from_head_matrix)` | `void` Gets the eye_from_head matrix for a particular eye. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1gaf9e5eb10b38d0d0863877c6a18055e76(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye, float *field_of_view)` | `void` Gets the field of view half angles for a particular eye. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga591ddf3e5ce8f682bff8f3f2a0332ebd(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye, float z_near, float z_far, float *projection_matrix)` | `void` Gets the ideal projection matrix for a particular eye. |
| `https://developers.google.com/cardboard/reference/c/group/lens-distortion#group__lens-distortion_1ga89bd6414683375ff6f1b0f62fc10cfcb(https://developers.google.com/cardboard/reference/c/group/types#group__types_1ga37184253f5103496a6033beebee99455 *lens_distortion, const https://developers.google.com/cardboard/reference/c/struct/cardboard-uv#struct_cardboard_uv *distorted_uv, https://developers.google.com/cardboard/reference/c/group/types#group__types_1gaf7cdc554e461d1ea3f236eefc6a3a59e eye)` | `https://developers.google.com/cardboard/reference/c/struct/cardboard-uv#struct_cardboard_uv` Applies lens inverse distortion function to a point normalized \[0,1\] in pre-distortion (eye texture) space. |

## Functions

### CardboardLensDistortion_create

```
CardboardLensDistortion * CardboardLensDistortion_create(
  const uint8_t *encoded_device_params,
  int size,
  int display_width,
  int display_height
)
```
Creates a new lens distortion object and initializes it with the values from `encoded_device_params`.

`encoded_device_params` Must not be null. When it is unmet, a call to this function results in a no-op and returns a `nullptr`.

| Details ||
|---|---|
| Parameters | |---|---| | `encoded_device_params` | The device parameters serialized using cardboard_device.proto. | | `size` | Size in bytes of `encoded_device_params`. | | `display_width` | Size in pixels of display width. | | `display_height` | Size in pixels of display height. | |
| **Returns** | Lens distortion object pointer. |

### CardboardLensDistortion_destroy

```
void CardboardLensDistortion_destroy(
  CardboardLensDistortion *lens_distortion
)
```
Destroys and releases memory used by the provided lens distortion object.

`lens_distortion` Must not be null. When it is unmet, a call to this function results in a no-op.

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | |

### CardboardLensDistortion_distortedUvForUndistortedUv

```
CardboardUv CardboardLensDistortion_distortedUvForUndistortedUv(
  CardboardLensDistortion *lens_distortion,
  const CardboardUv *undistorted_uv,
  CardboardEye eye
)
```
Applies lens distortion function to a point normalized \[0,1\] in the screen post-distortion space.

`lens_distortion` Must not be null. `undistorted_uv` Must not be null. When it is unmet, a call to this function results in a no-op and returns an invalid struct (in other words, both UV coordinates are equal to -1).

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `undistorted_uv` | Undistorted UV point. | | `eye` | Desired eye. | |
| **Returns** | Point normalized \[0,1\] in pre distort space (eye texture space). |

### CardboardLensDistortion_getDistortionMesh

```
void CardboardLensDistortion_getDistortionMesh(
  CardboardLensDistortion *lens_distortion,
  CardboardEye eye,
  CardboardMesh *mesh
)
```
Gets the distortion mesh for a particular eye.

`lens_distortion` Must not be null. `mesh` Must not be null. When it is unmet, a call to this function results in a no-op and a default value is returned (empty values).
Important: The distorsion mesh that is returned by this function becomes invalid if CardboardLensDistortion is destroyed.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `eye` | Desired eye. | | `mesh` | Distortion mesh. | |

### CardboardLensDistortion_getEyeFromHeadMatrix

```
void CardboardLensDistortion_getEyeFromHeadMatrix(
  CardboardLensDistortion *lens_distortion,
  CardboardEye eye,
  float *eye_from_head_matrix
)
```
Gets the eye_from_head matrix for a particular eye.

`lens_distortion` Must not be null. `eye_from_head_matrix` Must not be null. When it is unmet, a call to this function results in a no-op and a default value is returned (identity matrix).

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `eye` | Desired eye. | | `eye_from_head_matrix` | 4x4 float eye from head matrix. | |

### CardboardLensDistortion_getFieldOfView

```
void CardboardLensDistortion_getFieldOfView(
  CardboardLensDistortion *lens_distortion,
  CardboardEye eye,
  float *field_of_view
)
```
Gets the field of view half angles for a particular eye.

`lens_distortion` Must not be null. `field_of_view` Must not be null. When it is unmet, a call to this function results in a no-op and a default value is returned (all angles equal to 45 degrees).

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `eye` | Desired eye. | | `field_of_view` | 4x1 float half angles in radians, angles are disposed \[left, right, bottom, top\]. | |

### CardboardLensDistortion_getProjectionMatrix

```
void CardboardLensDistortion_getProjectionMatrix(
  CardboardLensDistortion *lens_distortion,
  CardboardEye eye,
  float z_near,
  float z_far,
  float *projection_matrix
)
```
Gets the ideal projection matrix for a particular eye.

`lens_distortion` Must not be null. `projection_matrix` Must not be null. When it is unmet, a call to this function results in a no-op and a default value is returned (identity matrix).

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `eye` | Desired eye. | | `z_near` | Near clip plane z-axis coordinate. | | `z_far` | Far clip plane z-axis coordinate. | | `projection_matrix` | 4x4 float ideal projection matrix. | |

### CardboardLensDistortion_undistortedUvForDistortedUv

```
CardboardUv CardboardLensDistortion_undistortedUvForDistortedUv(
  CardboardLensDistortion *lens_distortion,
  const CardboardUv *distorted_uv,
  CardboardEye eye
)
```
Applies lens inverse distortion function to a point normalized \[0,1\] in pre-distortion (eye texture) space.

`lens_distortion` Must not be null. `distorted_uv` Must not be null. When it is unmet, a call to this function results in a no-op and returns an invalid struct (in other words, both UV coordinates are equal to -1).

| Details ||
|---|---|
| Parameters | |---|---| | `lens_distortion` | Lens distortion object pointer. | | `distorted_uv` | Distorted UV point. | | `eye` | Desired eye. | |
| **Returns** | Point normalized \[0,1\] in the screen post distort space. |