Installation Instructions for GFFT ------------ ------------ --- ---- In most cases, steps 1-4 are all that should be necessary: 1) Get GNUPLOT and install it in C: 2) If your GNUPLOT is from a WinGnuPlot distribution, rename .gfft-WinGnuPlot to .gfft 3) If you have a hardware Floating Point Unit (68881, 68882, or standard 68040 with FPU) and a 68020 or better processor, you can delete GFFT and rename GFFT-FPU to GFFT. 4) You're ready. Click on the PianoLowC.iff icon, then on OK on the bottom right of the GFFT Dialog Window, and enjoy. If you have problems, check for missing C: commands and/or sys:utilities/more. (Do not delete gfft.help or COPYING from the GFFT directory.) Then read the rest of this document and/or the BUGS document. There is a lengthy discussion of how to get a copy of GNUPLOT below. OVERVIEW -------- GFFT requires the program GNUPLOT, which is available separately because it is written by other authors . Although GNUPLOT is a CLI-based program, you will not have to use the CLI because GFFT will invoke GNUPLOT for you automatically. If you already have installed GNUPLOT, you might already be ready to run GFFT from this unpacked archive. But, reading this file first might help you to avoid a few problems. If you don't have GNUPLOT yet, you will be still be able to examine the GFFT interface and options, access the built-in help documentation, and even analyze sample files (writing the results to named text files), but you will not be able to see the results plotted on your screen (or printer). In most cases, you will not actually have to do very much if anything to run GFFT after installing GNUPLOT, but this file is a little long because I have tried to deal with many possible cases. Once you have everything set up, you can simply click on the PianoLowC.iff icon, which will invoke GFFT to analyze the sample file. Then, click on the OK gadget in the bottom right of the GFFT dialog window, and in a few seconds you will see the spectrum of a low C piano note. REQUIREMENTS ------------ GFFT requires an Amiga with Workbench 1.3 (V34) or higher and 1.5 Mb of RAM. It can be run on some systems with as little as 1 Mb of RAM with reduced capabilities. Workbench 2.0 (V37) or higher, a hard drive or second floppy drive, and 3 Mb or more of RAM are strongly recommended. 1 Mb of memory is very tight. Though I've actually done it (on a 1 Mb all chip 500...it helps to have all one kind of memory if it is limited) note that you may have to use only 1024 bins or fewer, and go without any extra buffers, tasks, or commodities. In this use, it is preferable to get an earlier version of GNUPLOT such as 3.2. The main difficulty here is not the size of GFFT but the size of GNUPLOT, and the fact that in normal use both have to be in memory at the same time. See the section below entitled 'Low On Memory' for further help on how to run with minimal memory. Future releases of GFFT are likely to require more memory and Workbench 2.0 or greater. If you wish to make your own audio samples, you will need your own audio sampler hardware and software. You can also download and/or buy samples or import them from other systems. GFFT currently works only from stored sample files; it does not read data from an audio sampler. There are many commercial and shareware programs to read data from an audio sampler, and most sampling hardware is provided with suitable sampling programs to do that as well. Some of these sampling programs will even do real-time spectrum analysis, though with limited resolution and without many options available in GFFT. The intent of GFFT is to produce the highest quality spectrum analysis possible using FFT from a given stored sample file, possibly of considerable length. Obtaining GNUPLOT --------- ------- If you have not obtained GNUPLOT yet, please do so now. It is a very powerful program which can plot multiple graphs from functions and/or data files on your screen or to printers or to Postscript or TeX files. Although GNUPLOT is (ordinarily) a CLI-based program, you will NOT need to use the CLI to use it with GFFT. GFFT will automatically invoke GNUPLOT for you, so you will not necessarily ever need to learn GNUPLOT commands (though, it might be to your greater advantage to do so). (If you have trouble obtaining GNUPLOT from the sources below, or would simply like to help support the development of GFFT, you should know that I provide GNUPLOT and other useful software in the Expanded Deluxe Distribution of GFFT. Please see the README file for further details.) There are many different versions available (on Aminet, many CDROM's, and other fine locations). (Comments for each version follow in double-indented text blocks.) standard GNUPLOT: aminet: util/gnu/gnuplot-3.5.lha (Note: recently this archive seems to have disappeared. I am trying to get it restored. By the time you read this, it will probably either have been restored or updated with gnuplot-3.6.lha. Otherwise, see other options below.) fish: Gnuplot 3.2 is on AmigaLibDisk 701 Gnuplot 3.0 is on AmigaLibDisk 552 GFFT has been tested with GNUPLOT versions 3.0 to 3.5, and should work with others as well. Hidden3D requires GNUPLOT 3.4 or later. You will still be able to display 3D plots with version 3.0, however, just without the Hidden3D feature. The earlier versions of GNUPLOT (3.0 and 3.2) on Fish disks and Gold Fish and Frozen Fish CD-ROMS are particularly recommended for systems with limited memory, i.e. less than 2 Mb. (If you are reading this version of GFFT from a Fresh Fish CD-ROM, there is a good chance Fred has also included an updated GNUPLOT on the same CD-ROM.) GNUPLOT w/GNUFIT Aminet: util/gnu/gnufit12gp35.lha (This is also available on the 3rd Aminet CD-ROM released July 1994.) Until gnuplot-3.5.lha is restored, this will be the best version of GNUPLOT for use with GFFT on Aminet, though GFFT does not yet use the GNUFIT features. It is too big for use on an Amiga with 1 Mb of total ram, however, and doesn't include the GNUPLOT help file, which would be useful if you intended to run GNUPLOT by itself, or learn about the hardcopy output options. Otherwise, it works fine with no restrictions. I am told that future versions of GNUPLOT (3.6 and above) will have GNUFIT included by default. WinGnuPlot (intended for MUI, but also usable w/o MUI*): aminet: util/gnu/WinGnuPlot.lha *Note that you may obtain GNUPLOT from this WinGnuPlot archive even if you do not intend to load Magic User Interface (MUI). If you have obtained GNUPLOT from the WinGnuPlot distribution, then simply rename the file .gfft-WinGnuPlot to .gfft using the WORKBENCH rename operation or the following CLI command: rename .gfft-WinGnuPlot .gfft DO NOT DO THIS IF YOU HAVE OBTAINED GNUPLOT FROM THE REGULAR GNUPLOT DISTRIBUTION! IF YOU FAIL TO DO THIS WITH GNUPLOT FROM THE WinGnuPlot DISTRIBUTION, YOUR SYSTEM MAY GURU WHEN RUNNING GNUPLOT!, because otherwise this version will look for a CompuGraphic font and crash if it doesn't find it. All the above .gfft file does is tell GFFT to tell GNUPLOT to use the AMIGASCREEN terminal, instead of AMIGAWINDOW which requires MUI and a CompuGraphic font and is the default for the GNUPLOT from the WinGnuPlot distribution only. The default terminal for the standard GNUPLOT is AMIGA, which is identical to AMIGASCREEN except in name. It is not possible to use the MUI WinGnuPlot features from GFFT. GFFT provides much more complete control over GNUPLOT than WinGnuPlot does at this time anyway. If you will start GFFT from the CLI, you might wish to move or copy the .gfft file to your S: directory so it will always be found no matter what your current directory is when you start GFFT. If you will start GFFT only from the Workbench, this is not a problem as the "current directory" will always be the drawer in which GFFT is located, even if you leave the icon out on the Workbench. If you would also like the use the GNUPLOT from the WinGnuPlot distribution directly from the CLI, you may also copy the .gfft-WinGnuPlot to a file named .gnuplot so that it will also be used as a GNUPLOT startup file when GNUPLOT is started by itself. But note that GNUPLOT will only look in the current directory for its startup file (unless you have set the environmental variable GNUPLOT). (GFFT looks both in the current directory and in S: for its startup file.) One way or another, be sure the 'SET TERMINAL AMIGASCREEN' command is given before running GNUPLOT from the WinGnuPlot distribution unless you have MUI and a CompuGraphic font installed. Installing GNUPLOT ---------- ------- For the purposes of GFFT, all you really have to do is copy the program file named GNUPLOT to your C: directory (and follow the above instructions to create a .gfft file if you have obtained GNUPLOT from WinGnuPlot). Note: You must install GNUPLOT either to your C: directory OR to the same directory as GFFT. It is not acceptable to install GNUPLOT to some other directory in your default path. Installing GNUPLOT to your C: directory is preferable, because it works in all cases. Otherwise, it may not work at all (if you have Workbench 1.3), or it may not work if you invoke GFFT from the CLI when your current directory does not contain GNUPLOT. If you obtained GNUPLOT from the standard distribution, you may also choose to set up the gnuplot.gih file in your S: directory. This will give you interactive help while running GNUPLOT by itself (if you choose to do that). In the WinGnuPlot distribution, you are provided with an AmigaGuide version of the gnuplot documentation. How to install GFFT itself --- -- ------- ---- ------ If you are going to run GFFT from the workbench, you can simply leave the GFFT files in one disk or directory. Then, as long as you haven't stripped down your SYS: disk or partition, everything should be OK and you can begin running GFFT. To use the help facilities of GFFT and a few other message features, you should have the MORE program (supplied on your Amiga Workbench disk) either in the usual place (sys:utilities), in your C: directory, or in the same directory as GFFT itself. GFFT uses MORE automatically to display long messages. If you prefer to use some text reader other than MORE, you can create a link named MORE in your C: directory which points to it. For example, if your preferred reader is MORE2, you could use the following command: makelink c:more c:more2 Makelink is not available in AmigaDOS 1.3. If you still have only that release, you might consider making a copy of your preferred text reader named C:MORE, or renaming it to that permanently. It will then supercede the normal sys:utilities/more for most applications. Alternatively, you may make a copy of your preferred text reader named MORE in the same directory as GFFT if you intend to run GFFT only from the Workbench or from that directory. GFFT also automatically uses a few other commands which are normally included in your C: directory or built-in to the CLI (see COMMANDS USED below). Both GFFT and GNUPLOT use math and other libraries normally found in the LIBS: directory (except for AmigaDOS 1.2 and earlier...see below). If you choose to copy GFFT to your C: directory to use it exclusively from the CLI, you will want to copy COPYING and GFFT.HELP to your S: directory so that GFFT can find them no matter what the current directory is when GFFT is invoked. If you have a 68881, 68882, or 68040 with FPU and a 68020 or better processor, you can delete the ordinary GFFT and rename the GFFT-FPU to GFFT. However, do not then try to run the GFFT-FPU version on an Amiga without FPU. It may fail to run without any warning on an Amiga without an FPU or without a 68020 or better processor. LOW ON MEMORY --- -- ------ First note that the memory allocated by GFFT and GNUPLOT depends primarily on the number of BINS specified. By default, GFFT will use the maximum number of BINS possible, which may not be appropriate for large sample files (and could exhaust available memory). Typically, spectrum analyses are done with 1024 bins (though I prefer to use more for even higher resolution). You may wish to specify a smaller-than-maximum number of bins (using either the Bins gadget in the GFFT dialog window or the BINS command available from the CLI). This is the first of many parameters available to you in GFFT, though it might be the only one you ever need to adjust. If you routinely use a particular number of bins, you may wish to create a .gfft startup file (or edit the existing one created above) to add a bins command, e.g. bins 1024 (The number of bins is the number of non-zero spectral frequencies at which a spectral amplitude or power value will be computed.) Note also that GFFT will use the T: directory for temporary data files. The size of these temporary data files also depend on the number of BINS being used. Normally these files are fairly small, so having T: in ram: (which is the default for AmigaDOS 1.3 and above) should be no problem. However, if you are short on RAM, or if you analyze with a large number of bins, you may wish to reassign T: to a disk. For example, the following CLI commands would create a t directory on sys:, and assign t: there: makedir sys:t assign t: sys:t GNUPLOT takes up most of the memory used while GFFT is operating. GNUPLOT is much larger than GFFT to begin with, and it also uses up dynamic memory which depends on the number of bins being used. Furthermore, GNUPLOT expands considerably with each release. If you get GNUPLOT from one of the later WinGnuPlot distributions that has GNUFIT linked in and is even bigger, you can forget about running in 1 Mb. If memory is a problem, see if you can get GNUPLOT 3.4, or an even earlier release if you are not interested in Time-3D analysis. GFFT itself does not seem to require more than 4000 bytes of stack. To be safe, I have set the icons to bring in 9000 bytes of stack. When GNUPLOT is invoked by GFFT, it is automatically provided with a stack of 30000. If you get a GURU or stack overflow requester while running GFFT, you might try a setting a larger stack in the icon INFORMATION or in your Shell-Startup. If you are short on memory, you might try reducing the stack specification to 4000. Note that AmigaDOS 2.0 or greater handles stack overflows nicely with a requester, while 1.3 may guru on stack overflow. There is also a SAVEMEMORY command available in GFFT. This will save a fairly small amount of memory at the expense of a small increase in execution time. If you are running from the Workbench you can nevertheless use the CLI button to switch into CLI mode to give this command, and then return to the Workbench using the WORKBENCH command. I have been able to run the provided sample (PianoLowC.iff) on a 1 Mb (all chip) Amiga 500 running AmigaDOS 1.3 with no extra buffers or tasks or anything made resident and no hard drive, and with the number of Bins set to 1024. With hard drive added (which uses up memory for its buffers), I had to cut the number of Bins back to 256. I did this using an early GNUPLOT 3.5 w/o GNUFIT. (Note: Earlier versions of GNUPLOT are smaller, later ones are likely to become larger). I don't know what would happen on an Amiga with 512K chip and 512K fast. If all else fails, you may be able to run GNUPLOT from the CLI separately from GFFT. To do this, specify an explicit file for GFFT to write data to and cancel PLOT mode. After GFFT has completed, exit from GFFT and run GNUPLOT, giving it a command like: plot 'myspectrum' with lines Using this technique, however, you will lose the features of GFFT which control GNUPLOT for you. Commands Used By GFFT -------- ---- -- ---- Normally, you will have all the commands used by GFFT on your system disk or partition. However, if you have deleted a lot of these commands to save room, or if you are making a custom boot disk for GFFT, the following information may be useful: Under AmigaDOS 2.0 or greater, GFFT uses the following commands in your C: directory: delete run wait which GFFT also uses some additional commands which are built-in to the CLI under 2.0 or greater, but were implemented in the C: directory for earlier releases such as 1.3: echo endcli endif failat if path stack GFFT also uses MORE, usually found in SYS:UTILITIES. See above for using other text readers. **** Congratulations! You are now ready to run and enjoy GFFT! (The basic idea is to select a sample file, and then click the OK gadget or give the OK command. In between, you may adjust other parameters if desired.) **** 1.2 (sigh) ---------- Special Notes For AmigaDOS 1.2 First, in order for GFFT to invoke GNUPLOT, you will have to add the following lines to your startup-sequence (if you haven't done so already): makedir ram:T assign T: ram:T This should be added immediately prior to the LOADWB command. However, unfortunately, GNUPLOT requires mathieeedoubtrans.library, which is not included with AmigaDOS 1.2. I suggest you upgrade your OS. **** GNUPLOT is Copyright (C) 1986 - 1993 Thomas Williams, Colin Kelley.