Microsoft Corporation
September 1997
Microsoft® DirectX® provides a finely tuned set of application programming interfaces (APIs) that provide you with the resources you need to design high-performance, real-time applications. The DirectX set of APIs provides Windows®-based applications with high-performance, real-time access to available hardware on current and future computer systems. DirectX provides a consistent interface between hardware and applications, reducing the complexity of installation and configuration and using the hardware to its best advantage. By using the interfaces provided by DirectX, software developers can take advantage of hardware features without being concerned about the implementation details of that hardware.
DirectX Version 5.0 New Features Review
While continuing to expand support for performance games, Microsoft DirectX version 5.0 lays the foundation for extending DirectX media services to multimedia, Internet, and other performance applications.
Microsoft DirectX provides a finely tuned set of APIs that provide you with the resources you need to design high-performance, real-time applications. Microsoft developed the DirectX set of APIs so that the performance of applications running in the Microsoft Windows operating system can exceed the performance of applications running in the MS-DOS® operating system or on game consoles.
DirectX provides Windows-based applications with high-performance, real-time access to available hardware on current and future computer systems. DirectX provides a consistent interface between hardware and applications, reducing the complexity of installation and configuration and using the hardware to its best advantage. By using the interfaces provided by DirectX, software developers can take advantage of hardware features without being concerned about the implementation details of that hardware.
DirectX 5.0 has been developed to meet a set of related goals:
Unify media services. With DirectX, games and multimedia developers get the benefits of device independence without losing the benefits of direct access to the hardware. To accomplish this, DirectX provides a consistent API interface, device independence through the hardware abstraction layer/hardware emulation layer (HAL/HEL) architecture, and APIs that provide both low-level and high-level services.
Support entertainment, multimedia, and Internet development. When Microsoft created DirectX, one of its primary goals was to promote games development for the Windows environment. Prior to DirectX, the majority of games developed for the personal computer were MS-DOS–based. Developers of these games had to conform to a number of hardware implementations for a variety of cards. With the success of DirectX, this original mission has been extended to provide the media performance required by game developers to a larger class of applications, including multimedia and accelerated Internet content.
Enable hardware innovation. A key element of the success and importance of DirectX is that it is enabling a new generation of hardware innovation on personal computers. DirectX provides hardware development guidelines based on feedback from developers of high-performance applications and independent hardware vendors (IHVs). As a result, DirectX components might provide specifications for hardware-accelerator features that do not yet exist. In many cases, the software emulates these features. In other cases, the software polls the hardware regarding its capabilities and bypasses the feature if it is not supported.
Serve developers, hardware makers, and end users. Putting all these together, DirectX offers an evolving, innovative performance media platform for software developers, hardware makers, and end users.
DirectX offers hardware makers a key vehicle to introduce new classes of hardware features and achieve new levels of media processing performance. At the same time, DirectX offers software developers access to hardware features without being concerned about the implementation details of that hardware. For end users, DirectX offers to reduce he complexity of installation and configuration and an assurance that software will use hardware to its best advantage
DirectX 5.0 introduces a new "big-picture" architecture that organizes DirectX into two sets of services: the low-level DirectX foundation and high-level DirectX media.
The big-picture organization of DirectX services is shown in Figure 1.
Figure 1. DirectX architecture
DirectX foundation provides the basis for performance media on Windows-based computers, through DirectDraw®, DirectInput®, DirectSound®, and Direct3D® Immediate Mode:
Figure 2. DirectX foundation
DirectX media is a set of higher-level APIs that use DirectX foundation. These services include Direct3D Retained Mode, DirectShow™, DirectAnimation™, DirectModel and DirectShow. Support for Virtual Reality Markup/Modeling Language (VRML) is also provided in DirectX media.
Figure 3. DirectX Media
DirectX 5.0 is primarily an upgrade of DirectX foundation; DirectX 5.0.1 in the near future will be the first major release of DirectX media, which will include DirectAnimation, DirectShow (the system-level portions of ActiveMovie™), and VRML support.
The key new features in DirectX 5.0 are summarized below:
Table 1. New DirectX features
| DirectX 5.0 Service | Description | New features |
| DirectX foundation | ||
| DirectDraw | Graphics surface management | Video-ports, new MMX HEL, AGP |
| DirectSound | Sound mixer and effects | 3D HAL, capture, property sets |
| Direct3D Immediate Mode | Low-level 3D display | DrawPrimitive, overloads |
| DirectInput | Input device interface | New devices, force feedback |
| DirectSetup | Driver installation | Improved driver updating, user interface customization |
| DirectX media | ||
| Direct3D Retained Mode | 3D scene graph | Interpolators, progressive meshes |
| Microsoft DirectPlay® | Multiuser player | Connection shortcuts, improved password protection, secure server connections |
Most APIs in the DirectX Software Development Kit (SDK) are composed of objects and interfaces based on the Component Object Model (COM). COM is a foundation for an object-based system that focuses on reuse of interfaces, and it is the model at the heart of COM programming. It is also an interface specification from which any number of interfaces can be built. It is an object model at the operating-system level.
Many DirectX APIs are created as instances of COM objects. You can consider an object to be a black box that represents the hardware and requires communication with applications through an interface. The commands sent to and from the object through the COM interface are called methods. For example, the IDirectDraw2::GetDisplayMode method is sent through the IDirectDraw2 interface to get the current display mode of the display adapter from the DirectDraw object.
Objects can bind to other objects at run time, and they can use the implementation of interfaces provided by the other object. If you know an object is a COM object, and if you know which interfaces that object supports, your application (or another object) can determine which services the first object can perform. One of the methods all COM objects inherit, the QueryInterface method, lets you determine which interfaces an object supports and creates pointers to these interfaces.
COM dictates that objects update their functionality not by changing the methods within existing interfaces, but by extending new interfaces that encompass new features. By keeping existing interfaces static, an object built on COM can freely extend its services while maintaining compatibility with older applications.
DirectX components follow this philosophy. For example, the DirectDraw component supports three versions of the IDirectDrawSurface interface: IDirectDrawSurface, IDirectDrawSurface2, and IDirectDrawSurface3. Each version of the interface supports the methods provided by its ancestor, adding new methods to support new features. If your application doesn't need to use these new features, it doesn't need to retrieve newer interfaces. However, to take advantage of features provided by a new interface, you must call the object's IUnknown::QueryInterface method, specifying the globally unique identifier (GUID) of the interface you want to retrieve. Interface GUIDs are declared in the corresponding header file.
In some rare cases, a new interface will not support some methods provided in a previous interface version. The IDirect3DDevice2 interface is an example of this type of interface. If your application requires features provided by an earlier version of an interface, you can query for the earlier version in the same way as shown in the preceding example, using the GUID of the older interface to retrieve it.
DirectDraw is the foundation for performance graphics and video on Windows platforms. DirectDraw is essentially a memory manager for graphics and video surfaces that provides access to hardware-accelerated functions like blitting and overlays.
DirectDraw works with a wide variety of display hardware, ranging from simple SVGA monitors to advanced hardware implementations that provide clipping, stretching, and non-RGB color format support. The interface is designed so that applications can enumerate the capabilities of the underlying hardware and then use any supported hardware-accelerated features. DirectDraw emulates features that are not implemented in hardware.
DirectDraw is not a high-level graphics API that draws graphics primitives like lines and rectangles. Instead, DirectDraw is a low-level API that operates at the graphics surface level, providing the base for higher-level two-dimensional (2-D) and three-dimensional (3-D) graphics APIs.
Key features of DirectDraw are:
DirectDraw also provides:
These features combine to make it possible for you to write applications that easily out-perform standard Windows GDI-based applications and even MS-DOS–based applications.
The key reason to use DirectDraw is that it offers faster graphics performance than the standard Microsoft Win32® graphics functions and provides access to a new generation of graphics accelerators.
Most Windows programs access drawing surfaces indirectly through the Win32 device context functions such as GetDC. The application then writes indirectly to the device context through the graphics device interface (GDI) system. The GDI is a system component that provides an abstraction layer that enables standard Windows applications to draw to the screen.
The drawback of GDI is that it was not designed for high-performance multimedia software, it was made to be used by business applications like word processors and spreadsheet applications. GDI provides access to a video buffer in system memory, not video memory, and does not take advantage of special features that some video cards provide. In short, GDI is great for most types of business software, but its performance is too slow for multimedia or game software.
On the other hand, DirectDraw provides drawing surfaces that represent actual video memory. This means that with DirectDraw an application can write directly to the memory on the video card, making your graphics routines extremely fast. These surfaces are represented as contiguous blocks of memory, making it easy to perform addressing within them.
A surface is memory that represents visual images. A surface can be memory physically located on a graphics board, or it can an also be system memory used for graphics or video purposes.
Unless specifically instructed otherwise during the creation of the DirectDrawSurface object, DirectDraw object will put the DirectDrawSurface object wherever the best performance can be achieved given the requested capabilities. DirectDrawSurface objects can take advantage of specialized processors on display cards, not only to perform certain tasks faster, but also to perform some tasks in parallel with the system CPU.
DirectDraw provides device-dependent access to display memory in a device-independent way. Essentially, DirectDraw manages display memory. Your application need only recognize some basic device dependencies that are standard across hardware implementations, such as RGB and YUV color formats and the pitch between raster lines. You need not call specific procedures to use the blitter or manipulate palette registers. Using DirectDraw, you can manipulate display memory with ease, taking full advantage of the blitting and color decompression capabilities of different types of display hardware without becoming dependent on a particular piece of hardware.
DirectDraw is a software interface that provides direct access to display devices while maintaining compatibility with the Windows GDI. DirectDraw provides a device-independent way for games and Windows subsystem software, such as 3-D graphics packages and digital video codecs, to gain access to the features of specific display devices.
A video port, new in DirectX 5.0, is hardware on a display device that enables direct access to a surface within the frame buffer, bypassing the CPU and PCI bus. Direct frame buffer access makes it possible to efficiently play live or recorded video without creating noticeable load on the CPU. Once in a surface, an image can be displayed on the screen as an overlay, used as a Direct3D texture, or accessed by the CPU for capture or other processing.
In a machine equipped with a video port, data in a video stream can flow directly from a video source through a video decoder and the video port to the frame buffer. These components often exist together on a display adapter, but can be on separate hardware components that are physically connected to one another.
An example of this data flow is shown in Figure 4.
Figure 4. Video data flow
Video source. In the scope of video-port technology, a video source is strictly a hardware video input device, such as a Zoom Video port, MPEG codec, or other hardware source. These sources broadcast signals in a variety of formats, including NTSC, PAL, and SECAM (or in a digital TV format) through a physical connection to a video decoder.
Video decoder. A video decoder is also a hardware component. The video decoder's job is to decipher the information provided by the video source and send it to the video port in an agreed upon connection format. The decoder possesses a physical connection to the video port, and exposes its services through a stream class minidriver. The decoder is responsible for sending video data and clock and sync information to the video port.
Video-port. Like the other components in the data flow path, the video-port is a piece of hardware. The video port exists on the display adapter's VGA chip and has direct access to the frame buffer. It receives information sent from the decoder, processes it, and places it in the frame buffer to be displayed. During processing, the video port can manipulate image data to provide scaling, shrinking, color control, or cropping services.
Frame buffer. The frame buffer accepts video data as provided by the video port. Once received, applications can programmatically manipulate the image data, blit it to other locations, or show it on the display using an overlay (the most common function).
DirectSound is the audio component of DirectX. DirectSound enables hardware and software sound mixing, capture, and effects like 3-D positioning and panning.
Key features of DirectSound are:
Despite the advantages of DirectSound, the standard waveform-audio functions in Windows continue to be a practical solution for certain tasks. For example, an application can easily play a single sound or audio stream, such as introductory music, by using the PlaySound or WaveOut functions.
The relationship between DirectSound and Windows sound functions is shown in Figure 5.
Figure 5. The DirectSound and Windows sound relationship
DirectSound is essentially a sound mixing engine. The application places a set of sounds in buffers, called secondary buffers. DirectSound combines these sounds and writes them into a primary buffer, which holds the sound that the listener actually hears.
DirectSound automatically creates a primary buffer, which typically will reside in memory on a sound card. The application creates the secondary buffers either in system memory or directly on the sound card.
Figure 6. How DirectSound works
Depending on the type of sound card, DirectSound buffers can exist in hardware as on-board RAM, wave-table memory, a direct memory access (DMA) channel, or a virtual buffer (for an input/output [I/O] port–based audio card). Where there is no hardware implementation of a DirectSound buffer, it is emulated in system memory. Secondary sound buffers can be either static (contain a complete sound) or streaming (a small sound buffer that plays a lengthy sound because the application dynamically loads data into the buffer while it is playing).
Only the available processing time limits the number of buffers that DirectSound can mix, and an application can query a sound buffer to determine what percentage of main processing cycles are needed to mix the sound buffer. The DirectSound mixer can provide as little as 20 milliseconds of latency, so there is no perceptible delay before play begins. Under these conditions, if an application plays a buffer and immediately begins a screen animation, the audio and video appear to start at the same time. However, if DirectSound must emulate hardware features in software, the mixer cannot achieve low latency and a longer delay (typically 100-150 milliseconds) occurs before the sound is reproduced.
DirectSound supports pulse-code modulation (PCM) sound data, but does not currently support compressed wave formats. DirectSound does not include functions for parsing a sound file. It is the responsibility of the developer to stream data in the correct format into the secondary sound buffers.
Multiple applications can create DirectSound objects for the same sound device. When the input focus changes between applications, the audio output automatically switches from one application's streams to another's. Applications thus do not have to repeatedly play and stop their buffers when the input focus changes. Also sound buffers can have "sticky focus"—the ability of sounds from one application to play while the user is using another application.
DirectSound's mixing engine does not simply mix several sounds together. It can also apply effects to a sound as it is written from a secondary buffer into the primary buffer. Although these effects are audible using standard loudspeakers, they are more obvious and compelling when the user wears headphones.
Basic effects are volume and frequency control and panning (changing the relative volume between the left and right audio channels).
But DirectSound can also simulate 3-D positional effects through the following techniques:
An application can also implement its own custom mixing algorithm, and DirectSound will let the application write directly to the primary buffer.
DirectInput provides high-performance access to input devices including the mouse, keyboard, joystick, and the new force-feedback (input/output) devices that are coming to market.
Why use DirectInput over the standard Win32 API input device functions? DirectInput offers two key benefits:
Like other DirectX components, DirectInput is based on COM. The basic architecture of DirectInput is a hierarchy of objects:
DirectInput's object architecture is summarized in Figure 7.
Figure 7. DirectInput architecture
DirectInput supplies two types of data: buffered and immediate. Buffered data is a record of events that is stored until an application retrieves it. Immediate data is a snapshot of the current state of a device.
There are two ways to find out whether input data is available: by polling and by event notification. Polling a device means regularly getting the current state of the device objects with IDirectInputDevice::GetDeviceState or retrieving the contents of the buffer with IDirectInputDevice::GetDeviceData.
Polling is typically used by real-time games that are never idle but are constantly updating and rendering the game world. Event notification is suitable for applications that wait for input before doing anything. To use event notification, the application sets up a thread synchronization object with the Win32 CreateEvent function and then associates this event with the device by passing its handle to IDirectInputDevice::SetEventNotification. DirectInput then signals the event whenever the state of the device changes. The application can receive notification of the event with a Win32 function such as WaitForSingleObject, and then respond by checking the input buffer to find out what the event was.
Because DirectInput works directly with the device drivers, it either suppresses or ignores mouse and keyboard messages. When using the mouse in exclusive mode, DirectInput suppresses mouse messages; as a result, Windows is unable to show the standard cursor.
DirectInput also ignores mouse and keyboard settings made by the user in the Windows Control Panel. For the mouse, DirectInput ignores Control Panel settings such as acceleration and swapped buttons. Again, DirectInput works directly with the mouse driver, bypassing the subsystem of Windows that interprets mouse data for windowed applications. For a joystick or other game device, DirectInput does use the calibrations set by the user in Control Panel.
For the keyboard, DirectInput does not use character repeat settings. When using buffered data, DirectInput interprets each press and release as a single event, with no repetition. When using immediate data, DirectInput is concerned only with the present physical state of the keys, not with keyboard events as interpreted by Windows.
As far as DirectInput is concerned, the keyboard is not a text input device but a game pad with many buttons. When an application requires text input, DirectInput is not the recommended method. It is far easier to retrieve the data from the normal Windows messages, which conveniently offer services such as character repeat and translation of physical keys to virtual keys.
Unlike a typical input device like a mouse, keyboard, or joystick, a force-feedback device is also an output device. This means that a force-feedback device moves or responds in some way to output from the application. For example, a joystick could be made to vibrate to simulate the motor of a racecar or kick back when firing a missile. A motor mounted in the base of a joystick could create the "force" in the joystick. Force feedback devices are beginning to appear on the market at consumer price points.
DirectInput provides a generalized interface for force-feedback devices through the DirectInputEffect object. A particular instance of movement or resistance over a period of time is called an effect. With DirectInput, an application can define, manipulate and apply a wide range of standard and custom effects to a force feedback device.
DirectInput supports several standard categories of effects. These types of effects are called forces, and include:
Square
Sine
Cosine
Triangle
SawtoothUp. The waveform drops vertically after it reaches maximum positive force.
SawtoothDown. The waveform rises vertically after it reaches maximum negative force.
Friction. The force is applied when the axis is moved, and depends on the defined friction coefficient.
Damper. The force increases in proportion to the velocity with which the user moves the axis.
Inertia. The force increases in proportion to the acceleration of the axis.
Spring. The force increases in proportion to the distance of the axis from a defined neutral point.
Table 2 lists the standard forces supported by DirectInput.
Table 2. DirectInput Standard Forces
| DirectInput Force Types | |
| GUID_ConstantForce | GUID_SawtoothDown |
| GUID_RampForce | GUID_Spring |
| GUID_Square | GUID_Damper |
| GUID_Sine | GUID_Inertia |
| GUID_Triangle | GUID_Friction |
| GUID_SawtoothUp | GUID_CustomForce |
The strength of the force is called its magnitude. Magnitude is measured in units ranging from zero (no force) to 10,000 (maximum force for the device). A negative value indicates force in the opposite direction. Magnitudes are linear: a force of 10,000 is twice as great as one of 5,000.
Ramp forces have a beginning and ending magnitude. The basic magnitude of a periodic effect is the force at the peak of the wave.
The direction of a force is the direction from which it comes; just as a north wind comes from the north, a positive force on a given axis pushes from the positive toward the negative.
Effects also have duration, measured in microseconds. Periodic effects have a period, or the duration of one cycle, also measured in microseconds. The phase of a periodic effect is the point along the wave where playback begins.
A sawtooth periodic force is shown in Figure 8.
Figure 8. A sawtooth periodic force
A force may be modified by an envelope. An envelope is a "wrapper" that constrains a force within specified ranges over time. For example, an envelope could look similar to Figure 9.
Figure 9. A force envelope
An envelope defines an attack value and a fade value, which modify the beginning and ending magnitude of the effect. Attack and fade also have duration that determines how long the magnitude takes to reach or fall away from the sustain value, the magnitude in the middle portion of the effect.
When the envelope shown in Figure 9 is applied to a sawtooth force, the resulting force would appear as shown in Figure 10.
Figure 10. Combining an envelop with a sawtooth periodic force
The force shown in Figure 10 would make a joystick pulsate for a period of time—first with more pronounced pulses that declined in force, stayed constant for a while, then faded down.
Before an effect can be played, it must be downloaded to the device. Generally this means the driver will put the parameters of the effect in hardware memory. This speeds up the playback of the effect and reduces latency, and is particularly important for actions like trigger responses, such as a "fire" button. Ideally the device will not have to communicate with the system at all in order to respond to axis movements and button presses.
Direct3D Immediate Mode is designed to enable world-class game and interactive 3-D graphics on a computer running Windows. Its mission is to provide device-dependent access to 3-D video-display hardware in a device-independent manner. Simply put, Direct3D is a drawing interface for 3-D hardware.
You can use Direct3D in either of two modes: Immediate Mode or Retained Mode. Microsoft developed the Direct3D Immediate Mode as a low-level 3-D API. Immediate Mode is ideal for developers who need to port games and other high-performance multimedia applications to the Microsoft Windows operating system. Immediate Mode is a device-independent way for applications to communicate with accelerator hardware at a low level.
Retained Mode is a high-level 3-D application programmer interface (API) for programmers who require rapid development or who want the help of Retained Mode's built-in support for hierarchies and animations. Direct3D Retained Mode is built on top of Immediate Mode.
Key features of Direct3D Immediate Mode include:
The world management of Immediate Mode is based on vertices, polygons, and commands that control them. It allows immediate access to the transformation, lighting, and rasterization 3-D graphics pipeline and provides emulation for missing hardware functionality. (The programmer is always told which capabilities are in hardware and which are being emulated.)
There are two ways to use Immediate Mode: you can use the DrawPrimitive methods introduced in DirectX 5.0 or you can work with execute buffers (display lists) that have always existed in the Immediate Mode.
Most developers who have never worked with Immediate Mode before will use the DrawPrimitive methods. Developers who already have an investment in code that uses execute buffers will probably continue to work with them.
DrawPrimitive is an easy-to-use API for 3-D drawing. DrawPrimitive draws 3-D triangles, lines, and points—the fundamental primitives of 3-D—into DirectDraw surfaces.
DrawPrimitive is a simple, compact API—a set of 17 methods that extend the Direct3D device interface. This design simplicity makes DrawPrimitve ideal for a wide range of 3-D–related tasks, from quick prototyping and adding 3-D elements to existing applications to interfacing 3-D engines and toolkits to 3-D hardware.
DrawPrimitive does not require specific 3-D hardware, but is optimized to deliver maximum performance on both software-only and hardware-accelerated systems. DrawPrimitive is designed to be a foundation interface for 3-D acceleration that is rapidly becoming a standard computing capability.
DrawPrimitive provides a simple yet extremely powerful set of functions to perform the foundation operations of 3-D drawing. Whether your task is to add a few 3-D elements to an existing application or interface an entire 3-D game engine or tool to 3-D hardware, DrawPrimitive provides the essential primitive-level draw functionality you will need.
DrawPrimitive was designed with three key design goals: ease of use, DirectX compatibility, and scalable performance.
Ease of use. Ease of use is the key design goal of DrawPrimitive. Ease of use is a critical feature for anyone using a 3-D API:
DirectX compatibility. The second design goal for DrawPrimitive is DirectX compatibility. The reason is simple: DirectX is enormously successful, with hundreds of applications using DirectX technologies and millions of DirectX-enabled devices already in use. The DirectX family of performance graphics and media services are quickly become a core, universal PC media playback facility. As an extension of DirectX, DrawPrimitive API continues the DirectX "direct" design and interface philosophy, combining software emulation and hardware abstraction to unify and innovate digital media playback.
And indeed, users will find DrawPrimitive immediately familiar. Direct3D Immediate Mode users will perceive DrawPrimitive as a natural extension of Direct3D execute buffers, which are in essence user-compiled blocks of DrawPrimitive commands. DirectDraw users will find DrawPrimitive a simple and fast way to draw 3-D primitives into the DirectDraw surfaces they are already using. Device driver writers will find adding a DrawPrimitive extension to existing DirectX drivers to involve only a matter of days or weeks of effort.
All of this underscores the Microsoft commitment to DirectX as a core technology. DrawPrimitive protects the investment in DirectX technologies by ISVs and IHVs, while at the same time extending the functionality of DirectX over time.
Scalable performance. The final design goal of DrawPrimitive is scalable performance. This means that DrawPrimitive is designed to deliver to the API user the maximum performance available on the full range of 3-D–capable computing architectures.
There is no single universal 3-D computing architecture, and innovation in media computing architectures is sure to continue. A foundation 3-D draw API must therefore be scalable from plain software-only systems to various media processing architectures, from simple hardware triangle engines to advanced commodity media architectures like Talisman. This is a major design challenge, and requires hardware abstraction, software emulation, and the capability of the programmer to query and configure for a particular system.
DrawPrimitive is designed to do one thing very well—draw 3-D primitives. This requires supporting a variety of formats for describing 3-D primitives.
Triangles. DrawPrimitives supports triangle lists, triangle strips, and triangle fans:
Figure 11. Triangles
DrawPrimitive uses triangles to represent both simple and complex surfaces through texture mapping and shading algorithms.
Lines and points. DrawPrimitive supports line lists, line strips, and point lists:
Figure 12. Lines and Points
Indexed primitives. DrawPrimitive can represent primitives in two formats: as a list of vertices, or as a list of vertices plus an index into the list of vertices. For primitives described a list of vertices, the draw engine simply processes the vertices in the order they appear in the vertex list. For indexed primitives, the draw engine processes the vertex list in the order described by the index list.
The conceptual architecture of DrawPrimitive is straightforward. A core set of functions is used to pass 3-D primitives to a draw engine, which then draws the primitives into a DirectDraw surface. The Draw engine uses a transform formula to calculate how to convert locations in 3-D space into 2-D screen coordinates and uses a set of state variables that specify the stylistic characteristics of the draw operation.
The DrawPrimitive architecture is summarized in Figure 13.
Figure 13. The DrawPrimitive architecture
The 3 components of the Direct3D device are:
Transform. The transform is a set of formulas that describe how to convert a vertex's position in 3-D space into 2-D screen coordinates. The transform is actually made up of 3 matrix formulas, the world, view and projection matrix. The Transform matrices are configured with the SetTransform or MultiplyTransform methods or with helper macros.
State variables. State variables describe the current style settings for drawing operations.
Draw engine. The draw engine performs 3 separate functions: transformation, lighting, and rasterization. The API user can choose which of these functions the draw engine should perform by describing the vertex data in a particular vertex format. D3DVertex describes a vertex for the draw engine to transform, light and rasterize. D3DLVertex describes a vertex for which the calling application has already determined the color (a "lit" vertex). D3DTLVertex is used by the calling application to describe an already transformed and lit vertex, and the draw engine only needs to draw the primitive.
Direct3D Retained Mode is a high-level 3-D scene graph manager that simplifies the building and animation of 3-D worlds and data.
All access to Direct3D Retained Mode is through a small set of objects. Table 3 lists these objects and a brief description of each:
Table 3. Direct3D Retained Mode Objects
| Object | Description |
| Direct3DRMAnimation | Defines how a transformation will be modified, often in reference to a Direct3DRMFrame or Direct3DRMFrame2 object. You use it to animate position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects. |
| Direct3DRMAnimationSet | Allows Direct3DRMAnimation objects to be grouped together. |
| Direct3DRMDevice | Represents the visual display destination for the renderer. |
| Direct3DRMDevice2 | Same as the Direct3DRMDevice object but with enhanced control of transparency. |
| Direct3DRMFace | Represents a single polygon in a mesh. |
| Direct3DRMFrame | Positions objects within a scene and defines the positions and orientations of visual objects. |
| Direct3DRMFrame2 | Extends the Direct3DRMFrame object by enabling access to the frame axes, bounding boxes, and materials. Also supports ray picking. |
| Direct3DRMInterpolator | Stores actions and applies the actions to objects with automatic calculation of in-between values. |
| Direct3DRMLight | Defines one of five types of lights that are used to illuminate the visual objects in a scene. |
| Direct3DRMMaterial | Defines how a surface reflects light. |
| Direct3DRMMesh | A set of polygonal faces. You can use this object to manipulate groups of faces and vertices. |
| Direct3DRMMeshBuilder | Allows you to work with individual vertices and faces in a mesh. |
| Direct3DRMMeshBuilder2 | Allows you to work with individual vertices and faces in a mesh. Same as the Direct3DRMMeshBuilder object but with than the Direct3DRMMeshBuilder object. |
| Direct3DRMObject | A base class used by all other Direct3D Retained-Mode objects; it has characteristics that are common to all objects. |
| Direct3DRMPickedArray | Identifies a visual object that corresponds to a given 2-D point. |
| Direct3DRMPicked2Array | Identifies a visual object corresponding to a given ray intersection. |
| Direct3DRMProgressiveMesh | A coarse base mesh together with records describing how to incrementally refine the mesh. This allows a generalized level of detail to be set on the mesh as well as progressive download of the mesh from a remote source. |
| Direct3DRMShadow | Defines a shadow. |
| Direct3DRMTexture | A rectangular array of colored pixels. |
| Direct3DRMTexture2 | Same as the Direct3DRMTexture object except that resources can be loaded from files other than the currently executing file, textures can be created from images in memory, and you can generate MIP maps. |
| Direct3DRMUserVisual | This object is defined by an application to provide functionality not otherwise available in the system. |
| Direct3DRMViewport | Defines how the 3-D scene is rendered into a 2-D window. |
| Direct3DRMVisual | Anything that can be rendered in a scene. Visual objects need not be visible; for example, a frame can be added as a visual. |
| Direct3DRMWrap | Calculates texture coordinates for a face or mesh. |
An animation in Retained Mode is defined by a set of keys. A key is a time value associated with a scaling operation, an orientation, or a position. A Direct3DRMAnimation object defines how a transformation is modified according to the time value. The animation can be set to operate on a Direct3DRMFrame object, so it could be used to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.
The IDirect3DRMAnimation::AddPositionKey, IDirect3DRMAnimation::AddRotateKey, and IDirect3DRMAnimation::AddScaleKey methods each specify a time value whose units are arbitrary. If an application adds a position key with a time value of 99, for example, a new position key with a time value of 49 would occur exactly halfway between the (zero-based) beginning of the animation and the first position key.
Calling the IDirect3DRMAnimation::SetTime method drives the animation. This sets the visual object's transformation to the interpolated position, orientation, and scale of the nearby keys in the animation. As with the methods that add animation keys, the time value for IDirect3DRMAnimation::SetTime is an arbitrary value, based on the positions of keys the application has already added.
A Direct3DRMAnimationSet object allows Direct3DRMAnimation objects to be grouped together. This allows all the animations in an animation set to share the same time parameter, simplifying the playback of complex articulated animation sequences. An application can add an animation to an animation set by using the IDirect3DRMAnimationSet::AddAnimation method, and it can remove one by using the IDirect3DRMAnimationSet::DeleteAnimation method. Calling the IDirect3DRMAnimationSet::SetTime method drives animation sets.
A mesh is a visual object that is made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces.
A progressive mesh is a mesh that is stored as a base mesh (a coarse version) and a set of records that are used to increasingly refine the mesh. This allows you to set the level of detail rendered for a mesh and also allows progressive download from remote sources.
Using the methods of the IDirect3DRMProgressiveMesh interface, you can set the number of vertices or faces to render and thereby control the render detail. You can also specify a minimum level of detail required for rendering. Normally, a progressive mesh is rendered once the base mesh is available, but with the IDirect3DRMProgressiveMesh::SetMinRenderDetail method you can specify that a greater level of detail is necessary before rendering. You can also build a Direct3DRMMesh object from a particular state of the progressive mesh using the IDirect3DRMProgressiveMesh::CreateMesh method.
You can load a progressive mesh from a file, resource, memory, or Universal Resource Locator (URL). Loading can be done synchronously or asynchronously. You can check the status of a download with the IDirect3DRMProgressiveMesh::GetLoadStatus method, and terminate a download with the IDirect3DRMProgressiveMesh::Abort method. If loading is asynchronous, it is up to the application to use events through the IDirect3DRMProgressiveMesh::RegisterEvents and IDirect3DRMProgressiveMesh::GetLoadStatus methods to find out how the load is progressing.
DirectPlay makes it easy to connect games over the Internet, a modem link, or a network.
DirectPlay is a software interface that simplifies application access to communication services. DirectPlay has become a technology family that not only provides a way for applications to communicate with each other, independent of the underlying transport, protocol, or online service, but also provides this independence for matchmaking servers, game servers, and billing.
Applications (especially games) can be more compelling if they can be played against real players, and the personal computer has richer connectivity options than any game platform in history. Instead of forcing the developer to deal with the differences that each connectivity solution represents, DirectPlay provides well-defined, generalized communication capabilities. DirectPlay shields developers from the underlying complexities of diverse connectivity implementations, freeing them to concentrate on producing a great application.
DirectPlay 5.0 has a new interface, IDirectPlay3. This interface inherits directly from IDirectPlay2 and by default behaves as IDirectPlay2. All new functionality is enabled through new methods or new flags.
DirectPlay 5.0 includes numerous new features and improvements:
IDirectPlay3::EnumConnections enumerates the connection shortcuts available to the application. This method supersedes DirectPlayEnumerate.
IDirectPlay3::InitializeConnection initializes a DirectPlay connection. This method supersedes DirectPlayCreate. The new IDirectPlayLobby2::CreateCompoundAddress method creates connection shortcuts to pass to the InitializeConnection method.
IDirectPlay3::SecureOpen creates or joins a session on a machine that uses Windows NT LAN Manager (NTLM) security.
IDirectPlay3::CreateGroupInGroup, IDirectPlay3::AddGroupToGroup, IDirectPlay3::DeleteGroupFromGroup, and IDirectPlay3::EnumGroupsInGroup add richer group functionality and navigation when connected to a lobby server.
IDirectPlay3::SendChatMessage enables players to chat with other players connected to a lobby server.
IDirectPlay3::SetGroupConnectionSettings, IDirectPlay3::GetGroupConnectionSettings, and IDirectPlay3::StartSession enable synchronized application launching from a lobby server.
Password protection of sessions has been greatly improved. The new DPCREDENTIALS structure holds the user name and password to use when connecting to a secure server. The DPSECURITYDESC structure describes the security properties of a DirectPlay session instance.
An application can create multiple DirectPlay objects.
Guaranteed messaging is available for all service providers.
A new multicast server improves group messaging.
Support has been added for highly scalable client/server architecture applications.
The DirectPlay API is a network abstraction that applications can be written to. The API defines the functionality of the abstract DirectPlay network and all the functionality is available to your application regardless of whether the actual underlying network supports it or not. In cases where the underlying network does not support a function, DirectPlay contains all the code necessary to emulate it. Examples include group messaging and guaranteed messaging.
The service provider architecture in DirectPlay insulates the application from the underlying network it is running on. The application can query DirectPlay for specific capabilities of the underlying network, such as latency and bandwidth, and adjust its communications accordingly.
Figure 14. The DirectPlay architecture
A DirectPlay session is a communications channel between several machines. Before an application can start communicating with other machines it must join a session. An application can do this in one of two ways: it can enumerate all the existing sessions on a network and join one of them, or it can create a new session and wait for other machines to join it. Once the application has joined a session, it can create a player and exchange messages with all the other players in the session.
Each session has one machine that is designated as the host. The host is the owner of the session and is the only machine that can change the properties of the session.
The following diagram illustrates the DirectPlay session model: An application must join a session to communicate with other machines using DirectPlay.
Figure 15. The DirectPlay session model
The most basic entity within a DirectPlay session is a player. A player represents a logical object within the session that can send and receive messages. DirectPlay does not have any representation of a physical machine in the session. Each player is identified as being either a local player (one that exists on your machine) or a remote player (one that exists on another machine). Each machine must have at least one local player before it can start sending and receiving messages. Individual machines can have more than one local player but within the context of a DirectPlay session they are considered to be distinct entities.
When an application sends a message, it is always directed to another player—not another machine. The player can be another local player (in which case the message will not go out over the network) or a remote player. Similarly, when messages are received by an application they are always addressed to a specific (local) player and marked as being from some other player (except system messages which are always marked as being from DPID_SYSMSG).
Figure 16. Player and group structure
DirectPlay supports the concepts of groups within a session. A group is logical collection of players. By creating a group of players, an application can send a single message to the group and all the players in the group will receive a copy of the message. A group is the means by which multicast capabilities of the network are exposed to the application.
Groups can also be used as a general means to organize players in a session. A player can belong to more than one group. Functions are provided for administering groups and their membership. Additional functions are also provided to associate names and data with individual groups as a convenience but are not necessary to use groups.
DirectSetup is a simple API that provides you with a one-call installation for the DirectX components. This is more than merely a convenience; DirectX is a complex product, and its installation is an involved task. You should not attempt to manually install DirectX.
In addition, DirectSetup provides an automated way to install the appropriate Microsoft Windows registry information for applications that use the DirectPlayLobby object. This registry information is required for the DirectPlayLobby object to enumerate and start the application.
User interface customization. DirectSetup now supports a callback function that provides notification of various types of events that occur during the setup of DirectX. This allows developers to customize the setup interface.
Unregister. Also new in this version of DirectSetup is the ability of DirectPlayLobby applications to remove registration information.
Applications and games that depend on DirectX use the DirectXSetup function to install their system components into an existing Windows installation. It optionally updates the display and audio drivers to support DirectX during the DirectX installation process. This process is designed to happen smoothly, without adversely affecting the user's system. Older drivers are upgraded whenever possible to prevent reduced performance or stability of all DirectX-based applications on a computer.
Note that the DirectXSetup function overwrites system components from previous versions of DirectX. For example, if you install DirectX 5.0 on a system that already has DirectX version 3.0 components, all DirectX 3.0 components will be overwritten. Because all DirectX components comply with COM backward-compatibility rules, software written for DirectX 3.0 will continue to function properly.
The DirectX SDK contains the \Redist directory. Setup programs that use the DirectXSetup function must distribute the entire contents of the Redist directory, not just the contents of the \Redist\Directx directory. They must also include Dsetup.dll, Dsetup16.dll, and Dsetup32.dll.
As with previous versions of DirectX, version 5.0 requires the installation of all components. Current DirectX components are tightly integrated together for maximum performance. Hence, they all need to be installed for any one of them to work.
The DirectXSetup function can tell when DirectX components, display drivers, and audio drivers need to be upgraded. It can also distinguish whether or not these components can be upgraded without adversely affecting the Windows operating system. This is said to be a "safe" upgrade. It is important to note that the upgrade is safe for the operating system, not necessarily for the applications running on the computer. Some hardware-dependent applications can be negatively affected by an upgrade that is safe for Windows.
The DirectXSetup function makes two passes through all of the installed drivers. The first pass is a dry run, during which the DirectXSetup function will not perform any upgrades. The second pass is the action run, during which the DirectXSetup function actually installs the drivers.
During this two-step process, DirectXSetup creates a backup copy of the system components and drivers that are replaced. These can typically be restored in the event of an error.
When display or audio drivers are upgraded, the DirectXSetup function utilizes a database created by Microsoft to manage the process. The database contains information on existing drivers that are provided either by Microsoft, the manufacturers of the hardware, or the vendors of the hardware. This database describes the upgrade status of each driver, based on testing done at Microsoft and at other sites.
For additional information on DirectX, please refer to the Microsoft DirectX Web site (http://www.microsoft.com/directx).
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.