# Viewports and viewport lists

# Viewports and viewport lists

Objects to define the mapping between the application's rendering output and the user's field of view.

## Summary

| ### Functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga1005a44252487944198b31d0a6f49d45(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `gvr_buffer_viewport *` Creates a gvr_buffer_viewport instance. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga24524ca1af64663a2969b1c47188ae44(gvr_buffer_viewport **viewport)` | `void` Frees a gvr_buffer_viewport instance and clears the pointer. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gadfe006fb9f23bd0b4d1227eb82b68858(const gvr_buffer_viewport *a, const gvr_buffer_viewport *b)` | `bool` Compares two gvr_buffer_viewport instances and returns true if they specify the same view mapping. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga3737c2fd9be20b59a2df4a53ed21a580(const gvr_buffer_viewport *viewport)` | `int32_t` Gets the ID of the externally-managed Surface texture from which this viewport reads undistored pixels. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gaf7cc0087e067de5510de512ffc1b13a6(const gvr_buffer_viewport *viewport)` | `float` Gets the opacity to perform on the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga2891fa646d091576ba2b9d9b540cc93a(const gvr_buffer_viewport *viewport)` | `int32_t` Gets the type of reprojection to perform on the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gacedbce1f7d901e46065ea520eff1a2b6(const gvr_buffer_viewport *viewport)` | `int32_t` Gets the index of the source buffer from which the viewport reads its undistorted pixels. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga492c38af0e159bad17e062180b17de62(const gvr_buffer_viewport *viewport)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-rectf#structgvr__rectf` Retrieves the field of view for the referenced buffer region. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga57e6ae3c8bcf39a593476e602cd2515f(const gvr_buffer_viewport *viewport)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-rectf#structgvr__rectf` Gets the UV coordinates specifying where the output buffer is sampled. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga01936740e781dd515359c7f4a5ddd8b6(const gvr_buffer_viewport *viewport)` | `int32_t` Gets the target logical eye for the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga70121ead524e88d0ac2615c86e97829c(const gvr_buffer_viewport *viewport)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f` Gets the matrix that positions the viewport in eye space. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga1764815894fde73a0ce1680250830af4(const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `gvr_buffer_viewport_list *` Creates a new, empty list of viewports. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga9baf5a5fcd6ad6ccb69a1b15efd87c97(gvr_buffer_viewport_list **viewport_list)` | `void` Destroys a gvr_buffer_viewport_list instance. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gab65534f0798fafa9c0f8173b930fb742(const gvr_buffer_viewport_list *viewport_list, size_t index, gvr_buffer_viewport *viewport)` | `void` Retrieve a buffer viewport entry from a list. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga59f89692780bf72ab03787fe0bad5e6a(const gvr_buffer_viewport_list *viewport_list)` | `size_t` Returns the size of the given viewport list. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga39c1a62293bbe2ca0eda8944041fcf9f(gvr_buffer_viewport_list *viewport_list, size_t index, const gvr_buffer_viewport *viewport)` | `void` Update an element of the viewport list or append a new one at the end. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga0291753aff748fdc607988644fdadf63(gvr_buffer_viewport *viewport, int32_t external_surface_id)` | `void` Sets the ID of the externally-managed Surface texture from which this viewport reads. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga3282902214d973e2e02c9fcb83800afe(gvr_buffer_viewport *viewport, float opacity)` | `void` Sets the opacity to perform on the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gaaf017397f3c52984603b8e1195a384d1(gvr_buffer_viewport *viewport, int32_t reprojection)` | `void` Sets the type of reprojection to perform on the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga60083cb1f45dd2302dfbf3c24921f2a0(gvr_buffer_viewport *viewport, int32_t buffer_index)` | `void` Sets the buffer from which the viewport reads its undistorted pixels. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1gaabdd75193d6bfe4a091d3671551d3a79(gvr_buffer_viewport *viewport, https://developers.google.com/vr/reference/android-ndk/struct/gvr-rectf#structgvr__rectf fov)` | `void` Sets the field of view for the viewport contents. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga347a66462b513b2e86b70177780c6c81(gvr_buffer_viewport *viewport, int32_t layer_index)` | `void` Sets the layer in a multiview buffer from which the viewport should sample. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga177834a7e65a0e1906471bc1a386e5b6(gvr_buffer_viewport *viewport, https://developers.google.com/vr/reference/android-ndk/struct/gvr-rectf#structgvr__rectf uv)` | `void` Sets the UV coordinates specifying where the output buffer should be sampled when compositing the final distorted image. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga5414e6b39b7e29d922f5365cdaeb20cf(gvr_buffer_viewport *viewport, int32_t index)` | `void` Sets the target logical eye for the specified viewport. |
| `https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga8bbe798d6de19eff2f5499f3ab628722(gvr_buffer_viewport *viewport, https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f transform)` | `void` Sets the matrix that positions the viewport in eye space. |

## Functions

### gvr_buffer_viewport_create

```
gvr_buffer_viewport * gvr_buffer_viewport_create(
  gvr_context *gvr
)
```
Creates a gvr_buffer_viewport instance.

### gvr_buffer_viewport_destroy

```
void gvr_buffer_viewport_destroy(
  gvr_buffer_viewport **viewport
)
```
Frees a gvr_buffer_viewport instance and clears the pointer.

### gvr_buffer_viewport_equal

```
bool gvr_buffer_viewport_equal(
  const gvr_buffer_viewport *a,
  const gvr_buffer_viewport *b
)
```
Compares two gvr_buffer_viewport instances and returns true if they specify the same view mapping.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `a` | Instance of a buffer viewport. | | `b` | Another instance of a buffer viewport. | |
| **Returns** | True if the passed viewports are the same. |

### gvr_buffer_viewport_get_external_surface_id

```
int32_t gvr_buffer_viewport_get_external_surface_id(
  const gvr_buffer_viewport *viewport
)
```
Gets the ID of the externally-managed Surface texture from which this viewport reads undistored pixels.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | ID of the externally-managed Surface of undistorted pixels. |

### gvr_buffer_viewport_get_opacity

```
float gvr_buffer_viewport_get_opacity(
  const gvr_buffer_viewport *viewport
)
```
Gets the opacity to perform on the specified viewport.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | opacity that is applied to the viewport, default to be 1. |

### gvr_buffer_viewport_get_reprojection

```
int32_t gvr_buffer_viewport_get_reprojection(
  const gvr_buffer_viewport *viewport
)
```
Gets the type of reprojection to perform on the specified viewport.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | Type of reprojection that is applied to the viewport. |

### gvr_buffer_viewport_get_source_buffer_index

```
int32_t gvr_buffer_viewport_get_source_buffer_index(
  const gvr_buffer_viewport *viewport
)
```
Gets the index of the source buffer from which the viewport reads its undistorted pixels.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | Index of the source buffer. This corresponds to the index in the list of buffer specs that was passed to [gvr_swap_chain_create()](https://developers.google.com/vr/reference/android-ndk/group/swap-chain#group__swap__chain_1ga423d0cba3833a31d9ffe3a3d8c9bac53). |

### gvr_buffer_viewport_get_source_fov

```
gvr_rectf gvr_buffer_viewport_get_source_fov(
  const gvr_buffer_viewport *viewport
)
```
Retrieves the field of view for the referenced buffer region.

This is a helper that converts the stored projection matrix to a field of view. Note that if the previously set projection matrix cannot be expressed as a view frustum aligned with the eye's optical axis, the result will be incorrect.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | The field of view of the rendered image, in degrees. |

### gvr_buffer_viewport_get_source_uv

```
gvr_rectf gvr_buffer_viewport_get_source_uv(
  const gvr_buffer_viewport *viewport
)
```
Gets the UV coordinates specifying where the output buffer is sampled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | UV coordinates as a rectangle. |

### gvr_buffer_viewport_get_target_eye

```
int32_t gvr_buffer_viewport_get_target_eye(
  const gvr_buffer_viewport *viewport
)
```
Gets the target logical eye for the specified viewport.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | Index of the target logical eye for this viewport. |

### gvr_buffer_viewport_get_transform

```
gvr_mat4f gvr_buffer_viewport_get_transform(
  const gvr_buffer_viewport *viewport
)
```
Gets the matrix that positions the viewport in eye space.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | |
| **Returns** | Matrix that transforms a quad with vertices (-1, -1, 0), (1, -1, 0), (-1, 1, 0), (1, 1, 0) representing the viewport contents to its desired eye space position for the target eye. |

### gvr_buffer_viewport_list_create

```
gvr_buffer_viewport_list * gvr_buffer_viewport_list_create(
  const gvr_context *gvr
)
```
Creates a new, empty list of viewports.

The viewport list defines how the application's rendering output should be transformed into the stabilized, lens-distorted image that is sent to the screen.

The caller should populate the returned viewport using one of:

- [gvr_get_recommended_buffer_viewports()](https://developers.google.com/vr/reference/android-ndk/group/base#group__base_1ga21cff221055d2b7ed7c48a55b4a0b1eb)
- [gvr_get_screen_buffer_viewports()](https://developers.google.com/vr/reference/android-ndk/group/base#group__base_1gae5e37d75f0ae1554943f2a68978207eb)
- [gvr_buffer_viewport_list_set_item()](https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga39c1a62293bbe2ca0eda8944041fcf9f)

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `gvr` | Pointer the gvr instance from which to allocate the viewport list. | |
| **Returns** | Pointer to an allocated gvr_buffer_viewport_list object. The caller returned object when it is no longer needed. |

### gvr_buffer_viewport_list_destroy

```
void gvr_buffer_viewport_list_destroy(
  gvr_buffer_viewport_list **viewport_list
)
```
Destroys a gvr_buffer_viewport_list instance.

The parameter will be nulled by this operation.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport_list` | Pointer to a pointer to the viewport list instance to be destroyed and nulled. | |

### gvr_buffer_viewport_list_get_item

```
void gvr_buffer_viewport_list_get_item(
  const gvr_buffer_viewport_list *viewport_list,
  size_t index,
  gvr_buffer_viewport *viewport
)
```
Retrieve a buffer viewport entry from a list.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport_list` | Pointer to the previously allocated viewport list. | | `index` | Zero-based index of the viewport entry to query. Must be smaller than the list size. | | `viewport` | The buffer viewport structure that will be populated with retrieved data. | |

### gvr_buffer_viewport_list_get_size

```
size_t gvr_buffer_viewport_list_get_size(
  const gvr_buffer_viewport_list *viewport_list
)
```
Returns the size of the given viewport list.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport_list` | Pointer to a viewport list. | |
| **Returns** | The number of entries in the viewport list. |

### gvr_buffer_viewport_list_set_item

```
void gvr_buffer_viewport_list_set_item(
  gvr_buffer_viewport_list *viewport_list,
  size_t index,
  const gvr_buffer_viewport *viewport
)
```
Update an element of the viewport list or append a new one at the end.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport_list` | Pointer to a previously allocated viewport list. | | `index` | Index of the buffer viewport entry to update. If the `viewport_list` size is equal to the index, a new viewport entry will be added. The `viewport_list` size must *not* be less than the index value. | | `viewport` | A pointer to the buffer viewport object. | |

### gvr_buffer_viewport_set_external_surface_id

```
void gvr_buffer_viewport_set_external_surface_id(
  gvr_buffer_viewport *viewport,
  int32_t external_surface_id
)
```
Sets the ID of the externally-managed Surface texture from which this viewport reads.

The ID is issued by GvrLayout. If this viewport does not read from an external surface, this should be set to GVR_EXTERNAL_SURFACE_ID_NONE, which is also the default value. If it does read from an external surface, set this to the ID obtained from GvrLayout and set the source buffer index to the special value GVR_BUFFER_INDEX_EXTERNAL_SURFACE.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `external_surface_id` | The ID of the surface to read from. | |

### gvr_buffer_viewport_set_opacity

```
void gvr_buffer_viewport_set_opacity(
  gvr_buffer_viewport *viewport,
  float opacity
)
```
Sets the opacity to perform on the specified viewport.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `opacity` | Opacity that will be applied per viewport. It should be within \[0,1\], default to be 1. | |

### gvr_buffer_viewport_set_reprojection

```
void gvr_buffer_viewport_set_reprojection(
  gvr_buffer_viewport *viewport,
  int32_t reprojection
)
```
Sets the type of reprojection to perform on the specified viewport.

Viewports that display world content should use full reprojection. Viewports that display head-locked UI should disable reprojection to avoid excessive judder. The default is to perform full reprojection.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `reprojection` | Type of reprojection that will be applied to the passed viewport. | |

### gvr_buffer_viewport_set_source_buffer_index

```
void gvr_buffer_viewport_set_source_buffer_index(
  gvr_buffer_viewport *viewport,
  int32_t buffer_index
)
```
Sets the buffer from which the viewport reads its undistorted pixels.

To use the contents of the external surface as buffer contents, associate an external surface with the viewport by calling [gvr_buffer_viewport_set_external_surface_id()](https://developers.google.com/vr/reference/android-ndk/group/viewport#group__viewport_1ga0291753aff748fdc607988644fdadf63), then call this function and pass GVR_BUFFER_INDEX_EXTERNAL_SURFACE.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `buffer_index` | The index of the source buffer. This is either an index in the list of buffer specs that was passed to [gvr_swap_chain_create()](https://developers.google.com/vr/reference/android-ndk/group/swap-chain#group__swap__chain_1ga423d0cba3833a31d9ffe3a3d8c9bac53), or GVR_BUFFER_INDEX_EXTERNAL_SURFACE. | |

### gvr_buffer_viewport_set_source_fov

```
void gvr_buffer_viewport_set_source_fov(
  gvr_buffer_viewport *viewport,
  gvr_rectf fov
)
```
Sets the field of view for the viewport contents.

This is a helper that sets the projection matrix in such a way that the viewport's contents fill the specified FOV around the eye's optical axis.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `fov` | The field of view to use when compositing the rendered image, in degrees. | |

### gvr_buffer_viewport_set_source_layer

```
void gvr_buffer_viewport_set_source_layer(
  gvr_buffer_viewport *viewport,
  int32_t layer_index
)
```
Sets the layer in a multiview buffer from which the viewport should sample.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `layer_index` | The layer in the array texture that distortion samples from. Must be non-negative. Defaults to 0. | |

### gvr_buffer_viewport_set_source_uv

```
void gvr_buffer_viewport_set_source_uv(
  gvr_buffer_viewport *viewport,
  gvr_rectf uv
)
```
Sets the UV coordinates specifying where the output buffer should be sampled when compositing the final distorted image.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `uv` | The new UV coordinates for sampling. The coordinates must be valid, that is, left \<= right and bottom \<= top. Otherwise an empty source region is set, which will result in no output for this viewport. | |

### gvr_buffer_viewport_set_target_eye

```
void gvr_buffer_viewport_set_target_eye(
  gvr_buffer_viewport *viewport,
  int32_t index
)
```
Sets the target logical eye for the specified viewport.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `index` | Index of the target logical eye. | |

### gvr_buffer_viewport_set_transform

```
void gvr_buffer_viewport_set_transform(
  gvr_buffer_viewport *viewport,
  gvr_mat4f transform
)
```
Sets the matrix that positions the viewport in eye space.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `viewport` | The buffer viewport. | | `transform` | Matrix that transforms a quad with vertices (-1, -1, 0), (1, -1, 0), (-1, 1, 0), (1, 1, 0) representing the viewport contents to its desired eye space position for the target eye. | |