home *** CD-ROM | disk | FTP | other *** search
/ Inside Multimedia 1995 July / IMM0795.ISO / share / os2 / pmfract / src / pmfrsrc.doc < prev    next >
Text File  |  1994-01-24  |  8KB  |  155 lines
  1. FRACTINT for OS/2 Presentation Manager
  2. Description of the source code for version 2.0.
  3. The source code for Fractint for Presentation Manager is freely available.
  4.  
  5. Enhancements to it are appreciated.  If you want to add something to
  6. Fractint for PM and join the Stone Soup Group, please do!  To submit changes,
  7. see "Contacting the Authors" in Fractint's online help.
  8.  
  9. Some parts of the source are from the public domain and are not
  10. copyrighted.
  11. Some parts of the source bear explicit copyright notices from the
  12. author and are subject to the conditions listed there by the author.
  13.  
  14. The remainder of the source (not already public domain, no explicit
  15. author's copyright notice) is copyrighted by the Stone Soup Group
  16. (a loosely associated and ever-growing group of fanatic programmers).
  17. The source code may be copied freely and may be used in other programs
  18. under the following conditions:
  19.   It may not be used in a commercial program which produces fractal images.
  20.   Please credit the author (in general, credit Fractint and the Stone Soup
  21.   Group) as the source of the code.
  22.  
  23. I assume you have previously gotten the FRACTINT-for-DOS source code
  24. (FRASRC.ZIP) from whereever you get it (usually CompuServe COMART forum)
  25. and have read the documentation of how the fractal calculation engine works
  26. and how it is structured. Here I will describe the code I added to form the
  27. Presentation Manager user interface and drivers to connect the fractal
  28. calculation engine to Presentation Manager.
  29.  
  30. I assume you are somewhat familiar with the structure of a Presentation
  31. Manager program, and have a feel for window events, the PM API for window
  32. events, and threads and semaphores and such in OS/2. If not, I am afraid
  33. that this program will not make that good an introductory tutorial.  The
  34. books "Programming the OS/2 Presentation Manager" by Charles Petzold, and
  35. "Advanced OS/2 Programming" by Ray Duncan provide excellent background
  36. material.
  37.  
  38. To ensure responsiveness to mouse and keyboard actions, and to allow
  39. PMFRACT to be calculating a fractal in the background while I am working
  40. on something else, the fractal calculation engine runs as a background
  41. thread while the foreground thread interfaces with Presentation Manager,
  42. handling window events and doing the actual drawing on the window.
  43. The two threads interlock through several semaphores, flag bytes, and other
  44. common variables.  All of the shared fields are in a structure called the
  45. CALCPARM (defined in PMFRACT.H) which is defined only once as the global
  46. variable "cp".  Besides doing the fractal calculations, the background
  47. thread performs .GIF and .BMP file loading and saving, and all printing.
  48. The background thread can also signal to the foreground thread that it
  49. wants attention by posting a PM user message to the foreground window.
  50.  
  51. The code has been structured so that the functions to handle a given event
  52. or group of like events are together, along with subfunctions used by
  53. those functions.  The idea was that like code would then be loaded as a
  54. single segment, and could then be discarded after the event in question
  55. passed.  This lessens somewhat the amount of real menory needed to run this
  56. program.  It should be noted that the graphic data (bitmaps for both PM and
  57. me) takes up a lot of room!
  58.  
  59. All code new for PMFRACT begins with PMFR-.  Modules not mentioned here are
  60. straight from FRACTINT for DOS.  Details of the inner workings of modules
  61. and functions is spread out through the code as comments.  Here is a
  62. high-level index to the Presentation Manager-specific modules:
  63.  
  64. PMFRACT.C     The main module.  Main message loop and main window proc.
  65.               Also the routines that handle non-user generated window
  66.               events and routines to communicate with the background
  67.               thread.
  68. PMFRINIT.C    Initialization code.  Runs at startup and then discarded.
  69. PMFRTHRD.C    Main module for the background thread.  Waits on a semaphore
  70.               until the main thread gives it something to do, then calls
  71.               the appropriate Calc, Load, Save, or Print routine.
  72. PMFRUSER.C    Main user interface module.  The main function in this
  73.               module is called from the main window proc to handle events
  74.               generated by mouse movements or keyboard events, or poking
  75.               at the main menu.  Subroutines here or in PMFRDLG1 or
  76.               PMFRDLG2 then act on the event.
  77. PMFRDLG1.C    Functions supporting PM dialog boxes that process
  78.               parameters for the calculation engine.
  79. PMFRDLG2.C    Functions supporting PM dialog boxes that process other
  80.               activities, such as Load, Save, or Print.
  81. PMFRCALC.C    The main module that drives the FRACTINT calculation engine.
  82.               This is basically a hacked-up FRACTINT.C from FRACTINT for
  83.               DOS.  Also contains the code that sends pixels back to
  84.               Presentation Manager (putcolor and getcolor).  The pixels
  85.               are eventually displayed by the main thread from the function
  86.               PMfrPaint in PMFRACT.C.  This module also contains
  87.               many dummy functions to tie off loose FRACTINT function
  88.               references.
  89. PMFRLOAD.C    Module called to do reading of .GIF or .BMP files, or
  90.               to pull a bitmap off the PM Clipboard.
  91. PMFRSAVE.C    Module called to do saving of .GIF or .BMP files, or
  92.               to put a bitmap on the PM Clipboard.
  93. PMFRPRNT.C    Module called to do printing of the currently displayed
  94.               fractal.  Either prints using the Presentation Manager
  95.               printer driver, or prints directly to a HP PaintJet.
  96.               There is currently no HP PaintJet driver, so I stole the
  97.               code from FRACTINT for DOS.
  98. PMFRDATA.ASM  Assembler module containing the built-in display palettes.
  99. PMGENERL.ASM  Other assembler subroutines (hacked out of GENERAL.ASM
  100.               from FRACTINT for DOS).
  101.  
  102. SMPL*.*       The files pertaining to the Simple Help subroutines.
  103.  
  104. FILE.C, TOOL.C, etc.   Files from the Microsoft OS/2 Presentation Manager
  105.               Toolkit sample File Open/Save dialog (OPENDLG), modified
  106.               slightly by me to center the dialog boxes on the screen.
  107.               Other than that, this is straight out of the toolkit.
  108.  
  109.  
  110. How to build PMFRACT
  111.  
  112. I use Microsoft C (currently version 6.00A) as the primary tool.
  113. I also use Microsoft Macro Assembler (MASM) for assembler files.
  114. Most of the work was done with MASM 5.1, but the final build
  115. was done with MASM 6.0, which had just arrived.
  116.  
  117. There are three MAKE files that have to be built in turn.
  118. OPENDLG.MAK  is the make file for the OPENDLG subroutines.
  119. SMPLHELP     is the make file for the Simple Help subroutines.
  120. PMFRACT.MAK  is the make file for the main Fractint for PM executable.
  121.  
  122. OPENDLG and SMPLHELP must be constructed first as they create import .LIB
  123. files needed for the final link of PMFRACT.
  124. Also, the different Make files have symbols that can be used to
  125. create either debuging versions (full Codeview symbols) or optimized
  126. running versions (no Codeview symbols).
  127.  
  128. The make files assume that environment variables PATH, INCLUDE, LIB, TMP,
  129. and etc. have been set as needed for the version of C and MASM you have
  130. and the way you have chosen to install them.  I assume that all the
  131. rest of the source is in one subdirectory, which is the current subdirectory
  132. (that is how I work, more or less).
  133.  
  134. Now, for example, to make debugging versions of everything, just say:
  135. NMAKE /f OPENDLG.MAK
  136. NMAKE /f SMPLHELP
  137. NMAKE /f PMFRACT.MAK
  138.  
  139. To make the final optimized version, you could say:
  140. NMAKE nd= CC=$(CO) /f OPENDLG.MAK
  141. NMAKE nd= cl=$(co) /f SMPLHELP
  142. NMAKE nd= cl=$(co) cf=$(so) /f PMFRACT.MAK
  143.  
  144. **** Warning **** Warning **** Warning ****
  145. No Warranties are either Expressed or Implied!
  146. **** Warning **** Warning **** Warning ****
  147.  
  148. The best way to contact me is to leave me a message in the
  149. COMART forum of CompuServe.
  150.  
  151. Donald P. Egen
  152. 409 Cameron Circle, Apt. 1204
  153. Chattanooga, TN  37402
  154. CIS 73507,3143
  155.