gfx/public/nsIRegion.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsIRegion_h___
  39 #define nsIRegion_h___
  40
  41 #include "nscore.h"
  42 #include "nsISupports.h"
  43 #include "nsRect.h"
  44
  45 enum nsRegionComplexity
  46 {
  47   eRegionComplexity_empty = 0,
  48   eRegionComplexity_rect = 1,
  49   eRegionComplexity_complex = 2
  50 };
  51
  52 typedef struct
  53 {
  54   PRInt32   x;
  55   PRInt32   y;
  56   PRUint32  width;
  57   PRUint32  height;
  58 } nsRegionRect;
  59
  60 typedef struct
  61 {
  62   PRUint32      mNumRects;    //number of actual rects in the mRects array
  63   PRUint32      mRectsLen;    //length, in rects, of the mRects array
  64   PRUint32      mArea;        //area of the covered portion of the region
  65   nsRegionRect  mRects[1];
  66 } nsRegionRectSet;
  67
  68 // An implementation of a region primitive that can be used to
  69 // represent arbitrary pixel areas. Probably implemented on top
  70 // of the native region primitive. The assumption is that, at worst,
  71 // it is a rectangle list.
  72
  73 #define NS_IREGION_IID   \
  74 { 0x8ef366e0, 0xee94, 0x11d1,    \
  75 { 0xa8, 0x2a, 0x00, 0x40, 0x95, 0x9a, 0x28, 0xc9 } }
  76
  77 class nsIRegion : public nsISupports
  78 {
  79 public:
  80   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IREGION_IID)
  81
  82   virtual nsresult Init(void) = 0;
  83
  84   /**
  85   * copy operator equivalent that takes another region
  86   *
  87   * @param      region to copy
  88   * @return     void
  89   *
  90   **/
  91
  92   virtual void SetTo(const nsIRegion &aRegion) = 0;
  93
  94   /**
  95   * copy operator equivalent that takes a rect
  96   *
  97   * @param      aX xoffset of rect to set region to
  98   * @param      aY yoffset of rect to set region to
  99   * @param      aWidth width of rect to set region to
 100   * @param      aHeight height of rect to set region to
 101   * @return     void
 102   *
 103   **/
 104
 105   virtual void SetTo(PRInt32 aX, PRInt32 aY, PRInt32 aWidth, PRInt32 aHeight) = 0;
 106
 107   /**
 108   * destructively intersect another region with this one
 109   *
 110   * @param      region to intersect
 111   * @return     void
 112   *
 113   **/
 114
 115   virtual void Intersect(const nsIRegion &aRegion) = 0;
 116
 117   /**
 118   * destructively intersect a rect with this region
 119   *
 120   * @param      aX xoffset of rect to intersect with region
 121   * @param      aY yoffset of rect to intersect with region
 122   * @param      aWidth width of rect to intersect with region
 123   * @param      aHeight height of rect to intersect with region
 124   * @return     void
 125   *
 126   **/
 127
 128   virtual void Intersect(PRInt32 aX, PRInt32 aY, PRInt32 aWidth, PRInt32 aHeight) = 0;
 129
 130   /**
 131   * destructively union another region with this one
 132   *
 133   * @param      region to union
 134   * @return     void
 135   *
 136   **/
 137
 138   virtual void Union(const nsIRegion &aRegion) = 0;
 139
 140   /**
 141   * destructively union a rect with this region
 142   *
 143   * @param      aX xoffset of rect to union with region
 144   * @param      aY yoffset of rect to union with region
 145   * @param      aWidth width of rect to union with region
 146   * @param      aHeight height of rect to union with region
 147   * @return     void
 148   *
 149   **/
 150
 151   virtual void Union(PRInt32 aX, PRInt32 aY, PRInt32 aWidth, PRInt32 aHeight) = 0;
 152
 153   /**
 154   * destructively subtract another region with this one
 155   *
 156   * @param      region to subtract
 157   * @return     void
 158   *
 159   **/
 160
 161   virtual void Subtract(const nsIRegion &aRegion) = 0;
 162
 163   /**
 164   * destructively subtract a rect from this region
 165   *
 166   * @param      aX xoffset of rect to subtract with region
 167   * @param      aY yoffset of rect to subtract with region
 168   * @param      aWidth width of rect to subtract with region
 169   * @param      aHeight height of rect to subtract with region
 170   * @return     void
 171   *
 172   **/
 173
 174   virtual void Subtract(PRInt32 aX, PRInt32 aY, PRInt32 aWidth, PRInt32 aHeight) = 0;
 175
 176   /**
 177   * is this region empty? i.e. does it contain any pixels
 178   *
 179   * @param      none
 180   * @return     returns whether the region is empty
 181   *
 182   **/
 183
 184   virtual PRBool IsEmpty(void) = 0;
 185
 186   /**
 187   * == operator equivalent i.e. do the regions contain exactly
 188   * the same pixels
 189   *
 190   * @param      region to compare
 191   * @return     whether the regions are identical
 192   *
 193   **/
 194
 195   virtual PRBool IsEqual(const nsIRegion &aRegion) = 0;
 196
 197   /**
 198   * returns the bounding box of the region i.e. the smallest
 199   * rectangle that completely contains the region.
 200   *
 201   * @param      aX out parameter for xoffset of bounding rect for region
 202   * @param      aY out parameter for yoffset of bounding rect for region
 203   * @param      aWidth out parameter for width of bounding rect for region
 204   * @param      aHeight out parameter for height of bounding rect for region
 205   * @return     void
 206   *
 207   **/
 208   virtual void GetBoundingBox(PRInt32 *aX, PRInt32 *aY, PRInt32 *aWidth, PRInt32 *aHeight) = 0;
 209
 210   /**
 211   * offsets the region in x and y
 212   *
 213   * @param  xoffset  pixel offset in x
 214   * @param  yoffset  pixel offset in y
 215   * @return          void
 216   *
 217   **/
 218   virtual void Offset(PRInt32 aXOffset, PRInt32 aYOffset) = 0;
 219
 220   /**
 221   * does the region intersect the rectangle?
 222   *
 223   * @param      rect to check for containment
 224   * @return     true if the region intersects the rect
 225   *
 226   **/
 227
 228   virtual PRBool ContainsRect(PRInt32 aX, PRInt32 aY, PRInt32 aWidth, PRInt32 aHeight) = 0;
 229
 230   /**
 231    * get the set of rects which make up this region. the aRects
 232    * parameter must be freed by calling FreeRects before the region
 233    * is deleted. aRects may be passed in again when requesting
 234    * the rect list as a recycling method.
 235    *
 236    * @param  aRects out parameter containing set of rects
 237    *                comprising the region
 238    * @return error status
 239    *
 240    **/
 241   NS_IMETHOD GetRects(nsRegionRectSet **aRects) = 0;
 242
 243   /**
 244    * Free a rect set returned by GetRects.
 245    *
 246    * @param  aRects rects to free
 247    * @return error status
 248    *
 249    **/
 250   NS_IMETHOD FreeRects(nsRegionRectSet *aRects) = 0;
 251
 252   /**
 253    * Get the native region that this nsIRegion represents.
 254    * @param aRegion out parameter for native region handle
 255    * @return error status
 256    **/
 257   NS_IMETHOD GetNativeRegion(void *&aRegion) const = 0;
 258
 259   /**
 260    * Get the complexity of the region as defined by the
 261    * nsRegionComplexity enum.
 262    * @param aComplexity out parameter for region complexity
 263    * @return error status
 264    **/
 265   NS_IMETHOD GetRegionComplexity(nsRegionComplexity &aComplexity) const = 0;
 266
 267   /**
 268    * get the number of rects which make up this region.
 269    *
 270    * @param  aRects out parameter containing the number of rects
 271    *                comprising the region
 272    * @return error status
 273    *
 274    **/
 275   NS_IMETHOD GetNumRects(PRUint32 *aRects) const = 0;
 276 };
 277
 278 NS_DEFINE_STATIC_IID_ACCESSOR(nsIRegion, NS_IREGION_IID)
 279
 280 #endif  // nsIRegion_h___