home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / fractalus / !Fractulus / Docs / Cores next >
Encoding:
Text File  |  1995-05-04  |  4.4 KB  |  127 lines
  1. HOW TO WRITE YOUR OWN CORE
  2. --------------------------
  3.  
  4.  
  5. This section is of interest for programmers only. It deals with the
  6. interface Fractulus provides for its core processes.
  7.  
  8. The core does the actual processing of a fractal. Since there are a
  9. lot of algorithms that produce quite nice fractals I chose to offer
  10. facilities to run Fractulus with different cores.
  11.  
  12. A core has to be relocatable! Furthermore the current buffer holding
  13. the core is fixed to 4K, so a core must not be any larger. If this
  14. means a great drawback to you, mail me about it. Personally I think
  15. 4K for the core should suffice easily enough.
  16.  
  17. A core file has the following format:
  18.  
  19. Byte#
  20. 0    : offset from start of file to entrypoint (i.e. the address Fractulus
  21.        should BL to).
  22. 4    : unique algorithm ID. The idea is to give each type of algorithm
  23.        its own ID. This prevents you from loading a fractal into Fractulus
  24.        and zooming into it but getting only rubbish because the current
  25.        core produces altogether different results.
  26.        Algorithm IDs don't have to be unique among cores (only regarding
  27.        algorithms). fix32 e.g. has the same ID as mandelbrot (algorithm IDs
  28.        allocated so far see later).
  29. 8    : (since v0.10) Core flags. Meaning of bits when set:
  30.        0: core can deal with 16bpp sprites.
  31.        1: core can deal with 32bpp sprites.
  32.        2: core uses extension words.
  33.        3-31: reserved for future expansion, set to zero.
  34. 12-15: reserved for future expansion, set to zero.
  35. 16   : Core program.
  36.  
  37. Prior to calling the core (BL to entrypoint) Fractulus sets up the following
  38. registers:
  39. R0:  width (i.e. resolution x)
  40. R1:  height (i.e. resolution y)
  41. R2:  current y-position [0..height-1]; y=0 means top line
  42. R3:  current x-position [0..width-1];  x=0 means leftmost column
  43. R4:  pointer to begin of current line in sprite.
  44. R5:  IterMax
  45. R6:  IterPoll
  46. R7:  LineAdd (value to add to R4 after a line has been finished)
  47. R8:  (since v0.10) ld(bpp)-3, i.e. 0 for 8bpp, 1 for 16bpp, 2 for 32bpp
  48. R12: ^parameters
  49.  
  50. F0:  current REAL
  51. F1:  current IMAGINARY
  52. F7:  delta REAL
  53.  
  54. parameters is a chunk of memory containing further data:
  55. Byte#
  56. 0:   (int) width
  57. 4:   (int) height
  58. 8:   (int) current y
  59. 12:  (int) current x
  60. 16:  ^^SpriteArea (you should not normally use this. NEVER WRITE TO THIS ADDRESS!)
  61. 20:  (int) IterMax
  62. 24:  (int) IterPoll
  63. 28:  (int) LineAdd
  64. 32:  (float, extended) current REAL
  65. 44:  (float, extended) current IMAGINARY
  66. 56:  (float, extended) delta REAL
  67. 68:  (float, extended) delta IMAGINARY
  68. 80:  (float, extended) min(REAL)
  69.  
  70. The following since v0.10:
  71. 92:  (float, extended) ext1
  72. 104: (float, extended) ext2
  73. 116: (int) ld(bpp)-3 (see above)
  74.  
  75. You may change any registers you want except for R12 and R13.
  76. On exit the program has to set R2,R3 to new y/x pos and F0,F1 to new
  77. REAL/IMAGINARY. Return address is passed to the core in R14.
  78.  
  79. After completing a line, add R7 to R4 (bpp are already taken into account in R7!)
  80. and load current REAL = F0 from [R12,#80].
  81. When the fractal is finished (i.e. current y = R2  ==  height = R1) you must
  82. set R2 to -1 and exit.
  83.  
  84. IterPoll should be dealt with as follows: after the iterations loop subtract the
  85. number of iterations from it. Before starting on a new position you should
  86. check if it has become less or equal than zero and exit if so, otherwise continue.
  87.  
  88.  
  89. Colours:
  90. --------
  91.  
  92. The colours used in truecolour sprites are quite different from the ones used with
  93. 8bpp. My motivation was to give a maximum number of colours without ludicrously
  94. high iteration values. If you want to know my colours mail me and I'll give you
  95. the algorithm I use.
  96. EACH CORE *MUST* SUPPORT 8BPP MODES!
  97.  
  98.  
  99. That should suffice for you to write your own core. In case it's not mail me about
  100. it.
  101.  
  102.  
  103. ALGORITHM IDs
  104. -------------
  105.  
  106. Algorithm IDs allocated so far:
  107.  
  108. mandelbrot: 0       (z = z^2 + pos)
  109. mandel3:    1       (z = z^3 + pos)
  110. mandel4:    2       (z = z^4 + pos)
  111. mandel5:    3       (z = z^5 + pos)
  112. mandel6:    4       (z = z^6 + pos)
  113. julia:      16      (z = z^2 + c)
  114. crazy32:    32      (z = z^2 + pos, beautiful fixpoint-errors!)
  115. dragon:     64      (z = c*z*(1-z) )
  116. Where c is the complex number obtained from the extension words.
  117.  
  118. Any cores using the same algorithms (but different implementations) should use
  119. the same IDs.
  120. If you create a new algorithm you should mail me about it, telling me the
  121. algorithm you used so I can allocate you an ID to preserve consistency with
  122. other people's cores.
  123.  
  124.  
  125.  
  126. Andreas Dehmel
  127.