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 };
  76
  77 template <class TargetUnits, class SourceUnits>
  78 gfx::CoordTyped<TargetUnits> ViewAs(const gfx::CoordTyped<SourceUnits>& aCoord,
  79                                     PixelCastJustification) {
  80   return gfx::CoordTyped<TargetUnits>(aCoord.value);
  81 }
  82 template <class TargetUnits, class SourceUnits>
  83 gfx::IntCoordTyped<TargetUnits> ViewAs(
  84     const gfx::IntCoordTyped<SourceUnits>& aCoord, PixelCastJustification) {
  85   return gfx::IntCoordTyped<TargetUnits>(aCoord.value);
  86 }
  87 template <class TargetUnits, class SourceUnits>
  88 gfx::SizeTyped<TargetUnits> ViewAs(const gfx::SizeTyped<SourceUnits>& aSize,
  89                                    PixelCastJustification) {
  90   return gfx::SizeTyped<TargetUnits>(aSize.width, aSize.height);
  91 }
  92 template <class TargetUnits, class SourceUnits>
  93 gfx::IntSizeTyped<TargetUnits> ViewAs(
  94     const gfx::IntSizeTyped<SourceUnits>& aSize, PixelCastJustification) {
  95   return gfx::IntSizeTyped<TargetUnits>(aSize.width, aSize.height);
  96 }
  97 template <class TargetUnits, class SourceUnits>
  98 gfx::PointTyped<TargetUnits> ViewAs(const gfx::PointTyped<SourceUnits>& aPoint,
  99                                     PixelCastJustification) {
 100   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 101 }
 102 template <class TargetUnits, class SourceUnits>
 103 gfx::IntPointTyped<TargetUnits> ViewAs(
 104     const gfx::IntPointTyped<SourceUnits>& aPoint, PixelCastJustification) {
 105   return gfx::IntPointTyped<TargetUnits>(aPoint.x, aPoint.y);
 106 }
 107 template <class TargetUnits, class SourceUnits>
 108 gfx::RectTyped<TargetUnits> ViewAs(const gfx::RectTyped<SourceUnits>& aRect,
 109                                    PixelCastJustification) {
 110   return gfx::RectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 111                                      aRect.Height());
 112 }
 113 template <class TargetUnits, class SourceUnits>
 114 gfx::IntRectTyped<TargetUnits> ViewAs(
 115     const gfx::IntRectTyped<SourceUnits>& aRect, PixelCastJustification) {
 116   return gfx::IntRectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 117                                         aRect.Height());
 118 }
 119 template <class TargetUnits, class SourceUnits>
 120 gfx::MarginTyped<TargetUnits> ViewAs(
 121     const gfx::MarginTyped<SourceUnits>& aMargin, PixelCastJustification) {
 122   return gfx::MarginTyped<TargetUnits>(aMargin.top, aMargin.right,
 123                                        aMargin.bottom, aMargin.left);
 124 }
 125 template <class TargetUnits, class SourceUnits>
 126 gfx::IntMarginTyped<TargetUnits> ViewAs(
 127     const gfx::IntMarginTyped<SourceUnits>& aMargin, PixelCastJustification) {
 128   return gfx::IntMarginTyped<TargetUnits>(aMargin.top, aMargin.right,
 129                                           aMargin.bottom, aMargin.left);
 130 }
 131 template <class TargetUnits, class SourceUnits>
 132 gfx::IntRegionTyped<TargetUnits> ViewAs(
 133     const gfx::IntRegionTyped<SourceUnits>& aRegion, PixelCastJustification) {
 134   return gfx::IntRegionTyped<TargetUnits>::FromUnknownRegion(
 135       aRegion.ToUnknownRegion());
 136 }
 137 template <class NewTargetUnits, class OldTargetUnits, class SourceUnits>
 138 gfx::ScaleFactor<SourceUnits, NewTargetUnits> ViewTargetAs(
 139     const gfx::ScaleFactor<SourceUnits, OldTargetUnits>& aScaleFactor,
 140     PixelCastJustification) {
 141   return gfx::ScaleFactor<SourceUnits, NewTargetUnits>(aScaleFactor.scale);
 142 }
 143 template <class NewTargetUnits, class OldTargetUnits, class SourceUnits>
 144 gfx::ScaleFactors2D<SourceUnits, NewTargetUnits> ViewTargetAs(
 145     const gfx::ScaleFactors2D<SourceUnits, OldTargetUnits>& aScaleFactors,
 146     PixelCastJustification) {
 147   return gfx::ScaleFactors2D<SourceUnits, NewTargetUnits>(aScaleFactors.xScale,
 148                                                           aScaleFactors.yScale);
 149 }
 150 template <class TargetUnits, class SourceUnits>
 151 Maybe<gfx::IntRectTyped<TargetUnits>> ViewAs(
 152     const Maybe<gfx::IntRectTyped<SourceUnits>>& aRect,
 153     PixelCastJustification aJustification) {
 154   if (aRect.isSome()) {
 155     return Some(ViewAs<TargetUnits>(aRect.value(), aJustification));
 156   }
 157   return Nothing();
 158 }
 159 // Unlike the other functions in this category, these functions take the
 160 // target matrix type, rather than its source and target unit types, as
 161 // the explicit template argument, so an example invocation is:
 162 //    ViewAs<ScreenToLayerMatrix4x4>(otherTypedMatrix, justification)
 163 // The reason is that if it took the source and target unit types as two
 164 // template arguments, there may be some confusion as to which is the
 165 // source and which is the target.
 166 template <class TargetMatrix, class SourceMatrixSourceUnits,
 167           class SourceMatrixTargetUnits>
 168 TargetMatrix ViewAs(const gfx::Matrix4x4Typed<SourceMatrixSourceUnits,
 169                                               SourceMatrixTargetUnits>& aMatrix,
 170                     PixelCastJustification) {
 171   return TargetMatrix::FromUnknownMatrix(aMatrix.ToUnknownMatrix());
 172 }
 173 template <class TargetMatrix, class SourceMatrixSourceUnits,
 174           class SourceMatrixTargetUnits>
 175 Maybe<TargetMatrix> ViewAs(
 176     const Maybe<gfx::Matrix4x4Typed<SourceMatrixSourceUnits,
 177                                     SourceMatrixTargetUnits>>& aMatrix,
 178     PixelCastJustification) {
 179   if (aMatrix.isSome()) {
 180     return Some(TargetMatrix::FromUnknownMatrix(aMatrix->ToUnknownMatrix()));
 181   }
 182   return Nothing();
 183 }
 184
 185 // A non-member overload of ToUnknownMatrix() for use on a Maybe<Matrix>.
 186 // We can't make this a member because we can't inject a member into Maybe.
 187 template <typename SourceUnits, typename TargetUnits>
 188 Maybe<gfx::Matrix4x4> ToUnknownMatrix(
 189     const Maybe<gfx::Matrix4x4Typed<SourceUnits, TargetUnits>>& aMatrix) {
 190   if (aMatrix.isSome()) {
 191     return Some(aMatrix->ToUnknownMatrix());
 192   }
 193   return Nothing();
 194 }
 195
 196 // Convenience functions for casting untyped entities to typed entities.
 197 // Using these functions does not require a justification, but once we convert
 198 // all code to use strongly typed units they should not be needed any longer.
 199 template <class TargetUnits>
 200 gfx::PointTyped<TargetUnits> ViewAs(const gfxPoint& aPoint) {
 201   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 202 }
 203 template <class TargetUnits>
 204 gfx::PointTyped<TargetUnits> ViewAs(const gfx::Point& aPoint) {
 205   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 206 }
 207 template <class TargetUnits>
 208 gfx::RectTyped<TargetUnits> ViewAs(const gfx::Rect& aRect) {
 209   return gfx::RectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 210                                      aRect.Height());
 211 }
 212 template <class TargetUnits>
 213 gfx::IntSizeTyped<TargetUnits> ViewAs(const nsIntSize& aSize) {
 214   return gfx::IntSizeTyped<TargetUnits>(aSize.width, aSize.height);
 215 }
 216 template <class TargetUnits>
 217 gfx::IntPointTyped<TargetUnits> ViewAs(const nsIntPoint& aPoint) {
 218   return gfx::IntPointTyped<TargetUnits>(aPoint.x, aPoint.y);
 219 }
 220 template <class TargetUnits>
 221 gfx::IntRectTyped<TargetUnits> ViewAs(const nsIntRect& aRect) {
 222   return gfx::IntRectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 223                                         aRect.Height());
 224 }
 225 template <class TargetUnits>
 226 gfx::IntRegionTyped<TargetUnits> ViewAs(const nsIntRegion& aRegion) {
 227   return gfx::IntRegionTyped<TargetUnits>::FromUnknownRegion(aRegion);
 228 }
 229 // Unlike the other functions in this category, these functions take the
 230 // target matrix or scale type, rather than its source and target unit
 231 // types, as the template argument, so an example invocation is:
 232 //    ViewAs<ScreenToLayerMatrix4x4>(untypedMatrix)
 233 // The reason is that if it took the source and target unit types as two
 234 // template arguments, there may be some confusion as to which is the
 235 // source and which is the target.
 236 template <class TypedScale>
 237 TypedScale ViewAs(const Scale2D& aScale) {
 238   return TypedScale(aScale.xScale, aScale.yScale);
 239 }
 240 template <class TypedMatrix>
 241 TypedMatrix ViewAs(const gfx::Matrix4x4& aMatrix) {
 242   return TypedMatrix::FromUnknownMatrix(aMatrix);
 243 }
 244
 245 // Convenience functions for transforming an entity from one strongly-typed
 246 // coordinate system to another using the provided transformation matrix.
 247 template <typename TargetUnits, typename SourceUnits>
 248 static gfx::PointTyped<TargetUnits> TransformBy(
 249     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 250     const gfx::PointTyped<SourceUnits>& aPoint) {
 251   return aTransform.TransformPoint(aPoint);
 252 }
 253 template <typename TargetUnits, typename SourceUnits>
 254 static gfx::IntPointTyped<TargetUnits> TransformBy(
 255     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 256     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 257   return RoundedToInt(
 258       TransformBy(aTransform, gfx::PointTyped<SourceUnits>(aPoint)));
 259 }
 260 template <typename TargetUnits, typename SourceUnits>
 261 static gfx::RectTyped<TargetUnits> TransformBy(
 262     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 263     const gfx::RectTyped<SourceUnits>& aRect) {
 264   return aTransform.TransformBounds(aRect);
 265 }
 266 template <typename TargetUnits, typename SourceUnits>
 267 static gfx::IntRectTyped<TargetUnits> TransformBy(
 268     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 269     const gfx::IntRectTyped<SourceUnits>& aRect) {
 270   return RoundedToInt(
 271       TransformBy(aTransform, gfx::RectTyped<SourceUnits>(aRect)));
 272 }
 273 template <typename TargetUnits, typename SourceUnits>
 274 static gfx::IntRegionTyped<TargetUnits> TransformBy(
 275     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 276     const gfx::IntRegionTyped<SourceUnits>& aRegion) {
 277   return ViewAs<TargetUnits>(
 278       aRegion.ToUnknownRegion().Transform(aTransform.ToUnknownMatrix()));
 279 }
 280
 281 // Transform |aVector|, which is anchored at |aAnchor|, by the given transform
 282 // matrix, yielding a point in |TargetUnits|.
 283 // The anchor is necessary because with 3D tranforms, the location of the
 284 // vector can affect the result of the transform.
 285 template <typename TargetUnits, typename SourceUnits>
 286 static gfx::PointTyped<TargetUnits> TransformVector(
 287     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 288     const gfx::PointTyped<SourceUnits>& aVector,
 289     const gfx::PointTyped<SourceUnits>& aAnchor) {
 290   gfx::PointTyped<TargetUnits> transformedStart =
 291       TransformBy(aTransform, aAnchor);
 292   gfx::PointTyped<TargetUnits> transformedEnd =
 293       TransformBy(aTransform, aAnchor + aVector);
 294   return transformedEnd - transformedStart;
 295 }
 296
 297 // UntransformBy() and UntransformVector() are like TransformBy() and
 298 // TransformVector(), respectively, but are intended for cases where
 299 // the transformation matrix is the inverse of a 3D projection. When
 300 // using such transforms, the resulting Point4D is only meaningful
 301 // if it has a positive w-coordinate. To handle this, these functions
 302 // return a Maybe object which contains a value if and only if the
 303 // result is meaningful
 304 template <typename TargetUnits, typename SourceUnits>
 305 static Maybe<gfx::PointTyped<TargetUnits>> UntransformBy(
 306     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 307     const gfx::PointTyped<SourceUnits>& aPoint) {
 308   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(aPoint);
 309   if (!point.HasPositiveWCoord()) {
 310     return Nothing();
 311   }
 312   return Some(point.As2DPoint());
 313 }
 314 template <typename TargetUnits, typename SourceUnits>
 315 static Maybe<gfx::IntPointTyped<TargetUnits>> UntransformBy(
 316     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 317     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 318   gfx::PointTyped<SourceUnits> p = aPoint;
 319   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(p);
 320   if (!point.HasPositiveWCoord()) {
 321     return Nothing();
 322   }
 323   return Some(RoundedToInt(point.As2DPoint()));
 324 }
 325
 326 // The versions of UntransformBy() that take a rectangle also take a clip,
 327 // which represents the bounds within which the target must fall. The
 328 // result of the transform is intersected with this clip, and is considered
 329 // meaningful if the intersection is not empty.
 330 template <typename TargetUnits, typename SourceUnits>
 331 static Maybe<gfx::RectTyped<TargetUnits>> UntransformBy(
 332     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 333     const gfx::RectTyped<SourceUnits>& aRect,
 334     const gfx::RectTyped<TargetUnits>& aClip) {
 335   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 336   if (rect.IsEmpty()) {
 337     return Nothing();
 338   }
 339   return Some(rect);
 340 }
 341 template <typename TargetUnits, typename SourceUnits>
 342 static Maybe<gfx::IntRectTyped<TargetUnits>> UntransformBy(
 343     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 344     const gfx::IntRectTyped<SourceUnits>& aRect,
 345     const gfx::IntRectTyped<TargetUnits>& aClip) {
 346   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 347   if (rect.IsEmpty()) {
 348     return Nothing();
 349   }
 350   return Some(RoundedToInt(rect));
 351 }
 352
 353 template <typename TargetUnits, typename SourceUnits>
 354 static Maybe<gfx::PointTyped<TargetUnits>> UntransformVector(
 355     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 356     const gfx::PointTyped<SourceUnits>& aVector,
 357     const gfx::PointTyped<SourceUnits>& aAnchor) {
 358   gfx::Point4DTyped<TargetUnits> projectedAnchor =
 359       aTransform.ProjectPoint(aAnchor);
 360   gfx::Point4DTyped<TargetUnits> projectedTarget =
 361       aTransform.ProjectPoint(aAnchor + aVector);
 362   if (!projectedAnchor.HasPositiveWCoord() ||
 363       !projectedTarget.HasPositiveWCoord()) {
 364     return Nothing();
 365   }
 366   return Some(projectedTarget.As2DPoint() - projectedAnchor.As2DPoint());
 367 }
 368
 369 }  // namespace mozilla
 370
 371 #endif