README

                                  Cleancode


This archive contains example source code for using the Atari hardware using
all possible systems functions (and also hardware access, not recommended for
compatibility with future systems).

You need gcc, binutils, mintlib, gemlib (recent versions recommended).
To compile, just 'configure ; make ; make install'.

For .ttp and .gtp programs, the text output can be redirected to the file
"stdout.txt", by giving the "-file" parameter on the command-line.

See the file 'AUTHORS' for a list of drivers and documentations, used to
develop these test programs.


1 Keyboard
----------

Note: if you run kbde.tos, kbgd.tos or kbbi.tos from a terminal, you must set
it to a VT52 compatible type (TERM environment variable set to tw52, vt52 or
st52, see your termcap file),or most special keys will be prefixed by a ESC (27)
character, hence quitting the program.


1.1 AES
-------

Availability: All systems
Demo program: kbae.prg
Values read:  Ascii code, scancode, special keys state of pressed keys.

1.2 /dev/console
----------------

Availability: Multitasking OS
Demo program: kbde.tos
Values read:  Ascii code of pressed keys.

1.3 GEMDOS
----------

Availability: All systems
Demo program: kbgd.tos
Values read:  Ascii code, scancode, special keys state of pressed keys.

1.4 BIOS
--------

Availability: All systems
Demo program: kbbi.tos
Values read:  Ascii code, scancode, special keys state of pressed keys.

1.5 IKBD hardware access
------------------------

Availability: Atari machines, Medusa, Hades: yes
              Milan: no
Demo program: kbikin.tos (interrupt mode)
Demo program: kbikpo.tos (polling mode)
Values read:  Scancode, release/press of keys.



2 Mouse
-------


2.1 AES
-------

Availability: All systems
Demo program: moaegr.prg (graf_mkstate)
Demo program: moaeev.prg (evnt_multi)
Values read:  Absolute mouse position, release/press of buttons

2.2 VDI
-------

Availability: All systems
Demo program: movd.tos
Values read:  Absolute mouse position, release/press of buttons

2.3 /dev/mouse
--------------

Availability: Multitasking OS
Demo program: mode.tos
Values read:  Relative mouse motion, release/press of buttons

2.4 XBIOS
---------

Availability: All systems
Demo program: moxb.tos
Values read:  Relative mouse motion, release/press of buttons

2.5 IKBD hardware access
------------------------

Availability: Atari machines, Medusa, Hades: yes
              Milan: no
Demo program: moikin.tos (interrupt mode)
Values read:  Relative mouse motion, release/press of buttons



3 Joystick
----------


3.1 XBIOS
---------

Availability: All systems
Demo program: jsxb.tos
Values read:  Axis change, release/press of fire

3.2 IKBD hardware access
------------------------

Availability: Atari machines, Medusa, Hades: yes
              Milan: no
Demo program: jsikin.tos (interrupt mode)
Values read:  Axis change, release/press of fire



4 Joypads, lightpen, analog paddles
-----------------------------------


4.1 Hardware access
-------------------

This program displays joysticks, joypads, lightpen and paddles value changes,
when plugged on the enhanced ports.

Availability: STE, Falcon: yes
              Other machines: no
Demo program: jpha.tos
Values read:  Axis change, release/press of buttons



5 Video
-------


5.1 AES
-------

This program displays VDI information about current video mode. Then it tries
to draw Red, Green and Blue bars using 3 different methods:
- On the left: direct write to video RAM (if available)
- On the middle: write in a temporary buffer, then vro_cpyfm() to screen.
- On the right: bars drawn using the v_bar() function.
This work is done in a window, any resolution, any bits per pixel.

Availability: All systems
Demo program: viae.gtp
Values read:  Screen size, bit depth
              Pixel organization (with EdDI driver)
              Screen address, pitch (with EdDI 1.1 driver)

5.2 VDI
-------

This program displays VDI information about current video mode. Then it tries
to draw Red, Green and Blue bars using 3 different methods:
- On the left: direct write to video RAM (if available)
- On the middle: write in a temporary buffer, then vro_cpyfm() to screen.
- On the right: bars drawn using the v_bar() function.
This work is done in fullscreen, any resolution, any bits per pixel.

Availability: All systems
Demo program: vivd.ttp
Values read:  Screen size, bit depth
              Pixel organization (with EdDI driver)
              Screen address, pitch (with EdDI 1.1 driver)

5.3 XBIOS
---------

This program displays the list of available video modes, for each possible
bits per pixel value. Supported screen enhancers are these ones:
- Medusa, Hades: Imagine/Nova
- Milan:         Milan MVDI
- Falcon:        CentScreen, Videl Inside, BlowUp, Imagine/Nova,
                 ScreenBlaster 2, ScreenBlaster 3, Videlity
- Mega STE, TT:  Imagine/Nova
- Mega ST:       Imagine/Nova

Availability: Atari machines: yes
              Milan: need MVDI driver
Demo program: vixb.ttp
Values read:  List available video modes, depend on the current monitor.



6 Audio (PCM)
-------------


6.1 XBIOS
---------

To use Xbios functions, you may need one of these drivers:
STFA:        http://removers.atari.org/softs/stfa.html
GSXB:        http://assemsoft.atari.org/gsxb/
X-Sound:     http://www.uni-ulm.de/~s_thuth/atari/xsound_e.html
Magic Sound: http://perso.wanadoo.fr/didierm/
MacSound:    http://jf.omnis.ch/software/tos/

Availability: Falcon: yes
              Other machines: need one of previously listed XBIOS drivers
Demo program: auxb.tos
Values read:  List of available replay formats (frequency, channels, bits)

6.2 Hardware access
-------------------

(Todo)

Availability: STE, Mega STE, TT, Falcon: yes
              Other machines: no
Demo program: auha.tos
Values read:  List of available replay formats (frequency, channels, bits)



7 CD-ROM
--------


7.1 /dev/cdrom
--------------

Availability: Multitasking OS: need CD-ROM .xdd driver
Demo program: cdmi.tos
  The default device is '/dev/cdrom'. To change this, specify the device on
  the command line with '-device /dev/mydevice' parameter.
Values read:  List of tracks if CD present.

7.2 Metados
-----------

Availability: All systems: need Metados + CD-ROM driver
Demo program: cdme.ttp
Values read:  List of Metados drives, list of tracks if CD present.



8 Hard disk
-----------


8.1 XHDI
--------

Availability: All systems: need XHDI-aware harddisk driver
Demo program: dixh.ttp
Values read:  List of supported drives, partitions infos, device infos



9 Bus
-----


9.1 PCIBios/XPCI
----------------

When you run the test program, the file 'pci.ids' must be in the current path,
so the program can find it. It contains the names of devices.

Availability: All systems: need PCIBios or XPCI driver
Demo program: bupc.ttp
Values read:  List of PCI devices, and some infos

Use -dumpbios parameter to dump the ROMs of the cards.

9.2 SCSIdrv
-----------

Availability: All systems: need SCSIDRV driver
Demo program: busc.ttp
Values read:  List of devices, and some infos



10 Hardware
-----------

10.1 CPU/Custom chips
---------------------

Availability: All systems
Demo program: hw.ttp
Values read:  CPU/MMU/FPU type. List of custom chips.

10.2 RSVF/HSModem serial ports
------------------------------

Availability: All systems with HSModem installed
Demo program: hwrs.ttp
Values read:  List of serial ports.