Starboard Module Reference: window.h

Provides functionality to handle Window creation and management.

Structs

SbWindowOptions

Options that can be requested at window creation time.

Members

Members
SbWindowSize
size
The requested size of the new window. The value of video_pixel_ratio will not be used or looked at.
bool
windowed
Whether the new window should be windowed or not. If not, the requested size is really the requested resolution.
const
char* name
The name of the window to create.

SbWindowPrivate

Private structure representing a system window.

SbWindowSize

The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window.

Members

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 a common case as devices often have more video decoding capabilities than graphics rendering capabilities (or memory, 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 could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f).

Functions

SbWindowCreate

Description

Creates and returns a new system window with the given options, which may be NULL. The function returns kSbWindowInvalid if it cannot create the requested SbWindow due to policy, unsatisfiable options, or any other reason.
If options are not specified, this function uses all defaults, which must work on every platform. In general, it defaults to creating a fullscreen window at the highest 16:9 resolution possible. If the platform does not support fullscreen windows, then it creates a normal, windowed window.
Some devices are fullscreen-only, including many production targets for Starboard. In those cases, only one SbWindow may be created, and it must be fullscreen. Additionally, in those cases, the requested size will actually be the requested resolution.
An SbWindow must be created to receive window-based events, like input events, even on fullscreen-only devices. These events are dispatched to the Starboard entry point.

Declaration and definitions

SB_EXPORT SbWindow SbWindowCreate(const SbWindowOptions* options);

#include "starboard/window.h"

SbWindow SbWindowCreate(const SbWindowOptions* /*options*/) {
  return kSbWindowInvalid;
}

Parameters

Parameters
const SbWindowOptions*
options
Options that specify parameters for the window being created.

SbWindowDestroy

Description

Destroys window, reclaiming associated resources.

Declaration and definitions

SB_EXPORT bool SbWindowDestroy(SbWindow window);

#include "starboard/window.h"

bool SbWindowDestroy(SbWindow /*window*/) {
  return false;
}

Parameters

Parameters
SbWindow
window
The SbWindow to destroy.

SbWindowGetPlatformHandle

Description

Gets the platform-specific handle for window, which can be passed as an EGLNativeWindowType to initialize EGL/GLES. This return value is entirely platform-specific, so there are no constraints about expected ranges.

Declaration and definitions

SB_EXPORT void* SbWindowGetPlatformHandle(SbWindow window);

#include "starboard/window.h"

void* SbWindowGetPlatformHandle(SbWindow /*window*/) {
  return NULL;
}

Parameters

Parameters
SbWindow
window
The SbWindow to retrieve the platform handle for.

SbWindowGetSize

Description

Retrieves the dimensions of window and sets size accordingly. This function returns true if it completes successfully. If the function returns false, then size will not have been modified.

Declaration and definitions

SB_EXPORT bool SbWindowGetSize(SbWindow window, SbWindowSize* size);

#include "starboard/window.h"

bool SbWindowGetSize(SbWindow /*window*/, SbWindowSize* /*size*/) {
  return false;
}

Parameters

Parameters
SbWindow
window
The SbWindow to retrieve the size of.
SbWindowSize*
size
The retrieved size.

SbWindowIsValid

Description

Returns whether the given window handle is valid.

Declaration

static SB_C_INLINE bool SbWindowIsValid(SbWindow window) {
  return window != kSbWindowInvalid;
}

Parameters

Parameters
SbWindow
window

SbWindowSetDefaultOptions

Description

Sets the default options for system windows.

Declaration and definitions

SB_EXPORT void SbWindowSetDefaultOptions(SbWindowOptions* options);

#include "starboard/window.h"

void SbWindowSetDefaultOptions(SbWindowOptions* /*options*/) {
}

Parameters

Parameters
SbWindowOptions*
options
The option values to use as default values. This object must not be NULL.