* pixelMap2Rgn
* Copyright (C) 1989-1990 by Apple Computer
*   -- written by Eric Soldan
*
* pixelMap2Rgn is proprietary Apple code.  To use this routine in a
* commercial application, you must obtain redistribution rights from
* Apple Software Licensing:
*
*     Apple Software Licensing
*     Apple Computer, Inc.
*     20525 Mariani Avenue, M/S 38-I
*     Cupertino, CA 95014
*     (408) 974-4667
*     AppleLink:  SW.LICENSE
*
*
* Code has been written to convert a pixelmap into a region.  This is
* useful for a variety of things.  The most typical example is a
* lasso command in a paint program.  This is even easier than before,
* given the new functions SeedFill and CalcMask in 5.0.
* Using these new 5.0 functions, you can generate a pixelmap of the
* lassoed area.  Now, by using pixelMap2Rgn, you can convert this
* pixel map into a region that you then can use in various ways.
*
* One thing that you might want to do with this region is:
*   1) Copy it.
*   2) InsetRgn one of the copies.
*   3) Do a DiffRgn of these two regions.
* Now you have a region that is the border of the lassoed area.  This
* region can now be used to "shimmer" the border of the lassoed area,
* just like MacPaint does.  It also can be used to determine if the
* mouse has been moved over the lassoed area by using PtInRgn.
* Basically, being able to convert a pixelmap into a region gives you
* all the QuickDraw capabilities of any other region.  The
* possibilities are numerous.

*******************************************************************************

* How to use pixelMap2Rgn from assembly:

* Input:
*      long:  Pointer to a locInfo structure for the pixelmap.
*             The pixelmap must be locked down, if it is in a handle.
*      word:  Value indicating 2-bit or 4-bit pixels (2 or 4 passed).
*             This is independent of 320 or 640 mode.  This way, we
*             can handle dithered or non-dithered palettes.
*             320 or 640 mode is determined by the SCB in the locInfo
*             for the bitmap.
*      word:  color table indicating which colors to include.
*             bit 0 set:  include color 0 in region.
*             bit 1 set:  include color 1 in region.
*             .
*             .
*             .
*             (For 2-bit colors, only bits 0 thru 3 are used)
* Output:
*      This function returns a region containing the relavent pixels.
*      This is true only if:
*           1)  The region does not exceed 65535 bytes.
*           2)  There was enough memory to construct the region.
*      Possible errors:
*           1)  Region too complex.
*           2)  Out-of-memory.
*
***********************************************************************



* How to use pixelMap2Rgn from C:

* rgn = pixelMap2Rgn(locInfoPtr, mode, whichColors);
*  locInfoPtr:  pixelmap to convert
*        mode:  2-bit pixels or 4-bit pixels (2 or 4 passed)
* whichColors:  16 bits of data indicating which colors to include
*
* If the pixelmap is in a handle, make sure the handle is locked
* before calling pixelMap2rgn.
