(Editor's Note - this article requires additional formatting work and is incomplete)

To create a Windows-based Direct3D Immediate-Mode application, you create DirectDraw and Direct3D objects, set render states, fill execute buffers, and execute those buffers.

This section includes a simple Immediate-Mode application that draws a single, rotating, Gouraud-shaded triangle (please note: you will need to have the current version of DirectX installed in order to view the triangle). The triangle is drawn in a window whose size is fixed. For code clarity, we have chosen not to address a number of issues in this sample. For example, full screen operation, resizing the window, and texture mapping are not included. Furthermore, we have not included some optimizations when their inclusion would have made the code more obscure. Code comments highlight the places in which we did not implement a common optimization.

• [alink=m1]Definitions, Prototypes, and Globals[/alink]
• [alink=m2]Enumerating Direct3D Devices [/alink]
• [alink=m3]Creating Objects and Interfaces [/alink]
• [alink=m4]Creating the Scene [/alink]
• [alink=m5]Filling the Execute Buffer [/alink]
• [alink=m6]Animating the Scene [/alink]
• [alink=m7]Rendering [/alink]
• [alink=m8]Working with Matrices [/alink]
• [alink=m9]Restoring and Redrawing [/alink]
• [alink=m10]Releasing Objects [/alink]
• [alink=m11]Error Checking [/alink]
• [alink=m12]Converting Bit Depths[/alink]
• [alink=m13]Main Window Procedure [/alink]
• [alink=m14]WinMain Function[/alink]

[size="5"] [aname=m1]Definitions, Prototypes, and Globals

This section contains the definitions, function prototypes, global variables, constants, and other structural underpinnings for the Imsample.c code sample.

• [alink=s1-1]Header and Includes[/alink]
• [alink=s1-2]Constants [/alink]
• [alink=s1-3]Macros [/alink]
• [alink=s1-4]Global Variables [/alink]
• [alink=s1-5]Function Prototypes[/alink]

[size="3"][aname=s1-1]Header and Includes

[size="3"][aname=s1-2]Constants

[size="3"][aname=s1-3]Macros

[size="3"][aname=s1-4]Global Variables


[size="3"][aname=s1-5]Function Prototypes

[size="5"] [aname=m2]Enumerating Direct3D Devices

The first thing a Direct3D application should do is enumerate the available Direct3D device drivers. The most important API element in this job is IDirect3D::EnumDevices.

This section contains the ChooseDevice function that selects among the available Direct3D devices and the EnumDeviceCallback function that implements the selection mechanism.

• [alink=s2-1]Enumeration Callback Function[/alink]
• [alink=s2-2]Enumeration Function[/alink]

This sample application does not demonstrate the enumeration of display modes, which you will need to do if your application supports full-screen rendering modes. To enumerate the display modes, call the IDirectDraw3::EnumDisplayModes method.

[size="3"][aname=s2-1]Enumeration Callback Function

The EnumDeviceCallback function is invoked for each Direct3D device installed on the system. For each device we retrieve its identifying GUID, a name and description, a description of its hardware and software capabilities, and an unused user argument.

The EnumDeviceCallback function uses the following algorithm to choose an appropriate Direct3D device:

1. Discard any devices which don't match the current display depth.
2. Discard any devices which can't do Gouraud-shaded triangles.
3. If a hardware device is found which matches 1) and 2) use it. However, if we are running in debug mode we will skip hardware.
4. Otherwise favor Mono/Ramp mode software renderers over RGB ones as, at least until MMX is widespread, Mono will be faster.

This callback function is invoked by the ChooseDevice enumeration function, which is described in Enumeration Function.

Note that the first parameter passed to this callback function, lpGUID, is NULL for the primary device. All other devices should have a non-NULL pointer. You should consider saving the actual GUID for the device you choose, not the pointer to the GUID, in case the pointer is accidentally corrupted.

[size="3"][aname=s2-2]Enumeration Function

The ChooseDevice function invokes the EnumDeviceCallback function , which is described in Enumeration Callback Function.

[size="5"] [aname=m3]Creating Objects and Interfaces

This section contains functions that create the primary DirectDraw surface, a DirectDrawClipper object, a Direct3D object, and a Direct3DDevice.

• [alink=s3-1]Creating the Primary Surface and Clipper Object[/alink]
• [alink=s3-2]Creating the Direct3D Object [/alink]
• [alink=s3-3]Creating the Direct3D Device[/alink]

[size="3"][aname=s3-1]Creating the Primary Surface and Clipper Object

The CreatePrimary function creates the primary surface (representing the desktop) and creates and attaches a clipper object. If necessary, this function also creates a palette.

[aname[size="3"]=s3-2]Creating the Direct3D Object

The CreateDirect3D function creates the DirectDraw (Direct3D) driver objects and retrieves the COM interfaces for communicating with these objects. This function calls three crucial methods: DirectDrawCreate, to create the DirectDraw object, IDirectDraw3::SetCooperativeLevel, to determine whether the application will run in full-screen or windowed mode, and IDirectDraw::QueryInterface to retrieve a pointer to the Direct3D interface.

[size="3"][aname=s3-3]Creating the Direct3D Device

The CreateDevice function creates an instance of the Direct3D device we chose earlier, using the specified width and height.

This function handles all aspects of the device creation, including choosing the surface-memory type, creating the device surface, creating the z-buffer (if necessary), and attaching the palette (if required). If you create a z-buffer, you must do so before creating an IDirect3DDevice interface.


[size="5"][aname=m4]Creating the Scene

The CreateScene function creates the elements making up the 3D scene. In this sample, the scene consists of a single light, the viewport, the background and surface materials, the three transformation matrices, and the execute buffer holding the state changes and drawing primitives.


[size="5"][aname=m5]Filling the Execute Buffer

The FillExecuteBuffer function fills the single execute buffer used in this sample with all the vertices, transformations, light and render states, and drawing primitives necessary to draw our triangle.

NOTE: This is not the most efficient way of organizing the execute buffer. For best performance you should minimize state changes. In this sample we submit the execute buffer for each frame in the animation loop and no state in the buffer is modified. The only thing we modify is the world matrix (its contents--not its handle). Therefore, it would be more efficient to extract all the static state instructions into a separate execute buffer which we would issue once only at startup and, from then on, simply execute a second execute buffer with vertices and triangles.

However, because this sample is more concerned with clarity than performance, it uses only one execute buffer and resubmits it in its entirety for each frame.


[size="5"][aname=m6]Animating the Scene

The animation in this sample is simply a rotation about the Y axis. All we need to do is build a rotation matrix and set the world matrix to that new rotation matrix.

We don't need to modify the execute buffer in any way to peform this rotation. We simply set the matrix and resubmit the execute buffer.


[size="5"][aname=m7]Rendering
This section contains functions that render the entire scene and render a single frame.

• [alink=s7-1]Rendering the Scene[/alink]
• [alink=s7-2]Rendering a Single Frame[/alink]

[size="3"][aname=s7-1]Rendering the Scene

The RenderScene function renders the 3D scene, just as you might suspect. The fundamental task performed by this function is submitting the single execute buffer used by this sample. However, the function also clears the back and z-buffers and demarcates the start and end of the scene (which in this case is a single execute).

When you clear the back and z-buffers, it's safe to specify the z-buffer clear flag even if we don't have an attached z-buffer. Direct3D will simply discard the flag if no z-buffer is being used.

For maximum efficiency we only want to clear those regions of the device surface and z-buffer which we actually rendered to in the last frame. This is the purpose of the array of rectangles and count passed to this function. It is possible to query Direct3D for the regions of the device surface that were rendered to by that execute. The application can then accumulate those rectangles and clear only those regions. However this is a very simple sample and so, for simplicity, we will just clear the entire device surface and z-buffer. You should probably implement a more efficient clearing mechanism in your application.

The RenderScene function must be called once and once only for every frame of animation. If you have multiple execute buffers comprising a single frame you must have one call to the IDirect3DDevice::BeginScene method before submitting those execute buffers. If you have more than one device being rendered in a single frame, (for example, a rear-view mirror in a racing game), call the IDirect3DDevice::BeginScene and IDirect3DDevice::EndScene methods once for each device.

When the RenderScene function returns DD_OK, the scene will have been rendered and the device surface will hold the contents of the rendering.

[size="3"][aname=s7-2]Rendering a Single Frame

The DoFrame function renders and shows a single frame. This involves rendering the scene and blitting the result to the client area of the application window on the primary surface.

This function handles lost surfaces by attempting to restore the application's surfaces and then retrying the rendering. It is called by the OnMove function (discussed in Redrawing on Window Movement), the OnSize function (discussed in Redrawing on Window Resizing), and the OnPaint function (discussed in Repainting the Client Area).


[size="5"][aname=m8]Working with Matrices

This section contains two functions that work with matrices: the SetPerspectiveProjection function, which sets a given matrix to the appropriate values for the front and back clipping planes, and the SetRotationAboutY function, which sets a matrix to a rotation about the y axis.

• [alink=s8-1]Setting the Perspective Transformation[/alink]
• [alink=s8-2]Setting a Rotation Transformation[/alink]

[size="3"][aname=s8-1]Setting the Perspective Transformation

The SetPerspectiveProjection function sets the given matrix to a perspective transform for the given half-height and front- and back-clipping planes. This function is called as part of the CreateScene function, documented in Creating the Scene.

[size="3"][aname=s8-2]Setting a Rotation Transformation

The SetRotationAboutY function sets the given matrix to a rotation about the y axis, using the specified number of radians. This function is called as part of the AnimateScene function, documented in Animating the Scene.


[size="5"][aname=m9]Restoring and Redrawing

This section contains functions that restore objects and surfaces that may have been lost while the application is running.

• [alink=s9-1]Restoring the Direct3D Device[/alink]
• [alink=s9-2]Restoring the Primary Surface[/alink]
• [alink=s9-3]Restoring All Surfaces [/alink]
• [alink=s9-4]Redrawing on Window Movement [/alink]
• [alink=s9-5]Redrawing on Window Resizing [/alink]
• [alink=s9-6]Repainting the Client Area [/alink]
• [alink=s9-7]Updating the Viewport[/alink]

[size="3"][aname=s9-1]Restoring the Direct3D Device

The RestoreDevice function restores lost video memory for the device surface and z-buffer.

[size="3"][aname=s9-2]Restoring the Primary Surface

The RestorePrimary function attempts to restore the video memory allocated for the primary surface. This function will be invoked by a DirectX function returning DDERR_SURFACELOST due to a mode switch or fullscreen DOS box invalidating video memory.

[size="3"][aname=s9-3]Restoring All Surfaces

The RestoreSurfaces function attempts to restore all the surfaces used by the application.

[size="3"][aname=s9-4]Redrawing on Window Movement

[size="3"][aname=s9-5]Redrawing on Window Resizing

[size="3"][aname=s9-6]Repainting the Client Area

The OnPaint function repaints the client area, when required. Notice that it calls the DoFrame function to do much of the work, even though DoFrame rerenders the scene as well as blitting the result to the primary surface. Although the rerendering is not necessary, for this simple sample this inefficiency does not matter. In your application, you should rerender only when the scene changes.

For more information about the DoFrame function, see Rendering a Single Frame. The DoFrame function renders and shows a single frame. This involves rendering the scene and blitting the result to the client area of the application window on the primary surface..

[size="3"][aname=s9-7]Updating the Viewport

The UpdateViewport function updates the viewport in response to a change in window size. This ensures that we render at a resolution that matches the client area of the target window.