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

Chapter 6 is structured differently from the previous chapters.  It now
includes a library of the functions that we have looked at in chapters 3
- 5.  In addition, a few more primitives were added. Specifically in
base drawing operations.  Clearing the screen, drawing rectangles,
drawing lines, and simple blits were added.  The library contains a
RUNME batch file that compiles all the C code into object files that the
demonstration programs use.

Specific programs to illustrate different features of the mach64 are
now separated into their own directory.  These programs reference the
library object files.  These sample programs provide a one to one
correspondance to the mach64 Programmer's Guide, and cross referencing
between the guide and code is recommended.  The following is a summary
of the included sample programs, listed in order corresponding to the
programmer's guide:

LINE - This program illustrates drawing simple lines on the screen using
the Bressenham algorithm.  The line draw routine is explicitly included
in the main file.  A special routine is shown to take care of 24bpp
modes.

RECT - This program illustrates drawing simple rectangles on the screen.
The rectangle routine is also used to clear the screen simply by
changing the mixing parameters.  More on the subject of mixing is
discussed later.  The rectangle draw routine is explicitly included in
the main file.

COMPARE - Demonstrates the compare feature of the mach64.  A pattern of
rectangles is displayed on the screen, then a LIGHT GREEN rectangle
(slightly smaller that the original pattern) is drawn over top of this
pattern using compare destination with LIGHT BLUE.  This results in the
light blue areas of the screen to remain.  (compare this program with
MIX).

MIX - Demonstrates the mixing feature of the mach64.  A pattern of
rectangles is displayed on the screen, then a LIGHT GREEN rectangle
(slightly smaller that the original pattern) is drawn over top of this
pattern using a foreground mix of DST_OR_SRC.  (compare this program
with COMPARE).

SBLIT - Demonstrates simple screen 1 to 1 bitblits.  Source trajectory
is unbouded y and destination trajectory is set to rectangle.  A light
blue and light magenta rectangle pattern is displayed on screen and then
blitted to a different part of the screen.  DP_FRGD_SRC is set to a blit
source, while the DP_MONO_SRC is set to always '1'.

GPBLIT - Demonstrates a general pattern bitblit.  A small pattern of
concentric rectangles is draw in the top left corner of the screen.
This pattern is used to fill a blit area that is larger than the source.
The pattern is replicated as per the definition of the source
trajectory 'General Pattern'.  (compare this program wiht GPRBLIT).

GPRBLIT - Demonstrates a general pattern bitblit with rotation.  This
program is essentially the same as GPBLIT, except, instead of beginning
the blit at offset (0,0) from the source, it is begun with the start
coordinates rotated to the centre of the source pattern.  (compare this
program with GPBLIT).

SLBLIT - Demonstrates a strictly linear bitblit.  Strictly linear
bitblit makes very effiecient use of memory since all information is
packed linearly.  A checkered pattern is drawn in memory at the base of
on screen memory (so that is is visible) using the linear aperture.
This pattern is then blitted using the stricly linear trajectory.  The
destination is located at the centre of the screen.  (compare this
program with MEBLIT).

MEBLIT - Demonstrates a monochrome expansion bitblit.  A monochrome
pattern is written to on screen memory.  This pattern is then blitted
to the screen.  This blit tequnique is even more efficient with memory
than the SLBLIT technique, since the data is linearly packed and only
one bit is needed to represent each pixel.  However, only two colours
are achievable with this technique.  (compare this program with SLBLIT).

GPLINE - Demonstrates general pattern lines.  A pattern is drawn on the
screen.  This pattern is used as the source to fill in a couple of
diagonal lines on screen.

TBLIT - This program demonstrates transparent bitblits.  A pattern of
rectangles is displayed on the screen.  Then a small pattern is
displayed in the top left corner to act as the source of bitblit.  This
source is blitted using a colour compare, first equal to LIGHT BLUE,
then not equal to LIGHT BLUE.  In the fist case, the areas of the
source pattern that are equal to light blue are transparent.  In the
second case, the areas of the source pattern that are not equal to light
blue are transparent.

FIXPAT - Pattern registers are used as a source to draw rectangles.
Three rectangles are drawn on screen using the pattern registers.  A
monochrome 8x8 is used to draw a white and magenta patterned rectangle.
A colour 4x2 pattern (8bpp only) is used to draw a blue and white
rectangle.  Finally, a colour 8x1 pattern (8bpp only) is used to draw
a light red and yellow rectangle.

SCISSOR - This program demonstrates the draw inhibiting technique known
as scissoring or clipping.  Two of the same size rectangles are drawn in
the same location on the screen.  The first is white and is not
inhibited.  The second is red and is 'clipped' by the scissor context.

CURSOR - This  program demonstrates the hardware cursor.  Colour 0 is
LIGHTBLUE, and colour 1 is YELLOW.  The background is Red, making it's
complement cyan.  The cursor bitmap consists of concentric squares, from
the outside-in of colour0(00), 1's complement(11), colour1(01), and
transparent(10).


The following primitives were added to the library for chapter 6:

// Functions in draw.c
void draw_rectangle (int x, int y, int width, int height);
void clear_screen (int x, int y, int width, int height);
void draw_line (int x1, int y1, int x2, int y2);
void blit (int x1, int y1, int x2, int y2, int width, int height);

// Functions in colour.c
unsigned long get_primary_colour (primarycolour pri_col, unsigned long colour);
unsigned long get_xy_offset (int x, int y);


// Functions in hwcursor.c
void set_hwcursor (int y, int width, int height, int hot_x, int hot_y,
                   unsigned long colour0, unsigned long colour1,
                   unsigned int *bitmap);
void enable_hwcursor (void);
void disable_hwcursor (void);
void set_hwcursor_pos (int x, int y);
void get_hwcursor_pos (point *position);
void set_cursor_colours (unsigned long colour0, unsigned long colour1);


The following global was also added:

extern hwcursor CURSORDATA;


The following structures were added:

typedef struct point
typedef struct hwcursor
typedef enum primarycolour
