home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1998 #5 / AmigaPlus_CD-ROM_Nr.5-98.iso / pd / musik / playmf / fireworks / fireworks.doc < prev    next >
Text File  |  1998-04-13  |  17KB  |  463 lines
  1.  
  2.                    ------------------------------------
  3.                       Fireworks - see music explode!
  4.                    ------------------------------------
  5.  
  6. This  is  a  colourful  and  thrilling  little  eyecandy.   It  will  do an
  7. extraordinary  realtime display of MIDI notes that are received on any CAMD
  8. cluster.   You  can  for  example  use  it together with "playmf" from this
  9. package.  The program even has the ability to control PlayMF.
  10.  
  11. Every MIDI file looks different.  Some songs look like going to light speed
  12. in  "Star Wars".  Others look like the sky over Bagdad during the gulf war.
  13. Some look like a fantastic laser show.
  14.  
  15. NEW:   Three  differend  rendering  modes should make everyone happy.  I am
  16. especially  proud  of  the  new Fountain Mode.  It simulates gravity and is
  17. still not much slower than the original "Laser mode".
  18.  
  19. The  notes  will  be sent off into the sky in all directions.  The angle is
  20. varying with the pitch of the notes.  Soft notes will climb up slowly while
  21. loud  notes  will  be  shot  into the sky like flak bullets.  The different
  22. colours  represent  the different MIDI channels.
  23.  
  24. Play  around  with  the window sizes.  Narrow windows (either vertically or
  25. horizontally) have a nice effect.
  26.  
  27. With  my  Picasso  II+  running  Picasso  96  1.34a,  I get about 10-25 FPS
  28. depending  on how many notes are currently visible.  I have no problem with
  29. sizing  the window to about half the size of my workbench desktop.  See the
  30. General Tips section if the program doesn't run as smoothly as you wish.
  31.  
  32. The  option  to  load images as a backdrop into the fireworks window proves
  33. how  fast  Gfx  board  blitters  can  be.  This is really amazing.  Use any
  34. picture you like (as long as your datatypes support it).  But better choose
  35. dark images to have a good contrast to the fireworks.
  36.  
  37.  
  38. Requirements
  39. ------------
  40.  
  41. * OS 3.0 or better.
  42.  
  43. * installed camd.library (available on Aminet)
  44.  
  45. * any MIDI software using CAMD (e.g. Deluxe Music II, playmf)
  46.   or an external MIDI interface for feeding MIDI notes.
  47.  
  48. * some free pens on your Workbench screen.
  49.  
  50. * perferrably a graphics board using Picasso96 or Cybergraphics
  51.   for fast window refresh.
  52.  
  53.  
  54. Psychedelic Comsumation of this Program
  55. ---------------------------------------
  56.  
  57. This  section  is  only for "hardcore users" who like going to the extreme.
  58.  
  59. EPILEPSY  WARNING:  If you are a person who suffers from epilepsy or if you
  60. are  known  to  have  a  high risk of getting an epileptic attack caused by
  61. visual stimulation (flashing lights etc) - THEN DO NOT TRY THIS.
  62.  
  63. For  best  fireworks  experience, you need a fast processor (030/50 is just
  64. enough) and a fast graphics board.  Ideally you have a 17'' or 21'' Monitor
  65. or for the ultimate kick:  a video or data beamer!
  66.  
  67. You  own  a good General MIDI, Roland GS or Yamaha XG synthesizer.  Ideally
  68. you  have  built  my  waveblaster  hack  or  "Project  XG" from the British
  69. CU-Amiga magazine.  Without sound, this is only half the fun it should be.
  70.  
  71. Check  the  "Hide  Title  Bar"  and  "Hide Mouseptr" menu options.  Put the
  72. program  in  Fullscreen  mode  and choose a low resolution (320x240 is just
  73. fine).  People with plenty of computing power may use a higher resolution.
  74.  
  75. Remove  the backdrop image from Fireworks (it's too bright and disturbing).
  76. Turn  on  the  "Sparks"  option in Rendering Modes.  This will give you the
  77. kick.   Begin  with  "Pixel  Mode"  and "Double Strength".  Best choice for
  78. sensitivity  is probably "Med", but depends on the MIDI files you are going
  79. to listen to.
  80.  
  81. Turn  off  the  light.   If  it is daytime, close the windows and curtains.
  82. Your room needs to be dark as hell.
  83.  
  84. Make  your  monitor  bright  and  give  it a lot of contrast (but the black
  85. background must remain black - not grey!)
  86.  
  87. Write a small shell script that will play your favourite (most psychedelic,
  88. most  thrilling  or  whatever)  MIDI  files in a sequence (using PlayMF for
  89. example).  I prefer Classical music (symphonies, orchestral pieces) because
  90. they vary in speed and intensity.
  91.  
  92. Optionally: Get stoned (warning: illegal)
  93.  
  94. Start the script (music).
  95.  
  96. Take a distance of 1-2m to the screen in a comfortable chair.
  97.  
  98. Now  un-focus your eyes so that you don't see the screen in full sharpness.
  99. Alternative:  take off your eye-glasses (may have the same effect).
  100.  
  101. Relax and enjoy the experience. Get flashed.
  102.  
  103.  
  104.  
  105. General Program Usage
  106. ---------------------
  107.  
  108. The  command  can  be started from shell or Workbench.  After starting, you
  109. will  get  an  Intuition  window showing a still image.  Now use PlayMF and
  110. play a MIDI file.  Enjoy the show.
  111.  
  112. If  the  program  appears  too  slow  to  you, then read the "General Tips"
  113. section.   Especially important is to set the DRAGGING=NO tool type in your
  114. Cybergraphics V3 monitor driver.
  115.  
  116. The  background  image  may  be  replaced  against  any other image that is
  117. supported by your datatypes and fits into your memory.  This can be done by
  118. using  the  intuition menu or by dragging and dropping the icon of an image
  119. file into the Fireworks window.
  120.  
  121. MIDI  files  may  be played by dragging their icons onto the PlayMF window.
  122. The  PlayMF  program  will  then be launched automatically.  Make sure that
  123. Fireworks  can  find  PlayMF in the search path or as "/PlayMF/PlayMF" (the
  124. original location in this distribution archive).
  125.  
  126. Furthermore,  the menu options in the MIDI menu allow to load any MIDI file
  127. using  a file requester (see Bugs section concerning problems with MuiASL).
  128. The currently played MIDI file can easily be stopped.
  129.  
  130. The intuition menus are quite self explanatory.
  131.  
  132. Fullscreen is probably the best experience.  For optimum performance choose
  133. a  screenmode  with  enough  colours  (16 colors for the fireworks plus the
  134. number  of  colours  your  backdrop  requires).   Try  to  use  low  screen
  135. resolutions.  This will speed up screen refresh.
  136.  
  137. Double  strength  will  draw  all  the  lines twice as thick.  So they look
  138. brighter  and  give  a  better contrast to the backdrop image.  This option
  139. will slow down rendering a bit, though.
  140.  
  141. Release  Notes will kill any "hanging notes" that may have occured during a
  142. buffer  overrun.   Buffer overruns can happen if the program is not able to
  143. handle  the  incoming  notes,  for  example when it is blocked by intuition
  144. menus or requesters.
  145.  
  146. Any  errors will be reported either in intuition requesters or to the shell
  147. window you started the program from.
  148.  
  149. You  can  easily  change the MIDI link.  By entering a non existing cluster
  150. (link)  name, you can create a new one.  So it is possible to have multiple
  151. Fireworks  tasks  show different MIDI files.  Or you can show the same MIDI
  152. fireworks with multiple tasks in different windows with different backdrops
  153. ;-)
  154.  
  155.  
  156. CLI Usage
  157. ---------
  158.  
  159. The template for the shell command line is as follows
  160.  
  161. L=LINK/K,M=MODE/K/N,WX=WINX/K/N,WY=WINY/K/N,WW=WINW/K/N,WH=WINH/K/N,
  162. I=IMAGE/K,T=TILE/S,FS=FULLSCREEN/S,D=DOUBLE/S,SP=SPARKS/S,GM/S,GS/S,XG/S,MT32/S,
  163. NH=NOHOOKS/S,NTS=NOTIMESTAMPING/S
  164.  
  165. Description
  166.  
  167. * L=LINK/K  (Keyword)
  168.  
  169. The MIDI cluster to hook into.  Default is "out.0".  This will show you the
  170. notes  that  are  going  to any external MIDI hardware.  Ideal for use with
  171. playmf.
  172.  
  173. "in.0"  would  show  you  all  notes  that are coming from an external MIDI
  174. interface at your serial port.
  175.  
  176. * M=MODE/K/N   (Keyword, numeric argument)
  177.  
  178. The rendering mode to use.  Currently there are three modes, numbered 1-3.
  179. - 1 is Laser Mode (straight lines, known from earlier Fireworks versions)
  180. - 2 is Pixel Mode (parabolic flight paths, but only pixels)
  181. - 3 is Fountain Mode (parabolic flight paths and true rays)
  182. Default is No. 3.
  183.  
  184. * S=SENSITIVITY/K/N   (Keyword, numeric argument)
  185.  
  186. The  sensitivity  setting  of  the  fireworks.  There are three modes which
  187. correspond  to  the  sensitivity  settings  in  the  Intuition  Menu.  High
  188. sensitivity means that notes will emit faster from the center.
  189. - 1 is Max Sensitivity
  190. - 2 is Med Sensitivity
  191. - 3 is Min Sensitivity
  192. Default is No. 1.
  193.  
  194. * WX=WINX/K/N, WY=WINY/K/N   (Keywords, numeric arguments)
  195.  
  196. The initial window position.
  197.  
  198. * WW=WINW/K/N, WH=WINH/K/N   (Keywords, numeric arguments)
  199.  
  200. The  initial  window  size.   The  width  and  height  refers  to the inner
  201. dimensions and may vary between 64x64 and 1024x1024.
  202.  
  203. * I=IMAGE/K
  204.  
  205. Filename  of  any  image format that datatypes is able to load.  It will be
  206. put as a backdrop image into the fireworks window.  Astronomy images or the
  207. city  skylines  in moonshine make a good view.  The pictures will be scaled
  208. to fit the window.
  209.  
  210. * T=TILE/S
  211.  
  212. Tile  the  backdrop  image  instead  of scaling it.  This is what Workbench
  213. usually does with its backdrops.
  214.  
  215. * GS=FULLSCREEN/S
  216.  
  217. Open  the fireworks on a separate screen as a backdrop window.  This option
  218. will bring up an ASL screenmode requester.
  219.  
  220. * D=DOUBLE/S
  221.  
  222. Draw all lines in double strength.
  223.  
  224. * SP=SPARKS/S
  225.  
  226. Adds glittering sparks to the fireworks.
  227.  
  228. * GM/S, GS/S, XG/S, MT32/S   (switches)
  229.  
  230. these  correspond  to  the  same  switches  of PlayMF.  Please refer to the
  231. PlayMF documentation for more details.
  232.  
  233. * NH=NOHOOKS/S   (switch)
  234.  
  235. disables  the filetype recognition hooks in ASL filerequesters.  Will speed
  236. things  up  and  fixes  compatibility  problems with some ASL replacements.
  237. Make  sure to set this switch when using Mui-Asl (at least until the author
  238. fixes the problem).
  239.  
  240. * NTS=NOTIMESTAMPING/S   (switch)
  241.  
  242. Disables  MIDI  timestamping.   Timestamping  makes Fireworks recognize the
  243. exact  timing  of  all  MIDI  messages.  So the fireworks rendering becomes
  244. exact,  even  if it runs on very low frame rates.  Even after fireworks has
  245. been  suspended  for several seconds (e.g.  by other task or user activity)
  246. the notes are still shown in their correct timing relations.
  247.  
  248. This  new  feature slows down fireworks very slightly.  So it has been made
  249. optional an can be disabled with this switch.
  250.  
  251.  
  252. General Tips
  253. ------------
  254.  
  255. This  program is optimized for use with Picasso96 and Cybergraphics V3.  It
  256. will work on ECS/AGA systems as well, but maybe slower.
  257.  
  258. If  you  use Cybergraphics V3, set the DRAGGING=NO tooltype in your monitor
  259. driver. Otherwise the program will be slow as hell.
  260.  
  261. The  program  uses "intelligent" timing routines that adapt to the speed of
  262. your  screen  refresh.   The  program  runs  on a very low priority for not
  263. disturbing your multitasking too much.
  264.  
  265. If  you have AGA only, try reducing the number of colours on your WB screen
  266. for faster screen refresh.
  267.  
  268. The  fireworks  runs only smoothly if it can handle its graphics completely
  269. with  the  onboard blitter of the graphics board.  If you use Cybergraphics
  270. V3, please enable the option to keep BitMaps in the graphic card's RAM (set
  271. DRAGGING=NO tooltype in the monitor driver).
  272.  
  273. Unload  any large workbench backdrops.  They are likely to eat a lot of the
  274. graphic board's RAM.  Close other screens on your Gfx Board to increase the
  275. amount  of  free graphics RAM.  This will allow the program to place larger
  276. bitmaps  inside  your  graphics board.  Then you can make the window larger
  277. without losing much refresh speed.
  278.  
  279. Better don't use 24 bit modes.  They use a lot of RAM and require more data
  280. to be transferred over the bus and blitter.
  281.  
  282. Do  not  load  dithered  images  into Fireworks (turn off dithering in your
  283. picture  or  JFIF  datatype when using CLUT modes).  Dithered pictures will
  284. look awful when being scaled, especially when scaled to smaller sizes.
  285.  
  286.  
  287. Bugs
  288. ----
  289.  
  290. well, seems to work fine, except...
  291.  
  292. *  major instability problem on some Cybergraphics system.  Especially when
  293. resizing the window. Still looking for the problem.
  294.  
  295. *  The  ASL  filerequester  of  Fireworks  uses callback hooks for filetype
  296. recognition.   The Mui-ASL replacement has not implemented this, so it will
  297. show _NO_ files at all!  Ask the author to fix this (or at least show _all_
  298. files).
  299.  
  300. * the program may be very slow on AGA machines.  If the CPU is used to copy
  301. the  BitMaps  from  RAM to the graphics board, you have lost.  In this case
  302. your  computer  will  become  slow  as hell.  However if you own one of the
  303. latest  releases of Picasso96 or Cybergraphics, all the blitting is done in
  304. the RAM of your graphics board using the onboard blitter.  -> Faaaast!
  305.  
  306.  
  307. History
  308. -------
  309.  
  310. Release 1-2: this program was not yet written.
  311.  
  312. Release 3: initial release of this program
  313.  
  314. Release 4: the program will stop its window refresh when no notes
  315.            have to be displayed (idle mode).
  316.  
  317.            reduced the probability of "hanging" notes, especially
  318.            after an MIDI buffer overflow occurs.
  319.  
  320.            coordinate calculation is a lot faster now. It uses
  321.            integer maths and precalculated scale factors now.
  322.  
  323.            color palette is now a 360 degree rotation on the HSV
  324.            color wheel (saturation 75%, brightness 100%).
  325.  
  326.            added WINW, WINH keywords
  327.  
  328.            added "intelligent" scheduler that will force a display
  329.            refresh every 1/2 second if any other task runs at a
  330.            higher priority. Make sure to set Fireworks to NOSCHEDULE
  331.            ABOVE if you use Executive.
  332.  
  333.            improved performance on Cybergraphics systems (probably).
  334.            forgot to use BMF_MINPLANES. Picasso96 tolerated this.
  335.  
  336.            added IMAGE keyword. Load datatype images as backdrops
  337.            into the fireworks window! Also added menu options to
  338.            remove and load images.
  339.  
  340.            active MIDI cluster is now shown in window title.
  341.  
  342.            Window title now tells you when Fireworks is in idle mode.
  343.  
  344.            added menu option to release notes (useful when notes are
  345.            hanging after a buffer overrun or similar).
  346.  
  347.            when changing MIDI the link, all notes will be flushed.
  348.  
  349.            added menu option to enable double strength line rendering.
  350.  
  351. Release 5: major internal redesign
  352.  
  353.            added TILE switch and menu option
  354.  
  355.            added DOUBLE switch
  356.  
  357.            added FULLSCREEN switch and menu option and an ASL
  358.            screenmode requester
  359.  
  360.            added drag and drop support for backdrop images.
  361.  
  362.            added drag and drop support for MIDI files.
  363.            (requires PlayMF)
  364.  
  365.            added menu options to play and stop MIDI files.
  366.  
  367.            Fireworks became massively multithreaded. Most requesters
  368.            are asynchronous. The main program continues to run if you
  369.            are selecting a file/screenmode or viewing a message.
  370.  
  371. Release 6: improved screen palette (black blackground)
  372.  
  373.            added modular (multi-mode) design to support multiple modes.
  374.            Added two new modes (Pixel and Fountain mode). This stuff
  375.            is true high tech. So it may (or may not) contain bugs.
  376.  
  377. Release 7: added sensitivity switch and menu options.
  378.  
  379.            fixed some minor display bugs of the fireworks
  380.  
  381.            optimized and improved the fireworks code
  382.  
  383.            added glittering sparks to the fireworks
  384.  
  385.            modularized the source code a bit
  386.  
  387.            added MIDI initialisation switches and menu options
  388.  
  389.            added "psychedelic" section to this documentation. hehe.
  390.  
  391.            added menu option and switch to disable ASL hooks.
  392.  
  393.            fixed potential crash problem in Drag&Drop support
  394.  
  395.            implemented MIDI timestamping. This makes the recognition
  396.            of note timing and length quite exact, even at low frame
  397.            rates.
  398.  
  399.            implemented saving of preferences
  400.  
  401.            added menu options to hide title bar and mouse pointer
  402.  
  403.  
  404. Future
  405. ------
  406.  
  407. * support MIDI volumes
  408.  
  409. * tool type support.
  410.  
  411. * palette preferences
  412.  
  413. * allow setting the center point and angle view.
  414.  
  415.  
  416. See Also
  417. --------
  418.  
  419. "playmf".   A Standard MIDI file player using the CAMD library.  Originally
  420. provided as an example by Commodore.  Now overhauled, bugfixed and improved
  421. by me.
  422.  
  423. PianoMeter  -  an  experimental  graphical note visualisation utility using
  424. BOOPSI  classes.   Try  it!   It  is  a real eyecandy ;-) Based on the "vu"
  425. example in the CAMD developer package.
  426.  
  427. GMPlay  1.3 - available on Aminet.  Uses your CPU to play MIDI music.  Does
  428. not require any MIDI synthesizer, but lots of CPU power and RAM.
  429.  
  430.  
  431. Contact
  432. -------
  433.  
  434. for comments, bug reports and suggestions:
  435.  
  436. The author: Christian Buchner
  437.  
  438.             flowerp@eikon.e-technik.tu-muenchen.de
  439.  
  440.  
  441. Greetings
  442. ---------
  443.  
  444. Rafai Mantiuk - for the BCC precompiler that allows to programm
  445.                 MUI/BOOPSI classes with C++ syntax.
  446.  
  447. Tim Stack     - for his excellent Betty GUI system. This really
  448.                 deserves more public attention. My future application
  449.                 programs will be based on Betty. 
  450.                 see http://www.cs.utah.edu/~stack/betty/
  451.  
  452. CDTV (Tino    - for organizing the cool computer meetings in Erfurt
  453. Wildenhain)     and for testing PlayMF and PianoMeter and for his
  454.                 suggestions
  455.  
  456. Martin Gierich- for his midi.datatype which is based on the original
  457.                 "playmf" as well. However it is not reentrant and
  458.                 will crash when loading the second MIDI file.
  459.                 Hey, have a look at my playmf source code! ;-)
  460.  
  461. Timm Müller   - aka Captain Bifat. For MysticView, render.library
  462.                 and for liking my Fireworks ;-)
  463.