Direct3D Programming Tip #2: Use the Documentation

This is a programming tip? Well yeah, I’m sorry to report that often times its obvious from the questions people post that they either don’t know the documentation exists or they don’t use it. Personally, I don’t know how they can get anything done without the documentation. 3D graphics is hard! I put the shortcut to the documentation in my Quick Launch toolbar on the task bar:

  1. Click Start / Programs… and find the entry for the DirectX SDK.
  2. With the cursor over the DirectX SDK entry, right click to display the context menu and select Open
  3. While holding the Ctrl key, drag and drop the shortcut for the DirectX Documentation on the Quick Launch toolbar. A plus (+) sign should appear as you drop the shortcut to let you know that you’re making a copy of the shortcut and not moving it.

OK, now you’ve got the documentation at your fingertips ready to consult at any time. When I’m writing code that is talking directly to Direct3D interfaces, I usually leave the help browser open and just minimize it when I’m not using it. That way its only a quick Alt+TAB away while I’m coding.

OK, so with the documentation open, what’s the best way to use it? Well, if you’re looking for information on a particular symbol defined by the API such as D3DBLEND, then switch to the Index tab in the help viewer and start typing the symbol name. Entries should exist for all the symbols defined by the API. (I know I’ve filed a lot of bugs on missing enums from the index over the years. Microsoft fixed them all pretty promptly, usually by the next SDK release unless that release was already in code freeze.) For this particular example, the index entry for D3DBLEND takes you to the enum that defines all the values for alpha blending blend modes. OK, but what about #defines? They should all be indexed as well, as the index example for D3DCAPS2 shows.

For method names, you can enter just the beginning of the method name and you’ll see different index entries for different classes containing the same method. Go ahead and give it a try by typing GetDeviceCaps into the index tab’s search box. You’ll see separate entries for the following interfaces in the November 2008 SDK: IDirect3D9 and IDirect3DDevice9. If you know the interface and want to directly lookup a method on that interface, you can type the fully qualified method name. Give it a try by typing IDirect3D9 to see all the methods on the IDirect3D9 interface. You can then use the DownArrow key to select a particular method, or just keep typing the fully qualified name until the desired method is highlighted. Typing IDirect3D9::GetD is unique enough to highlight the GetDeviceCaps method on the interface.

If you’re looking for big overviews of the documentation, you’ll want to familiarize yourself with the Contents tab, which shows a hierarchical tree view of the documentation. I confess that I don’t use this portion of the documentation as much, unless I’m using it to drill down into the reference sections. I prefer to print out the user guide portion of documentation and read the printout. To print a chunk of the documentation as a single entity, right click on the tree node containing everything you want to print and select Print… from the context menu. A dialog box will appear asking if you want to print the selected topic or the selected heading and all subtopics. This way you can print out a chunk of the documentation as a single compact unit. Individual topics tend to be fairly short and usually don’t fill up the printed page when printed separately.

Next, is the search tab. For a newbie this is probably the most important place to start because you’re not familiar with the documentation or the API yet. I’ve seen lots of forum posts where someone asks a question and if I literally paste their question into this search box on the documentation, the first item in the search results is the one explaining their question. So you’ll definately want to become familiar with this.

Try out the search tab by typing D3DCAPS2 into the search box and click List Topics. You should get three entries with the titles D3DCAPS2, D3DCAPS9 and D3D Constants. You can double click any of the items in the search results to be shown the page that was found. Unfortunately the “Location” portion of the search results always just says “DirectX Software Development Kit”. I would rather it said something like “Direct3D9 Graphics”. With the Direct3D9 and Direct3D10 documentation mixed into the same help file, sometimes you have to check multiple entries to find the appropriate one. It will be clear when you’re looking at the wrong one.

One final thing to know about finding documentation with the search tab is the Locate button on the toolbar. Once you’ve found a particular page of interest to you, click Locate to have the Contents tab displayed and the table of contents tree view synchronized with the location of the page you’re viewing. All the tree view nodes above the displayed page will be opened up so you can see where to find this page through the table of contents.

For pages that you access frequently, you might want to set a bookmark on them. This is easy to do from the Favorites tab. Just display the help page you want to remember and select the Favorites tab. At the bottom of the tab is a text box that is prepopulated with the title of the page being displayed. You can edit this to be whatever you like. Then click Add. The next time you launch the help viewer, the favorites will be displayed and you can quickly navigate back to a piece of the documentation you frequently use.

One Response to “Direct3D Programming Tip #2: Use the Documentation”

  1. legalize Says:

    Starting with the August 2009 DirectX SDK, the graphics documentation is in a separate .CHM help file.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: