[Development] More flexible window orientation API

[Samuel Rødal]

On 01/25/2012 11:35 AM, Alan Alpert wrote:
> On Tue, 17 Jan 2012 21:58:29 ext Samuel Rødal wrote:
>> Hi,
>>
>> we're working toward having a flexible yet simple API for window
>> orientations. It's important that the QWindow orientation API is
>> flexible enough to handle all use cases, whereas the APIs on top (in Qt
>> components for instance) can offer some more convenience for application
>> developers.
>>
>> We've found that the current QWindow::setOrientation() API isn't
>> sufficient to express all the different ways of doing orientation.
>> Namely, it currently only allows you to tell the windowing system /
>> compositor about how the contents of the window are rendered, and not
>> how the window buffer itself should be interpreted. It's not always
>> desirable to explicitly rotate the contents of the window, sometimes
>> it's practical to be able to use a different buffer layout instead. As
>> an example, a game being ported to a portrait device might still want to
>> use a landscape buffer layout, if the game engine design makes it hard
>> to rotate the rendered output to fit a portrait buffer layout. For a
>> raster based game there are performance costs due to having to do a
>> 90-degree rotation.
>>
>> So we should support both approaches, having a way to hint to the
>> compositor both the window orientation and the content orientation.
>
> What happens if you set both? Or set one but query the other?

If you set both you need to rotate your content with the delta between 
your set contentOrientation() and your windowOrientation(). The 
QScreen::angleBetween() etc helpers are used for this.

If you want a static landscape buffer layout, you should probably set 
both, so that you don't need to rotate the contents.

> Examples: That landscape 2D game sets the window orientation, what if you
> query content orientation?

It should set both. Otherwise the compositor will assume that even 
though the window's buffer layout is in landscape, and is rotated in 
such a way as well, it has portrait contents and thus compositor popups 
should be shown in portrait as well.

> What if that game then gains it's own rotation, but bases it off landscape for
> portability? So it sets window orientation to landscape and content
> orientation to portrait?

Yep, that should work.

> And for completeness, a contrived application sets content orientation but is
> in a contrived window manager that only works off window orientation.

The window manager only cares about content orientation for popups etc. 
If however the platform says that the window manager supports a given 
window orientation (by requestWindowOrientation() returning true), then 
the platform guarantees that the window manager will properly rotate the 
window and translate incoming mouse and touch events.

--
Samuel