AudiLabDip graphics library

1. Introduction

Dip icon

My graphics software uses my Dip (Device-Independent Plotting) library for producing graphics output. Dip is an enhancement of the old Tektronix Plot-10 library, with the addition of color, polygons, menus, etc. It uses a bottom layer of device-dependent driver routines which are in the Sysdep part of my Gut library.

The Dip library is implemented mostly in Fortran. It was originally developed under VMS for the VAX, and later under Compaq (Digital) Unix for Alpha and GNU/Linux for Alpha and Intel. It is currently being developed under GNU/Linux for Intel and AMD and (alas) Microsoft Windows. So far there is no documentation beyond what you're looking at.

Under Linux, Dip uses Alan Richardson's xvertext-5.0 (available here and here) for drawing rotated text. I have changed NULL to 0 at 7 locations in the source code to avoid the compiler warning 'makes integer from pointer without a cast'.

2. Installation of software using Dip

2.1 Introduction

Dip can make use of some configuration files and some environment variables. The instructions in this section refer only to the HOME environment variable, which specifies a user-specific directory where the software can create and modify various files, for configuration, logging, etc. The section below on advanced installation describes optional additional features.

The environment variable HOME specifies a user-specific directory where the software can create and modify various files, for configuration, logging, etc.

2.2 Installation under MS Windows

  1. Download the programme executable for 32-bit Windows to somewhere on your hard disk. Just clicking on the link provided on the appropriate Web page should cause your Web browser to offer to save the file. (Users within AudiLab are advised to access the executable directly from probeShare via a mapped drive on their Windows machines, in order to always be sure of using the latest version.)
  2. To create an shortcut for the programme on the Windows desktop or start menu, right-click on the Taskbar and select Properties from the popup menu, select the Start Menu Programs tab and then Add..., and then follow the instructions for adding a shortcut. The resulting shortcut will use the Dip icon . You can change it to the AudiLab icon by accessing the Properties of the shortcut and selecting Change Icon.
  3. Choose a directory (e.g., D:\USERS\yourname) which the Dip software can use for your home directory. If you use something other than D:\USERS\yourname, replace D:\USERS\yourname in the instructions below by whichever directory you've chosen.
    This directory is used to store certain information from one session to another. If you will be using the software on multiple machines, you might want to specify some shared directory which is available from all of the machines. (In BME, you might want to use the P: drive which is mapped to the Probe server. )
    The folder name should not contain space characters; to be safe, use only letters, digits, and the underscore and hyphen characters.
  4. To setup the Windows environment variable HOME required by Dip:
  5. If the software fails under Windows 7 with an error message about not being able to open a log file, right-click on the executable file; select Properties and select the Compatibility tab; then check the box to Run this program as an administrator.

2.3 Installation under Unix and Linux

2.3.1 General

Copy the executable file to somewhere and make it accessible somehow, in the normal n*x way.

It is assumed that a HOME environmental variable is already defined.

2.3.2 Missing library

Dip software requires version 5 of the ncurses library, but recent versions of Linux may only have version 6. If you get an error message saying that is missing, give the command
sudo apt-get install libncurses5

2.3.3 Fonts

If the programme doesn't run properly, you may need to worry about fonts. As the default font, Bitstream Courier is tried, then Lucida Typewriter, then Courier. For fonts explicitly selected by the software, the following table describes the first choice of font and a fallback choice for each style. This mix of fonts was arrived at by trial and error on one particular set of computers at one particular point in time, and may not make sense in general.
First choice Fallback
Sans serif Monospaced Bitstream Vera Sans Mono Courier
Proportional Bitstream Vera Sans Helvetica
Serif Monospaced Courier Courier
Proportional DejaVu Serif Times
One way of having Helvetica, Times and Courier available is to install the Debian gsfonts-x11 package by giving the command
sudo apt-get install gsfonts-x11
This makes Postscript fonts available to X11. (Among others, Adobe Helvetica, Times and Courier are provided as aliases for URW Nimbus Sans L, Nimbus Roman No9 L and Nimbus Mono L, respectively.) If that doesn't work, another possibility is to install the Debian packages xfonts-75dpi and/or xfonts-100dpi. (They're not both required but it doesn't hurt to have both.) After installing the font package(s), give the command
xset fp rehash.

2.3.4 Partly or completely black window

If X11's backing store is not enabled then a Dip window, if covered by another window and then re-exposed, will not be refreshed and part or all of it will be black. Even if the backing store is enabled, a Dip window will come up all black after being minimized and then restored. However, there is little or no reason to ever minimize a Dip window.

If a Dip window is completely or partly black, you need to force it to be repainted. If the programme displays a Repaint button in the lower left corner, then clicking on it will refresh the window. You may need to type Control-Z or click in the lower left corner a few times to get the Repaint button to appear. If there is no Repaint button, typing Control-Z one or more times may cause the main user prompt to reappear.

The backing store can be enabled by putting the line Option "BackingStore" "True" in the Device section of the system's /etc/X11/xorg.conf file. If there is no such file, create one containing the following:

Section "Device" Identifier "Screen0" Option "BackingStore" "True" EndSection
I have not managed to make this work at all in VirtualBox. The xdpyinfo command can be used to display the status of the backing-store option.

Backing-store behaviour in the X server has changed with time (ref). Apparently it was removed at one time and then re-implemented ‘fairly recently’ (as of 2014 Feb). See, for example, this patch from 2013 Nov. And apparently at one time there was a bug such that the backing store could be enabled using the +bs qualifier with startx but not by using the backingstore option in xorg.conf (e.g., ref).

3. Using Dip menus

3.1 Overview

Menus are displayed as 3-D buttons which are shaded like this Button up when they're up (or unselected) and like this Button down when they're down (or selected). Menu selections are made either with a mouse click or with single-character keyboard shortcuts, as indicated by the underlined character in a menu button.

If the shift key is held down while the mouse is clicked on a menu button, all of the buttons between that one and the previously clicked one will be either selected or unselected. For example, if you click on menu button A to select it and then shift-click on button E, buttons B to E will all be selected. If you unselected button A by clicking on it and then shift-clicked on button E, buttons B to E would all be unselected.

Note that if you exit from one menu by clicking on a button in some other menu, that button will not actually be activated. Click on it a second time to activate it. This is a sometimes very irritating side effect of the way that the user interface is currently implemented.

3.2 Shortcut keys

Sample menu

Each menu item should have one character underlined, which serves as its keyboard shortcut. In some cases the underlined character comprises one letter of the corresponding command. In other cases, as illustrated in the menu shown here, digits (1 to 9) and letters (A to Z) are added to the menu buttons as shortcuts.

The shortcut keys are not case-sensitive, so, for example, a and A are equivalent. There are also equivalences between other pairs of characters which commonly appear as shifted and unshifted pairs on the keyboard, as shown in this table:
~!@ #$% ^&* ()_ +{} |:< >?
`12 345 678 90- =[] \;, ./
This means that you do not need to use the Shift key in order to use these shifted characters as shortcut keys. (The equivalences may not make sense for some keyboards, but they are applied none the less.)

3.3 Common control buttons

A menu may include some or all of the control buttons shown at the bottom of the sample menu shown here. The All button (keyboard shortcut = *) causes all of the menu items to be selected. The Inv button (shortcut = ~) causes all of the item selections to be inverted; that is, selected items become unselected and vice versa. These buttons don't appear if only a single item may be selected at one time.

The buttons labelled [<, <<, <(, )>, >> and >] (shortcuts [, <, (, ), > and ]) scroll the menu to the first item, one page back, one item back, one item forward, one page forward and to the last item, respectively. These buttons don't appear if the menu is short enough to appear on the screen in its entirety.

The Can button (shortcut \) cancels the menu, while the OK button (shortcut /) accepts the current set of selections. These buttons don't appear if only a single selection is possible and the menu closes as soon as that item is selected.

3.4 File browsing

File-browsing menu

When you are browsing to select an existing file to open, a menu like the one at the left will appear. The top menu button shows the current directory path; if you click on it you will be asked for a new directory path at which to start browsing. The second menu button is for moving up one level in the directory tree.

Each of the remaining entries in the menu is preceded by either D for ‘directory’, F for ‘file’, L for symbolic link, or ? for other. Clicking on a D button will move into that directory; clicking on an F button will select that file. Clicking on either an L button or a ? button will cause an error.

If the menu is too long to be displayed all at one time, navigation buttons will appear at the bottom and can be used for moving back and forth in the menu.

If you are creating an output file, a <new file> button will appear as the third button from the top of the menu. If you want to use an existing filename for the new output, just browse to the appropriate directory and select the file in the usual way. If, however, you wish to create a new file, browse to the desired directory and then click on the <new file> button. You will be prompted for the name to use for the new file. Normally you should not include the filename extension (or type); e.g., if you want to create the file test.tif, just specify test as the filename. The programme will know from the context what filename extension should be used.

4. Advanced topics

4.1 Optional configuration files

4.1.1 Input and output

The .pen and .gtd files are small text files used for configuring terminal interaction and graphics output. The only parameters which should normally be adjusted are GNPXH, GNPXV and GFONTSIZE in the .gtd file.

The default .gtd file provided for Microsoft Windows has conservative settings appropriate for low-resolution (1024×768) screens.

The .gtd file can be edited, if necessary, with a text editor like WordPad or Emacs. (Notepad does not work well because it doesn't recognise the Unix-style end-of-line convention.)

Besides the dvfgr_qw and xlib files mentioned below, there are also other .pen and .gtd files available that allow Dip to output its graphics to files in various formats, including TIFF, PPM, PostScript and Grf.

4.1.2 Colours

The file diprgb.txt defines colours by name. It can be used to override or supplement internal colour definitions. It is optional; if used, it should be in the location specified by the FUN_LOC environment variable.

4.2 Optional environment variables

tells Dip where to find its configuration files.
Programmes which use the Dip library use a very primitive method for deciding how large a window to use. If you find that the window has a vertical scroll bar and requires you to scroll in order to see the top or bottom of the display, you may be able to fix the problem by making sure that your display properties are set to use (1) a normal font (not large), (2) a single-line taskbar, and (3) Windows classic style (not XP style). You can also override the default window size by defining an environment variable DIP_NPIXV as the number of pixels you want to use vertically, e.g., 800. You will have to use trial and error to determine a value which uses as much of the screen as possible without having a scroll bar.
The environment variable FTERM (or FUN_TERM under MS Windows) can be used to tell Dip what type of graphics output device to use, and hence which .pen and .gtd files to use. By default, the device type is xlib for Unix and Linux (i.e., any operating system using X11 for graphics) and dvfgr_qw for Microsoft Windows. These days, there is seldom if ever a reason to override the default.

4.3 Specifying the output type

Some Dip software will ask you where to send its output. Normally you just press Enter (or Return) and output goes to the interactive display. To specify output to a file: filename/DEV=devname/qualifier1/qualifier2...

The recognized device names include:

The possible optional qualifiers are The qualifiers may be abbreviated.

If NPIXH or NPIXV is specified, but not both, then the other will be set so as to keep the normal aspect ratio. The standard numbers of pixels for each device type are found in the *.gtd files in FUN_GUT.

4.4 Using the Dip library

See dip.for for an example of using the Dip library to produce graphics. dip_link.csh shows how the programme is linked to the required libraries.

4.5 Internal colour definitions

The following colours are defined internally by default. They may be overridden or supplemented by the user's diprgb.txt file. The list was adapted from a list distributed with X11 by the X Consortium.
red green blue name
Primary colours
0 0 0 Black
255 255 255 White
255 0 0 Red
0 255 0 Green
0 0 255 Blue
0 255 255 Cyan
255 0 255 Magenta
255 255 0 Yellow
Combinations of 0, 127 and 255, or nearby
0 0 128 NavyBlue
0 100 0 DarkGreen
0 139 139 DarkCyan
30 144 255 DodgerBlue
0 255 127 SpringGreen
139 0 0 DarkRed
139 0 139 DarkMagenta
148 0 211 DarkViolet
107 142 35 OliveDrab
112 128 144 SlateGrey
132 112 255 LightSlateBlue
127 255 0 Chartreuse
152 251 152 PaleGreen
127 255 212 Aquamarine
255 20 147 DeepPink
255 140 0 DarkOrange
250 128 114 Salmon
238 130 238 Violet
255 250 205 LemonChiffon
105 105 105 DimGrey
169 169 169 DarkGrey
190 190 190 Grey
211 211 211 LightGrey
255 250 250 Snow
248 248 255 GhostWhite
245 245 245 WhiteSmoke
220 220 220 Gainsboro
255 250 240 FloralWhite
253 245 230 OldLace
250 240 230 Linen
250 235 215 AntiqueWhite
255 239 213 PapayaWhip
255 235 205 BlanchedAlmond
255 228 196 Bisque
255 218 185 PeachPuff
255 222 173 NavajoWhite
255 228 181 Moccasin
255 248 220 Cornsilk
255 255 240 Ivory
255 245 238 Seashell
240 255 240 Honeydew
245 255 250 MintCream
240 255 255 Azure
240 248 255 AliceBlue
230 230 250 Lavender
255 240 245 LavenderBlush
255 228 225 MistyRose
47 79 79 DarkSlateGrey
119 136 153 LightSlateGrey
25 25 112 MidnightBlue
100 149 237 CornflowerBlue
72 61 139 DarkSlateBlue
106 90 205 SlateBlue
123 104 238 MediumSlateBlue
0 0 205 MediumBlue
65 105 225 RoyalBlue
0 191 255 DeepSkyBlue
135 206 235 SkyBlue
135 206 250 LightSkyBlue
70 130 180 SteelBlue
176 196 222 LightSteelBlue
173 216 230 LightBlue
176 224 230 PowderBlue
175 238 238 PaleTurquoise
0 206 209 DarkTurquoise
72 209 204 MediumTurquoise
64 224 208 Turquoise
224 255 255 LightCyan
95 158 160 CadetBlue
102 205 170 MediumAquamarine
85 107 47 DarkOliveGreen
143 188 143 DarkSeaGreen
46 139 87 SeaGreen
60 179 113 MediumSeaGreen
32 178 170 LightSeaGreen
124 252 0 LawnGreen
0 250 154 MediumSpringGreen
173 255 47 GreenYellow
50 205 50 LimeGreen
154 205 50 YellowGreen
34 139 34 ForestGreen
189 183 107 DarkKhaki
240 230 140 khaki
238 232 170 PaleGoldenrod
250 250 210 LightGoldenrodYellow
255 255 224 LightYellow
255 215 0 Gold
238 221 130 LightGoldenrod
218 165 32 Goldenrod
184 134 11 DarkGoldenrod
188 143 143 RosyBrown
205 92 92 IndianRed
139 69 19 SaddleBrown
160 82 45 Sienna
205 133 63 Peru
245 245 220 Beige
245 222 179 Wheat
244 164 96 SandyBrown
210 180 140 Tan
210 105 30 Chocolate
178 34 34 Firebrick
165 42 42 Brown
233 150 122 DarkSalmon
255 160 122 LightSalmon
255 165 0 Orange
255 127 80 Coral
240 128 128 LightCoral
255 99 71 Tomato
255 69 0 OrangeRed
255 105 180 HotPink
255 192 203 Pink
255 182 193 LightPink
219 112 147 PaleVioletRed
176 48 96 Maroon
199 21 133 MediumVioletRed
208 32 144 VioletRed
221 160 221 Plum
218 112 214 Orchid
186 85 211 MediumOrchid
153 50 204 DarkOrchid
138 43 226 BlueViolet
160 32 240 Purple
147 112 219 MediumPurple
216 191 216 Thistle
0 0 139 DarkBlue
144 238 144 LightGreen

4.6 Making animations and movies using Dip

Animations and movies can be produced by first generating sequences of image files using the dipanim_* routines as described below.

From your programme using Dip:

  1. Call dipanim_init once at the beginning. The parameter is the number of digits to be used in making up file names for the set of image files. For example, a value of 3 will permit up to 999 frames to be produced.
  2. Call dipanim_frame once for each frame of your animation.

When you run your programme, for the output destination specify, for example, name/dev=ppm/npixh=320

See dip.for and fling.for for examples.

The Fling programme reads .fli animation files and either displays them or, with an output specification as above, exports the individual frames to image files. The .fli animation files can be produced on a PC using AutoDesk Animator. These files can be played back on the PC using aaplay, or using the portable Fling programme.

4.6.1 MPEG movies

An MPEG movie can be produced by using mpeg_encode to compress a set of PPM files into an MPEG file. Once you have a set of PPM files, create a file name.mpeg_param specifying the parameters for the MPEG encoder. (I last used version 1.2. The latest (1995) version is 1.5b). See the encoder documentation in ~funnell/mpeg_encode-1.2/doc for details. You'll probably want to use an existing file as a template.) Run the encoder with the command
~funnell/mpeg_encode-1.2/mpeg-encode name.mpeg_param .

To display your movie, use the command mpeg_play name.mpg. This is an example of a movie made using DIP. See InforMed for examples of movies made by converting FLI files. Note that some frames of the movies are badly corrupted. This may be because of the particular encoding parameters that I used.

4.6.2 Animated GIF's

Sets of images can be combined into animated GIF files using various software, e.g., ImageMagick.

I have also used Jeff Lawson's fli2gif to convert FLI/FLC files to animated GIF's.

AudiLab home page
R. Funnell
Last modified: 2020-03-23 18:50:37