D3DFRAME Getting Started
Author: Philip Taylor
Release Date: May 15, 2000 will be filed on June 19, 2000
Download the source code of this article (63.9K)
Welcome to "Driving DirectX" second problem, MSDN Online Voices DirectX® column. In the following columns, I want to focus on Direct3D (R) (D3D) for DirectX 7.0. For D3D examples and D3DFrame, a good entry point is the DirectX Software Development Kit (SDK) application framework. All D3D examples use d3dframe.
Using a common frame D3DFrame, we provide us with a public platform, and we can discuss various functions on this platform.
Some graphics chip vendors use D3DFrame variants as their own examples; for example, ATI SDK uses D3DFrame versions with certain ATI-specific accessories. A public platform is provided using a public framework that can be discussed on this platform. Using a public frame also allows me to avoid the general "basic knowledge" of D3D. This does not mean that D3DFrame can be used as product code; instead, it is just a "convenient" tool to prepare short and clear examples.
Open-minded
Before starting to explain D3DFrame, let's review the DirectX SDK basic knowledge and provide a common language on SDK development. Make sure that the command to find header files and library file directories is correct in your created environment. Common problems is the commands of these errors, resulting in a lot of compilation and link errors. The default path to the DirectX SDK is / MSSDK. You can control the path when you install SDK. The header file and library files are saved in / MSSDK / Include and / MSSDK / LIB.
SDK HTML HELP is a major understanding of the main resources of DirectX, especially for D3D. I solved some questions, and after having a certain idea, I repeatedly read the paragraphs in the document, so I had a new feeling, "Oh, it turned out to be such a thing." Sample code is another one of learning DirectX The best tool. "Direct3D Immediate Mode" sample code is saved in / MSSDK / Samples / MultiMedia / D3DIM. The following is / d3dim below / bin, / include, / lib, / medium, and / src. All examples existing in the form of ready to establish, can be found in / src, depending on / include and / lib, and use the art contents in / Media. The SDK installer is implanted / bin pre-established executable. I highly recommend examples to test, and check the code required to use the functions listed. This is the fastest way to quickly use D3D.
Debugging DirectX applications may be a problem. Let me introduce several useful gadgets and techniques that make jobs. The DXDiag SDK utility provides information about the SDK installation. Be sure to make your system. If any defects are found, this information is required to report defects. Moreover, be sure to select the debug runtime option at the SDK installation. This ensures that the development of the debugging is developed and the runtime contains error checks and reports, which can really help you explain where the code has a deviation. Debug runtime allows settings to enable interior debugging of runtime. "DirectX Control Panel" allows developers to set the report level to 0 to 5. I am generally set to 3 during debugging, and for a particularly serious defect is set to 5. Any debugger can track debugging. The Visual C GUI debugger provides debug output panes that are specifically used to track debugging. The Visual C GUI debugger, only when using the following system, you can debug full-screen exclusive application: multi-monitor system remote debugging
Under this ideological guide, usually a sensible approach is to generate code and first debug in window mode, and then focus on full screen.
Advanced view
Let's go back to DirectX 7.0 D3DFrame now. D3DFrame is an example framework for the Direct3D SDK example. If you really want to learn how the example works - not understanding the features listed in the example - must have a basic understanding of how D3DFrame works. First of all, I will take you into the D3DFrame advanced view containing all the content you must understand, and write your own examples with D3DFrame. For those who are as curious in the like, I will give a summary introduction to a more detailed level of the main part of D3DFrame to explain how to provide an application interface. In the subsequent discussion, I will introduce more content about D3DFrame while using D3DFrame.
Figure 1. D3DFrame project view
D3DFrame consists of 7 modules:
D3DAPP demonstrates the application interface used by this example. D3DFrame provides the framework used by the application interface, "under this framework" will be very smooth. D3Denum contains enumeration support for drivers, devices, and patterns. D3DTextr provides texture support. D3DFile provides X-file support. D3DMATH gives a mathematical utility function. D3DUTIL includes all other useful functions.
Each module consists of a .cpp source file and .h header file. The source file is located in D3DIM / SRC. The header file is located in D3DIM / include. The frame library is located in D3DIM / lib. In view of this paper, I mainly discuss D3DAPP and D3DFrame.
Check the function written by the user
The D3DAPP module contains class CD3DApplication. This class publishes the interface for the sample program in the D3DApp.h file, as shown below:
An alternative 3D scene function created by the application // application
Virtual hResult onetimesceneinit () {returnide s_ok;}
Virtual HRESULT INITDEVICEOBJECTS () {Return S_OK;}
Virtual HRESULT DeletedEviceObjects () {Return S_OK;}
Virtual hResult render () {return s_ok;}
Virtual HRESULT FRAMEMOVE (FLOAT) {Return S_OK;}
Virtual HRESULT RESTORESURFCES () {Return S_OK;}
Virtual hResult finalcleanup () {return s_ok;}
To create a new D3D app using the sample frame, just create a new project and new implementation of these functions; let us call the "public interface" for the D3DFrame sample. This is what the D3D SDK example is done. Let's take a look at these functions: OneTimesceneinit allows examples to complete a one-time initialization task, such as loading textures and X-files, establishing a computational value, generating the structure of the program and a similar operation. Usually, any disposable resource allocation should be done here. On each application execution cycle, OneTimesceneinit is called once.
INitDeviceObjects provides an opportunity to initialize each device object. Typically, the program performs operations such as loading the texture bit to the device surface, setting a matrix, setting the light source, and filling vertex buffer, etc. InitDeviceObjects is called when initializing the first device and whenever the device changes.
DeleteDeviceObjects contains code for deleting objects created in InitDeviceObjects. These two functions are paired; be sure to make your device-specific resource allocation and deletion match, otherwise it will leak memory whenever the device changes. Calls DeleteDeviceObjects whenever the device is canceled.
Render is a place that is displayed. Here, remove the frame buffer and call all the display code between Beginscene / EndScene pairs. Turn the render once per frame.
Framemove provides a simplicity of collecting an animation task per frame. Update matrices, texture adjustments, object adjustments, and other changes in time occurred in Framemove. The framemove is called once per frame.
RESTORESURFCES makes the sample test the missing surface and resumes them, allowing the application to continue. Call RESTORESURFCES when the surface is lost due to application switching.
Finalcleanup pairs with OneTimesceneinit and provides a method of canceling an object of an application. Be sure to match the clear code to the initialization code to avoid memory leakage.
D3DFrame inside
Once the application of the application function is mastered, you should see what something will make them run accurately. In addition to the common interface, class CD3DApplication has two parts worth checking. First, class CD3DApplication contains the following member functions:
HRESULT INITIALIZE3DENVIRONMENT ();
HRESULT CHANGE3DENVIRONMENT ();
HRESULT RENDER3DENVIRONMENT ();
Void cleanup3denvironment ();
These functions use common interfaces and class CD3DFramework7 to process many of the work of D3D applications.
Initialize3Denvironment calls cd3dframework7-> initialize to initialize the sample framework, then call the public interface initDeviceObjects to initialize the dedicated object. Constructing this code for processing possible errors in the initialization process.
Change3denvironment changes for the application to process drivers, devices, and / or patterns. It calls the public interface deleteDeviceObjects to release the object of the old device. Then create a new device status and call Initialize3Denvironment to create a new device environment.
Render3Denvironment completes five important tasks. First, it checks the status of the cooperation to ensure that it can continue to show. Next, it is called the common interface Framemove with a movie that changes over time. Then call the common interface render to complete the drawing. Drawing if statistics are started. Finally, use the CD3DFramework7-> ShowFrame display frame. If the display frame causes surface loss, the framework and public interface RESTORESURFCES will be called. Cleanup3Denvironment call deleteDeviceObjects and Finalcleanup ready for the application.
We don't forget that the D3D application is actually a Windows application. The content of the win32 application is hidden in the member function:
Virtual HRESULT CREATE (Hinstance, Tchar *);
Virtual int Run ();
Virtual LRESULT MSGPROC (HWND HWND, UINT UMSG,
WPARAM WPARAM, LPARAM LPARAM;
Let us take a look at what WinMain changes when you look at the underlying explanation. In this example, WinMain is ended:
Int WinApi Winmain (Hinstance Hinst, Hinstance, LPSTR STRCMDLINE, INT)
{
CMYD3DApplication D3DAPP;
IF (failed (d3dapp.create (hinst, strcmdline)))
Return 0;
Return D3DAPP.Run ();
}
This is very simple WinMain. And hidden Create and Run's motivation is clear because they are WinMain. MsgProc is a Windows Message Handler. Inside, they all use the XX3Denvironment function and class CD3DFramework7 to manage D3D applications and Windows applications.
CREATE Using Module D3Denum provides support for enumeration drivers, device support, and current hardware mode support; it also selects a default. Then call the common interface OneTimesceneinit. Once the user object is created, the new CD3DFramework7 object will be instantiated. Need to pay attention to the general WIN32 details, register the window class, and then create a window. Finally, call Initialize3Devironment to create a new device environment.
Run completes two important tasks: Windows messages loop processing and calling render3denvironment. Run also prepares for WM_QUIT messages and exits.
MsgProc is a message handler for Windows messages. It relies on and manages Win32 and D3D applications using the XXX3Devironment function and CD3DFramework7 objects.
Now, I have generally introduced the working mode of the CD3DApplication class, and how it uses the CD3DFramework7 class, and then study CD3DFramework7 and its interior below.
The main heavy tasks in class CD3DFramework7 is completed by the following two sets of member functions:
// Create a framework
HRESULT Initialize (HWND HWND, GUID * PDRIVERGUID,
GUID * PDEVICEGUID, DDSURFACEDESC2 * PDDSD,
DWORD DWFLAGS;
HRESULT DESTROYOBJECTS ();
// Internal function of the frame class
HRESULT CREATEZBUFFER (GUID *);
HRESULT CREATEFULLSCREENBUFFERS (DDSurfaceDesc2 *); HRESULT CREATEWINDOWEDBUFFERS ();
HRESULT CREATEDIRECTDRAW (GUID *, DWORD);
HRESULT CREATEDIRECT3D (GUID *);
HRESULT CREATEENVIRONMENT (GUID *, Guid *, DDSurfaceDesc2 *,
DWORD);
Let us first see the first group, initialize and destroyObjects.
Initialize is a public function for creating an internal object. It builds internally and then relies on CreateEnvironment to complete most of the difficult work.
DESTROYOBJECTS only releases all DirectX COM objects created in Initialize.
CREATEENVIRONMENT Creates the internal object of the frame. It determines the memory type of the device and then calls CREATEDIRECTDRAW. Once they are not normal, CreateFullScreenBuffers or CreateWindowedBuffers creates a front desk and a backend buffer. Finally, createDirect3d creates a 3-D device, and CreatezBuffer is created and connected to the Z-buffer.
Given the purpose of understanding D3DFrame, we don't need to understand the detailed implementation of CreateDirectDraw, CreateFullScreenBuffers, CreateWindowedBuffers, CreateDirect3D, or CreatezBuffer. They are directly related - this sentence is enough. For those who want to know how to achieve accurate implementation, the source code is waiting for them to study.
The last few sets of functions worth mentioning in class cd3dframework7 provide additional support for display. They are:
/ / Help the function of display
HRESULT RESTORESURFCES ();
HRESULT Showframe ();
HRESULT FLIPTOGDISURFACE (Bool BdrawFrame = false);
Void Move (int X, int y);
For these contents, I am just a rough brought because they are used in previously verified functions, and their usage can be easily exported from context.
To create a new example, now you only need to implement a class, such as the CMYD3DApplication shown below:
Class CMYD3DApplication: Public CD3DApplication
{
protected:
HRESULT OneTimesceneinit ();
HRESULT INITDEVICEOBJECTS ();
HRESULT DeletedEviceObjects ();
HRESULT RENDER ();
HRESULT FRAMEMOVE (FLOAT FTIMEKEY);
HRESULT FINALCLEANUP ();
Static HRESULT ConfirmDevice (DDCaps *, D3DDeviceDesc7 *);
PUBLIC:
CMYD3DApplication ();
}
After completing, you have an effective D3DFrame example. It can be seen that it repeatedly appears in the D3D SDK example. Or wait for the next column. Only empty implementation features will cause empty D3D applications. I have completed it, it will be the basis of future columns, and I also provide source code. Empty D3D applications running in the window, as shown in Figure 2.
Figure 2. D3DFrameApp example
Conclude
As a problem with the following, please refer to the four DirectX 7.0 Direct3D articles about the following: Virtual lights Two articles about Alpha mixtures:
Alpha DotProduct3 in the vertex in the alpha dotproduct3 in the ALPHA texture
"Virtual Light" will illustrate how to manipulate Direct 3D light to avoid the eight light restrictions applied by most hardware. Alpha mixture articles will explain two different transparent techniques: transparency in transparency and textures in the vertex. DotProduct3 Articles will discuss very good DotProduct3 operators and their uses (prompts, can see DotProduct3 as a wide range of lookup functions from vector to pixels). Each article contains an example of D3DFrame.
Welcome to feedback! Welcome to the following address, tell me your comments, questions, themes, or your different opinions on this column involved. However, please don't expect a separate reply or send me a question that requests support. Keep in mind that Microsoft has a list of event emails, DirectXDEV, developers who are loser to share as forums. The web interface is located at http://discuss.microsoft.com/archives/directxdev.html. Before you ask, read FAQ, which is located at http://msdn.microsoft.com/library/techart/dxfaq2.htm (English).
