@database
@node main "Matrix Documentation"

@{b}Matrix@{ub}

version 1.6
3 february 2001

Chapters modified since version 1.5 documentation are marked [new].

Menu :

 @{" LICENCE " link licence} [new]

 @{" Description   " link descr}
 @{" Requirements  " link config}
 @{" Installation  " link instal}
 @{" Settings      " link reglage} [new]
 @{" Usage         " link usage} [new]
 @{" Software used " link zinfos} [new]
 @{" Author        " link auteur}
 @{" History       " link histoire} [new]

 @{" DPMS for ECS/AGA ? " link ecsdpms} Help! [new]

Off topic :

 @{" Too many crashes ? " link enforcer} Try this... [new]

@endnode

=====================================================================

@node licence "Matrix Licence"

In  this  licence, the terms "the software" or "this software" refer to all
the  files  listed  in  the  "Distribution"  section, with the exception of
"GetModeID" and "GetModeID.guide".

This licence applies to "the software".  :)

You are not allowed to install, use in any way, or distribute this software
if  you  do not accept the terms of this licence.  If you do not agree with
this  licence,  please  delete  all the files to which this licence applies
immediatly.

@{b}Copyright@{ub} :

Unless  otherwise  noted,  all  the  files  were  made by and are copyright
©2000-2001 Olivier Fabre.

One  exception  is  that the graphics (included in the "Matrix" executable)
were  not  entirely  made  by  me.  The major part of them come from a BeOS
screen  blanker,  whose  author  took  them from a Linux version, and their
legal status is unknown to me.

Another exception is the GetModeID program, written by Magnus Holmgren, and
its  documentation,  whose  main  part  was taken from the documentation of
Visage.  This licence does not apply to these two files.

You  might disassemble the program if you think you'll have fun doing this,
but  you  are not allowed to release any program containing a large portion
of  my code without my written consent.  Anyway, I will send you the source
code of the program if you ask me (for educationnal purposes or for private
use only, unless you get my written consent to use it in another way).

@{b}Distribution@{ub} :

This  program  is  released as freeware.  You may copy it freely as long as
all the following files are included in their original, unmodified form :

- Matrix
- Matrix.info
- Matrix_english.guide
- Matrix_english.guide.info

And  preferably the following files too, only in their original, unmodified
form :

- Matrix_français.guide
- Matrix_français.guide.info
- GetModeID
- GetModeID.guide

This software must not be sold.

@{b}Disclaimer@{ub} :

This software is provided "as is", without any warranty of any kind.  There
might  be  bugs in the program; there might be errors in the documentation;
the  default  settings might blow your monitor, but then it's your fault if
you  do  not  change them.  In no event shall the author be held liable for
any  damage related to the use of this program, of any file included in the
distribution,   or  of  any  information  included  in  the  documentation.
Especially if you used DPMS on a monitor that did not support it...

Thank you.

@endnode

=====================================================================

@node descr "Description"

Matrix is a screen blanker with the following features:

- system friendly (tested with Enforcer, WipeOut and PatchWork)
- works on OCS/ECS/AGA and graphic cards
- handles DPMS


What is DPMS ?

This  is  a  power  consumption  reduction  system supported by most recent
monitors.

There are three levels of power consumption reduction:

- Standby (light reduction)
- Suspend (greater reduction)
- Off     (maximum reduction)

On my monitor (AcerView 77c), the normal power consumption is 110 W.
In DPMS_StandBy it falls to 15 W.
In DPMS_Suspend and DPMS_Off it is only 5 W.

Once  in  DPMS, the monitor needs some time to go back to a normal display;
so  it's  better  not  to  set a too short time for the DPMS starting.  The
display  will take longer to come back when the power reduction is greater;
hence the point in having several levels of DPMS.

@endnode

=====================================================================

@node config "Requirements"

Matrix requires :

- @{b}Kickstart 3.1@{ub} or better

- A @{b}68020@{ub} or better

- Only @{b}for DPMS : CGX or P96@{ub} (and a monitor that handles it !)

@endnode

=====================================================================

@node instal "Installation"

Simply drag Matrix into the WBStartup drawer to install it.

Then,  if  you  wish,  you  can  modify the tooltypes to change the default
settings.  (select its icon then the "Icons->Information" menu).

Matrix  can  also  be run in the user-startup.  You must then use the "Run"
command to let the Shell execution go on :

Run >NIL: Matrix

@endnode

=====================================================================

@node reglage "Settings"

Arguments are taken from the ToolTypes or the command line.  They are:

@{b}TimeOut@{ub}
    Inactivity  time in seconds before the blanker starts.  A TimeOut of -1
disactivates the "Matrix" animation.
    Min     :     4 or -1
    Max     : 32763 (9h 6min 3s)
    Default :   240 (4min)

Note :  Yes, the animation stops when DPMS or DMA_OFF starts :)

@{b}DMA_Off@{ub}
    Inactivity  time in seconds before stopping Copper, Sprite and Bitplane
DMA.   The result is a black screen and a slight speed increase to CHIP RAM
accesses.   This  option  hasn't  been  tested  a  lot,  and  will stop the
animation  on  any CGX screen without displaying a black screen or going to
DPMS.
    Min     :     4 or -1
    Max     : 32764
    Default :    -1 (no DMA stop)

@{b}DPMS_StandBy@{ub}
    Inactivity time in seconds before "Standby" DPMS.
    Min     :     4 or -1
    Max     : 32765
    Default :    -1 (no DPMS)

@{b}DPMS_Suspend@{ub}
    Inactivity time in seconds before "Suspend" DPMS.
    Min     :     4 or -1
    Max     : 32766
    Default :    -1 (no DPMS)

@{b}DPMS_Off@{ub}
    Inactivity time in seconds before "PowerOff" DPMS.
    Min     :     4 or -1
    Max     : 32767
    Default :    -1 (no DPMS)

                                @{b}* NOTE WELL *@{ub}

Do  *NOT*  use DPMS if the manual of your monitor doesn't explicitly states
that it supports DPMS.  That is to say :  always let a '(' at the beginning
of the tooltype lines containing "DPMS".

Moreover, Picasso96 or Cybergraphics must be installed for DPMS to function
(but I already said this).

New  for  version  1.6  :   you  also have to use the "DPMS" tooltype(s) to
activate DPMS (see below).

                             @{b}* END OF NOTE WELL *@{ub}

@{b}HotKey_Blank@{ub}
@{b}HotKey_DMA@{ub}
@{b}HotKey_StandBy@{ub}
@{b}HotKey_Suspend@{ub}
@{b}HotKey_PowerOff@{ub}
    These five tooltypes let you define hotkeys (key combinations) to start
each  mode  of the blanker.  Note that if the timeout of a mode is equal to
-1, it won't be triggered anyway.
    An hotkey description is of the form "[<qualifier(s)>] <key>".

Examples :
    HotKey_StandBy=lshift esc
    HotKey_PowerOff=ctrl alt o

Here are all the (usefull) qualifiers :
    lshift
    rshift
    shift      (lshift or rshift)
    capslock
    caps       (shift or capslock)
    control
    lalt
    ralt
    alt        (lalt or ralt)
    lcommand   (lamiga)
    rcommand   (ramiga)
    numericpad

And the "special" keys :
    space, backspace, tab, enter, return, esc, del, help,
    up, down, right, left, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10.

@{b}NoMouseCheck@{ub}
    Prevents  a  mouse move from stopping the blanking.  Can be usefull for
very sensitive mice.
    From  version  1.6 onwards, you can give a value to this tooltype.  For
example:   NoMouseCheck=10.   This  means  that  the  mouse  move  won't be
recognised unless it is of at least 10 pixels.
    Min     :     0 (same as 1)
    Max     : 32767 (same as "NoMouseCheck" without value)
    Default :     2 (if the "NoMouseCheck" tooltype is not mentionned)

@{b}NoJoyCheck@{ub}
    This  tooltype  tells  Matrix  not to check for movements in Gameport 1
(that  can  be  a  joystick,  a joypad, a mouse or something else).  Can be
usefull  for  Mroocheck  owners  having  set  the  AGA  display to 31kHz...
(aaargh..   mroocheck.driver  sends  "ghost"  events  that  prevent  screen
blankers   and  games  using  ReadJoyPort()  of  lowlevel.library  to  work
correctly...)

@{b}PassKeyPress@{ub}
    With  this  tooltype,  a  key press while the blanker is active will be
passed  to  the  application  that  was  active before the blanker started.
Without  it,  any  key  press  will be "swallowed" by the blanker.  In both
cases, the blanker will stop, of course.
    This option is currently flawed :
- the "Screen activation" function of MCP prevents it from working.
- the mouse pointer stays visible.


The other ToolTypes deal with graphical aspect of the blanker:

@{b}Delay@{ub} (formerly called "Speed")
    Time to wait between two frames of animation, in 50th of a second.
    Min     :  1 (max 50 fps)
    Max     : 50 (1 fps)
    Default :  2 (max 25 fps)

@{b}Speed@{ub}
    Characters scrolling speed.
    Min     :    1 (0.01 character per frame)
    Max     : 5000 (50 characters per frame)
    Default :  100 (1 caracter per frame)

@{b}SpeedChange@{ub}
    Possible speed variation, as a percentage of the default speed.
    Min     :    0 (every "threads" fall at the same speed)
    Max     : 1000 (up to 11 times faster or slower)
    Default :   25 (up to 1.25 times faster or slower)

@{b}Density@{ub}
    Percentage of screen filling.
    Min     :   0
    Max     : 100
    Default :  40

@{b}CharWidth@{ub}/@{b}CharHeight@{ub}
    Zoom percentage of the characters.
    Min     :   4 ( 1x1 pixel)
    Max     : 100 (27x31 pixels)
    Default :  50 (13x15 pixels)

@{b}Light@{ub}
    Light percentage of the characters.
    Min     :   0 (everything is black)
    Max     : 200 ("overexposed")
    Default : 100 (normal)

@{b}UpsideDown@{ub}
    Makes characters go up if specified.

@{b}ThreadsLength@{ub}
    Average length of the characters trails.
    Min     :     1
    Max     : 32767
    Default :    16

@{b}ModeID@{ub}
    This  tooltype  lets  you  choose  the mode of the screen opened by the
blanker.   If  no ModeID is given, the blanker will use the same screenmode
as the Workbench.
    The  ModeID is a number that you can type in decimal, or in hexadecimal
(preceding it with "0x").  For example:  ModeID=123456 or ModeID=0x5100ABCD
(do not use these values, they do not mean anything).
    To find the ModeID corresponding to the desired resolution, you can use
the   program   "@{"GetModeID" link "GetModeID.guide/MAIN"}"  (from  the  Visage  archive),  which  is  now
distributed  with  Matrix,  or  look  in  the "ScreenMode" section of Scout
(Visage and Scout are available on Aminet).

    Since  version  1.6, Matrix can handle several screens at the same time
(upto 5).  As a consequence, there are 4 other ModeID tooltypes :  @{b}ModeID2@{ub},
@{b}ModeID3@{ub}, @{b}ModeID4@{ub} and @{b}ModeID5@{ub}.
    For example, if the AGA output of your Amiga is plugged on a television
set,  and your graphic card to a monitor, you can give a PAL mode to ModeID
and a CGX one to ModeID2.
    You can always omit giving a value to ModeID (which will lead Matrix to
open  on the same screen as the Workbench), while at the same time giving a
value to ModeID2.

@{b}DPMS@{ub}
    Following the addition of multi-screen support, it has become necessary
to  be  able to specify which monitors did support DPMS, independently.  So
there   are   now   5  new  tooltypes  :  @{b}DPMS@{ub},  @{b}DPMS2@{ub},  @{b}DPMS3@{ub},  @{b}DPMS4@{ub}  and
@{b}DPMS5@{ub}.
    With  the  same example as above, if ModeID contains a PAL mode opening
on  a  television set, you shouldn't activate DPMS on that screen.  So, you
will not specify the tooltype "DPMS".  On the contrary, if ModeID2 contains
a CGX mode opening on an energy saving capable monitor, you may specify the
tooltype "DPMS2".

    So  as  to  be really clear, "to not specify the tooltype 'DPMS'" means
that  no  line  in  the  tooltypes  list  contains  exactly the word "DPMS"
(without the quotes) and nothing more, or, if Matrix is run from the Shell,
that you did not type this word on the command line.
    The  common  way  to  disactivate  a  tooltype  is  to surround it with
parentheses, like this :  "(DPMS)".


The standard "@{b}CX_PRIORITY@{ub}" and "@{b}STARTPRI@{ub}" ToolTypes are also here.  You can
find their description in your Amiga manual

@endnode

=====================================================================

@node usage "Usage"

To run Matrix, double-click on its icon or run it in a Shell.

If  you  run Matrix from a Shell, the parameters are taken from the command
line.  For example :

Run >NIL: Matrix timeout=150 delay=1

(case doesn't matter)


The blanker starts when you haven't :
- pressed a key
- moved the mouse or pressed one of its buttons
- inserted a disk
since a specified time.


If  you click on "Hide" or "Show" in Exchange, this will start the blanker.
To  stop  it,  then, mouse moves are not recognised, so you need to press a
key, a mouse button, or insert a disk.


To stop the program, three methods :

1 - run it another time
2 - within Exchange, select it in the list and clic on "Remove"
3 - send it a CTRL-C, for example with the Break command:

    break `status com=matrix`

(this example won't work if Matrix was run from the WB)



Note A:
    Any  error  message will be displayed only when Matrix was run from the
Shell  (without the >NIL:  redirection, of course).  So, if something seems
to  go  wrong, first try to run it in a Shell to see which error message is
displayed...

Note B:
    For  now,  Matrix  exits if it can't open its screen when it is time to
blank  (it  can  happen when almost all the RAM is used or if the ModeID is
incorrect).  It will first try to open a much smaller screen, though.

@endnode

=====================================================================

@node zinfos "Software used"

 @{b}VBCC@{ub} (C compiler, by Volker Barthelmann and Frank Wille)

 @{b}PhxAss@{ub} (assembler/linker, by Frank Wille)

 @{b}dmake@{ub} (DCC's "make", by Matt Dilon)

 @{b}CygnusEd 4.20@{ub} (text editor, by Bruce Dawson and Olaf Barthel)

 @{b}ArtPro@{ub} (pictures and palettes converter, by Frank Pagels - thanks
  for the update ! :))

 @{b}KingCON 1.4@{ub} (by David Larsson and a little bit Mikolaj Calusinski)

 @{b}Enforcer@{ub} (by Mike Sinz)

 @{b}Segtracker@{ub} (by Mike Sinz)

 @{b}WipeOut@{ub} (by Olaf Barthel)

 @{b}Sashimi@{ub} (by Olaf Barthel)

 @{b}PatchWork@{ub} (by Richard Koerber)

Thanks to all these authors for their excellent work :)

@endnode

=====================================================================

@node auteur "L'auteur, c'est moi"

 Olivier Fabre
 off@free.fr
 StAn_ / #artbas / IRCnet
 http://off.free.fr


While  I'm  about  it,  so as to fill this empty space, I would like to say
"thank  you"  to  everyone who mailed me about Matrix, sent me bug reports,
ideas or remarks :)

@endnode

=====================================================================

@node histoire "History"

History (backwards) :


### v1.6 (03.02.2001)

·  Graphics  are  now  in  16  colors  instead  of  64.   The difference is
practically  invisible, and this will enable OCS/ECS users to choose almost
any screenmode.  [Steven Norburn]

·  It  is  now  possible  not to "swallow" key presses while the blanker is
active.  [Feuille]

·  Added  minimum  mouse movement before detection.  Default value is now 2
pixels instead of 1.  [Pascal Marcelin]

· Variable and possibly faster animation speed (adjustable).  [AdamCa]
  Attention  :   the "Speed" tooltype has been renamed to "Delay" and there
is now another "Speed" tooltype.

· Ability to blank several screens simultaneously.  [AdamCa]

·   Joystick   check  in  Gameport  1  (optionally;  might  screw  up  with
mroocheck.driver, which sux :( ).  [AdamCa]

· The "Matrix" animation can be disabled by choosing TimeOut=-1.

· Ability to cut Copper, Sprite and BitPlane DMA (avoid if using CGX/P96).

·  Added  hotkeys  (to  activate the blanker).  [Thanks to SIL for the beta
version bug report :)]

· Other minor fixes and modifications.


### 25 october 2k, v1.5

· Bugfix : the blanker sometimes wouldn't start blanking...

· Compiled with VBCC 0.7 and v44 includes (yes, I was using older stuff..).
[Thanks to Henes for making me realise this ;)]

· Doesn't display an error message anymore when a second instance of Matrix
is run in order to kill the first one (Matrix must be run from the Shell in
order to see error messages).

·  When  the  Matrix animation is not playing, the blanker waits one second
between  each  events  check  instead of "Speed" * 1/50s. So it takes a bit
less CPU time.

· "UpsideDown" ToolType does not need a "=YES" anymore. [Thomas Chen]

· CharWidth/Height zoom default is now 50%. [Thomas Chen]

· Now also checks for mouse buttons when in "test" mode. [Thomas Chen]

· Added more error messages.

·  Added  BMF_DISPLAYABLE  flag for the source BitMap, so that graphics are
stored in VRAM with CGX too. [Henes]


### 5 october 2k, v1.4

·  Added the "NoMouseCheck" option which prevents mouse moves from stopping
the blanking.  [request by Zapek].


### 1 october 2k, v1.3

·  The program now asks for graphics.library v40 now, instead of v39, since
it uses WriteChunkyPixels() !  (before it would have crashed when run under
OS3.0 I guess..  stupid me !)

· Minor improvement in the blanking start via Exchange.

· AmigaGuide doc.


### 08 september 2k, v1.2

· Clicking on "Show" or "Hide" in Exchange now starts the blanker, which is
handy  for  trying  new  ToolTypes settings.  To stop blanking, you have to
press a key (mouse moves aren't taken into account).  [idea by Tex :)]


### 05 september 2k, v1.1

·  Correction  of  the  problem  which  could lead to a green palette after
stopping the DPMS on some systems. [reported by SIL and ATOMIK]

· Shouldn't start blanking when the time is (re)set.


### 03 september 2k, v1.0

· Added DPMS.


### early 2000...

· Working version.


### 25 december 1999

· Development started.


@endnode

=====================================================================

@node ecsdpms "What about DPMS for ECS..."

Firstly, DPMS on OCS is impossible.

It  is possible on ECS and AGA, since the ECS chipset can control the video
syncs, and MCP does it...

I  know  that  to  start  energy  saving  modes, the video syncs have to be
stopped/started :

             horiz sync    vert sync
Power ON  :     ON            ON
StandBy   :     OFF           ON
Suspend   :     ON            OFF
Power OFF :     OFF           OFF

I  have managed to code something that will put the monitor into Suspend or
Power OFF mode (I can't see the difference with my monitor), but the way to
disable correctly horiz and/or vertical sync is not very clear to me at the
moment.

Another  big  problem  is  that I am simply not able to restore the display
afterwards...   :-}  This  implies finding the original syncs and restoring
the  ECS  registers  to  their original values..  One of the problems being
that  these  registers  can't  be  read,  so I can't store the value before
changing them.  The registers are :  BEAMCON0, HSSTRT and HSSTOP, and maybe
VSSTRT and VSSTOP...

So,  if you can help me on this matter, please do not hesitate to mail me !
:-]

@endnode

=====================================================================

@node enforcer "Kill them all!"

Fed up of crashes with an unknown source ?

There  is  something that can help you find problems :  installing Enforcer
(and/or other similar programs) in your startup-sequence.

I'm using :

· SegTracker
· Enforcer
· WipeOut (not permanently because it slows down the system)
· PatchWork
· BlowUp
· Sashimi (displays the output of the other programs)

But there are also :

· CyberGuard (similar to Enforcer, for phase5 boards AFAIK)
·  Mungwall  (similar  to WipeOut, older, but usable with GAR and eats less
CPU time)
· GuardianAngelRemix (to be used with Enforcer and Mungwall)
· TNT (similar to BlowUp)
· MuForce (similar to Enforcer, needs MMU library)
· MuGuardianAngel (needs MMU library)


These  programs are meant to be used only by programmers, but since many of
them  release  bugged  software,  it has become usefull for the end user to
install them.  You can find them on the Amiga Developer CD or on Aminet.

Most of the time a MMU is required, but not for all of these programs.  For
example, you can still use BlowUp + WipeOut.


These programs detect illegal operations :

· memory read/write in an illegal location (Enforcer/Cyberguard)
· read/write in unallocated memory/out of bounds
  (Mungwall/WipeOut/GuardianAngelRemix)
· bad parameters passed to an OS function (PatchWork)


The  aim  here isn't to continue using bad programs without crashing; it is
to  see  rapidly  which  software behaves incorrectly.  Using some of these
tools might very well make bad programs crash faster !

So,  when  you  see  that a program makes Enforcer hits (or PatchWork hits,
etc.),  you  can  stop using it to prevent crashes/problems, and inform the
author, giving him the hits you got, so that he can debug his program !
Don't  forget  to  tell  him about your hardware and software configuration
too, and the actions you did to find this bug.


To  give you an idea of how to use these tools, here are the relevant parts
of my startup-sequence:

  [...ROM and OS3.5 modules remap...]

  SetPatch44 QUIET NOROMUPDATE
  @{b}Run >NIL: Apps:Programmation/Tools/SegTracker@{ub}
  Patchs/MCP/Tools/PatchControl

  [...some patches...]

  @{b}APPS:Programmation/Tools/Sashimi >NIL: RECOVER=RAM:Sashimi.out
  If EXISTS RAM:Sashimi.out
     Echo "*N- END OF RECOVERY -*N" >>RAM:Sashimi.out
  EndIf@{ub}
  TestLMB
  If WARN
     @{b}Run <>NIL: WipeOut NAMETAG PRESIZE=128 POSTSIZE=64 NOCONSISTENCECHECK AREGCHECK STACKCHECK@{ub}
  EndIf
  @{b}RUN <>NIL: Enforcer DATESTAMP LED=0 RAWIO BUFFERSIZE=32000 AREGCHECK STACKCHECK STACKLINES=2
  Run <>NIL: Sashimi >>RAM:Sashimi.out BUFK=128 NOPROMPT
  RUN <>NIL: PatchWork NOPERMIT MINOS=40 LEVEL=3 AREGCHECK STACKCHECK STACKLINES=2
  Run <>NIL: BlowUp STACKCHECK AREGCHECK NOBANNER@{ub}
  StackAttack MIN=8000 ADD=4000

  ;Version >NIL:
  ;AddBuffers >NIL: DF0: 15
  FailAt 21

  [...]

  LoadWB

  [...]

  @{b}If EXISTS RAM:Sashimi.out
     Type RAM:Sashimi.out >"CON:66/16/564/84/Sashimi hits during startup/ALT66/16/564/320/AUTO/CLOSE/WAIT/INACTIVE"
  EndIf
  Sashimi >NIL: OFF
  Run >NIL: Sashimi CONSOLE BUFK=64 NOPROMPT ASKEXIT ASKSAVE WINDOW="CON:466/16/164/84/Sashimi [Ctrl]+E=Empty [Ctrl]+F=File [Ctrl]+D=Reset console/ALT66/16/564/320/AUTO/CLOSE/WAIT/INACTIVE"@{ub}

  EndCLI >NIL:


This startup-sequence lets me :

-  know  which  programs  make hits (thanks to SegTracker which is launched
very early), including programs run in the startup-sequence.

-  display  hits  that  occured  during the startup-sequence execution, but
after  the  WB screen has opened (because otherwise it would prevent IPrefs
from changing the screen prefs..).

- get hits that lead to a crash, thanks to the RECOVER option of Sashimi.


Don't  forget  to  read these programs documentations with care, though, if
you don't want to be in trouble !  Including MMU.library doc if you want to
use any of the Mu#?  tools...


PatchWork  thinks some things are dangerous while they don't seem to be so.
Many   programs   seem   to  bend  the  autodocs  rules  without  immediate
consequences...  So,  if  you  don't  want to be annoyed with numerous hits
(notably while using MUI apps), don't let PatchWork run permanently.

On  the other hand, I strongly recommend it for testing your own programs !
(along with Enforcer + WipeOut or Enforcer + Mungwall + GuardianAngelRemix,
StackSnoop, EatMem or Memoration...)


Hoping to see fewer bugged software in the future... ;)

@endnode