This chapter discusses the implementation of some of the other important tools now available in Heidi. These functions are brought to your attention here so that you can explore their capability in advance of more detailed information:

• Utility routines
• Example functions
• The AppKit
• Frequently asked questions and answers

Utility Routines
This section provides a resource of practical utility routines useful to driver writers and developers. Note that Heidi contains many utility routines in the code which begin with the HD_xxx  prefix.  This  prefix generally refers to standard and utility functions or helpful routines such as HD_Device, "...which initializes the driver and creates a new driver object then returns a pointer to the object"; or, HD_Triangluate_Face, "...a useful tool  that decomposes polygons into triangles."  A list of many of these routines can be found in the Index under HD_xxx.

HD_Shrink_DC_Polygon
Usage

void HD_Shrink_DC_Polygon (
    int const       count,
    HT_DC_Point *   points,
    int const       offset);

Purpose
HD_Shrink_DC_Polygon offsets the points of a polygon.  A positive offset "shrinks" the polygon.  A negative offset will grow the polygon.  A pen plotter renderer can use this routine to shrink the polygon by half the pen width.

HD_Shrink_DC_Polygon computes the offset points by intersecting the offset line segments.  Shrinking self-intersecting and "sliver"  polygons (thinner than twice the offset) may not give the expected results.

HD_Fill_2DI_Polygon
Usage

void HD_Fill_2DI_Polygon (
    HT_Renderer_Data const *  rd,
    HT_Rendition const *      hr,
    int                       count,
    HT_DCI_Point const *      ipoints,
    int const                 pen_width,
    int const                 pitch,
    HT_Boolean                x_major_preferred);

Purpose
HD_Fill_2DI_Polygon, and its 2D counterpart, "fills" a polygon with lines.  Polygons with a solid face pattern are filled with vertical or horizontal lines a pen_width apart.  Horizontal lines are used if x_major_preferred is true.

All Heidi face patterns are supported except the stipple patterns and user-defined. The lines composing Horizontal_Bars, Vertical_Bars, Crosshatch, Slant_Right, Slant_Left, and Diamonds are pen_width*pitch apart.  The diagonals for Slant_Right, Slant_Left, and Diamonds are computed in floating point.  Endpoint rounding to integer may result in diagonals which are not precisely +/- 45 degrees.

The dots for Square_Dots are pen_width on a side and arrayed on a pen_width*pitch grid.  The squares for Checkerboard are spacing*pen_width on a side and also on a pen_width*pitch grid where spacing = ceil(pitch/3).

Solid face polygons are filled with lines in the current color.  Face pattern polygons are filled with lines in the contrast color.  All lines are solid, with weight = 1.


Example Functions
Currently most of the example functions are contained in the Heidi samples which can be found in the \samples directory.
 

The AppKit
The Heidi AppKit is a group of convenient functions for writing Heidi programs. It is a set of utility functions and classes designed to simplify operations which are commonly performed in Heidi applications. In the most common cases, a Heidi application simply wants to stack the software Z-buffer renderer on top of the GDI driver and then draw to the top of the renderer stack all of the time ¾ that is, to the software Z buffer. In cases like this, AppKit serves as a set of convenient functions that reduce the number of Heidi calls you need to make and save some programming effort.

These operations currently include the following functions:

• General stack operations (begin_picture, end_picture, update, and so forth.), a single begin_picture, update, end_picture drawing cycle that propagates from the top to the bottom of the renderer stack.
• Stack configuration (device/renderer selection) that creates a default software Z buffer on top of a GDI renderer stack.
• Persistent option mechanisms.
The set of functions which implement these operations are described in the following examples from heidi_tools.h located in \heidi\source\utilities\appkit.
HeidiBeginPicture()
Usage

HeidiBeginPicture (HT_Renderer & renderers)

Purpose
This function performs a begin_picture on each renderer of a linear stack, from the device to the target renderer.
HeidiConnect()
Usage

HeidiConnect (
    HT_Renderer &       renderers,
    HWND                wnd,
    HDC                 hdc)

Purpose
This attaches a stack to a GDI window handle/device context. The window id, context id, window size, and palette (for mapped devices) is set on the device.

The caller is responsible for performing the HeidiEstablish call.

Parameters

renderers       Identifies the renderer stack to connect.

hwnd            Identifies a GDI window handle.

hdc             Identifies a GDI device context.

HeidiCreateOptionsPage()
Usage

CPropertryPage * 
   HeidiCreateOptionsPage ( 
            HT_Renderer        *     renderers,
            HT_Renderer        *     target,
            HT_Device          *     device)

Purpose
This function creates a property page of configurable Heidi options based upon the supplied renderer stack, target and device. This is currently used to dynamically configure the renderer stack.
Parameters

renderers       Pointer to the full renderer stack of interest.

target          Pointer to the current rendering target.

device          Pointer to the current device.

Results
Returns a pointer to a property page. This pointer must be freed using HeidiDestroyOptionsPage(). The incoming renderers are updated to reflect any configuration changes.
HeidiDefaultStack()
Usage

HT_Renderer
    HeidiDefaultStack (const char * inipath = null)

Purpose
This function creates a default renderer stack. The stack is constructed based upon the contents of either an application specific INI file, or from a generic heidi.ini file. The stack is specified in the INI file in the following form:
 

[RENDERER OPTIONS] 
DEVICE=device.hdi 
RENDERER1=renderer.hdi 
RENDERER2=renderer.hdi 
RENDERERN=....

If no stack is specified, the default stack is simply the SZB renderer connected to the GDI device.
Parameters

inipath         Identifies the fullpathname of a user-supplied or null to use the Heidi INI file.

Results
Returns an HT_Renderer representing the stack.
HeidiDestroyOptionsPage()
Usage

HeidiDestroyOptionsPage  (CPropertyPage * page)

Purpose
This function destroys a property page created by the HeidiCreateOptionsPage function.

Parameters
page Pointer to an AppKit created property page.

HeidiEndPicture()
Usage

HeidiEndPicture (HT_Renderer & renderers)

Purpose
This function performs an end_picture on each renderer of a linear stack, from the target renderer to the base device.
HeidiEstablish()
Usage

HeidiEstablish (HT_Renderer & renderers)

Purpose
This function performs an establish upon each renderer of a linear stack, from the device to the target renderer.
HeidiUpdate()
Usage

HeidiUpdate (HT_Renderer & renderers)

Purpose
This function performs an update upon each renderer of a linear stack, from the target renderer to the base device.


HeidiUpdate()

Usage

HeidiUpdate ( 
   HT_Renderer               & renderers,
   HT_Int_Rectangle const   & bounds)

Purpose
This function performs an update by bounds upon each renderer of a linear stack, from the target renderer to the base device.

Parameters

bounds       Identifies the desired update region.

Frequently Asked Questions and Answers
A "Questions and Answers" page is posted to the Heidi web page. It contains technical and marketing questions from Heidi developers and driver writers. Just press the "Questions and Answers" button at the Heidi web page  http://www.autodesk.com/heidi .

The page provides answers to questions such as these:

 
• Is there a royalty fee for using Heidi in applications and drivers?
  There is no royalty fee!  Heidi is provided free as expressed in the license agreement. Commercial developers must register with the Autodesk Developer Network (ADN). For more information see the Heidi WWW page at http://www.autodesk.com/heidi .
• What is the purpose of the draw_dc_textured_polytriangle parameter float const *ws = null?
  This is an enhanced version of draw_dc_textured_polytriangle. In addition to the regular count and pointer for the vertices, textured polytriangles have a list of colors, texture parameters, perspective correction terms ws, and normals per vertex. The latter two are optional.
  The perspective correction terms ws might need some explanation. In computer graphics, it is the usual practice to transform a vertex or a point from 3D to dc by
  [x,y,z, 1] * M = > [x',y',z',w],
  where M is the 4 x 4 homogeneous transformation matrix and w is the perspective correction term. Then it is necessary to divide the [x',y',z']  by w to get [x'',y'',z'']  in dc. In other words, for each vertex there is a w term for the perspective division. Texture mapping u,v values need these w terms to correctly interpolate the texture.
  ws, is an array of these w terms, and it is the perspective correction. The default is a null pointer, meaning that the application is not interested in perspective correction. 3D Studio MAX uses this default from time to time, so it's possible that you will see a non-null pointer coming down.