Archive Magazine 1996/ARCHIVE_96.iso/discs/utilities/utility_01/tweaked/!CustomVDU/!Help

Text File | 1992-04-06 | 15KB | 329 lines

NOTE: This Help-file has not been completed as yet. ThCh wants to put this on
      Cryton now, so it will at least be better than nothing. I haven't got
      the time to write much, so It'll be brief.


                       Help file for CustomVDU v. 1.24
                       -------------------------------

CustomVDU was written when I eventually got tired of seeing 14 mode-modules
being loaded at boot, not being able to center them by software, and making
myself a second VIDC clock. That's why it provides (almost) complete control
over the VIDC. Giving absolute freedom to control a rather versatile chip
like this one unfortunately makes it almost impossible to restrict the
possibilities to the useful ones. Therefore, it's very easy to obtain a lot
of useless results, and you're advised to read the last section of this text
(Hints) if you don't know video signals or the VIDC too well.

CustomVDU consists of an application and a module. To avoid confusion, I'll
violate my own rules and call the application '!CustomVDU' in this text.



                     First time installation of CustomVDU
                     ------------------------------------

When !CustomVDU starts, it will scan all modules for modes, so if you want
to collect all your mode-modules in CustomVDU, make sure to load them
beforehand.
  Run !CustomVDU. This will load the CustomVDU module and start the
application. You may see a brief hourglass, depending on the speed of your
machine :-)
  Click on the icon, and the main window will open.

...

                                'Modes' Window
                                --------------

  Initially the module will be empty, containing no mode-definitions.
  In the main window, the white modes are undefined, the grey/blue ones are
defined, and the darkgrey/green ones are both defined and will be included
in the module you're making.

  You've probably got several mode-modules already, and if you want to
include them, do the following:
  Run all of them.
  Start !CustomVDU, or if it's already running, select 'Update info' from
the main menu.
  Make sure that the info in 'Info' corresponds to your system.
  Click on all the modes you want to include, so they're green.
  Select 'Make module', and a save box will appear.
  OK or Return will save the module in your System:Modules directory,
otherwise drag the icon somewhere else.
  Now you can forget about all the mode-modules and simply load CustomVDU at
boot.

  Note1: If any of the modules were supposed to turn on an enhancer, you
must tell CustomVDU to do likewise by editing the appropriate mode and
selecting the proper vidc frequency (see below).
  Note2: If you're booting a module to control the enhancer already, this
will have to be killed. ('There Can Be Only One!')

----

  If you press menu over a defined mode, the 'Mode xxx' submenu can be
reached. Firstly 'Info':
  It's a rather large window containing (almost) all information about the
selected mode. Nothing can be edited here, but the window looks similar to
the editable one, so it may be a good idea first to look at the info about
some well-known modes before attempting to edit or make one yourself.
  The info is not self-explanatory unless you know about video signals, but
I'll make a complete explanation in this file, later.

  The 'Clone' submenu obviously makes a copy of the selected mode.
  'Default' is only available for modes 0-21 & 23-28 and will simply reset
the mode to the default design.
  'Easy setup' was meant to become a quick way of setting up a mode, but I
haven't implemented that yet.
  'Single Mdl' will make a module containing the selected mode only. This is
useful for including custom-modes into your own work etc., and later the
application will be able to extract the mode-parametres from these modules.


                               Editing a mode
                               --------------

  Clicking Adjust on a mode will open the edit-window. This window contains
all information about the mode, and may look a bit confusing at first. You'll
get used to it when you learn where the relevant info is. I'll take it from
the top.
 The 'Mode xxx' is the mode number and cannot be changed.
 The Pixel rate is the pixel rate i.e. the number of pixels per second. The
possible pixel rates are calculated when you enter the enhancer frequency in
the 'System Info' box. You can change it with the arrows.
  (I'm not going to write that 50 times from now on, so you might as well
hear it now: The arrows will increase and decrease the corresponding value
unless it would become illegal and/or damage your monitor, in which case it
will stay where it is.)
  The left part of the window is the physical info which is sent to the
VIDC.
  The right part are the logical values, which Risc-Os knows about.
  In most cases these parts will reflect similar values, but it's sometimes
useful for them to differ (e.g. double-pixel modes, character enlargement/
reduction etc.) Because of this, the 'Get from physical' button is very
important and often used. It will read the physical values, assume a lot of
things, and generate some logical ones. Because of the assumptions, it might
not be what you wanted, but usually it will.
  Below is the actual VIDC register values. Most of these corresponds to one
or more of the values above and both will change when you alter one. Use of
these obviously requires knowledge about the VIDC, I can't give you that now,
but here's a list of the abbreviations:

   HCR: Horizontal Cycle Reg.
  HSWR: Horizontal Sync Width Reg.
  HBSR: Horizontal Border Start Reg.
  HDSR: Horizontal Display Start Reg.
  HDER: Horizontal Display End Reg.
  HBER: Horizontal Border End Reg.
   HIR: Horizontal Interlace Reg.
   VCR: Vertical Cycle Reg.
  VSWR: Vertical Sync Width Reg.
  VBSR: Vertical Border Start Reg.
  VDSR: Vertical Display Start Reg.
  VDER: Vertical Display End Reg.
  VBER: Vertical Border End Reg.
    CR: Control Reg.
      DMA: DMA request delay
      Bpp: Bits per pixel
     Rate: Clock division selection

  The 'Store' button will store the current values and you must remember to
click here at least when you're finished, if you want to keep your edited
mode.
  The 'Undo' button is not a proper undo, it just recalls the last values
stored. I.e. only press Store, when you've got some reasonable values.
  The 'Instant effect' button requires a certain amount of knowlegde about
what you're doing, if you don't want to end up with an even worse result.
When this option is active, the display will change instantly when you alter
a value. You'll get a totally garbled display if you alter anything
important like the number of colours, but this feature is marvelous when it
comes to centering the display etc. So use it with care. If you should end
up with nothing usable on the screen, Escape will act like Undo, i.e. reset
to the last values Stored. So press 'Store' when you've got a readable
display only.
  Note1: The instant effect uses a temporary mode (127), so don't change
mode by any other means while it's active.
  Note2: The width and height buttons resize the display and border
symmetrically around the center with a step of 4 and 2 pixels. The vidc can
do one half of this, and to get those values, alter the vidc registers
yourself (HBSR,HDSR,HDER,HBER,VBSR,VDSR,VDER,VBER, see above). When the
border would have gone beneath the display or on top of the syncs, the value
won't change. This can be annoying if the display isn't centered yet, so if
it happens, use the vidc-registers again.

A few Hints...

  The monitor-protection is only relevant for some multisync monitors. I've
got a Philips CM8873, and it simply won't die. Most multisyncs should be
able to cope with Hsync widths of 2 ╡s and above, so this is the default
value. If you've got a normal monitor, a vga monitor or the CM8873 you can
simply turn it off, otherwise the 'trial and scream' method is not exactly
good, but the only one, as the critical values are almost never documented.

  Some astoundingly ugly displays can be generated from eg. mode 9 by
setting 'Xcoords/pixel' and 'Ycoords/pixel' to 1. Might even be useful for
some.

  When you're editing a mode, the following method is almost fool-proof
(it's how I do it :-)

  1. Click 'Store'.
  2. Repeat this:
  3.   Adjust one or two parametres.
  4.   Click 'Get from physical'
  5.   Click 'Instant effect' on.
  6.   Observe the incredible useless display.
  7.   Click 'Instant effect' off.
  8.   Click 'Store' if the display was readable.
  9. Until you're satisfied.

When you're getting used to how the program behaves you may be able to hit
the opposite button to the one that made the display fall over. Practice
makes perfect.

  If your otherwise perfect mode appears shifted one or more chars to the
left, try adjusting the DMA bits.

  If you want to use the desktop in a mode, ensure that the number of x-
pixels is a multiple of 8. If the CLI or other VDU4 activity is going to
work, the y-resolution must also be a multiple of 8.

--------------------------------------------------------------------------

Thanks to:
  ThCh for useful reports and comments of use (!)
  Brian (Brain) for additional tech hints and research.

--------------------------------------------------------------------------

This is PD, spread at will. I've got the copyright of the application and
the modules generated though you're free to include the modules in a product
of your own.

Please report any problems or comments through FidoNet to Thomas Olsson
(2:231/86.1).

  All this software is provided "as is"; Thomas Olsson makes no warranty,
express or implied, of the merchantability of this software or its fitness
for any  particular purpose. In no circumstances shall Thomas Olsson be
liable for any damage, loss of profits, or any indirect or consequential
loss arising out of the use of this software or inability to use this
software, even if Thomas Olsson has been advised of the possibility of such
loss.

--------------------------------------------------------------------------


                             Technical details
                             -----------------

The main program is written in Basic and is rather big, about 80K. In order
to reduce dload time, disk space, load time, program memory, variable space
and execution time, it's crunched. However, if you want to look at the
program, perhaps for reasons of customising it even further, the source will
be available from me, and probably soon from your nearest BBS too. I can't
spread the cruncher as it's copyrighted, so if you've made major improvements
to the program, please return it to me, and I'll release a new crunched
version.

The technical info about the application which is not given above is too
extensive to be included here, but the source is fairly readable (I think
:-), nice long variables and routine-names (again an advantage in crunching)
so if you usually feel good about reading other peoples programs, you'll
have a fair chance here.

The module can do a few other things as well as providing your favourite
modes. Commands and swi's follows; for further details you can find the
module-source in the application sourcecode.

*WimpMode <mode>    will set the wimpmode to <mode> by issuing the
                    SWI "Wimp_SetMode" with R0=<mode>
                    There seem to exist a convention regarding that whoever
                    is controlling the enhancer, has the responsibility to
                    provide a 'WimpMode' command, so here it is.

*CustomOff          will remove all mode-grabbing activity etc. It's almost
                    the same as killing the module, but you've still got
                    the WimpMode command, and you can always use:

*CustomOn           which will wake the module up, and start controlling the
                    vdu again.

Software interrupts.
SWI base is &C1500, which is chosen at random among the user-swi's.

-----------------------------
  SWI &C1500, "CV_WannaAlter"

  On entry:  R0 = Mode

  On exit:   R0 = -1 or 0  (Yes or No)
             R1 corrupted
             R3 = Pointer to VIDC list if Yes
             R4 = Pointer to ModeVars if Yes
             R5 = Enhancer status if Yes, otherwise corrupted

  This SWI is used to ask CustomVDU whether it is planning to modify the
  mode given on entry by any means. If it is, the parametres which will be
  given to the OS at the modechange service call are returned, along with
  the on/off flag for the enhancer (0=Off).
  If CustomVDU has been disabled using *CustomOff, this SWI will always
  return 'No' in R0.
  Note: The enhancer flag has nothing to do with the actual value stored in
  LatchB; the polarity and position of this bit is constant, and set at
  assembly time from the 'Info' window.

---------------------------
  SWI &C1501, "CV_TestMode"

  On entry: R0 = Mode to react upon (or -1 to disable testmode)
            R1 = Pointer to VIDC list to use
            R2 = Pointer to ModeVar list to use
            R3 = Enhancer status to use

  On exit:  All registers preserved

  This SWI is used to (temporarily) set up a mode, usually for test
  purposes. It is used by !CustomVDU when 'Instant effect' has been
  activated, but can also be used by other programs as an easy way of
  setting up a non-standard mode. The mode number can be anything from 0 to
  127, or -1 to stop grabbing the mode.
  The lists pointed to by R1 and R2 and the flag in R3 is copied into
  CustomVDU's workspace, and thus need not to be preserved until the
  modechange occurs.
  No checks are made on the values in the lists, so you must be careful.
  A useful way of doing this is by issuing "CV_WannaAlter" first to get a
  proper list, and then modifying the appropriate values only.

---------------------------
  SWI &C1502, "CV_Enhancer"

  On entry: R0 = Status (-1=On, 0=Off)

  On exit:  All registers preserved

  This SWI will 'manually' turn the enhancer on or off.

--------------------------
  SWI &C1503, "CV_SysInfo"

  On entry: R0-R5 = Whatever values you want thrown away

  On exit:  R0 = Pointer to 0-terminated monitor name
            R1 = Protection level in ╡s
            R2 = Enhancer presence (-1 or 0)
            R3 = Enhancer frequency in MHz, fixed point before bit 16
            R4 = LatchB mask
            R5 = Bit polarity for turning the enchancer on

  This SWI returns some info about the system for which the module was
  generated. It is exactly the same as given in the 'Info' window before
  assembly. The number in R3 is fixed point, so if the frequency for example
  is 33.5 MHz, R3 would become 33.5*&10000 or &00218000.
  The enhancer mask is 1 in all bits except the one that controls the
  enhancer.
  The enhancer bit polarity is a sign (-1 or 0), if it's -1, the enhancer is
  turned on by writing a 1 in the appropriate bit in LatchB.