 Amiga Developer Conference Demos by Jim Mackraz, April, 1988

   Copyright (c) 1988, I and I Computing, and Commodore-Amiga, Inc.

  Executables based on this information may be used in software
  for Commodore Amiga computers.  All other rights reserved.
 
  This information is provided "as is"; no warranties are made.
  All use is at your own risk, and no liability or responsibility is assumed.


These directories contain source code and executable files for example
and demonstration programs to accompany several lectures at the 1988 Amiga
Developers' Conference.  This file describes the programs and the source
files individually.

Several techniques for "taking over from Intuition" are presented in the
DView example.  These include shutting off input, turning it on in a
synchronized way for a seamless transition into menus, and stealing sprite
zero.  These are just some of the first main steps to using Intuition
resources in a compatible way.

Please refer to the papers accompanying the talks for much more information
on each subject.

All of these programs are to be run from the CLI and  accept command-line
arguments parsed by a routine of my own named 'getargs().'  They typically
spit out an argument usage summary when you say "foo -?" or "foo -z" (or any
other unused argument).

All programs are developed under small-model Aztec C.  Several situations
require special handling for this model:
   - Aztec register conventions don't match the system code
   - small-model requires base-register A4 to be set up
   - input handlers receive parameters in registers, which need to be
     pushed onto the stack for use by C routines.

It turns out that I save and restore too many registers at times.  You can
do better in your programs.  All program files were created using tabstops
set every 4 character positions.

I'd like to acknowledge the assistance, suggestions, and motivation provided
by the Commodore-Amiga system software and technical support teams. 
Additionally, many ideas from BIX and Usenet found their way into the
programs.  These programs by no means represent the final word of knowledge
on any of the subjects. I hope the active developers' community can pick up
the ball from here and post corrections, enhancements, and discussions about
these techniques.

Most of all, I hope these examples help flatten out the learning curve for
programmers wanting to get at the guts of the the Amiga, and that we find,
as I suspect, that the wildest Amiga software is yet to come.

One last point:  As usual, I use the Workbench screen as my guinea pig.
No wild techniques should be applied to the Workbench in a real application. 
There are things coming which these programs will blow up, so use these
demos as examples only, for routines working on custom screens and bitmaps.

--------

UCop
   A demonstration of a couple of user copper list techniques.
   Not so interesting, but quite useful, since the documentation
   on user copper lists is sketchy, and the CINIT() code is kind
   of broken.

   A command-line option selects a demo from:
   - change background color every line
   - visualize time required by MOVE and WAIT instructions
   - copper change of bitplane pointers on the fly

   cpr.c  -- main source code for demo

BuildReq
   A demonstration of a routine to algorithmically build an AutoRequest
   from a simple description, taking into account the effective font
   metric.  An example of the type of font-sensitive calculations that
   will be necessary as we allow new sizes and types of system default
   fonts.

   Options of the demo include requesters with very short, normal, and
   user specified strings.

   buildreq.c -- the AutoRequest builder subroutine
   buildt.c -- test caller for the above

DCop
   An enhancement of Scott Evernden's copper disassembler.
   It disassembles (and comments, decoding the weird format of some of
   the display controller registers) the active view hardware copper lists,
   the intermediate (including User) copper lists for the active view's
   first viewport, and the secret graphics copinit copper header.

   dcop.c -- self-contained source module, includes useful (and soon to
      obsolete) names for Amiga custom registers.

DView
   This program demonstrates the best method of double-buffering displays
   I can think of without disabling Graphics' vertical blank interrupt
   handler (which pokes it's idea of the active copper list every frame).

   Once you figure out how to allocate views and viewports, the
   hard part is synchronizing the display of newly prepared buffers
   with the "safe moment" to begin rendering in the offscreen
   buffer.  As I will indicate in the lecture, neither WaitTOF(),
   nor WaitBOVP() is a suitable synchronization method (even if
   WaitBOVP() did not busy-wait).

   This program, in replacing the system View structure, 
   also serves as an example for "taking over the system from Intuition."
   As such, it goes a little further than necessary for just the
   example, and demonstrates:
   - how to use a custom input handler to shut off input to Intuition
   - how to seamlessly return input to Intuition for transitions
     into menus
   - synchronization methods between the handler and the application
   - how to steal, use,  and return Intuition's sprite zero
     (and other sprites)
   - a useful technique for rendering into a sprite using normal graphics
     function calls

   dview.h -- contains definitions, include the DoubleView control structure
   dview.c -- setup, utility, and disposal subroutines for DoubleView scheme
   dvdemo.c -- example using copies of the Workbench screen
   ucop.c -- user Copper list setup for Copper interrupt synchronization
   vint.c -- video (Copper) interrupt handler installation and removal
   vhdlr.a68 -- small Copper interrupt handler
   steali.c -- steals the input food chain from Intuition with custom
      input device handler
   spr.h -- definitions for easy sprite handling
   spr.c -- sprite allocation, stealing, and rendering setup and disposal

OScan
   An example of techniques for displaying an overscanned screen or
   viewport.  Demonstrates a supported method of displaying large screens
   but with limited mouse travel.  Also includes demonstration of
   unsupportable technique for freeing mouse limits, which will not
   continue to work under future versions of Intuition.  See accompanying
   paper for more discussion.

   String gadgets are used to input values for View->DxOffset and
   View->DyOffset.  Menu selections are used to go in and out of
   "overscan mode" using the specified offset values.

   oscan.h -- just contains constants for huge dimensions
   oscan.c -- overscan demonstration
   huge.c -- sets up huge experimental bitmap
   oscreen.c -- handles screen, window, menus, and gadgets for demo.

MISC. TOOLS
   These utility subroutine files are used by several of the demos.
   These are part of a personal tools library used in developing the example
   programs.

   getargs.h -- command line argument parsing 
   getargs.c

   awindow.c -- finds the address of the active window

   openg.c -- open graphics.library
   openi.c -- open intuition.library
   sysall.h -- every system include file used for all demos,
      used to create a pre-compiled include file under Aztec C

