 **************************************************************************
 * mach64 Chapter 8 sample code                                           *
 *                                                                        *
 * Copyright (c) 1994-1998 ATI Technologies Inc.  All rights reserved.    *
 **************************************************************************

Chapter 8 demonstrates topics of the mach64 specific to the mach64VT/3D RAGE.
As in previous chapters, we will add more functions to our library, and
describe the sample programs.

CSC - This program demonstrates the colour space conversion feature of the
back end overlay/scaler of the VT/3D RAGE.  This program must be run in 16 bpp
colour depth.  Files of pixel depths of 15, 16, 32, YVYU and VYUY are then
displayed in succession.  They are all colour space converted to be displayed
on the 16 bpp screen pixel depth, using the hardware overlay.

OVERLAY - The hardware overlay of the VT/3D RAGE is enabled to demonstrate
its behaviour.  The overlay is non-destructive, that is, it does not overwrite
the video memory that it uses as its source.  The overlay is done at the DAC
level, thus the frame buffer memory is preserved.  As in the SCALER example, a
test image is loaded in the lower left corner of the display, and used as the
overlay source.  The overlay is then enabled, and bounced around the display.

SCALER - This program utilizes the hardware overlay/scaler present in the
VT/3D RAGE. A test image is loaded in the lower left corner of the display.
At this point, a keypress is required, then the image is scaled out in both
the x and y direction, from the top left of the display.  When it reaches
the edge of the display (in either the x or y direction), it reverses
direction.

KEYER - This program loops through the various colour keying capability states
of the overlay/scaler.  The same image is overlaid with different colour key
states and settings.

FESCALER - The front end scaler is used in this program to demonstrate the
colour space conversion BLTing capabilities of this component.  While the
overlay/scaler performs colour space conversion at the DAC level, the front
end scaler performs the conversion within the pixel pipeline, and the result
is put back into the frame buffer.  This is useful in situations where you
require access to the colour space converted data.  A YUV test image is
loaded into offscreen memory.  The image is then converted to the current
pixel depth (16/32 bpp) and displayed in the upper left hand corner of the
display.  Then, after pressing the space bar, the image is scaled down by 50%
and BLTed to the upper right corner of the display.  After another space bar
press, the image is scaled up 125% of the original size, and inverted.  The
resulting image is displayed in the lower right corner of the display.

SWITCH - This program once again used the colour space conversion BLTing
hardware of the front end scaler.  This program allows for user input, where
the following keys are used:
    B - toggles pixel blending and replication.  When replication is enabled,
        the image tends to be blockier, where blending will smooth out edges
        giving a overall smoother image.  Replication, while not as visually
        appealling as blending, is faster when blting.
    I - inverts the image.
    UP ARROW - Decreases the vertical size of the image by 10% of the current
               image resolution, to a minimum of 10% of the original image
               size.
    DOWN ARROW - Increases the vertical size of the image by 10% of the
                 current image resolution, to a maximum of the screen Y
                 resolution.
    RIGHT ARROW - Increases the horizontal size of the image by 10% of the
                  current image resolution, to a maximum of the current X
                  resolution.
    LEFT ARROW - Decreases the horizontal size of the image by 10% of the
                 current image resolution, to a minimum of 10% of the current
                 X resolution.
    ESCAPE - exits the program.

*****************************************************************************
*                                                                           *
*                           W A R N I N G ! !                               *
*                                                                           *
* The following bus master examples may not operate properly if run under a *
* Windows 95/98 DOS box or command prompt.  We have experienced issues with *
* the DOS4GW extender and DPMI services that may lock your system.  It is   *
* highly recommeded that you boot your system with DOS to ensure proper     *
* operation.                                                                *
*                                                                           *
*****************************************************************************

BMASTER - The bus mastering capabilities of the 3D RAGE PRO are demonstrated
here.  This particular example uses the bus master hardware of the 3D RAGE PRO
to move an image from system memory to display memory, 10 times.  This example
covers setting up the descriptor table, as well as setting up the hardware
for bus master operation.

BMGUI - Another facet of the bus mastering capabilities of the 3D RAGE PRO is
covered in this example.  The bus mastering hardware has the capability of
queueing up a number of engine operations in system memory, and bus mastering
the commands over to the GUI engine.  This example queues up a series of
rectangle draw operations, then executes the commands via the bus mastering
hardware, resulting in numerous rectangles being drawn on the screen,
repeating until a keypress is detected.
