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 TargetMatrix::FromUnknownMatrix(aMatrix.ToUnknownMatrix());
 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(TargetMatrix::FromUnknownMatrix(aMatrix->ToUnknownMatrix()));
 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::PointTyped<TargetUnits> ViewAs(const gfxPoint& aPoint) {
 214   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 215 }
 216 template <class TargetUnits>
 217 gfx::PointTyped<TargetUnits> ViewAs(const gfx::Point& aPoint) {
 218   return gfx::PointTyped<TargetUnits>(aPoint.x, aPoint.y);
 219 }
 220 template <class TargetUnits>
 221 gfx::RectTyped<TargetUnits> ViewAs(const gfx::Rect& aRect) {
 222   return gfx::RectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 223                                      aRect.Height());
 224 }
 225 template <class TargetUnits>
 226 gfx::IntSizeTyped<TargetUnits> ViewAs(const nsIntSize& aSize) {
 227   return gfx::IntSizeTyped<TargetUnits>(aSize.width, aSize.height);
 228 }
 229 template <class TargetUnits>
 230 gfx::IntPointTyped<TargetUnits> ViewAs(const nsIntPoint& aPoint) {
 231   return gfx::IntPointTyped<TargetUnits>(aPoint.x, aPoint.y);
 232 }
 233 template <class TargetUnits>
 234 gfx::IntRectTyped<TargetUnits> ViewAs(const nsIntRect& aRect) {
 235   return gfx::IntRectTyped<TargetUnits>(aRect.x, aRect.y, aRect.Width(),
 236                                         aRect.Height());
 237 }
 238 template <class TargetUnits>
 239 gfx::IntRegionTyped<TargetUnits> ViewAs(const nsIntRegion& aRegion) {
 240   return gfx::IntRegionTyped<TargetUnits>::FromUnknownRegion(aRegion);
 241 }
 242 // Unlike the other functions in this category, these functions take the
 243 // target matrix or scale type, rather than its source and target unit
 244 // types, as the template argument, so an example invocation is:
 245 //    ViewAs<ScreenToLayerMatrix4x4>(untypedMatrix)
 246 // The reason is that if it took the source and target unit types as two
 247 // template arguments, there may be some confusion as to which is the
 248 // source and which is the target.
 249 template <class TypedScale>
 250 TypedScale ViewAs(const Scale2D& aScale) {
 251   return TypedScale(aScale.xScale, aScale.yScale);
 252 }
 253 template <class TypedMatrix>
 254 TypedMatrix ViewAs(const gfx::Matrix4x4& aMatrix) {
 255   return TypedMatrix::FromUnknownMatrix(aMatrix);
 256 }
 257
 258 // Convenience functions for transforming an entity from one strongly-typed
 259 // coordinate system to another using the provided transformation matrix.
 260 template <typename TargetUnits, typename SourceUnits>
 261 static gfx::PointTyped<TargetUnits> TransformBy(
 262     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 263     const gfx::PointTyped<SourceUnits>& aPoint) {
 264   return aTransform.TransformPoint(aPoint);
 265 }
 266 template <typename TargetUnits, typename SourceUnits>
 267 static gfx::IntPointTyped<TargetUnits> TransformBy(
 268     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 269     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 270   return RoundedToInt(
 271       TransformBy(aTransform, gfx::PointTyped<SourceUnits>(aPoint)));
 272 }
 273 template <typename TargetUnits, typename SourceUnits>
 274 static gfx::RectTyped<TargetUnits> TransformBy(
 275     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 276     const gfx::RectTyped<SourceUnits>& aRect) {
 277   return aTransform.TransformBounds(aRect);
 278 }
 279 template <typename TargetUnits, typename SourceUnits>
 280 static gfx::IntRectTyped<TargetUnits> TransformBy(
 281     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 282     const gfx::IntRectTyped<SourceUnits>& aRect) {
 283   return RoundedToInt(
 284       TransformBy(aTransform, gfx::RectTyped<SourceUnits>(aRect)));
 285 }
 286 template <typename TargetUnits, typename SourceUnits>
 287 static gfx::IntRegionTyped<TargetUnits> TransformBy(
 288     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 289     const gfx::IntRegionTyped<SourceUnits>& aRegion) {
 290   return ViewAs<TargetUnits>(
 291       aRegion.ToUnknownRegion().Transform(aTransform.ToUnknownMatrix()));
 292 }
 293
 294 // Transform |aVector|, which is anchored at |aAnchor|, by the given transform
 295 // matrix, yielding a point in |TargetUnits|.
 296 // The anchor is necessary because with 3D tranforms, the location of the
 297 // vector can affect the result of the transform.
 298 template <typename TargetUnits, typename SourceUnits>
 299 static gfx::PointTyped<TargetUnits> TransformVector(
 300     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 301     const gfx::PointTyped<SourceUnits>& aVector,
 302     const gfx::PointTyped<SourceUnits>& aAnchor) {
 303   gfx::PointTyped<TargetUnits> transformedStart =
 304       TransformBy(aTransform, aAnchor);
 305   gfx::PointTyped<TargetUnits> transformedEnd =
 306       TransformBy(aTransform, aAnchor + aVector);
 307   return transformedEnd - transformedStart;
 308 }
 309
 310 // UntransformBy() and UntransformVector() are like TransformBy() and
 311 // TransformVector(), respectively, but are intended for cases where
 312 // the transformation matrix is the inverse of a 3D projection. When
 313 // using such transforms, the resulting Point4D is only meaningful
 314 // if it has a positive w-coordinate. To handle this, these functions
 315 // return a Maybe object which contains a value if and only if the
 316 // result is meaningful
 317 template <typename TargetUnits, typename SourceUnits>
 318 static Maybe<gfx::PointTyped<TargetUnits>> UntransformBy(
 319     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 320     const gfx::PointTyped<SourceUnits>& aPoint) {
 321   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(aPoint);
 322   if (!point.HasPositiveWCoord()) {
 323     return Nothing();
 324   }
 325   return Some(point.As2DPoint());
 326 }
 327 template <typename TargetUnits, typename SourceUnits>
 328 static Maybe<gfx::IntPointTyped<TargetUnits>> UntransformBy(
 329     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 330     const gfx::IntPointTyped<SourceUnits>& aPoint) {
 331   gfx::PointTyped<SourceUnits> p = aPoint;
 332   gfx::Point4DTyped<TargetUnits> point = aTransform.ProjectPoint(p);
 333   if (!point.HasPositiveWCoord()) {
 334     return Nothing();
 335   }
 336   return Some(RoundedToInt(point.As2DPoint()));
 337 }
 338
 339 // The versions of UntransformBy() that take a rectangle also take a clip,
 340 // which represents the bounds within which the target must fall. The
 341 // result of the transform is intersected with this clip, and is considered
 342 // meaningful if the intersection is not empty.
 343 template <typename TargetUnits, typename SourceUnits>
 344 static Maybe<gfx::RectTyped<TargetUnits>> UntransformBy(
 345     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 346     const gfx::RectTyped<SourceUnits>& aRect,
 347     const gfx::RectTyped<TargetUnits>& aClip) {
 348   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 349   if (rect.IsEmpty()) {
 350     return Nothing();
 351   }
 352   return Some(rect);
 353 }
 354 template <typename TargetUnits, typename SourceUnits>
 355 static Maybe<gfx::IntRectTyped<TargetUnits>> UntransformBy(
 356     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 357     const gfx::IntRectTyped<SourceUnits>& aRect,
 358     const gfx::IntRectTyped<TargetUnits>& aClip) {
 359   gfx::RectTyped<TargetUnits> rect = aTransform.ProjectRectBounds(aRect, aClip);
 360   if (rect.IsEmpty()) {
 361     return Nothing();
 362   }
 363   return Some(RoundedToInt(rect));
 364 }
 365
 366 template <typename TargetUnits, typename SourceUnits>
 367 static Maybe<gfx::PointTyped<TargetUnits>> UntransformVector(
 368     const gfx::Matrix4x4Typed<SourceUnits, TargetUnits>& aTransform,
 369     const gfx::PointTyped<SourceUnits>& aVector,
 370     const gfx::PointTyped<SourceUnits>& aAnchor) {
 371   gfx::Point4DTyped<TargetUnits> projectedAnchor =
 372       aTransform.ProjectPoint(aAnchor);
 373   gfx::Point4DTyped<TargetUnits> projectedTarget =
 374       aTransform.ProjectPoint(aAnchor + aVector);
 375   if (!projectedAnchor.HasPositiveWCoord() ||
 376       !projectedTarget.HasPositiveWCoord()) {
 377     return Nothing();
 378   }
 379   return Some(projectedTarget.As2DPoint() - projectedAnchor.As2DPoint());
 380 }
 381
 382 }  // namespace mozilla
 383
 384 #endif