Documentation on DC's Windows CE and Directx

I found this resource over the web. The webmaster of DCemu.co.uk (or someone else) should upload this document in a decent place where everyone can see it.

--Saoshyant

*~*

Windows CE for Dreamcast Toolkit
Microsoft and some of its partners are already using DirectX on Windows CE for several consumer devices. As we already mentioned, the first product to ship with support for Windows CE and DirectX was the Sega Dreamcast game console. Microsoft recently released the Windows CE for Dreamcast Toolkit to licensed developers. Windows CE for Dreamcast is an optimized version of the Windows CE operating system designed for the Dreamcast hardware. It includes all the tools needed to develop for this SH4 processor-based platform in Visual C++ and a highly optimized implementation of the DirectX APIs. It is a prime example of a platform where you can leverage your existing Win32 and DirectX expertise and code to develop content for new consumer devices.

In the past, console developers were forced to learn and use proprietary APIs and tools for each new platform. Developing for a new console almost always meant dealing with all the hassles of first-generation development tools. By providing Win32 and DirectX on Dreamcast, Sega and Microsoft are for the first time allowing game developers to create titles for both the PC and console using virtually the same code base, as well as providing the opportunity to leverage existing code for the Dreamcast exclusive titles. Also, you get to do all the development using the same familiar tools used for desktop games.

Figure 2. Sega Dreamcast with controller and VMS unit

The Dreamcast console (shown in Figure 2) includes a 200-MHz Hitachi SH4 microprocessor and VideoLogic PowerVR graphics chip capable of rendering more than 1 million polygons per second. The system has 16 MB of main memory, 8 MB of video memory, and 2 MB of sound memory. The sound chip is the Yamaha AICA, which uses the ARM7DI as its sound controller. Unlike other consoles that either use cartridges (like the Nintendo 64) or standard CD-ROMs (like the Sony Playstation), Sega designed a proprietary storage format for the Dreamcast called GD-ROM (Gigabyte Disk ROM). These discs can store both standard CD-ROM data and game data in a high-density band. The GD-ROM format allows Dreamcast titles to store more data than standard CD-ROMs without having to go to the much more expensive DVD drives. There are currently several peripherals available for the Dreamcast, including a standard controller, microphone, light gun, wheel, and arcade-style joystick. Many of the peripherals support the use of plug-in Visual Memory System devices. These small devices serve as both persistent memory storage units as well as portable game players using their built-in LCD screen. One of the most promising features of the Dreamcast is its built-in modem. It allows you to provide the same kind of online game play features available in many PC titles today, as well as provide Internet connectivity previously unavailable on consoles.

The Dreamcast console does not actually ship with Windows CE built in. The operating system, DirectX, and the game itself are built as one image and stored on the GD-ROM. When the GD-ROM is placed in the Dreamcast console, the boot ROM loads the bootstrap code, which then loads the Windows CE operating system. This way, there are no versioning issues. You ship the version of Windows CE your game was developed on with your game, so there is no need to worry if the user has the correct version installed or not. There are, of course, differences between the Win32 and DirectX on Dreamcast compared to the desktop. There is no Windows UI (no Windows Explorer, Start menu, and so on), so the game is in charge of providing the entire user interface. There is no support for multiple windows either; the game runs in full-screen exclusive mode with DirectDraw and Direct3D as the primary graphics APIs. Like other Windows CE platforms, you can pick and choose which components you wish to build with your game. For example, if your game does not make any use of the networking features of Dreamcast, you don't have to include DirectPlay or Winsock.

Because Windows CE does not provide its own UI for the Dreamcast, much of the functionality of the Win32 user component as been removed. Only the APIs for accessing resources and some user input WM_* messages are supported. Specifically, those actually dealing with window elements like buttons or menus are removed. Similarly, much of the GDI has been removed because DirectDraw and Direct3D are the main graphics APIs. What's left of the GDI is support for loading fonts and bitmaps. A new Dreamcast-specific API has been introduced that allows read/write permission to the Visual Memory System devices mentioned earlier. For using the Dreamcast communication features, the standard Win32 serial communications API is supported, as well as Winsock 1.1.

Windows CE for Dreamcast supports the full set of DirectX foundation components. DirectDraw, Direct3D Immediate Mode, DirectInput, DirectSound, DirectPlay, and DirectShow are all supported. An upcoming release will also add support for DirectMusic. All these components have been optimized for Dreamcast to improve performance, reduce size, and take advantage of platform-specific features. This is done while still providing developers with the standard APIs available on the desktop for developing games. Figure 5 highlights some differences between the Dreamcast DirectX components and the desktop ones.

DirectDraw and Direct3D have been heavily optimized for the PowerVR graphics chip to support nearly all the features using the standard APIs from desktop DirectX. Because the hardware on the Dreamcast is fixed, much of the software emulation code in DirectDraw and Direct3D has been removed to reduce memory footprint. Again, your game will be the only application running, so you have to use full-screen exclusive mode:

lpDD->SetCooperativeLevel(hwndMain, DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN);

When using DirectDraw, your single game application loads the DirectDraw library, ddraw.dll, and DirectDraw hardware abstraction layer (HAL), ddhal.dll, and DirectDraw calls are passed through these thin libraries to the hardware for execution. When using DirectSound, your application loads dsound.dll and sndcore.dll and DirectSound calls are passed down through these thin layers to the ARM processor sound driver for execution.

Usage of Direct3D under Dreamcast is very similar to that of its PC equivalent. You create the Direct3D device, create and load textures, and then call BeginScene. Inside the loop you set render-states for each mesh and then call one of the DrawPrimitive* functions. When finished you call EndScene and Flip. One notable difference is that there is no Z buffer on the Dreamcast. However, it is still supported by Direct3D for code compatibility purposes. There are some features of the PowerVR chip that have no equivalent support in desktop Direct3D, like support for a modifier volume, which can be used by the hardware to alter various properties of other polygons that fall inside or outside of it. Direct3D exposes some of these in the current release and many will be in future releases. Using these features does create situations where code is Dreamcast specific, but also allows you to make full use of the Dreamcast hardware while still benefiting from desktop-compatible code for a majority of your game. One DirectX component that is completely missing from Dreamcast is Direct3D Retained Mode, mainly due to its size and performance.

Using DirectInput on the Dreamcast is virtually identical to the desktop. You enumerate input devices using EnumDevices and create device objects for each one found. All the currently available devices for the Dreamcast, such as the game pad, wheel, and arcade stick are supported. The main difference on Dreamcast is that buffered data is not supported, so you must use immediate data for all input. This should be done often but cannot be done more than once per frame.

Networking technologies like DirectPlay, WinInet, Winsock, and Remote Access Service (RAS) are all available on the Dreamcast. DirectPlay for Dreamcast allows game developers to provide network-play functionality similar to that already available on the desktop. WinInet opens the door to various Internet services like WebTV that want to target Dreamcast users. As on the desktop, Winsock and RAS provide low-level access to the underlying protocol stack and support for dial-up connections respectively.

Table 3. Windows CE for Dreamcast DirectX Components

DirectX components Main differences on Dreamcast
DirectDraw Full-Screen Exclusive Mode Only.
IDirectDrawClipper not supported.
Overlay surfaces not supported.

Direct3D Immediate Mode Dreamcast-specific flags used to expose some PowerVR features.
Frame buffer cleared after each frame.
No Z-buffer on PowevVR

Direct3D Retained Mode Not Supported.

DirectSound No software mixing.

DirectMusic Will be fully supported later this year.

DirectInput Buffered data not supported. Must poll for immediate data.
Force feedback not supported.

DirectPlay IPX protocol not supported.

DirectShow No audio or video capture support.
Control of DVD players and VCRs not supported.
No cutlist support.
No property pages or resource manager.

Figure 3. Windows CE for Dreamcast Toolkit fully integrates with Visual C++.

As with other platforms that support Windows CE, Visual C++ can be used to develop for Dreamcast. For the first time, this allows game developers the ability to use the same tools for both PC and console game development. The Windows CE for Dreamcast Toolkit includes the Windows CE Toolkit for Visual C++ 6.0, which provides an SH4 compiler, linker, and debugger. All this is available using the standard Microsoft Visual Studio® IDE (see Figure 3). Here we've created a Visual Studio workspace that includes both the x86 Win32 and SH4 Win32 versions of our game, which both use the same source files. The PC version builds using the include and library files from the DirectX 6.1 SDK and the Dreamcast version uses the ones provided in the Windows CE for Dreamcast Toolkit. Even though a large chunk of console game development is done in C and C++ these days, there is sometimes still the need to get down and dirty with assembly. This can be achieved using the inline assembly support of the compiler or using the stand-alone SH4 assembler provided. The tools run under both Windows 98 and Windows NT.

Figure 3 shows some code from the d3dstrm sample included in the Windows CE for Dreamcast Toolkit. This sample uses DirectShow to render a media stream onto a texture that is then mapped onto a waving flag using Direct3D. This sample will work under both Dreamcast and a PC running DirectX 5.0 or later. Of course, you won't be able to run this under Windows CE unless you have Dreamcast development hardware from Sega, but you can still run it on a PC. The full source of this sample is available from the Microsoft Journal (MSJ) article "DirectX 6.0 and Windows Media Technologies Bring Multimedia to Windows CE."). Looking at the sample, it's easy to see where code can be shared across platforms and what things need customization. A major difference under Dreamcast DirectX is that you can render the media stream directly into a DirectDraw surface that's in video memory. Restrictions under desktop DirectX force the media stream to be rendered into system memory first, and then copied over to video memory. The sample checks to see if RENDER_TO_DEVICE_MEMORY is defined to determine whether it can render straight to video memory. When building a Dreamcast Windows CE version of the project, this is set.

D3DSTRM sample builds and runs for both the desktop and Dreamcast
//************************************************** ******************
//
// Function:
//
// UpdateStreamSample
//
// Description:
//
// Synchronously render the contents of the given multimedia stream sample
// onto the texture surface. On Windows CE, the stream is rendered directly
// into the video memory texture. Restrictions on locking video memory
// surfaces under Windows 9x prevents us from doing this, on the 9x platform,
// so we render into a system memory texture and reload the contents
// into the video memory texture with each update.
//
// Arguments:
//
// IDirectDrawStreamSample* lpddss - Pointer to a DirectDrawStreamSample
// object to update from.
//
// Return Value:
//
// true on success, false on failure.
//
//************************************************** ****************************
bool UpdateStreamSample(IDirectDrawStreamSample* lpddss) {

HRESULT hr;

// Update the sample only if the application is active
if (!g_bActive) {
return true;
}

// If we are seeking, update the stream clock
if (g_stOffset) {
g_stTime += g_stOffset;
g_lpmmsStream->Seek(g_stTime);
}

#ifdef RENDER_TO_DEVICE_MEMORY
// Make sure the flip has completed before changing texture contents or
// we risk a render timeout
do {
hr = g_lpddsFront->GetFlipStatus(DDGFS_ISFLIPDONE);
} while (hr == DDERR_WASSTILLDRAWING);

if (ResultFailed(hr, TEXT("IDirectDrawSurface::GetFlipStatus" ))) {
return false;
}
#endif // RENDER_TO_DEVICE_MEMORY

// Update the texture with the contents of the video stream
hr = lpddss->Update(0, NULL, NULL, 0);
if (hr != MS_E_NOTRUNNING && FAILED(hr)) {
ResultFailed(hr, TEXT("IDirectDrawStreamSample::Update")) ;
return false;
}

// If we've reached the end of the stream, reset it
if (hr == MS_S_ENDOFSTREAM) {
if (WaitForSingleObject(g_hEOS, 0) == WAIT_OBJECT_0)
{
hr = g_lpmmsStream->Seek(0);
if (ResultFailed(hr, TEXT("IMultiMediaStream::Seek"))) {
return false;
}
}

hr = lpddss->Update(0, NULL, NULL, 0);
if (hr != MS_E_NOTRUNNING && FAILED(hr)) {
ResultFailed(hr, TEXT("IDirectDrawStreamSample::Update")) ;
return false;
}
}

#ifndef RENDER_TO_DEVICE_MEMORY

if (g_lpddsStreamTarget && g_bStretchStream) {
hr = g_lpddsSystemMemory->Blt(&g_rectTexture, g_lpddsStreamTarget,
&g_rectStream, DDBLT_WAIT, NULL);
if (ResultFailed(hr, TEXT("IDirectDrawSurface::Blt"))) {
return false;
}
}

// Load the source texture into the destination
hr = g_lpd3dtDeviceMemory->Load(g_lpd3dtSystemMemory);
if (FAILED(hr)) {
if (hr != DDERR_SURFACELOST) {
ResultFailed(hr, TEXT("IDirect3DTexture2::Load"));
return false;
}
}

#endif // !RENDER_TO_DEVICE_MEMORY

return true;}

Most code will compile without changes for both Dreamcast and the desktop, but there are situations where you'll have to make changes. For example, since there is no real concept of window attributes like the title bar, we don't specify any text for it:

#ifndef UNDER_CE
hWnd = CreateWindowEx(0, g_szAppName, g_szAppName, WS_VISIBLE, 0, 0,
GetSystemMetrics(SM_CXSCREEN), GetSystemMetrics(SM_CYSCREEN),
NULL, NULL, hInstance, NULL);
#else
hWnd = CreateWindowEx(0, g_szAppName, NULL, 0, 0, 0,
GetSystemMetrics(SM_CXSCREEN), GetSystemMetrics(SM_CYSCREEN),
NULL, NULL, hInstance, NULL);
#endif // !UNDER_CE

The bottom line is there will be differences between code that runs on the PC and code for the Dreamcast, particularly if your game makes heavy use of Windows UI components, or you wish to take advantage of Dreamcast features not available on the desktop. For the most part, however, a large chunk of code will work across platforms.

Conclusion
The Sega Dreamcast console is just one example of a cutting-edge consumer platform that takes advantage of industry standard APIs and tools. Microsoft is working with other partners to develop other consumer devices like Advanced Set-Top Boxes (ASTB) and Internet terminals built around Windows CE technologies. With the latest release of Platform Builder, the DirectX and Windows Media Technologies are now available to all OEMs interested in the ever-expanding consumer device market. For more information on developing for Windows CE devices or creating your own Windows CE-based platform, see http://msdn.microsoft.com/embedded/.