mgd2.h

Go to the documentation of this file.

/******************************************************************************,
 *
 * \file mi32/mgd2.h
 * \brief MicroImages Graphics Device
 *
 * \if NODOC
 * $Log: mgd2.h_v $
 * Revision 1.93  2004/10/15 21:26:43  ldyas
 * added usesTransparency to textblock
 *
 * Revision 1.92  2004/10/14 22:04:20  ldyas
 * added is antialiased as member of textblock
 *
 * Revision 1.91  2004/09/20 20:56:55  dwilliss
 * added SetColor method that takes COLOR::NAME
 *
 * Revision 1.90  2004/08/19 17:58:26  dwilliss
 * Made some funcitons non-inline
 *
 * Revision 1.89  2004/07/20 22:22:09  dwilliss
 * *** empty log message ***
 *
 * Revision 1.88  2004/07/20 16:51:00  dwilliss
 * Gave the lable extents computing functions a parameter to allow them to
 * bypass the whole region creation if totally off screen.
 *
 * Revision 1.87  2004/07/20 16:41:27  dwilliss
 * Added methods to compute label extents region
 *
 * Revision 1.86  2004/06/18 19:45:44  ldyas
 * added text get font by full name and family name.
 *
 * Revision 1.85  2004/05/25 19:26:58  dwilliss
 * Moved the enums to their own include file so that we could use them
 * elsewhere without having to include all of mgd2.h and all it pulls in.
 *
 * Revision 1.84  2004/05/25 19:05:43  dwilliss
 * fixed typo in template inline function
 *
 * Revision 1.83  2004/05/25 17:43:48  dwilliss
 * Added INTERFACETEXTSTYLE enum and parameters to InterfaceText functions
 *
 * Revision 1.82  2004/05/10 17:09:14  mju
 * Move PIXEL typedef to stddefns.
 *
 * Revision 1.81  2004/04/02 21:56:49  dwilliss
 * Added DrawLabel method that takes a TEXTBLOCK
 *
 * Revision 1.80  2004/04/01 00:04:44  dwilliss
 * text changes galore.
 *
 * Revision 1.79  2004/03/30 17:10:05  dwilliss
 * Added comments to an enum
 *
 * Revision 1.78  2004/03/05 21:20:57  mju
 * Change Draw...StyleSample to use enum flags.
 *
 * Revision 1.77  2004/03/05 18:40:11  dwilliss
 * Renamed a method
 *
 * Revision 1.76  2004/03/05 17:23:13  mju
 * No longer include legacy mgd hdr as want to fix stuff which uses it.
 *
 * Revision 1.75  2004/02/13 16:45:28  dwilliss
 * Changed to include mgd.h for deprecated builds AFTER everything else
 *
 * Revision 1.74  2004/02/13 15:31:31  dwilliss
 * include old mgd dot h unless NO_DEPRECATED is set
 *
 * Revision 1.73  2004/02/13 14:55:33  dwilliss
 * Changed reference to mgd dot h in comment to prevent grep from finding it.
 *
 * Revision 1.72  2004/02/12 21:45:28  dwilliss
 * GetImagePointer no longer protected.  Need it to get rid of old deprecated
 * thing
 *
 * Revision 1.71  2004/02/12 21:08:56  dwilliss
 * Fixed stupid warning
 *
 * Revision 1.70  2004/01/12 20:46:36  dwilliss
 * Made the non-virtual Clear() method inline
 *
 * Revision 1.69  2004/01/12 20:44:54  dwilliss
 * Added Clear method to device
 *
 * Revision 1.68  2003/12/15 23:34:45  dwilliss
 * Diverging for 7.0
 * Made changes necessary for SML interface and graphical data tips
 *
 * Revision 1.67  2003/12/10 23:46:34  dwilliss
 * Keep track of virtual window in the base device class so low-level
 * implementations of fill span can cope with it.
 *
 * Revision 1.66  2003/12/10 17:47:25  dwilliss
 * Added private data
 *
 * Revision 1.65  2003/12/04 16:18:28  dwilliss
 * Make default implementation of v_InterfaceTextGetExtents() return 0s instead
 * of leaving return values as the random garbage they were passed in as
 *
 * Revision 1.64  2003/11/10 16:09:27  dwilliss
 * Added GetPixelColorNoICM and GetColorPixelNoICM
 *
 * Revision 1.63  2003/11/04 14:58:40  scowan
 * Removed groupkey deprecated get scalable font function.
 *
 * Revision 1.62  2003/11/04 13:25:04  mju
 * Remove ambiguity in dlgGetScalableFont.
 *
 * Revision 1.61  2003/11/03 20:40:26  scowan
 * Deprecate legacy get scalable font function.
 * Add new function with textid handling.
 *
 * Revision 1.60  2003/10/29 22:01:02  dwilliss
 * Context's method to check antialiasing no longer inline.  Now also checks
 * to see if the device supports it
 *
 * Revision 1.59  2003/10/29 18:29:04  ldyas
 * *** empty log message ***
 *
 * Revision 1.58  2003/10/24 17:03:48  dwilliss
 * Added method to get/set thin line width hinting
 *
 * Revision 1.57  2003/10/22 21:20:42  ldyas
 * *** empty log message ***
 *
 * Revision 1.56  2003/10/10 22:44:48  dwilliss
 * Added Get/SetAntialiasing
 *
 * Revision 1.55  2003/10/08 17:46:35  ldyas
 * added anti-aliasing and filldevice
 *
 * Revision 1.54  2003/10/03 20:10:53  linux32build!build
 * Doxygen
 *
 * Revision 1.53  2003/10/01 22:16:22  dwilliss
 * Doxygen
 *
 * Revision 1.52  2003/09/29 22:58:22  dwilliss
 * Added a member to device
 *
 * Revision 1.51  2003/09/22 20:29:12  dwilliss
 * Got rid of an overload that wasn't used and didn't do anything useful
 *
 * Revision 1.50  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.49  2003/09/09 22:11:21  scowan
 * nc.
 *
 * Revision 1.48  2003/09/09 17:56:22  scowan
 * Added more work buffers.
 *
 * Revision 1.47  2003/07/31 20:36:33  dwilliss
 * Made SetICMSourceProfile() non-inline.  It just got a whole lot more
 * compilcated.
 *
 * Revision 1.46  2003/07/25 22:22:34  dwilliss
 * *** empty log message ***
 *
 * Revision 1.45  2003/07/03 17:52:14  dwilliss
 * *** empty log message ***
 *
 * Revision 1.44  2003/06/27 14:21:45  dwilliss
 * GetOutputScale modified to cope with this == NULL
 *
 * Revision 1.43  2003/06/24 16:11:20  dwilliss
 * Added a DrawLabel method
 *
 * Revision 1.42  2003/06/17 16:42:31  dwilliss
 * Made 3 methods of device non-inline.  GetPixelSizeMM (2 flavors) and
 * CreateContext now cope with "this" being NULL.
 *
 * Revision 1.41  2003/06/16 22:58:58  dwilliss
 * *** empty log message ***
 *
 * Revision 1.40  2003/06/11 22:12:28  dwilliss
 * *** empty log message ***
 *
 * Revision 1.39  2003/06/11 22:08:06  dwilliss
 * The inline for DrawPoint was missing.
 *
 * Revision 1.38  2003/06/11 17:10:57  dwilliss
 * Virtual methods all renamed to start with v_ and made private (where
 * possible) or protected.
 *
 * Revision 1.37  2003/06/06 22:34:45  dwilliss
 * color management stuff
 *
 * Revision 1.36  2003/05/30 16:50:24  dwilliss
 * Added a new overload of a function
 *
 * Revision 1.35  2003/05/28 15:13:37  dwilliss
 * A bunch of ICM changes
 *
 * Revision 1.34  2003/05/23 22:41:59  dwilliss
 * Added methods to Clear ICM Profiles
 *
 * Revision 1.33  2003/05/21 22:30:56  dwilliss
 * Added ICM Profile support
 *
 * Revision 1.32  2003/01/23 15:03:13  scowan
 * Fixed inline calling errors for draw lines dashed.
 *
 * Revision 1.31  2003/01/20 16:45:53  mju
 * Fix parm names for draw/fillrectangle.
 *
 * Revision 1.30  2003/01/10 21:51:31  mju
 * Add comment.
 *
 * Revision 1.29  2003/01/10 21:24:30  mju
 * Add DrawLinesDashed versions using c-style array.
 * Make virtual DrawLinesDashed start with v_.
 *
 * Revision 1.28  2003/01/07 21:50:32  dwilliss
 * Added DrawArrow() method
 *
 * Revision 1.27  2003/01/02 20:28:49  dwilliss
 * Added new DrawRegion/DrawSubregion methods
 *
 * Revision 1.26  2002/11/21 23:01:36  dwilliss
 * Added new capabililty flag
 *
 * Revision 1.25  2002/11/15 16:25:10  dwilliss
 * The idea of a "work" context is gone.
 *
 * Revision 1.24  2002/11/13 23:37:02  dwilliss
 * Complex Clip Regions
 * Added DrawLines() method taking a POLYLINE
 * Added FillRegion()
 * Various private method changes necessary to fix hatch pattern filling to
 *   use complex clip regions
 *
 * Revision 1.23  2002/10/30 21:54:22  scowan
 * Moved method to be private.
 *
 * Revision 1.22  2002/10/21 14:18:45  dwilliss
 * const issue
 *
 * Revision 1.21  2002/10/17 15:22:53  mju
 * COLORSPACE enum moved to mi32/colorspc.h and some items renamed.
 *
 * Revision 1.20  2002/10/03 22:05:52  dwilliss
 * Added InterfaceTextGetWidth(),  Gave InterfaceTextDrawString() an optional
 * parameter for visual order drawing
 *
 * Revision 1.19  2002/10/02 22:39:29  dwilliss
 * Made GetImagePointer protected
 *
 * Revision 1.18  2002/10/02 20:28:44  dwilliss
 * Fixed a problem in SetFont.  Wasn't keeping track of stuff right
 *
 * Revision 1.17  2002/09/09 17:00:42  mju
 * Allow mgd dot h so can compile stubs.
 *
 * Revision 1.16  2002/08/19 15:15:11  scowan
 * nc.
 *
 * Revision 1.15  2002/08/19 15:06:10  dwilliss
 * Change a cast to a const_cast for clarity
 *
 * Revision 1.14  2002/08/14 17:13:00  ldyas
 * *** empty log message ***
 *
 * Revision 1.13  2002/08/14 17:12:25  ldyas
 * Added IsEmbeddable for Fonts
 *
 * Revision 1.12  2002/08/13 16:15:47  vdronov
 * added m_IsPerspective and Calculate3dDepthFunction
 *
 * Revision 1.11  2002/08/01 16:09:39  dwilliss
 * *** empty log message ***
 *
 * Revision 1.10  2002/07/03 15:27:00  dwilliss
 * Added MGD::FONT::ReadTTF() as a static method
 *
 * Revision 1.9  2002/06/11 22:05:42  scowan
 * Added another friend.
 *
 * Revision 1.8  2002/06/10 16:18:59  mju
 * Add COLORLOCK class.
 *
 * Revision 1.7  2002/06/04 23:18:56  ldyas
 * Made SetColorIsPatternValue virtual
 *
 * Revision 1.4  2002/06/03 22:58:28  ldyas
 * Added SetColorIsPatternVariable and DrawLinesDashed
 *
 * RCS error forced me to delete the RCS file and start over
 *
 * Revision 1.1  2002/05/29 23:00:02  dwilliss
 * Initial revision
 *
 * Revision 1.62  2002/05/29 22:12:18  dwilliss
 * TextOpenFont now takes const filename
 *
 * Revision 1.61  2002/05/28 22:58:56  dwilliss
 * Expanded documentation in comments
 *
 * Revision 1.60  2002/05/21 22:51:14  dwilliss
 * Added TextBlockBegin/End methods
 *
 * Revision 1.59  2002/05/21 16:34:49  dwilliss
 * SetOutputScale is no longer inline.  More complicated that just assignment
 *
 * Revision 1.58  2002/05/17 22:53:31  dwilliss
 * Added TextSpanBegin/End
 *
 * Revision 1.57  2002/05/13 22:53:35  dwilliss
 * Defined new "cabability" flag.
 *
 * Revision 1.56  2002/05/13 22:50:22  dwilliss
 * Made some text drawing methods virtual
 *
 * Revision 1.55  2002/04/23 16:46:29  dwilliss
 * Added more colorspaces for 32-bit cases
 *
 * Revision 1.54  2002/04/19 14:18:13  dwilliss
 * Inline method was missing return value
 *
 * Revision 1.53  2002/04/05 21:03:52  mju
 * Add Draw...StyleSample methods use RVC::STYLE.
 *
 * Revision 1.49  2002/03/14 23:30:36  dwilliss
 * TEXTBLOCKs now use Unicode text exclusively.
 *
 * Revision 1.48  2002/03/13 21:11:25  dwilliss
 * Changes necessary to implement full justified text
 *
 * Revision 1.47  2002/03/11 18:52:00  dwilliss
 * Added a GetTextStyle/SetTextStyle pair
 *
 * Revision 1.46  2002/03/08 15:39:26  dwilliss
 * MGD::TEXTBLOCKs can't be memset now.  Use the constructor
 *
 * Revision 1.45  2002/03/08 15:28:54  dwilliss
 * TEXTBLOCK has constructor/destructor now
 *
 * Revision 1.44  2002/02/22 16:17:56  scowan
 * Added clip width.
 *
 * Revision 1.43  2002/02/21 23:59:24  scowan
 * Added clip width variable.
 *
 * Revision 1.42  2002/02/21 18:09:40  dwilliss
 * Changed the comments on CopyRect() to reflect reality
 *
 * Revision 1.41  2002/02/08 23:03:05  scowan
 * Changed text get area to text add to clip.
 *
 * Revision 1.40  2002/02/05 15:45:28  dwilliss
 * Changes to CONTEXT_AUTOPTR.  Constructor is explicit, copy constructor and
 * assignment operator are declared but unimplemented to prevent use.
 *
 * Revision 1.39  2002/02/05 15:39:44  dwilliss
 * Added CONTEXT_AUTOPTR
 *
 * Revision 1.38  2002/01/30 23:44:57  scowan
 * Removed flag for using fill span.
 *
 * Revision 1.37  2002/01/29 23:58:11  scowan
 * Added clear clip mask method.
 *
 * Revision 1.36  2002/01/29 15:55:21  dwilliss
 * Added private method to device
 *
 * Revision 1.35  2002/01/28 21:35:31  scowan
 * Added virtual methods to deal with clipping masks.
 *
 * Revision 1.34  2002/01/25 23:34:09  scowan
 * Removed legacy clip mask structure.
 *
 * Revision 1.33  2002/01/25 16:04:56  mju
 * Add defaults for DlgGetScalableFont like old version had.
 *
 * Revision 1.32  2002/01/16 23:34:54  scowan
 * Added boldnesswidth to textsettings.
 *
 * Revision 1.31  2002/01/16 23:17:46  scowan
 * Changed methods and added methods.
 *
 * Revision 1.30  2002/01/09 20:20:11  dwilliss
 * Fixed problem with null device
 *
 * Revision 1.29  2002/01/09 20:07:05  dwilliss
 * Added Null Device
 *
 * Revision 1.28  2002/01/08 23:48:50  dwilliss
 * ImageBegin/ImageEnd/PutImageSpan now deal with any source colorspace
 * CopyRect uses above changes so it works too.
 *
 * Revision 1.27  2002/01/08 20:52:47  dwilliss
 * Added version of ImageBegin that takes a rectangle instead of x,y,h,w
 *
 * Revision 1.26  2002/01/08 20:39:53  dwilliss
 * TextSetHeight now allows you to specify units
 *
 * Revision 1.25  2002/01/08 19:50:10  dwilliss
 * CreateContext no longer pure virtual.
 *
 * Revision 1.24  2002/01/08 18:57:10  dwilliss
 * Reworkded to move all class members to base class
 *
 * Revision 1.23  2002/01/04 21:28:08  dwilliss
 * Define use new mgd flag
 *
 * Revision 1.22  2002/01/04 14:59:45  dwilliss
 * Allow use again
 *
 * Revision 1.21  2002/01/02 22:49:31  dwilliss
 * Everything compiles now
 *
 * Revision 1.20  2001/12/31 16:57:52  dwilliss
 * GetColorSpace no longer pure virtual
 *
 * Revision 1.16  2001/12/24 16:50:53  dwilliss
 * Added some methods that old MGD had.
 *
 * Revision 1.15  2001/12/24 16:22:47  dwilliss
 * Added NoMultiPointSpan setting method
 *
 * Revision 1.8  2001/07/27 22:09:34  dwilliss
 * Added capability flag for being able to use a mask in PutImageSpan
 *
 * Revision 1.7  2001/07/26 20:57:10  dwilliss
 * Update font stuff to use new freetype
 *
 * Revision 1.6  2001/07/13 15:29:47  dwilliss
 * Some more Mac compile issues
 *
 * Revision 1.5  2001/07/13 15:11:14  dwilliss
 * Fixed Mac compiler errors
 *
 * Revision 1.4  2001/07/12 14:05:03  dwilliss
 * gcc didn't like #error with no quotes even though should be ifdef'd out
 *
 * Revision 1.1  2001/07/11 17:33:41  dwilliss
 * Initial revision
 * \endif
 */

#ifndef INC_MI32_MGD2_H
#define INC_MI32_MGD2_H

#define USE_NEW_MGD


#ifndef INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#ifndef INC_MI32_ELEMSTYL_H
#include <mi32/elemstyl.h>
#endif

#ifndef INC_MI32_MICON_H
#include <mi32/micon.h>
#endif

#ifndef INC_MI32_DISPINFO_H
#include <mi32/dispinfo.h>
#endif

#ifndef INC_MI32_COLORMAP_H
#include <mi32/colormap.h>
#endif

#ifndef INC_MI32_RECT_H
#include <mi32/rect.h>
#endif

#ifndef INC_MI32_POINT_H
#include <mi32/point.h>
#endif

#ifndef INC_MI32_SCRNUNIT_H
#include <mi32/scrnunit.h>
#endif

#ifndef INC_MI32_TEXTBASE_H
#include <mi32/textbase.h>
#endif

#ifndef INC_MI32_MILIST_H
#include <mi32/milist.h>
#endif

#ifndef INC_MI32_SIMPLEAR_H
#include <mi32/simplear.h>
#endif

#ifndef INC_MI32_COLOR_H
#include <mi32/color.h>
#endif

#ifndef INC_MI32_ERRCODES_H
#include <mi32/errcodes.h>
#endif

#ifndef INC_MI32_COLORSPC_H
#include <mi32/colorspc.h>
#endif

#ifndef INC_MI32_COLRCONV_H
#include <mi32/colrconv.h>
#endif
#ifndef INC_MI32_COLRCONV_H
#include <mi32/colrconv.h>
#endif

#ifndef INC_MI32_POLYLINE_H
#include <mi32/polyline.h>
#endif

#ifndef INC_MI32_MG2CMS_H
#include <mi32/mg2cms.h>
#endif

#ifndef INC_MI32_TEXTID_H
#include <mi32/textid.h>
#endif

#ifndef INC_MI32_MG2ENUMS_H
#include <mi32/mg2enums.h>
#endif


#ifndef GENERATING_DOXYGEN_OUTPUT
struct HATCHCOMPONENT;
class MISTRING;
class REGION2D;
class SUBREGION2D;
class LABELSTYLE;
struct FTFACE;
struct HATCHCOMPONENT;
struct McbAnyCallbackStruct;
class SAVEFONTFLAGS;
namespace RVC {
   class STYLE;
   }
namespace {
   class LOCALOPENFONTS;      // Located in mg2text.c
   }
#endif // GENERATING_DOXYGEN_OUTPUT

namespace MGD {


//! This struct should be moved to a private include file, but we might
//! yet find a use for it.
struct STRINGDATA {
   STRINGDATA() {}
   ~STRINGDATA() {}
   
   SIMPLE_ARRAY<UINT16> m_gid;
   SIMPLE_ARRAY<FTFACE*> m_face;
   SIMPLE_ARRAY<UINT16> m_gflags;
   SIMPLE_ARRAY<DPOINT2D> m_pos;
   MISTRING m_str;         //!< May be used by overloaded _DrawGlyph() call
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      STRINGDATA(const STRINGDATA&);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//! Special characters in array of Glyph IDs (GID) returned from
//! FONT.UCtoGID().  When rendering or computing string width,
//! These shoul be passed through to let the rendering engine handle them
//! XXX These should be private to mg2textt.c and mgdtext.c
#define  MgdTEXTGID_ChangeFace      0xFFFF   
#define  MgdTEXTGID_LeftToRight     0xFFFE
#define  MgdTEXTGID_RightToLeft     0xFFFD
#define  MgdTEXTGID_NextGlyph0Width 0xFFFC
#define  MgdTEXTGID_FallbackFace    0xFFFB
#define  MgdTEXTGID_SpecialCodeMin  0xFFFB   //!< For quicker comparison

#ifndef GENERATING_DOXYGEN_OUTPUT
class CONTEXT;       // Forward Declarations
class DEVICE_MEM1;
class DEVICE_MEM1_SPARSE;
class DEVICE_MEM8G;
#endif // GENERATING_DOXYGEN_OUTPUT

//! Information about single glyph in a font.
struct GLYPHINFO {
   double lbearing;                    //!< Pixels between glyph origin and left edge
   double rbearing;                    //!< Pixels between glyph origin and right edge
   double rspacing;                    //!< Pixels between glyph origin and next character
   double ascent;                      //!< Pixels between glyph origin and top
   double descent;                     //!< Pixels between glyph origin and bottom
   };

//! Font metrics.
struct FONTINFO {
   double ascent;                      //!< Ascent above baseline in pixels
   double descent;                     //!< Descent below baseline in pixels
   double linespace;                   //!< Spacing between baselines
   UINT16 NumGlyphs;                   //!< Number of glyphs in font
   UINT16 InitChar;                    //!< Initial character having glyph defined
   UINT16 LastChar;                    //!< Last character having glyph defined
   UINT16 NullChar;                    //!< Character to user for undefined glyphs
   };

//! Font definition and implementation.
class FONT {
   public:

      enum MODE {
         MODE_UNICODE,                    //!< Using Unicode
         MODE_RAWGID,                     //!< Glyph IDs instead of Unicode
         MODE_GID                         //!< Glyph IDs encoded by UCtoGID member function
         };

      enum FONTTYPE {
         FONTTYPE_OF,
         FONTTYPE_TTF
         };

      //! Read a TrueType font into memory.
      //!
      //! The "name" parameter is expected to be the filename, minus the path
      //! or extention.
      //!
      //! The FaceNum parameter is for TrueType Collections (ttc).  A ttc file
      //! contains multiple ttfs
      //! Since TrueType fonts are embeded in resource files on the Macintosh
      //! (even in OS X), a simple "filename" isn't all that useful.  This
      //! function handles reading the whole thing.
      static ERRVALUE ReadTTF (
         const UNICODE* name,
         SIMPLE_ARRAY<UINT8>& data
         );

      FONT();

      virtual ~FONT();
      
      virtual int DrawGlyph (
         MGD::CONTEXT* context, 
         double dx, 
         double dy, 
         double baseangle, 
         const UNICODE* ucstr, 
         MGD::FONT::MODE mode
         ) = 0;

      virtual int DrawGlyph (
         MGD::CONTEXT* context, 
         double dx, 
         double dy, 
         double baseangle, 
         const STRINGDATA& string,
         int n
         ) = 0;

      virtual double NextPosition (
         MGD::CONTEXT* context, 
         double* retx, 
         double* rety, 
         double baseangle, 
         const STRINGDATA& string,
         int n,
         double SpaceExtra = 0.0,   //!< Extra pixels per space to insert
         double GlyphExtra = 0.0
         ) = 0;

      virtual int GetFontMetrics (
         MGD::CONTEXT* context, 
         MGD::FONTINFO& fontinfo
         ) = 0;
      
      virtual int GetGlyphMetrics (
         MGD::CONTEXT* context, 
         UNICODE ch, 
         MGD::GLYPHINFO& glyphinfo, 
         MGD::FONT::MODE mode
         ) = 0;

      virtual int GetGlyphExtents (
         MGD::CONTEXT* context, 
         const double& dx, 
         const double& dy, 
         const double& baseangle, 
         UNICODE ch, 
         DRECT2D& extents, 
         MGD::FONT::MODE mode
         ) = 0;

      virtual bool IsEmbeddable (
         ) const = 0;

      virtual int UCtoGID (
         MGD::CONTEXT* context, 
         const UNICODE* uc, 
         MGD::STRINGDATA& strdata
         ) = 0;

      const UNICODE* GetFontName (
         ) const {
         return (m_fontname);
         }


      virtual MGD::FONT::FONTTYPE GetFontType (
         ) const = 0;
      
      //! Get the outline of a glyph.  This only works for TrueType
      //! fonts, but the caller won't have access to the TrueType-derived
      //! MGD::FONT_TTF.  So we make it virtual and let it return an
      //! error by default.  We could easily implement it for OF fonts
      //! too if it was ever needed.
      virtual ERRVALUE GetGlyphOutline (
         UINT16 GlyphIndex,
         INT32 *NumContours,
         LPOLYGON **Def,
         UINT32 FontFlags
         ) {
         return (EProgramError);
         }

      UNICODE GetInitChar (
         ) const {
         return (m_InitChar);
         }
      
      UNICODE GetLastChar (
         ) const {
         return (m_LastChar);
         }
      
      UNICODE GetNULLChar (
         ) const {
         return (m_NullChar);
         }
      
      UNICODE GetNumGlyphs (
         ) const {
         return (m_NumGlyphs);
         }

   protected:
      UNICODE m_fontname[32];
      UNICODE m_filename[FILENAME_MAX];
      UINT16 m_NumGlyphs;              //!< Number of glyphs in font
      UNICODE m_InitChar;              //!< Initial character having glyph defined
      UNICODE m_LastChar;              //!< Last character having glyph defined
      UNICODE m_NullChar;              //!< Character to user for undefined glyphs
   };


struct TEXTSETTINGS : public TEXTSTYLE {           //! Text drawing parameters
   PIXEL ForegroundPixel;
   PIXEL BackgroundPixel;
   PIXEL UnderlinePixel;
   
   TEXTSETTINGS (
      ) {
      Reset();
      }
      
   double GetBoldness (
      ) const {
      return (BoldnessWidth);
      }

   void Reset (
      );
      
   };


//! Text block border settings.
struct TEXTBLOCKBORDER {
   UINT16 Type;                        //!< Border type
   UINT16 WidthUnits;                  //!< Units for line width (SCREENUNIT_...)
   float Width;                        //!< Line or border width
   COLOR Color;                        //!< Line color

   TEXTBLOCKBORDER() {
      memset(this, 0, sizeof(TEXTBLOCKBORDER));
      }
   };

//! Text block.
struct TEXTBLOCK {
   const UNICODE *Text;                   //!< Encoded text string.  Note, TEXTBLOCK does not actually own the text and will not free it.
   TEXTSTYLE Style;                    //!< Initial style
   DPOINT2D basepoint;                 //!< Base point in display coordinates
   double baseangle;                   //!< Rotation angle in radians
   TEXTBASEORIGIN baseorigin;          //!< Origin of basepoint within block
   COLOR Background;                   //!< Background color
   COLOR ShadowTop;                    //!< "Top shadow" color, usually brighter than background
   COLOR ShadowBottom;                 //!< "Bottom shadow" color, usually darker than background
   TEXTBLOCKBORDER Frame;
   TEXTBLOCKBORDER LeftBorder;
   TEXTBLOCKBORDER RightBorder;
   TEXTBLOCKBORDER TopBorder;
   TEXTBLOCKBORDER BottomBorder;
   bool IsAntialiased; //!< set when SetUp is called
   bool UsesTransparency; //!< set when SetUp is called
   float MarginH;
   float MarginV;
   UINT16 MarginUnits;

   //! Get the first line of the text block
   ERRVALUE GetFirstString (
      MISTRING& string           //!< String returned
      );

   TEXTBLOCK();

   ~TEXTBLOCK();
   };



//!   \class DEVICE
//! \brief Base class for all MGD::DEVICE derived classes
//!
//! @note The default constructor is protected, so you can't declare
//! an MGD::DEVICE by itself.  You must use one of the derived classes.
class DEVICE {

   public:

      // Default constructor is protected.

      //! Destructor
      virtual ~DEVICE (
         );

      // (Note: copy constructor private and unimplemented.  Can't copy one.)
      
      
      //! Returns true if the derived class is based on an implementation
      //! where fill spans are considered "bad".  This is used by the
      //! implementation of text drawing functions to know if they should
      //! be drawn as fillspans of call FillPolygons
      bool AvoidFillSpans (
         ) const {
         return (v_AvoidFillSpans());
         }
            
      //! Set the colormap for the display.  Derived class should override this
      //! if it cares about colormaps.  If not, the default version just ignores
      //! the caller.
      //!
      //! XXX Old version took a COLORMAPINFO which was passed to 
      //! CompOptmFromColMap().  Has RedBits, GreenBits, BlueBits.
      //! What are these?
      ERRVALUE ChangeColorMap (
         const SIMPLE_ARRAY<COLOR>& colors
         ) {
         return (v_ChangeColorMap(colors));
         }

      ERRVALUE Clear (
         const COLOR& color
         ) {
         return (v_Clear(color));
         }
      
      //! Clear the ICM Profile of the destination device.
      void ClearICMDestProfile (
         ) {
         m_DestProfile.Free();
         }

      //! Clear the ICM Profile of the proofing device
      void ClearICMProofProfile (
         );

      //! Create a GC for drawing.  
      //!
      //! Derived classes may override this and make it return anything
      //! derived from MGD::CONTEXT.  MGD::CONTEXT's constructor is private, so
      //! this is the only way for calling code to create a GC.
      //! 
      MGD::CONTEXT* CreateContext (
         );

      //! If the display is going to support 3D, then it should allocate its depth
      //! buffer here.  If overriding this, also be sure to override
      //! Is3DInitialized() so that it will return true if DepthInit3D() has been
      //! called and override CanDo3D() to return true.
      //!
      //! This implementation allocates an in-memory buffer if the device
      //! size is <= 1024 x 1024.  If it's bigger, it allocates a temporary
      //! raster to hold the data.
      //!
      //! 3D implementation code can call GetDepthBuffer() to get the depth
      //! buffer for a given span of data.
      ERRVALUE DepthInit3D (
         ) {
         return (v_DepthInit3D());
         }

      //! Destroy a GC.
      //!
      //!   Not strictly necessary, but it balances the CreateGC() method nicely.
      //! You can just "delete" an MGD::CONTEXT.
      // Would inline this, but the compiler complains that MGD::CONTEXT is incomplete
      // and won't let me "delete" one here. 
      void DestroyContext (
         MGD::CONTEXT* gc
         );

      //! Return true if DepthInit3D() has been called.  
      //! Derived class should override this to return true if DepthInit3D has 
      //! been called.
      bool Is3DInitialized (
         ) const {
         return (m_zbuf != 0);
         }

      //! Return true if the display is for an X drawable
      bool IsX11 (
         ) const {
         return (v_IsX11());
         }

      //! Get the ColorMap for the device.  Will return NULL
      //! if the device doesn't use one.
      const SIMPLE_ARRAY<COLOR>* GetColorMap (
         ) const {
         return (&m_ColorMap);
         }

      //! Get the ColorMapInfo structure for this device
      //! Will return NULL if the device doesn't have one.
      //! Will be depricated.  Use GetColorMap() instead
      const COLMAPINFO* GetColorMapInfo (
         ) {
         memset(&m_ColorMapInfo, 0, sizeof(COLMAPINFO));
         m_ColorMapInfo.colmap = const_cast<COLOR*>((const COLOR*)GetColorMap());
         m_ColorMapInfo.NumColors = GetColorMap()->GetNumItems();
         //! The rest of the structure is never used any more
         return (&m_ColorMapInfo);
         }

      //! Given a color, return the Pixel value that matches (or is as close
      //! possible)
      //! Does NOT take ICM into account.  The one in context does.

#if !defined(NO_DEPRECATED)      
      //! Deprecated because you should call the one in the context
      //! \deprecated Call the version in the context
      PIXEL GetColorPixel (
         const COLOR& color
         ) {
         return (v_GetColorPixel(color));
         }
#endif

      //! Return the "native" COLORSPACE used by the display
      //! Image operations using this colorspace will be more effeciant.
      //! Default implementation determines the colorspace from the 
      //! DeviceInfo
      COLORSPACE GetColorSpace (
         ) const {
         return (v_GetColorSpace());
         }

      //! return the depth at a given pixel location.  
      //! This is GC-indapendant.
      float GetDepth3D (
         INT32 x, 
         INT32 y
         ) {
         return (v_GetDepth3D(x, y));
         }

      const DISPLAYINFO& GetDeviceInfo (
         ) const {
         return m_devinfo;
         }

      const LRECT2D& GetExtents (
         ) const  {
         return m_Extents;
         }

      INT32 GetHeight (
         ) const {
         return (GetExtents().GetHeight());
         }


      int GetImageBytesPerPixel (
         ) const {
         return m_ImageBytesPerPixel; 
         }

      //! Return a pointer to a piece of the image buffer.
      //! This only has to be implemented if HasCapability(CAPABILITY_GetImage)
      //! returns true.  The CopyRect() routines use it to read the source image.
      //! Note that this may return a pointer directly into the screen buffer
      //! or a temporary buffer into which it has read the requested data.  It's
      //! up to the implementation to decide how to handle this.
      UINT8* GetImagePointer (
         INT32 x,
         INT32 y,
         INT32 len
         ) {
         return (v_GetImagePointer(x, y, len));
         }

      //! Return the number of bytes needed to hold one line of image data
      //! Should be overridden by derived class unless images are not possible
      //! (such as a pen plotter)
      INT32 GetLineBytes (
         ) const {
         return (v_GetLineBytes());
         }

      //! Determine if full image lines are needed (no tiled output).
      bool GetNeedFullImageLine (
         ) const {
         return (v_GetNeedFullImageLine());
         }

      //! Get the OPTMPARM structure for the device.  Will return NULL
      //! if the device doesn't use one.
      const OPTMPARM* GetOptmParm (
         ) const {
         return (&m_optmparm);
         }

#if !defined(NO_DEPRECATED)      
      //! Given a pixel value, return the color it represents
      //! \deprecated Call the one in the context instead
      void GetPixelColor (
         PIXEL pixel,
         COLOR& color
         ) const {
         v_GetPixelColor(pixel, color);
         }
#endif

      //! Return the pixel size in millimeters, assuming square pixels.
      //! This method will cope with "this" being NULL by returning the
      //! pixel size of a NULL device
      double GetPixelSizeMM (
         ) const;

      //! Return the pixel size in millimeters without assuming squareness
      //! This method will cope with "this" being NULL by returning the
      //! pixel size of a NULL device
      void GetPixelSizeMM (
         double& xsize,
         double& ysize
         ) const;

      //! Return the pixel size in DPI, assuming square pixels.
      double GetPixelSizeDPI (
         ) const {
         return ((1000.0 / METERSTOINCHES) / GetPixelSizeMM());
         }

      //! Return the pixel size in DPI without assuming squareness
      void GetPixelSizeDPI (
         double& xsize,
         double& ysize
         ) const {
         double x, y;
         GetPixelSizeMM(x, y);
         xsize = (1000.0 / METERSTOINCHES) / x;
         ysize = (1000.0 / METERSTOINCHES) / y;
         }

      INT32 GetWidth (
         ) const {
         return (GetExtents().GetWidth());
         }

      bool HasCapability (
         MGD::CAPABILITY capability
         ) {
         return ((v_GetCapabilities() & capability) != 0);
         }

      //! Scan the image for color usage.
      //! (may not need for all implementations?)
      ERRVALUE ScanColorUse (
         HISTORGB& historgb
         ) {
         return (v_ScanColorUse(historgb));
         }
   
      const PROFILE& GetICMDestProfile (
         ) const {
         return (m_DestProfile);
         }

      PROFILE::INTENT GetICMIntent (
         ) const {
         return m_ICMIntent;
         }

      //! Set the ICM Profile of the destination device.
      void SetICMDestProfile (
         const PROFILE& profile,
         PROFILE::INTENT intent = PROFILE::INTENT_Perceptual
         );

      //! Set the ICM Profile of the destination device.
      void SetICMDestProfile (
         const PROFILEPARMS_PRINTER& profile
         );

      //! Set the ICM Profile of the destination device to the currently
      //! selected Screen profile (Selected in the TNTmips preferences)
      void SetICMDestProfileScreen (
         );

      //! Set the ICM Profile of the proofing device
      //! If set, will cause images and colors to be mapped to the gamut of
      //! the proofing device (printer) before being mapped to the gamut of
      //! the Dest device.  This way, the Dest device (screen) won't show any
      //! colors which the Proofing device (printer) is incapable of rendering.
      void SetICMProofProfile (
         const PROFILEPARMS_PRINTER& profile
         );

      //! Set the pixel size in millimeters without assuming squareness
      void SetPixelSizeMM (      
         double xsize,
         double ysize
         ) {
         m_mmPerPixel.x = xsize;
         m_mmPerPixel.y = ysize;
         return;
         }

   protected:

      #ifndef GENERATING_DOXYGEN_OUTPUT
      LRECT2D m_Extents;         //!< All implementations need this
      OPTMPARM m_optmparm;       //!< move to derived class? GetColorPixel uses it
      PIXEL m_AllPlanesMask;
      int m_ImageBytesPerPixel;
      DPOINT2D m_mmPerPixel;
      SIMPLE_ARRAY<COLOR> m_ColorMap;
      COLMAPINFO m_ColorMapInfo;    //!< Only for old code
      LPOINT2D m_TileSize;          //!< Raster tile size hint (0's if tiles not helpful)
      LPOINT2D m_offset;      // Only ever changed by DEVICE_RASTER, but we need
      LPOINT2D m_RealSize;    // to account for them in low-level fillspan
      bool m_bHasVirtualWindow;
      #endif


      //! Constructor.
      //!
      //! Because we could get an error while allocating an MGD::DEVICE,
      //! and we don't deal with exception handling code, 
      //! the constructor should only initialize the class members.
      //! Each derived class should have an Initialize() method to 
      //! actually allocate memory. This would be a pure-virtual 
      //! function, but the parameters necessary are likely to be
      //! implementation dependant.  For example, the raster implementation
      //! would need to take an RVC::RASTER object or something.
      //! An X implementation would require a Drawable, etc...
      //!
      DEVICE();

      virtual ERRVALUE v_CopyColorMap (
         SIMPLE_ARRAY<COLOR> colors
         ) {
         return (0);
         }

      //! Fill a horizontal span.
      //!
      //! Many of the default method implementations call this to do all the work.
      //! Not all of them even need it., so not pure-virtual.
      //! Derived classes that implement this do not need to worry about
      //! clipping, as the default implementation in CONTEXT does
      //! clipping and then calls this version.
      //!
      //! If your implementation handles bitmap pattern fills in a way that's
      //! optimized for your dest device, you should return CAPABALITY_BitmapFill
      //! in GetCapabilities
      virtual ERRVALUE v_FillSpan (
         MGD::CONTEXT* gc,
         INT32 x1,
         INT32 x2,
         INT32 y
         ) {
         return (0);
         }

      // For internal use only.  Calls v_FillSpan
      ERRVALUE FillSpanWithDepthTest (
         MGD::CONTEXT* gc,
         INT32 x1,
         INT32 x2,
         INT32 y
         );

      PIXEL GetAllPlanesMask (
         ) const {
         return (m_AllPlanesMask);
         }

      //! Return a list of the capabilities of this device.
      //! Don't forget to OR in the capabilities of the base class in the derived class
      virtual CAPABILITY v_GetCapabilities (
         ) const {
         return CAPABILITY_3D;
         }

      //! Get a pointer to the depth buffer for a given location.
      //! Since this is protected, it's assumed that you've already
      //! validated the coordinates.  If the depth buffer is all in memory,
      //! this returns a pointer into that buffer.  If it's being spooled
      //! to a temporary file, it reads the requested part into a buffer
      //! and returns that buffer.  In the temporary raster case, each call
      //! to GetDepthBuffer() reuses the same buffer.  After modifying the
      //! depth buffer, you should call WriteDepthBuffer().  WriteDepthBuffer()
      //! does nothing unless the depth buffer is from a temporary raster, in
      //! which case it writes it back out.
      //! This function will return NULL if the depth buffer is not initialized
      //! or if reading from the temporary raster would cause an error.
      float* GetDepthBuffer (
         INT32 x,
         INT32 y,
         INT32 len
         );


      //! Same as GetImagePointer() but returns a const pointer.
      const UINT8* GetImagePointerConst (
         INT32 x,
         INT32 y,
         INT32 len
         ) {
         return (v_GetImagePointer(x, y, len));
         }

      //! If GetImagePointer returns a pointer directly into the frame buffer,
      //!   this function does not need to be overridden.
      //! If GetImagePointer has to actually read something (say via an X
      //!   call to the display or reading out of a raster, then this version
      //!   should just return a temporary buffer big enough to hold a single
      //!   line.
      UINT8* GetImagePointerNoRead (
         INT32 x,
         INT32 y,
         INT32 len
         ) {
         return (v_GetImagePointerNoRead(x, y, len));
         }

      //! Sets the bits, shift, and mask parameters of the DEVICEINFO
      //! Currently only handles 16 and 24 bit RGB and BGR cases
      void SetDeviceColorSpace (
         COLORSPACE colorspace
         );

      //! To be called by Create() method to set stuff up.
      ERRVALUE SetDeviceInfo (
         const DISPLAYINFO& dispinfo
         );

      //! Update the Depth Buffer. 
      //! Does nothing unless the Depth Buffer is initialized and 
      //! is using a raster for depth buffering.  
      ERRVALUE WriteDepthBuffer (
         INT32 x,
         INT32 y,
         INT32 len,
         const float* zbuf
         );

      //! Write an image buffer to the display
      //! If GetImagePointer reutrns a pointer directly into the frame buffer,
      //! this method can just return 0.  If GetImagePointer has to actually
      //! read something, this method is used to write the result back out.
      //! Typically used when drawing to a raster
      ERRVALUE WriteImageBuffer (
         INT32 x,
         INT32 y,
         INT32 len,
         UINT8* buf
         ) { 
         return (v_WriteImageBuffer(x, y, len, buf));
         }


   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Copy constructor private and unimplemented
      DEVICE(const DEVICE&);


      friend class CONTEXT;   //!< Is allowed access to FillSpan()


      float* m_zbuf;
      int m_zrhandle;      //!< Handle for Z buffer if it's a raster
      int m_zfhandle;      //!< Handle for Z buffer if it's a raster
      DISPLAYINFO m_devinfo;     //!< MUST call Set method to modify

      PROFILE m_DestProfile;
      PROFILE::INTENT m_ICMIntent;
      PROFILEPARMS_PRINTER m_ProofProfileParms;

      static void MCB_ScreenProfileChanged (
         McbAnyCallbackStruct*,
         void*
         );
      #endif // GENERATING_DOXYGEN_OUTPUT

      virtual ERRVALUE v_Clear (
         const COLOR& color
         );
      
      //! Given a color, return the Pixel value that matches (or is as close
      //! possible).  This should NOT take ICM into account.  The context will
      //! have already translated the color through the ICM transform (if any)
      //! before calling this function.
      //! This method is not const because some derived classes may update a
      //! color map or something in the process.
      virtual PIXEL v_GetColorPixel (
         const COLOR& color
         );

      //! Return a pointer to a piece of the image buffer.
      //! This only has to be implemented if HasCapability(CAPABILITY_GetImage)
      //! returns true.  The CopyRect() routines use it to read the source image.
      //! Note that this may return a pointer directly into the screen buffer
      //! or a temporary buffer into which it has read the requested data.  It's
      //! up to the implementation to decide how to handle this.
      virtual UINT8* v_GetImagePointer (
         INT32 x,
         INT32 y,
         INT32 len
         ) {
         return (0);          
         }

      //! If GetImagePointer returns a pointer directly into the frame buffer.
      //!   this function does not need to be overridden.
      //! If GetImagePointer has to actually read something (say via an X
      //!   call to the display or reading out of a raster, then this version
      //!   should just return a temporary buffer big enough to hold a single
      //!   line.
      virtual UINT8* v_GetImagePointerNoRead (
         INT32 x,
         INT32 y,
         INT32 len
         ) {
         return (v_GetImagePointer(x, y, len));
         }

      //! Given a pixel value, return the color it represents.
      //! This should NOT take ICM into account.  The context will translate
      //! the color back through the inverse ICM transform (if any)
      virtual void v_GetPixelColor (
         PIXEL pixel,
         COLOR& color
         ) const;

      //! Return true if the display is for an X drawable.
      virtual bool v_IsX11 (
         ) const {
         return (false);
         }
      
      //! Returns true if the derived class is based on an implementation
      //! where fill spans are considered "bad".  This is used by the
      //! implementation of text drawing functions to know if they should
      //! be drawn as fillspans of call FillPolygons
      virtual bool v_AvoidFillSpans (
         ) const {
         return (false);
         }

      //! Determine if the device wants low-level drawing code to anti-alias
      //! using transparency.
      //!
      //! Binary devices should override this to return false.
      //! @return true if you want anti-aliased drawing, false if not. Default implementation returns true.
      virtual bool v_UseAntiAliasing (
         ) const {
         return (true);
         }
            
      //! Write an image buffer to the display.
      //! If GetImagePointer reutrns a pointer directly into the frame buffer,
      //! this method can just return 0.  If GetImagePointer has to actually
      //! read something, this method is used to write the result back out.
      //! Typically used when drawing to a raster
      virtual ERRVALUE v_WriteImageBuffer (
         INT32 x,
         INT32 y,
         INT32 len,
         UINT8* buf
         ) { 
         return 0; 
         }

      //! Set the colormap for the display.  Derived class should override this
      //! if it cares about colormaps.  If not, the default version just ignores
      //! the caller.
      //!
      //! XXX Old version took a COLORMAPINFO which was passed to 
      //! CompOptmFromColMap().  Has RedBits, GreenBits, BlueBits.
      //! What are these?
      virtual ERRVALUE v_ChangeColorMap (
         const SIMPLE_ARRAY<COLOR>& colors
         );

      //! Create a GC for drawing.  
      //!
      //! Derived classes may override this and make it return anything
      //! derived from MGD::CONTEXT.  MGD::CONTEXT's constructor is private, so
      //! this is the only way for calling code to create a GC.
      //! 
      virtual MGD::CONTEXT* v_CreateContext (
         );

      //! If the display is going to support 3D, then it should allocate its depth
      //! buffer here.  If overriding this, also be sure to override
      //! Is3DInitialized() so that it will return true if DepthInit3D() has been
      //! called and override CanDo3D() to return true.
      //!
      //! This implementation allocates an in-memory buffer if the device
      //! size is <= 1024 x 1024.  If it's bigger, it allocates a temporary
      //! raster to hold the data.
      //!
      //! 3D implementation code can call GetDepthBuffer() to get the depth
      //! buffer for a given span of data.
      virtual ERRVALUE v_DepthInit3D (
         );
      
      //! Return the "native" COLORSPACE used by the display.
      //! Image operations using this colorspace will be more effeciant.
      //! Default implementation determines the colorspace from the 
      //! DeviceInfo
      virtual COLORSPACE v_GetColorSpace (
         ) const;

      //! return the depth at a given pixel location.  
      //! This is GC-indapendant.
      virtual float v_GetDepth3D (
         INT32 x, 
         INT32 y
         );

      //! Return the number of bytes needed to hold one line of image data.
      //! Should be overridden by derived class unless images are not possible
      //! (such as a pen plotter)
      virtual INT32 v_GetLineBytes (
         ) const {
         return (0);
         }

      //! Determine if full image lines are needed (no tiled output).
      virtual bool v_GetNeedFullImageLine (
         ) const {
         return (false);
         }

      //! Scan the image for color usage.
      //! (may not need for all implementations?)
      virtual ERRVALUE v_ScanColorUse (
         HISTORGB& historgb
         ) {
         return (0);
         }

   };

      
// NOTE:  Need methods on GC to get/set styles and other stuff that we used to store in the display
//        but was set by macros and inline functions.
   
//! \class CONTEXT
//! \brief Base class for all your drawing needs.  
class CONTEXT {
   public:
      // Note, default Constructor is protected

      //! Base class for private data.
      //! Basically just a class with a pure virtual destructor so that we
      //!   can delete one without knowing what it is.  Used for Get/SetPrivData
      class PRIVDATA {
         public:
            PRIVDATA() {}
            virtual ~PRIVDATA() {}
         };

      virtual ~CONTEXT();

      //! Allocate a private data index.
      //! This is uses as an argument to GetPrivData and SetPrivData
      static int AllocPrivDataIndex (
         );

      //! Add to the clip mask drawing exclusion area using a rectangle.
      //! Areas OUTSIDE the rectangle will be clipped (i.e., they won't draw)
      //! The default method twiddles bits in a clip device which is used
      //! as a bitmask through which all FillSpans operate.
      //! ( Currently only used in autolabl.c, and only)
      //! Should be replaced by IntersectClipRegion()
      ERRVALUE AddExteriorToClip (
         const LRECT2D& rect
         );

      //! Add to the clip mask drawing exclusion area using a DRECT2D.
      //! Areas added will NOT draw (i.e. they WILL be clipped).
      //! The default method clears bits in a clip device which is used
      //! as a bitmask through which all FillSpans operate.
      ERRVALUE AddToClip (
         const DRECT2D& rect
         );

      //! Add to the clip mask drawing exclusion area using an LRECT2D.
      //! Areas added will NOT draw (i.e. they WILL be clipped).
      //! The default method clears bits in a clip device which is used
      //! as a bitmask through which all FillSpans operate.
      ERRVALUE AddToClip (
         const LRECT2D& rect
         );

      //! Add to the clip mask drawing exclusion area using a POLYLINE.
      //! Areas added will NOT draw (i.e. they WILL be clipped).
      //! The default method clears bits in a clip device which is used
      //! as a bitmask through which all FillSpans operate.
      ERRVALUE AddToClip (
         const POLYLINE& polyline
         );

      //! Add to the clip mask drawing exclusion area using a REGION2D.
      //! Areas added will NOT draw (i.e. they WILL be clipped).
      //! The default method clears bits in a clip device which is used
      //! as a bitmask through which all FillSpans operate.
      ERRVALUE AddToClip (
         const REGION2D& region
         );

      //! Intersects the current clip region with a DRECT2D.
      //! The resulting region is made the new clip region.
      //! Only areas inside the clip region will be drawn.
      ERRVALUE IntersectClip (
         const DRECT2D& rect
         );

      //! Intersects the current clip region with an LRECT2D.
      //! The resulting region is made the new clip region.