GAPI on the Motorola Q: what developers need to know

[Guest The PocketTV Team]

Game developers using GAPI - The Game API - (directly or through other libraries) may have problems on the Motorola Q.

That's because the engineers who wrote the video drivers for this device made a very questionable design choice, reminiscent of the iPaq 3800.

If you call the GAPI routines on the Motorola Q, they will tell you that:

1) the screen size is width=176 and height=220 (in fact the display on the Motorola Q is Landscape with width=320 and height=240).

2) GAPI is using a DRAM buffer, i.e. you cannot write directly in the raw frame buffer with GAPI, rather GAPI GXBeginDraw will return you the address of a 176x220 memory buffer, which will be copied in the real display frame buffer when you call GXEndDraw.

Consequences:

1) Applications/games using GAPI on this device can only use a small part of the display (size 176x220), rather than the entire screen.

2) Applications/games using GAPI will be much slower than they should be because each call to GXEndDraw will do a copy of the DRAM memory buffer in the display frame buffer.

3) Applications that use GAPI incorrectly, e.g. that don't call GXEndDraw at the end of the drawing cycle, will not work at all on the Motorola Q.

Why did they implement GAPI this way?

Because they were affraid that by implementing GAPI correctly (i.e. providing the actual frame buffer access and indicating the actual frame buffer size of 320x240), they would break of a lot of existing code.

Theye were affraid that games not expecting a Smartphone with Landscape screen would not directly work on the Motorola Q, until they are ported / adapted to this new device.

But in fact by making this poor implementation choice, Motorola made it harder to port GAPI-based applications that want to take advantage of the full screen size of their device. Motorola did not realize that adapting applications to take advantage of a new device is something we, developers, do all the times when a new device with special characteristics comes out (like the Landscape Pocket PCs), usually a few days after the release of a new popular device.

In fact a lot of Smartphones already have a 320x240 (Portrait) display, so the only difference in the Q is that the screen is oriented Landscape instead of Portrait. It would have been much better and simpler for developers if Motorola had implement GAPI correctly rather than tried to provide some dubious emulation mode for old applications designed only for older 176x220 Smartphones.

It's very similar to what HP did with GAPI on the iPAQ 3800, and to what Microsoft did with VGA-resolution Pocket PC's, and the result is the same: they made a mistake, and their bad decision is just making it harder on developers, not simpler, as they though.

So in essence, on the Q, Motorola broke GAPI, i.e. GAPI cannot be used for writing fast full-screen games and video applications, which is what this GAPI was designed for.

Workaround? Yes, luckily there is one!

Luckily the ExtEscape(hdc, GETRAWFRAMEBUFFER,...) is implemented (almost) correctly on the Motorola Q, and this call allows you to get the address of the raw frame buffer, its correct size, pitch, and pixel format.

On some devices, rfbi.wFormat is incorrectly set to 33 instead of 1 (FORMAT_565). They said this would be fixed, but apparently it is not fixed on our production device.

Other Caveats with Landscape-oriented Smartphones:

There are some issues that stem from poor specifications from Microsoft (i.e. not the fault of Motorola), for example, Microsoft never said if GETRAWFRAMEBUFFER (and GAPI) should consider that the device is in a particular orientation as defined by the ChangeDisplaySettingsEx API (e.g. DMDO_0 = "Native" orientation). In other word, the "width" returned by these API are the width of the displayin a certain orientation, but this orientation is not specified by MSFT, so it creates an ambiguity!

Also, Microsoft never said what DMDO_0 = "Native" orientation means on Smartphones. On Pocket PC, it always means "Portrait", even on devices that support Landscape). On Smartphone, it means "Portrait" on Portrait-oriented Smartphones, but on Landscape-oriented devices, rotation DMDO_0 sometimes means Landscape, sometimes means Portrait. Try on the Motorola Q and on the Landscape-oriented Smartphone emulator, you'll be surprised.

These poor specifications mean inconsistent implementations of the drivers on the various devices, and as a result, applications often need to do things differently (or make different assumptions) for each device.

Basically, when you call GETRAWFRAMEBUFFER (and GAPI), you never know if the data returned correspond to the "Native" orientation of the device, or to some other orientation. In general you can figure out if it matches the "Native" orientation by looking at the width and height, and comparing to GetSystemMetrics(SM_CXSCREEN) and GetSystemMetrics(SM_CYSCREEN), assuming you don't have a square display! But if it does not match the native orientation, then you have 50% chances to be wrong (between 90 deg left and 90 deg right). Ah, the joy of trying to write code that will work on all devices!

So be aware of that if you are trying to write portable, cross-device code using GETRAWFRAMEBUFFER or GAPI to display on Smartphones.

Edited June 16, 2006 by The PocketTV Team

[Guest muff]

Nice write up

Makes me wonder wether my new gfx engine works on this curiously messed up GAPI :/

And here I was thinking that life programming MS devices was already complicated enough

thanks again for sharing

[Guest joshbu]

Have you tried DirectDraw on the Q?

Note that GAPI is listed as a deprecated API on this page:

http://msdn.microsoft.com/library/default....APIOverview.asp

Edited June 16, 2006 by joshbu

[Guest andyraf]

The behavior of GAPI on the Q is as I would expect. Unfortunately, many/most GAPI Smartphone applications assume a 176x220 display in a specific format, and exposing any other format would break back-compat for existing apps. You can argue that GAPI and it's associated (existing) apps are poorly spec'd/designed (I wouldn't disagree), but the implementation on the Q is exactly as it should be given the back-compat situation.

As another poster mentioned, GAPI has been deprecated (for quite awhile now), so no one should be using GAPI for new applications. You shouldn't expect to see any new effort expended on GAPI beyond attempts to maintain some level of back-compat with existing well-behaved apps.

With respect to GETRAWFRAMEBUFFER, this is a call directly into the display driver. There's no guarantee that it will work on any specific device, nor is there a guarantee that it will return any specific resolution or format or that it will even continue to work in the future. I would recommend against using it if your goal includes cross-platform compatibility.

DirectDraw is the officially supported way of talking to the display, and will continue to get support/bug fixes/new features moving forward. If you find that DirectDraw doesn't work correctly/acceptably on the Q, I suspect Microsoft and Motorola would want to understand why (and please post your experiences/results for the rest of us as well).

[Guest The PocketTV Team]

The behavior of GAPI on the Q is as I would expect. Unfortunately, many/most GAPI Smartphone applications assume a 176x220 display in a specific format, and exposing any other format would break back-compat for existing apps. You can argue that GAPI and it's associated (existing) apps are poorly spec'd/designed (I wouldn't disagree), but the implementation on the Q is exactly as it should be given the back-compat situation.

I definitely don't agree with you there.

I think the correct way would have been for GAPI to return the real width and height of the display and to give access to the address of the raw frame buffer. All correctly programmed applications would then work correctly. The excuse of "back-compat situation" to justify breaking an API is lame, IMHO. Look at historical example of similar cases, like the iPaq 3800 and the VGA-res Pocket PCs.

You write: many/most GAPI Smartphone applications assume a 176x220 display in a specific format

Well, most GAPI Smartphone applications also run on Pocket PC, so most can also handle the QVGA case, if not out of the box, at least with very little development work, and many GAPI applications can handle any display size, e.g. video applications like TCPMP and PocketTV.

I'm sure that your statement is wrong, and that most GAPI games will be adapted to QVGA Smartphones and will handle 320x240. No-one really cares if old/unsupported applications will still run on the new devices. What people want is that applications that are supported will be correctly adapted to run on the device, and that the adaptation will be as easy as possible for the developer.

As another poster mentioned, GAPI has been deprecated (for quite awhile now), so no one should be using GAPI for new applications.

True, but unfortunately a number of recent devices either don't implement GETRAWFRAMEBUFFER at all [apparently MSFT does not test that it is correctly implemented in their Platform tests], or implement it wrong/incorrectly/broken, so on those devices, usually GAPI is the only way to get direct access to the frame buffer, when this is necessary for performances.

You shouldn't expect to see any new effort expended on GAPI beyond attempts to maintain some level of back-compat with existing well-behaved apps.

With respect to GETRAWFRAMEBUFFER, this is a call directly into the display driver. There's no guarantee that it will work on any specific device, nor is there a guarantee that it will return any specific resolution or format or that it will even continue to work in the future. I would recommend against using it if your goal includes cross-platform compatibility.

Unfortunately this is the only API available today that gives direct access to the video frame buffer. For some applications, like video players and games, it is critical, for performance reasons, to get direct access to the raw frame buffer. I know this is very low level, but using higher level API (e.g. GAPI of DDraw) can result in considerable degradation of video performances (e.g. 10 fps instead of 30 fps).

DirectDraw is the officially supported way of talking to the display, and will continue to get support/bug fixes/new features moving forward. If you find that DirectDraw doesn't work correctly/acceptably on the Q, I suspect Microsoft and Motorola would want to understand why (and please post your experiences/results for the rest of us as well).

DirectDraw is certainely the best way to access the display on devices that have hardware acceleration for displaying YUV planes. That's not the case on Smartphones. Using DirectDraw on Smartphone would imply additional buffer copies, causing very significant loss of performances for video applications. This is why we use GETRAWFRAMEBUFFER, and this is why GAPI was created. DirectDraw cannot replace those API unless there is some sort of hardware acceleration.

Edited June 17, 2006 by The PocketTV Team

[Guest The PocketTV Team]

Have you tried DirectDraw on the Q?

Note that GAPI is listed as a deprecated API on this page:

http://msdn.microsoft.com/library/default....APIOverview.asp

I am perfectly aware that GAPI has been deprecated.

On devices that do not have hardware acceleration, in order to get good performances when playing video, the only solution today is to use GETRAWFRAMEBUFFER when it is available and implemented correctly.

Using DirectDraw will never give you efficient performances except on devices that have video acceleration hardware, and that's not the case of the Q.

[Guest samj88]

I am perfectly aware that GAPI has been deprecated.

On devices that do not have hardware acceleration, in order to get good performances when playing video, the only solution today is to use GETRAWFRAMEBUFFER when it is available and implemented correctly.

Using DirectDraw will never give you efficient performances except on devices that have video acceleration hardware, and that's not the case of the Q.

From your post above, it sounds like you don't understand that DirectDraw allows you to get the raw frame buffer address, just as you have been doing with GAPI and with ExtEscape(GETRAWFRAMEBUFFER).

You don't need to use DirectDraw for blitting, page flipping, or YUV color conversion if you don't want to.

Create a DDraw primary surface, then lock it to get the pointer to the video memory that comprises the display, scribble into it, then unlock it. It's a pretty simple process.

[Guest The PocketTV Team]

From your post above, it sounds like you don't understand that DirectDraw allows you to get the raw frame buffer address, just as you have been doing with GAPI and with ExtEscape(GETRAWFRAMEBUFFER).

You don't need to use DirectDraw for blitting, page flipping, or YUV color conversion if you don't want to.

Create a DDraw primary surface, then lock it to get the pointer to the video memory that comprises the display, scribble into it, then unlock it. It's a pretty simple process.

Yes, I was not aware that you could just use DirectDraw to get access to the raw frame buffer.

We will certainely use DDraw in the future, in case GETRAWFRAMEBUFFER is not implemented, and for compatibility with future devices.

When PocketTV was originally developed, DirectDraw was not available under WindowsCE, which is why we did not use it.

[Guest neilarmstrong]

"The PocketTV Team": I am totally with you on everything you said. I experienced the same problems fixing my code to run on the Motorola Q. I'm pretty sure that all the Microsoft documentation for DMDO_0 says that it should be treated as the "native" orientation, it appears to me that Motorola have done something of a hack on a standard QVGA portrait screen and physically rotated it by 90degrees, then they've done some software hacks to get the screen into landscape mode. Basically my experience of updating my game engine was that they hadn't done things quite right.

BTW: Big thanks to Paul O'Brien for putting me in touch with Motorola, it helped in finding the bug in the ExtEscape function (as mention in PocketTV's original post).

When you're selling commercial software it makes sense to support as few installers as possible but target as many devices/operating systems as possible...hence some newer APIs seem attractive but aren't really a great option because you end up with multiple versions of an app...and that in turn becomes a support nightmare. My engine works on Pocket PC 2000 to Windows Mobile 5 devices with a single EXE...and you have to jump through a few hoops to get decent performance from each OS. If only it was as easy as ditching the old every time a new OS came along...but you'd be waving goodbye to a lot of potential customers :)

So...the only thing I haven't fixed on the Motorola Q is the handling of number key messages: VK_T0, VK_T1 etc. It appears that you have to press a numlock button first? I don't actually own a Q so all my testing has been thanks to customers in USA who are willing to sacrifice some of their time to help test. Not ideal...but thanks especially to Juan Gomez! Anyway...and help about the VK_T0 buttons would be great...

[Guest The PocketTV Team]

> I'm pretty sure that all the Microsoft documentation for DMDO_0 says that it should be treated as the "native" orientation

yes, but what is "native" orientation?

On Pocket PC, it is always Portrait (for Pocket PC with a rectangular display). For Pocket PC with a square display, "native" is the orientation used by default by the device, i.e. the orientation with D-pad buttons being under the screen.

But on Smartphone, what is "native" orientation?

Well, on "Portrait oriented" Smartphones, "native" orientation is Portrait.

But on "Landscape oriented" Smartphones, it is apparently not always Portrait, i.e. on the emulator it appears to be Landscape, while on the Motorola Q, it is Portrait. Who knows what it will be on future "Landscape oriented" Smartphones.

> it appears to me that Motorola have done something of a hack on a standard QVGA portrait screen and physically rotated it by 90degrees, then they've done some software hacks to get the screen into landscape mode. Basically my experience of updating my game engine was that they hadn't done things quite right.

Correct. This discrepency may be due to the fact that the Motorola Q is using an older version of the OS compared to the 320x240 Landscape Smartphone emulator:

The Motorola Q that we have is using OS 5.1.70 (Build 14523.1.3.0)

The 320x240(Landscape) WM5 Smartphone emulator is using OS 5.1.195 (Build 14847.2.0)

There are a number of things that work differently between the Emulator and the Motorola Q. For example, GetOpenFileName is implemented in the Emulator, but does not work on the Motorola Q.

> When you're selling commercial software it makes sense to support as few installers as possible but target as many devices/operating systems as possible...hence some newer APIs seem attractive but aren't really a great option because you end up with multiple versions of an app...

yes, i agree with all you say in your post. definitely it is a support nightmare when you have several different exe targetted to different versions of the OS, and the alternative is to try dynamically extracting the symbols from the DLL's when they are present, and this is not very practical either.

> If only it was as easy as ditching the old every time a new OS came along...but you'd be waving goodbye to a lot of potential customers :)

at one point you can reduce the frequency of upgrades for older versions of the OS, e.g. today Windows Mobile 2000 and 2002 count for a very marginal revenue, even 2003 and 2003SE are now small compared to WM5. of course customers with old versions of the OS won't be happy, but they certainely can understand the business issue of supporting obsolete devices...

> So...the only thing I haven't fixed on the Motorola Q is the handling of number key messages: VK_T0, VK_T1 etc. It appears that you have to press a numlock button first?

You have to press the "Function key" aka "Alt key" (at the bottom-left part of the keyboard, with a black half-disk on the key) before pressing a digit, if the keyboard mode is set to alphanumeric (e.g. when typing normal text).

you can also change the keyboard mode to ALT by pressing the "Alt key" twice, which will allow to type several digits in a raw.

> I don't actually own a Q so all my testing has been thanks to customers in USA who are willing to sacrifice some of their time to help test. Not ideal...but thanks especially to Juan Gomez! Anyway...and help about the VK_T0 buttons would be great...

I think you will get the exact same keyboard behavior by using the 320x240 Landscape Smartphone emulator, so you can probably test that with the emulator.

We were lucky enough to get a loaned device from Motorola, and that helped us a lot.

Edited June 25, 2006 by The PocketTV Team

[Guest Mohammed sadiq]

hi ,

1. how to solve the QWERTY keypad issue programatically . My app is fully number oriented .. how to make the default mode of the motorola Q keys to only numeric which should be generic to all devices ?

2. how to get the keycode of the keys . beacuse while testing in the Motorola Q devices , when i am trying to get the keycode , i got only "ProcessKey : 229" as keycode for all the keys . even in T-mobile Dash , its giving the same thing . how to get the keycode . then how the application can handle keypresses in windows mobile devices ?

waiting for some help

thanks

sadiq

[Guest zorba990]

I'm a bit late to this discussion.

I've got a Motorola Q and have been trying to get my direct screen code to work.

This code works fine on a 2003 pocket pc 16bpp 565.

ExtEscape succeeds, but returns height and width wrong (they are swapped).

Format returns 565 and 16bpp.

Unfortunately, simply swaping width and height along with the pitch produces a left-right flipped

image with all the wrong colors.

Before I embark on ripping up my code to support flipping this back and trying to fix up the

colors....am I doing something basically wrong? I'm trying to maintain one executable

for all devices but this (the Q) is proving to be a bear! Also, will it always be consistent

as far as left right swap? How to tell if otherwise?

thanks in advance...

[Guest The PocketTV Team]

you have to detect the Q and handle it with a special case, i'm affraid.

[Guest zorba990]

you have to detect the Q and handle it with a special case, i'm affraid.

Thanks. Is there a standard detection method? Like platform IDs or something?

[Guest The PocketTV Team]

Thanks. Is there a standard detection method? Like platform IDs or something?

SPI_GETOEMINFO

[Guest zorba990]

SPI_GETOEMINFO

Thanks again, it showed up as "MotoQ".

[Guest The PocketTV Team]

Thanks again, it showed up as "MotoQ".

yep. it's supposed to be different for every model. althought not always the case, but for the Q it works.

[Guest zorba990]

yep. it's supposed to be different for every model. althought not always the case, but for the Q it works.

Was able to flip it back, but haven't fixed up the colors yet. Tried a few

basic things but they've done something awful. I put in an SR to Motorola

just so they know that someone else is unhappy about this....

[Guest The PocketTV Team]

Was able to flip it back, but haven't fixed up the colors yet. Tried a few

basic things but they've done something awful. I put in an SR to Motorola

just so they know that someone else is unhappy about this....

you might have a bug on your side concerning colors. we never had any color-related problem with the Q.

[Guest zorba990]

you might have a bug on your side concerning colors. we never had any color-related problem with the Q.

Yup, my bad code...thanks! I should add that its at least 3-4 times faster this way than will GDI.

Edited June 20, 2007 by zorba990

[Guest jeiku]

RE: The original post.

That would probably explain why I cannot get spvDuke3d to run on my Motorola Q. I'm really bummed about this.

[Guest zorba990]

Yup, my bad code...thanks! I should add that its at least 3-4 times faster this way than will GDI.

I'm noticing that although direct screen writes seem to work fine on the

Treo 700p, I'm not getting a WM_ACTIVATE message when the phone

goes into its suspend state (the off button can invoke this or it can

invoke itself on a timer). So when the keylock dialog comes up,

Treo is automatically resuming my app, but I'm fighting the screen with that

dialog since my app was never suspended.

Is there a solution for this? The docs seems abit spotty about registering for

system power states where a suspended state is concerned.

[Guest zorba990]

Edited February 5, 2008 by zorba990

[Guest wipeout2097]

Hi everyone, first post. :)

I'm sorry that I bumped this thread. I have the Moto Q 9h and the display is garbled when running myDoomCe4.exe. Emulators either get the same result or crash complaining about cbPitch = 352 or whatever that is.

I tried everything: flashing WM 6.1, using GAPI from www.wincesoft.de, I'm going to install Windows Mobile 6 SDK and try recompile the Doom executable and emulators for which there's source code available. But after 2 weeks I just can't stand this anymore and there's always something in my way that makes me drop the ball out of frustration

Please help me. Thanks again