Retrieving the DirectX Version

Search Tips

Advanced Search

Delphi Graphics and Game Programming Exposed with DirectX 7.0 by John Ayres

Wordware Publishing, Inc.

ISBN: 1556226373 Pub Date: 12/01/99 Search this book:

Previous Table of Contents Next

DirectX Result Codes

Just about every DirectX function and method returns an HResult, a 32-bit number that maps to a DirectX error code. There are hundreds of error codes, all of which are located in the DDraw unit. These codes can be translated into a textual form by calling the DXErrorString function located in the DXTools unit. The

DXTools unit also contains a procedure called DXCheck that will raise an exception if a DirectX function returns any error code other than DD_OK.

In theory, every call to any DirectX method should be wrapped with this DXCheck function. In practice, this may be impractical, but you should always check the results of any extremely critical methods, such as blits, flips, and initialization code. Methods such as these can cause an application to waltz off into limbo if they fail and are not gracefully handled, so checking the result code is very important for a robust application.

The DXErrorString function can be incredibly useful when debugging a DirectX application. The result of this function could be written out to a disk- based text file, and later examined if the DirectX application crashes. This tends to happen often when developing DirectX applications, and due to the fact that you cannot step through your code or use any of Delphi’s awesome debugging features, this is a useful, if sloppy,

debugging technique.

Most commercial DirectX applications ship with a version of the DirectX run- time redistributables. The developer knows that the application will be using either the version installed with the application or a more recent version installed by other applications or the operating system. However, sometimes it is necessary to determine which version of DirectX is installed before initializing objects, particularly if the application is to be distributed without the DirectX run-time redistributables, such as on floppy or over the Internet.

Specifically, you should not be checking for an overall DirectX version, but instead you should check for the availability of specific interfaces. As we’ve seen, the QueryInterface method implemented in every COM object can determine if a specific interface is supported. Using this method, you can determine if certain features are supported on the target machine. For example, if the IDirectDraw4 interface is not available, you know that you’re working with a version of DirectDraw older than 6. By querying for other interfaces, you can determine if 3-D sound or force feedback devices are supported. Using the QueryInterface method is

Title

---much more reliable than checking the drive for the existence and time stamp of particular files.

Additionally, DirectSetup features a method for retrieving the current version of DirectX that is installed on the machine. See Appendix A for complete information about DirectSetup and how to retrieve the current version of DirectX.

Summary

In this chapter, we discussed several DirectX and DirectDraw topics. The examples built from initializing DirectDraw all the way to implementing a general page flipping architecture and displaying bitmaps. DirectX programming in general is a very complex topic, filled with many nuances with which the developer must become familiar. We covered DirectDraw programming to a minor degree in order to illustrate this point, and as a foundation upon which the rest of the book’s knowledge will be built. When coding a DirectX

application, and using DirectDraw in particular, it is important to keep these points in mind:

• The DirectX development team’s goal was to create a low-level architecture that would provide developers with the hardware control they need at the speed they demanded, while still retaining Windows’ device-independent benefits. This was to be accomplished without imposing a restrictive high-level design architecture. Therefore, DirectX promises three things to developers: fast execution, minimal style restraints, and a level of abstraction that will provide benefits from future hardware.

• DirectX delivers exceptionally on all of its promises, and offers many benefits, such as speed, control, and feature emulation. However, DirectX programming has a number of drawbacks, such as difficult debugging, few Delphi-specific examples, and a steep learning curve. The developer must determine if the benefits and advantages offered by DirectX outweigh the drawbacks and disadvantages for the specific functionality required by the application.

• The DirectX API itself, in the form of various COM objects and their methods, acts as an interface into the DirectX drivers. On the back side, the DirectX drivers can be thought of as two separate systems: the hardware abstraction layer (HAL) and the hardware emulation layer (HEL). The HAL represents the hardware itself. The HEL, on the other hand, represents the software emulation of certain features. It is important to note that, for the most part, this is completely transparent to developers.

• DirectX is comprised of many components. While the inventive game developer could potentially make use of all of these components, there are only a few which are essential for game development:

DirectDraw, DirectSound, and DirectInput. Other components that may be useful in a particular game include DirectPlay, DirectSetup, Direct3D, and DirectMusic.

• Under Delphi, you do not necessarily need the DirectX SDK; you only need the DirectX

redistributables that are installed with the DirectX SDK or almost any commercially available game.

However, the DirectX SDK includes a number of debugging and control panel utilities that can be useful, and is the only source for the DirectX API documentation. In this book, we use the DirectX headers from the JEDI project, translated by Erik Unger. However, there are several other commercial and shareware/freeware DirectX components and headers that can dramatically decrease the production time for a DirectX project under Delphi.

Previous Table of Contents Next [an error occurred while processing this directive]

Use of this site is subject to certain Terms & Conditions, Copyright © 1996-2000 EarthWeb Inc. All rights reserved. Reproduction whole or in part in any form or medium without express written permission of

EarthWeb is prohibited. Read EarthWeb's privacy statement.

Delphi Graphics and Game Programming Exposed with DirectX 7.0 by John Ayres

Wordware Publishing, Inc.

ISBN: 1556226373 Pub Date: 12/01/99 Search this book:

Previous Table of Contents Next

• DirectX objects are COM based, consequently involving all of the associated benefits and drawbacks of using COM objects. Working with DirectX objects has some similarities to working with other COM objects, but there are a few differences. The primary difference is the fact that DirectX objects do not need to be created by using the CoCreateInstance function. All DirectX objects are created through custom function calls that return an instantiated COM object. A COM object can almost be thought of as a VCL object with no properties, only methods. The methods of a COM object are known as an interface. A COM object can have more than one interface, and it can be extended by added new interfaces, similar to deriving a new component from an ancestor. However, the COM standard dictates that an interface can never change. COM objects determine when they can destroy themselves, and thus do not need to be freed by the creating application. A unique identifier called a GUID is used to

distinguish individual COM objects.

• Perhaps the single most important concept in DirectDraw programming is that of the surface. A surface is directly analogous to Delphi’s TBitmap or TCanvas object. It represents a virtual “picture”

upon which graphical output can be drawn. In reality, a surface is a linear chunk of memory that is managed as if it were rectangular. Surfaces have width and height, among many other properties. The memory for a surface can be located in a number of places, but primarily it will be found in system memory or in the memory on the display card itself. There are many different types of surfaces, some of which are very specialized for a particular purpose. For the purposes of this book, we will be concerned with only three different types: the primary surface, the backbuffer surface, and off-screen surfaces.

• Page flipping is an incredibly powerful technique for producing flicker-free animation. The term

“page flipping” comes from the inspiration for this animation technique, that of traditional cartoon animation. Cartoons (and movies, for that matter) create the illusion of animation by displaying to the viewer a series of images, one after the other. Someone can create a crude animation by taking a stack of paper, drawing an image on each page, and then flipping through it rapidly. This is the architecture of page flipping animation. The idea is to create two surfaces, the primary surface and the backbuffer surface. The next frame of animation is composed on the backbuffer surface, and then it is “flipped” to the display screen. This updates the entire display screen in one fell swoop, resulting in a flickerless animation.

• There are several tasks an application is required to perform before DirectDraw can be instantiated and the display mode modified. Some of these tasks are optional, some are not. The application may want to enumerate all attached display devices, although this is not specifically required. After the user

Title

---picks an enumerated display device, or if the application simply decides to go with the primary display device, the DirectDraw object can be created. Supported display modes can then be enumerated; while not specifically required, the display mode into which the display hardware is switched must be a supported mode, which can be verified by enumerating supported display modes. The cooperative level can then be set, determining if the application will run full screen or windowed. Finally, setting the display mode causes the hardware to switch over to the indicated resolution and color depth. Bear in mind that certain requirements are imposed on the main window before the display mode can be set properly.

• A device context handle can be retrieved from a surface, allowing the application to use GDI rendering functions. When combined with a TCanvas object, the full power of Delphi’s built-in graphical rendering functionality can be brought to bear. However, the sluggishness of the GDI will also be present. It is very important that any device contexts retrieved be released before performing any DirectDraw functions that manipulate the surface.

• Bitmaps can be easily loaded and stored into a surface by using the TBitmap object combined with the drawing capabilities of a TCanvas object and a device context retrieved from a surface.

• The memory associated with surfaces located in display memory can be lost if the user Alt+Tabs out of the application. When the DirectDraw application receives focus again, it must call the Restore method of any display memory surfaces, including the primary surface. Their contents will be undefined, so they must be reinitialized by reloading bitmaps or redrawing graphics.

• DirectX was written so that a developer can take advantage of certain hardware features if they are available, such as overlays or the ability to create off-screen surfaces wider than the primary surface.

We can determine what features are available by calling the IDirectDraw4’s GetCaps method.

• Just about every DirectX function and method returns an HResult, a 32-bit number that maps to a DirectX error code. There are hundreds of error codes, all of which are located in the DDraw unit.

These codes can be translated into a textual form by calling the DXErrorString function located in the DXTools unit. You should always check the results of any extremely critical methods, such as blits, flips, and initialization code. Methods such as these can cause an application to waltz off into limbo if they fail and are not gracefully handled, so checking the result code is very important for a robust application.

• Sometimes it is necessary to determine which version of DirectX is installed before initializing objects, particularly if the application is to be distributed without the DirectX run-time redistributables, such as on floppy or over the Internet. Specifically, you should not be checking for an overall DirectX version, but instead you should check for the availability of specific interfaces. The QueryInterface method implemented in every COM object can determine if a specific interface is supported.

Previous Table of Contents Next [an error occurred while processing this directive]

EarthWeb is prohibited. Read EarthWeb's privacy statement.

Search Tips

Advanced Search

Delphi Graphics and Game Programming Exposed with DirectX 7.0 by John Ayres

Wordware Publishing, Inc.

ISBN: 1556226373 Pub Date: 12/01/99 Search this book:

Previous Table of Contents Next

CHAPTER 5 Palettes

This chapter covers the following topics:

• The definition of a color palette

• The creation and use of the IDirectDrawPalette object

• Palette animation

Game programmers tend to have mixed feelings about palettized display modes. On one hand, you’ve got special animation effects and superior performance benefiting you from using a palettized display mode. On the other hand, you’ve got graphic resource management nightmares, an extra layer of indirection and complexity, and a limited resource in the form of color. With the increasing speed of today’s hardware, someday the performance boost available with palettized display modes will not outweigh the benefits of using 16-bit or 32-bit color modes.

However, at this point, creating games in a 256-color palettized display mode still has many advantages over the higher color depth modes. Since this book discusses techniques for game and graphics programming under 256 video modes, we should examine how DirectX handles color palettes in a little more depth.

In this chapter, we will examine how palettes are supported under DirectDraw in full-screen exclusive mode. We covered color depth and palettes back in Chapter 3, Basic Graphics Programming, and palettes still work very much the same way under DirectX. For the sake of completeness (in case you skipped Chapter 3), we’ll briefly examine what a color palette is and how it works. Then we’ll dive right into creating DirectDraw palettes, how they are used, and some special effects you can accomplish with them. If you read the basic graphics programming chapter, skip ahead to the section on the IDirectDrawPalette object.

In document WordwarePublishing-Delphi Graphics and Game Programming Exposed With DirectX 7.0 (Page 158-162)