Firebee/FireBee_Setup-Dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
b4912f303e267dda7201cc3cf8dec149fe66518b
FireBee_Setup-Dev/THING/TOS2GEM/TOS2GEM.TXT
root b4912f303e initial commit
2023-06-12 09:14:09 +02:00

453 lines
22 KiB
Plaintext
Raw Blame History

Short information for TOS2GEM of 13.09.1996. As at: 13.09.1996
--------------------------------------------------------------
1. What is TOS2GEM?
-------------------
TOS2GEM is a program for the AUTO-folder which offers GEM applications
a flexible way to redirect screen output of .TOS or .TTP programs to
a window. This is achieved with VDI text commands, and allows
programmers of shells or alternative desktops to install a kind of
Console window without much effort.
From this it becomes clear, of course, that TOS2GEM is intended for
use mainly under SingleTOS. Actually it will also run under Geneva,
MagiC and MultiTOS, though here its use is of course very restricted
as TOS programs under these systems run in windows anyway (if they
are started correctly).
The most important properties of TOS2GEM at a glance:
- Offers programmers a clean way of diverting output of TOS programs
started after it to a GEM window
- Simulates TOS screens of any desired size (so not just the boring
80x25), that may also be only partly visible
- Works with all non-proportional fonts in any point size
- With (optional) output buffering can have faster output than with
GEMDOS/BIOS (only for SingleTOS/MagiC)
- Optionally offers a 'history' buffer for older output ('scroll-back')
- Has complete VT52 emulation (colour sequences only optional)
2. How does one install it?
---------------------------
TOS2GEM.PRG is simply copied to the AUTO-folder on the boot partition
and during each boot process creates a cookie which the programmer
can use to control the use of TOS2GEM. But if required TOS2GEM.PRG
can also be started from ther desktop.
3. What is T2GRESET.PRG?
-------------------------
Programs have to reserve TOS2GEM for themselves; until it is released
other programs cannot make use of TOS2GEM. Should a program that has
reserved TOS2GEM for itself crash, or forget to release it when it
terminates, then this blockage can be removed by calling T2GRESET.
It is not advisable to call T2GRESET while the application that
reserved TOS2GEM is still running, because this will necessarily lead
to serious complications. An indication that such a blockage has
occurred is when no program using TOS2GEM is running and a newly
started one reports that it cannot reserve it for itself.
4. What is T2G_INTR.PRG?
------------------------
Since the beta version of 09.07.1995 TOS2GEM hooks into the VBL
(vertical blanking) interrupt in order to be able to trigger a
refresh of the screen contents during time-controlled buffering even
when the running program has made no output for some time (previously
checks were made directly during output only to see whether the time
interval had been exceeded). If this should give rise to unexpected
problems (e.g. unexplained crashes while output redirection is
active) one can use T2G_INTR.PRG to switch off the use of the
interrupt (and switch it back on again if required). If this is
desired or required permanently, then T2G_INTR.PRG should be placed
physically after TOS2GEM.PRG in the AUTO folder.
Important: Those who have included the mini-package of TOS2GEM with
their own programs in the past (see item 9) should ensure that
T2G_INTR.PRG is included in this pckage!
5. What are T2G_BSP.PRG/T2G_TEST.PRG and PRIMZAHL.TOS/PRIME_NO.TOS?
-------------------------------------------------------------------
As it is difficult to visualise what TOS2GEM actually does from a
theoretical description of how it works, I have written a small
example program (called T2G_BSP.PRG for 'TOS2GEM-Beispiel' (-example)
in German and T2G_TEST.PRG in the English translation). Incidentally,
neither file is contained in the small archive (see item 9) such as
the one included with Thing!
After starting this program (TOS2GEM must of course have been started
earlier) a dialog box appears in which one can specify the dimensions
of the TOS screen to be simulated by TOS2GEM, and the maximum amount
of this to be visible. In addition one can select here whether and how
output buffering and colour support are to be used by TOS2GEM.
Following this a corresponding window will be opened to which (already
using TOS2GEM redirection) the dimensions to be realised are written.
Directly after this the program PRIMZAHL.TOS (PRIME_NO.TOS in English)
will be started (it has to be present in the same directory) which
can calculate all the primes up to a specified number which the user
is asked to input, using the 'Sieve of Eratosthenes' algorithm; one
could also use any other .TOS program as long as it is placed in the
correct directory and renamed to PRIMZAHL.TOS or PRIME_NO.TOS for the
German and English versions of the example program respectively.
At the end of the prime number program one can position the window
into which clean output was made anywhere on the screen. Clicking on
the 'Closer' button terminates the program, a click within the working
area of the window brings up an alert offering three choices: 'Resize'
permits altering the TOS2GEM window size (with the same dialog as at
its start; the screen is cleared if the total size is altered). With
'Rerun' PRIMZAHL/PRIME_NO.TOS can be started again and 'Nothing' does
just that...
The example program has been kept simple deliberately, so that one
can see that TOS2GEM support is relatively easy. Not all capabilities
of TOS2GEM are demonstrated (in particular neither various fonts and
character sizes nor a 'scroll-back' history buffer are available),
but it should make clear the possibilities that TOS2GEM offers.
Those who would like to obtain the source code in order to obtain a
concrete picture of TOS2GEM support should get in touch with me (see
below). As the source has been extensively furnished with comments
(in German) and some library fuinctions have been incorporated
directly so that it can be compiled as it stands, its size has grown
to some 46 kilobytes. However the portion that is required for TOS2GEM
support only is relatively small (excluding the comments), so there's
no need to be afraid...
6. Docs for programmers
-----------------------
I have decided to release the hypertext with information (not only)
for programmers in its still incomplete version, since it may be
half-way usable in its present state. To view it one requires ST-GUIDE
by Holger Weets, whom I'd like to thank here once more for this
excellent utility.
In addition to the hypertext docs, those who can read German may be
helped by a look at 'ST-Computer' 04/95 and 05/95.
In addition I'd advise everyone to take a look at the TOS2GEM library
by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) for Pure and Gnu C,
which makes using TOS2GEM child's play. A short summary of its
capabilities can be obtained from 'ST-Computer' 05/95. Anyone wishing
to know more please get in touch directly with Dirk, as I have little
or nothing to do with the library itself.
7. INSPECT.TTP
--------------
This tiny program serves as an aid for programmers who wish to write
applications with TOS2GEM support. More about this can be found in the
hypertext.
8. Legal
--------
TOS2GEM was programmed with great care and tested extensively.
However one cannot exclude the possibility that some bugs remain. I
can therefore neither guarantee fault-free operation of TOS2GEM nor
its fitness for any particular purpose.
Furthermore, you use TOS2GEM at your own risk! I, Thomas Binder, do
not accept any liability or responsibility for any direct or indirect
damage that may arise, either financial, material or any other kind
from either the use or misuse of TOS2GEM.
The same applies, of course, to the associated applications, utilities
and documentation contained in the archive.
9. Distribution of TOS2GEM
--------------------------
TOS2GEM is freeware and may be copied and used freely. For general
distribution one of two of the following packages has to be chosen,
where all the named files have to be copied unchanged in each case
(archiving is permitted):
a) Complete package
Contains TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG, TOS2GEM.H,
TOS2GEM.TXT, T2G_BSP/T2G_TEST.PRG, PRIMZAHL/PRIME_NO.TOS, INSPECT.TTP,
as well as TOS2GEM.HYP and TOS2GEM.REF. This package is mainly
intended for distributing TOS2GEM on its own (when it is not included
with another program).
b) Mini-package
Contains only TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG and TOS2GEM.TXT.
This variant should only be used when one wants TOS2GEM to accompany a
program that requires it.
Those who have developed their own programs that support or require
TOS2GEM may include TOS2GEM in their program package (in one of the
forms mentioned above) no matter whether it is PD/Shareware or
commercial software, as long as the following conditions are fulfilled:
- TOS2GEM must be copied to its own folder
- The documentation or the program must contain instructions for
using TOS2GEM
- It must be clear from the documentation that TOS2GEM is a separate,
free-standing utility developed by me, and that it does not belong
to the actual program
Additionally I would be most grateful if you would send me a sample of
the program.
10. Contact with the Author
---------------------------
Anyone who has found any bugs, would like the source code, needs help
for programming TOS2GEM applications, wishes to send praise, criticism
and/or suggestions or just simply wishes to 'chat' with me can make
use of the following addresses:
Thomas Binder
Johann-Valentin-May-Stra<72>e 7
64665 Alsbach-H<>hnlein
Deutschland/Germany
InterNet: binder@rbg.informatik.tu-darmstadt.de (preferred)
gryf@hrzpub.tu-darmstadt.de
MausNet: Thomas_Binder @ HD (no mails > 16K!)
IRC: Gryf
Those who would like to obtain the extensively commented source code
for the TOS2GEM example should either send me a self-addressed
envelope with German stamps or 2 International Reply Coupons, or be
in a position to receive binaries by Email. In addition you should
specify whether you want the code for the old or new TOS2GEM example.
The newer one uses a little more complicated but in return
multitasking-friendly method of control, while the old version
proceeds 'conventionally'. I'd only recommend the new version to
those who have had previous experience with TOS2GEM programming! For
beginners I suggest the older source code.
Naturally I'd be very happy if some of you would reward the work
that I have put into TOS2GEM with a small contribution sent to my bank
account (or to my British representative - see SUPPORT.TXT.) Every
contributions safeguards further development of TOS2GEM, which I hope
is desirable.
My banking details:
Dresdner Bank AG Frankfurt am Main
Konto-Nummer/Account No.00
Bankleitzahl/Sort code: 500 800 00
Many thanks!
11. Which programs support TOS2GEM?
-----------------------------------
Up to now I am aware of four programs that use TOS2GEM to redirect
output of TOS programs into a window:
- The POVShell by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) from
Version 1.3 onwards
- The alternative desktop Thing originally programmed by Arno Welzel
(arno@alphasystems.de) and now with continued development by me
- The Shell Easy-PGP by Manfred Ssykor (msy@lafp.tng.oche.de)
- A POV-3.0 port by Szymon Stasik (ss158962@students.mimuw.edu.pl)
Since in the age of MagiC and N.AES no other people seem to be
interested in supporting TOS2GEM in their own programs, I have not
done much more in the docs for programmers. I don't want to do
unnecessary work ;)
12. Thanks
----------
The following people took part in the development of TOS2GEM, directly
or indirectly (in alphabetical order):
- Denesh Bhabuta
- Alexander Clauss
- Joe Connor
- Frank Danapfel
- Dirk Klemmt
- Harald Sch<63>nfeld
- Thomas Schulze
- Manfred Ssykor
- Arno Welzel
In addition I'd like to thank all those who have sent me a
contribution for TOS2GEM.
13. Outlook for further development of TOS2GEM
----------------------------------------------
Apart from some possible bug fixes I doubt if I'll do much more with
TOS2GEM, since in my opinion it's already relatively mature; in any
case there seems to be no great demand for it from programmers or
users any more.
14. History
-----------
The history only contains changes from the last pre-release
beta-version of TOS2GEM, as it would get a bit long otherwise...
TOS2GEM of 13.09.1996:
- No more crashes if the visible portion lies outside the physical
screen (even though this is not allowed anyway according to the docs)
- Under certain circumstances the internal colour-buffer pointer
introduced in the beta of 10.02.1996 was not updated when diversion
was switched back on again, which resulted in the colour buffer
being kept at the wrong position
TOS2GEM-beta of 01.03.1996:
- Further small increase in output speed with buffering active
TOS2GEM-beta of 10.02.1996:
- If the time interval for time- and(!) interrupt-controlled buffering
is smaller than 200ms, TOS2GEM omits refreshes during input as one
happens often enough. Thanks to this output from Mupfel under MagiC
is no longer painfully slow (Mupfel asks after outputting each(!)
character whether a character is on the way, which TOS2GEM under
MagiC must normally evaluate as a refresh request)
- The output speed in colour mode is now almost as fast with a white
background as in monochrome, since in this case the additional
drawing of the character background is dispensed with in favour of
the replace-mode. Since a white background is the norm, this
improvement is very noticeable
- Output buffering too has now become appreciably more efficient when
lines contain many space charactes at the ends. Although this is
not quite as common as a white background, it still happens often
enough to make an appreciable difference
TOS2GEM of 26.07.1995:
- Stupidly the 'MiNT' cookie was only looked for when TOS2GEM was
started, so that TOS2GEM also buffered under MiNT when this was
started first (recognition of input requests doesn't work with MiNT
so one may not buffer with it)
- The TOS2GEM example program now exploits the possibility of
reserving TOS2GEM really only when it is needed. So one can now
start it several times (with multitasking) as TOS2GEM is not
permanently engaged
TOS2GEM-beta of 09.07.1995:
- A number of errors or inadequacies in the stats-evaluation removed
- With time-controlled buffering TOS2GEM hooks into the VBL (vertical
blanking) interrupt in order to be able to trigger a refresh of the
screen contents even when the running program has made no output for
some time (previously checks were made directly during output only
to see whether the time interval had been exceeded)
- New file 'T2G_INTR.PRG' to switch interrupt usage on and off, in
case of problems arising
- With active buffering TOS2GEM now also clears the buffer when the
visible area is moved
TOS2GEM of 21.06.1995:
- New cookie-element 'stats', in which the contents of several
internal variables can be stored when output redirection is
inactive, to be read out again later (see more about this in the
docs)
TOS2GEM-beta of 01.06.1995:
- During initialising of the text buffers setting Null bytes for the
line end was omitted (the source line seems to have got lost while
incorporating colour support...)
TOS2GEM-beta of 11.05.1995
- Serious error under MiNT removed: Due to an oversight in the source,
buffering took place under MiNT though the recognition of input
does not work there
- TOS2GEM can now also use time-controlled output buffering, where
refreshes take place at specified time intervals. This is achieved
by negative values in the cookie element 'buffer_output'
- The line redraw in colour mode was altered to a 'flicker-free'
method, which while being slower is far easier on the eye
TOS2GEM-beta of 07.04.1995
- TOS2GEM now also uses the colour sequences (which also includes
inversion!). The new cookie element 'color' sets the type of colour
support (compatible or VDI-conforming). More about this in the .HYP
docs, which have now been released
- Under SingleTOS, TOS2GEM now also uses a timer that triggers a
refresh after 500 ms at Bconstat calls during output buffering. This
permits TOS programs that interrogate the keyboard with Bconstat/
Bconin to work correctly (e.g. SYSOK). Under MagiC this is not
necessary as in that case the buffer is cleared anyway at each
Bconstat call
TOS2GEM of 24.03.1995
- As a bug report informed me that the 'TOS2GEM' cookie was still
present after a reset, TOS2GEM no also hooks into the reset vector
to clear the cookie pointer even when it only needs to extend the
cookie jar. I hope this has removed the problem (I could not
duplicate it)
- With output buffering active, a 'refresh' will also be executed now
when the screen contents (internally) have moved by the height of
the window. This prevents any output from being completely
'swallowed'
TOS2GEM-beta of 02.02.1995
- Now the recognition of keyboard input also works under MagiC, so
that buffering is also possible with that operating system.
Unfortunately it does not work with MiNT/MultiTOS (but there one
would use TOSWIN/MINIWIN in preference to TOS2GEM anyway, which also
applies to VT52 under MagiC, of course
- Buffering could be improved once more so that output now takes place
more than twice as fast as without buffering (in part this is faster
than the standard GEMDOS/BIOS output)
TOS2GEM-beta of 31.01.1995(?)
- With the new cookie element 'buffer_output' one can achieve
buffering of the output, which brings a marked speed increase.
Unfortunately this only works with SingleTOS, as TOS2GEM can only
recognise keyboard input correctly there (in such a case the buffer
has to be cleared to make it possible to see what is to be input)
TOS2GEM of 19.01.1995
- If TOS2GEM had to create or extend the cookie jar, this was lost at
the first activation of output redirection, as it lay in the same
memory region as the VDI array
TOS2GEM of 03.01.1995
- When reactivating output redirection with 'switch_output' the
y_offset was not adapted correctly. As this is a not inconsiderable
error, it is advisable to use at least this TOS2GEM version with
programs in which the size of the TOS2GEM window can be altered
(take note of the 'date' cookie element!)
- TOS2GEM.PRG now has the memory protection flag 'Global' once again
(I had forgotten this the last time because the Pure C linker
unfortunately cannot do this (at least not the one from PC 1.0))
- The header file has been improved: The constant RESERVED_SIZE now
exists for the 'reserved' field of the cookie, specifying the size
of the field
TOS2GEM of 12.12.1994:
- A small error crept into the calculation of two internal variables
which led to faulty scrolling in certain circumstances (if only the
first row of pixels of a line was visible)
- TOS2GEM example included into the 'large' archive so that one can
visualise what TOS2GEM actually does and how it works. I hadn't
thought of this originally (thanks to Dirk Klemmt, who pointed this
out to me)
TOS2GEM of 22.11.1994:
- First official version, unfortunately still without ST-Guide docs
(I wanted to 'release' TOS2GEM at the proTOS...)
- Under MagiC there is a workaround for the problem that an 'Fread'
call for the Console switches on the 'real' cursor and places the
one for TOS2GEM in completely the wrong place. The solution is a
little 'dirty' (write access to the negative LineA variables) but I
could find no other reliable method to accomplish this
- TOS2GEM now has the memory protection flag 'Global', so that no
problems should arise with this under MiNT/MultiTOS
-------------------------------------------------------------------------
English translation of this and associated files: Peter West, TransAction.
Reference in New Issue View Git Blame Copy Permalink