Provides functionality to create and manage windows.

## Macros

### kSbWindowInvalid

Well-defined value for an invalid window handle.

## Typedefs

### SbWindow

A handle to a window.

#### Definition

    typedef SbWindowPrivate* SbWindow

## Structs

### SbWindowOptions

Options that can be requested at window creation time.

#### Members

- `SbWindowSize size`

  The requested size of the new window. The value of `video_pixel_ratio` is
  ignored.
- `bool windowed`

  Specifies whether the new window is windowed. If `false`, the requested size
  represents the requested resolution.
- `const char* name`

  The name of the window to create.

### SbWindowSize

The size of a window in graphics rendering coordinates. The width and height of
a window must correspond to the size of the backing graphics surface used for
drawing.

#### Members

- `int width`

  The width of the window in graphics pixels.
- `int height`

  The height of the window in graphics pixels.
- `float video_pixel_ratio`

  The ratio of video pixels to graphics pixels. This ratio must be applied
  equally to width and height, meaning the aspect ratio is maintained.

  A value of 1.0f means the video resolution is the same as the graphics
  resolution. This is the most common case.

  Values greater than 1.0f mean that the video resolution is higher (denser,
  larger) than the graphics resolution. This is common because devices often
  have greater video decoding capabilities than graphics rendering
  capabilities (due to memory constraints, etc.).

  Values less than 1.0f mean that the maximum video resolution is smaller than
  the graphics resolution.

  A value of `0.0f` means the ratio cannot be determined; it is assumed to be
  the same as the graphics resolution (i.e., `1.0f`).

## Functions

### SbWindowCreate

Creates and returns a new system window with the specified `options` (which can
be `NULL`). Returns `kSbWindowInvalid` if the window cannot be created due to
policy, unsatisfiable options, or other reasons.

If `options` are not specified, the function uses default values that must work
on all platforms. By default, it creates a fullscreen window at the highest
possible 16:9 resolution. If the platform does not support fullscreen windows,
it creates a standard windowed window.

Some devices (including many production targets for Starboard) only support
fullscreen windows. On these platforms, only one `SbWindow` can be created, and
it must be fullscreen. The requested size is treated as the requested
resolution.

You must create an `SbWindow` to receive window-based events (such as input
events), even on fullscreen-only devices. These events are dispatched to the
Starboard entry point.

- `options`: Options that specify parameters for the window being created.

#### Declaration

    SbWindow SbWindowCreate(const SbWindowOptions *options)

### SbWindowDestroy

Destroys `window`, reclaiming associated resources.

- `window`: The `SbWindow` to destroy.

#### Declaration

    bool SbWindowDestroy(SbWindow window)

### SbWindowGetDiagonalSizeInInches

Gets the size of the diagonal between two opposing screen corners.

Returns `0` if Starboard cannot determine the screen diagonal.

#### Declaration

    float SbWindowGetDiagonalSizeInInches(SbWindow window)

### SbWindowGetPlatformHandle

Gets the platform-specific handle for `window`, which can be passed as an
`EGLNativeWindowType` to initialize EGL/GLES. The return value is
platform-specific, with no constraints on expected ranges.

- `window`: The `SbWindow` to query.

#### Declaration

    void * SbWindowGetPlatformHandle(SbWindow window)

### SbWindowGetSize

Retrieves the dimensions of `window` and writes them to `size`. Returns `true`
if successful; otherwise, returns `false` and leaves `size` unchanged.

- `window`: The `SbWindow` to query.

- `size`: The destination buffer for the window size.

#### Declaration

    bool SbWindowGetSize(SbWindow window, SbWindowSize *size)

### SbWindowIsValid

Returns whether the given window handle is valid.

#### Declaration

    static bool SbWindowIsValid(SbWindow window)

### SbWindowSetDefaultOptions

Sets the default options for system windows in `options`.

- `options`: The destination buffer for the default options. Must not be `NULL`.

#### Declaration

    void SbWindowSetDefaultOptions(SbWindowOptions *options)