PowerFrax is a fractal generator used to demonstrate DayStar's accelerators and multiprocessing systems. The version that is included in this SDK takes advantage of the Multiprocessing API Library. Source code has been provided that demonstrates how this is achieved.
This document describes the components of PowerFrax, how PowerFrax works, how to build PowerFrax and how to debug it. For specific implementation details refer to the comments within the source code itself.
PowerFrax Components
PowerFraxMP.π
This Metrowerks PPC project builds a PPC code resource directly into the "PowerFrax" application. This is the module that implements all of the multiprocessing facilities. Note that the Multiprocessing API Library is 'weak-linked' into this project. Any application that does not require the library to be present should weak link to the library. The MacOS will refuse to launch any program that strong links to a shared library that cannot be located.
MandelbrotPPCMod.π
This Metrowerks PPC project builds a PPC code resource directly into the "PowerFrax" application. This is the module that implements the mandelbrot algorithm. This project is provided as a reference. It is not really necessary to understand the multiprocessing example.
sources
This folder contains the source files used by the projects.
'HFMultiprocessingPPC.c' is part of the PowerFraxMP.π project. It contains the functions that PowerFrax uses for task creation, communication and destruction. It also contains the single function used for the tasks.
'PowerFraxMP.π.exp' is part of the PowerFraxMP.π project. It lists the symbols exported from the module to PowerFrax.
'HFDocMandelbrot.c' is part of the MandelbrotPPCMod.π project. It contains a generic Mandelbrot fractal generation routine
'HFDocMandelbrot.o' is a highly optimized compiled version of 'HFDocMandelbrot.c'. It was compiled using the Motorola compiler which for this particular piece of code proved to be significantly better than anything else. For better performance in PowerFrax include this file directly in the MandelbrotPPCMod.π project, remove the file 'HFDocMandelbrot.c' and recompile. The version on the SDK was built using this optimised file.
includes
This folder contains the include files used by the projects.
'HFDocMandelbrot.h' is part of the MandelbrotPPCMod.π project. It defines the parameter block used by the Mandelbrot function.
PowerFrax
The main PowerFrax application. PowerFraxMP.π and MandelbrotPPCMod.π both build directly into this file.
Julia Sets
A PowerFrax plug-in that will generate Julia sets. Create a new Julia set by selecting 'Julia Sets' from the New submenu under the file menu. This plug-in is experimental and will break with the next release of PowerFrax. You can explore Julia sets quickly by opening a new Julia sets window and option clicking inside a mandelbrot window.
3D Projection
A PowerFrax plug-in that will generate 3D projections of fractals. Create a new 3D projection by selecting '3D Projection' from the New submenu under the file menu. This plug-in is experimental and will break with the next release of PowerFrax. Holding the option key when you select new will generate a wire frame model. Holding down the option key on a flat shaded model will change the interpolation method used to draw the model. Note that saved files from this plug-in will be useless in future versions of PowerFrax! QD3D and a PowerPC Macintosh are required to use this plug-in.
Fractals
Some cool fractals.
PowerFrax 1.4.2 Read Me
The read me that went out with the release version of PowerFrax 1.4.2.
How PowerFrax Works
PowerFrax is a 68k application that uses PPC code fragments for multiprocessor support and for fractal generation. When PowerFrax starts it initializes multiprocessing by calling fMPInitialize() inside the PowerFraxMP module built by PowerFraxMP.π. To create the required tasks fMPTasksCreate() is called. When PowerFrax is through with the tasks it calls fMPTasksQuit(). PowerFrax generates fractals one scanline at time. It submits one scanline to each of the tasks currently available by calling fMPTaskRun() for each task. It then waits for each task to finish by calling fMPTaskWait(). This process is repeated until the fractal is finished.
The number of tasks available to PowerFrax can be controlled via the Multiprocessing menu. A multi-processor environment can be simulated by pressing command-d. The contents of the Multiprocessing menu will convert to 'DayStar' mode. Select the 'Other...' item and type in a number from 1 to 100. That many tasks will be created and used to regenerate all the open fractals.
Since PowerFrax can support plugin based fractal generators the PowerFraxMP module allows an arbitary fractal generating function to be specified. Thus when examining the task code inside 'HFMultiprocessingPPC.c' no reference to a specific fractal generator will be found. The statement
p->workFunction( p->params );
is the call to the function that generates the fractal data. Parameters passed to the function fMPTaskRun() define which function will be used and what parameters will be used prior to signalling the task to run. Note that the parameters referred to by tasks are unique blocks of data. If a shared block were used then the tasks would all generate the same information.
The project MandelbrotPPCMod.π creates the Mandelbrot fractal generating module. The one and only function inside this project is the one called by fTask() using the above statement. There is a similar function inside the Julia Sets plug-in.
Building And Debugging PowerFrax
PowerFrax comes pre-built. It is not necessary to recompile anything unless you want to experiment with debugging.
Make sure that the Multiprocessing API Library is available to the projects. Follow the instructions given in the 'MP API Library Release Notes' for installing the library for development purposes before trying to build the projects.
To build PowerFrax for debugging open PowerFraxMP.π and select 'make'. The multi-processing module will be built directly into the PowerFrax application provided. You can also build the mandelbrot generator by opening MandelbrotPPCMod.π and selecting 'make'. When opening either symbol file with the Metrowerks Debugger from CodeWarrior 9 or later, select PowerFrax as the target. Since the Metrowerks Debugger will currently only allow one symbol file associated with a target do not try to to open both symbol files in the same session. You can get around this if you wish by building the mandelbrot generator into a resource file and targetting the resource file. That will allow both symbol files to be opened at once. The Metrowerks Debugger will create a seperate window for every task and will allow you to single step through task source code, inspect and change values etc.
Multiprocessing Support
If you have questions or have encountered problems, please contact DayStar. We have established an internet account and a voicemail line. Please leave your phone number and/or e-mail address and someone will be in touch with you as soon as we can manage.
world wide web: daystar.com
Internet: mp@daystar.com
Phone: (770) 967 2077 x267
Historical note: PowerFrax' first name was HappyFracs; a name which lasted about two days, i.e. the interval between starting it and Monday morning when Marketing first saw it. Although the product's name has changed, most of the naming conventions used in the project are still based on the earlier name.
