Displays

cerlib provides the necessary functions and data structures to query a system’s display(s).

A display has one or multiple modes that describe a resolution and refresh rate, and sometimes a special pixel density (DPI).

Obtaining information about displays is useful for e.g. providing the user a list of game resolutions to choose from. Another example would be to manually position and size the game’s window within specific display bounds, i.e. by using the Window::setPosition() and Window::setSize() methods.

This information is represented by the cer::DisplayMode structure.

struct DisplayMode {
    Option<ImageFormat> format;
    int width          = 0;
    int height         = 0;
    float refreshRate  = 0.0f;
    float contentScale = 0.0f;
};

Additionally, a display may have a special orientation, which is represented by the cer::DisplayOrientation enum.

enum class DisplayOrientation {
    Unknown          = 0,
    Landscape        = 1,
    LandscapeFlipped = 2,
    Portrait         = 3,
    PortraitFlipped  = 4,
};

To query the number of displays that are attached to a system, use the Game::displayCount() method.

The Game class further provides methods that take a display index and return corresponding information about it:

• Game::displayModes(displayIndex)
• Game::displayContentScale(displayIndex)
• Game::displayOrientation(displayIndex)

The following example loops through all displays and obtain such information for each of them.

auto displayCount = game.displayCount();

for (int i = 0; i < displayCount; ++i) {
    auto modes        = game.displayModes(i);        // : List<DisplayMode>
    auto contentScale = game.displayContentScale(i); // : float
    auto orientation  = game.displayOrientation(i);  // : DisplayOrientation

    // ...
}

Note
The display API will be improved in a future version, where such manual loops will not be necessary anymore. Instead, a list of Display structures is returned that contains all of a display’s relevant information.