Introduction to the ZW3D API
___________________________________________________________________________


The ZW3D API is a basic set of C functions for implementing custom commands 
and operations in ZW3D.

The ZW3D API is used to create DLL's that are dynamically loaded by ZW3D
at runtime.  Functions in a ZW3D API DLL may be invoked from the ZW3D user 
interface directly.


"Hello World" Example
___________________________________________________________________________

The following example shows how to create a ZW3D API DLL with a function 
that prints "Hello World" in the ZW3D message area.

1) Copy zw3d.lib from the ZW3D installation folder to a local folder
(i.e. "MyFolder").  The path of the installation folder is listed under the
"About..." option on the ZW3D "Help" pulldown menu.

2) Copy VxApi.h from the "api" folder to "MyFolder".

3) Create a simple text file named MyLib.c in "MyFolder" using Notepad 
or a similar text editor.  Type the following code in the file.  You may 
ignore the comments, which are included here for your instruction.

      #include "VxApi.h"

      void MyFunction(void);

      /*
      ** You must supply an initialization function whose name
      ** is the name of your DLL suffixed with "Init" (MyLibInit).
      **
      ** This function is automatically called by ZW3D when it
      ** loads your DLL at startup.
      **
      ** It should perform whatever initializations your DLL
      ** requires, such as registering your callback functions.
      **
      ** The function must be declared with the arguments shown.
      **
      ** The function should return 0 if it is successful; 1 if it fails.
      */

      int MyLibInit(int format, void *data)
      {
      /* register your function with ZW3D */
      cvxCmdFunc("MyFunction",(void*)MyFunction,VX_CODE_GENERAL);

      return(0);
      }

      /*
      ** You must also supply an exit (i.e. cleanup) function whose
      ** name is the name of your DLL suffixed with "Exit" (MyLibExit).
      **
      ** This function is automatically called by ZW3D during its
      ** shutdown (i.e. exit) process.
      **
      ** It should perform whatever cleanup your DLL requires
      ** before ZW3D is shutdown.
      **
      ** This function should always return 0.
      */

      int MyLibExit(void)
      {
      /* put your cleanup code here */

      return(0);
      }

      /*
      ** This is the function registered in MyLibInit().
      */

      void MyFunction(void)
      {
      cvxMsgDisp("Hello world!");
      }

4) Create another text file named "MyLib.def" in "MyFolder".   This
file must specify all functions "exported" by your library.  Type the 
following text in it.   

      LIBRARY MyLib.dll
      EXPORTS
      MyLibInit
      MyLibExit
      MyFunction

5) Build MyLib.dll using the following commands:

   cl.exe /nologo /c /MT /LD /Z7 MyLib.c
   link /DEF:MyLib.def /DLL /OUT:MyLib.dll *.obj zw3dmain.lib

6) Copy MyLib.dll from "MyFolder" to a sub-folder named "apilibs" 
in your ZW3D user folder or main ZW3D program folder.  The paths to these
folders are shown at the bottom of the first tab of the ZW3D Configuration
menu (see Utilities/Configuration... or Help/About...).

7) Start ZW3D.  It will automatically load DLL's found in an "apilibs" 
folder.

8) Type "~MyFunction" at the ZW3D command line.  ZW3D invokes MyFunction(),
which prints "Hello World" in the ZW3D message area.  This command string
(~MyFunction) can be assigned to an icon or button on a custom toolbar.
An example showing how to register a custom toolbar with ZW3D is given 
later in this section.


Please refer to "FAQ" page for more details.