1.1 Software Layout
Canvas3D has basically three layers of software code :
The top layer is the Tcl/Tk interface that provides facilities for parsing Canvas3D commands, writing script files, embedding Canvas3D in C code and developing X Systems-like GUI. Tcl/Tk is a software convenient for portability and it works over most of the known popular systems. This layer does not required to be rewritten for different systems.
The lower layer is the Graphics Rendering Engine that communicates with the hardware, operating system and/or other libraries that provide support to render the three-dimensional graphics. This layer may be implemented using any convenient tools and systems. This layer changes from system to system. Microsoft Direct3D provides such support for Windows95/NT as well as Macintosh systems. The current version of Canvas3D has this layer implemented in Direct3D.
The middle layer is for portability issues. Canvas3D defines a Graphics Engine (GE) library, that basically has all the functionality any graphics system would require. The top layer calls utilities in the middle layer, that are actually implemented in the lower layer. The middle layer also does not change for different systems.
1.2 Directory Structure
Canvas3D code is arranged as follows :
A main directory Canvas3D has four sub-directories : generic, Direct3D, tests and win. The generic directory has all the source code for the top layer in the above design. Direct3D directory has source code for the middle and the lower layer as described above. Directory tests carries number of test script files for Canvas3D. The win directory has the makefile, and other system files required to compile the Canvas3D code on Microsoft Windows operating system.
Files in the generic directory follow the convention of tk* for filenames, such as tkCanv3DBox.c for all the Box Item code. Files supporting the middle layer in Direct3D directory follow the convention of ge*, such as geShapes.c, that has all the supporting functions for shapes. And all the Direct3D code resides in files named with the convention d3d* , such as d3dapp.c, in the Direct3D directory. Some of the Direct3D code is reused from the Direct3D demo code, provided by Microsoft with the software.
If you are planning to extend the features for this package, or else change some of the existing code, here are a few things that might be useful to start with. Tcl/Tk has enough documentation available for all its source code and conventions. A very useful link would be the Tcl/Tk Manual as well as the `Tcl and the Tk' book by John Ousterhout. See explanation on the generic code for Canvas3D below to see how everything is implemented in Canvas3D. Direct3D SDK documentation is now available online. It would be highly useful to refer to the Direct3D Overviews chapter, which is a good reference for a quick understanding of some important Graphics concepts. The chapter on Immediate-Mode Direct3D provides all its utilities. No other part of the huge manual would be required for Canvas3D. Most of the features in Direct3D have been implemented in the GE Library, at a very clean level of abstraction.
The Canvas3D documentation does not provide a very detailed description of the functions and structures used in its C code. Developers are suggested to use this documentation for understanding the overall layout, whereas try to look at the well-commented code itself for details.
The generic code of Canvas3D has files for the Tcl/Tk interface. There are three header files. tkCanvas3d.h, tkCanvas3dInt.h and tkCanv3dConts.h. tkCanvas3d.h has the declarations for the Tk_Canvas3D as well as Item3D structues as well as declares all the callbacks functions in these structures. tkCanvas3dInt.h has all the item dependent structures, and also declarations for the GE Library. tkCanv3dConsts.h defines the various constants for graphics as well as those used in general in the software. tkCanv3dConsts.h is included in all the .c files of the package.
tkCanv3dConsts.c is a file for functions that parse string values to their equivalent constants as defined in tkCanv3dConsts.h. tkCanvas3d.c file implements the Canvas3D widget, and all the rest of the files has the implementation of different items. The functions as defined in Tk_Item3DType in these item files are actually callbacks from tkCanvas3d.c.
geUtils.h is the header file to hold the various binding structures between Tcl/Tk and Direct3D. Almost every function in the GE library takes a value geInterface. This structure holds the data for various Direct3D objects as well as Windows handle. geInterface plays somewhat similar role to that of Tcl_Interp in Tcl/Tk. It makes useful things available at different parts of the code. Utilities are provided in the generic code tkCanv3dUtils.c for extracting the geInterface from Tk_Canvas3D structure, etc. Canvas3D defines standard structure names for graphical objects. The contents of these objects may change from system to system, depending upon implementation. Some of these structures are ShapeData, MatrixData, SurfData, LightData, canv3dcoord, canv3dDir,etc.
GE Library is a higher level abstraction for Direct3D. This code is equivalent to the Retained-mode Direct3D, only that the utilities are more clearly, more well-defined to suit the purposes, and to allow the fine tuning of different features as per the requirements. Also, this format inherently allows portability over the other systems. The name of the functions in this library, and structures in the Graphics Engine Interface may be reused with different contents, and Canvas3D will be extendable to other systems. Another very important reason for this library lies in the fact that an application more close to the graphics engine and far from Tcl/Tk can be developed by using these functions in a C code. The purpose of various functions are briefly described here :
GE_ViewClears : Set the clears option for Canvas3D.
GE_RenderDither : Set the dithering option for rendering.
GE_RenderFill : Set the fill option for a shape.
GE_RenderFog : Set the fog option for rendering.
GE_RenderShade : Set the shade type for a shape.
GE_RenderAntiAlias : Set the anti-aliasing option for rendering.
GE_RenderTextFilt : Set the texture filter type for rendering.
GE_RenderPerspCor : Set the perspective correctness option for rendering.
GE_RenderZbuffer : Set the z-Buffering option for rendering.
Ankit Patel (apatel@cs.cornell.edu)