Display +Control and Mapping in the Window Server Client

The CWsScreenDevice Window Server client-side API has +a GetInterface() function, which you can use to return +pointers to the MDisplayControl and MDisplayMapping interfaces +or null if the interface is not supported. For example:

In addition, CWsScreenDevice provides the IsCurrentModeDynamic() and IsModeDynamic() functions +for querying whether the current screen mode and a given screen mode are dynamic. +If a screen mode is dynamic, the application extent always fills the full +UI space and the area returned by CWsScreenDevice::SizeInPixels() always +matches the actual resolution that is in use. However, the MDisplayMapping interface +also provides features that enable you to draw outside the application UI +extent.

MDisplayControl

The MDisplayControl interface +provides Window Server clients with functions for setting and getting the +current display configuration, getting a list of available resolutions and +enabling display change event notifications (EEventDisplayChanged). +The following diagram shows the class hierarchy.

+ Display control class diagram + +

Once you have obtained +the MDisplayControl interface, you can call GetResolutions() on +it. For example:

// Get available resolutions +RArray<MDisplayControl::TResolution> resolutions; +User::LeaveIfError(iDisplayControl->GetResolutions(resolutions)); + +// Use resolution list. + +

You can use the EnableDisplayChangedEvents() function +to register for notifications of the EEventDisplayChanged event. +This is generated when the display device is attached or detached or there +is a change in the current resolution, the resolution list or the current +configuration. For example, this can be generated by a render stage or the +composition engine in response to a hardware event (such as an external display +being connected or disconnected). The event is sometimes, but not always, +triggered by a change in the screen mode.

There are therefore two +aspects to the event in that it can be triggered by a display change or a +configuration change. Typically you check the event against the previous one +to see what has changed.

The following table provides a summary of +how this event compares to EEventScreenDeviceChanged.

+ + + +Action +EEventScreenDeviceChanged +EEventDisplayChanged + + + + +

Screen mode change

Always triggers this event

Triggers this event only if it causes a change in the configuration.

+ + +

Display configuration change

Generally does not trigger this event

Generally triggers this event

+ + + +

The following example first registers for notification of EEventDisplayChanged events +and then changes the screen mode. The second part illustrates a simplified +handler for the events. It demonstrates checking the event against the previous +one to see whether the resolution or configuration has changed.

// Establish connection and get display control interface. + +iDisplayControl->EnableDisplayChangeEvents(ETrue); + +iScreenDevice->SetScreenMode(2); // Number depends on WSINI.INI config. +iScreenDevice->SetAppScreenMode(2); // Ensure application windows are + // shown in the new mode. +... + +// Simplified event handler. +TWsEvent event; +iSession.GetEvent(event); + +switch (event.Type()) + { + case EEventScreenDeviceChanged: + { + TSize screenSize = iScreenDevice->SizeInPixels(); + // Re-layout windows for new application screen dimensions + } + break; + case Redraw: + { + // Draw content of window + } + break; + case EEventDisplayChanged: + { + TWsDisplayChangedEvent* newEvent; + newEvent = event.DisplayChanged(); + + if (newEvent->iResolutionListChangeId != + iLastEvent.iResolutionListChangeId) + { + // ... + } + + if (newEvent->iConfigurationChangeId != + iLastEvent.iConfigurationChangeId) + { + TDisplayConfiguration config; + User::LeaveIfError( + iDisplayControl->GetConfiguration(config))); + // Handle updated configuration + // May be entirely handled by screen device changed event + } + iLastEvent = *newEvent; + } + break; + }

Here is an example of setting a new display resolution:

TDisplayConfiguration config; +config.SetResolution(TSize(1280, 720)); +config.SetRotation(MDisplayControl::ERotation180); + +User::LeaveIfError(iDisplayControl->SetConfiguration(config)); +

MDisplayMapping

The MDisplayMapping interface +enables Window Server clients to map between coordinate spaces, allowing for +translation and scaling of coordinates. For example, suppose an application +is to draw a virtual keyboard outside of the application's extent. This requires +knowing the extent of both the application and the full UI area. The application +can use the MDisplayMapping interface to get this information, +so that the virtual keyboard can be drawn within the full UI area but outside +of the application's extent.

+ Display mapping class diagram + +

The MDisplayMapping interface is very +flexible. UIDs are used to signify the application UI coordinate space, the +full UI space, the composition/display coordinate space (which may be a different +scale to the UI coordinate space) and the Direct Screen Access (DSA) space +(which may match the full UI space, or be offset relative to the application +UI space).

The MapCoordinates() function takes +a rectangle, a source space and a target space and returns the correspondingly +mapped rectangle in the target space. To map a point, use a rectangle with +a width and height of one pixel, because the scaling between UI space and +composition/display space may enlarge (or sometimes reduce) the rectangle’s +size.

For example, consider the following diagram, in which the outer +rectangle represents the display area and the inner one represents the application +space (screen mode).

+Display area and application extent + +

The display resolution is 1280 x 720, the application size is 176 +x 208 and a virtual resolution of 426 x 240 has been introduced, which gives +a scaling factor of three in each direction. All pixels are approximately +square, for simplicity. The application area has been centered in the display, +giving an X offset of (426-176)/2 and a Y offset of (240-208)/2, +or (125, 16).

To put a window on screen to fill the display, create +a rectangle positioned at (0,0) with a size of the current resolution (426 +x 240). Then pass this in with a source space of the full UI and target space +of the application. This results in a rectangle of the same size but at offset +(125,16).

In addition, to use an external surface at the real resolution, +pass this rectangle in with a source space of the application UI and a target +space of the composition/display. This results in a rectangle with size of +1280 x 720, which you can then use when creating the surface. Because the +UI surface and external surface are scaled independently, the UI memory requirements +can remain low, even with high resolution video, viewfinder and games. For +an example code snippet, see External +Surfaces Overview.