Getting Started with the DirectX 8 Library

Home | Up | Search | X-Zone News | Services | Book Support | Links | Feedback | Smalltalk MT | The Scrapyard | FAQ | Technical Articles

 

Getting Started with the DirectX 8 Library

 

This document is organized into the following topics:

bulletGetting started
bulletWhat's New in this Release
bulletLoading the DirectX 8 project
bulletTesting out DirectX 8
bulletDebugging
bullet Modifying a running application
bulletWorkspaces
bulletSummary
bulletAppendix
bulletInstallation Problems
bulletDriver Issues
bulletImage Settings
 

 

Getting started

The DirectX 8 Library consists of a set of frameworks, COM interfaces, and sample code that allow you to build powerful DirectX 8 applications interactively.

Installing the environment
Step 1: is to install Smalltalk MT (STMT) using stmt41.exe. (Assumption here is that you will install in the default directory C:\Program Files\Smalltalk MT 4). Choose complete to include all samples.

Step 2: copy Microsoft DirectX 8.1 media files (Media.zip) into C:\Program Files\Smalltalk MT 4\DirectX 8 Library\Media. These files are used for demonstration purposes in the samples and are not an integral part of the framework.

Launch STMT.exe
You will be presented with the Transcript. All other windows can be launched from the Transcript (STMT is an SDI application).

What's New in this Release

This version of the library is based on DirectX 8.1.

New Samples

bulletLighting

New Demos

bulletParticles

Changes

bulletParticle parameters are completely encapsulated in a structure, making it much easier to work with presets. The new Particle demo displays a UI that allows you to interactively control the parameters. The number of particles is now defined as the number of particles per second.
bulletWhen a DirectX frame window looses focus, it automatically inserts wait states to yield to other windows and processes.

Loading the DirectX 8 project

The DirectX framework projects and DirectX 8 DLLs now need to be bound in to the image, which is accomplished in the following steps:

  1. Open the Project Browser using Tools Menu -> Browsers -> Project Browser
  2. This window can be sized and preferences saved using Option Menu -> Save Preferences. The next time you open a new Project Browser it will use the preferences you saved.
  3. Use the File Menu -> Open … and navigate to C:\Program Files\Smalltalk MT 4\DirectX 8 Library\Samples
  4. Select the Dx8 samples.spx project and choose Open. The package contents will display in the PB. To load this package choose Project Menu -> File In[1]
  5. STMT will now advise that there are libraries (DLLs) that are not linked with the current image (these are the DX8 DLLs). Choose Yes to load the libraries.
  6. You will now be presented with three dialogs indicating the location of the DEF files for the DLLs (DINPUT8.def, STD3DX8.def and D3D8.def). Choose OK for all three dialogs.
  7. STMT will now recreate the development environment with the DirectX 8 DLLs bound in and restart the image.
  8. When the image restarts, the DirectX8 Application and all the samples will be loaded.


[1] To ‘File In’ in Smalltalk means to compile and load the code into the currently running development environment.

Testing out DirectX 8

bulletIn the Project Browser, select the project Triangle in the left hand pane. Next select the class DX::Triangle in the middle pane. Click right and select Test

.

The DX::Triangle application will start and display a spinning yellow triangle.

bulletTo see the class, click right onto DX::Triangle and select Browse Class. A Class Hierarchy Browser will open on the DX::Triangle class.
bulletAgain this window can be sized and saved using Tools Menu -> Save Preferences.
bulletTo test this application from the Class Hierarchy Browser, right click on the DX::Triangle class and choose Test. The application will open a window and display a rotating yellow triangle (rotating around the Y axis).

It is important to note that unlike Visual Studio, the application is running in the same process as the development environment. To further demonstrate this, let us change the running program. 

bulletSelect the method (right hand pane) frameMove.

On the third line from the bottom you will see a line:

matspin rotationY: m_fTime.

which calculates the Y rotation from the time the application has been running. Change this line to:

matspin rotationY: m_fTime/2.

bulletSave the new method by right clicking in the text pane and choosing Accept.

The triangle will now immediately begin to rotate at half the previous speed. Try m_fTime*3 to speed up rotation.

We have just modified a running program which is one of the greatest strengths of Smalltalk.

Debugging

Now let’s debug this application.

bulletAfter the line above (and before the line containing SetTransform) insert the following line (don’t forget the period at the end of the line):

self halt.

When you save the new method this time, a debugger window will display. First choose Window Menu -> Arrange windows and then save this with Options Menu -> Save Preferences.

The debugger window displays the call stack (top left), the locals (top right) and the current position (bottom).

In the locals window, you can expand out matSpin to see all of its values and by pressing the Resume toolbar button (far left), you can see the matspin matrix changing. Thus the debugger gives you ways of tracking complex changes.

To dismiss the debugger while leaving the application running, remove the self halt line in the debugger text and right click to accept. Choose resume to continue the application and close the debugger window. You will see the application continue to run.

bulletExit the application by closing the window.

Modifying a running application

Another example might be to test out different materials. To do this:

bulletGo to the method renderScene and insert as the first line:

self createMaterial.

bulletNow go to the method createMaterial and change the first float (currently 1.0) to 0.0 after the initMaterial:. 

The triangle immediately goes green.

Syntax
Just before we go into workspaces, we need to briefly review the Smalltalk syntax. All Smalltalk statements are of the form “receiver message” or “receiver message: param1” or “receiver message: param1 with: param2”. There are no exceptions to this rule. In addition, the Smalltalk standard does not define operator precedence.

1*3 + 3*4 will execute as (((1*3)+3)*4)

1*4<3*6 will execute as (((1*4)<3)*6)

unless of course you provide parenthesis yourself.

Note: Optionally, Smalltalk MT supports operator precedence. To enable operator precedence, open the Image Properties (in the Transcript, Tools Menu -> Image Properties), click on the Compiler Tab, and check the box labeled “Enable Operator Precedence”. Doing this makes your code incompatible with other Smalltalks.

Workspaces

bulletFrom the Class Hierarchy Browser choose Tools Menu -> New Workspace. Let’s call a DLL entry point by typing in:

WINAPI MessageBeep: -1

bulletExecute this line by choosing Smalltalk Menu -> Execute (Note: The cursor must be somewhere on the line you typed). The system bell will ring. You have just executed a DLL call (statically called) by executing this line as though it was a script!

Smalltalk code can be executed anywhere in a text pane which provides the ability to easily prototype and test. Workspaces also have the ability to create variables to hold onto values. For example, let us test out the PerformanceTimer. 

bulletIn a workspace enter:

a := PerformanceTimer new.

If you execute this line, you will be prompted that “a” is not defined. Do you wish to declare it as a workspace variable. Select Yes. 

bulletNow enter the line:

a tick

bulletThis time instead of executing this line, display this line using Smalltalk Menu -> Display. A float will be displayed showing the current tick value. Execute:

a resetTimer

bulletTo set the timer back to zero and then display the tick value again.

As you can see, it is simple to test out classes in a workspace for use in your code.

Exit Smalltalk MT
Exit Smalltalk by closing the Transcript. Choose Exit (not Save & Exit) to maintain a ‘clean’ image (choosing Save & Exit will save the image in its current state with all projects loaded).

Summary

This simple introduction introduces some of the rich features of Smalltalk MT. Smalltalk is extremely capable of handling complex and large applications. The image can be saved with all project code and then can be reloaded without the need to recompile.

Unit testing is part of Smalltalk development and is accomplished by calling methods from a workspace or in the running application.

Whole structures can be debugged and inspected and the developer can navigate through these.

Copyright © 2001 Genify  Corporation. All Rights Reserved. 

Appendix

Installation Problems

Media Path

If the samples don't run the cause is probably a faulty media path or missing media files. The media path is a registry entry that points to the location of media files. If the registry entry is missing, or if it points to a non-existing location, the framework tries to load media files from a media subdirectory, under the folder from which the program started.

The installation program sets the media path to c:\Program Files\Smalltalk MT 4\DirectX 8 Library\Media.

Make sure that you have the required media files in the directory above. DirectX 8 samples use the media files from the Microsoft DirectX 8 SDK, so you can simply copy the whole media folder from the SDK to the location above, or alternatively you can the media path in the registry:

HKEY_CURRENT_USER\Software\Object Connect\Smalltalk MT\DirectX8 SDK

(replace HKEY_CURRENT_USER with HKEY_CURRENT_MACHINE if you installed for all users).

Resource DLLs

Some of the samples (more precisely, the dialog-based ones) require custom resource DLLs. All other samples use DX8Res.DLL, which contains standard resources. The development image requires access to these DLLs in order to run the samples.

Driver Issues

No Hardware Support

You may not be able to run all samples, depending on your graphics hardware. If you installed the DirectX 8 SDK you should at least be able to run in the reference rasterizer mode. The retail mode doesn't offer this mode; in that case a sample that uses unsupported features will not run.

Sometimes hardware support can be enabled by installing a newer graphics driver.  

Image Settings

Compiler Support

DirectX code requires a minimum level of compiler optimization, otherwise inline structure accesses may fault or return unexpected results. The minimum settings are met by the level 'Debug', in the image properties. By default, the image is shipped with a predefined setting of 'Full' (or 'Debug', depending on the version), however any predefined setting except 'Disable Optimizations' is adequate.

 

This site, created by DirectX MVP Robert Dunlop and aided by the work of other volunteers, provides a free on-line resource for DirectX programmers.

Special thanks to WWW.MVPS.ORG, for providing a permanent home for this site.

Visitors Since 1/1/2000: Hit Counter
Last updated: 07/26/05.