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
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.
CardboardLensDistortion_destroy(CardboardLensDistortion *lens_distortion)
void
Destroys and releases memory used by the provided lens distortion object.
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.
CardboardLensDistortion_getDistortionMesh(CardboardLensDistortion *lens_distortion, CardboardEye eye, CardboardMesh *mesh)
void
Gets the distortion mesh for a particular eye.
CardboardLensDistortion_getEyeFromHeadMatrix(CardboardLensDistortion *lens_distortion, CardboardEye eye, float *eye_from_head_matrix)
void
Gets the eye_from_head matrix for a particular eye.
CardboardLensDistortion_getFieldOfView(CardboardLensDistortion *lens_distortion, CardboardEye eye, float *field_of_view)
void
Gets the field of view half angles for a particular eye.
CardboardLensDistortion_getProjectionMatrix(CardboardLensDistortion *lens_distortion, CardboardEye eye, float z_near, float z_far, float *projection_matrix)
void
Gets the ideal projection matrix for a particular eye.
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.

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.

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.