I have attached FORTRAN code for a test USERFUNCTION tailored to work with a ZEMAX model, “Double Gauss 5 degree field.ZMX” that should normally be found in the SAMPLES...SEQUENTIAL...OBJECTIVES folder. Included also are all of the FORTRAN modules you will need (except DFWINTY) and my version of ZCLIENT.CPP. I have also included the linked executable, HELPFUNC.EXE. You are invited to try it out by copying it to the ZEMAX...EXTEND folder and then starting ZEMAX, loading the above lens and selecting HELLOFUNC from the Extensions menu item.

User Interaction

Output to the user is given in calls to the Windows® API function MessageBox, which takes null-terminated C-strings as two of its four arguments, the others being an integer window handle (NULL in this case) and an integer flag (defined with all other flags in module DFWINTY) to show an ‘OK’ button on it. In Compaq Visual Fortran, the FORTRAN interface to this function is specified in a module called DFLIB (in Intel Fortran it will probably be called IFLIB). It is recommended that you follow the FORTRAN code for USERFUNCTION line by line to see how each displayed message box is related to the code. A ‘CANCEL’ button is offered each time a message box is displayed, allowing the user to terminate program execution at any time. Here is an example MessageBox output by the extension HELLOFUNC.



Extracting Model Data and Ray Tracing

Along the way, the program also generates two files, one called “SURFLABELS.TMP” (probably found in the EXTEND folder) containing a list of surface comments extracted from the ZEMAX model, and “TESTLOCAL.TXT” (probably found in the SAMPLES folder) containing X,Y and Z co-ordinate intercepts on five of the surfaces traced at maximum field and through the (0,1) pupil point. The latter co-ordinates are local co-ordinates generated using the PostTraceRequest function. They should then be compared with the values obtained later by tracing the same rays but this time using the PostArrayTraceMessage function, and shown to be identical. To transform from a surface’s local co-ordinates to a global frame, the transformation matrix is needed and examples of extracting this data are also demonstrated.

Generating Graphic Data and Opening, Displaying and Interacting with a ZEMAX Graphic Window

The demonstration extension also generates some points to plot in a ZEMAX graphic window, using the DDE data item ‘MakeGraphicWindow’ as you will discover. If you examine the code, you will find a routine PUPILPOINTS that generates points on a spiral inside a unit circle representing the pupil. The plot commands are generated in routine PUPILPLOT and output into the temporary file named and supplied by ZEMAX on the command line that starts the extension. (See the section on “Generating a Graphic Window” in the ZEMAX Extensions chapter of the manual for a full description of the simple script language used for the plot commands). Note that a single ‘setting’ value of ‘1’ is fed to ZEMAX at the end of the MakeGraphicWindow string. This is used by the HELLOFUNC extension as a flag when ZEMAX returns it to the extension whenever the user clicks on the ‘Update’ or  ‘Settings’ items in the menu at the top of the graphics window that is opened and controlled by the extension. Here is a picture of what should appear:

The graphic window will remain displayed, even when the extension is terminated, until it is closed by the user. The HELLOFUNC extension can be active or not, with the graphic displayed, and if you click on ‘Update’ or ‘Settings’ menu items, another instance of the extension is started, so the ‘settings’ flag, stored by ZEMAX and associated with the window, is sent back to the new instance of the extension and is used, in the present case, to sense and quit this new instance, displaying the message that ‘This window has no options’. On the left below is the message displayed by the extension when the ‘Update’ menu item is pressed. On the right is that shown when the ‘Settings’ menu item is selected and the ‘Options’ flag is set to ‘1’ by ZEMAX.

Otherwise the extension could just regenerate new data for the plot window, based on the ‘settings’ data that ZEMAX received when it got the ‘MakeGraphicWindow’ command and which it reflects back to the extension when the appropriate menu item is selected. Note that before any instance of the extension is terminated, the DDE item ‘ReleaseWindow’ is and must be sent, in order to release control of the graphics window. The following is the message sent using PostRequestMessage:



A message box (on the right above) is programmed to appear giving the return code from this command, which is just the number displayed in the top left hand corner of the graphics window shown earlier. This number would be ‘0’ if no window had been displayed before the request to ‘ReleaseWindow’ was made. Refer to the ZEMAX manual for full details on extension-generated graphic and text windows and their settings.

Note that an extension can open and maintain only one graphic window, as only a single temporary filename is supplied to the extension by ZEMAX. You can have as many extensions as you like running, and they can all have their own windows, but only one window is allowed per instance of the extension. This is just the way ZEMAX works. For example, when you open a ray fan plot you don't get two windows, just one.
 
If an extension wanted to show more than one graph or text listing, then the workaround is for the extension to make the selection of which data to present one of the settings, like ZEMAX does to choose between false color and contour maps for example. The extension could even create multiple displays, and then store them for rapid re-display when the user selects the alternate display.