* 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)