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)

 CardboardLensDistortion 
*

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)

 CardboardUv

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)

 CardboardUv

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.