Manual for GMT program developers / composers

Installation instructions

Main runtime setup screen:This screen will always open first on starting the compiled GMT software. The menu bar allows the user to select all required settings for his application. The 'Cockpit' window opens after selecting start GMT in this main menu. If any menu item is grayed out, either you do not have the required hardware, or the compilation does not included the required source code or libraries.

Writing code within the GMT in a minimum of time:

Step 1:

Power Basic DLL compiler V8.02 or later:

- start the PBEdit-editor and load our source code file gmt.bas

This source code includes automatically all code contained in our libraries (g_lib.dll, g_mus.dll, g_har.dll, g_indep.dll, g_noh.dll, g_mus.dll, gh_indep.dll...) as well as some code for windows callbacks required for GMT.

In any case, the source-code file is:

• Gmt.bas ' this will always have to be the main module, since it contains the compulsary Winmain() function.

Since power basic has no real restrictions with regard to program size, we have now included all essential GMT code in a single module. (There might be a problem though with source code modules requiring over 600kByte, since the power basic editor is in fact still a 16 bit application...). Please check it out and report any bugs found. Users are advised to add their composition and application code in a separate module, such that they can easily upgrade to future versions of <GMT>. Demonstration code for GMT apps can be found in other *.BAS or *.INC modules such as demo.bas. You can load those in the editor after GMT.BAS or by editing your g_meta.inc file.

Step 2:

Suppose you have something in mind you want to see handled as a task. We will handle this step by example, since this seems to be the most pragmatic way of explaining things in this context. Suppose the task we want to have performed consists of sounding a note using midi. We would use the procedure Play to send the note information to the port:

Play 0, 36, 64 ' suppose channel 0, note is low C and midrange velocity

In order to make this happen, we have to declare a task, preferably in a newly created code module or procedure of your own, but you can also add it in the gmt.bas module.(Later you can easily move procedures from this module to your own...). If at this point you decide to add a module of your own, start by inserting its reference in the header of gmt.bas with a $INCLUDE command. Note that you can only include source code and/or declarations of procedures and functions to be used in a named DLL file. (The use of compiler metastatements is highly advised for building applications).

So we go on and write

SUB MyNote

Play 0, 36, 64

END SUB

Now we have written a task. It wont do anything yet if we launch the multitasker. So we have to declare it, by adding a declaring statement in the corresponding *.BI file or in the procedure declaration section of gmt.bas.

DECLARE SUB MyNote ()

Note that the procedure does not take parameters, so we leave the brackets empty. Procedures we want to see as tasks should never have parameters, since we use a code pointer mechanism inside the taskscheduler. Later we can pass all parameters we want to our tasks either by using semaphore variables, or by using the Windows message mechanism, thus making things like varying reschedule intervals (periods), varying dynamics, controller values, algorithms... possible.

After having done this, still it wont run. We have to initialize the reschedule values for our task and give it a name so that it appears on our screen. Let us choose to make it task nr. 15 (Tasks 0-15 and a few others are reserved for internal GMT-use, so we should not use these numbers. Look into the procedure InitTasks to find out which numbers are free).

Go to the procedure InitTasks in GMT.Bas and lets fill in some values for our newly created task:

Task(15).name = "MyNote"

Then we set an initial reschedule frequency if required:

Task(15).freq = 5               ' 5 times a second this would be

You will already have noticed that the typed array variable Task().--- has many fields. It's prototype is declared in TYPES.BI and referenced in the header of the GMT.BAS file. The task() type looks like this:

This typed variable array is shared across modules. It is dimensioned in GMT.Bas, and known by its pointer in the DLL. Task() is declared as global. (cfr. g_GLOB.BI for a complete declaration of all global variables).

So your code can change the values at any time. The use of the Task().level, Task().channel, Task().switch, Task().patch, Task().duur variables is not restricted to their names within our code-framework. So if you are writing code for tasks not requiring certain fields provided in the type, you may use them for other purposes. However, for code clarity, it is a better idea to add specific typed variables of your own. If you need more task linked data, we also provided the TaskEX() type. Herein we store handles for extra real time controlls and dialogs, etc. Details are documented in G_TYPE.BI The Task() prototype contains a single field which the user should not set/reset nor interfere with in any respect. This is: Task().rsi.

From this, it will be clear that our procedure can already take profit of some of the features of the Task().- variable. Let's implement it right away, and change our procedure as follows:

SUB MyNote

Play Task(15).channel, 36, Task(15).level

'Task(15).level  is the velocity as calculated in a procedure or function.

END SUB

and set the appropriate fields in InitMT:

Task(15).channel = 0

Task(15).level = 64

Since we can already foresee from now that we forgot to switch the sounding note off, we may as well implement this on entry by writing:

SUB MyNote

STATIC Oldnote%

Newnote%= 36 :' low C

IF Oldnote% THEN

NoteOff Task(15).channel, Oldnote%

Oldnote%= %False

ENDIF

Play Task(15).channel, Newnote%, Task(15).level

Oldnote% = Newnote%

END SUB

It will be clear that we have now prepared our task already to accept the note value as a parameter, or to expand the procedure such as to calculate new notes every time it is invoked. Lets make our note go up and down using the cosine function:

SUB MyNote

LOCAL Newnote%

STATIC Oldnote%

Newnote%= 48 + (COS(Promil!) *12)           ' down to 36 and up top 64

IF Oldnote% THEN

NoteOff Task(15).channel,Oldnote%

Oldnote%= False

ENDIF

IF Newnote% <> Oldnote% THEN

Play Task(15).channel, Newnote%, Task(15).level

Oldnote% = Newnote%

ENDIF

END SUB

In order to use the Promil% function, (as well as the derived functions Tprop! and Tang!) you have to set a value for the global variable Komposduur%. This value should be expressed in absolute duration units, in seconds. The value is found in the GMT.INI file, so the user can change it easily using notepad or the PB editor itself. Or, better, make up an application specific ini file where you set a suitable value.

Step 3:

Now we are done with the coding. The next and last step prior to test running, is enabling the multitasker to recognize your task. Go to the InitTasks procedure and search where we fiind a reference to Task(15). The we add:

Task(15).cPtr = CODEPTR(MyNote)

Now save all, and make sure you have added the declare statement to either GMT.BI, to the header of Gmt.Bas in the appropriate section, to your own declaration file. (In the latter case, insert it in the header of GMT, following the other #INCLUDE statements.)

COMPILE IT and/or RUN IT !!! (Do not attempt to run it using the PBcc debugger: this does not work at all for real time apps like this one!).

When you startup the program, it will display two windows: a 'Cockpit' style controll window and a 'welcome' and initialisation window. Make the latter active and initialize the I/O dives you want to use (Click on the menu items Input-devices and Output devices). Follow the instructions displayed in the messageboxes on screen. If you finished this step, select Start in the menu and the win dow will minimize itself leaving you only with the cockpit window, which is the main command window for GMT. If you have your midi module connected, or if you have selected internal sound devices, the program should start running. In order to activate your newly created task, use your mouse and click on its name in the corresponding check box. (Your task name should appear in the Cockpit window to the right of a checkbox).

So we helped you through the very first steps... The rest is left to you imagination! You might be helped by studying the sample procudures provided in the debug module (One does an upwards scale, another one a downwards scale in a different tempo).

Note that this GMT-framework is basically capable of all things such a program as Max or better, PD, can do. Only with these differences:

1.-it's a whole lot faster! (Max is originally developped for the legacy Macintosdh system and was only later translated for Intel platsform PC's) . On the PC platform, PD is in fact a much better alternative. PD is public domain and free!

2.-it's open architecture and public domain!

3.- it's for free...

You can remap whatever incoming information into whatever going out, feeding it to and transforming it by any algorithm of your liking. Although in this Basic version, its a bit harder to take profit of many new hardware features offered on the Windows platform, it is not at all impossible as we have shown in many of our GMT applications. Users have to know and understand the Win32Api in order to add these features..

People interested can obtain hardware specific GMT-libraries supporting a range of ADC/DAC converter boards (ISA, USB, PCMCIA...). We have used the Contec and Arcom boards to good success in our compositions <A Book of Moves>, <Songbook>, <Mach'96>, <Winter'97>. This is really the best way to go for real-world interfacing, and at the same time the reason to go for PC's for this kind of applications. We have libraries for FFT-analysis, complex math and filtering, robot-controll… available as well. Much of it is actually already a part of the code contained in our libraries. On purpose we did not include any of these extra features in the GMT basic package, that we wanted to keep as much bare bones as possible. Contributions from people writing Basic code or public DLL's are welcomed! Support for USB-based data acquisition hardware is available. Sofar we support devices by National Instruments. Since august 1998, only the version written in PowerBasic DLL will be available from the logos website.Comments relative to previous versions can be found in our archive file http://www.logosfoundation.org/logos/gmt/gmt_archive.html. Since october 1998, we stopped all support for the Dos-box only versions of this package. Now we exclusively use Power Basic's dll compiler version 8.02.

After the proper devices have been selected, the opening screen displays the users choices in a list as follows:

The GMT-Cockpit : User Interface

Users Guide to public declared Tasks, Functions and Procedures

List of GLOBAL variables

• g_glob.bi

All main procedures and functions are now to be found in the code modules: GMT.BAS or, for the largest part, are contained in the DLL libraries.

Here we present them in categories. We do not have the time to regularly synchronize the contents of this manual with the contents of the code. So please, look into the source code for the most up-to-date and accurate information. Often we move source code from the main GMT module to the dll libraries. So if you cannot find something referred to in this section in GMT.BAS, please have a look in its libraries, g_lib.bas/bi, g_nih.bas/bi, g_noh.bas/bi,g_indep.inc... . There is usually a lot of comment embedded in our source code. New since version 2.1 is also that we are now including all procedures and functions in a single hyperlinked index covering both our trusted HarmLib and <GMT>.. Since version 2.2 we integrated complete support for the Win32Api. This ought to make us more independent from common but very contingent hardware intrinsics of users machines. The drawback is that our code now absolutely needs a 32-bit OS as well as a fast Pentium processor. MMX support is very desirable now. There are, since version 2.3 a lot more midi functions and procedures. Since version 3, there is also suppport for real time audio processing. Version 3.3 brings support for data acquisition hardware: this module can be requested on demand. It makes no sense including it in the main GMT package, since most users do not have the required hardware.

TASKS

All midi related procedures and functions have been placed in a separate section of the DLL file since 03.03.1999... The manual, covering all midi related functions is also in a separate file now:

gmt_midi.html

2. Internal GMT Main-module tasks functions and procedures

Code module: DLL

Procedures:

StartTask tasknumber%

• This procedure performs all thats needed to start a task under GMT. If called with a negative tasknumber, it does not set the checkmarks in the cockpitwindow. Negative parameters for tasknumber% are used internally within the Windows messagehandler, that takes care of screen updates itself.

StopTask tasknumber%

• This procedure performs all thats needed to stop a task under GMT. If called with a negative tasknumber, it does not set the checkmarks in the cockpitwindow. Negative parameters for tasknumber% are used internally within the Windows messagehandler, that takes care of screen updates itself.

SUB CleanUp ()

• This procedure leaves the computer in a clean state after ending <GMT>. It is called by pushing the close button of the Cockpit Window.

SUB InitTasks ()

• Task definitions and parameter initialization

SUB PrepareMenu ()

• This procedure is a meta-compiler procedure and makes sure the menu items that are selectable in the opening window are enables/disabled/grayed in accordance with the version compiled. It is steered by the declaration of the metacompiler constants such as %NiDAQ, %gwr, %demo, %students9899 etc...

FUNCTION CheckTimerResolution LIB "gmt_harm.dll" () AS WORD

• This procedure, residing in the DLL library , checks the capabilities of the timer on your hardware. If this timer is not capable of providing <GMT> with the required 1ms resolution, the function will display a message. If the %Wordy constant is set to 3, it will also report the minimum value of the timer resolution as reported by the WinApi. The result of the function is to be used as parameter for the WinApi calls:

• • timeBeginPeriod
  • timeEndPeriod
• The calls always have to be used as a matched pair with identical parameters. More documentation can be found in the Microsoft MSDN. (Multimedia section).

Tasks:

3. Debugging-related tasks, functions and procedures (the reside in the DLL)

SUB ShowMTspeed ()

• In former versions this task displayed the loop-speed of the multitasker (in loops per second). Now it shows the jitter-value for the multitasker. (Should be as low and constant as possible), a less impressive, but a lot more relevant data item.

SUB ShowTime ()

• This task displays a chronometer starting on pushing the start button in the cockpit window

SUB ShowPromil () :

• This task displays the proportional position where we are in a musical piece, if the duration was defined in Komposduur%. (cfr. GMT.INI file)

SUB wPrint (param AS DWORD, BYREF gList() AS ASCII * 80)

• This procedure creates a non modal text only dialog wherein you can display a string array passed by reference. The string array is normally declared global in gmt_debug and is dimensioned as gList(0 to 30) such as to conform to DOS windows as we have known them for many years. You can destroy the dialog with the text by calling the procedure with %False for param. All other values for param will create a dialog. If the dialog already exists, the new text passed will be displayed.

DEMO task code:

SUB ScaleUP (): ' test task - example for the coding of a task playing an upwards scale (in module gmt_demo.bas)
SUB ScaleDOWN () :' test task - example downwards scale

4. User-related tasks functions and procedures, application examples

DEMO code:

DECLARE SUB VoiceProtoType (tasknr%):' test task 18 - example code from boxing
DECLARE SUB Player () :' test task 21 - example code for use of midi input
DECLARE SUB GlobHar () :' task 28 - example code from Boxing
DECLARE SUB DelayPlayerF (tasknr%) :' - example code for delay lines
DECLARE SUB DelayPlayerS (tasknr%)
DECLARE SUB DelayPlayerN (tasknr%)
DECLARE SUB DelayPlayerBackN (tasknr%)

5. Time-related tasks functions and procedures, application examples

FUNCTION GetPromil% ()

• returns the %% of a musical piece or event, relative to global variable Komposduur%. The count starts only after the <Start> button has been activated in the Cockpit window.

FUNCTION Tprop! (k%)

• Returns a normalised value for the progress of the task (0-1), parameter k%= tasknumber
  Returns a normalized value (0->1) for the time of the task with the tasknumber passed.

FUNCTION Tang! (k%)

• the same, but expressed as an angle in radians. It returns the angle in radians of time passed in task k%

6. Window & Win32Api tasks functions and procedures, application examples

• CenterWindow hwnd

Centers a window on the screen. You have to pass the handle. (LONG)

• CornerWindow hWnd, place$
• Positions a window in one of the corners of the screen. You have to pass the handle (LONG) as well as the placement in the form of a string parameter:

for upper left corner you pass "UL" or "BL" or "1"

for upper right corner you pass "UR" or "BR" or "2"

for lower left corner you pass "DL" or "OL" or "4"

for lower right corner you pass "DR" or "OR" or "3"

 

---

• Warning messagetext AS STRING, duration_in_ms AS DWORD

This procedure, residing in the DLL was added to the library to overcome the lack of easy to use, non-modal text displaying tools both in the WinApi and in PowerBasic. The MSGBOX function in PB as well as the MessageBox function in Windows both confront you with minimal modal dialogs that require user interaction and halt the flow of your programm. So out procedure displays the string passed in a autowrapping and autosizing window that kills itself after the time set in duration_in_ms is passed. This duration has to be passed as a value expressed in milliseconds.

Sorry but the manual isn't complete and ready as yet…We will update and complete it as soon as we can. Reading through the source may help you out in this early stage!.For quick references, please consult the language reference: index-harmlib.html This is always the first file we update as new functions become available.

Compositions realized using this software: <Fall'95>, <Sincs>, <Counting Down to minus 747>,<Mach'96>,<Winter'97>, <Boxing>, <CoHiBa>, <Gorgonio>, <OboTek>, <CelloPi>,<LickStick>,<Hidden {C} Harrns>,<Climbing FujiSan>,<FriRick>,<Fidel-C>, <TechnoFaustus>,<Gestrobo>,<PicRada>, <Quadrada>, <TransiTrance>...

Other composers and musicians using this real time software: Joachim Brackx, Karin De Fleyt, Marc Maes, Luc Brewaeys, Champ d'Action, Kristof Lauwers,Yvan Vander Sanden, Kris De Baerdemacker...

Last updated: 2024-03-31