Sue Ledoux
Microsoft Corporation
August 5, 1996
Note Although this article is about the DirectX 2 SDK, the newer version, DirectX 3 SDK, is now available. The technological differences between the two are relatively minor. For a list of the important differences between the two versions, see the appendix What's New in the DirectX 3 SDK?
First, let's get the ®s and ™s out of the way so the editors and the legal department can relax and I can loosen up some of the Diet Coke™ I spilled on the ALT key that night I spent 4 hours trying to find a bug that turned out to be just a mislabeled COM port. Microsoft® Direct3D™ is the real-time 3-D graphics component of the Microsoft DirectX™ 2 interactive-media technologies. DirectX 2 includes the DirectDraw™, DirectSound™, DirectInput™, and DirectPlay™ application programming interfaces (APIs). These technologies are supported on the Windows® 95 operating system and will be incorporated into the next release of the Win32® API. DirectX 2 is also slated to be available for the Windows NT® operating system and the Apple® Power Macintosh® environment.
Direct3D and the other DirectX technologies are intended to give programmers the best of both worlds—a low-level, high-performance interface to hardware combined with the flexibility of device independence. With Direct3D, programmers can incorporate 3-D graphics functionality into Windows programs to take advantage of hardware acceleration whenever present, without actually coding to any specific hardware.
When I set out to learn about Direct3D, I was surprised by the volume of material to be found in the DirectX 2 SDK: binaries and libraries and header files, sample code and demo games, Help files, readme files, and documents. Direct3D is the biggest and most complex component in the SDK. Add to that beta mailings, CD inserts, press releases, and third-party offerings, and I found myself buried. So although there is no shortage of information about Direct3D, sorting through it and finding what you need is time-consuming. This article serves as a summary and road map of the Direct3D technology, SDK, and resources. Most of the information is available in the assorted bits of documentation, but if you need to make product and technical decisions quickly and don't have the time to go searching, this is the article for you.
After you've read this article, you should be able to answer the following questions:
Once you've had a taste of Direct3D and decided that your life won't be complete unless you've experienced the spellbinding thrill of 3-D programming with Direct3D, you'll know how to go about learning how to add Direct3D functionality to your application.
OK, so I lied when I said we'd be done with the ®s and ™s. Here, straight from the horse's mouth (OK, the CD sleeve) are the platform requirements for DirectX 2.
You'll need a multimedia computer or compatible running Windows 95. For the three of you who still don't know, multimedia means a CD-ROM drive, a sound card, and an 8-bit or greater video card.
The recommended system is an Intel Pentium 90 or higher with at least 16 MB of memory or other 100 percent compatible PC systems.
The minimum system is an Intel 486/66 or compatible with 8 MB of memory. But let's be honest: while this configuration may be fine for some of the other DirectX components, we all know that 3-D graphics are greedy when it comes to computing resources. Be sure to try out your application on all configurations before making system recommendations to your customers.
Here's the current list of hardware supported by DirectX 2. Supported means either that DirectX 2 supports a particular hardware-acceleration feature of the hardware or that the drivers and hardware have gone through testing with DirectX 2 components and have performed reasonably well. No, it doesn't mean the performance is perfect, nor does it indicate whether Microsoft or the hardware manufacturer actually wrote the driver and DirectX 2 Hardware Abstraction Layer (HAL). And yes, I'm punting on the definition of reasonably well.
You'll need the Win32 SDK to build applications for DirectX 2. The samples come with makefiles for Microsoft Visual C++ (version 2.0 or later) but can of course be compiled using other development environments. If you're a user of Watcom C/C++ (version 10.5 or later is needed), be sure to check out the readme file in the samples directory for instructions created Just For You.
Because Direct3D and the other DirectX 2 components are new, they don't yet ship with Windows. Until they do, you'll have to include them in your application's setup process. The DirectX 2 SDK includes instructions and the component (called, surprisingly enough, DirectSetup) you'll need to do this.
One day in the not-too-distant future, you'll wake up and discover that the sun is shining, birds are singing, and DirectX 2 is supported on the Windows NT operating system and on the Apple® Power Macintosh®. We'll let you know when as soon as we get some firm dates. Hey, go easy on us—this is the software industry, after all! The best way to keep yourself informed on expected release dates of this and any other Microsoft interactive-media technologies is to keep in touch with the Interactive Media and Game Developers Web site at http://www.microsoft.com/MEDIADEV/. You'll also be able to keep up-to-date on hardware support for DirectX 2, as more drivers and HAL implementations become available.
To keep abreast of the ever-changing cast of interactive-media technologies, peruse "A Road Map of Game and Interactive-Media Technologies." This article is kept up-to-date with descriptions and status (including expected release dates) of all current and upcoming technologies.
Here's a nice diagram (done with Etch-A-Sketch™) that shows how Direct3D relates to Windows architecture:
Figure 1. Direct3D in the grand scheme of things
DirectDraw is the Windows composition engine for 2-D graphics, 3-D graphics, and video. It is used both directly by applications and by Direct3D. If you decide to use Direct3D in your application, you will probably want to familiarize yourself with DirectDraw as well.
The HAL is home to hardware-specific code that takes advantage of special features like hardware blting and page flipping. The companion to this, not shown in Figure 1, is the HEL, or hardware emulation layer. This contains software implementations of all the functionality available in DirectDraw and Direct3D. The combination of the HEL and the HAL allow applications to take maximum advantage of whatever hardware is installed without sacrificing device independence. Programmers can then write code in one standard way that will run as fast as is possible, whatever the system.
An example of what Figure 1 refers to as "Other 3D APIs or engines" that use DirectDraw and Direct3D is OpenGL. This is another 3-D technology available from Microsoft that is aimed at the high-end CAD/CAM and scientific-application crowd. You can get more information about OpenGL in "A Road Map of Game and Interactive-Media Technologies" or by reading "Windows NT Open GL: Getting Started."
The Direct3D rendering pipeline is made up of three modules: the lighting module, the transformation module, and the rasterization module. Each of these can be emulated in software and accelerated by hardware, and can be exchanged (on the fly if necessary) for different implementations that match an application's unique needs. Direct3D ships with two lighting modules, one transformation module, and two rasterization modules.
Although it's not obvious from the diagram, Direct3D is, in effect, two 3-D packages in one. Programmers can choose to use the high-level Retained Mode API or the low-level Immediate Mode API.
The Direct3D Retained Mode API is designed to provide high-level services for manipulating scenes and objects. It sits on top of Immediate Mode and has a built-in geometry engine, so you don't need to keep databases of objects or their internal structures. This engine also supports capabilities such as key-frame animation. With just a few calls, you can load up predefined objects and manipulate them within scenes.
The pros: You don't need to know as much about 3-D programming, so you can get up and running more quickly, and you can write a whole lot less code to create straightforward 3-D effects.
The cons: It won't be as fast or as flexible as Immediate Mode.
If you only want to add standard 3-D functionality to your application or don't have the time to develop your own complex geometry routines, Retained Mode will more than likely suffice.
The Direct3D Immediate Mode API provides low-level, device-independent communication with rendering and accelerator hardware. This is the API of choice of developers who have considerable 3-D programming experience or who may have large amounts of existing 3-D code that they wish to port to Direct3D.
The pros: You get to do your own scene rendering and scene management. This will give your application significantly more flexibility, and it may give you better performance if you have optimized these for your particular needs.
The cons: You have to do your own scene rendering and scene management, and you'll need to know a lot more about 3-D programming.
If you're a hot-shot game programmer who is interested in high-performance, cooler-than-cool 3-D effects, have personally developed routines to prove it, scoff at the notion of us providing you with a namby-pamby, easy-to-use, high-level interface, then Immediate Mode has your name written all over it.
The major features of Direct3D are listed in the following table.
Table 1. Key Features of Direct3D
| Z-buffer disabling in both Retained Mode and Immediate Mode |
| Demand-loadable device drivers for efficient memory usage |
| Flat and Gouraud shading models |
| Point, line, and solid-fill modes |
| Multiple, movable, colored light sources |
| Spot, point, ambient, and directional light sources |
| Specular highlighting |
| Ramp and true color red, green, and blue (RGB) model |
| Color depths of 8, 16, 24, or 32 bits |
| Dithering |
| Vertex colors |
| Multiple viewports, devices, and cameras |
| Materials support |
| Texture mapping in any shading model |
| Bilinear, trilinear, mipmap texture filtering |
| Perspective-corrected texture mapping in any shading model |
| Full transparency, including alpha maps for textures |
| Orthographic and perspective projections |
| Environment (reflection) and motion video mapping |
| Real-time object deformation |
| Support for off-axis general-viewing transforms |
| Animated backgrounds with optional depth information |
| Full picking support for user interaction |
| Depth cueing with atmospheric effects (such as fog or haze) |
| Ability to support hooks for collision detection |
To give you a better idea of what you can do with Retained Mode and Immediate Mode, I've listed the APIs by category in the next section and briefly described each. The SDK documentation contains a comprehensive API reference of both Retained Mode and Retained Mode APIs.
Table 2. lists some of the features specific to Retained Mode.
Table 2. Features Specific to Retained Mode
| Inheritance of textures, colors, and materials through hierarchies |
| Projected shadows |
| Multiple instancing of objects and hierarchies |
| Complex-spline interpolated motion |
| Real-time animation keyframer |
The general kinds of objects and functionality available in the Retained Mode API set include:
Animation. Using the animation object, you can animate the position, orientation, and scaling of visual, light, and viewport objects. This is accomplished by the setting of keys, which associates a time value with a position, orientation, or scaling operation. To animate the objects, you program repeated calls to a time set function; the system then calculates what the position should be by interpolating from the key values. Animation objects can be grouped, allowing multiple objects to be animated simultaneously.
Devices. In Direct3D, a device object is the visual display destination for the renderer. Devices can render directly to the screen, to windows, or into application memory.
Color models. Retained Mode supports two color models—an RGB model and a monochromatic model (also called a ramp model). The ramp model can be used if maximum performance is desired at the expense of color.
Faces. A face is a single polygon in a mesh. Methods allow you to build the face from vertices and set the color, texture, and material of the face. Faces can be stored in arrays to perform identical operations on multiple faces.
Frames. Frames are used to position objects within scenes. Each object has a position relative to its parent frame, and multiple frames make up a scene. Frames exist in a hierarchy, where the scene itself is the (parentless) root frame. Methods allow you to create frames, add and delete children, and get information on the parent and children of a frame. In addition, you can add or modify position, rotation, and scale transformations between child and parent frames.
Lights. Lights are attached to frames and illuminate the visual objects within that scene. Five types of lighting are available: ambient, directional, parallel point, point, and spotlight.
Materials. Methods allow you to set emissive and specular properties of a material, which define how a surface reflects light.
Meshes. Meshes are collections of vertices and polygonal faces that make up a visual object. Mesh-manipulation methods include those to add vertices, faces, and normals as well as set colors, textures, and materials to a face or a group of faces.
Shadows. A shadow object can be created by specifying the light source, the object casting the shadow, and the plane on which the shadow is cast.
Textures. Textures can be mapped onto faces or rendered directly as decals. Texture-manipulation routines include methods to set and get texture colors, control how the textures are mapped onto surfaces, and set transparency for a texture. In addition, the quality of textures can be improved by using mipmaps, which provide prefiltered, progressively lower resolutions of the same image.
User-visual objects. Retained Mode supports application-defined objects that the programmer can add to a scene and then render.
Viewports. The viewport defines the actual viewable portion of a scene after it has been converted from 3-D to 2-D coordinates for display onto the screen. Camera-control methods set the position, direction, and orientation of the viewport. The programmer can choose between perspective and orthographic viewing and can set the front and back clipping planes of the viewing frustum. The viewport interface is also where the actual transformations from 3-D to 2-D space are specified.
Wraps. Wraps define how a texture is mapped onto a visual object. Programmers can choose from flat, cylindrical, spherical, or chrome wrapping modes.
Most of the Immediate Mode interfaces provide subsets of the functionality described in the Retained Mode interfaces. These interfaces, which provide device, texture, material, light, and viewport functionality, typically give up some hand holding in favor of performance and/or flexibility.
A notable exception is the ExecuteBuffer function, which does not exist in the Retained Mode API. An execute buffer is a list of vertices followed by a series of instructions that operate on those vertices. This functionality makes it possible for an application to customize the rendering pipeline; both the transformation and the lighting modules can be disabled, and prelit or pretransformed vertices can be supplied to the rasterization module.
This section will help you to quickly find the Direct3D information and components that you need from the DirectX 2 SDK.
The SDK contains the following components:
Installation of the SDK is a quick and painless procedure (except for you diehards crazy enough to download it from the Web site!). A complete DirectX 2 setup from CD takes about 5 to 10 minutes and requires approximately 60 MB of hard drive space. Choosing the Custom Setup option allows you to choose from the components listed in Table 3.
Table 3. Custom Setup Options
| Component | Description | Size (bytes) |
| DirectX | Run-time components | 4,208,594 |
| SDK Basics and Help | Headers, libraries, and Help files | 5,504,475 |
| SDK Tools | Development and debugging tools, including the Viewer | 1,231,057 |
| Sample Binaries | Compiled binaries of samples | 3,923,968 |
| Sample Code | SDK sample code, including the Viewer | 22,616,572 |
| DirectX Media | DirectX Media, including .x files, textures, and waves | 8,769,917 |
| The Fox & the Bear | Parallax scrolling demonstration of DirectX | 2,026,264 |
| Rockem 3D | Multiplayer 3-D fighting game optimized for software | 4,701,996 |
| Immortal Klowns | Multiplayer side scrolling game | 8,183,101 |
Even though you may think you want only the Direct3D and DirectDraw components, the setup program does not allow you to install only parts of the SDK. What's shown in Table 3 is as granular as it gets. If hard drive space is at a premium for you, you could skip installing the DirectX Media; it's only there for you to use as samples in your code and with the Viewer. The sample binaries and code cover many of the technologies, and you may not be interested in all of the samples. The setup program does not allow you to pick and choose, but you can install all of the samples and their binaries and then delete those you don't need. Also, "The Fox & the Bear" and "Immortal Klowns" do not demonstrate Direct3D. Let's be real, though: if you're stressing over a few dozen megabytes, you're hardly a real 3-D programmer.
For the purposes of the rest of this article, I'm assuming that you've installed your SDK in the \dxsdk directory (the default location). If you've put it somewhere else, I'm sure you're bright enough to make the necessary interpolation!
Online Help is in the \dxsdk\help\directx.hlp file. This file is the primary documentation for all of the DirectX 2 SDK components, and includes overviews, tutorials, and references.
In the \dxsdk\docs directory are a number of Microsoft Word and text files that duplicate the contents of the Help file, but in a format that's easier to read (should you wish to print the files). Table 4 lists the files in this directory relating to Direct3D.
Table 4. Direct3D-Related Files in \dxsdk\docs
| Filename | Description |
| D3DOVER.DOC | Overview of Direct3D. Includes overall architecture, technical background for 3-D programming, performance optimization, and overviews and tutorials for both Immediate Mode and Retained Mode. |
| D3DIMREF.DOC | Reference for Immediate Mode APIs. |
| D3DRMREF.DOC | Reference for Retained Mode APIs. |
| D3D.TXT | Release notes for Direct3D. Includes known problems and workarounds. |
| CONV3DS.TXT | Instructions for 3-D model conversion from Autodesk 3D Studio and other modeling packages. |
| README.TXT | Readme file for this directory. Includes instructions for printing documentation. |
Tools and utilities can be found in \dxsdk\sdk\bin. If you installed the binaries of the samples, they'll be there too. As you might guess, headers and libraries are in \dxsdk\sdk\inc and \dxsdk\sdk\lib, respectively.
If you use nmake and the supplied makefiles, your environment variables will be set up appropriately. After setting up the SDK, you should be ready to compile the samples, and your own program as well, if you copy the makefiles used for the samples. If you use a different make process, you'll have to add the appropriate directories to your linker lists, create your own makefiles, and so on.
Samples are located in a couple of different places. Three demo games ship with the SDK: "The Fox & the Bear," "Rockem," and "Immortal Klowns." Of these, only "Rockem" uses Direct3D. The compiled versions of these games are available in the \dxsdk\foxbear, \dxsdk\rockem, and \dxsdk\iklowns directories. Additionally, the source code for these games is available, along with almost 50 other sample apps and utilities, in the \dxsdk\sdk\samples directory.
The \dxsdk\sdk\samples\readme.txt file is a brief explanation of the make process. Approximately half of the samples in the \dxsdk\sdk\samples directory are for Direct3D. The \dxsdk\sdk\samples\d3dsamp.txt file explains which these are and gives a brief description of what each one does.
The tutorials go hand in hand with the samples: one each for Immediate Mode and Retained Mode. If you have time, these will give you a great crash course in programming for Direct3D. They will walk you through all the steps necessary to load and display 3-D objects and demonstrate major functionality. The tutorials are roughly 12 pages long and can be found in the DIRECTX.HLP file.
Viewer is both a sample and a utility: it loads predefined objects (stored in .x files) and lets you play around with lighting, shading, color, and so on. Use it on the objects in the \dxsdk\sdk\media directory.
3D programming is a big, complicated topic, so of course Direct3D is big and complicated. By now you should know whether you're ready to dive into Direct3D programming or whether you first need to learn a bit more. If you have lots of 3-D programming experience and understand everything so far in this article, you'll probably only need to read the SDK documentation and go to it. If you're a little shaky or only plan on doing a few things with Retained Mode, there's a nice little technical backgrounder called "A Technical Foundation for 3D Programming" in the SDK documentation in the Library that will help. If you're completely and utterly lost, you might want to read a graphics text or pursue other educational avenues first.
Following are some suggestions for obtaining additional sources of information.
Since the DirectX API set is mostly COM based, you will need to know a little about using COM. Don't worry! Implementing COM objects is rocket science, but using them is pretty straightforward. Plenty of information about COM can be found in the technical articles on the Library.
If you haven't yet seen the Interactive Media/Games site at http://www.microsoft.com/mediadev/, you need to get with the program! This is the location where developers can find the most up-to-date information about Microsoft's interactive-media technologies. Here you'll find technical articles, technology overviews, resource lists, and FAQs—in short, the kind of information you need to successfully write applications using Microsoft technologies.
The site includes a feedback page, which we hope you'll make use of. While we can't offer one-on-one support, we do answer simple questions and pay particular attention to requests for content. What technologies do you have questions about? What issues would you like us to cover in articles? Let us know.
Microsoft Press has just published 3-D Graphics Programming for Windows 95 by Nigel Thompson. You may remember Nigel as the guy who brought you Animation Techniques in Win32, not to mention scores of technical articles on the Library that are full of great information and weird British humor. His Direct3D book carries on his tradition of clear, easy-to-understand instruction that includes lots of reusable sample code and libraries.
Another book is coming out soon on Direct3D. Rob Glidden is the author; the publisher is Addison-Wesley. Apologies to the author for the lack of further information about the book. No doubt he's a really nice guy and the book is very good, and just as soon as we get our hands on it, I'll update this section and say nice objective things about it that prove that I don't show any favoritism simply because Nigel is a friend of mine and his book will be published by Microsoft Press. (Editor's note: This book has since been published. It is Graphics Programming With Direct3D : Techniques and Concepts by Rob Glidden, published by Addison-Wesley.)
There's no shortage of good, general 3-D programming books, newsgroups, mailing lists, and so on. Some are listed on the Microsoft DirectX Web site at http://www.microsoft.com/directx.
Report bugs to dxbugs@microsoft.com. Note that this alias is for bug reporting, not technical support.
Editor's note: This section, taken from the DirectX 3 SDK, has been added to Sue Ledoux's article as a quick reference. The full DirectX 3 SDK documentation is available in the MSDN Library.
The DirectX 3 SDK provides more services—and more avenues for innovation—than the DirectX 2 SDK. Although this SDK contains additional functions and services, all of the applications you wrote with the DirectX 2 SDK, or the original DirectX 1 SDK, will compile and run successfully without changes.
The purpose of this appendix is to help those of you familiar with the DirectX 2 SDK to quickly identify several important areas of this SDK that are significantly different. These differences are listed by component.
DirectDraw. No changes to the API. The documentation has been updated to include a series of tutorials that provide step-by-step instructions for implementing a simple DirectDraw application. To read these tutorials, see "DirectDraw Tutorials" in the DirectDraw documentation.
DirectSound. DirectX 3 contains DirectSound3D functionality, which enables an application to change the apparent position of a sound source. Applications can specify sound cones for directional sound sources, Doppler-shift effects for moving sounds, and distances at which different effects occur. For more information about this new feature of DirectSound, see "Three-Dimensional Sound" in the DirectSound section of the documentation.
DirectPlay. DirectPlay has become a technology family that provides not only a way for applications to communicate with each other that is independent of the underlying transport, protocol, or online service, but also the independence for matchmaking servers. The IDirectPlay2, IDirectPlay2A, and IDirectPlayLobby interfaces were added to implement this new technology. For more information about what's new in DirectPlay, see "What's New in DirectPlay Version 3?" in the documentation.
Direct3D. No changes to the API. The Retained-Mode tutorial has been updated and simplified. To read this tutorial, see "Direct3D Retained-Mode Tutorial" in the Direct3D documentation.
DirectInput. DirectInput now includes support for mouse and keyboard input devices, as well as joysticks.
DirectSetup. DirectSetup has a new function that helps applications make the proper entries in the registry during installation.
AutoPlay. The AutoPlay documentation now includes Windows NT information.