Chapter 1. Overview

This chapter provides an overview of the Heidi programming environment and how to use this manual.

Introduction-What is Heidi?
Heidi is Autodesk's high-speed graphics solution. Specifically, it is an immediate mode interface designed for the drawing portion of graphics software construction activity. It is the critical core component that coordinates many aspects of 3D graphics application development. Basically, it provides application developers and programmers writing drivers a dynamically configurable framework for managing the graphics display of 2D and 3D objects, rendering and shading. The technology is also applied to hard-copy development and interapplication data transfer. Heidi's rendering pipeline augments graphics hardware through a scalable device interface.

Features and Functionality
Heidi offers driver writers and application developers many features and functionality for managing graphics display and hardcopy output.

Synopsis of the Guide
This guide contains an overview of Heidi architecture, a class reference and guidelines for writing Heidi drivers and applications.  It is written entirely in html and arranged in 5 frames on its own web page for free access by developers world wide. The guide is cross referenced with links to related topics¾simply click on the short list of "Chapters" which will jump you to that area of the detailed "Contents" where you can view and link to specific chapter information. The "Class Reference," Appendix A, contains a  complete listing of all of the significant Heidi classes and methods in alphabetical order. A convenient index links to useful subjects in the guide and a "What's New" section highlights and links you to the latest updates in the Guide.

The guide is written for use by programmers who already have a high level of experience in C and C++ programming as well as expertise in graphics or hardcopy device interfaces. It therefor does not provide introductory information on these subjects.

The guide is updated periodically as new information becomes available. You can view the latest public updated guide directly at http://www.autodesk.com/heididg.

The following chapters are included in this manual:

Heidi Programming Environment
Working with Heidi requires a high level of programming and graphics-device interface expertise.

Technical Expertise
To write Heidi device drivers or applications, you need to be an experienced C or C++ programmer. It is also assumed that you have the following background and experience:

System and Software
Following are the current hardware and software requirements to use Heidi:


System Notes


Typographical and Naming Conventions
In this guide, certain typographical conventions are used to make reading and understanding easier.
The Courier font is used for items and fragments of C or C++ language code as shown in the following examples:


An italic font is used for names of files and directory locations supplied with the kit. For example


In code samples or code sequences, the use of a C++ comment identifier followed by ellipses indicates code that has been omitted for clarity.


In this document, physical renderer and device driver are used interchangeably because, in the Heidi architecture, the device driver is typically the lowest level software in contact with the physical device.

The guide is written for use by both applications developers and programmers writing specific Heidi drivers. When necessary, instructions may be called out that are specific to application developers or driver writers. Customers or end users of developer products are referred to as end users. Developers and programmers making use of specific Heidi driver and application code, are referred to as users.
 

In the guide, classes (as reflected in the code) always begin with the prefix HT_xxx while utilities and functions generally start with the HD_xxx prefix. Classes are listed alphabetically in the "Contents" under appendix A, "Class Reference."   A list of many of the standard and utility routines can be found in the Index under HD_xxx and in chapter 6, "Other New Heidi Tools." Technical Support, Information, and Revisions
Heidi is provided free on an as-is basis. There is no technical support available. Any defects or proprietary questions can be emailed to heidi_dk@autodesk.com, however for questions of a general nature go the Heidi Discussion Group. Information, software, and documentation revisions for Heidi can be accessed from the Heidi page of the Autodesk World Wide Web site.

  Heidi Discussion Group
You are welcome to tune in and submit questions, answers and comments to the Heidi Discussion Group (or use the web browser format) on the Autodesk World Wide Web site. At this public forum, important messages are posted and programmers from our development group can discuss general  issues and field questions of interest to application developers and driver writers using Heidi.


Heidi Web Page
The Heidi web page is located at http://www.autodesk.com/heidi .  The site provides initial access to the development kit software, documentation and License Agreement. A "Questions and Answers" page periodically posts answers to common questions from developers and driver writers.  You can also view the latest updated guide at http://www.autodesk.com/heididg.


Heidi Development Kit ¾ Access & Licensing

The Heidi Development Kit is provided free to developers and driver writers who register by accepting the Heidi License Agreement and submitting the registration form which is accessed from the Heidi web page. Only Autodesk Developer Network (ADN) members may license Heidi for commercial use. For more information on ADN and commercial licensing see the Heidi web page. A copy of the License Agreement is also included in this Guide for your review.


Writing Heidi Device Drivers

If you are considering writing a Heidi driver, apply the information in this manual as follows:

  1. Determine hardware and software requirements.
  2. Run one or more of the supplied Heidi test programs from the \samples subdirectory using one or more of the supplied sample drivers, such as the GDI driver.
  3. Read chapter 2, "Heidi Architecture."
  4. Read chapter 3, "Implementing a New Driver."
  5. Start writing a driver, referring to appendix A, "Heidi Class Reference" and B, "Utility Class and Typedef Descriptions" as needed.

The source code for the Heidi GDI and OpenGL drivers is available for ADN members.

Writing Heidi Applications
To develop a Heidi application, it is recommended that you apply the information in this manual as follows:

  1. Determine hardware and software requirements.
  2. Run one or more of the supplied Heidi test programs from \samples. All examples are using the software Z buffer renderer (SZB) stacked on top of the GDI driver. You can change the renderer stack via the option dialogue menu or by modifying the hard coded renderer names in the source.
  3. Read chapter 2, "Heidi Architecture."
  4. Read chapter 4, "Implementing a New Application."
  5. Refer to the samples as you build up your application. The most elementary sample is "Simple", which illustrates the bare minimum for starting Heidi renderers. "SimpleNoMFC" is a non-MFC version of "Simple."

Heidi Sample Applications
Several sample applications are included in Heidi. These are located in the \samples subdirectory of the tree. Note that they are written purely for demo or testing purposes ¾ they have not been performance tuned.

Note: In samples that let you configure the render stack, note that the only meaningful driver choices are wopengl10.hdi, direct3d10.hdi, or gdi10.hdi. You can optionally configure the renderer szb10.hdi on top of gdi10.hdi.

MULTITHREAD: This program demonstrates Heidi's multithreading renderer. It is intended as proof of concept only. In other words, since the program is NOT compute bound, it does not demonstrate a performance boost on multiple CPU machines. Example output is shown in figure 1.

Figure 1. Multithread

CAMTEST: This program shows off Heidi 3D capabilities, such as lighting, material, and texture mapping. It draws either a wireframe or textured 3D cube on the screen and allows you to manipulate it by rotating, zooming in and zooming out. Figure 2 shows a textured 3D cube and intersecting triangle.

Figure 2. Camtest



SIMPLE: This is the simplest Heidi program. In Simple, an MFC (Microsoft Foundation Class) application is intentionally created with the minimal steps to draw lines, text, and images on the screen. This application is a good one to start with if you are new to Heidi. Figure 3 shows an example of colorized and Gouraud polytriangles.

Figure 3. Simple

SIMPLENOMFC: This program runs the same way as Simple but the code is written without using MFC- hence the name simple no MFC. Figure 4 shows an example of text output.

Figure 4. Simplenomfc

SPRITE: This program draws a number of Gouraud-shaded polytriangles and lets you move a  texture-mapped polytriangle on top of them. It demonstrates a fast way of dragging a 2D image with depth by taking advantage of Heidi color and depth image read/write capabilities. Figure 5 shows the texture map (text image) dragged across the polytriangles.

Figure 5. Sprite

STDTEST: This program tests different draw_ calls of the Heidi API. Renderer stack performance metrics are available. Figure 6 shows a test image compared with results from several other types of images in figure 7.

Figure 6. Standard Test

Figure 7. Standard Test results

UNITTEST : This program is used to draw multiple instances of a particular primitive to test the performance of your driver. There are several options available, such as Polylines, Polytriangles and so forth, for testing different primitives. Figure 8 shows a test using complex Gouraud polytriangles with the statistics for the szb8 driver. The statistics for several test runs are saved to the results viewer shown in figure 9.

To build and run the Heidi sample applications, follow these steps:
     
  1. Include the appropriate Heidi Bin directory for Heidi DLLs in your path.  In a command prompt, this means setting your path in the following manner for the Debug DLLs:
    Set PATH=%PATH%;my_directory\heididk\bin\i386\Release;my_directory\heididk\bin\i386

    Alternatively, set your path environment variable for your system to include the appropriate Heidi Bin directory.


Note: This is loading the release version of Heidi. The release version is under my_directory\heididk\bin\i386\Release and the debug version is in my_directory\heididk\bin\i386\Debug. Be sure to set your path appropriately.

You can build the sample with its release target and set the environment variables accordingly. Please do not mix the release and debug builds. The Microsoft compiler uses different C run time libraries for debug and release, and mixing these builds could result in unexpected crashes. A better way of setting the environment is to start your control panel, double click on "system" and then modify the system environment variables. To ensure that the new setting has taken effect, log out and then log back in.

  1. Set the Heidi build environment variables:

        Set HEIDIVER=10

        Set HEIDISDK=my_directory\heididk

        Set HEIDIBIN=my_directory\heididk\bin\i386\Release

        Set HEIDILIB=my_directory\heididk\lib\i386\Release

        Set HEIDIOBJ=my_directory\heididk\obj\i386\Release

        Set USRCFLAGS=/w34701 /wd4996 /GS /DHEIDIUNICODE=1 /U_MBCS /UMBCS

You may also set optional link (USRLFLAGS) flags.

  1. Select an application to build, such as the Camtest application, by changing directories to the appropriate application subdirectory. In this case, the directory is \heididk\samples\camtest.
  2. While running Microsoft Visual C++, load the corresponding make file for that application. For Camtest, load the camtest.vcproj project file.
  3. To create the camtest executable, select Build->Rebuild Solution.
  4. Run the resulting executable.