GDF Delivery and Localization

  • Article

This section generally describes Games Explorer, and describes how you can get started with a typical installation scenario. Windows Games Explorer (available on Windows starting with Vista) requires that game definition files (GDF) and associated icons conform to the following conventions to allow for proper, trusted behavior and to facilitate localization.

Delivering a Game Definition File

Game titles can register themselves with Games Explorer by providing a game definition file (GDF) and a graphic (a thumbnail) that represents the game's box art. You must embed both the GDF and the graphic into a signed resource file.

Gameux.h contains two #define directives that identify the names of the resource file entries you must use to identify the GDF and the icon in your resource file. Include Gameux.h in your resource file to use these values, as shown in the following table.

Name Type Description
ID_GDF_XML DATA Name of the game's GDF file
ID_GDF_THUMBNAIL DATA Name of the game's icon bitmap file

Game Definition File Localization

If a game is localized for various markets, you should specify different Game Definition Files and images for each supported locale. You can do this manually or automatically by using the Game Definition File Editor.

To localize GDF files

  1. In the resource file, define sections for all supported languages, bracketing each section with:

    #if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_XXX)

    Where XXX is a three letter language specifier. For example, NEU stands for language neutrality, FRA for French, and ENU for English. For more details on language strings, see Language and Country/Region Strings

  2. In each section, set the appropriate language ID for the locale inside the resource file.

    For example:

    LANGUAGE LANG_FRENCH, SUBLANG_FRENCH

    For information how to specify a language, see Language Identifier Constants and Strings.

    Note

    To specify a language neutral locale in a GDF file, use: 

             LANGUAGE LANG_NEUTRAL,  SUBLANG_DEFAULT

  3. In each language section of the resource file, assign the location of the locale-specific GDF file and game bitmap to ID_GDF_XML and ID_GDF_THUMBNAIL, respectively.

Games Explorer automatically selects the properly localized GDF and thumbnail resource, depending on the system's current language setting.

Thumbnail Formats

The file format of the thumbnail graphic can be one of several values:

  • Bitmap (BMP)
  • Graphics Interchange Format (GIF)
  • Joint Photographic Experts Group (JPEG)
  • Exchangeable Image File (Exif)
  • Portable Network Graphics (PNG)
  • Tagged Image File Format (TIFF)

PNG is recommended. The built-in transparency in the PNG format allows the box art to attain the cleanest look in Games Explorer.

The recommended size for your box art graphic is 256×256 pixels. The image will be used for the main box art at that size, but it will also be scaled down automatically to 48×48 to be used as a smaller icon. This means you should test your graphic at the smaller size to ensure it scales well.

GDF Resource Script Example

The following code is an example of a resource script that includes localized GDFs and thumbnails for several languages.

/////////////////////////////////////////////////////////////////////////////
// Note! We do not show the other resource stuff that really should be here,
//like the VERSION INFORMATION.  Putting this into every executable is a superior idea!

#include "resource.h"
#include "gameux.h"

#define APSTUDIO_READONLY_SYMBOLS
#include "afxres.h"
#undef APSTUDIO_READONLY_SYMBOLS

/////////////////////////////////////////////////////////////////////////////
// Neutral resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_NEU)
#ifdef _WIN32

LANGUAGE LANG_NEUTRAL, SUBLANG_DEFAULT     //      Compatible with Vista and Other Windows Version

#endif
#pragma code_page(1252)
#endif //_WIN32

ID_GDF_XML          DATA        "D:\\GameInstall\\gdfmaker_neutral.gdf"
ID_GDF_THUMBNAIL		DATA				"D:\\GameInstall\\boxart_neutral.png"

#endif    // Neutral resources
/////////////////////////////////////////////////////////////////////////////
// French (France) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_FRA)
#ifdef _WIN32
LANGUAGE LANG_FRENCH, SUBLANG_FRENCH
#pragma code_page(1252)
#endif //_WIN32

ID_GDF_XML              DATA                    "D:\\GameInstall\\gdfmaker_fr.gdf"
ID_GDF_THUMBNAIL		    DATA				            "D:\\GameInstall\\boxart_fr.png"

#endif    // French (France) resources
/////////////////////////////////////////////////////////////////////////////


/////////////////////////////////////////////////////////////////////////////
// English (U.S.) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENU)
#ifdef _WIN32
LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
#pragma code_page(1252)
#endif //_WIN32

ID_GDF_XML          DATA        "D:\\GameInstall\\gdfmaker_us.gdf"
ID_GDF_THUMBNAIL		DATA				"D:\\GameInstall\\boxart_us.png"

#endif    // English (U.S.) resources
/////////////////////////////////////////////////////////////////////////////
  • Games Explorer Programming Guide
    Contains conceptual topics about how to interact with Windows Games Explorer, a feature available on Windows Vista and Windows 7