Prof.Dr.Godfried-Willem RAES

<GMT> & Harmony Library Reference Manual: Module 5: Waves, Spectrum and Harmony visualisation functions

 CHAPTER 5: HARM_VIZ

Procedures for displaying results and data from library functions

The functions and procedures contained in this module are not required for the functionality of any other module. They are provided as basic GUI and debugging tool for program development and result evaluation. It is often required that your main module initializes a graphics window, except for functions that only make use of the console screen (the DOS box). We are not giving code examples in this section, since the functions included herein have been integrated in most of the examples given in previous chapters.

Since version 3.8 most of these procedures and functions found a place in the DLL library. This caused some sligth changes in the syntax of the functions. So, now you have to pass a pointer to the Staff (of Stafftype) to the procedures and functions. This is required because we do not share the Staff structure between GMT and the DLL.

Alphabetical list of functions and procedures:

DECLARE SUB ClearScreenBlock (BYVAL hDC AS LONG, BYVAL hor%, BYVAL ver%, BYVAL width%, BYVAL height%)

DECLARE SUB ShowCrd (crd%, v%, h%) [dos only]

DECLARE SUB ShowHar (BYVAL hDC AS LONG, h AS HarmType, hor%, ver%, s!)

DECLARE SUB ShowHarmFuz (refnote%)

DECLARE SUB ShowMelFuz (refnote%)

DECLARE SUB ShowNormArray (hWnd AS LONG,Ar!())

DECLARE SUB ShowPsiChord (hDC AS LONG , h AS HarmType, hor%, ver%, hs%, vs%)

New functions for graphic support using the Win32Api included since version 2.7:

common structure

Staff AS STAFFTYPE

elementary music notation functions to display staffs and notes in a graphic window.

SUB DrawNote (s AS STAFFTYPE,hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)
SUB DrawFlat (s AS STAFFTYPE,hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)
SUB DrawSharp (s AS STAFFTYPE, hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)
SUB DrawClef (s AS STAFFTYPE, hDC AS LONG, BYVAL horpos AS WORD)
SUB DrawBarline (s AS STAFFTYPE, hDC AS LONG, horpos AS WORD)

SUB DrawBlankBar (s AS STAFFTYPE, hDC AS LONG, horpos AS WORD, ...

SUB DrawStaff (s AS STAFFTYPE, hDC AS LONG,...

SUB DrawChordNumber (s AS STAFFTYPE, hDC AS LONG, BYVAL crd%, horblock AS WORD)

FUNCTION ShowNote (s AS STAFFTYPE, hDC AS LONG, midinote AS BYTE, horpos AS WORD) AS WORD

SUB Warning (msg AS STRING, duration AS DWORD)

Users guide

Debug and display procedures for <GMT> & harmony library functions and procedures:

Staff AS STAFFTYPE

All music drawing procedures make use of the global structure STAFFTYPE containing following elements. The fields should be known before calling any of these functions. This structure had to be passed by its pointer to the drawing procedures in the DLL library.

TYPE StaffType

hor AS INTEGER ' horizontal window coordinate for start of staff
ver AS INTEGER ' vertical window coordinate for start of staff
length AS WORD ' horizontal length of staff
clef AS STRING * 2 ' G, F, C clef... the second character may be the staffline used for C-clefs
lijnafstand AS WORD ' for music graphics procedures, distance between staff lines
akkoordraster AS WORD 'horizontal space reserved for drawing chordnumbers as chords
nh AS BYTE ' note height
nb AS BYTE ' note width

END TYPE

Coding for common clefs:

"G2" G clef on the second line of the staff

"G1" G clef on the first line of the staff

"F4" F clef (bass clef) on the 4th line of the staff

"F3" F clef on the 3th line of the staff

"C1" C clef on the first line of the staff (soprano clef)

"C2" C clef on the second line of the staff

"C3" C clef on the third line of the staff(alto clef)

"C4" C clef on the fouth line of the staff

The coordinates for hor and ver are absolute in pixels for the window opened for drawing. The upper left corner has the coordinates 0,0. (As in plain old DOS...). staff.hor and staff.ver define the upper left corner of the staff to be drawn in the window. The stafflength, again expressed in pixels, is in the field staff.length. Note that the clef field is a string variable and should be given between quotation marks. Staff.lijnafstand contains the distance between the lines composing the staff. The sizing of the notes , drawn as ellipses, depends on the variables in staff.nh and staff.nb. Make sure not to exceed the value for staff.lijnafstand for staff.nh.

SUB DrawNote (s AS STAFFTYPE, hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)

SUB DrawFlat (s AS STAFFTYPE, hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)

SUB DrawSharp (s AS STAFFTYPE, hDC AS LONG, lineposition AS INTEGER, horpos AS WORD)

These procedures need a valid device handle for graphics operations in a window. The hDC handle can be retreived using the Win32Api function hDC = GetDC(hGraphicWindow) after creating the window with that handle. Creation of this window is part of GMT source code as well as the messageloop to handle operations in this window.

The second parameter follows the old DARMS code tradition in numbering staff lines. Low D in the G clef (the note just under the staff) is said to sit on line 0. A tone higher, E, sits on line 1, F on 2 , G on 3 etc...

Lines numbering goes on beyond the five lines of the staff: thus noteposition -1 corresponds to C in the G clef and E in the F clef. Odd numbers represent notes drawn on the lines, whereas even lineposition numners represent notes drawn between stafflines.

 

SUB DrawClef (s AS STAFFTYPE, hDC AS LONG, BYVAL horpos AS WORD)

This procedure draws a clef on the staff. The horizontal space occupied by a clef does not exceed staff.nb * 4. Vector graphics are used for the drawing, not a predefined font. The clef drawn depend on the setting of staff.clef, a global variable. 8 clef-types are supported: G1, G2, F4, F3, C1, C2, C3, C4. If an invalid type is specified, the procedure will default the the G2 clef.

SUB DrawBarline (s AS STAFFTYPE, hDC AS LONG, horpos AS WORD)

This procedure draws a vertical barline on the staff.

SUB DrawChordNumber (s AS STAFFTYPE, hDC AS LONG, BYVAL crd%, horpos AS WORD)

This procedure draws a chordnumber on a musical staff as a chord composed of up to 12 notes. The horpos parameter represents a multiple of staff.akkoordraster. (NOT a pixel coordinate!!!).

FUNCTION ShowNote (s AS STAFFTYPE, hDC AS LONG, midinote AS BYTE, horpos AS WORD) AS WORD

This function draws a midinote on a musical staff. The function will attempt to draw in the correct octave position, but will not be able to do so, if the range implemented in our DrawNote procedure is exceeded. The horpos parameter represents the position starting from staff.hor where the note should be drawn. Accidentals are added automatically. (C#,Eb,F#,G#,Bb) The function returns a new value for the horpos position where a next note can be written. This the function can be called with its own argument, to closely print notes next to each other. The function is used in <GMT> to draw melody patterns to be recognized, where proportional time notation and note colors is used.

SUB ShowCrd (i%, v%,h%) [only works when using the console compiler!]

This procedure was added for fast visualisation and debugging purposes. It displays using textmode only, a staff with all notes found in the chordnumber passed as a first parameter. Other parameters are used for location on the screen.

v%= vertical screen coordinates (as in the Basic statement LOCATE)

h%= horizontal screen coordinates

The first parameter should be a chordnumber following the convention laid out in chapter 1, under HARM_GEN. This function allows the display of quite a few chords on a single screen:

v% values: 10,20

h% values: 5,15,25,35,45,55,65,75

Of all the chorddisplaying procedures, this was the fastest one in former DOS versions of GMT/Harmlib. On a pentium 100MHz it took less then 2 ms to perform a single call. The slowness was caused by the fact that we used intrinsic Basic functions to write to the screen. Rewriting in assembler would greatly have improved speed in this case.

Full Win32 graphics functions are available since version 3.0.

Debug and Display procedures for HARM_PSY functions:

SUB ShowPsiChord (H AS HarmType, h%, v%, hs%, vs%)

This procedure was added for visualisation and debugging purposes. It displays graphically the weighted distribution of tones in the chord-array as a bar-graph (stave-diagram). White-key notes will be displayed as white staves, whilst 'black' keys will be displayed in red color. The screen must be set to SCREEN 12 , vga mode 640x480 pixels. The H.C() array is passed as data-input (part of the structure H). The other parameters allow free positioning on the screen.

• h%= horizontal coordinate for the left side of the graph expressed in pixels (1 to 640)
• v%= vertical coordinate for the bottom of the graph expressed in pixels (480 to 1) (Reminder: bottom to top!)
• hs%= horizontal size in number of pixels. The procedure adjusts the value to the closest possible value if needed.
• vs%= vertical size in number of pixels. Internally adjusted.

SUB ShowHar (H AS HarmType, h%, v%, s!)

This procedure was added for visualisation and debugging purposes. It displays graphically the weighted distribution of all notes in the complete 128-byte harmony string as a bar-graph (stave-diagram). White-key notes will be displayed as white staves, whilst 'black' keys will be displayed in red color. The procedure displays the weighted loudness of all notes from 0 to 127. The screen must be set to SCREEN 12 , vga mode 640x480 pixels. The harmony string is passed as data-input, via its structure. The other parameters allow free positioning of the graph on the screen.

• h%= horizontal coordinate for the left side of the graph expressed in pixels (1 to 640)
• v%= vertical coordinate for the bottom of the graph expressed in pixels (480 to 1) (Reminder: bottom to top!)
• s!= scaling factor. If set to 1, the staves will be 128 pixels high.

The procedure adjusts all values to the closest possible values if needed.

Procedures to display the data in the fuzzy-data set files

SUB ShowHarmFuz (b%)

Utility procedure to display the lookup tables for harmony in a message box. The parameter is a midi-note value, to which the harmony relations will be shown. This procedure is only used for debugging. Users can use their own data set in a file called har_fuz.dat. The default data set is compiled into the program.

SUB ShowMelFuz (b%)

Utility procedure to display the lookup tables for melody in a message box. The values shown will be relative to the note parameter given in b%. This parameter should be a midi-note value. This procedure is only used for debugging puposes. Users can use their own data set in a file called har_fuz.dat. The default data set is compiled into the program.

Procedures to display waveforms and other normalized arrays

SUB ClearScreenBlock (BYVAL hDC AS LONG , BYVAL hor%, BYVAL ver%, BYVAL horpix%, BYVAL verpix%)

This procedure erases a rectangle on the screen, as filled with ShowNormArray(). It sets the contents back to the background color. The parameters are:

• hor% = left most horizontal position of the block to erase
• ver% = central vertical position of the block to erase
• width%= witdth expressed in pixels of the block starting from hor%
• height% = heigth expressed as number of pixels the block occupies vertically.

If these last two parameters exceed screen size, the procedure will adjust automatically to stay within screen limits for VGA 640x480.

SUB ShowNormArray (hWnd AS LONG, Ar!())

This procedure draws a graph of the array passed in a window, passed by its handle. The scaling is automatic and adept to the size of the window. The values in the array are supposed to be bipolar normalized and not to exceed the range -1 to +1. This is not checked inside the procedure however. The procedure draws a horizontal time axis and a vertical symmetry axis. The procedure can be used to display waveshapes as well as spectral distributions. You can create a suitable window for this procedure by calling MakeSpectrumWindow.

NEW VERSION 20.04.2000

Filedate: 971122/2004-10-30