just say no to GAPI – What you need to know about AllKeys and input management.

The Games API (GAPI) was a technology that allowed Windows Mobile 2003 applications to quickly draw graphics onto the device screen. It also contained functions that allowed an application to request all button press messages, even the ones that were normally intercepted by the Windows Mobile operating system.

The graphics component of GAPI was replaced by DirectDraw (which allowed hardware acceleration) in Windows Mobile 5.0. Application compatibility was maintained so that older programs would still work.

Most of the reference material for GAPI was removed from the Windows Mobile 6.1 documentation set, although the input functions were kept, so that applications could still request all key and button presses.  Application compatibility was maintained for this release as well.

This is all changing for the next generation of Windows Mobile, Windows Mobile 6.5.  Although some devices may still support GAPI, there is no longer a requirement for device manufacturers or mobile operators to ship or test for compatibility with GAPI.  This means that applications that require GAPI will provide an unpredictable experience for users on Windows Mobile 6.5 devices.

Another important change is that acceptance to the Windows Marketplace for Mobile and Designed for Windows Mobile certification requires no application dependencies on GAPI.

In order to replace the input functionality that GAPI once provided, a new keyboard API function is being made public.  This function is AllKeys() , and is defined below.  One great thing about this substitution is that AllKeys has been a part of Windows Mobile as long as GAPI, and is actually the API call that GAPI wrapped in order to publicly expose this functionality. This means that the transition to AllKeys should be easy, and backwards compatibility should be maintained.

You can migrate your input code to AllKeys in the following way:

Replace:

·         GXOpenInput() with AllKeys(TRUE).

·         GXCloseInput() with AllKeys(FALSE).

While AllKeys is set to true, all key presses will be sent to your application for handling.

Since GXOpenInput and GXCloseInput were simply wrappers for a call to AllKeys, so this substitution should cause no change in behavior in your programs.

The following is the definition of the new AllKeys API.

AllKeys

This function allows your programs to request that all key presses be sent directly to the requesting application. Normally some buttons are intercepted by the operating system for its own use, but games and input - intensive applications may want access to these buttons for their own use.

Syntax

BOOL AllKeys(

     BOOL bAllKeys

);

Parameters

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Sample Code

The following C++ code illustrates how to use AllKeys. In the application that this sample is taken from, a check box is used to set AllKeys to true or false.

// process checkbox

case IDC_ALL_KEYS_CHECK_BOX:

if (g_AllKeys == true)

    {

    // Allow the OS to intercept some button presses

     AllKeys(FALSE);

    g_AllKeys = false;

    // set button state

    SendMessage(hwndCtl,BM_SETCHECK, BST_UNCHECKED,0);

    }

else

    {

    // Do not allow os to intercept button presses

    AllKeys(TRUE);

    g_AllKeys = true;

    //set button state

    SendMessage(hwndCtl,BM_SETCHECK, BST_CHECKED,0);

    }

Requirements

OS Versions: Windows Mobile 2003 and later.

Header: Winuser.h.

Comments

• Anonymous
  May 06, 2009
  Good information to have!  After seeing AllKeys reference in the Marketplace requirements I was looking for documentation on it and could not find it anywhere!

• Anonymous
  May 06, 2009
  You seem to be saying "The input bits of GAPI were supported and documented and certified in 6.1, but they'll stop being all those things as of 6.5. You need to update your apps." Fair enough, but:  a) You say that GX(Open|Close)Input() calls always just delegated the actual work to AllKeys() anyway; so as an app developer I'm not particularly worried that the handset operators won't be testing or certifying that the GX* API works okay on their handsets :-) I could be missing something here, but this is your main "big stick to motivate developers to update", so let me know if there's something else I should take into account.  b) Following on, how much of a maintenance burden are you really carrying for the two GX* API calls you really want to retire? Is the benefit to MS as the maintainer really big enough to justify the impact on the customers and developer ecosystem of deprecating this API as part of an OS point release?

• Anonymous
  May 07, 2009
  The quick answer is that GAPI was not just about input - in fact input is just a small part of what GAPI provided.   Most of GAPI was concerned with fast access to the device screen, and those functions were improved on and replaced by DirectDraw some time ago. Supporting the GAPI API costs money, not just to Microsoft, but more importantly to our partners, and since the API has been replaced by superior technologies (DirectDraw) or equal technologies (AllKeys), that extra expense could no longer be justified. --Norm

• Anonymous
  May 08, 2009
  DirectDraw for blitting? I'd rather not..... the performance is sub-par compared to my own assembler optimized software blitters. So ok if you drop the GAPI calls will GetRawFramebuffer still be supported?

• Anonymous
  May 08, 2009
  Try DirectDraw->Lock() to get direct access to the primary display buffer from within DirectDraw. Also, remember that as more and more devices provide hardware acceleration, DirectDraw blits will take advantage of that acceleration, where custom code most likely will not.

• Anonymous
  May 08, 2009
  I'm well aware of locking a DDraw surface to get access to it.  Up to now, I've used PocketHAL as my framebuffer manager so whatever it does behind the scenes, I'm content with. As for hardware blitting... it's far to limited from what I've seen.  My blitters can do - alpha (per-pixel, constant and keyed constant) as well as additive, subtractive and modulative blending both with and without keying.  Same goes for scaled and rotated blits too.

• Anonymous
  May 13, 2009
  I have to agree with Phred, GetRawFramebuffer is basically the only API call we use in our project to manage the presentation layer. It is many times faster than DirectDraw and much more flexible. Here where I work we have decided to skip any b-plan: if GetRawFramebuffer goes away, so will my company.

• Anonymous
  May 14, 2009
  Still on a HTC I fail to capture the "home" hardware key with AllKeys(true); when sniffing the windows message pump, any suggestion ? Would be much appreciated :)

• Anonymous
  May 14, 2009
  Hello, Tyua, I have just posted a new article on input management, and have also posted sample code that does what you are asking about.  Take a look at: http://blogs.msdn.com/windowsmobile/archive/2009/05/14/twisted-pixels-4-a-button-mashers-guide-to-input.aspx http://code.msdn.microsoft.com/tpix

• Anonymous
  May 14, 2009
  Hello, Klaus, What are your specific objections to directly using the buffer returned by "DirectDraw->Lock()"?

• Anonymous
  May 14, 2009
  Hello, Phred, It sounds like you have no dependency on GAPI at all. (PocketHAL is advertised as a replacement for GAPI), so my guess is that you will not see much change in your apps as long as PocketHAL runs on 6.5 - I don't use it myself, so I can't speak for that. The additional functionality in your custom blitters sound awesome. Ever think of posting them and supporting the community?

• Anonymous
  May 14, 2009
  Thank you nsohl for the code sample you provided, unfortunately it fails to catch the button I try to get. I figured before your post how to intercept key events from the message pump, but still your code sample fails to catch the "home" button on my HTC touch HD. So i have no way atm to disable the "home" button which hides my application when the user presses it.

• Anonymous
  May 15, 2009
  Thanks for letting me know.  I will look into it and see if I can get an answer to you.

• Anonymous
  May 18, 2009
  We have a rather large code repository and would not like to hunt for GetRawFramebuffer, replace with IDirectDrawSurface->Lock and associated setup, then debug everything from scratch. If we have to rewrite our display abstraction and interfacing code, then we will go OpenGL ES, and drop our WinCE first policy. bye, Klaus

• Anonymous
  May 24, 2009
  Klaus, even if you decided so, you couldn't simply go the DirectDraw->Lock. Your app would not receive WM_ACTIVATE-alike events and it would also run slower. The WinCE team has really messed up the API, this time.

• Anonymous
  May 29, 2009
  Klaus, In my experience, the performance lost by using DD->Lock() is very small, and I've never seen a significant framerate hit after moving some personal projects to DD on WinMo. That said, I think going OGLES and dropping WinMo as your primary platform is a good idea. Much better to do OGLES on iPhone while we wait for MS to catch up. MS, I think it would have been a fantastic idea to mandate minimum DX9-level GPU's in WinMo 6.5. -Kevin

• Anonymous
  June 01, 2009
  Is there any way to disable/lock the camera button on HTC S710 with AllKeys(true). I tried it but it disables all keys without the camera button and function keys on qwerty keyboard. Please let me know

• Anonymous
  June 02, 2009
  Here's an update to Tyua and perhaps to Harshal- There is an issue with a driver used on some of the HTC phones that allows the home button to over-ride AllKeys.  This will be fixed in future releases.  Unfortunatly there does not seem to be a work-around. Harshal - if I understand your question, AllKeys is not intercepting the camera buttons or the keyboard function keys on the S710 - is that correct?  In my testing, I have not had this issue, but I have not tested the specific device you mention. I'l see if I can track one down and will let you know what I learn.

• Anonymous
  June 02, 2009
  Thank you nsohl for the reply. I think what you understand is correct. Let me clear my question again. My requirement is to lock down the windows mobile device completely by my application. In that case all buttons should be locked and should not work. Firstly, I used GXOpenInput() from GAPI. Then I found that it is depricated, so I used AllKeys(true) from DirectDraw to lock down buttons. Then I found that all keys on keypad and home, back, call buttons are locked, but the camera button on right hand top is still working and opens the camera when user press it. Also, the function keys on QWERTY keyboard are working. So I want the solution to lock these buttons. Please let me know how to acheive this programatically. I am using HTC S710 device and .Net for programming.

• Anonymous
  June 04, 2009
  Hi Don't know whether that's right place to ask. It seems that my fairly new Toshiba G810 WM 6.1 phone doesn't support PocketHAL which is used by DirectDraw, and all programs that use it just don't work. Here is their support answers http://www.discuss.com.hk/archiver/?tid-8901117.html So I have several questions about it: Is it required for vendor to support DirectDraw? If yes could Microsoft press them into making an update that supports it? If no is there a chance that it could be taken from some other device? Or is there some reference source code for PocketHal driver that could be adapted to this phone?

• Anonymous
  June 08, 2009
  "Just Say No To GAPI" I just downloaded the official 6.5 emulator images, and they still include a fully working gx.dll GAPI library. So it seems that the 6.5 emulators still say "Yes" to GAPI. So for anyone wondering why their GAPI dependent applications still work in the 6.5 emulators, you now know why...