home *** CD-ROM | disk | FTP | other *** search
/ Computerworld 1996 March / Computerworld_1996-03_cd.bin / idg_cd3 / grafika / fraktaly / frasr192 / fractsrc.doc < prev    next >
Text File  |  1995-03-05  |  16KB  |  402 lines
  1. The source code for Fractint is freely available.
  2.  
  3. Enhancements to it are appreciated.  If you want to add something to
  4. Fractint and join the Stone Soup Group, please do!  To submit changes,
  5. see "Contacting the Authors" in Fractint's online help.
  6.  
  7.  
  8. Copyright Information:
  9. ======================
  10.  
  11. Some parts of the source are from the public domain and are not
  12. copyrighted.
  13.  
  14. Some parts of the source bear explicit copyright notices from the
  15. author and are subject to the conditions listed there by the author.
  16.  
  17. The remainder of the source (not already public domain, no explicit
  18. author's copyright notice) is Copyright 1990, 1991 by the Stone Soup Group
  19. (a loosely associated and ever-growing group of fanatic programmers).
  20.  
  21. The source code may be copied freely and may be used in other programs
  22. under the following conditions:
  23.   It may not be used in a commercial program which produces fractal images.
  24.   Please credit the author (in general, credit Fractint and the Stone Soup
  25.   Group) as the source of the code.
  26.  
  27.  
  28. Distribution of modified versions of Fractint:
  29. ==============================================
  30.  
  31. If you enhance Fractint and want to distribute the results to others, the
  32. preferred approach is to join the Stone Soup Group - send us your
  33. enhancements and get your name in lights in future versions of Fractint.
  34.  
  35. We prefer that a modified Fractint executable program not be distributed to
  36. others, but understand that you might want to give copies to friends.  This
  37. is permitted, under the following conditions:
  38.   o The modified executable has a different name than "fractint.exe".
  39.   o The distribution includes a full unmodified copy of the corresponding
  40.     original version of fraint.exe.  (The easiest way is to copy fraint.exe
  41.     to yournew.exe, then "pkzip -a fraint.exe newfract.exe" to add your
  42.     version, and perhaps add a read.me file to describe it.)
  43.   o The heading displayed by the modified program clearly indicates that
  44.     it is a non-standard release.  E.g. you might change the heading to
  45.     say "Non-standard Fractint, Modified by John Doe".
  46.   o All author credits and distribution information in the online help
  47.     are unchanged (adding lines for your work is of course ok.)
  48.  
  49. The source code for a modified version of Fractint may not be distributed.
  50. (This is because we don't want any chance of confusion over which version
  51. of a source file is the official release.)
  52.  
  53.  
  54. Compiling Fractint:
  55. ===================
  56.  
  57. FRASRC.EXE includes the complete source code for FRACTINT (.C and .ASM).
  58. Recognizing that not everyone HAS (or even wants) an assembler, much less
  59. either MASM 5.1 or Turbo-ASM, which are the only two assemblers that the
  60. authors are aware of that can handle these particular files, it also contains
  61. a complete set of .OBJ files from the assembler code,
  62.  
  63. The distributed source will not compile to exactly match the Fractint
  64. release - it compiles with a different version number and heading.
  65.  
  66. The Microsoft 6.00A C compiler and Microsoft 5.1 assembler are used for
  67. Fractint releases, so that is the one combination of compiler/assembler
  68. which is pretty much guaranteed to handle FRACTINT in all of its various
  69. mutations.
  70.  
  71. Given that several of FRACTINT's co-authors now prefer (or only have!)
  72. alternate combinations, we have re-arranged the code to (usually) handle
  73. several popular alternatives.  In particular:
  74.  
  75. Microsoft C 7/8 and MASM 6.x:
  76. -------------------------------
  77. Just run MAKEFRAC.BAT, which invokes the Microsoft NMK utility using the
  78. files FRACHELP.MAK, FRACTINT.MAK, and FRACTINT.LN7.  Note that the assembler
  79. .OBJ files have been included in the .ZIP file, so that you don't really
  80. need MASM unless you are going to modify one or more of them.  If you ARE
  81. going to modify one of the assembler files, note that the distributed
  82. versions rely on some nifty features added to version 6.0 (like the '.model
  83. medium,c' option) and will not assemble under older versions of MASM without
  84. a LOT of work.
  85.  
  86. Warning: FRACTINT.MAK uses the most aggressive optimizations that we *think*
  87. are safe. Every time Microsoft comes out with a new compiler, something
  88. usually breaks, and we have to back of of our optimizations a little.
  89.  
  90. Microsoft C (earlier versions):
  91. ----------------
  92. Edit MAKEFRAC.BAT: comment out the two "nmk ..." lines and uncomment
  93. the lines for earlier versions. These probably need some work.
  94.  
  95. Borland C++ 3.0 and 3.1 Users
  96. -----------------------------
  97. See the BC*.* files.
  98.  
  99. Help System
  100. ===========
  101.  
  102. You'll need to set up the help files to get any online help from a modified
  103. version of Fractint.
  104.  
  105. For MSC users the MAKEFRAC.BAT file contains the necessary steps, you don't
  106. need to do anything special.
  107.  
  108. TC++ users should:
  109.   start by creating HC.EXE using the supplied HC.PRJ file
  110.   run "hc /c" to create the file FRACTINT.HLP
  111.   each time you create a new fractint.exe, afterward run "hc /a" to append
  112.     FRACTINT.HLP to the new FRACTINT.EXE
  113.  
  114. You don't need to understand the rest of this section unless you have a
  115. problem.
  116.  
  117. The source for Fractint's help is in the files HELP.SRC, HELP2.SRC, HELP3.SRC,
  118. HELP4.SRC, and HELP5.SRC.  The format of these files is described in HC.DOC.
  119.  
  120. The program HC.C ("help compiler") is used to convert the help text into
  121. the form Fractint uses at run time.
  122.  
  123. Running "hc /c" compiles HELPx.SRC.  It produces the file HELPDEFS.H for
  124. use when compiling Fractint, and the file FRACTINT.HLP.
  125. Running "hc /a" appends the FRACTINT.HLP file to FRACTINT.EXE to make the
  126. compiled help info available at run time.
  127.  
  128.  
  129. Overlays
  130. ========
  131.  
  132. Note: generally you won't have to worry about this!
  133. Only the addition of huge code (new overlays), or work which changes the
  134. relationship between major components of Fractint, are likely to affect
  135. the overlay structure.    
  136.  
  137. Fractint uses the new Microsoft Link overlay feature, to reduce the runtime
  138. memory required (which would otherwise exceed what DOS can give it.)
  139. Some caution is required with overlays.  Those source modules which are
  140. part of an overlay have a comment to indicate this at the start.  See the
  141. fractint.def file for the current overlay structure.
  142.  
  143. Some notes about overlays:
  144.   o The obvious one: control should not switch to different overlays
  145.     frequently, else Fractint will become sluggish.  If the overlay structure
  146.     changes, a test from floppy disk with no disk caching is a good idea.
  147.   o The overlay manager logic (inserted by the linker) does handle calls
  148.     from within one overlay to another - the new overlay is brought in
  149.     from disk (displacing the old one in memory), when the subroutine
  150.     finishes the old overlay is brought back into memory.
  151.   o To save memory, Fractint overlays data. The FCODE type accomplishes this.
  152.     Make sure that overlayed data is used immediately. If a pointer to 
  153.     overlayed data is passed to a routine in a different overlay, and the
  154.     first overlay swaps out, the data with be trashed.
  155.   
  156. Where the Goodies are
  157. =====================
  158.  
  159. It has come to our attention that people who have no interest in fractals
  160. at all have been wandering through the FRACTINT source code just to get at
  161. some of the neat tricks buried therein.  Here are a few hints as to where
  162. to look:
  163.  
  164. FRACTINT.C    - The main routine.  Nothing special here.
  165.  FRAMAIN2.C   
  166. FRACTINT.H    - General Include file.  Nothing special here, either.
  167. FRACTYPE.H    - Fractal type-specific Include file.
  168.  
  169. PROMPTS1.C    - The full-screen prompting code (using support routines
  170. PROMPTS2.C          in VIDEO.ASM)
  171. CMDFILES.C    - Command line and sstools.ini parsing.
  172.  
  173. FRACTALS.C,    - Most of the fractal-specific code.  If you want to know
  174.  FRASETUP.C       how a fractal is calculated, look in here.  Specific   
  175.  CALCFRAC.C,      speed-em-up support for special fractal types is in:   
  176.  FRACSUBR.C      
  177.  FRACSUBA.ASM
  178.  FRACTALB.C     - Arbitrary precision fractal implementations
  179.  FRACTALP.C     - El Grande fractalspecific structure
  180.  ANT.C          - Ant automaton 
  181.  CALCMAND.ASM    - Mandelbrot/Julia set calculations.
  182.  NEWTON.ASM    - Newton calculations
  183.  LORENZ.C    - Attractor fractals and IFS
  184.  JB.C        - "Julibrot" fractal type calculations
  185.  TESTPT.C    - "Roll-your-own" fractal routine
  186.  JIIM.C         - Inverse julia and orbits window code  
  187.  LSYS.C         - Lsystems code
  188.  LSYS.H       
  189.  LSYSA.ASM    
  190.  LSYSAF.ASM   
  191.  LSYSF.C      
  192.  LYAPUNOV.ASM   - Lyapunov speedup code 
  193.  
  194. MPMATH_C.C,    - Mark Peterson's "fast-math" support routines.
  195.  MPMATH_A.ASM,      (this stuff puts some of the routines supplied by your
  196.  FPU387.ASM,      favorite "C" compiler to shame!)
  197.  FPU087.ASM,      ...
  198.  FMATH.H,      ...
  199.  MPMATH.H      ...
  200. CMPLX.H         - Complex math defines
  201. HCMPLX.C        - 4D Hypercomplex math
  202. PARSER.C    - The "type=formula" formula parser routines
  203. BIGFLT.C        - Wes Loewer's arbitrary precision library. All ASM code
  204.  BIGFLT.H          exists as C also for portability.
  205.  BIGFLTA.ASM  
  206.  BIGFLTC.C    
  207.  BIGINIT.C    
  208.  BIGINIT.H    
  209.  BIGNUM.C     
  210.  BIGNUM.H     
  211.  BIGNUMA.ASM  
  212.  BIGNUMC.C    
  213.  
  214. VIDEO.ASM    - Assembler code containing all of the video routines
  215.           (setting up the video, reading/writing pixels, zoom-box
  216.           code, color-cycling, graphics-to-text "help" switch,
  217.           ... with help from the routines below for special adapters:
  218. LOADMAP.C    - Load .map files.
  219. TARGA.C,    - TARGA Video Routines
  220.  TARGA.H,      ...
  221. FR8514A.ASM    - 8514/A Routines
  222. TPLUS.C     - Targa+ video routines
  223.  TPLUS.H      ...
  224.  TPLUS_A.ASM      ...
  225. HGCFRA.ASM    - Hercules Video Routines
  226. DISKVID.C    - "DISK'RAM" video routines
  227. YOURVID.C    - "Roll-your-own" video routines
  228.  
  229. GENERAL.ASM    - General assembler code having nothing to do with fractals.
  230.           Lots of the tricky stuff is in here, and many of the "C"
  231.           routines that perform tricky functions rely on support
  232.           code buried in here.    In particular, this routine has the:
  233.             CPU, FPU Detectors
  234.             Keyboard routines
  235.             Mouse routines
  236.             Expanded memory routines
  237.             32-bit scaled integer multiply and divide routines
  238.  
  239. ENCODER.C    - GIF Encoder routine.
  240. GIFVIEW.C,    - GIF Decoder routines.
  241.  DECODER.C,
  242.  TGAVIEW.C,      (including a TARGA-format decoder currently used only for
  243.  F16.C,       loading obsolete .tga format "Continuous Potential" files)
  244.  TARGA_LC.H      ...
  245. LOADFILE.C    - Loads the Fractint parameter info from a GIF file.
  246.  LOADFDOS.C      subroutines for DOS Fractint only
  247.  
  248. LINE3D.C,    - 3D manipulation routines
  249.  3D.C
  250. PLOT3D        - 3D subroutines for LINE3D.C and LORENZ.C
  251. STEREO.C        - RDS stereo module
  252.  
  253. ROTATE.C    - routines which "spin" the VGA video-DAC.
  254. EDITPAL.C    - palette-editing mode
  255.  
  256. HELP.C        - HELP support
  257. INTRO.C     - title screen
  258.  
  259. ZOOM.C        - Zoombox manipulation.
  260.  
  261. PRINTER.C,    - The Printer Routines
  262.  PRINTERA.ASM      Data used by PRINTER.C
  263.  
  264. MISCRES.C    - Miscellaneous resident subroutines; nothing special.
  265. MISCOVL.C    - Miscellaneous overlayed subroutines; includes <B>atch
  266.           command.
  267. REALDOS.C    - Some subroutines isolated from Windows development work;
  268.           nothing special in here.
  269.  
  270. SLIDESHW.C      - Autokey interpreter
  271.  
  272. PORT.H        - Some portability stuff, nothing special here.
  273.  
  274.  
  275. EXTERNS.H    - All external variable declarations
  276. PROTOTYP.H   - All function prototypes
  277.  
  278. How things are set up
  279. =====================
  280. I've had to go through a lot of the code to figure out how things are set
  281. up.  These are my rough notes, which I'm including in case they can help
  282. someone else. -- Ken Shirriff
  283.  
  284. The control flow is very confusing.  Here are some details:
  285.  
  286. Each fractal type has an entry in the fractalspecific table in fractalp.c.
  287. Entries that are not displayed are marked with an asterisk.  Each entry is
  288. marked as int or not int, and either has a pointer to another entry
  289. (tofloat) or NOFRACTAL.  If you select float and the type is int or vice
  290. versa, you will end up with the tofloat type.  (e.g. If you select entry
  291. MANDEL, and select floating point, you will get entry MANDELFP).  There are
  292. also pointers tojulia and tomandel, which allow you to switch between mandel
  293. and julia.  The four functions listed are curfractalspecific->orbitcalc,
  294. curfractalspecific->per_pixel, curfractalspecific->per_image, and
  295. curfractalspecific->calctype.
  296.  
  297. main calls calcfracinit.
  298. calcfractint: this sets up curfractalspecific, which is the appropriate entry
  299.     from the fractalspecific table.  This routine does the int/float
  300.     conversion.
  301.  
  302. main calls calcfract, which calls timer, which calls perform_worklist
  303. perform_worklist calls curfractalspecific->per_image, which is eg.  MandelSetup
  304. MandelSetup: sets calctype to curfractalspecific->calctype, or for special
  305.     cases (eg. decomposition) to StandardFractal
  306.  
  307. perform_worklist calls solidguess (or whatever drawing system)
  308. solidguess calls *calctype for each pixel; calctype is eg. StandardFractal
  309.  
  310. StandardFractal calls curfractalspecific->per_pixel once, and then loops over
  311.     each iteration calling curfractalspecific->orbitcalc.  These routines
  312.     are eg.  mandel_per_pixel and JuliaFractal.
  313.  
  314.  
  315.  
  316. Here is the structure of the main routine. For overlay reasons a lot of
  317. this logic is now in FRAMAIN2.C.
  318.  
  319. main()
  320. {
  321.     initialize things
  322. restorestart:
  323.     if loading, look after specifying image
  324. imagestart:
  325.     while (adapter<0) {
  326.     process keys from short main menu
  327.     }
  328.  
  329.     while (1) {
  330.     if (calc_status != 2 || showfile==0) {
  331.         initialize videoentry from videotable[adapter]
  332.         initialize size, color, etc. from videoentry
  333.         setvideomode()
  334.     }
  335.     if (showfile==0) {
  336.         load file
  337.     }
  338.     calcfracinit();
  339.     save corners, zoom data
  340.     if (showfile != 0) {
  341.         calcfract(); /* calculates the fractal until interrupted */
  342.     }
  343. resumeloop:
  344.     if (no key pressed) {
  345.         set keypress = 13 to continue
  346.     } else if (key pressed) {
  347.         check input key
  348.     } else if (batch mode) {
  349.         look after batch key
  350.     }
  351.  
  352.     process key from long menu
  353.     }
  354. }
  355.  
  356.  
  357. How the video entries are managed:
  358.  
  359. get_video_mode(fractal_info): This routine is used to select a video mode
  360.     to match a picture we're loading.  It loads vidtbl and then  tries to
  361.     find a video mode that matches that in fractal_info.  Asks the user to
  362.     select one if there's no good match.  Figures out how to reduce the image
  363.     to fit the screen.
  364.  
  365. select_video_mode(curmode): This is the main-menu routine for the user to
  366.     pick a video mode.  picks default video mode, lets user select mode
  367.     from menu, copies entry to videoentry, puts entry in videotable if not
  368.     there, calls update_fractint_cfg if key reassigned, returns key
  369.     corresponding to mode
  370.  
  371. check_vidmode_key(option, keypress): if keypress corresponds to a videomode in
  372.     videotable (for option 0) or vidtbl (for option 1) return the videomode
  373.     index, else -1.
  374.  
  375. check_vidmode_keyname: converts ascii key name into key number
  376.  
  377. adapter_detect: checks for type of video (ega, cga, etc) and set video_type,
  378. mode7text, textsafe.
  379.  
  380. load_videotable: reads the entries in fractint.cfg into vidtbl
  381.     copies entries with an associated function key into videotable
  382.  
  383. load_fractint_cfg: reads video modes in fractint.cfg into vidtbl
  384.     (or copies from videotable) if fractint.cfg missing or bad
  385.  
  386. update_fractint_cfg: writes the entry in videoentry into the fractint.cfg file.
  387.  
  388. vidtbl: contains the video modes from fractint.cfg
  389. videotable: contains video modes with function keys; initialized in video.asm
  390. video_type: contains type: hgc, egc, cga, mcga
  391.  
  392.  
  393. Here is how the floating point modes are set up.
  394. parser.c uses the MathTypes:
  395. D_MATH: uses double precision routines, such as dStkMul, and FPUsincos
  396.     This is used if we have a fpu.
  397. M_MATH: uses MP type (mantissa, exponent).  These routines such as mStkAdd
  398.     call MPCadd, which call pMPadd, which calls MPadd086 or MPadd386.
  399.     The MP routines work on multiple precision, MPC works on complex pairs
  400.     of multiple precision.
  401. L_MATH: uses integer math.  Routines such as lStkAdd.
  402.