
* FORMAT DESCRIPTION OF VLM FILES

    Basicly *.vlm files have the same format as the normal atari program
    files. At the beginning of the text-segment there is the module 
    structure, which looks like this:
    
      DC.B "VLM1"       ;vlm module type
      DC.L infotext     ;pointer to an infotext
      DC.L settings     ;pointer to a settings-structure
      DC.L init         ;pointer to an initialization routine
      DC.L deinit       ;pointer to an deinitialization routine
      DC.L main         ;pointer to the mainloop routine
      
    If there is no infotext or a settings-structure, the value has to
    be set to zero (DC.L 0). 
    
  + VLM MODULE TYPES
    
      The moduletype "VLM1" uses an own DSP program, which analysis the
      incoming sound. The DSP initialisation must be done in the init
      routine.
      For easier implementations of effects there is a moduletype "VLM2".
      This moduletype runs a standart DSP program. This DSP-program takes
      out some information of the music. After every mainloop cycle these
      values are transfered to an area of the cpu memory. 
      
  + INFOTEXT
    
      Every infotext line must be finished by zero. The infotext itself
      must be finished by two zeros. So an infotext can look like this:
      
        infotext:
        DC.B "Spectre analyser",0
        DC.B "version: 1.0",0
        DC.B "author:  Achim Settelmeier",0
        DC.B 0
        EVEN
        
      The number of characters per line is not limited but it is good
      to use less lines than 25 because the width of the info-box of "Whip".
      
  + SETTINGS

      Every VLM module can feature parameters for more flexibility. In
      general the number of parameters is not limited. The format of the
      settings structure is for example:
      
        settings:
        DC.L 3           ;number of parameters
        DC.L par_name1   ;pointer to the name of parameter 1
        DC.L 1           ;type of parameter 1 (activator)
        DC.L 0           ;value of parameter 1 (initialised with defaultvalue)
                         ;1=enabled, 0=disabled
        DC.L 0           ;pointer to a parameter structure (depends of the
                         ;type of parameter), 0=no parameter structure
                         
        DC.L par_name2   ;pointer to the name of parameter 2
        DC.L 2           ;type of parameter 2 (choice)
        DC.L 1           ;at the beginning the first button is enabled
        DC.L par_struct2 ;pointer to choice parameter structure
        
        DC.L par_name3   ;pointer to the name of parameter 3
        DC.L 3           ;type of parameter 3 (slider)
        DC.L 100         ;defaultvalue of slider and later the slidervalue
        DC.L par_struct3 ;pointer to slider parameter structure
      
      There are different kinds of parameter types:
      
    - ACTIVATOR
        
        An activator is just a button which can be selected or deselected.
        It can either be active or not. There is no special parameter 
        structure for this type of parameter. As parameter type must be
        specified 1. The value of an activator can be 1 (enabled) or 0
        (disabled).
        
    - CHOICE
    
        A choice is represented by a set of alternatives. Each alternative
        is a button, but only one of them can be selected at one time. So
        these are the same as radiobuttons. The parameter type must be set
        to 2 for this one. The value of the parameter represents the number
        of the selected alternatives (beginning with 1). For this parameter
        an additional parameter structure is needed to be specified:
        
          par_struct2:
          DC.L 3           ;number of alternatives
          DC.B "SLOW",0    ;text of button 1
          DC.B "MEDIUM",0  ;text of button 2
          DC.B "FAST",0    ;text of button 3 
    
        Each button text must be terminated by zero.  
        
    - SLIDER
    
        A slider can be used to get a value in a specified range. A slider
        has the following parameter structure
     
          par_struct3:
          DC.L 0           ;minimum value
          DC.L 200         ;maximum value
          
  + INIT ROUTINE
      
      The routine is called at first and offers the possibility to make
      precalculations, set up values etc. This routine is called only once.
      The init routine gets one parameter which is a pointer to a structure.
      This structure features pointers to different service routines. It
      is very useful to store the pointer to this service structure in a
      variable (for example: move.l a0,service_struct).
      
    - SERVICE STRUCTURE
    
        The service structure is filled out by the calling program. The 
        VLM module can feel free to make use these routines, which are:
        
        offset | routine
        -----------------------------------------------------------------
        00     | set_vblrout (a0: routine adress)
               |   set a routine that will be called everytime when a
               |   vbl interrupt occures. The routine has to end with rts
        04     | wait_vbl
               |   wait until vertical syncronisation (vbl occured)
        08     | set_scradr (a0: new screen adress)
               |   set adress of visible screen to the specified adress
        12     | set_resolution (d0: resolution id)
               |   set the screen resolution to the specified one
        16     | get_left_spec
               |   returns adress of the left spectre (which consists of 
               |   128 words) in a0. Values ranges from 0 to 65535
               |   This function is only usable in "VLM2" modules.
        20     | get_right_spec
               |   returns adress of the right spectre in a0.
               |   This function is only usable in "VLM2" modules.
        24     | get_left_volume
               |   returns the value of the left input volume in d0
               |   The value can be beetween 0 and 65535.
               |   This function is only usable in "VLM2" modules.
        28     | get_right_volume
               |   returns the value of the right input volume in d0.
               |   This function is only usable in "VLM2" modules.
        32     | get_left_osci
               |   returns adress of the left oscilloscope data
               |   (256 words) in a0. Each value is 16bit signed.
               |   This function is only usable in "VLM2" modules.
        36     | get_right_osci
               |   returns adress of the right oscilloscope data
               |   This function is only usable in "VLM2" modules.

        The routines can destroy the registers d0,d1,d2,a0,a1. 

    - RESOLUTIONS
        
        It is possible to set a resolution using the service routine
        set_resolution. Featured resolutions are:
        1: 320x240 16 bit
        2: 320x100 16 bit
        3: 320x240  8 bit
        4: 320x100  8 bit
      
  + MAIN ROUTINE
  
      This routine is called in every mainloop cycle and is the kernel of
      the vlm module. The mainroutine must end with rts and does NOT include
      the "mainloop". It is just a routine, which is a part of the mainloop.
      The mainloop control is made by the calling program.
    
* GENERAL RULES

  Please do only use the functions provided by the module interface. Please
  do not use any GEMDOS, XBIOS etc. functions, except when you code a VLM1
  module and want to initalize the DSP. 
  The whole vlm module is executed in supervisor mode. Please do not change 
  the cpu mode in your own module.
  
  
* CONTACT

  Norman Feske
  Uhlandstr.6
  01069 Dresden
  phone: ++49(351)471 68 75
  email: nf2@inf.tu-dresden.de
  www:	http://escape.atari.org
  
* LAST WORDS

  I would be very happy to see your creations. It was nice to collect all 
  existing vlm modules on my homepage. So everyone had an overview about
  all modules.

  If you have any problems just contact me.
  
  Good luck,
  
Norman Feske (NO/Escape)
