layout/base/UnitTransforms.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef MOZ_UNIT_TRANSFORMS_H_
   8 #define MOZ_UNIT_TRANSFORMS_H_
   9
  10 #include "Units.h"
  11 #include "mozilla/gfx/Matrix.h"
  12 #include "mozilla/Maybe.h"
  13 #include "nsRegion.h"
  14
  15 namespace mozilla {
  16
  17 // Convenience functions for converting an entity from one strongly-typed
  18 // coordinate system to another without changing the values it stores (this
  19 // can be thought of as a cast).
  20 // To use these functions, you must provide a justification for each use!
  21 // Feel free to add more justifications to PixelCastJustification, along with
  22 // a comment that explains under what circumstances it is appropriate to use.
  23
  24 enum class PixelCastJustification : uint8_t {
  25   // For the root layer, Screen Pixel = Parent Layer Pixel.
  26   ScreenIsParentLayerForRoot,
  27   // On the layout side, Screen Pixel = LayoutDevice at the outer-window level.
  28   LayoutDeviceIsScreenForBounds,
  29   // For the root layer, Render Target Pixel = Parent Layer Pixel.
  30   RenderTargetIsParentLayerForRoot,
  31   // For the root composition size we want to view it as layer pixels in any
  32   // layer
  33   ParentLayerToLayerForRootComposition,
  34   // The Layer coordinate space for one layer is the ParentLayer coordinate
  35   // space for its children
  36   MovingDownToChildren,
  37   // The transform that is usually used to convert between two coordinate
  38   // systems is not available (for example, because the object that stores it
  39   // is being destroyed), so fall back to the identity.
  40   TransformNotAvailable,
  41   // When an OS event is initially constructed, its reference point is
  42   // technically in screen pixels, as it has not yet accounted for any
  43   // asynchronous transforms. This justification is for viewing the initial
  44   // reference point as a screen point. The reverse is useful when synthetically
  45   // created WidgetEvents need to be converted back to InputData.
  46   LayoutDeviceIsScreenForUntransformedEvent,
  47   // Similar to LayoutDeviceIsScreenForUntransformedEvent, PBrowser handles
  48   // some widget/tab dimension information as the OS does -- in screen units.
  49   LayoutDeviceIsScreenForTabDims,
  50   // A combination of LayoutDeviceIsScreenForBounds and
  51   // ScreenIsParentLayerForRoot, which is how we're using it.
  52   LayoutDeviceIsParentLayerForRCDRSF,
  53   // Used to treat the product of AsyncTransformComponentMatrix objects
  54   // as an AsyncTransformMatrix. See the definitions of these matrices in
  55   // LayersTypes.h for details.
  56   MultipleAsyncTransforms,
  57   // We have reason to believe a layer doesn't have a local transform.
  58   // Should only be used if we've already checked or asserted this.
  59   NoTransformOnLayer,
  60   // LayerPixels are ImagePixels
  61   LayerIsImage,
  62   // External pixels are the same scale as screen pixels
  63   ExternalIsScreen,
  64   // LayerToScreenMatrix is used as LayoutDeviceToLayoutDevice, because
  65   // out-of-process iframes uses LayoutDevicePixels as the type system-visible
  66   // type of their top-level event coordinate space even if technically
  67   // inaccurate.
  68   ContentProcessIsLayerInUiProcess,
  69   // Propagating TransformToAncestorScale to a child process.
  70   PropagatingToChildProcess,
  71   // A quantity represents a proportion of a page length, e.g. "0.5 pages".
  72   // The proportion does not need to be scaled when converting between
  73   // units (the page length that it's mutlipled by will be scaled instead).
  74   DeltaIsPageProportion,
  75   // Used to cast between CSS and OuterCSS pixels when moving between code
  76   // that deals with content outside a scroll frame generically (which would
  77   // use CSS pixels) and code related to the scroll frame in APZ (which wants
  78   // such quantities in OuterCSS pixels).
  79   CSSPixelsOfSurroundingContent,
  80 };
  81
  82 template <class TargetUnits, class SourceUnits>
  83 gfx::CoordTyped<TargetUnits> ViewAs(const gfx::CoordTyped<SourceUnits>& aCoord,
  84                                     PixelCastJustification) {
  85   return gfx::CoordTyped<TargetUnits>(aCoord.value);
  86 }
  87 template <class TargetUnits, class SourceUnits>
  88 gfx::IntCoordTyped<TargetUnits> ViewAs(
  89     const gfx::IntCoordTyped<SourceUnits>& aCoord, PixelCastJustification) {
  90   return gfx::IntCoordTyped<TargetUnits>(aCoord.value);
  91 }
  92 template <class TargetUnits, class SourceUnits>
  93 gfx::SizeTyped<TargetUnits> ViewAs(const gfx::SizeTyped<SourceUnits>& aSize,
  94                                    PixelCastJustification) {
  95   return gfx::SizeTyped<TargetUnits>(aSize.width, aSize.height);
  96 }
  97 template <class TargetUnits, class SourceUnits>
  98 gfx::IntSizeTyped<TargetUnits> ViewAs(
  99     const gfx::IntSizeTyped<SourceUnits>& aSize, PixelCastJustification) {
 100   return gfx::IntSizeTyped<TargetUnits>(aSize.width, aSize.height);
 101 }
 102 template <class TargetUnits, class SourceUnits>
 103 gfx::PointTyped<TargetUnits> ViewAs(const gfx::PointTyped<SourceUnits>& aPoint,
 104                                     PixelCastJustification) {
 105   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 106 }
 107 template <class TargetUnits, class SourceUnits>
 108 gfx::IntPointTyped<TargetUnits> ViewAs(
 109     const gfx::IntPointTyped<SourceUnits>& aPoint, PixelCastJustification) {
 110   return gfx::IntPointTyped<TargetUnits>(aPoint.x, aPoint.y);
 111 }
 112 template <class TargetUnits, class SourceUnits>
 113 gfx::RectTyped<TargetUnits> ViewAs(const gfx::RectTyped<SourceUnits>& aRect,
 114                                    PixelCastJustification) {
 115   return gfx::RectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 116                                      aRect.Height());
 117 }
 118 template <class TargetUnits, class SourceUnits>
 119 gfx::IntRectTyped<TargetUnits> ViewAs(
 120     const gfx::IntRectTyped<SourceUnits>& aRect, PixelCastJustification) {
 121   return gfx::IntRectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 122                                         aRect.Height());
 123 }
 124 template <class TargetUnits, class SourceUnits>
 125 gfx::MarginTyped<TargetUnits> ViewAs(
 126     const gfx::MarginTyped<SourceUnits>& aMargin, PixelCastJustification) {
 127   return gfx::MarginTyped<TargetUnits>(aMargin.top.value, aMargin.right.value,
 128                                        aMargin.bottom.value,
 129                                        aMargin.left.value);
 130 }
 131 template <class TargetUnits, class SourceUnits>
 132 gfx::IntMarginTyped<TargetUnits> ViewAs(
 133     const gfx::IntMarginTyped<SourceUnits>& aMargin, PixelCastJustification) {
 134   return gfx::IntMarginTyped<TargetUnits>(aMargin.top, aMargin.right,
 135                                           aMargin.bottom, aMargin.left);
 136 }
 137 template <class TargetUnits, class SourceUnits>
 138 gfx::IntRegionTyped<TargetUnits> ViewAs(
 139     const gfx::IntRegionTyped<SourceUnits>& aRegion, PixelCastJustification) {
 140   return gfx::IntRegionTyped<TargetUnits>::FromUnknownRegion(
 141       aRegion.ToUnknownRegion());
 142 }
 143 template <class NewTargetUnits, class OldTargetUnits, class SourceUnits>
 144 gfx::ScaleFactor<SourceUnits, NewTargetUnits> ViewTargetAs(
 145     const gfx::ScaleFactor<SourceUnits, OldTargetUnits>& aScaleFactor,
 146     PixelCastJustification) {
 147   return gfx::ScaleFactor<SourceUnits, NewTargetUnits>(aScaleFactor.scale);
 148 }
 149 template <class NewTargetUnits, class OldTargetUnits, class SourceUnits>
 150 gfx::ScaleFactors2D<SourceUnits, NewTargetUnits> ViewTargetAs(
 151     const gfx::ScaleFactors2D<SourceUnits, OldTargetUnits>& aScaleFactors,
 152     PixelCastJustification) {
 153   return gfx::ScaleFactors2D<SourceUnits, NewTargetUnits>(aScaleFactors.xScale,
 154                                                           aScaleFactors.yScale);
 155 }
 156 template <class TargetUnits, class SourceUnits>
 157 Maybe<gfx::IntRectTyped<TargetUnits>> ViewAs(
 158     const Maybe<gfx::IntRectTyped<SourceUnits>>& aRect,
 159     PixelCastJustification aJustification) {
 160   if (aRect.isSome()) {
 161     return Some(ViewAs<TargetUnits>(aRect.value(), aJustification));
 162   }
 163   return Nothing();
 164 }
 165 // Unlike the other functions in this category, these functions take the
 166 // target matrix or scale type, rather than its source and target unit types, as
 167 // the explicit template argument, so an example invocation is:
 168 //    ViewAs<ScreenToLayerMatrix4x4>(otherTypedMatrix, justification)
 169 // The reason is that if it took the source and target unit types as two
 170 // template arguments, there may be some confusion as to which is the
 171 // source and which is the target.
 172 template <class TargetMatrix, class SourceMatrixSourceUnits,
 173           class SourceMatrixTargetUnits>
 174 TargetMatrix ViewAs(const gfx::Matrix4x4Typed<SourceMatrixSourceUnits,
 175                                               SourceMatrixTargetUnits>& aMatrix,
 176                     PixelCastJustification) {
 177   return aMatrix.template Cast<TargetMatrix>();
 178 }
 179 template <class TargetMatrix, class SourceMatrixSourceUnits,
 180           class SourceMatrixTargetUnits>
 181 Maybe<TargetMatrix> ViewAs(
 182     const Maybe<gfx::Matrix4x4Typed<SourceMatrixSourceUnits,
 183                                     SourceMatrixTargetUnits>>& aMatrix,
 184     PixelCastJustification) {
 185   if (aMatrix.isSome()) {
 186     return Some(aMatrix->template Cast<TargetMatrix>());
 187   }
 188   return Nothing();
 189 }
 190 template <class TargetScale, class SourceScaleSourceUnits,
 191           class SourceScaleTargetUnits>
 192 TargetScale ViewAs(const gfx::ScaleFactor<SourceScaleSourceUnits,
 193                                           SourceScaleTargetUnits>& aScale,
 194                    PixelCastJustification) {
 195   return TargetScale{aScale.scale};
 196 }
 197
 198 // A non-member overload of ToUnknownMatrix() for use on a Maybe<Matrix>.
 199 // We can't make this a member because we can't inject a member into Maybe.
 200 template <typename SourceUnits, typename TargetUnits>
 201 Maybe<gfx::Matrix4x4> ToUnknownMatrix(
 202     const Maybe<gfx::Matrix4x4Typed<SourceUnits, TargetUnits>>& aMatrix) {
 203   if (aMatrix.isSome()) {
 204     return Some(aMatrix->ToUnknownMatrix());
 205   }
 206   return Nothing();
 207 }
 208
 209 // Convenience functions for casting untyped entities to typed entities.
 210 // Using these functions does not require a justification, but once we convert
 211 // all code to use strongly typed units they should not be needed any longer.
 212 template <class TargetUnits>
 213 gfx::CoordTyped<TargetUnits> ViewAs(const gfx::Coord& aCoord) {
 214   return gfx::CoordTyped<TargetUnits>(aCoord.value);
 215 }
 216 template <class TargetUnits>
 217 gfx::PointTyped<TargetUnits> ViewAs(const gfxPoint& aPoint) {
 218   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 219 }
 220 template <class TargetUnits>
 221 gfx::PointTyped<TargetUnits> ViewAs(const gfx::Point& aPoint) {
 222   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 223 }
 224 template <class TargetUnits>
 225 gfx::RectTyped<TargetUnits> ViewAs(const gfx::Rect& aRect) {
 226   return gfx::RectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 227                                      aRect.Height());
 228 }
 229 template <class TargetUnits>
 230 gfx::IntSizeTyped<TargetUnits> ViewAs(const nsIntSize& aSize) {
 231   return gfx::IntSizeTyped<TargetUnits>(aSize.width, aSize.height);
 232 }
 233 template <class TargetUnits>
 234 gfx::IntPointTyped<TargetUnits> ViewAs(const nsIntPoint& aPoint) {
 235   return gfx::IntPointTyped<TargetUnits>(aPoint.x, aPoint.y);
 236 }
 237 template <class TargetUnits>
 238 gfx::IntRectTyped<TargetUnits> ViewAs(const nsIntRect& aRect) {
 239   return gfx::IntRectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 240                                         aRect.Height());
 241 }
 242 template <class TargetUnits>
 243 gfx::IntRegionTyped<TargetUnits> ViewAs(const nsIntRegion& aRegion) {
 244   return gfx::IntRegionTyped<TargetUnits>::FromUnknownRegion(aRegion);
 245 }
 246 // Unlike the other functions in this category, these functions take the
 247 // target matrix or scale type, rather than its source and target unit
 248 // types, as the template argument, so an example invocation is:
 249 //    ViewAs<ScreenToLayerMatrix4x4>(untypedMatrix)
 250 // The reason is that if it took the source and target unit types as two
 251 // template arguments, there may be some confusion as to which is the
 252 // source and which is the target.
 253 template <class TypedScale>
 254 TypedScale ViewAs(const Scale2D& aScale) {
 255   return TypedScale(aScale.xScale, aScale.yScale);
 256 }
 257 template <class TypedMatrix>
 258 TypedMatrix ViewAs(const gfx::Matrix4x4& aMatrix) {
 259   return TypedMatrix::FromUnknownMatrix(aMatrix);
 260 }
 261
 262 // Convenience functions for transforming an entity from one strongly-typed
 263 // coordinate system to another using the provided transformation matrix.
 264 template <typename TargetUnits, typename SourceUnits>
 265 static gfx::PointTyped<TargetUnits> TransformBy(
 266     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 267     const gfx::PointTyped<SourceUnits>& aPoint) {
 268   return aTransform.TransformPoint(aPoint);
 269 }
 270 template <typename TargetUnits, typename SourceUnits>
 271 static gfx::IntPointTyped<TargetUnits> TransformBy(
 272     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 273     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 274   return RoundedToInt(
 275       TransformBy(aTransform, gfx::PointTyped<SourceUnits>(aPoint)));
 276 }
 277 template <typename TargetUnits, typename SourceUnits>
 278 static gfx::RectTyped<TargetUnits> TransformBy(
 279     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 280     const gfx::RectTyped<SourceUnits>& aRect) {
 281   return aTransform.TransformBounds(aRect);
 282 }
 283 template <typename TargetUnits, typename SourceUnits>
 284 static gfx::IntRectTyped<TargetUnits> TransformBy(
 285     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 286     const gfx::IntRectTyped<SourceUnits>& aRect) {
 287   return RoundedToInt(
 288       TransformBy(aTransform, gfx::RectTyped<SourceUnits>(aRect)));
 289 }
 290 template <typename TargetUnits, typename SourceUnits>
 291 static gfx::IntRegionTyped<TargetUnits> TransformBy(
 292     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 293     const gfx::IntRegionTyped<SourceUnits>& aRegion) {
 294   return ViewAs<TargetUnits>(
 295       aRegion.ToUnknownRegion().Transform(aTransform.ToUnknownMatrix()));
 296 }
 297
 298 // Transform |aVector|, which is anchored at |aAnchor|, by the given transform
 299 // matrix, yielding a point in |TargetUnits|.
 300 // The anchor is necessary because with 3D tranforms, the location of the
 301 // vector can affect the result of the transform.
 302 template <typename TargetUnits, typename SourceUnits>
 303 static gfx::PointTyped<TargetUnits> TransformVector(
 304     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 305     const gfx::PointTyped<SourceUnits>& aVector,
 306     const gfx::PointTyped<SourceUnits>& aAnchor) {
 307   gfx::PointTyped<TargetUnits> transformedStart =
 308       TransformBy(aTransform, aAnchor);
 309   gfx::PointTyped<TargetUnits> transformedEnd =
 310       TransformBy(aTransform, aAnchor + aVector);
 311   return transformedEnd - transformedStart;
 312 }
 313
 314 // UntransformBy() and UntransformVector() are like TransformBy() and
 315 // TransformVector(), respectively, but are intended for cases where
 316 // the transformation matrix is the inverse of a 3D projection. When
 317 // using such transforms, the resulting Point4D is only meaningful
 318 // if it has a positive w-coordinate. To handle this, these functions
 319 // return a Maybe object which contains a value if and only if the
 320 // result is meaningful
 321 template <typename TargetUnits, typename SourceUnits>
 322 static Maybe<gfx::PointTyped<TargetUnits>> UntransformBy(
 323     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 324     const gfx::PointTyped<SourceUnits>& aPoint) {
 325   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(aPoint);
 326   if (!point.HasPositiveWCoord()) {
 327     return Nothing();
 328   }
 329   return Some(point.As2DPoint());
 330 }
 331 template <typename TargetUnits, typename SourceUnits>
 332 static Maybe<gfx::IntPointTyped<TargetUnits>> UntransformBy(
 333     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 334     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 335   gfx::PointTyped<SourceUnits> p = aPoint;
 336   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(p);
 337   if (!point.HasPositiveWCoord()) {
 338     return Nothing();
 339   }
 340   return Some(RoundedToInt(point.As2DPoint()));
 341 }
 342
 343 // The versions of UntransformBy() that take a rectangle also take a clip,
 344 // which represents the bounds within which the target must fall. The
 345 // result of the transform is intersected with this clip, and is considered
 346 // meaningful if the intersection is not empty.
 347 template <typename TargetUnits, typename SourceUnits>
 348 static Maybe<gfx::RectTyped<TargetUnits>> UntransformBy(
 349     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 350     const gfx::RectTyped<SourceUnits>& aRect,
 351     const gfx::RectTyped<TargetUnits>& aClip) {
 352   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 353   if (rect.IsEmpty()) {
 354     return Nothing();
 355   }
 356   return Some(rect);
 357 }
 358 template <typename TargetUnits, typename SourceUnits>
 359 static Maybe<gfx::IntRectTyped<TargetUnits>> UntransformBy(
 360     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 361     const gfx::IntRectTyped<SourceUnits>& aRect,
 362     const gfx::IntRectTyped<TargetUnits>& aClip) {
 363   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 364   if (rect.IsEmpty()) {
 365     return Nothing();
 366   }
 367   return Some(RoundedToInt(rect));
 368 }
 369
 370 template <typename TargetUnits, typename SourceUnits>
 371 static Maybe<gfx::PointTyped<TargetUnits>> UntransformVector(
 372     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 373     const gfx::PointTyped<SourceUnits>& aVector,
 374     const gfx::PointTyped<SourceUnits>& aAnchor) {
 375   gfx::Point4DTyped<TargetUnits> projectedAnchor =
 376       aTransform.ProjectPoint(aAnchor);
 377   gfx::Point4DTyped<TargetUnits> projectedTarget =
 378       aTransform.ProjectPoint(aAnchor + aVector);
 379   if (!projectedAnchor.HasPositiveWCoord() ||
 380       !projectedTarget.HasPositiveWCoord()) {
 381     return Nothing();
 382   }
 383   return Some(projectedTarget.As2DPoint() - projectedAnchor.As2DPoint());
 384 }
 385
 386 }  // namespace mozilla
 387
 388 #endif