gf_display_set_mode()

Set the display mode

Synopsis:

#include <gf/gf.h>

int gf_display_set_mode( gf_display_t display,
                         int xres,
                         int yres,
                         int refresh,
                         gf_format_t format,
                         unsigned flags );

Arguments:

display

The handle for a display that you want to set the mode for.

xres, yres

The new screen resolution.

refresh

The new refresh rate.

format

The pixel format of the display; this pertains to the main layer only.

flags

No flags are currently defined; pass as 0.

Library:

gf

Description:

This function sets the display mode. Depending on the driver, when you call this function, some or all surfaces pertaining to the device may be destroyed. Futhermore, there may be multiple applications in the system which might be affected by the modeswitch.

---

Threads should not call this function between calls to gf_draw_begin() and gf_draw_end(), or a deadlock will occur.

---

It is up to you to ensure that all apps running on the display whose resolution has changed behave appropriately. A modeswitch could be dealt with in one of two ways:

1. Notification via IPC. Using an application-specific inter-process communication mechanism, the application that initiated the mode-switch notifies all other client applications in the system which may be rendering to this device, that a mode-switch has occured. Upon receiving notification, the applications destroy all their surfaces and re-created them, resizing them as required by the new display resolution.
2. Applications can detect if a surface has been destroyed when they attempt to render to it. For 2D rendering, gf_draw_begin() returns GF_ERR_SURFDESTROYED if the surface has been destroyed. For 3D rendering, eglSwapBuffers() returns EGL_FALSE, and generates the error EGL_BAD_SURFACE is generated.

   ---

   The vsync and gears sample applications shipped with QNX Advanced Graphics demonstrate the second method.

   ---

---

When a surface is destroyed, any layer which is displaying that surface is automatically disabled, and needs to be explicitly re-enabled by the application when the surface is re-created. This avoids temporarily displaying junk on the screen.

---

If Photon is part of the system, we recommend you initiate the mode-switch via the Photon API, to ensure that the Photon display is refreshed properly.

Returns:

GF_ERR_OK

Success.

GF_ERR_NOSUPPORT

The specified display mode isn't supported.

Classification:

QNX Graphics Framework

See also:

gf_display_query_mode(), gf_draw_begin()